Dispatcher

For every dispatch: start the watchdog first, then dispatch the agent, then poll for completion. The templates below show the complete pattern for each agent type.

Executor (writes code — worktree isolated, stale threshold: 300s):

bash .gitban/hooks/agent-watchdog.sh "{SPRINTTAG}-{cardid}-executor-{N}" 300 30 &

Agent(
  subagent_type="executor",
  description="{SPRINTTAG}-{cardid}-executor-{N}",
  isolation="worktree",
  run_in_background=true,
  prompt="Card ID: {cardid}\nSprint tag: {SPRINTTAG}"
)

Reviewer (reads code, writes review — main thread, stale threshold: 180s):

bash .gitban/hooks/agent-watchdog.sh "{SPRINTTAG}-{cardid}-reviewer-{N}" 180 30 &

Agent(
  subagent_type="reviewer",
  description="{SPRINTTAG}-{cardid}-reviewer-{N}",
  run_in_background=true,
  prompt="Card ID: {cardid}\nSprint tag: {SPRINTTAG}\nCommit: {commit_hash}\nReview number: {N}"
)

Router (reads review, routes instructions — main thread, stale threshold: 120s):

bash .gitban/hooks/agent-watchdog.sh "{SPRINTTAG}-{cardid}-router-{N}" 120 30 &

Agent(
  subagent_type="router",
  description="{SPRINTTAG}-{cardid}-router-{N}",
  run_in_background=true,
  prompt="Card ID: {cardid}\nSprint tag: {SPRINTTAG}\nReview number: {N}"
)

Close-out (checks off card, completes — main thread, stale threshold: 120s):

bash .gitban/hooks/agent-watchdog.sh "{SPRINTTAG}-{cardid}-closeout-{N}" 120 30 &

Agent(
  subagent_type="general-purpose",
  description="{SPRINTTAG}-{cardid}-closeout-{N}",
  run_in_background=true,
  prompt="Card ID: {cardid}\nSprint tag: {SPRINTTAG}\n\nRead the executor instructions at .gitban/agents/executor/inbox/{SPRINTTAG}-{cardid}-executor-{N}.md and follow them. Use the gitban MCP tools to check off remaining checkboxes and complete the card. Do not archive it."
)

Planner (captures tech debt, extends sprint — main thread, stale threshold: 180s):

bash .gitban/hooks/agent-watchdog.sh "{SPRINTTAG}-{cardid}-planner-{N}" 180 30 &

Agent(
  subagent_type="planner",
  description="{SPRINTTAG}-{cardid}-planner-{N}",
  run_in_background=true,
  prompt="Card ID: {cardid}\nSprint tag: {SPRINTTAG}\nReview number: {N}"
)

Parallel dispatch: When a batch has multiple cards, start all watchdogs first, then dispatch all agents in that batch in a single message with multiple Agent tool calls.

Statelessness: Every agent starts from scratch with no context beyond its prompt. Agents rely on their inbox files and card content for context — not on anything the dispatcher tells them. Do not include execution context, prior results, or summaries in agent prompts. The agent's own system prompt tells it to check its inbox.

Agent Liveness Monitoring

Agents can hang silently when they hit platform errors like [Tool result missing due to internal error]. The watchdog started before each dispatch (see templates above) monitors trace files in .gitban/agents/traces/ and writes .stale markers when an agent goes quiet past its threshold.

Polling loop

After dispatching a batch, poll every 30 seconds. A single check iteration handles all agents in the batch:

1. TaskOutput(task_id="{id}", block=false, timeout=5000) — check if the agent returned a result
2. Check for .stale marker files: ls .gitban/agents/traces/*{agent_short_id}*.stale 2>/dev/null
3. Check for error outbox files: ls .gitban/agents/{role}/inbox/*-ERROR.md 2>/dev/null

On completion

Agent returned a result via TaskOutput. Check for -ERROR.md files in the agent's outbox — an INTERNAL_ERROR return means the agent hit a platform error and wrote diagnostics. Log the result and proceed.

On stale detection

The watchdog wrote a .stale file. The agent is likely hung.

• Read the .stale file for diagnostics (last tool call, idle duration)
• Use TaskStop(task_id="{id}") to kill the hung agent
• Check for -ERROR.md files — the agent may have written partial results before dying
• Check for partial commits on the worktree branch (git log worktree-agent-{id})
• Log the failure in the dispatch log with full context
• For executors: Merge any partial work, then re-dispatch a new executor for the remaining work. Include a note in the prompt: "Previous executor hit an internal error. Error file: {path}. Continue from where it left off."
• For reviewers/routers: Re-dispatch. These are stateless reads and cheap to retry.

Batch cleanup

After all agents in a batch complete (or are killed), kill the watchdog processes and remove marker files:

rm -f .gitban/agents/traces/*.stale .gitban/agents/traces/*.alive

Timeout thresholds

Error file convention

When an agent hits [Tool result missing due to internal error], it writes an error file to its outbox:

.gitban/agents/{role}/inbox/{SPRINTTAG}-{cardid}-{role}-{N}-ERROR.md

This file contains: which tool failed, what work was completed, and what remains. The dispatcher reads this on recovery to decide whether to re-dispatch or escalate.

Inputs

• Sprint tag: provided by the user
• Card list: use mcp__gitban__list_cards with the sprint tag filter

Phase 0: Sprint Readiness

Step 0: Claim ownership

Before creating a branch or dispatching anything, claim all sprint cards on main:

mcp__gitban__take_sprint(sprint_name="{SPRINTTAG}", handle="CAMERON")

CAMERON is the user's git handle. All dispatched work runs under CAMERON — it does not mean "reserved for manual work."

Step 1: Prepare cards for dispatch

Dispatch a general-purpose agent to get the cards ready. Tell it what you need — it knows how to use the gitban tools.

Agent(
  subagent_type="general-purpose",
  description="{SPRINTTAG}-sprintmaster",
  prompt="Sprint tag: {SPRINTTAG}

Hey, I need to dispatch these cards and they're not ready yet. Can you get them into shape for me? Here's what I need:

Cards: {card_list}

What 'ready' means:

1. Every card in todo status. If they're stuck in draft, sort out the validation issues (get_validation_fixes will tell you what's wrong, then edit_card/append_card to fix). If they're in backlog, just move them over.

2. Step numbers in each card title (update_card_metadata) so I know what order to run them:
   - step 1, step 2, step 3 = sequential
   - step 2A, step 2B, step 2C = parallel batch, safe to run at the same time
   - Same number + different letter = no shared files, no dependency
   - Next number = phase barrier, everything before it must finish first
   - P0s before P1s at the same dependency level

3. Figure out the dependencies — which cards touch the same files, which ones need another card done first, which are truly independent. That's how you'll know the step numbers.

4. Assign an owner to each card.

5. Give me back the execution plan — batches, order, and anything you think I should know about.

Important: if a card is fighting you on validation or the scope seems unclear or too big, don't try to be a hero. Flag it and tell me it needs an architect review. Your job is to get cards ready for dispatch, not to redesign them.

Use the gitban tools however you see fit — you know the system better than I do."
)

Step 2: Plan Review

Review the sprintmaster's execution plan yourself before proceeding:

• Are all cards in each parallel batch truly independent?
• Do any batched cards touch the same source files?
• Could any shared test fixtures cause race conditions?
• Are P0 cards sequenced before P1 cards at the same dependency level?

If anything looks wrong, re-sequence using mcp__gitban__update_card_metadata. Do not proceed until you are confident.

Phase 1–4: Execution Loop

For each step group (in order):

Pre-batch Review

Before dispatching each batch, check for drift:

• Are the cards in this batch still independent given changes from previous batches?
• Did a previous executor touch files that create new dependencies for this batch?

If drift is detected, re-sequence the remaining cards before proceeding.

Important: The dispatcher does not use card status as a control signal. The router's verdict drives sequencing — not the card's done/blocked/in_progress state. Card status is managed by the agents. However, the dispatcher should sanity-check card status after each phase as a health check.

1. Dispatch Executors (worktree isolated)

For each card in the batch, dispatch an executor using the template and polling loop above.

• Worktree venv resolution is automatic via scripts/venv-python — no setup script needed (see ADR-032).
• If batch has multiple cards, dispatch all in parallel (single message, multiple Agent calls)
• If an agent goes stale, follow the stale detection recovery procedure
• After each executor completes, merge its worktree branch back to the sprint branch:

  git merge worktree-agent-{id} --no-edit
  git tag -d "{SPRINTTAG}-{cardid}-done" 2>/dev/null
  git worktree remove --force {path}
  git branch -D worktree-agent-{id}
  

• Run git worktree prune before proceeding

Post-merge checklist

After all worktrees in a batch are merged:

• Run tests on the merged sprint branch to catch integration issues between parallel changes. Remember: no piping or output redirection (see top-level rule). Use pytest flags (-q, --tb=line, --no-header, --timeout=30) to control verbosity.
• Regenerate derived artifacts (manifests, generated code, etc.) if multiple executors touched source files that feed into them — individual executors may have regenerated in their worktree, but the merged result needs a final pass
• Check for "Already up to date" on any merge — this means the executor committed to the sprint branch instead of its worktree branch. Verify the changes are present; if not, investigate.

2. Dispatch Reviewers (main thread)

Every executor cycle gets reviewed. No exceptions.

For each card in the batch, dispatch a reviewer using the template and polling loop above.

• Get the commit hash from the merge commit or git log
• Review number N = 1 for first review, increment on re-review
• If batch has multiple cards, dispatch all in parallel

3. Dispatch Routers (main thread)

For each reviewed card, dispatch a router using the template and polling loop above.

• If batch has multiple cards, dispatch all in parallel

4. Process Router Verdicts

Read the router's output files to determine the verdict for each card:

APPROVAL → dispatch a close-out agent using the pattern above BLOCKERS → dispatch an executor agent (N incremented). The full loop repeats: executor → reviewer → router. Do NOT skip the reviewer on re-work. PLANNER WORK → dispatch a planner agent using the pattern above. Non-blocking relative to executor sequencing — planners don't gate the next batch. But "non-blocking" does not mean "safe to forget." The planner feeds follow-up work back into the current sprint, extending it to absorb its own findings. If a planner fails, retry it once before moving on (transient failures like permission bugs and tool timeouts are the common case, not genuine rejection). Log the full error message on failure (see Dispatch Log section).

5. Check for new sprint cards from the planner

After processing all verdicts for a batch, re-read the sprint card list. The planner extends the sprint by adding new cards with step numbers. If new cards appear in todo status with step numbers, they become part of the remaining execution plan — treat them like any other sprint card and dispatch them in their sequenced order. This is the self-healing loop: tech debt discovered during the sprint gets resolved in the same sprint.

6. Generate Phase Metrics

After all verdicts for this batch are processed (approvals closed out, rework dispatched, planners dispatched), run the parser to append metrics for this phase to the dispatch log:

.venv/Scripts/python.exe scripts/parse-agent-logs.py --sprint {SPRINTTAG} --phase {N} >> .gitban/agents/dispatcher/inbox/{SPRINTTAG}-dispatch-log.md

If the parser exits with code 1 (no logs found), skip and continue. Agents may not have emitted JSONL logs if they were not instrumented.

7. Repeat

Move to the next step group (including any new cards the planner added to the sprint). Continue until all router verdicts for all cards are APPROVAL and close-out agents have completed.

Dispatch Log

Maintain an append-only log at .gitban/agents/dispatcher/inbox/{SPRINTTAG}-dispatch-log.md. After each phase completion, append an entry with:

• Timestamp
• Phase/step completed
• Cards processed and results
• Merge status
• Any drift detected
• Agent failures: log the full error message, tool name, and card ID — not just "Error (non-blocking, backlog items deferred)." A resuming dispatcher (or a human) needs the actual error to diagnose and recover.

This enables crash recovery — a new dispatcher session can read the log and resume.

Agent Performance Metrics

Agents emit structured JSONL trace logs via the agent-trace.sh PreToolUse hook to .gitban/agents/traces/. After each phase completes, the dispatcher runs scripts/parse-agent-logs.py to generate metrics tables and appends them to the dispatch log. Use --breakdown for time-per-activity analysis.

After each phase (immediately after processing router verdicts):

.venv/Scripts/python.exe scripts/parse-agent-logs.py --sprint {SPRINTTAG} --phase {N} >> .gitban/agents/dispatcher/inbox/{SPRINTTAG}-dispatch-log.md

This produces a table like:

### Phase 1: Step 1 (abc123)

| Agent | Tokens | Tools | Duration |
|:------|-------:|------:|---------:|
| executor-1 | -- | 131 | 23m |
| reviewer-1 | -- | 33 | 3m |
| router-1 | -- | 9 | 1m |
| **Phase total** | **--** | **173** | **27m** |

At sprint close-out (Phase 5, before archiving):

.venv/Scripts/python.exe scripts/parse-agent-logs.py --sprint {SPRINTTAG} --summary >> .gitban/agents/dispatcher/inbox/{SPRINTTAG}-dispatch-log.md

This produces a summary table like:

## Sprint Metrics
| Metric | Value |
|:-------|------:|
| Cards completed | 5 |
| Total agent dispatches | 19 |
| Total tokens | -- |
| Total tool uses | 650 |
| Total wall time | 2h 15m |
| Rework cycles | 1 (53px1p) |
| Backlog cards created | -- |

Fallback: If the parser finds no JSONL logs (e.g., agents did not emit logs), fall back to logging agent result metadata (total_tokens, tool_uses, duration_ms) manually as before. The parser output is preferred when available.

This data is used for profiling and optimizing agent performance across sprints.

Phase 5: Sprint Close-out

ONLY run Phase 5 when the ENTIRE sprint is complete. That means every card the user assigned to this dispatch has received an APPROVAL verdict and its close-out agent has finished. If you were given a subset of cards from a larger sprint, Phase 5 does NOT apply — commit your work and stop. The sprint stays open for the next dispatch.

Do NOT archive cards mid-sprint. Completed cards stay in done status on the board until the sprint closes. This keeps the done pile visible for progress tracking and retrospectives — just like a real scrum board.

When (and only when) the full sprint is complete:

0. Backlog verification: Before generating metrics, cross-reference router-identified backlog items (from router output files) against actual cards on the board. If a router routed N items to a planner and fewer than N cards exist, the planner dropped work. Re-dispatch the planner for the missing items before proceeding.

0b. Done tag cleanup: Sweep any leftover done tags for this sprint:

git tag -l "{SPRINTTAG}-*-done" | xargs -r git tag -d

1. Generate sprint summary metrics:

   .venv/Scripts/python.exe scripts/parse-agent-logs.py --sprint {SPRINTTAG} --summary >> .gitban/agents/dispatcher/inbox/{SPRINTTAG}-dispatch-log.md
   

2. Archive all done cards for the sprint using gitban tools
3. Commit all .gitban/ changes
4. Report completion to the user. The dispatcher does not push branches, create PRs, or dispatch PR agents — the user handles that.

If only a batch of cards was dispatched (not the full sprint): commit all .gitban/ changes to the sprint branch and stop. Do NOT archive.

Agent Inboxes

All inter-agent communication goes through versioned inbox files:

.gitban/agents/reviewer/inbox/{SPRINTTAG}-{cardid}-reviewer-{N}.md
.gitban/agents/executor/inbox/{SPRINTTAG}-{cardid}-executor-{N}.md
.gitban/agents/planner/inbox/{SPRINTTAG}-{cardid}-planner-{N}.md
.gitban/agents/dispatcher/inbox/{SPRINTTAG}-dispatch-log.md

Key Conventions

• Phase barrier: all agents in a batch must complete and merge before the next batch starts
• Review is mandatory: every executor cycle produces a review. The dispatcher cannot skip reviews.
• Router verdict drives sequencing: the dispatcher reads router verdicts and dispatches accordingly.
• Only executors use worktree isolation: reviewers, routers, planners, and close-out agents run on the main thread.
• Worktree cleanup: after each executor completes, merge its branch, remove the worktree, delete the branch. Run git worktree prune before each new batch.
• MCP tools hit main repo: card edits from any worktree land on the main .gitban/ directory
• Long paths on Windows: ensure git config core.longpaths true is set
• No co-authored-by lines in commits
• Never use --no-verify to bypass pre-commit hooks
• No PRs: The dispatcher does not push branches, create PRs, or dispatch PR agents. The user handles that.
• No output piping: No |, >, 2>&1, tee, or any output redirection in Bash commands. See the terminal output rule at the top.
• Stage with git add .gitban/: always stage the entire .gitban/ directory, never cherry-pick specific files — partial staging causes orphaned renames (old file tracked, new file untracked) that create duplicates.

Operational Notes

Things the dispatcher should be aware of that aren't covered by the phase instructions above.

Merge conflicts

Parallel worktree executors can produce merge conflicts even when cards touch different functions in the same file. When this happens:

• If a rework executor rewrote a file that the original also created (e.g. a test file), take the rework version (git checkout --theirs)
• If the conflict is between two independent cards, resolve by keeping both changes
• Never use --no-verify or skip hooks to work around a conflict

Pre-commit hook failures on dispatcher commits

Pre-commit hooks may auto-fix issues (line endings, path lengths, formatting) when the dispatcher commits .gitban/ changes. When a hook auto-fixes and fails the commit:

• Re-stage the modified files (git add the changed paths)
• Create a new commit (do not amend)

Parallelizing across verdict types

When processing router verdicts, independent actions can be dispatched in parallel:

• Close-out agents for approved cards
• Planner agents for follow-up items
• Rework executors for rejected cards

These have no dependencies on each other and can all go out in a single parallel dispatch.

Continuing an existing dispatch log

When dispatching a new batch of cards for a sprint that already has a dispatch log, append to it. Use a clear separator (e.g. ## Batch 2: Cards ...) to distinguish batches. Do not overwrite or restructure existing log entries.

Claude Code false positive: "user doesn't want to proceed"

The error message "The user doesn't want to proceed with this tool use" is a known Claude Code false positive — it can fire spuriously on git and MCP tool calls when no user interaction occurred. Do not treat this as an intentional stop signal. If an agent fails with this exact message, retry automatically. This applies to all agent types but is most commonly seen with planners and close-out agents.

Crash recovery

If a dispatcher session ends mid-sprint, a new session recovers by reading the dispatch log and classifying in-flight cards by branch and tag state.

Step 1: Read the dispatch log. Read .gitban/agents/dispatcher/inbox/{SPRINTTAG}-dispatch-log.md to determine which phases completed. Cards with logged APPROVAL verdicts and successful merges are done — skip them.

Step 2: Check for error files. Check for -ERROR.md files in agent inboxes — these indicate agents that failed mid-work and wrote diagnostics before exiting. The error files contain enough context to re-dispatch without re-reading the full card.

Step 3: Classify in-flight cards. For each card that was dispatched but not logged as complete:

Step 4: Resume the execution loop. With all cards classified, resume from the earliest incomplete phase. Cards classified as "done" enter the review queue. Cards classified as "partial" or "not started" enter the executor queue.

Step 5: Clean up stale worktrees. After classification, prune any leftover worktrees:

git worktree prune

Hung agent recovery

When a watchdog marks an agent as stale and the dispatcher kills it via TaskStop:

1. Log everything in the dispatch log: agent type, card ID, idle duration, last tool call from the .stale file, and whether partial work was found.
2. For executors with partial commits: Merge the partial work before re-dispatching. The new executor's error file tells it what remains.
3. For agents with no commits: Re-dispatch from scratch. The work is lost but the card and inbox files are intact.
4. Max retries: Re-dispatch a failed agent at most once. If the re-dispatch also goes stale, escalate to the user — something is systematically wrong (e.g., MCP server down, API errors).