git:20260929.6c69bd8 to git:20260930.462b272

1 added, 1 removed. Audit A to A.

# AGENTS.md: Project Router

> **This file is a table of contents, not an encyclopedia.**

> Keep it under ~150 lines. Point agents to references. Do not embed content here.

> If guidance needs to exist, put it in `docs/` and link from here.

## What this is

Team is a plugin that orchestrates specialized agents to implement features end-to-end across Claude Code, Codex CLI, and Antigravity CLI. The orchestrator (the main session) walks a linear phase table, and persists state as artifact files in `docs/plans/<id>/`. That per-id directory carries YAML frontmatter with phase and revision metadata. The orchestrator coordinates live progress through TodoWrite, and dispatches each specialist from its portable `agents/<name>.md` definition. See [docs/architecture.md](docs/architecture.md) for the full design.

> **North star: read [docs/vision.md](docs/vision.md) and [docs/ethos.md](docs/ethos.md).** Team is a *loop-driven development system*: a human fills the Backlog and reviews finished work. Everything in between (groom → start → implement → open PR) runs autonomously. The ethos explains *why* the autonomous middle can be trusted. Every agent should understand this end state, which is the target the whole project moves toward.

## Runtime vs. development

This project produces a **distributed plugin**. Two contexts exist:

**Runtime** (`agents/`, `skills/`, `opencode/`, and the host manifests `.claude-plugin/`, `.codex-plugin/`, `.agents/plugins/`, and the root `plugin.json`) ships to end users. Fires when someone installs the Team plugin and runs `/team`. Changes here affect all users.

**Development** (`.claude/`) is our workspace tooling. Fires only when developing the plugin itself. Never distributed.

| Concern | Where it lives | Who runs it |

|---------|---------------|-------------|

| Pipeline agents, skills, OpenCode adapter | `agents/`, `skills/`, `opencode/` | End users |

| Plugin manifests | `.claude-plugin/` (Claude Code), `.codex-plugin/` + `.agents/plugins/` (Codex), root `plugin.json` (Antigravity) | End users |

| Registry sync validation | `.claude/hooks/check-registry-sync.mjs` | Plugin developers |

| Pre-merge version gate | `.claude/hooks/pre-merge-guard.mjs` | Plugin developers |

| Dev scripts | `.claude/scripts/` | Plugin developers |

| Dev settings/hooks | `.claude/settings.json` | Plugin developers |

| Work tracking | [GitHub Project board](https://github.com/users/bostonaholic/projects/5/views/1) | Plugin developers |

| Versioning & release automation | [docs/versioning.md](docs/versioning.md), `.claude/skills/version-bump/`, `.claude/scripts/next-version.sh`, `.github/workflows/` | Plugin developers |

| Dev install, per harness | `script/dev-install`/`dev-uninstall` (Claude, Codex, Antigravity, OpenCode); [OpenCode lifecycle](docs/cross-host-portability.md#opencode) | Plugin developers |

**Rule of thumb:** If it validates that the plugin is *built correctly*, it is a dev concern (`.claude/`). If it runs *as part of the plugin's functionality*, it is runtime (`agents/`, `skills/`).

## Design philosophy

Agents are **decoupled microservices**. Each consumes a predecessor artifact on disk, does work, and writes its output artifact to `docs/plans/` (with YAML frontmatter on every artifact). The orchestrator walks a linear phase table in `skills/team/SKILL.md`. `skills/team/registry.json` lists the 13 agents as a phase-tagged inventory.

## Pipeline

```

WORKTREE → QUESTION → RESEARCH → DESIGN → STRUCTURE → PLAN → IMPLEMENT → PR

```

Team runs **QRSPI** (Worktree-Question-Research-Design-Structure-Plan-Implement-PR). There are **no mid-run human gates**. An adversarial design review gates the Design (~200-line alignment doc), and the orchestrator records the verdicts to `design-review-<n>.md`. The human's checkpoint is the PR review at the end. The Structure (~2-page vertical-slice breakdown) is produced autonomously and advances to Plan with no approval wait. Research is **isolated**: the researcher reads only `2-questions.md`, never `1-task.md` or the user's framing. The Plan is a tactical artifact for the implementer, not for human review. Implement is a sub-pipeline (test-first → slice execution → 5-reviewer adversarial verify with hard-gate retry loop). The whole run is autonomous with mechanical gates.

## Entry points

| Command | Phase |

|---------|-------|

| `/team <desc>` | Full 8-phase QRSPI pipeline, on stated pipeline intent — it commits, pushes, opens a PR, and moves the ticket. A leading-argument route selects a bounded task instead: `/team investigate|plan|prototype` stop at their deliverable with no commit, push, or PR; `/team feature|fix|refactor` run their full pipeline to a draft PR |

| `/team-fix <bug>` | Compressed bug-fix pipeline (no QRSPI ceremony), on stated pipeline intent, never on a plain "fix this bug" |

| `/team-worktree` | Leading WORKTREE phase: create the home worktree — a branch, so on stated intent or as phase 1 of a `/team` run. In a full run it is automatic and first. Standalone, it consumes `8-plan.md` post-PLAN for manual recovery or multi-repo setup |

| `/team-question <desc>` | Decompose intent into task + questions + brief |

| `/team-research` | Isolated codebase research (runs Question if missing) |

| `/team-design` | Draft the design. An adversarial design review gates advancement |

| `/eng-design-doc-review` | Adversarial fresh-context audit of `6-design.md`. The front door over the design reviewer brief the pipeline's design-review gate also runs |

| `/team-structure` | Break design into vertical slices (autonomous) |

| `/team-plan` | Tactical plan from the structure |

| `/team-implement` | Test-first + slice execution + 5-reviewer verify, on stated intent or as the IMPLEMENT phase — it commits each slice |

| `/team-pr` | Commit + open PR, on stated intent or as the PR phase — it pushes and moves the ticket |

## Agents (13)

See `agents/*.md`. Each agent file uses only Claude Code's [supported frontmatter fields](https://code.claude.com/docs/en/agents#supported-frontmatter-fields) (no custom fields). Model tiering: haiku (mechanical), sonnet (bounded judgment), and opus by default for complex work (research, planning, test authoring, implementation, code review, security review). `fable` is the tier above opus, for an agent with a demonstrated, concrete need opus cannot meet; the tier is empty. Never override `security-reviewer` up to fable — Fable's cybersecurity classifiers refuse security-review content in non-interactive subagent contexts — and never down off opus either. See [docs/architecture.md](docs/architecture.md#model-tiering) for everything else: the fable prerequisites, the override escape hatch, and the re-pin bar. Effort tracks the work on its own ladder: `low` (mechanical), `medium`/`high` (judgment — the band spans both), `xhigh` (strategic artifact authors: `design-author` and `structure-planner`). Methodology skills carry no `effort`. They inherit from the loading agent.

Four agents (`researcher`, `implementer`, `code-reviewer`, `security-reviewer`) hold the `Agent` tool and may spawn read-only nested sub-agents (Claude Code ≥ 2.1.172) under the guardrails in `skills/team/references/agent-dispatch.md`. Nesting is an optimization with an inline fallback, invisible to the orchestrator. See [docs/architecture.md](docs/architecture.md#10-nested-sub-agents).

**Invariant:** the agent inventory in `skills/team/registry.json` (which carries the `phase` mapping) and the files under `agents/` must always agree by name. When adding or renaming an agent, update both in the same commit. The dev hook `.claude/hooks/check-registry-sync.mjs` enforces this automatically.

**Invariant (checks and balances):** producers write, reviewers judge, and no agent does both. A reviewer (`code-reviewer`, `security-reviewer`, `technical-writer`, `ux-reviewer`, `verifier`) holds no `Write`/`Edit` tool and carries `permissionMode: plan`. A reviewer that can edit can fix what it found and then approve its own fix, which collapses the generator and the evaluator into one role. See [docs/architecture.md](docs/architecture.md#checks-and-balances).

## Skills

- See `skills/*/SKILL.md`. Entry point skills double as slash commands. Some of them are standalone slash-command utilities that are not QRSPI phases. `shipit` lands a reviewed PR — on stated ship intent, never on a PR merely being approved or green. `pr-open-comments` triages unresolved PR review feedback — on stated triage intent, because an auto-applied item commits and pushes. `pr-watch-as-author` is a bounded PR review watch loop — on stated watch intent, because it undrafts the PR and moves the ticket. `pr-watch-as-reviewer` is the reviewer-side watch-and-approve — on stated watch intent, because an approval can transitively arm an auto-merge. `groom-backlog` grooms a project backlog with a board-level pass plus per-item promotion, and can close an issue whose premise evaporated — an irreversible public mutation, each close gated on its own per-issue approval. `pr-cleanup` tears down local and remote branch state after a PR is merged or abandoned — abandon mode on the user's own stated request, never on a PR merely being stale. `prove` proves any claim a person or another skill passes in, including a PR's test plan, with evidence-rated verdicts. It changes nothing, and calls `paparazzi`, `how`, or `why` when a claim needs their evidence. `pr-screenshots` attaches local images to any PR's body and owns every upload mechanic `team-pr` used to duplicate — on stated intent to add screenshots or attach an image to a PR, never inferred from images sitting on disk. `paparazzi` captures verified screenshots of an app — local files only, never a commit, push, or PR edit; what the frames are for is its caller's decision. `pr-rebase` rebases a branch onto its base, resolving conflicts from both sides' intent and comparing the project's checks before and after — user-invoked only (`disable-model-invocation: true`), on stated rebase intent, never on a branch merely being behind. `retro` mines the invoking session's own transcript for durable learnings and turns the approved ones into skill edits and tracker issues — user-invoked only (`disable-model-invocation: true`), because a run rewrites `SKILL.md` files and files public issues. `why` investigates the design rationale behind code — parallel read-only investigators over every available evidence source, synthesized into confidence-tiered, citation-backed findings. `how` explains how a subsystem works at onboarding depth, with an optional fresh-context architectural critique; the two are companions (mechanics vs. motivation), both read-only. `no-comments` removes low-value source comments after a fresh read-only review and asks before encoding constraints — user-invoked only (`disable-model-invocation: true`), on stated comment-cleanup intent, never inferred from a diff containing comments. `agent-prompt` composes a self-contained, agent-optimized prompt for a task from a short description and an optional target repo, emitted as text with no dispatch or execution. Methodology skills are loaded by agents. Shared principles live in six ordinary documents under `skills/team/principles/`. Guarded principles are commands that set `disable-model-invocation: true` and are read by path (`principle-fix-root-causes`), never applied on their own. Execution, decisions, external-data, and bug-fix rules have scoped resource owners. Question, Research, Design, Structure, Plan, Implement, and bug-fix procedures live in playbooks with shared templates and dependency, testing, and diagnosis references. Consumers read applicable installed paths before work. Twelve agents read execution rules from their bodies; file-finder keeps its single-step contract. The 28 commands remain registered. For design guidelines on skill extraction and load limits, see [`docs/architecture.md`](docs/architecture.md#design-guidelines).

+ See `skills/*/SKILL.md`. Entry point skills double as slash commands. Some of them are standalone slash-command utilities that are not QRSPI phases. `shipit` lands a reviewed PR — on stated ship intent, never on a PR merely being approved or green. `pr-open-comments` triages unresolved PR review feedback — on stated triage intent, because an auto-applied item commits and pushes. `pr-watch-as-author` is a bounded PR review watch loop — on stated watch intent, because it undrafts the PR and moves the ticket. `pr-watch-as-reviewer` is the reviewer-side watch-and-approve — on stated watch intent, because an approval can transitively arm an auto-merge. `groom-backlog` grooms a project backlog with a board-level pass plus per-item promotion, and can close an issue whose premise evaporated — an irreversible public mutation, each close gated on its own per-issue approval. `pr-cleanup` tears down local and remote branch state after a PR is merged or abandoned — abandon mode on the user's own stated request, never on a PR merely being stale. `prove` proves any claim a person or another skill passes in, including a PR's test plan, with evidence-rated verdicts. It changes nothing, and calls `paparazzi`, `how`, or `why` when a claim needs their evidence. `pr-screenshots` attaches local images to any PR's body and owns every upload mechanic `team-pr` used to duplicate — on stated intent to add screenshots or attach an image to a PR, never inferred from images sitting on disk. `paparazzi` captures verified screenshots of an app — local files only, never a commit, push, or PR edit; what the frames are for is its caller's decision. `pr-rebase` rebases a branch onto its base, resolving conflicts from both sides' intent and comparing the project's checks before and after — user-invoked only (`disable-model-invocation: true`), on stated rebase intent, never on a branch merely being behind. `retro` mines the invoking session's own transcript for durable learnings and turns the approved ones into skill edits and tracker issues — user-invoked only (`disable-model-invocation: true`), because a run rewrites `SKILL.md` files and files public issues. `why` investigates the design rationale behind code — parallel read-only investigators over every available evidence source, synthesized into confidence-tiered, citation-backed findings. `how` explains how a subsystem works at onboarding depth, with an optional fresh-context architectural critique; the two are companions (mechanics vs. motivation), both read-only. `no-comments` removes low-value source comments after a fresh read-only review and asks before encoding constraints — user-invoked only (`disable-model-invocation: true`), on stated comment-cleanup intent, never inferred from a diff containing comments. `agent-prompt` composes a self-contained, agent-optimized prompt for a task from a short description and an optional target repo, emitted as text with no dispatch or execution. `audit-tests` audits a whole test suite against the test value bar and writes one structured report (`report.json` plus a rendered `report.md`) marking each test retain, fix, consolidate, or delete with evidence — it edits no code or test. Methodology skills are loaded by agents. Shared principles live in six ordinary documents under `skills/team/principles/`. Guarded principles are commands that set `disable-model-invocation: true` and are read by path (`principle-fix-root-causes`), never applied on their own. Execution, decisions, external-data, and bug-fix rules have scoped resource owners. Question, Research, Design, Structure, Plan, Implement, and bug-fix procedures live in playbooks with shared templates and dependency, testing, and diagnosis references. Consumers read applicable installed paths before work. Twelve agents read execution rules from their bodies; file-finder keeps its single-step contract. The 29 commands remain registered. For design guidelines on skill extraction and load limits, see [`docs/architecture.md`](docs/architecture.md#design-guidelines).

## Hooks

Team ships **no runtime hooks**. The distributed surface is agents, skills, the host manifests, and the OpenCode adapter. Session recovery lives in the orchestrator's Setup step: any `/team-*` command resolves the artifact directory and fast-forwards the ledger on entry. See [docs/architecture.md section 9](docs/architecture.md#9-state-management).

**Development** (in `.claude/hooks/`):

| Hook | Event | Purpose |

|------|-------|---------|

| `pre-merge-guard.mjs` | PreToolUse(Bash) | Deny `gh pr merge` when the version-bump invariant fails. Its reach is one surface: a literal `gh pr merge` Bash tool call in a session that loaded `.claude/settings.json`. Every other merge surface — UI, raw terminal, a wrapped call, another host — runs no version-bump check and shows no red signal for it (see [docs/versioning.md](docs/versioning.md)) |

## State

State is the set of artifacts in `docs/plans/<id>/*.md`, where `<id>` is `<TICKET>-<topic>` or `<YYYY-MM-DD>-<topic>`. Each artifact carries YAML frontmatter (`topic`, `date`, `phase`). `6-design.md` also carries `revision`, review verdicts live in `design-review-<n>.md`, and cross-model review dispositions (when the opt-in pass ran) in `cross-model-notes.md`, with raw design-round vendor transcripts in `cross-model-raw.md`. Live in-session coordination uses TodoWrite (session-scoped). Any `/team-*` command rebuilds the ledger by scanning artifacts on entry. See [docs/architecture.md section 9](docs/architecture.md#9-state-management) for the full state-management explanation.

## Learned rules

- **No `commands/` directory.** Skills are the only entry point mechanism. They auto-register as slash commands.

- **No project-scoped memory.** Do not save memories to `~/.claude/projects/*/memory/`. All project knowledge belongs in this file or docs linked from here. This file is checked into git and travels with the project.

- **Todo-first progress tracking.** Any agent or skill that executes a multi-step numbered procedure seeds one TodoWrite item per step before starting and marks each complete as it goes. See [execution rules](skills/team/references/execution.md) for the convention and ledger-ownership rules.

- **A drafted PR carries no version. Nothing versions until the step immediately before the merge command.** Bullets accumulate under `## [Unreleased]`; the version strings, the dated changelog section, and the `vX.Y.Z` PR-title prefix all stay untouched until that step. **"Land time" means exactly that moment, never "when the work is done"** — a version assigned at PR-open time is computed against a `main` that keeps moving, so it goes stale as soon as another PR lands and the pre-merge guard then denies the merge. Versioning runs through the `version-bump` skill, which fires **only on explicit land intent** and never on work merely looking landable. **The bump is also conditional on a runtime change, not universal:** only a PR that changes the **distributed runtime surface** (per the runtime-vs-development split above) bumps; a dev-only PR (CI, docs, `.claude/` tooling) lands with no bump, no changelog cut, and a plain conventional title. The deterministic gate `.claude/scripts/version-bump-required.sh` states a *merge* precondition, so its exit 1 on an unbumped runtime branch is the expected state throughout review rather than a cue to bump; `version-bump` runs it early, and the pre-merge dev hook (`.claude/hooks/pre-merge-guard.mjs`) denies the merge command on either violation. **Pre-merge step for `/shipit`:** before merging, run this repo's project-local `.claude/skills/version-bump/SKILL.md`. Team ships no versioning skill; `shipit` runs whatever pre-merge step a project declares, then pushes, waits for CI, and merges. See [docs/versioning.md](docs/versioning.md).

## Work tracking

All work, including features, bugs, and chores, is tracked on the [GitHub Project board](https://github.com/users/bostonaholic/projects/5/views/1). It is the single source of truth. If work is not on the board, it is not tracked. Create a GitHub issue in `bostonaholic/team` and add it to the project. Then move its card across the kanban (**Backlog → Ready → In progress → In review → Done**) as the work progresses. See [docs/project-tracking.md](docs/project-tracking.md) for the full workflow.

**Every issue carries a `Priority`** (`P0`, `P1`, or `P2`), set when it is created. An unprioritized issue is untriaged. **Every `bug` is `P0`**, because bugs take precedence over features and enhancements. See [docs/project-tracking.md](docs/project-tracking.md#creating-work).

## Cursor Cloud specific instructions

Node 22 is already on the image. The environment install puts Ruby 3.3.6 and Bundler 2.7.1 on `PATH`. Docs gems install into gitignored `docs/vendor/bundle`.

- Plugin checks, from the repo root: `node --test tests/*.test.mjs` and `git diff --check`. There is no `npm test` script.

- Docs, from `docs/`: `bundle exec jekyll build`, or `bundle exec jekyll serve --host 0.0.0.0 --port 4000` at http://localhost:4000. The environment start command detaches that server when port 4000 is free.

- OpenCode dev install: `script/dev-install opencode` registers `opencode/team.js`. The Claude Code, Codex, and Antigravity CLIs are not installed, so `claude plugin validate .` cannot run here.