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. Include the Linear identifier in the branch name (e.g. docs/man-132-…). When the SDLC gate below is green, commit and open the PR without asking. Watch CI until green, then merge. Clean up the worktree with git worktree remove after merge.

Agent SDLC (do not ask)

Never ask whether to commit or open a PR. After each complete slice of work, ship it:

1. Work is done in a Linear-linked worktree.
2. Tests are written or updated for the changed layer. Skip new tests only when the change has no runtime impact (docs, templates, static config).
3. Pre-commit passes (composer pint:check and composer phpstan). Do not --no-verify. If the hook fails, fix and rerun.
4. Commit with Conventional Commits. Cite the Linear identifier.
5. Push and open the Gitea PR (tea pulls create) using .gitea/PULL_REQUEST_TEMPLATE.md (WHAT / WHY / HOW / Linear Issue / Comments). Attach the PR URL on the Linear issue via save_issue links. GitHub is the legacy mirror only.

Do not wait for "pode commitar?" or "abre o PR?".

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. Fill the PR template (WHAT / WHY / HOW / Linear Issue / Comments). Linear Issue is required (identifier + URL). An OpenSpec change is extra context, not a substitute. Include verification commands and screenshots for UI changes. Ensure all CI jobs pass. After pre-commit is green, commit and open the PR — do not ask.

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.

Every piece of work and every PR must be tied to a Linear issue. Do not create a branch, worktree, or PR until an issue exists (identifier like MAN-132). If the user did not give one, search Linear first; if none fits, create it with save_issue on team Maneco-workspace before starting. Put the identifier in the branch name. Cite identifier + URL in the PR body. After opening the PR, attach the PR URL on the issue via save_issue links. Do not start untracked work.

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.