Files
pipelines/internal/author/skill/references/work.md
T
alan 01d5dad9b9 docs: describe the agent-driven workflow, drop the scripted driver model
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.
2026-10-18 01:50:55 +01:00

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_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.
  • queue.md is the resume point (references/queue.md): read it top to bottom and take the first unfinished item. notes.md is 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:

  1. Read the queue top to bottom and take the first unfinished item.
  2. 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.
  3. 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).
  4. Launch the run from that worktree: pipelines run <pipeline> <brief> --json --yes. Keep the returned run id.
  5. 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.
  6. Reconcile. pipelines inspect <run-id> --json; read the outcomes and evidence; verify the branch landed with git merge-base --is-ancestor <branch> main (exit 0 = landed); mark the item in queue.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.