addyosmani / addyosmani/agent-skills

Docs: distinguish repo orchestration convention from current Claude Code behavior

Abierto
#377 2 comentarios 2 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
JavaScript
Estrellas
93.8k
Forks
10k
Merge medio
3 d 15 h
PR fusionados (30 d)
23

Descripción

## 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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.