# 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.

## Installing Team

Installing Team for a user? Follow [INSTALL.md](INSTALL.md), using the section for each harness they run.

## 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 (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 (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 |
| `/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 |
| `/team-migrate` | Move a machine set up before v0.147.0 onto native Team plus the `bostonaholic/skills` plugin in every harness, on explicit request only — it rewrites plugin registrations and moves old skill copies aside after one confirmation |

## 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`. Team ships only its pipeline: the `/team` orchestrator, the eight phase commands (`/team-worktree` through `/team-pr`), the `/team-fix` bug-fix pipeline, the explicit-only `/team-migrate` setup migration, and one guarded principle. Entry point skills double as slash commands. 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. The reviewer briefs (code, security, documentation, UX, design) and the finding format live under `skills/team/references/`; the reviewer agents and the design-review gate read them by path. 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 12 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 |
|------|-------|---------|
| `check-registry-sync.mjs` | PostToolUse(Write\|Edit) | Cross-check agent frontmatter against registry.json |
| `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

- **Test executable code, not skill Markdown.** Do not add assertions about skill or agent prose, frontmatter, links, or fenced examples. Evaluate agent behavior in a future eval suite. Script tests may use synthetic Markdown as input or inspect generated Markdown output.

- **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:** before merging any PR, run this repo's project-local `.claude/skills/version-bump/SKILL.md`. Team ships no versioning skill; a land command that honors declared pre-merge steps runs it, 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.