/parallel-orchestrator

name: parallel-orchestrator
description: Use to actually launch multiple developer agents in parallel via the subagent tool (Task/Agent), given a sprint plan and board. Triggers from /app-build or when the tech-manager says "spawn the pod". Encapsulates the rules for safe concurrent agent execution.

Parallel orchestrator

You launch IC agents concurrently. This skill exists because parallel agent launches need rules — without them, agents stomp each other.

When to use

Called from `/app-build` or by the tech-manager once `docs/31-board.md` has tickets in `todo` ready to start.

Procedure

0. **Doctor gate.** Run the `board-doctor` skill first. If it exits non-zero, spawn nobody — a parallel launch against an incoherent board multiplies the damage across every track at once.

0a. **Budget gate.** The loop has no economic brake other than this one:

   node "${CLAUDE_PLUGIN_ROOT}/scripts/round-journal.mjs" check

Exit `1` means a ceiling is reached: **stop the loop**, print the line verbatim, and report what is unfinished. Do not start a round you cannot finish. Ceilings come from `--max-rounds` / `--max-spawns` / `--max-retries` / `--max-spend-usd`, or `APP_TEAM_MAX_*` in the environment. Raising one is a decision the user makes, not one you make to keep going.

1. **Read the board.** Find tickets where `Status = todo` and all `Depends on` IDs are **merged** (`qa` or `done`) — a dependency is satisfied once its code is on the integration branch, not once QA has signed it off. Requiring `done` stalls every dependent behind a QA pass.

Read it from the log rather than the table where one exists — `node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" show --json` gives you `status` and `dependsOn` per ticket already derived.

Note what this readiness rule *cannot* express: a ticket behind a `blocked` dependency is not ready and never will be, but it is also never reported. That is the doctor's `stranded` check, and it is why step 0 exists.

1a. **Claim before you spawn.** One append per ticket, and it is also the readiness check you cannot forget to run:

   node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" move APP-001 claimed --by ios-developer

`claimed` is **refused** on a ticket whose dependency has never merged. That refusal is the answer, not an obstacle: spawn nobody for that ticket and say why in the standup. Claiming before the spawn also means the board says who is working on what *while* they work — the window in which two orchestrators could both hand out the same ticket closes here.

2. **Group by owner.** One agent invocation per owner, batched. iOS dev gets all their ready tickets in one prompt; same for Android; same for backend.

2a. **Lease one slot per writing agent, then let the gate check you** (`agent-isolation`):

   node "${CLAUDE_PLUGIN_ROOT}/scripts/worktree-slot.mjs" lease --owner ios-developer --tickets APP-001,APP-004
   node "${CLAUDE_PLUGIN_ROOT}/scripts/worktree-slot.mjs" lease --owner android-developer --tickets APP-002
   sh "${CLAUDE_PLUGIN_ROOT}/scripts/spawn-gate.sh" ios-developer android-developer

**The gate takes OWNERS now, because that is what has a tree each.** Step 2 above batches by owner and step 3 below tells each agent to use "its worktree path" — those two sentences and a worktree-per-ticket rule could not all be true at once, and the first owner with two ready tickets is where it breaks (`agent-isolation` Rule 1 has the full argument). The owner cuts a branch per ticket inside its slot, so branch-per-ticket and `code-reviewer`'s "this branch contains only this ticket's files" both still hold.

`lease` refuses when the pool is full — that is the round's parallelism cap doing its job, and raising it (`--pool N`) is a decision about how much of the machine the studio may use, not a workaround to keep going.

The gate is the last thing you run before the launch message, and **its exit code decides whether the launch happens**:

• `0 GO` → spawn. With one ticket it prints `SERIALIZED` instead — that is the legal one-writer

path, and it holds only while the writer stays alone. Say so in the standup.

• `1 REFUSED` → **spawn nobody.** Two or more writers, at least one with no worktree. It names

the missing IDs and prints the `git worktree add` line for each. Create them and re-run, or serialize the round.

• `2 CANNOT EVALUATE` → not a git repo, so worktrees are unavailable. Serialize; never treat a

2 as a go-ahead.

**Why this is a script and not a paragraph.** The paragraph existed. It had existed since v1.4.0, backed by a measured collision — a commit containing another ticket's half-written files, ~50% of an agent's budget burned redoing work it had already done, add/add conflicts on all 8 files (`docs/research/2026-07-29-dry-run-parallel-agent-collision.md`). Then, hours after spending a day hardening that paragraph, the orchestrator spawned two writers into one checkout anyway; one ran `git stash` + `git reset` and 22 files of the other's work vanished, recoverable only by luck (DR4-027). Knowing a rule, having written it, and having defended it does not make you apply it. Run the gate.

2a-i. **Destructive commands are banned for any agent that shares a tree** — and you tell every agent so in its prompt. Never, repo-wide:

   git reset (--hard or otherwise)   git stash   git checkout -- .
   git clean                          git add -A / git add . / git commit -a

Stage by explicit path (`agent-isolation` Rule 2). If you need a clean tree to run a check, **copy the repo to a temp dir and dirty that instead** — `cp -R` or `git worktree add` a scratch worktree. Those commands are all unrecoverable from inside your run, and one of them is exactly how DR4-027 lost 22 files. If HEAD moved under you, stop and report (`ag