team-forming

team-forming

Compose and spawn a team for one task-group. Returns the team-slug, member list with agent IDs, formation output contract, and scaling envelope to the caller (the main session, or a coordinating agent when invoked from one).

Actors (terminology). Two actors drive everything below:

• Orchestrator — whoever runs this skill: the main session, or a coordinating agent that invoked it. It forms the team and, after handoff, acts as the coordinator that wakes members at their phase boundaries (via SendMessage) and fields escalations. The words caller, main session, coordinating agent, and coordinator all refer to this one actor in different moments.
• tech-lead — a distinct in-team member (when composed) that coordinates task execution within the team's autonomy boundaries. It does NOT own formation or cross-team decisions — those stay with the orchestrator.

Communication model (mailbox). Spawning a named agent creates a persistent teammate that goes idle and is re-woken by SendMessage with its context intact — there is no synchronous return value; members reply by SendMessage to the lead. An agent idles until a message arrives, acts on it, then idles again. (Verified in-harness: a member re-messaged after going idle replied and correctly recalled its earlier turn.)

State directory. All persistent state lives under ~/.claude/teams-state/:

• ~/.claude/teams-state/<team-slug>.json — team registry (one file per formed team)
• ~/.claude/teams-state/<team-slug>.log.jsonl — event log (append-only)
• ~/.claude/teams-state/<team-slug>.design.md — the architect's design doc (the durable single source of design truth that teammates read for clarification)
• ~/.claude/teams-state/patterns/formation-<type>.jsonl — formation pattern history (one JSON record per past formation: {composition, verdict, date, task_group_ref, planned_vs_actual})
• ~/.claude/teams-state/patterns/review-<domain>.jsonl — review pattern history

Create directories on first write. A missing pattern file is not an error — it means "no historical patterns", and the relevant cascade step falls through.

Spawn-in-two-waves, everything-upfront principle. Wave 0 spawns the architect/planner alone; it designs the work and composes the rest of the team (see Phase 0). Wave 1 then spawns every remaining role in a single batch, before execution unblocks. Each teammate reads its brief, acknowledges, and goes idle; the coordinator wakes each at its phase boundary via SendMessage, and any teammate may wake the architect for clarification. These two waves are the ONLY staging — within wave 1, lazy per-phase spawning is still forbidden: it leads to late phases with absent roles and inconsistent briefs. Writing all wave-1 briefs in a single batch forces reconciling role boundaries, downstream expectations, and scope in one pass — lazy spawning produces role drift.

Planner-first, MAX-pinned pivots. Two roles are pinned to the MAX tier (the most capable model + an Ultrathink — use maximum thinking. prefix — see Model tiers below), overriding the Cost framing budget guidance: the architect/planner and the verification roles — both lenses, code-reviewer (static) and qa-tester (behavioural), whenever present. Rationale: planning decisions shape every downstream brief, and verification is the last line of defense — quality at these points compounds across the whole engagement, so they get maximum reasoning regardless of cost. The architect/planner is additionally spawned in a first wave, before the rest of the team, because its output composes the team — and an independent MAX-tier plan-reviewer gates that plan before wave 1 (see the Adversarial Plan-Review Gate). Do not down-tier these roles to save cost.

Explicit-per-role-model mandate. Every spawn names a pinned model tier (haiku / sonnet / the top tier via the Agent tool's model param — the top tier resolves to the most capable model available, opus today; see Model tiers) — never omitted, never inherit, never an implicit default. An omitted model inherits the orchestrator's model and carries no cost intent, which compounds per-teammate cost across a multi-member team. A closed session at ~14B sub-agent tokens across 30 engagements is the cost shape this rule prevents. The spawn batch aborts if any role lacks an assigned model tier. MAX-tier spawns additionally pass effort="max" (see Model tiers); the opt-in --fable flag swaps the top-tier model to fable (see Top-tier model).