AGENTS.md template for Laravel

# Project instructions

This repository is a Laravel application. Preserve its routing, service-container, request-validation, authorization, Eloquent, event, queue, and testing conventions. Treat database and HTTP behavior as public contracts.

## Start here

- Read the target route, controller, request, policy, model, service, resource, job, and tests before editing.
- Use the PHP and Node versions plus package managers already configured in the repository.
- Reuse existing actions, services, components, traits, and query scopes before introducing new layers.
- Preserve local changes and never expose values from `.env` or deployed configuration.

## Commands

- `composer install`: install locked PHP dependencies.
- `php artisan serve`: start the local application server.
- `php artisan test`: run the Pest or PHPUnit test suite through Artisan.
- `vendor/bin/pint --test`: verify PHP formatting when Laravel Pint is configured.
- `npm run build`: build frontend assets when the application has a JavaScript bundle.

Replace these commands when the repository uses Sail, Herd, Docker, a different formatter, or project-specific scripts.

## Repository map

- `routes/`: HTTP, console, and channel entry points.
- `app/Http/`: controllers, middleware, requests, and API resources.
- `app/Models/`: Eloquent models, relationships, casts, and query scopes.
- `app/Policies/`: object-level authorization.
- `app/Jobs/`, `app/Events/`, and `app/Listeners/`: asynchronous and event-driven work.
- `database/migrations/` and `database/factories/`: schema history and test data.
- `tests/Feature/` and `tests/Unit/`: application and isolated coverage.

## Laravel rules

- Validate client input with the established Form Request or validator pattern.
- Authorize every protected action through policies, gates, middleware, or the repository's existing boundary.
- Guard mass assignment and expose response fields through established resources or transformers.
- Avoid N+1 queries; eager-load relationships only where the response or workflow uses them.
- Keep controllers focused on transport and orchestration when domain behavior already has an owner.
- Make queued jobs idempotent where retries are possible and never serialize secrets or unnecessary model state.

## Database and security

- Do not create, edit, or apply migrations unless the task explicitly includes a schema change.
- Review indexes, foreign keys, defaults, data backfills, locks, and rollback behavior before accepting a migration.
- Never run destructive Artisan commands or migrations against shared environments.
- Do not log credentials, tokens, session data, private request fields, or raw exception details.

## Testing and validation

- Prefer feature tests for HTTP, authorization, database, event, and queue behavior; use unit tests for isolated logic.
- Cover success, validation failure, unauthenticated, unauthorized, and not-found branches.
- Use factories and framework fakes consistently; do not contact live services from the test suite.
- Run the focused test first, then the full suite, formatting check, and frontend build when affected.

## Definition of done

- The changed flow works through its route, command, event, or job boundary.
- Tests and configured formatting checks pass; frontend assets build when changed.
- Authorization, Eloquent query behavior, queues, and migration safety were reviewed.
- No secrets, unrelated migrations, lockfiles, or user changes were modified accidentally.
- The handoff states the behavior changed, checks run, and any deployment or data risk.