arc-dispatching-teammates

name	arc-dispatching-teammates
description	Run epic-level parallel work via agent teammates while staying present to monitor. Use when dag.yaml has 2+ ready epics and you want a live team; for walk-away loops use arc-looping, for feature fan-out use arc-dispatching-parallel.
category	orchestration
status	promoted

arc-dispatching-teammates

Overview

Dispatch one Claude Code agent teammate per ready epic. Lead stays present, messages teammates via SendMessage, intervenes on blockers. Teammates implement inside isolated worktrees and merge back to a short-lived dev branch — intermediate noise (retries, fix-forward commits) is fine.

Core principle: Teammates are the arcforge-supported substrate for lead-present multi-epic parallelism. Manual "open N Claude windows" is a fallback, not the default. Don't pre-identify conflicts — let runtime handle runtime.

Platform note: This skill targets Claude Code's agent-teammates feature (SendMessage, team_name); other harnesses have no teammate substrate — use arc-looping (walk-away) or arc-executing-tasks (attended) for multi-epic work instead.

When to Use

Condition	Route to
2+ ready epics, lead staying present ("I'll watch", "step in if needed")	arc-dispatching-teammates (this skill)
2+ ready epics, lead walking away ("overnight", "going to bed")	arc-looping --pattern dag
1 ready epic	arc-coordinating expand + arc-implementing
Feature-level parallelism inside one worktree	arc-dispatching-parallel
No specs/<spec-id>/dag.yaml	arc-planning first

The boundary vs arc-looping is attendance, not risk. A risky epic with the lead watching is still teammates; a safe epic with the lead walking away is still arc-looping.

REQUIRED BACKGROUND: arc-using — call it if routing context is needed. REQUIRED PRECEDENT: arc-planning must have produced specs/<spec-id>/dag.yaml.

Preconditions

1. 2+ ready epics — arcforge status --json shows epics with status: pending, worktree: null, deps completed. If < 2, skill does not apply.
2. Single spec. Cross-spec ready epics → report blocked, user picks with --spec-id <id>.
3. Agent tool supports team_name and name. If dispatch errors with "unknown parameter team_name", report blocked.
4. Lead is in project root, not a worktree. Move to base worktree if .arcforge-epic is in cwd.
5. On a dev branch, not main/master. Teammates merge back to the lead's branch. If on main/master, create one first: git switch -c dispatch/<spec-id>-$(date +%Y-%m-%d). If the user named a branch, or the lead is already off the default, use that — never override an explicit choice.

Precondition failure = hard fail. Do not silently fall back to arc-looping or manual juggling.

Core Workflow

1. Identify ready epics. From arcforge status --json, collect every epic with status: pending and worktree: null. Call this set R.

2. Cap team size at 5 (default). If |R| > 5, take the first 5 as the initial team and queue the rest. ≤5 teammates is Anthropic's documented best practice; beyond 5 coordination overhead exceeds benefit. Honor a higher cap only when the user explicitly asks for one.

3. TeamCreate BEFORE any Agent dispatch. Use a descriptive name like dispatch-<project>-<timestamp>. Per Agent Teams docs, passing team_name to Agent does NOT auto-create — it triggers a state-sync bug.

4. Expand worktrees and dispatch teammates in parallel. For each epic in the initial 5:

   • : "${ARCFORGE_ROOT:=$HOME/.agents/arcforge}"; node "${ARCFORGE_ROOT}/scripts/cli.js" expand --epic <epic-id> from the project root — creates the canonical worktree and stamps .arcforge-epic. Per-epic, not batch.
   • Read the absolute worktree path from arcforge status --json; do not reconstruct it.
   • Dispatch via Agent with team_name=<team>, name=worker-<epic-id>, spawn prompt from references/spawn-prompt-template.md.

   Parallel, not sequential — documented good pattern. If some spawns fail with Failed to create teammate pane, you hit GH #40168; retry those sequentially. See references/tmux-timing-race.md.

5. Monitor. Stay present. Read mailbox periodically, answer questions via SendMessage, intervene on stuck teammates. On completion → Step 6. On acceptance → dispatch next queued epic if any (continuous, not waves).

6. Acceptance check (per teammate completion) — delegate, do NOT inline. The lead dispatches two subagents with fresh context; the lead does NOT locate code or run tests itself. When a teammate reports done:

   • Spec compliance — Agent(subagent_type='arcforge:spec-reviewer') with specs/<spec-id>/epics/<epic-id>/epic.md and its features/*.md attached (name in the prompt). It locates every acceptance criterion in the merged dev branch and returns PASS/FAIL with file:line evidence.

Spawn Prompt Template

Lives in references/spawn-prompt-template.md with three sections: Your Authority (autonomous end-to-end execution grant), Your Workspace (cd + invoke /arc-implementing), Coordination (SendMessage-only). Read that file before dispatching, fill in <epic-id> and <absolute-worktree-path>, paste into each Agent call. Teammate plain text is invisible to the lead — SendMessage is the only channel.

Red Flags

Rationalizations observed in baseline testing. If you catch yourself saying any of these, stop and re-check routing:

• "You become the coordinator, just open N Claude windows and tab between them." Papering over the gap. With this skill, the lead session is the coordinator via teammates — the user does not juggle windows.
• "Agent teammates are a generic Claude Code feature, not an arcforge pattern." They are an arcforge pattern now. Don't bucket them as external.
• "I'll use arc-looping since it handles dag parallelism." arc-looping is walk-away. Re-read the user's attendance signal.
• "arc-dispatching-parallel already covers this." No — that skill is feature-level inside one worktree. This is epic-level across worktrees.
• "Let me spawn 8 teammates since there are 8 ready epics." Cap at 5. Queue the rest. Continuous dispatch.
• "Worktrees already exist, so I'll just dispatch." Fine — skip the expand step for epics whose worktree is non-null. Do not re-expand.
• "I'm on main, dispatching from here is fine." No — teammates merge back to the lead's branch. Create a dev branch first (Precondition 5).
• "Parallel burst hit Failed to create teammate pane — downscale the team." No. You hit GH #40168. Retry the failed spawns sequentially. See references/tmux-timing-race.md.
• "I need to tell teammates which shared files to avoid." No. Let conflicts happen; arc-finishing escalates them via the Merge Conflict (Multi-Teammate) path. Static prediction is over-engineering.
• "Pin arcforge version inline: ARCFORGE_ROOT=... node "${ARCFORGE_ROOT}/scripts/cli.js"." POSIX footgun — "${VAR}" expands before the inline assignment, resolving to the old value. export ARCFORGE_ROOT=... on its own line first, then the blessed form.
• "I already know what this epic does — I'll skip the spec-reviewer and just map test names to ACs." This is the qmd baseline failure verbatim. The lead's prior context is precisely what makes inline acceptance unreliable. Always dispatch arcforge:spec-reviewer per Step 6; it has fresh context and cannot rationalize.
• "The teammate already ran tests green — running verifier is redundant." Same mistake. The verifier runs from an empty context; "redundant" is the rationalization that skips the gate. Dispatch arcforge:verifier per Step 6.
• "I'll close tmux panes manually later, skip TeamDelete." Without TeamDelete, panes orphan and the team's runtime state lingers across sessions. Step 8c is not optional.

Completion Formats

Dispatch ready (after Step 4 — initial spawn successful)

✅ Teammate dispatch: team ready
- Team: dispatch-<project>-<timestamp>
- Teammates spawned: 3 (worker-epic-auth, worker-epic-api, worker-epic-ui)
- Queued: 0
- Lead: monitoring via SendMessage, will run acceptance check per completion

Final Report (after Step 8 — session end)

Use this after every dispatched epic has reached a terminal state (accepted or permanently failed). This is the user-facing hand-off — they read this and decide what to do with the dev branch.

See references/wrap-up-sequence.md (§8a) for the full Final Report example.

Each accepted epic MUST show subagent evidence (spec-reviewer + verifier PASS). Missing = Step 6 was skipped. Failed epics show the last subagent FAIL and are NOT auto-cleaned. "Next actions" lists user options — you don't execute them.

Blocked Format

⚠️ Teammate dispatch: blocked
- Issue: <precondition that failed, e.g. only 1 ready epic, Agent team_name unsupported>
- Checked: <exact command or tool invocation>
- Action: <remediation — e.g. arc-coordinating for 1 epic, enable teammates, or fall back to arc-looping>

After This Skill

• Each teammate hands off to arc-finishing (Step 0 selects the epic path) as part of /arc-implementing.
• Lead session dispatches arcforge:spec-reviewer + arcforge:verifier per Step 6 on each completion; does NOT run arc-verifying inline.
• Blocked teammates → route to arc-debugging on the specific epics. Do not auto-retry.