amare/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This is a Laravel 13 application for an event-planning consultancy. Application code lives in app/: domain rules belong in app/Domain, HTTP entry points in app/Http, and the internal Filament 5 panel in app/Filament. Blade views, JavaScript, and Tailwind CSS are under resources/; Vite publishes browser assets to public/. Database migrations, factories, and seeders live in database/. Tests are grouped into tests/Unit, tests/Architecture, tests/Feature, and tests/Browser. Treat SPEC.md as the product source of truth and use openspec/ for planned changes.

Build, Test, and Development Commands

• composer setup installs PHP and npm dependencies, creates .env, migrates, and builds assets.
• docker compose up -d starts the local PostgreSQL service.
• composer dev runs Laravel, the queue listener, logs, and Vite together.
• npm run build creates the production frontend bundle.
• composer quality runs formatting checks, PHPStan level 5, dependency audit, and every test suite.
• composer test:unit, composer test:feature, or composer test:browser run focused suites.

Feature and browser tests require the amare_test PostgreSQL database configured in phpunit.xml.

Worktrees

Always work in a git worktree created from the main ref — never modify main directly and never commit from the primary working tree. Create a dedicated worktree per feature/branch with git worktree add -b <branch> <path> main. On finishing work, create a PR, watch CI until green, then merge it. Clean up the worktree with git worktree remove after merge.

Git Hooks (husky)

Hooks live in .husky/ and auto-install on any plain npm install via the prepare script. Note composer setup runs npm install --ignore-scripts, which skips hook installation — after setup, run npm install once (or npx husky) to activate hooks.

• pre-commit: runs composer pint:check and composer phpstan.
• pre-push: gates on the amare_test database (settings parsed from phpunit.xml), blocks the push with a docker compose up -d hint when Postgres is unreachable, then runs composer test:unit and composer test:feature. Browser tests are CI-only (FrankenPHP container).

Coding Style & Naming Conventions

Follow PSR-4 and Laravel conventions: PascalCase classes, camelCase methods, and snake_case database columns. Use four spaces (two in YAML, except four in Compose files), LF endings, and UTF-8 as defined by .editorconfig. Every project-owned PHP file must place declare(strict_types=1); immediately after <?php. Keep domain code independent of Filament and Livewire. Run composer pint to format and composer phpstan before review.

Testing Guidelines

Tests use Pest 4; browser coverage uses Pest Browser/Playwright. Name files by behavior, ending in Test.php, and add tests in the suite matching the changed layer. Feature tests use RefreshDatabase. Add architecture coverage for dependency-boundary changes. No numeric coverage threshold is enforced, but changed behavior must have regression coverage.

Commit & Pull Request Guidelines

History follows Conventional Commit-style subjects, for example feat: Fase 0 — Fundação. Use <type>: <imperative summary> (feat, fix, docs, test, chore) and keep commits focused. Pull requests should explain scope, link the relevant issue or OpenSpec requirement, list verification commands, and include screenshots for UI changes. Ensure all CI jobs pass.

Security & Configuration

Copy .env.example; never commit secrets or production credentials. Development seed credentials are local-only. Validate uploads and authorization through Laravel policies, and run composer security-audit after dependency changes.