The previous text implied personas behave identically as subagents and
teammates. Per the Agent Teams docs, the skills and mcpServers
frontmatter fields in a subagent definition are not applied when the
definition runs as a teammate — teammates load those from project and
user settings instead.
Adds a qualifier so persona authors don't assume a skills: [...] block
will load in both modes. Flagged in review.
Per the Agent Teams docs, a persona body is appended to the teammate's
system prompt as additional instructions — not a replacement. The prior
wording implied the persona owned the whole prompt, which would mislead
a persona author about what coordination instructions they inherit from
the lead (SendMessage, task-list tools, etc.).
Fixes the same inaccuracy in two locations (agents/README.md and
references/orchestration-patterns.md). Flagged in review.
Walk through a realistic scenario (intermittent 30-second checkout hang
with four plausible root causes) where Agent Teams beats /ship's subagent
fan-out: teammates can challenge each other's hypotheses directly via
inter-teammate messaging, which subagents cannot do.
Includes the one-time CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 setup, a
copy-paste trigger prompt that reuses the existing personas as teammate
types, an explicit anti-pattern warning against wrapping the workflow as
a /debug slash command (which would lose the inter-teammate messaging),
and a 'when not to use Agent Teams' decision rule.
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.
Catalog the five endorsed patterns (direct invocation, single-persona
slash command, parallel fan-out with merge, user-driven sequential
pipeline, research isolation) and four anti-patterns (router persona,
persona-calls-persona, sequential paraphrasing orchestrator, deep
persona trees). Includes a decision flow and a gate for when to add
new patterns to the catalog.
Addy Osmani