Laravel

Deterministic, test-driven workflows for Laravel applications.

Overview

Build, refactor, and debug Laravel applications using native Artisan inspection and established repository conventions. Delegate architectural scoping to superpower skills, write tests before implementation, and verify changes with automated test suites and Pint formatting.

Modes

Select an execution mode before Step 1:

• Feature mode (default). Follow test-driven development to build new routes, Eloquent models, and components.
• Diagnostic mode. Inspect logs, reproduce exceptions with minimal scripts, and resolve failures without adding architectural scaffolding.

Workflow

Follow these four steps in sequence:

Step 1. Environment and runtime probe

Probe framework version, configuration, and database state before modifying application files:

1. Check the Laravel version and PHP runtime:

   php artisan --version

2. Detect the laravel/boost MCP server in available tools:
   • When search-docs is present, query it for version-specific documentation and package contracts.
   • When search-docs is absent, inspect framework behavior with native Artisan commands in references/cli-introspection.md or read vendor source directly.
3. Inspect affected database tables and route definitions:

   php artisan model:show <ModelName>
   php artisan route:list --name=<routeName>

Completion criterion. Command output confirms Laravel version, runtime settings, affected database schemas, and route mappings.

Step 2. Convention mapping and reference selection

Audit sibling controllers, models, migrations, and test files for established project patterns. Match affected application layers to the reference index below:

Completion criterion. .agents/state/laravel/edit-plan.md exists on disk and lists every file to create or modify with its matching reference guide and section anchor.

Step 3. Implementation and boundary isolation

Apply minimal, isolated modifications using test-first development:

1. For new features or bug fixes, coordinate with the testing-patterns skill to establish failing tests before writing production code.
2. For error diagnosis, coordinate with the systematic-debugging skill to inspect storage/logs/laravel.log and verify reproducing steps first.
3. Confine database queries to Eloquent models, repositories, or query scopes, and leave Blade templates, Inertia controllers, and JsonResource classes free of direct queries.
4. Extract validation into Form Request classes and pass only $request->validated() into models.
5. Eager load relationships using with() or loadMissing() to eliminate N+1 queries.

Completion criterion. Implementation passes input validation, eagerly loads database relations, keeps business logic separated from HTTP controllers, and records targeted test failure command in .agents/state/laravel/red-test.txt.

Step 4. Verification pass

Run automated verification commands before finishing work:

1. Execute the narrowest relevant test suite:

   php artisan test --filter=<TestClassOrMethod>

2. Check code style with Laravel Pint when installed in the repository:

   vendor/bin/pint --test

   If vendor/bin/pint does not exist, record pint: absent in .agents/state/laravel/verification.txt and skip the style check.
3. Inspect the git diff of modified files. Confirm that input passes through validation, migrations declare explicit constraints, and queries load relationships eagerly.

Completion criterion. Targeted tests pass with exit code 0. If Pint is present, Pint reports zero style violations. If Pint is absent, .agents/state/laravel/verification.txt contains pint: absent and the test exit code.

Decision rules

• Audit sibling files before introducing patterns. Consistent project conventions take precedence over alternate architectures.
• Prefer native framework utilities over custom helper functions or external packages.
• Pass raw SQL through parameterized bindings with positional placeholders.
• Maintain CSRF protection, route middleware, and model authorization policies during tests. Fix test fixtures rather than disabling security middleware.
• Store credentials and private keys in .env and config/ files, and never hardcode secrets in application code.

Boundary isolation

Confine framework modifications strictly to application architecture and test assertions:

• Keep vendor packages, generated migration timestamps, Composer lock files, and core Laravel framework files untouched.
• Preserve database column names, environment variable keys, and CLI command signatures in their exact schema formats.

Quick audit checklist

Review this table before completing Laravel tasks: