117 lines
5.3 KiB
Markdown
117 lines
5.3 KiB
Markdown
---
|
||
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)
|