Rewrite the workflow documentation to describe how the system actually works: the agent (the session) is the brain and advances the queue by hand through the `pipelines` CLI. There is no orchestration script, no driver, no polling loop and no lane machinery, and none may be written. - references/work.md: rewritten end to end. The queue-driver script (drivers/workd.sh), the claim-file ledger with atomic renames, the PAUSED marker and the poll loop are gone. State is now the server (authoritative for run state), the queue file (authoritative for intent) and the conversation. The agent reads the queue, picks the item, creates its worktree/branch and launches it with `pipelines run <pipeline> <brief> --json --yes`; progress is event-driven via a background `pipelines wait <run-id> [...]` (never polled); on completion the agent reconciles with `pipelines inspect <run-id> --json`, verifies it landed and starts the next item. - references/queue.md: the landing gate runs the command directly (`git merge-base --is-ancestor <branch> main`, exit 0 = landed) instead of a `land-check.sh` helper; the never-delete-branch / never-remove-worktree rules are kept, and the waiting section states the agent advances the queue by hand. - references/orchestration.md: intro and "Running and watching" state the agent-driven, event-driven model; "Pipeline choice" names the current set (Android, TUI, Server, Generic, Plan and land, UI sweep, Probe) by area and records the retired names. - references/debugging.md: "Duplicated work after a driver restart" became "…after a session restart", resuming from the queue file not a cursor file. - SKILL.md: the routing row no longer says "queue driver". - AGENTS.md: the maintenance workflow names the current pipeline set instead of the retired `Pipelines maintenance - plan implement review`. - internal/tui/AGENTS.md: the restart line no longer names lanes. - docs/notes/agent-driven-work-model.md: the docs-fold note recording that docs/cli.md needs its "Scripted runs"/`--wait` framing aligned to the event-driven model, and that the dated evidence docs stay as they are. Checked before committing: no packaged template directory exists in this repo, so none needed updating; internal/author/install.go's managed file inventory needs no change (no packaged reference was added or removed — the 13 listed files all match internal/author/skill/references/); no stale `queue driver`/`workd.sh`/ `claim-file` references remain anywhere under internal/author. Genuine device tooling (android/scripts/capture_png.sh-style) and server-side polling prose were left alone. Checks: `go test ./internal/author -count=1` ok; `go build ./...` clean; `go vet ./...` clean; `gofmt -l .` clean.
8.0 KiB
Project work ledger and sessions
Work in a project is not a chat. It is a durable ledger: what is queued, what is running, what has landed, and what is blocked. A session — this conversation — reads the ledger, launches the runs, is woken when they finish, and reports.
The agent is the brain. It advances the queue by hand through the pipelines
CLI: it reads the queue, picks the item, launches the run(s) itself, is woken when they
finish, reconciles against the server, and starts the next item. There is no
orchestration script, no driver, no polling loop and no lane machinery, and none may be
written. Where a check is needed, run the command directly.
State lives in exactly three places:
- the server is authoritative for run state —
pipelines inspect <run-id> --json; - the queue file is authoritative for intent — what is queued, in what order, and what is finished;
- the conversation holds this session's working memory.
Never keep progress in a script's own files. A session that dies and comes back reads
the queue file and continues. This is the multi-project lifecycle on top of
references/orchestration.md (work items, briefs, pipeline choice) and
references/queue.md (parallel items, one worktree per item, landing).
Where the ledger lives
Keep state outside repositories, under one work root, so it never collides with an item's worktree or a commit:
${XDG_STATE_HOME:-$HOME/.local/state}/pipelines/work/
registry.json every project this machine knows
projects/<slug>/
queue.md the project's markdown queue: items, briefs, state
notes.md recon, decisions, open questions, blockers
<slug>is<basename>-<8 hex of sha256(absolute project root)>. Resolve a worktree to its main repository so every item shares the project's one queue.PIPELINES_WORK_DIRoverrides the work root.registry.jsonmaps projects to roots; add a project the first time it is worked on and keep it current.queue.mdis the resume point (references/queue.md): read it top to bottom and take the first unfinished item.notes.mdis the operator's record: keep it truthful about decisions taken and left open, never narrate it as a diary.- The CLI's configured endpoint and the area map's default pipeline come from the CLI and the project's own map, not from a script. Do not write a per-project state file for a script to read.
Operations
Map one operator sentence to one operation. Do the operation, then answer with the status block — nothing else. You launch the runs yourself; nothing else does it.
| Operator says | Do |
|---|---|
| start / work on X | Reconnoitre, register the project, write the queue file, then launch the first item's run yourself. |
| status / how is it going | Read the server and the queue, then print the status block. |
| queue "…" / add … | Reconnoitre, split into small items, append them to the queue file, launch what is ready. |
| pause / stop for now | Launch nothing new. The runs already in flight finish; reconcile them when they do. |
| resume / continue | Reconcile against the server, then launch the next item. |
| drop item N | Mark its item failed in the queue file with a reason. Never silently delete work. |
| done / stop everything | Stop launching, wait for what is in flight, and report what landed and what remains. |
Reconcile before acting, always. The server is authoritative for run state; the
queue file is authoritative for intent. On every invocation: read the project's
queue.md; for each item marked running, pipelines inspect <run-id> --json and settle
it (running → keep waiting; succeeded → verify it landed and mark it done;
failed/interrupted → mark it failed with the diagnostic). Only then do the requested
operation. Never trust your memory of a run's status, and never start a second run for
an item whose request key is already admitted — reuse the original --request-key so a
redispatch attaches instead of duplicating.
Status block (these lines, no prose around them):
pipelines — active
queue: 4 pending · 1 running (run 185 · reviewer · 6m) · 12 done · 2 failed
next: 0005-graph-arrows on "TUI"
blocked: none
The brief, and per-item directives
Write every brief exactly as references/orchestration.md describes. An item in
queue.md may open its brief with up to three directive lines, stripped before the
prompt is sent:
# pipeline: TUI
# workspace: /path/to/item-worktree
# device: emulator-5556
Goal: …
pipeline overrides the default for that item; workspace names the item's own
worktree (create it with git worktree add -b <item> <path> main, references/queue.md);
device is for the brief's own text. Number items 0001-…, 0002-… so order is
explicit.
Advancing the queue by hand
There is no driver. You advance the queue yourself, through the CLI:
- Read the queue top to bottom and take the first unfinished item.
- Choose the pipeline by area (
references/orchestration.md):Android,TUI,Server,Generic,Plan and land,UI sweep,Probe. Each area pipeline reads the project's own map for its build, test, run and capture commands. - Create the item's worktree and branch:
git worktree add -b <item> <path> main. One worktree per item is what lets independent items run at once without the workspace guard becoming a bottleneck (references/queue.md). - Launch the run from that worktree:
pipelines run <pipeline> <brief> --json --yes. Keep the returned run id. - Be woken when it finishes — do not poll.
pipelines wait <run-id> […]blocks until the runs are terminal and is run as a background task, so the session is woken exactly when the batch finishes — or arm a timer and check on the tick. No polling loop, no cursor file, no driver script, ever. - Reconcile.
pipelines inspect <run-id> --json; read the outcomes and evidence; verify the branch landed withgit merge-base --is-ancestor <branch> main(exit 0 = landed); mark the item inqueue.md; then start the next item — or several independent items at once.
Parallelism is your judgement, bounded by real conflicts only: two items editing the same files at once, the one capture device, or the provider's spend cap. Launch as many independent runs as the machine can carry without overload; serialise only for a real conflict and say which limit is binding. Never present serialisation as the operator's decision.
Landing stays the pipeline's job: the committer stage merges and lands its own
work. There is no merger, no resolver and nothing to hand to a script. You verify the
landing gate (references/queue.md); you do not perform the merge.
Sleeping and waking
- Before the operator sleeps: reconcile, make sure the queue has enough items to cover
the night, and launch what is ready with a background
pipelines wait. - Configure a failure notification (
references/notifications.md) so a failed run is not silent. A run that fails is recorded and the next item starts; do not add retry loops to make it look busy. - On waking, reconcile first, then answer with the status block: what landed, what failed and why, what is next.
Conciseness
The operator wants the result, not the shift report.
- Match the answer's length to the question. A yes/no or one-line question gets one or two sentences; never answer a narrow question with a sectioned report.
- Answer the question that was asked first. Put any extra fact that changes a decision in a single clause, not in a new section.
- Answer with the status block for status; do not narrate waiting or re-print the queue when nothing changed.
- Report a run by its outcome and evidence (
references/verification.md), not the steps you took to watch it. - Ask only for a decision the operator owns (accept, publish, restart, install). Batch the day's questions rather than asking per item.
- Never claim a check, build or screenshot you did not run.