Agent Teams Manager

Agent Teams Manager

Philosophy: Hybrid approach - Agent Teams for research/discussion phases, Parallel Workers for implementation phases.

Quick Start

Example (orchestrator auto-selects strategy):

# Phase 1 (Discovery) - Auto-selects Agent Teams
strategy = select_strategy(phase=1, complexity=2, task_count=3)
# Returns: "agent_teams" (research benefits from discussion)

# Phase 6 (Implementation) - Auto-selects Parallel Workers
strategy = select_strategy(phase=6, complexity=2, task_count=3)
# Returns: "parallel_workers" (isolation prevents conflicts)

When to Use This Skill

Use this skill when:

• Orchestrator needs to parallelize work across multiple agents
• Phase 1, 2, 3, or 6 with 2+ concurrent tasks
• Research/architecture discussions benefit from real-time collaboration
• Debugging with competing hypotheses (Agent Teams enables debate)
• Code reviews requiring multiple specialized perspectives

DO NOT use when:

• Single-agent sequential execution is sufficient
• Phase 6 (Implementation) editing same files (use parallel-workers instead)
• Token budget is critical (Agent Teams uses 3x tokens)
• Feature flag agent_teams is disabled

Core Workflows

Workflow 1: Strategy Selection (Auto)

Use when: Orchestrator needs to decide parallelization approach

Steps:

1. Read .claude/settings.json → Check sdlc.feature_flags.agent_teams
2. If agent_teams: false → Return "parallel_workers" (only option)
3. If agent_teams: true:
   • Check current phase number
   • Check complexity level (0-3)
   • Check task count
   • Check task characteristics (research vs implementation)
4. Apply strategy selection logic:
   • Phase 1, 2, 3, 6 AND research/review → "agent_teams"
   • Phase 6 (Implementation) AND file editing → "parallel_workers"
   • Task count < 2 → "sequential"
   • Token budget exhausted → "sequential"
5. Log decision with rationale

Strategy Selection Logic:

IF agent_teams flag is disabled:
  RETURN "parallel_workers" (fallback)

IF phase in [1, 2, 3, 6] AND task_type in ["research", "review", "architecture"]:
  RETURN "agent_teams"  # Discussion benefits from real-time collaboration

IF phase == 6 AND task_type == "implementation":
  RETURN "parallel_workers"  # File isolation prevents conflicts

IF task_count < 2:
  RETURN "sequential"  # No parallelization needed

ELSE:
  RETURN "sequential"  # Conservative default

Example:

# Phase 1 (Discovery): 3 domain-researcher tasks
- Current phase: 1
- Task type: research
- Task count: 3
→ Decision: "agent_teams" (research benefits from discussion)

# Phase 6 (Implementation): 4 code-author tasks
- Current phase: 6
- Task type: implementation
- Task count: 4
→ Decision: "parallel_workers" (file isolation required)

# Phase 3 (Architecture): 2 architects debating
- Current phase: 3
- Task type: architecture
- Task count: 2
→ Decision: "agent_teams" (architecture requires trade-off debate)

Common Issues:

• Problem: Agent Teams not available (experimental flag not set)
• Solution: Fallback to parallel_workers or sequential. Log warning.

Workflow 2: Create Agent Team

Use when: Strategy selection returned "agent_teams"

Steps:

1. Validate prerequisites:
   • CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in environment
   • Team name is unique (check ~/.claude/teams/)
   • Phase is in allowed list ([1, 2, 3, 6])
2. Define team structure:
   • Lead agent (coordinates, synthesizes, makes decisions)
   • Teammate agents (execute tasks, provide perspectives)
   • Shared task list
3. Create team configuration:

   claude team create {team-name} \
     --lead {lead-agent} \
     --teammates {agent1},{agent2},{agent3}
   

4. Assign tasks to teammates:

   # Each teammate claims tasks from shared list
   claude team assign {team-name} {teammate} {task-id}
   

5. Monitor team progress:
   • Check task statuses
   • Watch for blockers
   • Facilitate messaging if needed
6. Synthesize results:
   • Lead agent collects teammate outputs
   • Creates final deliverable
   • Commits to git

Example:

# Phase 1 (Discovery): Research Kafka best practices
1. Create team:
   - Lead: domain-researcher (coordinates)
   - Teammate 1: doc-crawler (searches official docs)
   - Teammate 2: domain-researcher-2 (searches patterns)
   - Teammate 3: rag-curator (indexes findings)

2. Assign tasks:
   - doc-crawler → "Fetch Kafka official documentation"
   - domain-researcher-2 → "Research Kafka patterns in corpus"
   - rag-curator → "Index findings for future queries"

3. Teammates message each other:
   - doc-crawler: "Found Kafka Streams API docs"
   - domain-researcher-2: "Event Sourcing pattern common"
   - Lead synthesizes: "Kafka Streams + Event Sourcing recommended"

4. Lead commits decision as ADR

Common Issues:

• Problem: Experimental flag not set → Team creation fails

• Solution: Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, warn user

• Problem: Teammates editing same file → Merge conflicts

• Solution: Detect file collision, switch to parallel_workers strategy

Workflow 3: Spawn Parallel Workers

Use when: Strategy selection returned "parallel_workers"

Steps:

1. Delegate to parallel-workers skill:
   • Read tasks from Phase 5 (Planning) output
   • Create git worktrees for isolation
   • Spawn workers with assigned tasks
   • Monitor PR creation
   • Run automation loop
2. Wait for workers to complete
3. Merge PRs through gate-evaluator

Example:

# Phase 6 (Implementation): 3 parallel tasks
1. Call parallel-workers skill:
   /parallel-spawn --batch tasks.yml

2. Workers execute in isolation:
   - Worker 1: Implements authentication
   - Worker 2: Implements payment gateway
   - Worker 3: Writes integration tests

3. PRs created automatically
4. Security gate validates before merge

Common Issues:

• Problem: Disk space exhausted (worktrees use disk)
• Solution: Cleanup old worktrees, reduce max_workers

Workflow 4: Fallback to Sequential

Use when: Strategy selection returned "sequential"

Steps:

1. Log reason for sequential execution:
   • Task count too small (< 2)
   • Token budget exhausted
   • Feature flags disabled
2. Execute tasks one by one:
   • Call agent for task 1
   • Wait for completion
   • Call agent for task 2
   • Repeat
3. Commit after all tasks complete

Example:

# Single research task - no parallelization needed
1. Strategy: "sequential" (task_count=1)
2. Execute: domain-researcher researches Kafka
3. Commit: ADR created

Strategy Selection Reference

Phase-Specific Recommendations

Task Type Detection

Research Tasks (Agent Teams preferred):

• Keywords: "research", "explore", "investigate", "analyze", "compare"
• Agents: domain-researcher, doc-crawler, rag-curator
• Output: Documentation, ADRs, learnings

Implementation Tasks (Parallel Workers preferred):

• Keywords: "implement", "code", "write", "build", "develop"
• Agents: code-author, test-author, iac-engineer
• Output: Source code, tests, infrastructure

Review Tasks (Agent Teams preferred):

• Keywords: "review", "audit", "validate", "assess", "evaluate"
• Agents: code-reviewer, qa-analyst, security-scanner
• Output: Reports, findings, recommendations

Token Budget Considerations

Configuration

Feature Flag (.claude/settings.json)

{
  "sdlc": {
    "feature_flags": {
      "agent_teams": false  // Experimental - disable by default
    },
    "parallelization": {
      "strategies": {
        "parallel_workers": {
          "enabled": true,
          "phases": [6],
          "max_workers": 5
        },
        "agent_teams": {
          "enabled": false,  // Follows feature_flags.agent_teams
          "phases": [1, 2, 3, 6],
          "token_budget_multiplier": 3.0
        }
      },
      "strategy_selection": "auto"  // or "manual"
    }
  }
}

Environment Variables

To enable Agent Teams:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Integration

With Other Skills

• parallel-workers: Fallback when Agent Teams unavailable or inappropriate
• gate-evaluator: Validates outputs from both strategies
• phase-commit: Commits results after parallelization completes
• rag-curator: Indexes learnings from Agent Team discussions

With Agents

• orchestrator (Phase 0-9): Primary consumer - calls this skill for parallelization decisions
• delivery-planner (Phase 5): Generates task lists consumed by parallelization strategies
• system-architect (Phase 3): Uses Agent Teams for architecture debates

Troubleshooting

Common Issues

Issue: Agent Teams feature not available

Solution:

# Check environment variable
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

# Should output: 1
# If not, enable:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Issue: High token usage with Agent Teams

Solution:

• Monitor token budget: /token-status
• Reduce teammate count (max 3 recommended)
• Switch to parallel_workers for implementation
• Disable agent_teams flag if budget critical

Issue: Team status shows "lag" or stale data

Solution:

# Manually refresh task list
claude team refresh {team-name}

# Check teammate status
claude team status {team-name}

Issue: Teammates editing same file → Merge conflicts

Solution:

• Prevention: Use parallel_workers for implementation (isolates files)
• Detection: Monitor file paths in tasks, warn if overlap detected
• Recovery: Coordinate manual merge or reassign tasks

Examples

Example 1: Phase 1 Discovery with Agent Teams

Scenario: Research Kafka for new event-driven architecture

Input:

phase: 1
complexity: 2
tasks:
  - "Research Kafka official documentation"
  - "Find Kafka patterns in corpus"
  - "Index Kafka learnings for future use"

Process:

1. Read settings → agent_teams enabled
2. Detect: Phase 1, research tasks, 3 tasks
3. Strategy: "agent_teams" (research benefits from discussion)
4. Create team:
   - Lead: domain-researcher
   - Teammates: doc-crawler, rag-curator
5. Teammates work in parallel:
   - doc-crawler fetches official docs
   - rag-curator searches corpus
   - Lead synthesizes findings
6. Team discusses via messaging
7. Lead creates ADR with recommendations
8. Commit to git

Output:

ADR-015: Adopt Kafka for Event-Driven Architecture
- Kafka Streams API for event processing
- Event Sourcing pattern recommended
- Indexed 15 Kafka patterns in corpus

Example 2: Phase 6 Implementation with Parallel Workers

Scenario: Implement 3 microservices concurrently

Input:

phase: 6
complexity: 2
tasks:
  - "Implement authentication service"
  - "Implement payment gateway"
  - "Write integration tests"

Process:

1. Read settings → agent_teams enabled
2. Detect: Phase 6, implementation tasks, 3 tasks, file editing
3. Strategy: "parallel_workers" (file isolation required)
4. Delegate to parallel-workers skill
5. Workers execute in isolated worktrees
6. PRs created automatically
7. Security gate validates
8. Merge to main

Output:

3 PRs created:
- PR #42: feat(auth): Add authentication service
- PR #43: feat(payment): Add payment gateway integration
- PR #44: test(integration): Add E2E tests

All passed security gate, merged to main.

Example 3: Fallback to Sequential

Scenario: Single architecture task, no parallelization needed

Input:

phase: 3
complexity: 1
tasks:
  - "Create ADR for database selection"

Process:

1. Read settings → agent_teams enabled
2. Detect: Phase 3, 1 task
3. Strategy: "sequential" (task_count < 2, no parallelization needed)
4. Execute: system-architect creates ADR
5. Commit to git

Output:

ADR-016: Use PostgreSQL for Relational Data
- Single task, no parallelization overhead
- Completed in 5 minutes

Anti-Patterns to Avoid

❌ DON'T:

• Use Agent Teams for Phase 6 implementation (file conflicts)
• Enable Agent Teams when token budget < 50k
• Create teams for single-task scenarios
• Hardcode strategy selection (use auto-detection)

✅ DO:

• Use hybrid approach (teams for research, workers for code)
• Monitor token usage with Agent Teams
• Fallback to parallel_workers when teams unavailable
• Log strategy selection rationale

Skill maintained by: SDLC Agêntico Core Team Last updated: 2026-02-10 Related: ADR-018 (Agent Teams vs Parallel Workers)