Refactor parallel dispatch to use Claude Code agent teams (Wave 4 of #202)
kind: infra
Goal
Refactor /issue and /adversarial-planner to use Claude Code's native agent-team primitives (TeamCreate, TeamDelete, Agent() with team_name) for phases that benefit from parallel dispatch.
Parent: #202 (Workflow optimizations — Waves 1-3 landed in PR #217)
Background
This is Wave 4 / PR-H from the #202 plan. It was intentionally deferred because:
- Agent teams are experimental (
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) - It's the highest-risk item (touches core orchestrator)
- It depends on Waves 1-3 landing first (especially PR-E parallel critics and PR-F/G SKILL.md flow changes)
Design decisions (from #202 plan, approved)
- Teams only for parallel phases. Sequential phases (planner, experimenter, reviewer) keep direct
Agent()calls. Teams add value only where 2+ agents run concurrently. - Marker comments remain primary state. Teams are ephemeral (die with the session); markers are durable (survive across sessions). No migration of state from markers to team context.
- Teams created per invocation, not persistent. Since teams don't survive session boundaries, each
/issue <N>invocation creates a fresh team if needed for the current phase. isolation: "worktree"replaces manualgit worktree addfor implementer dispatch in Step 4a.
Phases that benefit from teams
| Phase | Current | With teams |
|---|---|---|
/adversarial-planner Phase 2 | 3 parallel Agent() critics (from PR-E) | 3 critic teammates in a team |
/issue Step 9a | Sequential analyzer → interpretation-critic | Potentially parallelizable |
Fallback design (required)
If the teams API is too limited (idle/wake management too complex, limitations block us):
- Fall back to 3
Agent()calls withrun_in_background: true - Feature flag:
USE_AGENT_TEAMS=truein the skill so it can be reverted without touching the rest of the flow
Known API limitations (from docs)
- No session resumption with in-process teammates
- Task status can lag
- No nested teams
- One team per session
- Lead is fixed
- Teammates go idle after every turn (need explicit SendMessage to wake)
Acceptance criteria
-
/adversarial-plannerPhase 2 runs 3 critics via a team (or fallback) on a test task -
/issueStep 4a usesisolation: "worktree"instead of manualgit worktree add - Feature flag allows reverting to non-team dispatch
- Dry-run on a synthetic issue completes full lifecycle
- All existing tests pass
- Documented in SKILL.md with the new flow
Compute
0 GPU-hours. Pure infra work.
Estimate
8-12 hours (multi-day). Develop in a worktree.
Timeline · 0 events
No events recorded.
Comments · 0
No comments yet. (Auth + comment composer land in step 5.)