Files
pipelines/internal/author/skill/references/queue.md
T
alan 8f3ebf74ad skill: replace the lane model with the work queue
The lane machinery is gone: work is a markdown queue, items run in parallel in
their own worktrees, the committer stage lands its own work, land-check.sh gates
cleanup, branches are never deleted, and pipelines wait (rather than a driver
script) is what wakes a session. references/lanes.md becomes references/queue.md;
the remaining lane references in work/orchestration/debugging/delivery/format and
SKILL.md are rewritten, and the installer now prunes a managed file it no longer
bundles when the copy is unmodified.
2026-10-18 01:12:21 +01:00

4.3 KiB

The work queue

There are no lanes. Work is a markdown queue of items and a handful of rules that keep several items moving at once without losing any of them.

The queue is a file you can read

  • One markdown file lists the items, numbered, each saying what it is, the brief that carries the task, and its state. Read it top to bottom and take the first unfinished item.
  • An item is done when it is committed to main, verified, and — if it changed the app or the server — deployed and installed. Mark it in the file.
  • The file is the resume point. A session that dies and comes back reads it and continues; nothing is replayed because nothing is inferred from "what was I doing".

Parallel by default

Run independent items concurrently. Serialisation is the exception and must be justified by a real conflict, never by caution, and never presented as the operator's decision.

Serialize only when:

  • two items edit the same files at the same time and the merge cost would exceed the gain;
  • the one capture device is the bottleneck — implementation still runs concurrently, captures queue on the device lock;
  • the provider's spend cap is close, because tripping it fails every run in flight at once.

One worktree and branch per item

  • git worktree add -b <item> <path> main, and the brief names that worktree. Runs in different workspaces execute concurrently; a second run in a workspace an active run is changing is refused, naming the conflicting run (references/operations.md). One worktree per item is what keeps that guard from being a bottleneck.
  • The brief also names the device the item may use and forbids the others, so two items never fight over one phone. Never use the operator's own device unless the brief explicitly allows it.
  • Choose the pipeline by area (references/orchestration.md); each area pipeline reads the project's own map — android/AGENTS.md, internal/tui/AGENTS.md, internal/server/AGENTS.md — for the build, test, run and capture commands. The pipeline carries how that technology is worked on anywhere; the map carries what is specific to this repository.

Landing is the pipeline's job

  • The committer stage lands its own work: after committing, it merges main into its branch, resolves any conflict there with the context of the change it just made, runs the checks again, then merges the branch into main and verifies its ancestry.
  • There is no merger process, no resolver pipeline and no escalation from pipeline to pipeline. A conflict is resolved by the stage that caused it, in the run that caused it.
  • Merging needs main's tree for a moment: the committer takes a lock and retries, so a concurrent landing cannot corrupt it.

The landing gate, and what must never happen

  • After every item, and before any cleanup or before starting the next item, run land-check.sh <branch>. It must report the branch as an ancestor of main.
  • If it refuses: do not remove the worktree, do not touch the branch, do not start the next item. Report the landing failure and the commits that are not in main.
  • Never delete a branch. Deleting a branch whose commits are not yet in main leaves them unreferenced — that is how six finished items were lost in one day. Removing a worktree is fine, the commits live on the branch. A cherry-pick's deletions need the same scrutiny as its conflicts: replaying an older commit can delete a file that a later refactor added.

Waiting without a scripting harness

  • pipelines wait <run-id> […​] blocks until the runs finish and exits; run it as a background task so the session is woken exactly when the batch is done. A run that failed is still a finished run: it exits 0 and says what happened.
  • Do not build a polling loop, a cursor file or a driver script to answer "is it done yet", and do not infer progress from an earlier read. Ask the server, or wait on it.

The shared server

  • Do not restart, rebuild or redeploy the shared Pipelines or OpenCode server while any item has a run in flight — a restart interrupts in-flight runs (references/debugging.md). A deploy must wait for active runs to reach zero, and deploys are the operator's step.
  • All items read the one logical endpoint; a worktree separates them, not a second server.