Team Architecture

A deep dive into how Team is built. Skim it for the mental model, or read it in full to contribute. The high-level pipeline overview lives on the home page.

Source of truth: the artifacts in docs/plans/<id>/*.md and the in-session TodoWrite ledger.

Contents

• 1. Design philosophy
• 2. Artifact layout & frontmatter
• 3. Pipeline (QRSPI)
• 4. Agent roster
• 5. Phase-table orchestrator
• 6. Skills
• OpenCode adapter
• 7. Hooks
• 8. Behavioral evals
• 9. State management
• 10. Nested sub-agents

1. Design philosophy

Agents are decoupled microservices. Each agent consumes a predecessor artifact on disk, does work, and produces its own artifact under docs/plans/<id>/. The orchestrator is the main session: it walks a linear phase table, dispatches the right specialist for each phase, seeds and updates a TodoWrite ledger, and runs the gates.

Principles:

• Files on disk are the durable record. Every artifact under docs/plans/<id>/ carries YAML frontmatter that describes its phase and revision metadata. Phase progression is inferred by scanning artifacts.
• TodoWrite is the live coordination ledger. It is session-scoped. Re-invoking any /team-* command rebuilds the ledger by scanning artifacts on entry.
• Registry is a phase-tagged inventory. skills/team/registry.json lists the 13 specialist agents and the QRSPI phase each serves. The orchestrator dispatches through the phase table in skills/team/SKILL.md, not through the registry.
• File artifacts survive compaction. Agents communicate through files in docs/plans/<id>/. These survive context-window compaction, can be re-read by any agent in any session, and live in git history.
• Research isolation. The researcher and file-finder never receive the user’s original task description. Enforcement is two-layer. Structural: the orchestrator only passes the 2-questions.md path to the research agents. Procedural: the research agents’ system prompts forbid reading 1-task.md.
• No mid-run human gates. The design (alignment doc) is gated by an adversarial design review. A fresh-context subagent audits it, and the orchestrator records its verdict to design-review-<n>.md. The artifacts are thus self-describing. The Structure (vertical-slice breakdown) and the Plan are not gated. They advance autonomously. The human’s checkpoint is the PR review at the end.

Trust boundary. The single human checkpoint, the end-of-run PR review, is a code checkpoint, and it happens after the run has already executed. Local Bash execution (implementer, verifier), branch creation, pushes to remotes, and any multi-repo worktree effects all occur before a human sees the PR. The PR review contains the diff, the design’s recorded assumptions, and the deferred findings in the review-notes comment. It does not contain the run’s local side effects. The pipeline also assumes that repository content the researcher reads is trusted: a repo that accepts untrusted contributions feeds untrusted text into agent context. Merging remains human-only: nothing in the pipeline marks a PR ready for review or merges it.

2. Artifact layout & frontmatter

Runtime canon: the schema below is carried for agents by artifact schema. This section is the doc-surface copy. The executable ID_RE lives in skills/team/scripts/plan-id.sh, which also builds every new <id>; PHASE_FILES lives in skills/team/discover-topic.sh.

All phase artifacts live in docs/plans/<id>/, where <id> is one of:

• Ticket-prefixed: <TICKET>-<kebab-topic> (e.g., ENG-1234-add-rate-limiting)
• Date-prefixed: <YYYY-MM-DD>-<kebab-topic> (e.g., 2026-05-01-add-rate-limiting)

Every artifact opens with YAML frontmatter. Common fields:

---
topic: <kebab-case>
date: 2026-04-30
phase: design        # task | questions | prd | repos | research | design | structure | plan
---

Per-phase additions:

Design-review record (design-review-<n>.md): each review round the orchestrator writes docs/plans/<id>/design-review-<n>.md (<n> 1-based per round) with frontmatter topic, date, phase: design-review, and verdict: <APPROVE|REQUEST CHANGES|COMMENT>. The body carries the reviewer’s findings verbatim. The verdict field is the deterministic read for resume detection. A design has passed review when the highest-<n> file carries APPROVE or COMMENT; every gate reads that through skills/team/scripts/design-review-status.sh.

Review loop (REQUEST CHANGES): the design-author re-drafts with the reviewer’s findings verbatim. The orchestrator increments revision: <n+1> in the new draft’s frontmatter.

Code-review record (review-<n>.md): each CODE REVIEW round, the session that runs team-code-review writes docs/plans/<id>/review-<n>.md with verdict: <PASS|FAIL>, the round’s pinned review range, the tier sort, and the four reviewer reports verbatim. Resume detection and /team-pr read it. The artifact schema owns its frontmatter, its sections, and its malformed, current, and stale states.

Security-review record (security-review-<n>.md): each SECURITY REVIEW round, the session that runs team-security-review writes docs/plans/<id>/security-review-<n>.md with phase: security-review. It has the same schema and record states as the code-review record, and its ## Reports holds the one security-reviewer report. Resume detection, the phase loop’s PR predecessor check, and /team-pr read it.

Phase inference (orchestrator):

Worktree presence: git worktree list --porcelain | grep -q <id>. The merge-base is taken against origin/<default>, the ref each worktree is cut from, and against the local default branch only when the repo has no origin remote. IMPLEMENT is complete once every **Commit:** subject in 8-plan.md names a commit in <merge-base>..HEAD. In multi-repo mode, that commit must be in the worktree of each repo the slice names. Without an 8-plan.md, any such commit completes it. A run interrupted before its last slice commit thus resumes at IMPLEMENT. CODE REVIEW is complete only when the newest review-<n>.md is PASS and current. SECURITY REVIEW is complete only when CODE REVIEW is complete and the newest security-review-<n>.md is PASS and current. A SECURITY REVIEW fix commit leaves the review-<n>.md record stale, so that run resumes at CODE REVIEW. The “Branch state” section of the artifact schema owns these definitions.

Discovery keys only on the six PHASE_FILES names, so review-<n>.md, security-review-<n>.md, and the two non-phase sibling outputs below are invisible to discovery. IMPLEMENT declares no phase artifact. CODE REVIEW declares review-<n>.md. SECURITY REVIEW declares security-review-<n>.md.

docs/plans/<id>/screenshots/ (PNGs plus manifest.md) is written by ux-reviewer during CODE REVIEW for UI-touching changes and consumed by team-pr. The upload itself, and every mechanic it needs, lives in skills/team-pr/ (its screenshot-*.md references and scripts/).

docs/plans/<id>/cross-model-notes.md is written by the orchestrator at the DESIGN review gate and the CODE REVIEW phase — one ### Cross-model disposition block appended per review round, at either gate, in which the cross-model pass ran — and consumed by team-pr for the PR review comments (skills/team-pr/references/07-review-comments.md). It is created only on the first round that runs the pass, so a repo where the pass never runs gains no artifact. Beside it, docs/plans/<id>/cross-model-raw.md is the design path’s raw transcript — the orchestrator appends each vendor call’s result line and fenced output at capture time. Like the notes file, it is invisible to discovery: neither is a phase artifact, and neither is ever read back as state. Both frontmatter schemas (phase: cross-model-review and phase: cross-model-raw, no verdict) live in artifact schema.

3. Pipeline (QRSPI)

The pipeline has ten phases. The orchestrator walks them in order. Each phase needs the prior phase’s artifact on disk.

WORKTREE → QUESTION → RESEARCH → DESIGN → STRUCTURE → PLAN → IMPLEMENT → CODE REVIEW → SECURITY REVIEW → PR → SHIPPED

Phase 1: Worktree

Action: orchestrator-emit (the leading phase) Predecessor: none. The description arrives in ``.

Before QUESTION, the orchestrator creates the home worktree on branch <id> off origin/HEAD using Claude Code’s native worktree support, and authors docs/plans/<id>/ inside it. Because the artifact directory is born in the worktree, no copy is ever needed and the home checkout’s git status stays clean for the whole run. The orchestrator computes the worktree’s absolute path once and threads it into every downstream dispatch (the main session does not cd).

Single-repo (default): 4-repos.md is absent. One home worktree at <repo>/.claude/worktrees/<id>.

Multi-repo: the questioner writes 4-repos.md autonomously at QUESTION, one phase after WORKTREE. The design-author writes it at DESIGN when the questioner missed the multi-repo signals. Only the home worktree is created here. Secondary worktrees are created after the design review, one per listed repo. Each repo path must first pass the containment check: its realpath must be a direct child of the home repo’s parent directory.

git -C <repo-path> worktree add .claude/worktrees/<id> -b <id> origin/HEAD

At that point the orchestrator writes a ## Worktrees section to 4-repos.md. It back-records the home worktree path plus each secondary path. Any later /team-* invocation can thus rediscover all paths from one file. Only the home repo’s worktree carries docs/plans/<id>/. Other repos’ worktrees do not duplicate the artifacts. See skills/team-worktree/playbooks/worktree.md for full topology.

Fallback: if home-worktree creation fails (shallow clone, certain CI systems, permissions), the orchestrator reports it and falls back to in-place for the entire run: docs/plans/<id>/ lives at the home-repo root and the threaded path is the home-repo root.

Phase 2: Question

Agent: questioner Predecessor: worktree prepared (+ description in $ARGUMENTS) Artifacts: docs/plans/<id>/{task,questions}.md

Decomposes the user’s intent into two artifacts. Only the questioner ever sees the user’s description. There is no separate brief.md. Neutral codebase context lives in a “Codebase context” section at the top of 2-questions.md.

Phase 3: Research

Agents: file-finder and researcher (parallel, isolated) Predecessor: 2-questions.md (orchestrator passes only the 2-questions.md path to the research agents) Artifact: docs/plans/<id>/5-research.md

Orchestrator waits for both agents to return, then writes the combined research artifact with the necessary frontmatter.

Phase 4: Design

Agent: design-author (resolves its own open questions, recording each as an auditable assumption) Predecessor: 5-research.md Artifact: docs/plans/<id>/6-design.md Gate: REVIEW. The orchestrator dispatches a fresh-context, read-only Explore subagent with the ## Review brief from skills/team/references/design-reviewer.md. The subagent holds no Write or Edit tools, so the reviewer cannot touch the artifacts it judges. The orchestrator records the verdict to design-review-<n>.md. APPROVE and COMMENT advance. On REQUEST CHANGES the agent re-drafts with the findings verbatim and increments revision.

Phase 5: Structure

Agent: structure-planner Predecessor: 6-design.md + passing design-review-<n>.md Artifact: docs/plans/<id>/7-structure.md Gate: NONE (autonomous). Once 7-structure.md exists the pipeline advances to PLAN.

Phase 6: Plan

Agent: planner Predecessor: 7-structure.md Artifact: docs/plans/<id>/8-plan.md

No gate. The plan is mechanically derived from the structure.

Phase 7: Implement

Sub-pipeline:

1. Test-first. test-architect writes failing acceptance tests.
2. Mechanical gate. The orchestrator runs the suite and the project’s static checks. All tests must fail with assertion errors, not crashes, and every static check must pass — a runner that transpiles without type-checking leaves a red type checker behind a green suite. A change whose stated contract is zero behavior change inverts both steps: step 1 is skipped with a recorded reason, since the current suite is already the acceptance suite, and the gate becomes “the checks reproduce the baseline captured before any file moved”. Green is the correct state throughout.
3. Slice execution. implementer works through the plan one slice at a time, committing each atomically. After its last slice, it runs the full suite and every project static check, fixes each failure inside the plan scope, commits those fixes, and reports each check’s result. It hands CODE REVIEW a tree clean outside docs/plans/.

IMPLEMENT ends when the implementer returns its completion report. It dispatches no reviewer.

Phase 8: Code review

Agents: code-reviewer, technical-writer, ux-reviewer, verifier (parallel), plus implementer for fix rounds Predecessor: 8-plan.md + IMPLEMENT complete Artifact: docs/plans/<id>/review-<n>.md, one per round

The orchestrator delegates this phase to the team-code-review skill (skills/team-code-review/references/02-execution.md).

1. Code review. 4 reviewers in parallel: code-reviewer, technical-writer, ux-reviewer, verifier. Each dispatch names the round’s pinned review range, from the merge-base to HEAD.
2. Aggregate gate. team-code-review sorts every finding into a severity tier: Blocking, Major, or Minor-and-below. See skills/team/references/findings.md. Each round in which the code-reviewer’s report carries a ### Cross-model disposition block, it appends that block — altered only by the blockquote wrap (every line prefixed with >) — to docs/plans/<id>/cross-model-notes.md (see section 2). It then writes the round’s review-<n>.md. While any Blocking or Major finding remains, it dispatches the implementer to fix the typed failure class. The implementer commits each fix round and leaves the tree clean, because a record is current only over a clean tree. team-code-review refuses to start over a tree dirty outside docs/plans/, and checks again after each fix round. It then re-runs all 4 reviewers automatically. It never consults the user. This is the no-consult rule. Once Blocking and Major are clean, any remaining Minor-and-below findings stay in the record for the PR’s review-notes comment and the human’s PR review.

team-code-review tracks the round count by appending Code review round <n+1> (<b> Blocking, <m> Major open) items to the TodoWrite ledger. The count is that round’s open Blocking and Major total, so an operator watching the ledger can tell a converging loop from a stuck one. The loop has no count cap. When the three newest records all carry FAIL, each later implementer fix dispatch carries Reconsider approach: rounds <a>-<n> failed, and the ledger item ends reconsider approach. The implementer then runs a root-cause analysis for each open finding class and replaces the approach inside its scope. The directive never halts the loop. An implementer blocker against an open Blocking or Major finding halts it loudly.

Recovery after an operator stop, a context-exhausted session, or a fail-closed halt: a human re-invokes the same /team-* command bare. Each command runs its own phase and names the next one to run. What the human can fix first differs by gate.

The design-review gate writes every round’s findings to design-review-<n>.md, so they are on disk to read before editing 6-design.md. The design revision counter persists in 6-design.md frontmatter. The review records persist the same way, so /team-code-review resumes from the newest review-<n>.md and the round number continues. A stale newest record runs a fresh round, whose reviewers re-derive the open set.

Phase 9: Security review

Agents: security-reviewer, plus implementer for fix rounds Predecessor: newest review-<n>.md PASS and current Artifact: docs/plans/<id>/security-review-<n>.md, one per round

The orchestrator delegates this phase to the team-security-review skill (skills/team-security-review/references/02-execution.md). That skill runs the team-code-review loop by citation and owns only a per-step delta table. It dispatches security-reviewer alone over the same pinned range. CRITICAL and HIGH findings are Blocking. MEDIUM and LOW findings are Minor and stay in the record for the PR’s review-notes comment. The loop has no count cap, never consults the user, and appends Security review round <n+1> (<b> Blocking, <m> Major open) items to the ledger. A CRITICAL or HIGH finding that only a locked acceptance test edit can fix ends in the implementer’s blocker halt.

A SECURITY REVIEW fix commit moves HEAD, so it leaves the review-<n>.md record stale. When SECURITY REVIEW passes with a stale review record, the phase loop moves the run back one phase to CODE REVIEW, which runs a fresh round over the whole range. Every shipped commit thus passes both phases. When CODE REVIEW then passes with no new commit, the security record stays current, and SECURITY REVIEW dispatches nothing on its way to PR. Standalone, /team-security-review names /team-code-review as the next command after a fix, and /team-pr otherwise.

Phase 10: PR

Action: orchestrator-emit Predecessor: newest review-<n>.md and newest security-review-<n>.md both PASS and current

team-pr first binds the review status from the newest review-<n>.md and the security status from the newest security-review-<n>.md, before any edit, so its own changelog edit cannot make either record stale. Then it updates an existing CHANGELOG.md (filter for user-facing commits since last release); if the root file is absent, leave it absent unless the user explicitly requested one. Push the branch and open a draft PR automatically with gh pr create --draft. The PR phase never waits for approval. Then surface the tracking ticket, if 1-task.md carries ticketId. When the branch impacts a UI, the PR body also gets a ## Screenshots section, populated by team-pr’s own screenshot upload, which attaches the PNGs and rewrites the body. UI impact is decided from the full branch diff; when ux-reviewer produced no capture manifest (docs/plans/<id>/screenshots/, see the artifact-layout note in section 2), the PR phase captures per the ux-reviewer brief before rendering the section. When docs/plans/<id>/cross-model-notes.md exists, team-pr posts its blocks as PR review comments (skills/team-pr/references/07-review-comments.md), replacing the final round’s inline disposition block so every round appears exactly once. /team-pr reads the newest review-<n>.md and the newest security-review-<n>.md once each and posts their ### Minor and below lines in review-notes. A stale or missing review or security record is disclosed, not refused. The worktree stays in place after the PR opens. Teardown is deferred until the PR merges or the user asks, so the branch remains available for iteration. The final report tells the user how to mark the PR ready for review and move its ticket.

4. Agent roster

13 specialist agents, organized by phase:

Each agent’s QRSPI phase is recorded in skills/team/registry.json. Agent frontmatter uses only Claude Code’s supported fields. The dev hook .claude/hooks/check-registry-sync.mjs validates that the inventory in registry.json and the files under agents/ agree by name.

Checks and balances

The roster splits into two roles with deliberately non-overlapping powers. Producers write artifacts and code. Reviewers cast verdicts. No agent holds both powers, and neither role can complete a review cycle alone.

The tools: grant is the enforcement, not prompt text. A reviewer that could edit could fix the defect it found and then approve its own fix, which collapses the generator and the evaluator into one role. Withholding Write and Edit removes that power at the harness layer.

The permissionMode column is declared, not enforced. Claude Code ignores permissionMode for plugin subagents, and it ignores any subagent’s permissionMode when the main session runs in auto, acceptEdits, or bypassPermissions mode. Plan mode would not close the gap anyway: it blocks edits but only prompts for shell commands, and an allow rule runs them. Every reviewer holds Bash, so nothing prevents a reviewer’s shell mutation. The CODE REVIEW and SECURITY REVIEW phases detect one instead: team-code-review and team-security-review compare HEAD and git status before and after each reviewer dispatch and turn any change into a Blocking finding (skills/team-code-review/references/02-execution.md, step 3).

One path steps outside that enforcement: the cross-model pass (skills/team/references/cross-model-review.md) shells out to external vendor CLIs — the code-reviewer on the code path, the orchestrator on the design path — and an external process is beyond the harness’s tool grants. On that path the reviewer invariant is trusted, not enforced: codex and agy run with their full-access flags in the repo cwd — unsandboxed, with the invoking user’s permissions — and with a vendor CLI installed, diff and design-document content leaves the machine. What bounds the path is the pinned argv the bundled script hardcodes, the per-vendor env allowlist, the machine-wide TEAM_DISABLE_CROSS_MODEL kill-switch that disables both paths when set, the untrusted-output rules on everything a vendor returns, and the post-pass git status check that reports any vendor write as a blocking finding.

researcher and file-finder are also read-only, for a different reason: research isolation (see Phase 3). Read-only does not by itself mean reviewer.

Three more balances bound the checks themselves:

• The veto ends on agreement, not on a count. The review loop runs until no Blocking or Major finding is left. A check that can never be satisfied grinds until a person stops the run. See skills/team/references/findings.md.
• The check has a check. The optional skeptic pass is default-keep. An inconclusive refutation leaves the finding standing, so the pass removes false positives only.
• The orchestrator cannot punt. The no-consult rule forbids escalation of a Blocking or Major finding to the user mid-run.

Model tiering

The principle: complex work runs on opus. Bounded judgment runs on sonnet. Mechanical checks run on haiku. fable is the tier above opus: an agent runs there on a demonstrated, concrete need opus cannot meet. The tier is empty.

• opus (complex work, the default): researcher, design-author, structure-planner, planner, test-architect, implementer, code-reviewer, and security-reviewer. Security review is complex work, so it runs on this rung like the rest. What is particular to security-reviewer is that it must never be overridden up to fable, and never down off opus; the override recipe below carries that constraint and its reason.
• sonnet (bounded single-pass judgment): questioner, ux-reviewer, technical-writer.
• haiku (mechanical checks): file-finder, verifier.

Notes:

• Overriding up to fable. After the flip, fable is the override tier and opus is the shipped default, so a user without fable access needs no override at all. What the fable override requires of plugin users: Claude Code ≥ v2.1.170 and Fable access. As of 2026-07-13, Fable 5 is not available under zero data retention (30-day retention is necessary), and on Bedrock/Vertex/Foundry ANTHROPIC_DEFAULT_FABLE_MODEL must be pinned.
  • The recommended mechanism is a per-agent file copy: copy the agent file into the .claude/agents/ directory of the session that runs it, with the one-line edit model: fable, one file per agent. Never copy security-reviewer. This is a named, load-bearing constraint on the recipe, and here is the fact behind it: Fable 5’s cybersecurity safety classifiers flag security-review content (observed 2026-07-13), and in a non-interactive subagent context a flagged request ends the turn with a refusal rather than a fallback, so the review dies mid-run. opus is a floating alias — it resolves to Claude Code’s current Opus — and riding the latest Opus rather than a dated one is deliberate: the constraint is about Fable’s classifiers, not about freezing a specific Opus. Opus-tier models carry cybersecurity safeguards of their own (far milder than Fable’s), so if security reviews ever start ending in refusals after an Opus upgrade, overriding to the prior Opus is the escape hatch.
  • Placement is part of the recommendation. An override takes effect only where the host looks for it, and a /team run has two candidate directories: the orchestrating session keeps its own directory at the primary repo root and dispatches each agent into .claude/worktrees/<id> by absolute path (skills/team/SKILL.md). The worktree is a fresh checkout that carries no untracked files unless the root .worktreeinclude names them (and only files that are also gitignored are copied), and no repo surface pins which of the two directories the host’s project-agent resolution follows — unpinned host behavior, like the frontmatter-read timing hedged below. The rule splits by run mode and holds under either answer. For an autonomous /team run, add .claude/agents/ to the repository’s .gitignore and to its root .worktreeinclude, then keep the untracked override copy at .claude/agents/<name>.md: the copy stays present at the primary repo root and worktree creation carries it into each new worktree on its own, so the override is in place whichever directory resolution follows — and /team opens no window to place a file after the worktree exists. The gitignore half is not optional — only files that are also gitignored get copied. For a phase-by-phase or manual session, an untracked copy inside the directory that session opens works with no repo change, because the user places it before dispatching. The committed alternative, for a team that wants one shared repository-wide override: commit .claude/agents/<name>.md on the repository’s default branch and push it — never on a run’s feature branch — which needs permission to push to that branch. The observable that an override took effect is the manual routing check: spawn the agent from a fresh headless session and read back the model it reports, valid only against an install of the plugin version under test (against a stale install it is a false pass). One residual holds under either route: a worktree that already exists misses the override, because reuse runs no checkout and no .worktreeinclude copy. The fix is by hand — drop the copy into that worktree’s own .claude/agents/, or let the next new worktree pick it up.
  • Parity: a user who moves implementer up to fable moves test-architect and code-reviewer with it — the scope fence and the correctness evaluator must not run on a weaker model than the implementer they gate. The parity set is exactly those three agents and stops there.
  • Freeze and resync: a copied file is a whole agent definition, not a model patch. It shadows the plugin’s prompt, tools, effort, and permissionMode, and it keeps shadowing them after plugin updates, so re-copy overridden agents after each plugin upgrade and re-apply the one-line model edit. Skill content is not frozen: the skills: field lists names, and the bodies load from the installed plugin.
  • Do not use CLAUDE_CODE_SUBAGENT_MODEL for this. The variable applies to every subagent, so any value flattens the five sonnet/haiku agents onto that tier’s price — and =fable also drags security-reviewer onto the model whose classifier refusals end a security review mid-run.
  • An override takes effect no later than the next session: a restart, or a copy placed before a session opens, applies it whether the host reads frontmatter once at session start or live-loads it.
  • The re-pin bar. An agent returns to fable in the shipped defaults on a differential: a recorded opus failure on the agent’s own task that reproduces across at least two independent runs, and a matched fable success on the same task. The bar’s qualifications and limits are part of the bar:
    • No instrument for producing that matched pair ships with this change. Its requirements sit on #139. Until that instrument lands, a re-pin proposal rests on recorded production failures plus operator judgment — weak evidence the maintainer weighs, never a cleared bar. The bar is an evidential target, not a procedure to improvise: the design that specifies one has not been done.
    • Reach. The bar starts from a recorded failure on the agent’s own task, and only three agents produce one: design-author (the adversarial design-review verdict), test-architect (the mechanical test gate), and implementer (acceptance tests plus the CODE REVIEW and SECURITY REVIEW verify). It does not reach researcher, structure-planner, planner, or code-reviewer, because nothing evaluates the artifact or verdict they produce. code-reviewer’s one live route is the coupled reviewer set below. For researcher, structure-planner, and planner the routes are two, and both are future work: the deferred work on #139 produces per-agent evidence and the bar’s terms are extended to admit it (a future decision, recorded then), or a per-task failure signal for them comes into existence. Until one of those opens, the shipped opus default holds for them. The deferred aggregate comparison is neither route: it observes the flip in aggregate, which cannot meet a bar written per agent and per task.
    • The bar’s unit is a coupled set of pins. Most sets hold one member. The reviewer set holds three: if implementer clears the bar, the re-pin moves test-architect and code-reviewer with it on implementer’s evidence alone. Never re-pin implementer solo — a scope fence or evaluator on a weaker model than the implementer it gates is the defect the 0.14.1 fence rationale forbids. The cost is stated: one agent’s evidence triples the pin count, and with it the permanent spend.
    • What counts as recorded evidence is defined per agent, because each agent’s gate detects its own class of failure. test-architect’s gate detects mechanical faults (a crash, a failing static check, a new test that does not fail with an assertion error), not a scope fence that runs green and covers too little. Its recorded failure is evidence for that class, which is what puts it on the reached list, and its practical route back is the coupled reviewer set above.
    • The multi-repo limit: the route for a failure in a multi-repo run is future work too, and the aggregate comparison cannot host it — the Golden Master is pinned to one repository, and #139 models a run with no repository axis — so the deferred instrument work must state its own repository scope.
    • The evidence venue: whatever evidence a re-pin proposal rests on lives in a GitHub issue on the project board, linking the runs it cites.

    Even for the three reached agents, nobody can complete a case today, because the matched fable half needs the instrument this change defers. And “a matched fable success on the same task” is the evidential target, not proof on its own that the tier caused a difference — two opus failures alone prove the task is hard, not that the tier caused it.

• 1M context window comes for free at the opus tier. As of 2026-08-13, Opus 5, like Opus 4.8 before it, always runs with the 1M window on the Anthropic API. Max, Team, and Enterprise plans include the 1M upgrade with the subscription, and Pro degrades gracefully to 200K. These agents thus need no [1m] suffix. The sonnet agents stay at 200K, because their bounded single-pass work is nowhere near the ceiling. Haiku does not support 1M.

• Users can override any agent’s model with CLAUDE_CODE_SUBAGENT_MODEL (applies to all subagents — see the env-var warning in the override note above), or copy an agent file into .claude/agents/ with a different model:.

• Four agents (researcher, implementer, code-reviewer, security-reviewer) additionally hold the Agent tool and may spawn read-only nested sub-agents. See 10. Nested sub-agents.

Effort tiering

Effort tracks the work the agent does, on its own four-rung ladder: low (mechanical), medium and high (judgment — the band spans both rungs), and xhigh (strategic artifact authors). The xhigh tier holds design-author and structure-planner, whose artifacts set the direction everything downstream inherits. The ladder runs alongside the model ladder rather than off it, so an agent on sonnet at high is inside the rule: questioner is the live case, doing judgment work in a bounded single pass. Methodology skills carry no effort. They inherit it from the loading agent.

User-facing skills use the same ladder. The full /team orchestrator runs at high because it maintains state and applies gates across all ten phases. Single-phase orchestrators stay at medium; their specialist agents perform the complex work. Mechanical worktree setup runs at low, while entry points that directly perform complex analysis or conflict resolution run at high.

5. Phase-table orchestrator

The orchestrator (the main session) drives /team by walking the phase table in skills/team/SKILL.md. Pseudocode:

setup:
  resolve $ARGUMENTS (issue URL → gh issue view; ticket → use as prefix).
  derive <id> = "<TICKET>-<topic>" or "<YYYY-MM-DD>-<topic>".
  create docs/plans/<id>/ if needed.
  seed TodoWrite ledger with one item per phase.
  on resume: scan docs/plans/<id>/, fast-forward the ledger.

loop:
  1. Inspect TodoWrite. If all phases completed → exit.
  2. Identify the in_progress phase. Look up agent(s) and predecessor
     artifact path(s) in the phase table.
  3. Make sure that predecessors exist on disk. For STRUCTURE that includes
     a `design-review-<n>.md` with a passing verdict. If one is missing, the
     run is desynced. Suggest the bare /team-* command again. Its three-tier
     discovery resolves docs/plans/<id>/ without an explicit arg.
  4. Dispatch the agent(s) (none for an orchestrator-emit row) — pass
     them the artifact directory `docs/plans/<id>/`.
  5. Write returned artifacts to docs/plans/<id>/<name>.md with the
     YAML frontmatter the agent specifies.
  6. Run the gate for this phase (HUMAN | MECHANICAL | ORCHESTRATOR-EMIT
     | AGGREGATE). AGGREGATE delegates to the `team-code-review` and
     `team-security-review` skills.
  7. Mark current TodoWrite item complete and the next one in_progress.
  8. Goto loop.

6. Skills

Skills live under skills/. There are two flavors:

Entry-point skills (slash commands)

Every entry-point skill carries an argument-hint field in its frontmatter (Claude Code skills frontmatter) that documents the expected $ARGUMENTS shape.

Each downstream skill (team-research and beyond) treats $ARGUMENTS as an artifact directory, typically the path printed by the previous phase’s completion message. For the 9 directory-consuming skills (team-research, team-design, team-structure, team-plan, team-worktree, team-implement, team-code-review, team-security-review, team-pr) the docs/plans/<id>/ argument is optional. Each skill resolves the directory through a three-tier chain: explicit $ARGUMENTS → newest-mtime convention discovery → AskUserQuestion. The middle tier filters by ID_RE and PHASE_FILES, applied by the bundled discovery helper below, and by the skill’s necessary predecessor artifact. The orchestrator or entry-point skill calls AskUserQuestion itself, never a subagent. Subagents never pause for user input. Standalone modes still exist. A partial skill invoked with no resolvable directory, or with a free-form description, bootstraps the missing upstream artifacts inline rather than hard-error.

Shared discovery helper. The 9 directory-consuming skills invoke the bundled skills/team/discover-topic.sh helper with their predecessor filename. team-structure also passes --require-passing-review. Each skill resolves <team-skill-dir> to the absolute directory containing skills/team/SKILL.md, then runs the helper from the repository root. The helper reads no host-specific environment variable. It owns PHASE_FILES, macOS/Linux mtime lookup, explicit-path precedence, and empty-success output when no candidate matches. It calls two siblings under skills/team/scripts/: plan-id.sh --parse, the one owner of ID_RE, and, for the optional review filter, design-review-status.sh. That script accepts only APPROVE or COMMENT from the first verdict: line of the highest-numbered design-review-<n>.md YAML frontmatter. Line 1 and a closing marker within 60 lines must both be ---; malformed or over-cap input fails closed. An explicit path skips that filter, so team-structure then runs design-review-status.sh itself on the resolved directory before any slicing; the DESIGN gate and resume detection run the same script.

Methodology skills (loaded by agents, not directly invoked)

Methodology skills carry no argument-hint. Agents load them through one of two mechanisms. The first is a skills: YAML block list in the agent’s frontmatter, one indented - <name> per line.

After the playbook-and-verification consolidation, no methodology skill remains registered: the last two (running-quality-checks and verifying-ux) moved into the verify playbook and the ux reviewer brief. The block form is the contract: three test parsers read it, and the one-line inline flow form parses to zero names, so it is an offender rather than a second shape. The second is an inline prose load instruction in the agent body. All methodology content is now an ordinary resource rather than a registered skill: it lives in ordinary references such as the code standards and writing standards, which consumers read by path before work.

Two reference forms, and the form is the contract. Every skill-to-skill reference is one of two kinds, and each has its own encoding:

The citation row splits. A reference to a skill’s own SKILL.md is also an edge in the docs/skills.md Uses/Used by graph — the consuming procedure reads the skill, so it uses it. A reference to any other file in that skill’s directory is a citation only and draws no edge, and so does a reference that only locates a skill’s install directory (for example, “the directory containing skills/team/SKILL.md”, read to run a script beside it).

The imperative phrasing on a load is what makes a model actually issue the tool call. “Load X”, “see X”, and “per X” all read as citations, and a model that treats a load as a citation proceeds on the summary in its own context instead of the skill’s actual content — a slice ships without the commit conventions applied, a review runs without its severity table, and nothing announces either.

A load carries no path. The bare name is what the Skill tool takes, and a path sitting beside it reintroduces the ambiguity the imperative exists to remove: it reads as a file to go open. Name resolution is what replaces the path’s rename-detection, and it is strictly stronger — it catches a rename and a typo, where a path assertion only ever confirmed a string was present. skills/git-commmit/SKILL.md passed the old check.

Shared principles use six ordinary documents under skills/team/principles/. Artifact and operational rules use scoped references, outside registration. Consumers explicitly read their installed paths before work; missing files stop the consuming operation with the resolved path. The dispatch contract supplies definition and resource paths for named, body-loaded, and standalone agents.

The load form applies only where the other skill is genuinely needed. A citation keeps its path and its ordinary wording: a schema lookup, a “see also”, and a pointer to a skill the frontmatter already preloaded. Turning one of those into a tool call would spend a call and a slice of context on content nobody asked for. A citation to a skill’s SKILL.md still draws a Uses edge — the procedure reads the skill — even though it is not a load.

The phrase is load-bearing as the encoding. Changing the convention means changing every reference that carries it, deliberately.

Because they are reference material rather than user actions, methodology skills set user-invocable: false in their frontmatter. This keeps them out of the / slash-command menu. They stay fully loadable by their two mechanisms above. Neither the skills: preload nor a by-path load is affected by the field, which governs only menu visibility. Setting disable-model-invocation is a separate per-skill call with its own recorded reason, and no methodology skill has one: the model auto-loading a methodology skill when relevant is how it reaches one at all. When you add a new methodology skill, set user-invocable: false. When you add a new entry-point skill, leave it unset, so it registers as a slash command.

The field is honored by Claude Code only. Codex reads no invocability field at all, so it lists every registered methodology skill in its $ picker and a user can invoke any of them. Guarded commands such as team-migrate and team-update avoid that leak with disable-model-invocation: true plus allow_implicit_invocation: false in their agents/openai.yaml, which keeps them out of Codex’s implicit catalog. There is no fix on Team’s side, and the workarounds that look plausible all fail — see cross-host-portability.md before spending time on it.

The consolidated writing standards carry the former unslop and writing-prose content as one ordinary reference. Its Team-authored categories separate AI-pattern detection from sentence mechanics within one file.

The author scans the untouched draft with the exact-text and semantic guard before applying style edits. Exact source text stays byte-identical. The semantic guard protects normative force, permission, real uncertainty, and meaningful time relations. It outranks style substitutions.

Every agent and entry point reads the writing standards before finalizing prose. Agents audit only text they author. Orchestrators store and relay completed agent and vendor reports unchanged. The fresh design reviewer can use Read, Grep, Glob, and Skill, but no mutating tool. The technical writer uses the semantic guard to veto a readability finding that would change meaning.

Claude Code may retain the writing standards for later utilities in the same context before compaction. Compaction can evict that retained content. A recovered pipeline phase uses its phase entry and reloads the writing standards explicitly.

The trigger-condition convention keys on the user-invocable field — not on argument-hint, which docs/skills.md uses to sort skill flavor. A skill that does not set user-invocable: false must state, in its description, one concise use condition by default and a second only for a distinct intent. The leading Use for … sentence describes the situation rather than quoting an exact request. The description omits its own slash command because host catalogs already show the skill name. A side-effecting or irreversible entry-point skill MUST start with an explicit-intent guard that puts the operation immediately after Use for and includes only on explicit request in that sentence. Add a specific exclusion only to prevent likely misrouting; omit generic restatements of the explicit-request requirement.

Which skills are in that class is a complement pair over every write an invocation authorizes, so it returns one answer per skill. Out of class: the invocation reads only, or writes only (1) files under docs/plans/ and (2) invocation-local scratch files — untracked, created and consumed inside the same run, carried by no commit, and read by no later phase. In class: everything else — a change to any file the repo tracks, or to an untracked file the change is meant to deliver; a git write to history or refs (a commit, a branch, a rebase, a push, a branch delete); or a change on a host outside the checkout (a PR opened, approved, or merged; a ticket or issue moved, filed, or closed; a deploy). The verb list this replaced — commits, pushes, opens a PR, moves a ticket, merges, deploys, or deletes — still reads as an illustration of the in-class half. A write the invocation never authorized, such as an unsandboxed vendor CLI mutating the tree during a cross-model pass, moves no skill into the class: the caller detects that write and reverts it rather than authoring it.

Second tier: a skill that gates every mutation on its own in-run approval carries the guard there instead, which is where human-control rules puts it. Setting disable-model-invocation is a further per-skill call with its own recorded reason, never a property of this class. An in-class skill stays listed as a command, and its routing-map line in AGENTS.md states the explicit intent, so the map never invites it on a plain request. The guard wording is the author’s and reviewer’s responsibility, and its absence on a side-effecting skill is a review-blocking defect.

No methodology skill is user-invocable. When a methodology also wants a user-facing command, the answer is a front door, not an exception: the methodology keeps user-invocable: false and a separate entry-point skill carries the slash command. The review procedures moved off the methodology list entirely. Each reviewer brief is an ordinary reference under skills/team/references/: the code reviewer brief (code-reviewer.md), the security and documentation briefs (security-reviewer.md, documentation-reviewer.md), the UX reviewer brief (ux-reviewer.md), the shared finding format (findings.md), and the design reviewer brief (design-reviewer.md). The code-reviewer, security-reviewer, ux-reviewer, and technical-writer agents read them from the installed plugin, and team and team-design read the design reviewer brief by path.

(This is separate from the entry-point skills, which are user-invocable by definition. Some of those, e.g. team-worktree and team-pr, are also referenced by path from team/SKILL.md, but those are procedural cross-links in the orchestrator’s prose, not a parent loading the skill as a building block.)

For the full per-skill reference (all skills, each with the skills it loads, which is the skill-to-skill dependency graph), see skills.md.

Design guidelines

Skill sources follow six rules: assert without arguing; state invariants instead of exhaustive case lists; define shared rules once; keep SKILL.md as a router to references/ and scripts; use descriptions only for capability and trigger; and test commands, numbers, names, paths, or behavior rather than prose wording.

Source budgets remain 80 lines for methodology and 150 for entry points. Descriptions are at most 200 characters, or 150 for methodology. An overage requires a reviewed reason stating its exact line count.

1. Methodology skill load limit: three methodology skills is what an agent gets without argument. Every name in the agent’s skills: block counts, including the agent’s own procedure skill. An agent that lists more than three carries one recorded reason, and that record names the count it justifies. A fourth name still signals that the agent’s responsibility can be too broad, and answering that is what the reason is for.

2. Extraction threshold: capability against fragment. Content that is an independently useful capability earns its own skill regardless of consumer count. Such content is coherent and self-contained, and the model or a future consumer can plausibly load it on demand. Claude Code preloads only each skill’s name and description. The body loads just-in-time when invoked. An unused small skill thus costs almost nothing. Content embedded into a consumer instead forecloses just-in-time loading for everyone else. Content that is only meaningful inside one consumer’s procedure, a procedure fragment, stays inline in that consumer.

3. Shared principles: six ordinary documents define human control, durable state, verified results, independent review, focused work, and boil the ocean. Execution, external-data, decisions, and bug-fix resources own the remaining operational rules. Question, Research, Design, Structure, Plan, and Implement procedures live in playbooks with shared templates and dependency, testing, and diagnosis references. Code policy lives in the code-standards reference; prose policy lives in the writing-standards reference. Read only applicable resources from the installed skill or agent base. Stop missing reads with the exact path. Twelve agent bodies read execution rules. File-finder retains its single-step contract. Resources use no skill frontmatter or discovery metadata. Keep the 14 commands registered. Guarded commands such as team-migrate and team-update carry skill frontmatter and agents/openai.yaml, register as commands, and set disable-model-invocation: true so the model never applies them on its own. Do not add unguarded principle registrations, recursive loading, compatibility stubs, or a resource registry.

Step delegation

A skill’s main session orchestrates; it does not do the step work itself. Each numbered step runs in a fresh-context subagent with a self-contained brief (goal, input paths, boundaries, return shape, done condition) and returns a status line plus evidence. The main session keeps user questions, gate and verdict decisions, one-command steps, and the TodoWrite ledger. Dependent steps run one at a time; independent steps fan out in one turn. /team-fix delegates Reproduce, Red, Green, Verify, and Ship. /team-pr delegates input gathering, screenshots, the changelog, body authoring, upload, and review comments. The mechanical test gate delegates its evidence run. The host mapping (Claude Code Agent, Codex spawn_agent with fork_turns: "none", Antigravity invoke_subagent) and the inline fallback live in skills/team/references/step-delegation.md.

Codex host manifests

Every skill under skills/ carries agents/openai.yaml, the per-skill manifest Codex reads to build its catalog entry. Without one, Codex falls back to the directory name and a truncated description:. The file is optional upstream and mandatory here.

Three fields, each derived from the skill’s own SKILL.md frontmatter rather than stored twice: display_name title-cases the kebab name: through two closed lists (acronyms up, joiners down); short_description is an imperative phrase in the spec’s 25-64 character window; default_prompt is Use $<name> to <short_description with its first character lowercased>., using the skill’s own declared name as the explicit-invocation token. No icons, no brand color. A policy block declaring allow_implicit_invocation: false appears if and only if the frontmatter sets disable-model-invocation: true, and the test asserts that equality in both directions.

short_description has no mechanical derivation. The creation guide requires updating agents/openai.yaml whenever description: changes; the manifest gate checks its shape and length.

OpenCode adapter

Distributed opencode/team.js exports only the native plugin function. It resolves its real checkout and imports opencode/catalog.mjs, the same catalog validator used by script/dev-opencode.mjs. The Bash lifecycle entry scripts require Node. script/dev-install/dev-uninstall and dev.yml route the OpenCode target to them. opencode/ counts as distributed runtime for land-time versioning.

The catalog enumerates immediate real skill directories in stable order, reads each header once, and walks each tree once without following links. It rejects nested skill files, symlinks, invalid/ambiguous consumed frontmatter, duplicate names, empty catalogs, and canonical template-marker paths. References and scripts remain canonical files. Install validates before registration; plugin initialization validates before returning config contributions. Existing command collisions and invalid consumed config types fail before any config mutation.

All skills receive native configured commands containing canonical file/base pointers and $ARGUMENTS, without embedded bodies, model overrides, or agent overrides. This includes methodology skills marked user-invocable: false. Frontmatter disable-model-invocation: true excludes only Team’s added native skill paths. Those skills still have explicit commands. Existing external skill sources may expose their own guarded copies or resolve duplicate names to other files. Team commands retain canonical pointers, but later plugins/MCP can collide.

Command-file reads use native read and external_directory permission. Unguarded cached skill loading uses skill permission. read: deny does not block that route. Supplied arguments retain native preprocessing, including shell syntax such as !`printf example` that can run before a model call, outside model-tool rules including bash: deny. File pointers preserve body text. They do not make arguments inert. See OpenCode support for usage and resolved-skill versus command-template diagnostics.

Lifecycle operations canonicalize the existing plugin parent, acquire its atomic team.js.lock directory, then inspect/change only the exact-owned symlink. They release only their acquired empty lock, refuse busy/stale locks, preserve config and credentials without reading them, and never invoke OpenCode. Install success means registered. Native config loading remains separate. New host processes read live checkout edits. Concurrent checkout edits or external replacement without the lifecycle lock are unsupported.

This adapter establishes discovery and lifecycle support. Full QRSPI execution, specialist/nested dispatch, and reviewer isolation on OpenCode remain unverified.

7. Hooks

Team ships no runtime hooks. The distributed plugin has no hooks/ tree and registers no host hook events. Session recovery is the orchestrator’s Setup step (section 5): any /team-* command resolves docs/plans/<id>/ and rebuilds the ledger from artifact presence and frontmatter on entry. .team/config.json is validated by the resolver at dispatch time, not ahead of a prompt.

Development hooks (.claude/hooks/, not distributed):

Development scripts (.claude/scripts/, not distributed) house dev-only tooling run by plugin developers: version computation, the land-time version-consistency assertion, and project-board helpers.

8. Testing

Team currently has no test suite. The previous behavioral-eval harness (tests/, evals/, and its CI workflows) was removed so a new testing methodology can be designed from scratch. What remains is static: the dev hooks under .claude/hooks/, the version scripts under .claude/scripts/ and .github/scripts/, and claude plugin validate ..

9. State management

Primary state: the artifacts in docs/plans/<id>/*.md. Each artifact’s YAML frontmatter is the source of truth for “did this phase finish?” and “did the design review pass?”

Live coordination: TodoWrite (session-scoped). The orchestrator seeds the ledger at the start of /team, marks each item in_progress when dispatching, and completed when the artifact lands. Any /team-* command rebuilds the ledger by scanning artifacts on entry, so an interrupted run can be resumed by re-invoking any of them bare: discovery auto-resolves the artifact directory (an explicit docs/plans/<id>/ is still accepted). On a host offering no TodoWrite, docs/plans/<id>/ledger.md substitutes for the ledger rather than supplementing it, and the run reports which of the two it used; being on disk, that one is durable rather than session-scoped, so its round items survive a restart.

Design-review records: docs/plans/<id>/design-review-<n>.md (frontmatter verdict: <APPROVE|REQUEST CHANGES|COMMENT>) records each review round durably. The artifacts are self-describing.

Review records: docs/plans/<id>/review-<n>.md and docs/plans/<id>/security-review-<n>.md (frontmatter verdict: <PASS|FAIL>) record each CODE REVIEW and SECURITY REVIEW round durably, on every host. Resume detection, the team-code-review and team-security-review round numbers, and /team-pr read them, so a restart loses no round result.

Compaction defense: when context is compacted or a fresh session begins, the durable record is the artifacts themselves. Re-invoking any /team-* command resolves the active docs/plans/<id>/ directory from disk and rebuilds the ledger from artifact presence and frontmatter.

Artifact persistence: during a run, files in docs/plans/<id>/ live on disk in the worktree’s working tree and the pipeline never commits them. That discipline keeps artifacts out of the commit-based IMPLEMENT signal. The signal matches each 8-plan.md **Commit:** subject against the commits past the merge-base with origin/<default>, and without a plan any such commit counts. Any commit on <id> is thus a code or slice commit, never an artifact commit. A finished plan directory can land later in its feature PR, which is outside the run. Persistence across sessions, compaction events, and context resets comes from the survival of the worktree’s files, not from git history. They remain the durable communication protocol between agents and the source of truth for “did phase N finish?”

10. Nested sub-agents

Claude Code v2.1.172 lets sub-agents spawn their own sub-agents (up to 5 levels deep). The plugin uses this capability in exactly three patterns, all governed by skills/team/references/agent-dispatch.md:

• Context-economy scouts (researcher, implementer): read-only Explore / team:file-finder helpers that absorb bulk reading the parent would otherwise hold in its own context without ever referencing it again. Scouts are long-lived: both agents hold SendMessage, so a follow-up question inside a live scout’s territory goes to that scout (warm context) rather than to a cold respawn, and the implementer dispatches the next slice’s scout in the background while finishing the current slice. The researcher’s scouts inherit the research isolation invariant: task-derived content in scout prompts — first dispatch and follow-up alike — is restricted to verbatim question text and Codebase context from 2-questions.md, plus 4-repos.md paths. Fixed trusted prose paths, audit instructions, read-only tool rules, reply caps, and output contracts are allowed operational method text.
• Skeptic verification (code-reviewer, security-reviewer): each hard-gate finding (Blocking, CRITICAL, or HIGH) goes to a fresh general-purpose sub-agent as a neutral, falsifiable claim, with instructions to refute it. The claim never carries the reviewer’s verdict or severity. Skeptics are deliberately one-shot — never a follow-up to a live skeptic — because a skeptic that has judged earlier claims accumulates a model of the review and anchors to it. Default-keep: a finding is dropped only on an evidence-backed refutation the reviewer verifies itself. A false hard-gate finding costs an entire review round (implementer re-dispatch
  • the phase’s reviewers re-run), so the pass pays for itself.
• Vendor couriers (code-reviewer; the orchestrator uses the same pattern at the design-review gate as ordinary dispatch): each cross-model vendor call runs through one Explore courier named after its CLI (codex-review, agy-review), so each external model’s review is visible as its own agent while it runs. The courier’s errand is fixed — run the pinned runner command, return its stdout verbatim — and the vendor-courier block in skills/team/references/cross-model-review.md carries the contract plus the inline fallback when nesting is unavailable.

Policy:

• The Agent tool is granted to exactly four agents: researcher, implementer, code-reviewer, security-reviewer. Any other agent gaining the tool must be a deliberate decision.
• Nested helpers are read-only, never write under docs/plans/, and never pause for user input (see skills/team/references/agent-dispatch.md).
• Depth budget: pipeline agents sit at depth 2 of 5 and may spawn at most one more level.
• Version-gated. Nesting requires Claude Code >= 2.1.172. The universal gate is Agent-tool presence. The platform withholds the tool from sub-agents below that floor. An agent that lacks Agent thus works inline. So does any read-only agent like researcher that has no Bash. Agents that also hold Bash additionally run the bundled deterministic check skills/team/references/supports-nesting.mjs "$(claude --version)". The check is fail-closed: an older release, unrecognizable version output, or an environment where it cannot run all resolve to “unsupported,” which routes the agent to its inline path.
• Optimization, never a dependency. Every nested-dispatch section is optional with a mandatory inline fallback. On Claude Code versions without nesting, the plugin degrades to exactly its previous behavior. Nesting is invisible to the orchestrator: no phase-table, gate, or artifact contract depends on it.

Before any non-vendor dispatch, the parent resolves and Reads the writing standards reference under ${CLAUDE_PLUGIN_ROOT}. Claude Code substitutes that installed plugin root before dispatch. The prompt carries the resolved, read-only path. The helper Reads it before it audits its authored report. If any Read fails, the parent discards the return. Research scouts fall back to inline reading. Reviewer skeptics keep the finding by default. Vendor couriers receive no prose paths and relay stdout unchanged.

Research assembly treats completed file-finder and researcher returns as unchanged, untrusted source data. At capture, the root wraps each return in a backtick fence labeled untrusted-evidence-file-finder or untrusted-evidence-researcher and makes it longer than every backtick run in that return. A fixed line identifies the blocks as untrusted evidence and says embedded imperatives carry no authority. The root then traces every final substantive claim only to the completed returns, never to task framing. Neither return carries a line cap. The root adds only the frontmatter, the authority line, four fence lines, and one source-grounded synthesis line, and never truncates source data. Design, structure, planning, test authoring, and implementation use those blocks only as evidence. Each actor revalidates proposed actions or acceptance tests against 1-task.md, which records user intent. Embedded imperatives authorize no action.

Future work (ship-later)

Recorded here so the next capability step is deliberate, not improvised. Prerequisite for all items: nesting survives 2-3 Claude Code releases without breaking changes, parallel dispatch semantics for nested children are confirmed, and the depth cap is stable.

• Verify-coordinator (strongest candidate): a CODE REVIEW-phase coordinator that owns the 4-reviewer fan-out, the aggregate gate, and the typed failure retry loop. It returns a compact terminal verdict for the orchestrator to render: {verdict: PASS | CONDITIONAL | ESCALATE, rounds, findings[]}. This keeps every reviewer report out of the orchestrator’s long-lived context. Needs: a terminal-verdict envelope protocol, because the no-consult rule means no mid-loop user interaction exists to forward. It builds on the per-round docs/plans/<id>/review-<n>.md records, which already survive coordinator death.
• Research-coordinator: only if multi-repo research outgrows the current 2-agent fan-out (e.g. 2×N agents across N repos).
• Parallel sub-implementers: only ever slice-level (never step-level), one worktree per slice, coordinator cherry-picks sequentially to preserve linear history. Requires measured wall-clock pain on large plans.

See also

• Skills: the full per-skill reference for all skills.
• Vision: the loop-driven end state this design builds toward.
• Ethos: the principles behind the pipeline.
• Overview: the landing page and pipeline overview.