Context
The Claude Code orchestration notes in this repo appear to predate the June 2026 Claude Code updates, so this looks like documentation drift rather than incorrect original guidance.
The repo currently describes subagents cannot spawn other subagents as a hard Claude Code platform constraint, while also using that constraint to reinforce the repo rule that personas should not invoke other personas.
That repo rule still seems valuable and should remain. The part that may need updating is the platform-mapping wording.
Current drift candidates
AGENTS.md, docs/agents.md, and references/orchestration-patterns.md describe nested subagents as impossible on Claude Code.- The Agent Teams worked example still includes a separate
Clean up the team instruction, which reads like older TeamDelete-style behavior.
Current Claude Code behavior
- As of Claude Code v2.1.172, subagents can spawn their own subagents, up to 5 levels deep.
- The official docs still allow projects to prevent that by omitting the
Agent tool from an explicit tools allowlist or by using disallowedTools.
- As of Claude Code v2.1.178, Agent Teams no longer use
TeamCreate / TeamDelete; with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, each session has one implicit team and teammates are spawned directly with the Agent tool name parameter.
- Agent Teams still cannot nest: teammates cannot spawn their own teammates.
Suggested direction
Keep the repo orchestration convention:
- personas do not invoke other personas;
- composition remains the job of slash commands or the user;
- Agent Teams remain the only endorsed pattern when teammates need to communicate directly.
But reword the Claude Code compatibility notes so the repo rule is framed as a deliberate project convention, not as a current hard platform limitation.
For the Agent Teams example, remove or soften the separate Clean up the team instruction; current docs describe no separate TeamDelete-style cleanup step, while still documenting graceful teammate shutdown and possible orphaned tmux cleanup.
Non-goal
This issue is not asking the repo to adopt nested persona trees. It is only about keeping the Claude Code interop documentation accurate while preserving the repo orchestration model.
Sources
Context
The Claude Code orchestration notes in this repo appear to predate the June 2026 Claude Code updates, so this looks like documentation drift rather than incorrect original guidance.
The repo currently describes
subagents cannot spawn other subagentsas a hard Claude Code platform constraint, while also using that constraint to reinforce the repo rule that personas should not invoke other personas.That repo rule still seems valuable and should remain. The part that may need updating is the platform-mapping wording.
Current drift candidates
AGENTS.md,docs/agents.md, andreferences/orchestration-patterns.mddescribe nested subagents as impossible on Claude Code.Clean up the teaminstruction, which reads like olderTeamDelete-style behavior.Current Claude Code behavior
Agenttool from an explicit tools allowlist or by usingdisallowedTools.TeamCreate/TeamDelete; withCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, each session has one implicit team and teammates are spawned directly with the Agent toolnameparameter.Suggested direction
Keep the repo orchestration convention:
But reword the Claude Code compatibility notes so the repo rule is framed as a deliberate project convention, not as a current hard platform limitation.
For the Agent Teams example, remove or soften the separate
Clean up the teaminstruction; current docs describe no separateTeamDelete-style cleanup step, while still documenting graceful teammate shutdown and possible orphaned tmux cleanup.Non-goal
This issue is not asking the repo to adopt nested persona trees. It is only about keeping the Claude Code interop documentation accurate while preserving the repo orchestration model.
Sources