parallel-execution

Parallel Execution

1. Initialize the run

Create and check out this run's branch before initializing, then run init-run from it:

git checkout -b <run branch> <base branch>    # e.g. run/<runId> from master
node "$CLAUDE_PLUGIN_ROOT/scripts/cli.mjs" init-run <planPath> --run <runId> --root <project root>

This writes .teammates/<runId>/plan.json and status.json and prints the phase breakdown. Tasks land in the same phase only when their deps are satisfied and their file sets are disjoint.

The order matters for enforcement, not just tidiness. init-run records a run branch by fill-if-absent: it records HEAD when the run has no runBranch recorded yet and HEAD is not the base branch, and it records nothing when HEAD is the base. A value already recorded always wins — writePlan resolves the field as carried ?? usable — so a re-init from a different branch keeps the old record and prints a note naming the branch it kept. Compare that name by bytes rather than by eye: the check is byte-wise, and zero-width and homoglyph characters render identically in a terminal.

It records nothing at all wherever it cannot resolve the base on its own: it derives the base itself and takes no --base, so a repository holding both main and master, or neither, throws into a catch that leaves the field unset, and no §1 order can arm anything there until a command that does take --base records it.

One input escapes that description: a recorded empty string is carried like any other, then dropped on write because it is falsy, so the field disappears, the note names no branch, and the run ends up with no record rather than the one it reports keeping.

That record does not resolve a stopping teammate to its task — the worktree location record written by locate does that. What it decides is whether the stop-time checks are allowed to be a verdict: complete --enforcement-only compares the recorded run branch against the branch the main worktree has checked out, and when it is absent or different it reports that it cannot verify completion and the stop is allowed. Checking the run branch out before the first init-run is therefore what puts the record in place at the start of the run, on a run id that has none yet. It does not repair a run whose recorded branch is already wrong: no command overwrites that field. To correct one, remove runBranch from .teammates/<runId>/plan.json and run init-run again — from an attached branch. An absent record needs no hand-editing: some later commands fill it in and others only read it, so read runBranch in .teammates/<runId>/plan.json rather than predicting which. On a detached HEAD init-run records the literal string HEAD, which is not a run branch and which no command overwrites, so it disarms the second layer until the field is removed by hand.