Parallel Tracks

Parallel Tracks

This is a generic, project-agnostic methodology for deciding when sliced work can be dispatched to parallel, worktree-isolated subagents instead of one sequential subagent after another. It does not replace a project's own stage gates (design review, code review, verification) — a track still has to pass those on its own before it merges.

When To Load

Load this when an orchestrator command (e.g. /develop-phase, /implement) has already sliced work into more than one piece and needs to decide dispatch order — not when there's only one piece of work, and not as a default for every implementation run. Parallel dispatch is an opt-in optimization for genuinely independent work, not the normal path.

The Independence Test

Two pieces of work are an independent track pair only if both hold:

1. Neither track reads or writes the other's owned code, database, or module.
2. Both tracks build only against an interface that is already frozen — neither track is itself still changing that interface.

If either condition fails, the tracks are dependent: the prerequisite track must merge before the dependent one starts, and they run sequentially in the main tree, dispatched the normal way (see each command's own ## Execution Note).

A change to a shared library or shared abstraction (something more than one track would otherwise touch) is never split across two parallel tracks — treat it as its own prerequisite track that merges first, then re-evaluate independence for what's left.

For a project organized around bounded modules/capabilities with a hard rule against cross-module database joins or foreign keys, module/capability boundaries are usually a safe, low-conflict split axis: a track should be one or more whole modules, never a partial slice of one.

The Interface-Contract Precondition

Independent parallel tracks require a frozen interface-contract artifact produced at the design stage — an API contract, event/message schema, or equivalent — that every track implements against instead of against each other's in-progress code. If no such artifact exists yet for the boundary in question, the tracks are not safely parallelizable yet: fall back to sequential dispatch, or ask whoever runs the design stage to produce one first.

Dispatch Mechanics

For each track confirmed independent:

• Dispatch it via the Agent tool with isolation: "worktree" and subagent_type set to that track's role (e.g. backend-developer, frontend-developer).
• Each dispatch gets its own git worktree and branch, isolated from the main tree and from every other track's worktree.
• If the subagent makes no changes, the worktree is cleaned up automatically. If it does, the tool result returns the worktree path and branch.
• Run all confirmed-independent tracks' dispatches in parallel (same message, multiple tool calls) — there is no reason to serialize them once independence is confirmed.

Merge-Back And Cleanup

• A track's branch only merges back after that track's own stage gates (code review, verification, whatever the project's pipeline requires) pass on that branch — worktree isolation does not skip or shortcut those gates.
• Dependent tracks wait for their prerequisite's merge before their own dispatch begins; independent tracks may merge in any order relative to each other.
• The orchestrating command owns the outcome of every worktree it opened: either merge it or explicitly flag the branch for human review before the command reports itself done. Never leave a worktree dangling with unmerged, unflagged changes.

Common Failure Modes

• Splitting a track boundary through the middle of a single module/shared library instead of along a whole-module line — this is the single most common source of merge conflicts between "independent" tracks.
• Declaring tracks independent against an interface contract that isn't actually frozen yet (one side is still redesigning it mid-implementation).
• Skipping a track's own code-review/verification gate because "it's isolated in its own worktree, so it must be fine."
• Leaving a worktree/branch unmerged and unflagged after its subagent finishes.

Validation Evidence

• The independence test's answer recorded explicitly (which condition held, which didn't) before dispatch — not assumed.
• Each track's own stage-gate evidence, still produced per-track even though execution was parallel.
• Confirmation every opened worktree was either merged or explicitly flagged, with none left dangling.