| name | tl-subagent-dispatch |
| description | Use when spawning subagents, monitoring their progress, or intervening when stuck. Covers worktree creation, human oversight patterns, and completion protocol. |
Tech Lead Subagent Dispatch
Core Principles
-
Fire-and-forget execution. TL decomposes, specs, spawns, and idles. Convergence is leaf + Copilot + event handlers, not TL.
-
Dispatch is heterogeneous. Claude for decomposition, Gemini for implementation, Copilot for review.
Agent Types
| Tool | Agent | Role | Use When |
|---|
fork_wave | Claude | TL (can spawn children) | Multi-step work requiring sub-decomposition |
spawn_gemini (worktree) | Gemini | Dev (files PR) | Focused implementation in isolated worktree |
spawn_gemini (inline) | Gemini | Worker (ephemeral) | Investigation, hypothesis testing, no commits |
Dispatch Protocol
1. Write the Spec
Every spec follows this structure:
1. ANTI-PATTERNS — Known failure modes as "DO NOT" rules (FIRST)
2. READ FIRST — Exact files to read (CLAUDE.md, source files)
3. STEPS — Numbered, each step = one concrete action
4. VERIFY — Exact build/test commands
5. DONE CRITERIA — What "done" looks like
2. Spawn
# Focused implementation (own branch, files PR)
spawn_gemini(
name="feature-name",
task="[full spec here]",
isolation="worktree"
)
# Investigation (ephemeral panes, no branch)
spawn_gemini(name="h1", task="Check if X causes the bug", isolation="inline")
spawn_gemini(name="h2", task="Check if Y causes the bug", isolation="inline")
3. Return Immediately
After spawning, idle. Do not watch, poll, or narrate.
Convergence Flow
- Leaf works → commits → files PR via
file_pr
- Copilot reviews automatically (first review only)
- If Copilot posts comments → event handler injects into leaf's pane → leaf fixes → pushes
- Event handler fires
[FIXES PUSHED] to TL (Copilot does NOT re-review)
- TL merges if CI passes
Alternative paths:
- Copilot approves first time →
[PR READY] → TL merges
- No Copilot review →
[REVIEW TIMEOUT] after 15min (5min after addressing changes) → TL merges if CI passes
- Leaf fails →
[FAILED: agent-id] → TL re-decomposes
When TL Gets Notified
| Message | Source | Action |
|---|
[FIXES PUSHED] | Event handler | Merge if CI passes |
[PR READY] | Event handler | Merge |
[REVIEW TIMEOUT] | Event handler | Merge if CI passes |
[from: agent-id] | Agent message | Read, do not auto-merge |
[FAILED: agent-id] | Agent failure | Re-decompose or escalate |
Spec Anti-Patterns (Front-Load These)
| Known Failure Mode | Anti-Pattern Rule |
|---|
| Adds unnecessary dependencies | "ZERO external dependencies" |
| Invents escape hatches | "No todo!(), Raw(String), Other(Box<dyn Any>)" |
| Writes thinking-out-loud comments | "No stream-of-consciousness comments" |
| Renames types/variants | "Use EXACT type signatures below" |
| Makes architectural decisions | "Do not change the module structure" |
Uses git add . | "Always git add specific files by name" |
| Shells out to nonexistent CLIs | "Use MCP tools, NOT bash commands for notify_parent" |
| Corrupts Haskell pragmas | "Closing delimiter is #-} not #}" |
Anti-Patterns (TL Behavior)
TL explores codebases
That exploration belongs in a worker's spec. Spawn a worker to investigate.
TL writes implementation code
That belongs in a leaf's task. Gemini agents are smart enough.
TL manually reviews intermediate output
Convergence is leaf + Copilot. TL only reviews at merge time.
TL iterates on a failing leaf
Escalation, not iteration. If leaf fails 3+ rounds, re-decompose with a different approach.
