Setup Playbook

Installs the standing infrastructure the three loops depend on. Run once per repository. Idempotent: never overwrite an existing file — show a diff and merge instead.

Steps

1. Inspect the repo first. Detect: package manager, language, formatter/ linter, test runner, existing CI, existing CLAUDE.md/CONTEXT.md. Every template below gets adapted to what's found, not pasted blind.
2. CI gates — from templates/github/workflows/ci.yml:
   • format + lint check, typecheck, and dependency-free unit tests
   • fill in the repo's real commands; delete the placeholder comments
   • gates must be FAST (minutes) — anything slow runs elsewhere
   • Expect the format/lint gate to FAIL on the existing default branch if the repo has only ever had pre-commit hooks: staged-files-only hooks let unformatted content arrive via merges and web edits. Run the gates against the default branch first and clear the drift in the install PR itself, as its own commit — the gate must start green.
3. Agent review workflow — from templates/github/workflows/agent-review.yml:
   • reviews every PR from a fresh context; always posts a summary
   • tell the user to add the ANTHROPIC_API_KEY secret (repo settings) — the workflow is inert without it, and you cannot add secrets for them
   • keep the tool allowlist read-only: the reviewer comments, it never pushes
4. Git hooks — from templates/lefthook.yml (or the repo's existing hook manager): pre-commit format-fix + re-stage of staged files only.
5. CLAUDE.md — from templates/CLAUDE.md. Fill in: launch commands (ask the user or read compose files/scripts), test commands, and any framework guard blocks that apply. If one exists, merge sections rather than replacing.
6. CONTEXT.md — from templates/CONTEXT.md. Seed the glossary with terms already in the codebase (status enums, job names, user-facing nouns) — an empty glossary teaches nothing. Create the shared-resource registry and pre-fill current claims (existing migration numbers, ports, queue names).
7. ADR directory — docs/adr/ with the template and ADR-0001 (from templates/docs/adr/).
8. PRINCIPLES.md — from templates/PRINCIPLES.md. If the operator is a non-coding owner, fill it WITH them now (product principles, quality bar, ask-first list, risk posture) — it is the file that makes their judgment enforceable by agents and reviewers alike. If standing rules already live in-repo (a rules section in CLAUDE.md, a sacred-files list), do NOT create a duplicate: point the review workflow's prompt at the existing sections by name and record them as this repo's principles file. One source of truth beats the template.
9. Verify the installation: run the gates locally under the repo's pinned runtime — read .node-version / .tool-versions / equivalent and activate it explicitly (version managers often don't hook non-interactive shells, and a stale global runtime fails in ways that look like repo bugs). Then open a trivial PR if the user agrees, and confirm the review workflow fires.

Report

End with: what was installed, what was skipped (and why), what needs the user's hands (secrets, branch protection), and the one-line reminder of the per-feature loop: interrogate → spec → decompose → generate → verify-live → respond-to-review.