Rewrite SKILL.md to state the stance (reconnoitre, then route all work through Pipelines runs; manage and debug, never implement), keep the existing authoring/operations index, and route to four new references. Add references/orchestration.md (stance, work items, brief template, hard constraints, pipeline choice, running and watching), references/lanes.md (worktrees, devices, sync/merge, restart-replay cursor fix), references/debugging.md (eight symptom/confirm/do playbooks) and references/delivery.md (artifacts, LAN URLs, WIP naming, install boundaries), each with a clearly labelled project example where Android/device specifics apply. Append orchestration verification habits to references/verification.md and add the four new files to install.go's managed inventory.
4.6 KiB
Parallel lanes
A lane is one sequence of runs in its own workspace, on its own branch, with its own device. Several lanes run concurrently without colliding, and each lane advances its own list of briefs one item at a time.
Why lanes, and what separates them
Runs in different resolved workspaces execute concurrently; a second run in a
workspace an active run is already changing is refused, naming the conflicting run
(references/operations.md). That guard is what makes lanes safe: give each lane its
own checkout so its runs never share a workspace. Concurrency is between lanes,
never inside one.
- One git worktree per lane, on its own branch. Create it with
git worktree add <path> -b <lane> main. Never run two lanes in the same tree, and never run a lane in the main checkout while another lane is merging into it. - One emulator or device per lane. Name the lane's serial explicitly in every brief dispatched to that lane, and forbid the serials the other lanes own. Never point two lanes at one device, and never at the operator's physical device.
- One work list per lane — a plain file of brief filenames, read one at a time.
- A brief for a lane must name the lane's worktree and device, so the run cannot stray onto another lane's tree or device.
Sync and merge
- Sync before each item: merge
maininto the lane branch so the item builds on the latest tree. If the sync conflicts, abort the merge and continue on the older base rather than hand-resolving mid-tick; record that it happened. - Merge back only when main's tree is idle. The main-lane publishes a busy marker
while one of its items runs; merging lanes wait for it. Never merge into
mainwhile a run is usingmain's working tree. - One lane merges at a time — take a lock around the merge so two lanes cannot merge simultaneously.
- Record a conflict, do not force it. On a merge conflict into
main, abort the merge and leave the work on the branch for a human to resolve; write it to a conflicts log. Never force-push, rebase, or otherwise rewrite around a conflict. The committer stage may resolve a conflict inside its own workspace, but a lane never silently discards the other side's work. - Clear stale markers. A marker left by a lane that died must not stall the others forever; expire markers older than a bounded age.
The restart-replay hazard
A lane script that simply re-reads its list from the top replays completed items after a crash or restart: it re-invokes the model, repeats side effects and may re-commit already-landed work. A list is a plan, not a resume point.
- Fix: persist a cursor. After each item is fully committed and merged, append it
to a per-lane
donefile. On startup, skip every item already recorded there and resume from the first unrecorded one. Record an item only once it has landed; an item that failed twice stays unrecorded so a later restart retries it deliberately. - An interrupted run is not replayed automatically; a retry is explicit
(
references/operations.md). Do not restart a lane to "get back to where it was" without the cursor, or it will re-run finished items. Never relaunch a duplicate of a run that is still active — reattach with its request key instead.
Coordinating the shared server
- Do not restart the shared Pipelines or OpenCode server while any lane has a run
in flight. A restart interrupts in-flight runs (
references/debugging.md). A deploy/restart tick must first ask the other lanes to stop starting runs, wait for active runs to reach zero, then restart; if runs will not drain, defer. - All lanes read the one logical endpoint; a lane's workspace is what separates it, not a separate server.
- A run that pauses the world (touching shared state, restarting a service) must hold the busy marker for the whole pause, not only while a model call runs.
Example (this repository, not a rule)
The repository runs several lanes at once. Concretely, at the time of writing:
- Worktrees
lane-app2(branchlane-app2) andlane-go(branchlane-go) under the temp directory, with a third main lane in/Users/alan/repos/pipelines. - Emulator ownership: lane A uses
emulator-5554, lane B usesemulator-5556; a brief names its own serial and states the other's is forbidden. - The main lane uses a busy marker while its item runs; the app lanes merge into
mainwhen it is idle and record conflicts instead of forcing them. - Restarts are deferred: a deploy tick waits for active runs to reach zero before it stops the server. This is the pattern the general rules above describe, not a hardcoded configuration a new project must copy.