epic: Claude Code Agent Teams integration — transform ZERG into a higher-level orchestration framework

[rocklambros]

Epic: Agent Teams Integration

Vision

ZERG evolves from a standalone parallel execution system into a higher-level orchestration framework that uses Claude Code Agent Teams as one of its execution runtimes — while preserving subprocess and container modes for headless/CI scenarios.

Agent Teams = low-level runtime (spawn, communicate, coordinate)
ZERG = application framework (task decomposition, context optimization, architectural guardrails, workflow orchestration, multi-mode execution)

Key Insight

Agent Teams uses the same Claude Code Task system (TaskCreate/TaskUpdate/TaskList/TaskGet) that ZERG already mandates as its source of truth. They are architecturally aligned by design.

ZERG's Unique Value Over Raw Agent Teams

Capability	Agent Teams Alone	ZERG + Agent Teams
Task decomposition	Manual	Automated from specs via /zerg:design
Context optimization	Full CLAUDE.md per teammate	Task-scoped 4000-token spawn prompts
Architectural guardrails	None	File ownership, plan approval, quality gates
Workflow orchestration	Ad-hoc	plan → design → execute → merge → verify
Multi-mode execution	Interactive only	Interactive + headless + container + CI/CD
Crash recovery	No session resumption	Spec-as-memory, stateless workers, resume from task state
Quality gates	Hooks only	Hooks + level gates + verification commands + gate caching

Phased Roadmap

Phase 1: Foundation

• feat: AgentTeamLauncher — new execution backend for Claude Code Agent Teams #167 — AgentTeamLauncher: new --mode team execution backend

Phase 2: Hook Integration

• feat: TaskCompleted hook — per-task quality gates with self-healing workers #168 — TaskCompleted hook: per-task quality gates (self-healing workers)
• feat: TeammateIdle hook — automatic work redistribution with context preservation #169 — TeammateIdle hook: automatic work redistribution (context preservation)

Phase 3: Guardrails

• feat: per-worker plan approval — architectural consistency before code is written #170 — Plan approval: per-worker architectural consistency checks

Phase 4: Throughput

• feat: fine-grained dependency DAG execution — break rigid level barriers #171 — DAG execution: fine-grained dependency resolution (20-40% faster)

Phase 5: Communication & New Commands

• feat: inter-agent communication channels — structured messaging between workers #172 — Inter-agent communication channels
• feat: new commands — /zerg:debate, /zerg:pair, enhanced review & debug #173 — New commands: /zerg:debate, /zerg:pair, enhanced review & debug
• feat: spawn prompt optimization via context engineering for Agent Teams #174 — Spawn prompt optimization via context engineering
• feat: live observability dashboard — real-time worker visibility via Agent Teams display #175 — Live observability dashboard
• feat: delegate mode for orchestrator lead — pure coordination, no code writing #176 — Delegate mode for orchestrator lead

Dependency Graph

#167 AgentTeamLauncher (FOUNDATION)
 ├──→ #168 TaskCompleted Hook
 │     └──→ #171 DAG Execution
 ├──→ #169 TeammateIdle Hook
 ├──→ #170 Plan Approval
 ├──→ #172 Inter-Agent Communication
 │     └──→ #173 New Commands (debate, pair, review, debug)
 ├──→ #174 Spawn Prompt Optimization
 ├──→ #175 Live Dashboard
 └──→ #176 Delegate Mode

Critical Constraint

--mode subprocess and --mode container remain completely unchanged throughout all phases. Agent Teams mode is opt-in, never default.

Spawning Architecture Decision (Resolved)

Decision: ZERG will programmatically spawn Agent Teams teammates from Python code — not via natural language prompts to a lead agent.

This means AgentTeamLauncher (#167) will use the Agent Teams SDK/API to directly create, configure, and manage teammate processes. This gives ZERG full control over:

• Worker lifecycle (spawn, monitor, terminate)
• Spawn prompt injection (task-scoped context, file ownership, verification commands)
• Concurrency limits and level-gated execution
• Error handling and retry logic

This is consistent with how SubprocessLauncher and ContainerLauncher already work — ZERG's Python orchestrator drives the execution, not a conversational agent.

Implementation Hold

This epic is on hold until Claude Code Agent Teams exits experimental status. Currently requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and the API surface may change. Implementation will begin once Agent Teams reaches GA (general availability) with a stable programmatic spawning API.

All existing execution modes (--mode task, --mode subprocess, --mode container) remain fully functional and actively maintained in the interim.

Source

Full brainstorm analysis: /Users/klambros/.claude/plans/drifting-beaming-pinwheel.md
Sequential thinking analysis: 13 dimensions across worker spawning, inter-agent communication, task coordination, context engineering, quality gates, plan approval, display/observability, new commands, migration strategy, and risk assessment.