---
id: 0e484de1-cb92-479c-95ec-06fa9e886c0c
type: procedure
title: "Agent Team Operational Playbook: Wave-Based Parallel Implementation with Code Review"
tags: [claude-code, swarm, agent-teams, orchestrator, code-review, procedure, lessons-learned, rust, sba-scout]
importance: 0.8
confidence: 0.8
created: "2026-02-28T05:06:14.591287+00:00"
updated: "2026-02-28T05:06:41.138617+00:00"
relations:
  - target: 3ecd877b-de73-4afd-b328-b3ee99f5a1e3
    type: BUILDS_ON
    direction: outgoing
    strength: 0.95
    edge_id: 91e7a65f-ba4f-4533-b9b6-b9d732762490
  - target: 99f4462b-91eb-4243-99cf-7a74a3afadbf
    type: BUILDS_ON
    direction: outgoing
    strength: 0.9
    edge_id: 129677be-d2fe-45f2-a69c-b1340256d48c
  - target: 4dc83eed-b0b1-4924-b82e-faf352426785
    type: FOLLOWS
    direction: outgoing
    strength: 0.9
    edge_id: c32c4588-17b5-4f00-8d59-37bf89c6f6be
  - target: 3227a923-84c4-4fe3-8574-dbf74d6e8b37
    type: BUILDS_ON
    direction: outgoing
    strength: 0.85
    edge_id: 173a8645-ab54-4247-822b-9fb9e2ca23fd
  - target: 4dfc5003-44f8-4520-8cfc-dc6d6ef9a65f
    type: REQUIRES
    direction: outgoing
    strength: 0.8
    edge_id: 600e028b-6ee2-4413-b35c-220d210fb8fd
  - target: 27a1f728-ec90-469c-a6ab-5644d333322f
    type: RELATED_TO
    direction: outgoing
    strength: 0.7
    edge_id: 67fc682d-2b46-43c8-b950-bd80147e0056
  - target: c9add129-283a-445a-8dff-4525ec7fa9b6
    type: FOLLOWS
    direction: outgoing
    strength: 0.8
    edge_id: 10efe7b8-fe41-4e80-8733-e65add502655
---

# Agent Team Operational Playbook: Wave-Based Parallel Implementation with Code Review

Detailed operational lessons from running a 7-task Rust implementation with agent teams (Phase 2 of SBA Scout rewrite). This captures what worked, what didn't, and specific patterns to follow.

## Preconditions
- Detailed task specs written up with file paths and reference code
- Dependency graph between tasks already mapped
- Enough tmux pane slots for parallel agents (check before launching)

## Postconditions
- All code compiles (`cargo check` or equivalent passes)
- Tests pass
- All review findings addressed
- Team cleaned up (TeamDelete)

## Team Setup

- Use `TeamCreate` to create the team, then `TaskCreate` for all tasks upfront with full dependency chains (`TaskUpdate addBlockedBy`)
- **Task descriptions must be extremely detailed**: include exact file paths, column mappings, reference files to read, expected function signatures
- Agents that got detailed specs produced compiling code on first try with zero clarification needed
- Use `isolation: "worktree"` for all coders so they work on independent copies

## Wave Execution Pattern

1. Map the dependency graph first, identify which tasks can run in parallel
2. Launch parallel coders for independent tasks (Wave 1: e.g. 3 agents on independent files)
3. After each wave completes: verify compilation on main worktree (`cargo check`), then launch next wave
4. Worktree changes auto-merge back to the working directory when agents complete

## Pane Limit Management (CRITICAL)

- Hit "no space for new pane" error when trying to launch an agent with 6 idle agents still alive
- **Solution: Send `shutdown_request` to ALL completed agents IMMEDIATELY after their task is done — do not let them idle**
- Do not wait for batch shutdown — shut down each agent as soon as you confirm their task is complete
- The idle notification spam from completed agents is noise — ignore it, just send `shutdown_request`

## Code Review Pattern That Worked

- Launch reviewer agents (`swarm-reviewer` type) after each wave or at the end
- Provide explicit review checklists in the prompt: list every field mapping, every edge case, every cross-reference file
- The reviewer caught 2 real bugs that would have caused runtime issues in the Phase 2 run:
  1. Missing `#[serde(default)]` on 8 `TeamData` fields — would cause deserialization panics if API omits optional fields
  2. Dead `ApiError::Parse` variant — `response.json()` returns `reqwest::Error` not `serde_json::Error`, so the `Parse` variant was unreachable
- Also caught: `import_all_cards` hard-failing on first missing CSV (should try both card types independently)
- **Apply fixes yourself (team lead) rather than sending back to coders** — faster for small mechanical fixes

## Full Step-by-Step

1. Create team + all tasks with dependencies
2. Map dependency graph into waves
3. Launch Wave N coders in parallel (worktree isolation)
4. Wait for completion + verify compilation
5. Shut down completed agents immediately (do not batch)
6. Launch reviewer for completed wave's files
7. Apply review fixes directly
8. Launch Wave N+1
9. Repeat steps 3–8 until all waves done
10. Final comprehensive review across all files
11. Clean up team (TeamDelete)

## What to Improve Next Time

- Shut down agents between waves, not in batches at the end
- Could run final review in parallel with later-wave coders if the review only covers earlier-wave files
- For tasks that produce very similar code (e.g. batter importer vs pitcher importer), consider having one coder do both sequentially instead of two coders — avoids code style divergence
- Agent model: sonnet for both coders and reviewers (cost-effective, reliable for implementation tasks)

## Context
Validated on: SBA Scout Rust rewrite Phase 2 (7 tasks: API client, sync orchestrator, batter importer, pitcher importer, team importer, transaction importer, query layer)