From d01ec538db1da69e175e3d82138551316700e3ea Mon Sep 17 00:00:00 2001 From: Addy Osmani Date: Sat, 18 Apr 2026 23:32:17 -0700 Subject: [PATCH] docs: document Claude Code subagent and Agent Teams compatibility Verify the orchestration design against the official Claude Code docs and make the platform mapping explicit: - /ship now names the Agent tool and the subagent_type field directly, with a fallback note for harnesses that lack an Agent tool. - AGENTS.md notes that personas work as both subagents and Agent Teams teammates, and lists the unsupported plugin frontmatter fields. - agents/README.md gains a Claude Code interop section and notes that rule #2 is also a hard platform constraint. - references/orchestration-patterns.md gains a Claude Code compatibility appendix covering plugin paths, the subagents-vs-teams comparison, the built-in Explore/Plan/general-purpose subagents, and the parallel Agent tool call requirement. Pattern 5 now points at Explore first. No behavior changes; documentation only. --- .claude/commands/ship.md | 17 ++++++--- AGENTS.md | 2 + agents/README.md | 13 ++++++- references/orchestration-patterns.md | 57 ++++++++++++++++++++++++++++ 4 files changed, 83 insertions(+), 6 deletions(-) diff --git a/.claude/commands/ship.md b/.claude/commands/ship.md index b1cc8e06..eba257f7 100644 --- a/.claude/commands/ship.md +++ b/.claude/commands/ship.md @@ -8,13 +8,20 @@ Invoke the agent-skills:shipping-and-launch skill. ## Phase A — Parallel fan-out -Spawn the following sub-agents concurrently. Each should run in its own context and return a structured report: +Spawn three subagents concurrently using the Agent tool. **Issue all three Agent tool calls in a single assistant turn so they execute in parallel** — sequential calls defeat the purpose of this command. -1. **code-reviewer** — Run a five-axis review (correctness, readability, architecture, security, performance) on the staged changes or recent commits. Output the standard review template. -2. **security-auditor** — Run a vulnerability and threat-model pass. Check OWASP Top 10, secrets handling, auth/authz, dependency CVEs. Output the standard audit report. -3. **test-engineer** — Analyze test coverage for the change. Identify gaps in happy path, edge cases, error paths, and concurrency scenarios. Output the standard coverage analysis. +In Claude Code, each call passes `subagent_type` matching the persona's `name` field: -Do not run these sequentially. Do not let one persona call another. Each persona sees the same diff and produces its own perspective. +1. **`code-reviewer`** — Run a five-axis review (correctness, readability, architecture, security, performance) on the staged changes or recent commits. Output the standard review template. +2. **`security-auditor`** — Run a vulnerability and threat-model pass. Check OWASP Top 10, secrets handling, auth/authz, dependency CVEs. Output the standard audit report. +3. **`test-engineer`** — Analyze test coverage for the change. Identify gaps in happy path, edge cases, error paths, and concurrency scenarios. Output the standard coverage analysis. + +In other harnesses without an Agent tool, invoke each persona's system prompt sequentially and treat their outputs as if returned in parallel — the merge phase still works. + +Constraints (from Claude Code's subagent model): +- Subagents cannot spawn other subagents — do not let one persona delegate to another. +- Each subagent gets its own context window and returns only its report to this main session. +- If you need teammates that talk to each other instead of just reporting back, use Claude Code Agent Teams and reference these personas as teammate types (see `references/orchestration-patterns.md`). ## Phase B — Merge in main context diff --git a/AGENTS.md b/AGENTS.md index 9d892cad..7b094707 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,6 +79,8 @@ The only multi-persona orchestration pattern this repo endorses is **parallel fa See [agents/README.md](agents/README.md) for the decision matrix and [references/orchestration-patterns.md](references/orchestration-patterns.md) for the full pattern catalog. +**Claude Code interop:** the personas in `agents/` work as Claude Code subagents (auto-discovered from this plugin's `agents/` directory) and as Agent Teams teammates (referenced by name when spawning). Two platform constraints align with our rules: subagents cannot spawn other subagents, and teams cannot nest. Plugin agents silently ignore the `hooks`, `mcpServers`, and `permissionMode` frontmatter fields. + ## Creating a New Skill ### Directory Structure diff --git a/agents/README.md b/agents/README.md index 4a69cb64..0f423092 100644 --- a/agents/README.md +++ b/agents/README.md @@ -96,10 +96,21 @@ Why this fails: ## Rules for personas 1. A persona is a single role with a single output format. If you find yourself adding a second role, create a second persona. -2. **Personas do not invoke other personas.** Composition is the job of slash commands or the user. +2. **Personas do not invoke other personas.** Composition is the job of slash commands or the user. On Claude Code this is also a hard platform constraint — *"subagents cannot spawn other subagents"* — so the rule is enforced for you. 3. A persona may invoke skills (the *how*). 4. Every persona file ends with a "Composition" block stating where it fits. +## Claude Code interop + +The personas in this repo are designed to work as Claude Code subagents and as Agent Teams teammates without modification: + +- **As subagents:** auto-discovered when this plugin is enabled (no path config needed). Use the Agent tool with `subagent_type: code-reviewer` (or `security-auditor`, `test-engineer`). `/ship` is the canonical example. +- **As Agent Teams teammates** (experimental, requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`): reference the same persona name when spawning a teammate. The persona's body becomes the teammate's system prompt. + +Subagents only report results back to the main agent. Agent Teams let teammates message each other directly. Use subagents when reports are enough; use Agent Teams when sub-agents need to challenge each other's findings (e.g. competing-hypothesis debugging). See [references/orchestration-patterns.md](../references/orchestration-patterns.md) for the full mapping. + +Plugin agents do not support `hooks`, `mcpServers`, or `permissionMode` frontmatter — those fields are silently ignored. Avoid relying on them when authoring new personas here. + ## Adding a new persona 1. Create `agents/.md` with the same frontmatter format used by existing personas. diff --git a/references/orchestration-patterns.md b/references/orchestration-patterns.md index 9f98801f..65aa0292 100644 --- a/references/orchestration-patterns.md +++ b/references/orchestration-patterns.md @@ -110,6 +110,63 @@ main agent → research sub-agent (reads 50 files) → digest → main agent con **Cost:** one isolated sub-agent context. Worth it any time the alternative is loading hundreds of files into the main context. +**On Claude Code, use the built-in `Explore` subagent** rather than defining a custom research persona. `Explore` runs on Haiku, is denied write/edit tools, and is purpose-built for this pattern. Define a custom research subagent only when `Explore` doesn't fit (e.g. you need a domain-specific system prompt the model wouldn't infer). + +--- + +## Claude Code compatibility + +This catalog is harness-agnostic, but most readers will run it on Claude Code. Here's how each pattern maps onto Claude Code's primitives — and where the platform enforces our rules for us. + +### Where personas live + +Plugin subagents go in `agents/` at the plugin root. This repo is a plugin (`.claude-plugin/plugin.json`), so `agents/code-reviewer.md`, `agents/security-auditor.md`, and `agents/test-engineer.md` are auto-discovered when the plugin is enabled. No path configuration needed. + +### Subagents vs. Agent Teams + +Claude Code has two parallelism primitives. Pattern 3 (parallel fan-out with merge) maps to **subagents**. If you need teammates that talk to each other, use **Agent Teams** instead. + +| | Subagents | Agent Teams | +|--|-----------|-------------| +| Coordination | Main agent fans out, sub-agents only report back | Teammates message each other, share a task list | +| Context | Own context window per subagent | Own context window per teammate | +| When to use | Independent tasks producing reports | Collaborative work needing discussion | +| Status | Stable | Experimental — requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` | +| Cost | Lower | Higher — each teammate is a separate Claude instance | + +**The personas in this repo work in both modes.** When spawned as subagents (e.g. by `/ship`), they report findings to the main session. When spawned as teammates (`Spawn a teammate using the security-auditor agent type…`), they can challenge each other's findings directly. The persona definition is the same; only the spawning context changes. + +### Platform-enforced rules + +Two rules in this catalog aren't just convention — Claude Code enforces them: + +- **"Subagents cannot spawn other subagents"** (verbatim from the docs). Anti-pattern B (persona-calls-persona) and Anti-pattern D (deep persona trees) cannot exist on Claude Code by construction. +- **"No nested teams"** — teammates cannot spawn their own teams. Same anti-patterns blocked at the team level. + +This means you can adopt the patterns in this catalog without worrying about contributors accidentally building the anti-patterns. They'll just fail to load. + +### Built-in subagents to know about + +Before defining a custom subagent, check whether one of these covers the role: + +| Built-in | Purpose | +|----------|---------| +| `Explore` | Read-only codebase search and analysis. Use this for Pattern 5 (research isolation). | +| `Plan` | Read-only research during plan mode. | +| `general-purpose` | Multi-step tasks needing both exploration and modification. | + +Don't redefine these. Layer your specialist personas (code-reviewer, security-auditor, test-engineer) on top of them. + +### Frontmatter restrictions for plugin agents + +Plugin subagents do **not** support the `hooks`, `mcpServers`, or `permissionMode` frontmatter fields — these are silently ignored. If a future persona needs any of those, the user must copy the file into `.claude/agents/` or `~/.claude/agents/` instead. + +The fields that DO work in plugin agents are: `name`, `description`, `tools`, `disallowedTools`, `model`, `maxTurns`, `skills`, `memory`, `background`, `effort`, `isolation`, `color`, `initialPrompt`. Use `model` per-persona if you want to optimize cost (e.g. Haiku for `test-engineer` coverage scans, Sonnet for `code-reviewer`, Opus for `security-auditor`). + +### Spawning multiple subagents in parallel + +In Claude Code, parallel fan-out (Pattern 3) requires issuing **multiple Agent tool calls in a single assistant turn**. Sequential turns serialize execution. `/ship` calls this out explicitly. Any new orchestrator command should do the same. + --- ## Anti-patterns