tomevault-io 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.
Source: tidepool-heavy-industries/exomonad — distributed by TomeVault.