Project Conventions

The planner initializes this file from the .agents/templates/AGENTS.md template when absent. Update it when durable conventions, decisions, or workflow rules change.

• Keep durable project conventions here.
• Store mutable workflow artifacts in .agents/artifacts/.
• The orchestrator owns state.md; planner initializes project memory; quality generates and owns local-test.md from repository evidence. At feature completion, the orchestrator logs the feature in state.md with: feature name, key decisions, known issues, dependencies, and QA outcome. When starting a new feature, the orchestrator reads the last 2-3 completed features from the log for context continuity.
• Default to prototype-first: approve the smallest first-feature plan, then implement and test it without routine confirmation. Record the selected delivery mode and confirmed material decisions in project memory. Guided/checkpointed and autonomous delivery require an explicit request.
• Hard gates — never skip: (1) Developer always hands off to quality. After developer finishes, the orchestrator must invoke quality before declaring work done. (2) Quality must produce qa-report.md and review.md. The orchestrator must confirm these files exist before telling the user the work is complete. (3) Never declare work done without quality artifacts. (4) Never infer quality from the developer's output — developer saying "all tests pass" is not a quality review. (5) Never silently skip a workflow step.
• Diagnose before fixing: when something is reported broken, first establish where the problem actually is (code, config, environment, infrastructure, user error) before routing any code changes. Never modify code to fix a problem that has not been diagnosed. A system that is not broken can be broken by unnecessary fixes.
• Three-tier routing: Tier 1 (clearly bounded, diagnosis confirms code issue) routes developer then quality. Tier 2 (probably small, scope unclear) routes planner for 1-2 questions then developer. Tier 3 (clearly complex) routes full planner workflow. Default to tier 2 when unsure.
• Risk-triggered evidence only: Trigger security review only for authentication, authorization, sessions, secrets/credentials, payments, sensitive personal data, security controls, or an untrusted-input/external-data boundary. Trigger accessibility review only for a user-facing interface, navigation, form, or interactive control. Trigger performance review only for a hot path, database query pattern, N+1 query risk, response-time budget, large data set processing, memory allocation, bundle size, or caching behavior. For each trigger, developer records the trigger, change-specific checks, results, and remaining risk; quality verifies and records it. Security checks cover the relevant boundary, access control, data exposure, and safe handling; accessibility checks cover keyboard path, semantic/accessible name, focus behavior, and visual readability; performance checks cover the affected path, measured or estimated cost, and whether the change stays within the existing budget. Missing triggered evidence or an unresolved issue blocks QA/review; non-triggered changes need no such evidence. This is not a scanner, formal compliance assessment, or a reliability or architecture review.
• Skill routing is automatic: the orchestrator scans available skills on every handoff and tells the subagent which to load. The user should never need to request a skill explicitly. Route UI work to frontend-design (or ui-ux), test work to unit-testing/feature-testing/e2e-testing, review to quality-review, unclear scope to requirements-gathering, architecture to solution-design, tickets to task-breakdown, Git to branch-safely, deploy to deploy (plus deploy-vercel/deploy-vps/deployment-decisions as needed), docs to documentation, production to monitoring. Do not skip routing for small changes.
• Every implementation must include tests at all three applicable levels: unit tests for isolated logic, feature tests against acceptance criteria, and end-to-end tests simulating real user flows. For a bug fix, developer writes regression tests at all three applicable levels before the fix. Quality performs three sequential phases: run tests, inspect the diff (correctness/security/scope), then classify findings as blocking or advisory. The planner includes a test strategy in plan.md specifying which levels apply and what each covers.
• Ask for approval only for the first-feature plan, material scope or goal changes, security/cost/privacy/credential decisions, destructive or remote actions, deployment, or an explicit user-requested checkpoint.
• After each completed user-facing feature, give the simplest actual local test path organized by test level and ask whether the user wants to test, fix, adjust, or start the next feature. Do not automatically build the next major feature unless autonomous delivery was explicitly selected.
• Commit requirements.md, plan.md, backlog.md, project-memory.md, local-test.md, and this AGENTS.md.
• Do not commit transient state.md or failure-log.md.
• Deployment requires an explicit human request and passing quality gates. The deploy skill is the entry point — it checks for an existing project deployment process (.agents/skills/deploy-project/SKILL.md) and loads the right sub-skill (deploy-vercel, deploy-vps, or deployment-decisions). Agents never handle credentials directly; prefer gh CLI or guide the user to add secrets in their service dashboard. After setup, save the deployment process as a project skill for future use.
• Before implementation, inspect Git status and branch in an existing repository; never work on main or master, and preserve unrelated work.
• Git is required. Before any code work, check whether the project is a Git repository. If not, run git init -b main automatically. Do not ask. Do not set global Git identity. Do not create a commit automatically — commits require an explicit human request. Check local Git identity before a requested baseline commit and ask the human to configure it if absent. A newly initialized repository may remain on main until that first baseline commit; after that, use task feature branches.
• Developer and quality may inspect project files, use normal non-force branch commands, stage changes, run known local build, test, and dev commands, and list Docker containers or images without repeated approval. Package installation, publishing, destructive, remote, and secret-related commands ask first. Ask before commits, remote Git operations, sensitive Docker commands, external-system actions not explicitly requested, and deployment.
• Ask before reading, searching, or scanning .env, .env.*, .secrets, *.secrets, *.pem, *.key, credential-named paths, secrets/, .ssh/, .aws/, or similar credential locations. Never print, copy, log, or report secrets.