epic: migrate workaround orchestration patterns to native Claude Agent Teams

[JacobPEvans]

Summary

Claude Code now supports Agent Teams (experimental) - a native multi-agent coordination feature that enables peer-to-peer messaging, shared task lists, and autonomous team coordination. This epic tracks the migration of existing workaround patterns in this repo to leverage Agent Teams with Opus 4.6.

Background

This repo currently implements several workaround patterns that simulate multi-agent coordination:

1. Command→Agent→Skill architecture (codeql-resolver) - Hierarchical dispatch with batching, no inter-agent communication
2. Orchestrator philosophy (CLAUDE.md) - Manual delegation patterns using subagents
3. Phase-based workflows (git-rebase-workflow) - Sequential state machines with no parallelization
4. Hook-based gating (5 plugins) - Independent pre/post tool use filtering with no coordination

Agent Teams provides native solutions for many of these patterns through:

• TeammateTool API: spawnTeam, write, broadcast, requestShutdown, approvePlan/rejectPlan
• Shared task list: Dependencies, self-claiming, status tracking
• Delegate mode: Lead focuses on orchestration only
• Plan approval: Teammates plan before implementing, lead reviews

Feature Flag

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Migration Areas (Child Issues)

• feat: create agent-teams-orchestrator plugin with team lifecycle management #15 - Create agent-teams-orchestrator plugin (foundational)
• feat: migrate codeql-resolver to Agent Teams with peer-to-peer coordination #16 - Migrate codeql-resolver to Agent Teams
• feat: create team-based parallel PR review plugin #17 - Create team-based parallel PR review plugin
• feat: create team-based multi-repo sync and CI fix plugin #18 - Create team-based multi-repo sync plugin
• feat: update CLAUDE.md orchestrator philosophy for Agent Teams era #19 - Update CLAUDE.md orchestrator patterns
• feat: create agent-teams-guard hook plugin for team safety #20 - Create agent-teams-guard hook plugin
• feat: create team-templates skill with reusable team configurations #21 - Create team templates skill

Dependency Graph

#15 (orchestrator) ← foundational, all others depend on this
├── #21 (templates) ← defines reusable team patterns
├── #16 (codeql migration) ← uses orchestrator + templates
├── #17 (PR review) ← uses orchestrator + templates
├── #18 (multi-repo ops) ← uses orchestrator + templates
├── #20 (guard hooks) ← uses orchestrator config format
└── #19 (CLAUDE.md update) ← references all new commands

Implementation Order

1. Phase 1: feat: create agent-teams-orchestrator plugin with team lifecycle management #15 (orchestrator) + feat: create team-templates skill with reusable team configurations #21 (templates) - Foundation
2. Phase 2: feat: create agent-teams-guard hook plugin for team safety #20 (guard hooks) - Safety first
3. Phase 3: feat: create team-based parallel PR review plugin #17 (PR review) - Lowest risk, best for learning
4. Phase 4: feat: migrate codeql-resolver to Agent Teams with peer-to-peer coordination #16 (codeql migration) - Most complex migration
5. Phase 5: feat: create team-based multi-repo sync and CI fix plugin #18 (multi-repo ops) - Cross-repo coordination
6. Phase 6: feat: update CLAUDE.md orchestrator philosophy for Agent Teams era #19 (CLAUDE.md update) - Documentation after all plugins exist

Key Decisions

• Experimental flag: Agent Teams is experimental. All new plugins must gracefully degrade when the flag is disabled
• Token costs: Agent Teams uses significantly more tokens (N teammates = ~Nx cost). Document cost tradeoffs
• Model routing: Use Opus 4.6 for lead, Sonnet 4.5 for most teammates, Haiku 4.5 for simple tasks
• Display mode: Default to in-process; document tmux setup as optional

Workaround Pattern → Agent Teams Mapping

Current Workaround	Location	Agent Teams Replacement
Command→Agent batching (max 5)	codeql-resolver	Shared task list + self-claiming teammates
One-way agent communication	codeql-resolver	Peer-to-peer write/broadcast messaging
Sequential subagent dispatch	CLAUDE.md orchestrator	Parallel teammate spawning
Manual result aggregation	All commands	Lead synthesizes via teammate messages
No cross-checking between agents	codeql-resolver	Verifier teammate + inter-agent debate
Serial multi-repo operations	ready-player-one, sync-main	Per-repo teammate parallelism
Sequential PR review perspectives	review-pr, review-code	Multi-perspective review team
Phase-based sequential workflow	git-rebase-workflow	Parallel pre-validation + post-cleanup
No agent-to-agent escalation	All	Direct teammate messaging for help

References

• Official Agent Teams docs
• TeammateTool system prompt
• Building a C compiler with agent teams
• Claude Opus 4.6 announcement
• Agent SDK overview