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 postgres starts the local PostgreSQL service. docker compose up -d (no service name) also builds and starts the app service — a local FrankenPHP container for parity with staging/production, see README.md.
• 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, PHP + npm dependency audits, and every test suite.
• composer test:unit, composer test:feature, or composer test:browser run focused suites.
• composer test:coverage runs the Domain/Application coverage gate (80% minimum, scoped via phpunit.coverage.xml) used by CI's unit job. Requires a coverage driver (pcov or xdebug); fails with "No code coverage driver available" without one — that's an environment gap, not a broken repo.

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

Design Principles: DRY & YAGNI

Write for the problem at hand, not an imagined future. DRY: extract and reuse a piece of logic as soon as it is genuinely duplicated in more than one place — but not before. YAGNI: do not add abstraction, configurability, or layers speculatively; add them only when a concrete requirement demands it. Prefer the simplest thing that solves the current requirement. Duplication that appears once is not yet a reason to abstract — wait for a second real occurrence before generalizing. This repo already encodes YAGNI in openspec/config.yaml (no generic repositories / BaseService); keep that spirit in new code. Avoid over-engineering and avoid premature extraction.

Testing Guidelines

Tests use Pest 4; browser coverage uses Pest Browser/Playwright. Tests are verification, not a design driver — write them to cover behavior you've already implemented, matching the layer you changed. 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; add regression tests where a bug was fixed or behavior is non-obvious, without making tests a front-loaded design ceremony.

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.

Design Context

Amare: refined, humane, precise — Heritage Editorial. Trust-first, both private + corporate audiences. Never generic wedding decor (hearts/gold/script) or AI-slop. Real proof only.

The design system lives in DESIGN.md (palette, typography, layout, do's and don'ts) and positioning in PRODUCT.md; tokens are implemented in resources/css/tokens.css and asserted by tests/Feature/PublicSite/HeritageEditorialTokensTest.php. Per-surface briefs live in .impeccable/surfaces/. The Impeccable skill itself is vendored at .github/skills/impeccable/SKILL.md — its setup step reads PRODUCT.md, DESIGN.md, and the matching surface brief.

Agent skills

Issue tracker

Issues live in Linear, driven through the Linear MCP tools. See docs/agents/issue-tracker.md for workspace, team, and tool conventions. The repo ships no .mcp.json, so the Linear MCP has to be enabled for the session before those tools exist — if it isn't, report that instead of silently falling back to another tracker.

Triage labels

Default vocabulary: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. See docs/agents/triage-labels.md.

Domain docs

Single-context repo. There is no CONTEXT.md — the domain is documented in SPEC.md (§8 is the domain model and database schema) and PRODUCT.md, with current capabilities described per-capability under openspec/specs/. docs/adr/README.md is an index only: ADR-001 through ADR-010 are decided in SPEC.md §21, and there are no standalone ADR files. docs/agents/domain.md describes the generic CONTEXT.md/CONTEXT-MAP.md layout that the engineering skills look for and instructs them to proceed silently when it's absent, which is the case here.