addyosmani / addyosmani/agent-skills

Docs: distinguish repo orchestration convention from current Claude Code behavior

Open
#377 2 comments 2 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
93.8k
Forks
10k
Avg merge
3d 15h
Merged PRs (30d)
23

Description

## 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](https://code.claude.com/docs/en/changelog#2-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

- Claude Code subagents docs: https://code.claude.com/docs/en/sub-agents
- Claude Code Agent Teams docs: https://code.claude.com/docs/en/agent-teams
- Claude Code changelog: https://code.claude.com/docs/en/changelog

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.