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

Map the dependency graph first, identify which tasks can run in parallel
Launch parallel coders for independent tasks (Wave 1: e.g. 3 agents on independent files)
After each wave completes: verify compilation on main worktree (cargo check), then launch next wave
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

Create team + all tasks with dependencies
Map dependency graph into waves
Launch Wave N coders in parallel (worktree isolation)
Wait for completion + verify compilation
Shut down completed agents immediately (do not batch)
Launch reviewer for completed wave's files
Apply review fixes directly
Launch Wave N+1
Repeat steps 3–8 until all waves done
Final comprehensive review across all files
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)

5.3 KiB Raw Blame History Unescape Escape