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 for the full design.

North star: read docs/vision.md and 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, 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.

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 → CODE REVIEW → SECURITY REVIEW → PR

Team runs QRSPI (Worktree-Question-Research-Design-Structure-Plan-Implement-Code Review-Security Review-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 test-first plus slice execution. Code review runs the 4-reviewer adversarial verify with the hard-gate fix loop and writes review-<n>.md each round. Security review then runs the security reviewer alone in the same loop and writes security-review-<n>.md each round. A security fix commit sends the run back through Code review before PR. The whole run is autonomous with mechanical gates.

Entry points

Agents (13)

See agents/*.md. Each agent file uses only Claude Code's 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 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.

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 (Claude Code ignores that field for plugin agents, so the tools: grant is the only enforcement, and a post-dispatch tree check in CODE REVIEW and SECURITY REVIEW detects Bash mutation). 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.

Skills

See skills/*/SKILL.md. Team ships only its pipeline: the /team orchestrator, the ten phase commands (/team-worktree through /team-pr), the /team-fix bug-fix pipeline, the explicit-only /team-migrate setup migration, and the explicit-only /team-update release update. Entry point skills double as slash commands. Methodology skills are loaded by agents. Shared principles live in six ordinary documents under skills/team/principles/. 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 14 commands remain registered. For design guidelines on skill extraction and load limits, see docs/architecture.md.

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.

Development (in .claude/hooks/):

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, per-round code-review records live in review-<n>.md, per-round security-review records in security-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 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 for the convention and ledger-ownership rules.
• Every dispatched subagent starts with a fresh context window. A skill, agent, or reference that starts a subagent links fresh context, or reads host dispatch, step delegation, or agent dispatch before the dispatch. Never ask for a fork of the parent conversation. Team asks each host for a fresh child, and not every host can prove it gives one. A passage that only describes subagents needs nothing.
• 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.

Work tracking

All work, including features, bugs, and chores, is tracked on the GitHub Project board. 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 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.

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.