Laravel 11/12 App Guidelines

Overview

Apply a consistent workflow for Laravel 11/12 apps with optional frontend stacks, Dockerized commands, and Laravel Boost tooling.

Quick Start

• •Read repository instructions first: AGENTS.md. If docs/ exists, read docs/README.md and relevant module docs before decisions.
• •Detect the stack and command locations; do not guess.
• •Use Laravel Boost search-docs for Laravel ecosystem guidance; use Context7 only if Boost docs are unavailable.
• •Follow repo conventions for naming, UI language, docs-first policies, and existing component patterns.

Stack Detection

• •Check composer.json, package.json, docker-compose.*, and config/* to confirm:
  • •Docker Compose/Sail vs host commands
  • •API-only vs full-stack
  • •Frontend framework (Inertia/React, Livewire, Vue, Blade)
  • •Auth (Fortify, Sanctum, Passport, custom)

Laravel 11/12 Core Conventions

• •Use the Laravel 11/12 structure: configure middleware, exceptions, and routes in bootstrap/app.php; service providers in bootstrap/providers.php; console configuration in routes/console.php.
• •Use Eloquent models and relationships first; avoid raw queries and DB:: unless truly necessary.
• •Create Form Request classes for validation instead of inline validation.
• •Prefer named routes and route() for URL generation.
• •When altering columns, include all existing attributes in the migration to avoid dropping them.
• •Ask before destructive database operations (e.g., reset/rollback/fresh).

API-Only Mode

• •Use routes/api.php; avoid Inertia and frontend assumptions.
• •Prefer API Resources and versioning if the repo already uses them.
• •Follow the repo's auth stack (Sanctum/Passport/custom) and response format conventions.
• •Do not require Vite/Tailwind/NPM unless the repo already includes them.

Inertia + React + Wayfinder (if present)

• •Use Inertia::render() for server-side routing; place pages under resources/js/Pages unless the repo says otherwise.
• •Use <Form> or useForm for Inertia forms; add skeleton/empty states for deferred props.
• •Use <Link> or router.visit() for navigation.
• •Use Wayfinder named imports for tree-shaking; avoid default imports; regenerate routes after changes if required.

Livewire / Vue / Blade (if present)

• •Follow existing component patterns and conventions; do not mix frameworks unless the repo already does.
• •Keep UI strings in the repo's expected language.

Tailwind CSS v4 (if present)

• •Use @import "tailwindcss"; and @theme for tokens.
• •Avoid deprecated utilities; use replacements (e.g., shrink-*, grow-*, text-ellipsis).
• •Use gap-* for spacing between items; follow existing dark mode conventions if present.

Testing and Formatting

• •Use PHPUnit; generate tests with php artisan make:test --phpunit and prefer feature tests.
• •Run the minimal relevant tests (php artisan test <file> or --filter=).
• •Run vendor/bin/pint --dirty before finalizing code changes.
• •After minimal tests pass, offer to run the full test suite.

Laravel Boost MCP Tools (when available)

• •search-docs before changing behavior or using framework features.
• •list-artisan-commands to confirm Artisan options.
• •list-routes to inspect routing changes.
• •tinker for PHP debugging and database-query for read-only DB checks.
• •browser-logs to inspect frontend errors.
• •get-absolute-url for sharing project URLs.
• •See references/boost-tools.md for query patterns and tool usage tips.

Output Expectations

• •Preserve existing architecture, structure, and dependencies unless the user explicitly requests changes.
• •Reuse existing components and follow local patterns.
• •Ask concise clarifying questions when repo guidance is missing or ambiguous.