team-orchestration

Team Orchestration — Nested Team-Lead Hierarchy

Overview

This pattern runs every larger piece of work as a delegated agent organization instead of doing it solo. The main session is the CEO and delegates only — it never does the work itself (sole exception: maintaining the memory).

When to apply

• The task is large, multi-part, or quality-critical.
• Several independent sub-pieces exist (parallelizable).
• The result must be checked independently (author != reviewer).

The 5 levels

1. CEO (main session) — delegates only, NEVER does the work itself. Exception: memory.
2. Team Lead — lead, review, consolidate; also do not do the work themselves.
3. Specialists — do the actual work; may start Interns.
4. Interns — sub-pieces and supporting research.
5. Assistants — the finest-grained sub-tasks.

Hard rules (see references/roles.md)

• EVERY agent dispatch on EVERY level with model: "opus". No exceptions.
• ALWAYS start independent work in parallel — several agent calls in ONE block.
• Give agents a name; follow up on gaps via SendMessage on the named agent instead of starting it anew.
• Author != reviewer: a separate reviewer checks before anything is "done".
• Mandatory memory upkeep: status, agent IDs and handoff fully in one memory file (.remember/remember.md, see conventions.md §1).

Precedence over the workflow tool / Ultracode

Regardless of whether Ultracode is on or off, this pattern uses exclusively the nested agent hierarchy; if Ultracode is active, the hierarchy takes precedence over its workflow recommendation.

Ultracode is optional — not everyone has it. Both cases are covered:

• Without Ultracode: the nested agent hierarchy anyway.
• With active Ultracode (which literally recommends "use the Workflow tool"): the nested agent hierarchy STILL and ALWAYS takes precedence; the workflow tool is deliberately not used for this pattern.

Workflow (see references/lifecycle.md)

Decompose → dispatch in parallel → let them work → review separately → fix defects → consolidate → sign off → maintain the memory.

Concretely:

1. Decompose the assignment into independent sub-packages.
2. Start one Team Lead per package IN PARALLEL (all model: "opus", each with a name).
3. Let them work; follow up on open gaps via SendMessage, do not restart.
4. Have each package checked by a SEPARATE reviewer (read-only, fixes nothing itself).
5. Have the respective author fix the defects; verification before completion — real evidence (test/build/proof), no assertions.
6. Consolidate the results, sign off, capture the state in the memory.

Prompt building blocks

Ready-made templates for team-lead, specialist and review assignments: references/prompt-templates.md.

Operationalization in this plugin

The methodology is run via the bundled subagents team-hierarchy:team-lead, team-hierarchy:specialist and team-hierarchy:reviewer (all model: opus, reviewer read-only) plus the slash command /team-start <assignment>. The opus requirement is additionally enforced deterministically by a PreToolUse hook.

Distinction from the model skills

This pattern copies no foreign skills — it further specializes two related Superpowers skills (do NOT duplicate their content, only reference them):

• superpowers:dispatching-parallel-agents — pure parallel fan-out for 2+ independent tasks without shared state. Look it up there.
• superpowers:subagent-driven-development — plan execution with independent tasks via subagents in the running session.

Contrast this with the workflow tool, a flat deterministic phase script with no nested Team Lead. The workflow tool is a deterministic orchestration script (code/JS) with hard-wired phases (build → review → fix). It calls agent() FLAT — all sub-agents on ONE level under the orchestrator, with no nested Team Leads. That is a legitimate, sensible feature for deterministic pipelines: not bad, just the wrong tool, because the recursive 5-level hierarchy is structurally not represented by it (breadth instead of depth, script instead of model autonomy). The Agent tool used here, by contrast, is recursive — each agent may itself call the Agent tool (CEO → Team Lead → Specialist → Intern → Assistant). Each agent is its own Claude instance with its own context window and decides for itself how to sub-delegate further; there is no central script. In the harness this tool is called "Agent", officially the "Task tool" — the same concept. Mnemonics:

• Agent tool = recursive, model-driven delegation in depth.
• Workflow tool = flat, script-driven orchestration in breadth.

On top of that, this plugin lays four fixed specializations:

1. Strict 5-level hierarchy (CEO → Team Lead → Specialist → Intern → Assistant) with a clear "delegates only" rule per level — not just flat fan-out.
2. model: "opus" enforcement via hook on EVERY level — the models prescribe no model; here it is enforced deterministically.
3. Mandatory memory upkeep as a fixed single-source-of-truth file (status, agent IDs, handoff) — a prerequisite for seamless session handovers.
4. Author != reviewer as a fixed gate rule with a dedicated read-only reviewer archetype and verification before completion.

Enforceability (honest)

Only model: "opus" is deterministic, and only for an explicitly set model. The PreToolUse hook checks the dispatch's model field three ways: an EXPLICITLY set non-opus model (sonnet/haiku) is denied; opus is allowed; and an empty or missing model is ALSO allowed — a subagent whose model is set only via its agent frontmatter carries no tool_input.model, so denying would wrongly block it, and the frontmatter model: "opus" applies instead. The hook rewrites nothing; it only allows or denies, and is fail-open if jq is missing (allow plus a warning). Everything else is only guidance, not hard enforceable: "Agent tool instead of workflow tool", "CEO never does the work itself" and "author != reviewer" are PROBABILISTIC — skill and CLAUDE.md influence the model, but enforce nothing; only hooks are deterministic. For details, see the README section "Limitations".

Deep dive

• references/roles.md — roles, boundaries and responsibilities per level.
• references/lifecycle.md — complete lifecycle of a team.
• references/prompt-templates.md — prompt building blocks for dispatch and review, plus the agent-name prefix legend (tl-/sp-/rev-/int-/asst-).
• references/conventions.md — memory, git/commit and handoff conventions.
• references/case-study.md — fictional example + self-check whether the pattern is represented.