Parallel Dispatch

Parallel Dispatch

Generate structured agent prompts and a coordinator playbook from a user-provided parallel work plan. The user has already done the decomposition — this skill validates that the tracks are actually parallel-safe, then formats the output.

When invoked

Step 0 — Confirm parallel fit

Before generating prompts, verify that the plan is a good candidate for parallel dispatch:

| Check | Dispatch if true | Do not dispatch if true | |-------|------------------|-------------------------| | Independence | Each track has a distinct problem domain | A fix in one track is likely to change the diagnosis for another | | Context shape | Each agent can succeed from a narrow, self-contained prompt plus handover doc | Agents need the full system story or the coordinator's private context | | Shared state | Tracks do not edit the same files, mutate the same data, or compete for the same external resource | Tracks touch shared state without an explicit dependency | | Payoff | There are 2+ genuinely independent tracks; 3+ is usually where the benefit is clearest | One focused session would likely finish faster than coordinating agents |

If the tracks are related, have shared state, or are still exploratory, tell the user to run one sequential investigation first. If the decomposition is incomplete, ask for the missing track fields instead of inventing tracks.

Step 0.5 — Use code-wins for cheap design disputes

When the unresolved question is a design or implementation preference and building variants is cheap, dispatch the work as competing artifacts instead of arguing in prose:

1. Define the shared acceptance criteria and non-negotiable constraints.
2. Assign 2-3 agents to produce divergent implementations in isolated worktrees

or artifact folders.

1. Require each runner to include a short tradeoff note and proof commands.
2. Compare the artifacts directly, choose one, and either delete the throwaway

variants or preserve the winning pattern in a follow-up task.

Do not use code-wins when the variants would mutate the same database, send messages, deploy to production, or change irreversible external state.

Step 0.7 - Default to serial landing (not parallel push)

Parallel investigation can run concurrently; parallel landing on main cannot unless every track has a separate clone/worktree, zero file overlap, and Dan explicitly accepts push races. Default every code dispatch to a serial landing queue:

| Role | Does | Does NOT | |------|------|----------| | Runner | Work in git wt , commit locally, run track gates, return summary + git log -1 --stat + verification + branch/worktree path | Push to main, edit outside CAN touch, land from the canonical dirty checkout | | Coordinator | Pull fresh main, land one track at a time via git land (or repo-specific land path), re-run gates after each land, stop on conflict or scope drift | Let every runner push concurrently, use piped push commands that mask exit codes, or land while another track is still writing |

When to keep serial (default): 2+ code tracks, shared repo, any overlap risk, dans-brain canonical checkout (permanently dirty), client/shared-tree history, or when the concept-loop flagged multi-agent overlap / landing friction.

When parallel push is allowed: Dan explicitly opts in and the validator reports zero overlapping can_touch scopes and each runner uses its own worktree/clone. Even then, prefer serial unless the tracks are truly trivial.

Read [assets/serial-landing-queue.md](assets/serial-landing-queue.md) when filling the coordinator playbook and code-track prompts.

Step 0.6 — Babysit open PRs with a bounded /loop

Use this recipe when Dan asks to babysit PRs, keep agent branches moving, or run a standing /loop over dans-brain, brain/_repos/*, and client-adjacent repos. The point is to turn scattered branch/CI state into a small action queue, not to merge risky work by momentum.

1. Inventory the repos and open PRs: root repo first, then active submodules

under brain/_repos/, then explicitly named client repos.

1. For each PR, record branch, author/agent, files touched, check status, merge

conflict status, and whether the PR is mechanical or needs judgment.

1. Apply the CI/CD tier gate: mechanical auto failures can be fixed, verified,

committed, and pushed; propose failures get a diagnosis or draft fix only.

1. Land or rebase one clean PR at a time. Use the repo's sanctioned land path

(git land, merge button, or repo-specific instructions), then re-check the next PR against fresh main.

1. Stop on any conflict, red check that changes behavior, missing secret, or

unclear ownership. Surface a short queue with owner, blocker, and next action.

The loop is deliberately bounded: run one pass, produce the queue, act only on safe mechanical items, and end with exact proof links or commands. Do not keep polling indefinitely, bypass branch protection, rewrite another agent's branch, or edit workflow/secrets/branch-protection files to make checks green.

Step 1 — Collect track definitions

Ask the user for track definitions if not already provided. Each track needs these fields:

| Field | Required | Description | |-------|----------|-------------| | Name | Yes | Short label (e.g., "Track A — Server Conversion") | | Handover doc | Yes | Path to the handover document for this track | | Goal / evidence | Yes | Self-contained problem statement, expected outcome, and concrete evidence such as failing tests, errors, URLs, or acceptance checks | | Soldiers | Yes | List of sub-task IDs the agent should execute | | File scope | Yes | CAN touch / CANNOT touch: explicit file lists or globs (no repo-wide ** unless the track truly owns everything) | | Worktree slug | Yes (code) | Short slug for git wt : one isolated worktree per code track | | Issues | Yes | GitHub issue numbers to close (code tracks) or comment on (analysis tracks) | | Dependencies | No | Which tracks must land before this one starts (default: none) | | Landing order | No | Integer rank for the serial queue when dependencies are insufficient (lower lands first) | | Type | No | code (default) or analysis |

The user may provide these as a table, a list, or point to a file. Accept any format — extract the required and optional fields.

Step 2 - Validate file scope and ownership matrix

Before generating prompts, check for file overlap between tracks and emit an explicit File Ownership Matrix (file/area to owning track). Shared infra must have a single owner or sit in CANNOT touch for every other track:

• .github/workflows/**, lockfiles, root build/config (package.json,

pyproject.toml, netlify.toml, staticwebapp.config.json, ...)

• Shared engines (shared-engine.cjs, parser/, gate.js, design tokens)
• Capture dirs, handoff dirs, and coordinator-only landing paths

Validation steps:

1. Compare the "CAN touch" file lists across all tracks.
2. Reject repo-wide or directory-wide globs (**, src/**, app/**) unless

exactly one code track claims them and others list that tree under CANNOT touch.

1. If two tracks claim the same file (or overlapping globs), stop and flag it:

> "Tracks A and D both claim netlify/functions/firm-comp.mts. Split the scope, add a dependency + serial landing order, or collapse into one track."

1. Analysis tracks (read-only) are exempt from overlap checks; they do not edit files.
2. Append the matrix to the dispatch output and coordinator playbook so runners

see neighbor ownership without reading each other's prompts.

If the plan is available as JSON or YAML, run the bundled validator first:

python3 scripts/validate_tracks.py path/to/parallel-plan.json
python3 scripts/validate_tracks.py path/to/parallel-plan.yaml

It rejects missing goal/evidence, code tracks with no can_touch scope, overlapping edit scopes without dependencies, and explicitly shared state without dependencies. YAML support uses PyYAML when available and a narrow track-plan parser when it is not, so simple tracks: files remain portable.

Step 3 — Generate agent prompts

For each track, produce a fenced code block (```markdown) the user can copy-paste into a new coding-agent session. Use the template that matches the track type:

• Code track: [assets/agent-prompt-code.md](assets/agent-prompt-code.md)
• Analysis track: [assets/agent-prompt-analysis.md](assets/agent-prompt-analysis.md)

Read the appropriate template, fill in the bracketed placeholders, and emit the result inside a fenced markdown block.

Template rules

• Worktree + landing: Every code prompt must name git wt and forbid pushing to main. Runners return proof; the coordinator lands serially.
• Dependencies: If a track has dependencies, prepend: **DO NOT START until [dependency tracks] have landed on main (coordinator confirmed).**
• Self-contained context: Prompts must not depend on the coordinator's current chat history. Include the track goal, concrete evidence, and expected output directly in the prompt, even when a handover doc exists.
• Focused scope: One agent gets one problem domain. Do not use prompts like "fix all failing tests"; use prompts like "fix these failures in this file/subsystem."
• Constraints: Tell the agent not to broaden scope. If the evidence points outside its file scope, it should stop and report the scope issue instead of editing unrelated files.
• Post-completion gates: For code tracks, include appropriate verification commands based on the file scope:
• Touched shared-engine.cjs or parser/? Add: Run node tests/ AND npm run test:vitest:tracked
• Touched JS/JSX files? Add: Run node scripts/dead-code-check.js
• Final or dependent track? Add: Run npm run verify
• Analysis tracks: no gates
• Issue action: Code tracks "close" issues. Analysis tracks "comment on" issues.
• File scope phrasing: Be explicit. List specific files when possible. Use "and their lib/ helpers" for function groups. ALWAYS include both CAN and CANNOT lists.
• Capture add-on (optional): If the per-runner capture add-on is enabled (see [Optional add-ons](#optional-add-ons)), append [assets/runner-capture-addendum.md](assets/runner-capture-addendum.md) to each prompt and fill its [capture path] with //.md. Pick ` and each ` once, up front, and bake the literal path into each prompt — the separate sessions then need no coordination.

Step 4 — Generate coordinator playbook

After the agent prompts, produce a Coordinator Playbook section by reading [assets/coordinator-playbook.md](assets/coordinator-playbook.md) and filling in the track names, issue numbers, and any track-specific verification commands. The playbook carries two optional end-of-run passes (pagecraft HTML polish, combined-insight digest); keep or drop them to match the [Optional add-ons](#optional-add-ons) you enabled.

Step 5 — Summary table

End with a summary table so the user can see the full dispatch at a glance:

## Dispatch Summary

| Agent | Track | Type | Worktree | Soldiers | Issues | Land order | Can Start |
|-------|-------|------|----------|----------|--------|------------|-----------|
| 1 | ... | code | `git wt a` | ... | ... | 1 | Now (work only) |
| 2 | ... | code | `git wt b` | ... | ... | 2 | Now (work only) |
| 3 | ... | analysis | - | ... | ... | - | Now |
| 4 | ... | code | `git wt d` | ... | ... | 3 | After 1+2 land |

Optional add-ons

Two opt-in add-ons. Both default off so the base flow is unchanged. Turn them on when the user asks ("with capture", "insight-lock per runner", "polish the HTML at the end"), or proactively offer when the conditions below hold. State which add-ons are on at the top of your output.

A. Per-runner capture → combined insight (insight-lock)

Each runner writes a short insight-lock capture as it finishes; the coordinator condenses all of them into one cross-track memo at the end and surfaces the headline. Offer this for research-heavy or multi-track runs where the learning matters as much as the diff.

How the captures get back with no extra plumbing: under serial landing, runners commit captures in their worktrees; the coordinator lands each track (capture included) and pulls after each land. So:

1. Pick one ` (date + short label, e.g. 2026-06-03-layer-c`) and one

`` per track, up front.

1. Choose ` by repo, following insight-lock`'s storage rule:

• /root/dans-brain (or the Mac mirror): brain/context-captures/parallel-dispatch/
• any other repo: .agent-handoffs/context-captures/parallel-dispatch/

1. In Step 3, append [assets/runner-capture-addendum.md](assets/runner-capture-addendum.md)

to each prompt with [capture path] = //.md. Because every track's path is a distinct literal string baked into its own prompt, the separate sessions never coordinate and never collide.

1. After all tracks merge and you have pulled their captures, read every

//*.md and write a condensed //_combined.md from [assets/combined-insight.md](assets/combined-insight.md). The cross-track value is in the disagreements — lift each runner's Contradictions / Integration Risks into the combined memo. A risk only one track saw is what the others were blind to.

1. Surface it: end your final report with the combined memo's Headline

inline, a link to _combined.md, and anything in Contradictions / Integration Risks that should change the next decision.

The capture file is an allowed addition beyond a track's file scope (it is new, uniquely named, and conflict-free); tell the coordinator not to flag it as scope drift.

B. End-of-run HTML polish (pagecraft)

If any merged track produced or changed static HTML deliverables, finish them with pagecraft before declaring done — never ship hand-checked HTML. Auto-offer whenever a track's file scope includes .html/HTML output roots; skip entirely otherwise. The operational commands live in the coordinator playbook's "HTML polish with pagecraft" pass: install (or reuse) pagecraft, run the deterministic check-keystone.py guard, then the real-browser runner.py probe, fix keystone/wrap failures, and allowlist only confirmed non-defects.

Output format

• Agent prompts go inside fenced code blocks for easy copy-paste
• Coordinator playbook is regular markdown (not fenced — it's reference, not copy-paste)
• Keep the work scope of each prompt concise — under ~200 words. The handover doc has the details; the prompt just scopes the work. When the capture add-on is on, the fixed capture block is appended on top of that budget.

Common Pitfalls

Cheap building beats long argument

If the team is stuck on "which UI/layout/approach is better" and each option can be built in under an hour, create variant tracks. The output should be artifacts plus proof, not essays. Preserve only the winner unless the alternatives teach a durable lesson worth capturing.

Zombie issues — code merged, issues still open

When dispatching parallel agents, each agent will do the work but often skip issue closure — leaving issues in a zombie-open state where the code is merged but the issue dangles. This happened systematically on the Layer C migration: all 16 issues across Tracks C and D were left open despite code being committed and pushed.

Root cause: Issue closure instructions at the end of an agent prompt are treated as low-priority after the primary code/analysis work is complete. Agents prioritize "commit and push" as their exit signal and drop the issue lifecycle step.

Prevention: The agent prompt templates below include gated issue closure (bolded, with "do not end the session until..."). The coordinator playbook includes a verification step. Both are needed — agent

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bogdanbaciu21
• Source: bogdanbaciu21/skills
• License: MIT
• Homepage: https://www.bogdanbaciu.com

Install and usage instructions live in the source repository linked above.