# Laravel 11 12 App Guidelines

> Coordinator-routed implementation guidance for confirmed Laravel 11 or 12 repositories when framework conventions materially own the work. Use after project-development-mindset inspects laravel/framework, or directly when explicitly invoked or installed standalone. Never load both Laravel version skills; Laravel 12-to-13 upgrades use the Laravel 13 skill. Do not use merely for supporting Sail, Docker, test, or frontend commands.

- Skill: `gabrielmoreira/laravel-11-12-app-guidelines` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/laravel-11-12-app-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/laravel-11-12-app-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/laravel-11-12-app-guidelines

---


# 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.

This skill owns version-specific Laravel implementation guidance, not the whole
task lifecycle. Keep routine testing, documentation, Docker command execution,
and UI reuse as supporting work. Return routing control to
`project-development-mindset` if debugging, test strategy, local container
topology, UI concept work, or deployment becomes the primary concern.

Run this skill in the main conversation. Do not spawn subagents, agent teams, or
delegated parallel workers unless the user explicitly approves the proposed
count and scope after being told that doing so can increase usage. Ask again
before expanding an approved scope.

## Quick Start

- Read repository instructions first: `AGENTS.md`. If `docs/` exists, read `docs/README.md` and relevant module docs before decisions.
- Detect installed versions, the stack, and command locations; do not guess.
- Use Laravel Boost `search-docs` for version-matched ecosystem guidance; use official versioned Laravel or package documentation if Boost is unavailable.
- Follow repo conventions for naming, UI language, docs-first policies, and existing component patterns.

## Stack Detection

- Check `composer.json`, `composer.lock`, `package.json`, frontend lockfiles,
  `bootstrap/app.php`, `docker-compose.*`, and `config/*` to confirm:
  - Docker Compose/Sail vs host commands
  - API-only vs full-stack
  - Frontend framework (Inertia with React, Vue, or Svelte; Livewire; Blade)
  - Auth (Fortify, Sanctum, Passport, custom)

## Laravel 11/12 Core Conventions

- When the application uses the modern Laravel 11/12 skeleton, configure
  middleware, exceptions, and routes in `bootstrap/app.php`; register service
  providers in `bootstrap/providers.php`; define closure commands and schedules
  in `routes/console.php`. Preserve a supported upgraded structure unless the
  task requires reorganizing it.
- Prefer Eloquent models and relationships for domain-oriented work. Use the
  query builder or bound raw expressions when bulk or complex queries are
  clearer; never interpolate untrusted SQL.
- Use Form Request classes for reusable or non-trivial validation and
  authorization. Inline validation is acceptable for a small one-off flow when
  it matches repository conventions.
- Prefer named routes and `route()` for URL generation.
- When modifying an existing column with `change()`, restate every modifier that
  must be retained because omitted modifiers are dropped.
- Ask before destructive database operations (e.g., reset/rollback/fresh).

## API-Only Mode

- Use `routes/api.php` when it exists. Fresh Laravel 11/12 applications may omit
  it; run `install:api` only when adding an API and Sanctum is intended.
- 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 + Wayfinder (if present)

- Use `Inertia::render()` for server-side responses and discover page paths from
  the application's page resolver; do not assume a directory or casing.
- Use form APIs supported by the installed Inertia version; add loading, empty,
  validation, and error states where relevant.
- Use `<Link>` or `router.visit()` for navigation.
- Use Wayfinder named imports for tree-shaking; avoid default imports; regenerate routes after changes if required.

## Livewire / 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

- Preserve the repository's Pest or PHPUnit test runner. Confirm generator flags
  with `php artisan help make:test`; generally prefer feature tests for behavior
  that crosses framework boundaries.
- Run the smallest relevant test target (`php artisan test <file>` or
  `--filter=`). After implementation and focused verification are complete,
  identify the broader affected or full suite and ask the user whether to run it.
  Do not run it without explicit approval unless higher-priority repository
  instructions require it.
- Run `vendor/bin/pint --dirty` before finalizing code changes.

## Laravel Boost MCP Tools (when available)

- Read application information, then use `search-docs` before changing framework
  behavior or using version-sensitive features.
- Discover the tools exposed by the installed Boost server; tool names and
  capabilities can vary by release.
- Use available route, Artisan, schema, log, browser, and URL tools for
  inspection. Keep database queries read-only and executable-code tools scoped
  to local or test environments unless explicitly authorized.
- 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.