| name | worktree-parallel-orchestration |
| description | Procedure for running multiple independent backlog items in parallel via worktree-isolated subagents with zero merge conflicts — partition file ownership before spawning, isolate each implementer in its own worktree, sequence overlapping work behind occupants, one coherent self-verified PR per agent, and serial orchestrator merge. Use when executing 2 or more independent items concurrently. |
Worktree-Parallel Orchestration
Procedure for the orchestrator that fans out several independent backlog items to
worktree-isolated subagents at once, then merges their PRs serially with no conflicts. This skill is
routing/procedure only — every git, spec, TDD, and verification constraint it invokes is owned by the
rules below and must not be restated here.
Where the procedure needs a concrete command, script, branch name, or threshold, it points at the rule
that owns it instead of naming it. The only names used literally are the agent-tooling primitives the
procedure is built on (the Agent tool's worktree isolation and SendMessage), because they are the
mechanism.
Rule Anchor
AGENTS.md > "Rules and Skills Boundary" — skills are procedure; rules win on conflict.- git-branch.md — "Git Worktree" (isolation + guardrails);
"One-Branch-At-A-Time Rule" (Exception 2 authorizes concurrent worktree branches on a disjoint file
set, and names the branch-guard override that permits them); "Clean Working Tree Before Every Commit
and Push" (names the CI-equivalent verification entry point); the merge-time branch-deletion ban;
"Merge Landing Verification"; "Delete Merged Branches"; "PR Batching".
- spec-workflow.md + backlog-execution.md
— the spec gate pipeline for code work.
- tdd-and-planning.md — "Prove the regression test RED" (red-before-green).
- verification.md — build / test / typecheck / scan gates.
When to Use / When NOT to Use
- Use when there are ≥ 2 independent items whose file territories can be made disjoint, and the
speedup of running them concurrently is worth the partition overhead.
- Do NOT use for a single item (just do it on one branch) or for tightly-coupled changes that
cannot be split into non-overlapping file sets — run those sequentially on one branch instead.
- Do NOT use — and drain everything else first — for a "shared-ground" change: anything that alters
the toolchain or configuration every other task is verified against (the type-checker or its
configuration, the test runner, the lint/format configuration, the build pipeline, a workspace-wide
dependency bump). File ownership cannot make these disjoint: they are disjoint in files but shared in
effect. Landing one while other branches are in flight makes every downstream failure ambiguous — an
agent cannot tell its own defect from fallout, and bisecting afterwards costs far more than waiting.
Run such an item serially, on an empty queue: no other open PRs, no running implementation agents,
and the integration branch green on the project's CI-equivalent verification entry point. Re-check that
the queue is still empty immediately before starting.
The Procedure
1. Partition file ownership BEFORE spawning (primary conflict-avoidance)
Before any agent is spawned, assign every candidate item an explicit OWNED path list and a
FORBIDDEN path list. The partition invariant: no two concurrent agents may write the same file.
Shared/central files (index registries, generated baselines, cross-cutting rule docs) are the usual
collision points — give each such file to at most one agent, or defer edits to it (see step 8). This is
the mechanism the git rules' One-Branch-At-A-Time exception depends on; without a clean partition, do not
run in parallel.
2. Isolate each implementer in its own worktree
Spawn each parallel implementer with the Agent tool's isolation: "worktree". Each carries its own
concurrent feature branch cut from a freshly-fetched integration branch, created with the branch-guard
override the git rules define for exactly this case. Hand each agent its OWNED + FORBIDDEN lists verbatim.
3. Sequence overlapping work behind occupants
If a candidate item's territory overlaps the OWNED paths of a currently-running agent, HOLD it —
do not spawn it. Release it only after the occupying agent's PR merges (its files are then free). Never
run two agents that touch the same file concurrently.
4. One coherent PR per agent (the agent's contract)
Each implementer produces exactly one PR and does not self-merge:
- Prove it fails first. A new or changed regression test does not count as verification until it has
been demonstrated to FAIL against the pre-change state, then pass. Never skip this because the test is
green now.
- Self-verify in the FOREGROUND using the project's CI-equivalent verification entry point — the
single entry that reproduces what CI's required checks assert, including the build and the affected
packages' tests. All green, evidence reported. A partial check is not the gate: a narrower
scan-only or hook-only run can report a pass where CI fails, because it treats baseline notices and
missing build outputs as clean, and a freshly-created worktree may not carry the installed
hook/formatter toolchain the project's checks assume. Never substitute a narrower command for the
CI-equivalent one, never restrict it to a subset of its stages, and never background the
verification and report before it finishes. It takes minutes on a code branch — that is the gate,
not an overrun.
- Correct commit footers; open exactly one PR against the integration branch.
- Stop-and-report on a blocker rather than merging or leaving a broken commit.
5. Orchestrator merges serially
The orchestrator — never the implementer — merges, and one PR at a time, via the armed auto-merge form
the git rules permit (the merge-time branch-deletion flag is banned there; do not reintroduce it). On a
stale base or a CI flake, rebase the branch onto the freshly-fetched integration branch and re-arm.
Diagnose real failures; a known fresh-worktree environment artifact (e.g. build outputs absent because
that worktree was never built) is not a code failure.
After each merge, run post-merge-cycle — it confirms the merge actually
landed, and only then deletes the branch and prunes its worktree. Release an item held in step 3 only once
that cycle reports the landing confirmed; the occupant's files are not free until then. Run it per merge,
as you go — that is the orchestrator's call, not something to wait for a human to request, and deferring
it is how a hundred stale branches and tens of gigabytes of worktrees accumulate.
Read the review output BEFORE arming the merge. Review-producing automation is typically advisory:
its findings arrive as PR comments, while the checks that actually gate a merge are a different set. So an
auto-merge armed early fires on the gating checks and carries the review's findings straight into the
integration branch — the feedback was produced, and simply never read. A review job reporting pass is
not evidence of no findings; it usually passes whether or not it commented. Therefore: fetch the PR's
review comments and analysis findings, address or consciously dismiss them, and only then arm the merge.
Passing checks answer "did it break anything"; the review answers "should it land as written". The full
fix → push → re-review loop this hands off to is
automated-review-convergence.
6. Spec-gated (code) work clears its gate BEFORE implementation
For code items requiring a spec, run draft → GATE-WRITE → independent GATE-APPROVAL first — independent
meaning a reviewer that did not author the spec (the proposal-reviewer / architecture-auditor roles).
Fold every REVISE finding, then approve — all per the spec-workflow / backlog-execution rules. Only
APPROVED items enter the parallel implementation wave.
7. Resume, don't respawn
A subagent killed by a session limit is resumed from its transcript (SendMessage to the same
agent), never re-spawned from scratch — a fresh spawn loses its partition context and its in-progress
worktree state.
8. Baseline reconciliation once
When several concurrent PRs each tighten the same ratchet baseline — any generated allowlist or
threshold file the project derives from the whole tree — do not regenerate that baseline per-PR: each
regeneration races the others and freezes a tree the sibling PRs are about to change. Let the earlier PRs
land, then regenerate the baseline once, on the last-merging PR.
Worked Example — the partition step
Three independent items, partitioned so no file is written twice:
| Item | Agent | OWNED (may write) | FORBIDDEN (must not touch) |
|---|
| A | a1 | packages/foo/** | packages/bar/**, packages/baz/**, shared idx |
| B | a2 | packages/bar/** | packages/foo/**, packages/baz/**, shared idx |
| C | a3 | packages/baz/** + the shared registry/index | packages/foo/**, packages/bar/** |
The shared registry is owned by exactly one agent (a3). A fourth item touching packages/bar/** is
held (step 3) until B's PR merges, since it overlaps a2's OWNED set.
What This Skill Does NOT Do
| Not this skill's job | Owner |
|---|
| Define git/branch/merge/worktree policy | .agents/rules/git-branch.md |
| Name the CI-equivalent verification entry | .agents/rules/git-branch.md |
| Define the spec gate pipeline | spec-workflow.md / backlog-execution.md |
| Define red-before-green / verification | tdd-and-planning.md / verification.md |
| Verify a merge landed / delete a branch | post-merge-cycle |
| Do the implementation or judge the PR | the spawned implementer / the code-review gate |
If you find yourself restating a rule here, stop — link the rule instead.
