Files
pipelines/internal/author/skill/references/queue.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

79 lines
4.6 KiB
Markdown

# 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**, verify
the branch is an **ancestor of main** directly, with no helper script:
`git merge-base --is-ancestor <branch> main` (exit 0 = landed).
- 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
- The agent advances the queue **by hand**: read it, create the item's worktree, and launch
`pipelines run <pipeline> <brief> --json --yes` from that worktree. Nothing else advances it —
there is no driver, and none may be written.
- `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.