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.
This commit is contained in:
2026-10-18 01:12:21 +01:00
parent 2da583c946
commit 8f3ebf74ad
9 changed files with 118 additions and 110 deletions
+16 -1
View File
@@ -9,7 +9,7 @@ import (
"path/filepath"
)
var skillFiles = []string{"SKILL.md", "references/orchestration.md", "references/work.md", "references/lanes.md", "references/debugging.md", "references/delivery.md", "references/format.md", "references/notifications.md", "references/operations.md", "references/transfer.md", "references/verification.md", "references/control.md", "references/harnesses.md"}
var skillFiles = []string{"SKILL.md", "references/orchestration.md", "references/work.md", "references/queue.md", "references/debugging.md", "references/delivery.md", "references/format.md", "references/notifications.md", "references/operations.md", "references/transfer.md", "references/verification.md", "references/control.md", "references/harnesses.md"}
func SkillDirectory() (string, error) {
dir := os.Getenv("XDG_CONFIG_HOME")
@@ -97,6 +97,21 @@ func InstallSkill() (string, error) {
return "", err
}
}
// A file the previous install managed but this version no longer bundles - a
// reference renamed or withdrawn - is removed only when it is unmodified. A copy
// the user edited is left alone, exactly as an edit to a live file is.
for file, hash := range previous {
if _, still := next[file]; still {
continue
}
existing, readErr := os.ReadFile(filepath.Join(dir, file))
if readErr != nil {
continue
}
if digest(existing) == hash {
_ = os.Remove(filepath.Join(dir, file))
}
}
if len(previous) == len(next) {
equal := true
for file, hash := range next {
+2 -2
View File
@@ -1,6 +1,6 @@
---
name: pipelines
description: Manage and author the Pipelines system through its CLI: write per-item briefs, run and watch pipelines, drive parallel worktree lanes, debug wedged runs, verify and deliver artefacts, and edit, validate and transfer pipeline definitions, preserving immutable history and requiring explicit approval to publish, execute, restart or install.
description: Manage and author the Pipelines system through its CLI: write per-item briefs, run and watch pipelines, drive parallel items in worktrees, debug wedged runs, verify and deliver artefacts, and edit, validate and transfer pipeline definitions, preserving immutable history and requiring explicit approval to publish, execute, restart or install.
---
# Pipelines management and authoring
@@ -60,7 +60,7 @@ and `references/format.md` (in parallel when possible); for notifications also r
| --- | --- |
| Briefs, work items, pipeline choice, running and watching | `references/orchestration.md` |
| Across projects: work ledger, start/pause/resume/status, queue driver | `references/work.md` |
| Parallel lanes, worktrees, sync/merge, restart replay | `references/lanes.md` |
| The work queue, parallel items and landing | `references/queue.md` |
| Diagnose a wedged, blocked or failed run | `references/debugging.md` |
| Publish artefacts, LAN URLs, install boundaries | `references/delivery.md` |
| Result format, tools, permissions, committer, routing, schedules, budgets | `references/format.md` |
@@ -82,7 +82,7 @@ Each playbook is *symptom → how to confirm → what to do*.
- **Confirm** The message names the conflicting run and its workspace; the guard is
working as designed — one active run per resolved workspace.
- **Do** Wait for the conflicting run, or start this one in a different workspace
(another worktree/checkout, which is what a lane is for — `references/lanes.md`).
(another worktree/checkout, which is what a second item's worktree is for — `references/queue.md`).
Do not delete the active run, the database or sessions to clear it. An **orphan**
active session left by a restart with no owning active run still refuses new work
until it is interrupted; reusing the active run's original request key reattaches
@@ -113,7 +113,7 @@ Each playbook is *symptom → how to confirm → what to do*.
replay**.
- **Do** Recovery is explicit. Inspect what completed; retry only when the server is
healthy and the previous attempt's cleanup has stopped. Never restart a server that
has runs in flight — quiesce first (`references/lanes.md`). Keep the interrupted run
has runs in flight — quiesce first (`references/queue.md`). Keep the interrupted run
as history; never describe a restart, retry or cancellation as rollback.
## Screenshot capture that silently produces non-images
@@ -130,13 +130,13 @@ Each playbook is *symptom → how to confirm → what to do*.
approval. Put the capture helper in the repository so every UI run reuses one path.
See the example in `references/delivery.md`.
## Duplicated work after a lane or chain restart
## Duplicated work after a driver restart
- **Symptom** Items already completed run again after a lane or chain script
- **Symptom** Items already completed run again after a queue driver
restarts: the same brief is re-invoked, side effects repeat, or a commit is made
twice.
- **Confirm** Compare the lane's list against its completed-items record. A list alone
- **Confirm** Compare the queue's items against their recorded state. A list alone
has no resume point.
- **Do** Persist a cursor and resume from it (`references/lanes.md`). Record an item
- **Do** Record each item's state in the queue itself (`references/queue.md`) and resume from it. Record an item
only once it has landed, and skip recorded items on startup. Never relaunch a
duplicate of a run that is still active — reattach with its request key instead.
+3 -4
View File
@@ -45,8 +45,8 @@ with its own rules.
## Install and deploy boundaries
- **Installing onto the operator's physical device is the operator's job, not a
run's.** A run may install only on the emulator or device its lane owns
(`references/lanes.md`).
run's.** A run may install only on the device its brief names
(`references/queue.md`).
- **Restarting, rebuilding or reconfiguring the Pipelines/OpenCode service is the
operator's job.** A run may not stop a server another run depends on.
- A run may build and publish; it may not deploy a service, install to hardware the
@@ -72,8 +72,7 @@ This repository's Android client is delivered as a debug APK:
`--check <file.png>` to re-validate); it captures on the device, pulls and checks
the PNG magic bytes, deleting a file that is not a real image. Never write
`adb ... screencap` to a file through `exec-out` or a redirect.
- The lane's emulator serial is fixed per lane (for example `emulator-5554` for one
lane, `emulator-5556` for another); the operator's attached Pixel is never the
- The device serial is named per item in its brief; the operator's attached device is never the
runs' device.
- This is the concrete instance of the general rules above; a different project
substitutes its own build artefact, capture tool and device, and keeps the naming
+3 -2
View File
@@ -238,8 +238,9 @@ This list is the canonical checklist. The bundled starters `task`, `three-stage`
`docs-fold` each repeat it in their committer prompt because a template is embedded and
published on its own; keep those copies in sync with this list.
Merging is the operator's or a lane's job, not the committer's: it commits locally
and stops (`references/orchestration.md`, `references/lanes.md`). The server does
The committer commits **and lands** its own work: it merges main into its branch, resolves any
conflict there, then merges the branch into main and verifies its ancestry
(`references/queue.md`). There is no separate merger stage or resolver pipeline. The server does
not create the commit and cannot enforce the message; a reviewer checks the rules.
Malformed final JSON has bounded recovery even with `retries=0`; it never changes
-81
View File
@@ -1,81 +0,0 @@
# 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 `main` into 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 `main`
while a run is using `main`'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 `done` file. 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` (branch `lane-app2`) and `lane-go` (branch `lane-go`) under
the temp directory, with a third main lane in `/Users/alan/repos/pipelines`.
- Emulator ownership: lane A uses `emulator-5554`, lane B uses `emulator-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
`main` when 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.
@@ -33,8 +33,8 @@ each**.
unrelated changes into one run; a run whose reviewer is arguing about two
independent changes is unreviewable.
- State dependencies and ordering: which items must land first and which are
independent. Independent items may go to parallel lanes
(`references/lanes.md`); dependent items run in order.
independent. Independent items run in parallel, each in its own worktree
(`references/queue.md`); dependent items run in order.
- Prefer more, smaller items to fewer large ones: a smaller item is cheaper to
review, cheaper to retry, and less likely to loop back through the reviewer.
@@ -80,7 +80,7 @@ not run.
Constraints: <scope: the one subtree or package this item may touch>; no new
dependencies; do not restart, rebuild or reconfigure the Pipelines or OpenCode
server, the installer, the ntfy service or any other service - runs and lanes are
server, the installer, the ntfy service or any other service - runs are
active; never install on the operator's physical device; keep geometry and values
from their single existing sources rather than new literals; commit locally only,
never push; record a documentation note in `docs/notes/<slug>.md` rather than editing
@@ -89,7 +89,7 @@ a shared document; <the item's publishing rules>.
Requirements must be concrete and checkable. Name files, functions, commands, and
the existing helpers to reuse. State what must survive — existing behaviour, other
lanes' work. If a requirement cannot be checked by a command or by an image a
the other items' work. If a requirement cannot be checked by a command or by an image a
reviewer can open, it is not evidence: rewrite it.
Do not write a brief that asks a stage to do a vague job ("make the UI better"). A
@@ -102,10 +102,10 @@ Adapt the scope and publishing lines per item; keep the rest.
- **Scope** — the single subtree or package the item may touch, and nothing else.
- **No new dependencies** unless the brief argues the exception in-line.
- **Do not restart, rebuild or reconfigure** the Pipelines server, the CLI, the
installer, the OpenCode service or ntfy, and do not touch another lane's worktree
installer, the OpenCode service or ntfy, and do not touch another item's worktree
or device.
- **Never install on the operator's physical device** — only the lane's own emulator
or device (`references/lanes.md`).
- **Never install on the operator's physical device** unless the brief says so — use the device
the brief names and no other (`references/queue.md`).
- **Keep values from single sources** — geometry, tokens, sizes and constants come
from the source that already owns them, not from new literals.
- **Commit locally only, never push** — the committer stage commits, no other stage.
+74
View File
@@ -0,0 +1,74 @@
# 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.
+7 -7
View File
@@ -6,12 +6,12 @@ pauses, resumes and reports that ledger. Nothing important lives only in the
conversation: running the skill again, in any project on this machine, reads the
ledger and continues. This is the multi-project lifecycle on top of
`references/orchestration.md` (work items, briefs, pipeline choice) and
`references/lanes.md` (parallel workspaces).
`references/queue.md` (parallel items).
## Where the ledger lives
Keep state **outside repositories**, under one work root, so it never collides with a
lane's tree or a commit:
item's worktree or a commit:
${XDG_STATE_HOME:-$HOME/.local/state}/pipelines/work/
registry.json every project this machine knows
@@ -27,7 +27,7 @@ lane's tree or a commit:
PAUSED marker: stop dispatching new items
- `<slug>` is `<basename>-<8 hex of sha256(absolute project root)>`. **Resolve a
worktree to its main repository** so a lane shares the project's one ledger.
worktree to its main repository** so every item shares the project's one ledger.
- `PIPELINES_WORK_DIR` overrides the work root. `registry.json` maps projects to
roots; add a project the first time it is worked on and keep it current.
- `state.json` holds `project`, `root`, `endpoint` (the CLI's `--url`), `pipeline`
@@ -71,12 +71,12 @@ Write every brief exactly as `references/orchestration.md` describes. A brief fi
`queue/` may open with up to three directive lines, stripped before the prompt is sent:
# pipeline: Focused tweak - implement review commit
# workspace: /path/to/lane-app2
# workspace: /path/to/item-worktree
# device: emulator-5556
Goal: …
`pipeline` overrides the default for that item; `workspace` routes an item to a lane's
`pipeline` overrides the default for that item; `workspace` routes an item to its own
checkout (a driver only claims items for its own workspace); `device` is for the
brief's own text. Number briefs `0001-…`, `0002-…` so order is explicit.
@@ -86,7 +86,7 @@ A queue is advanced by a small driver, so work continues while the operator slee
Write the driver once per project to `drivers/workd.sh` and launch it; it is
restart-safe (it resumes from `done/`, reattaches to `active/` runs by id, and never
starts a duplicate), and it stops on the first item that fails twice. Run **one
driver per workspace**; several drivers sharing one queue advance different lanes in
item at a time per worktree**; several items in their own worktrees advance in
parallel because an item is claimed by an atomic rename.
```sh
@@ -97,7 +97,7 @@ parallel because an item is claimed by an atomic rename.
#
# PROJECT_ROOT identifies the ledger (default: the current directory).
# WORKSPACE is the checkout this driver may run in (default: the ledger's
# workspace). One driver per workspace lets several lanes advance one shared
# workspace). One item per worktree lets several items advance against one shared
# queue: an item is claimed by an atomic rename, so it runs exactly once.
#
# Restart-safe. It resumes from done/, reattaches to active/ runs by id and