Skip to main content

​
Branching

  • New work starts from current origin/main in a clean task branch/worktree.
  • Continue an existing branch only when the task explicitly names that work.
  • Never reset, stash, overwrite, or mix unrelated work.
  • Default to one branch and PR for one complete outcome. Split only at independently useful, safe, testable, deployable, and rollbackable boundaries.

​
PR contract

Copy /.agents/plan-template.md into the PR body and keep these sections current:
  • outcome;
  • low, standard, high, or critical risk;
  • scope and file allowlist;
  • concrete acceptance checklist;
  • executable tests;
  • actual visual proof for frontend paths; and
  • realistic risk and rollback.
Before a PR exists, an ignored local copy may live at .agents/plans/<branch>.md. The PR body is public metadata: never include secrets, credentials, or private client facts.

​
CI and review

Every PR runs:
  • Lint, Typecheck & Test;
  • Database Sync;
  • database-independent Build;
  • Docs Validation;
  • PR Policy;
  • PR Metadata Policy;
  • Secret Scan; and
  • Client Data Scan.
PR Policy checks the contract, declared files, critical handling of protected paths, acceptance completion, domain tests, frontend proof, environment files, and forbidden executable patterns. It does not enforce arbitrary line or file limits. Head, PR-body, label, draft-state, and merge-group changes refresh the distinct trusted metadata policy status without rerunning expensive code checks. Invalid metadata removes the PR from the queue. The legacy snapshot gate remains required during staged activation and is removed only after the replacement is proven. The independent reviewer reads the complete current diff and requests changes only for objective blockers. Native GitHub rules dismiss stale approvals, require the latest push to be approved, require conversations and status checks to pass, and send the result through the merge queue.

​
Frontend proof

Run the application and capture the actual changed behavior. Keep captures under ignored .artifacts/, upload with node scripts/upload-build-artifacts.mjs, and paste the link into the PR. Use a private artifact when the proof contains private data. Never commit generated screenshots or recordings.

​
Labels

  • halt-agents: stop work and review.
  • needs-replan: the bounded correction loop reached a genuine impasse.
  • auto-revert: a protected recovery PR.
  • force-merge: rare explicit human bypass with a public audit comment.
Labels do not waive secrets, tests, data safety, prisma db push, or --no-verify.