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

12 KiB

Orchestrate work through runs

When the operator asks for a change to this project, the agent's product is a set of briefs and a set of managed runs, not the change itself. The implementer stage makes the change; the reviewer stages check it; the committer stage commits it. Route all project work through Pipelines runs.

The agent advances this by hand through the pipelines CLI: it launches each run, is woken when it finishes, reconciles against the server, and starts the next item. There is no orchestration script, driver, polling loop or lane machinery, and none may be written.

Stance

  • Reconnoitre first. Read enough of the repository, its notes and recent history to write a truthful brief: name the exact files, functions, commands and existing helpers the change touches. Do not guess and do not hand-roll the change to avoid reading.
  • Then route every work item through a run. Do not edit the project's files yourself, not even a one-line unblock. A hand edit has no brief, no independent review and no recorded run, so nothing about it can be reviewed or trusted.
  • Fix the cause, not the symptom. When a run wedges, fix the pipeline definition, the stage configuration or the Pipelines/harness service. Do not reach around a stuck stage and finish its work by hand. Diagnose with references/debugging.md.
  • The agent decides scope, decomposition, pipeline choice and what to publish; the operator owns the decisions a run cannot make — which items to accept, what to publish, when to restart a service, when to install on real hardware. Ask only for those.

Work items

Decompose the request into single-purpose items, roughly an hour of agent work each.

  • One item is one coherent change with its own brief, its own evidence and its own review, so the operator can review it on its own.
  • One item = one run = one commit (the committer stage commits). Do not batch 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 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.

The brief

A brief is the entire task a run receives. The run does not see this conversation, the operator's intent beyond the brief's words, or any context that is not on disk. Write it self-contained.

Every brief has:

  1. Goal — one line naming the change.
  2. The observed problem — what is wrong today and why it matters, in the repository's own terms, naming the exact files, commands or runs.
  3. Requirements — a short bulleted list of the exact behaviour, the surfaces it touches, and every constraint the change must honour.
  4. Falsifiable evidence required — the exact commands the run must run and the output it must report, plus the screenshots the reviewer must read. Say plainly: "report the exact commands and their observed results. Do not claim a check you did not run."
  5. Documentation note — where the change makes shared documentation stale, the item records that in its own per-item note docs/notes/<slug>.md: what it changed and which shared document (a README or topic doc, or a packaged skill reference) is now stale and what should change there. The item writes only its note; it must not edit a shared document. See "Single documentation writer" below.
  6. The hard constraints block (below).
  7. Publishing rules (references/delivery.md).

Template:

<one-line goal: the change, in the repository's own words.>

<what is wrong today and why it matters; name the exact files, commands or runs.>

- <requirement 1: the behaviour and the surface it touches>
- <requirement 2>
...

Evidence: <exact build/test commands> and <the screenshots or captures asked for>;
report the exact commands and their observed results. Do not claim a check you did
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 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
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 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 reviewer cannot falsify it and the run will drift. One item, one observable outcome.

Hard constraints to carry into every brief

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 item's worktree or device.
  • 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.
  • Record stale documentation; do not rewrite it — before committing, the committer ensures the item's docs/notes/<slug>.md note, when the change makes a shared document stale, is staged with the change, and states in the commit body what it checked. The committer never edits a shared document (a README or topic doc, or a packaged skill reference) itself; the single documentation writer folds notes later.
  • Publish rules — WIP artefact naming and LAN URLs per references/delivery.md.

Single documentation writer

Shared documentation — the repository's READMEs and topic docs (for this repository android/README.md and docs/cli.md) and the packaged skill references in internal/author/skill/references/ — has exactly one writer, never an item. Each item that makes one of these stale leaves a note at docs/notes/<slug>.md (item 5 above). The note's filename is unique per item, so two items never write the same file and never conflict on prose.

The writer is the manual-only docs-fold pipeline, bundled as the starter examples/docs-fold.md. Its fold stage reads every note under docs/notes/, folds each into the shared document it names, and deletes the consumed notes in its own commit; an empty docs/notes/ is a success no-op with no empty commit. It is never scheduled and is never part of a per-item workflow.

The operator triggers it deliberately:

pipelines new "Docs fold" --template docs-fold --no-open
pipelines submit <draft.md>
pipelines run "Docs fold"

Pipeline choice

Choose by the area the work is in; each area pipeline reads the project's own map for its build, test, run and capture commands:

  • Android — android/.
  • TUI — internal/tui/.
  • Server — internal/server/, internal/stage/, internal/pipeline/ and internal/protocol/.
  • Generic — only when a change genuinely spans areas.
  • Plan and land — when the change needs a plan before implementation (contract-level work).
  • UI sweep — a full-screen review pass.
  • Probe — a harness smoke check.

The retired names (Pipelines quick/maintenance/critical, Focused tweak, Quick tweak, Plan, implement, review, Harness probe) stay in the registry because definitions are immutable, but nothing should start them. If a pipeline is unavailable, ask instead of silently bypassing it.

  • Use a pipeline that keeps implementer + reviewer + ui_reviewer + committer for anything that matters. The planner is the only stage a leaner variant may drop.
  • Never remove a review stage to go faster. The reviewer stages are the independent evidence the operator reviews against; dropping them is exactly how a regression ships unreviewed.
  • The ui_reviewer must build, capture and read the actual screenshots, or return skipped with a reason when the change has no rendered surface. Never accept a UI change approved without the images.
  • The committer is the only stage that commits, and it stages only the run's changed files. Before committing it ensures the item's docs/notes/<slug>.md note, when the change makes a shared document stale, is staged with the change, and states in the commit body what it checked; it never edits a shared document (a README or topic doc, or a packaged skill reference) itself, because a single documentation writer folds notes later. It must also select input.server_changed_files (the runner's captured evidence, references/control.md) alongside the implementer's declared changed_files and stage their union: an implementer's declared list can be incomplete, and a captured path it omitted is still this run's change. Its prompt carries the pre-commit checklist in references/format.md; it commits locally and stops, never pushing.
  • A run cannot approve its own work. When an item genuinely needs an operator gate before it continues or commits, insert a type=human decision stage (references/format.md); never invent a model stage that pretends to approve.
  • Pick the pipeline whose area matches the change (above); Generic only when a change genuinely spans areas. A logic, server or format change usually wants the planner (Plan and land); a small, fully understood tweak may use the leaner area pipeline. Both keep all review stages.

Running and watching

  • Launch with the authoritative CLI_PREFIX (pipelines run). The brief text is the run's task; pass it whole. Read references/operations.md for the exact flags — --json, confirmation (--yes) and --wait/--wait-timeout.
  • Model overrides at launch. Use --model PROVIDER/MODEL to override the model for every model stage of that run, and repeatable --stage-model STAGE=PROVIDER/MODEL to override individual stages. Precedence is per-stage > whole-run > the model pinned in the pipeline version. Overrides apply to that run only (the pinned pipeline is never edited), are validated before the run starts, and are recorded on the run; retry reuses them. See references/harnesses.md for how a stage's model and its repair path both use the effective model.
  • Watch to a terminal state (succeeded, failed, canceled, interrupted). Progress is event-driven, never polled: CLI_PREFIX 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; CLI_PREFIX inspect RUN_ID --json then reads the retained outcome. A reached client wait limit is not a run failure: the run stays active; keep waiting or reattach with the original request key, never start a duplicate run. Do not build a polling loop, a cursor file or a driver script to answer "is it done yet".
  • Read the outcomes, not just the status: the option each stage returned, the evidence it recorded, and any run or step diagnostic. Interpret diagnostics by category (references/debugging.md).
  • Retry once, then record and continue. Retry a failed or interrupted item at most once. If it fails again, record the brief as failed and move to the next item; never loop or start duplicates to force a pass.
  • Stop the chain on failure and verify by hand. Do not push the next item on top of a broken tree. Inspect the failure, fix the pipeline or service cause, and verify the tree by hand before continuing. Report the failure; never hide it by re-running until something passes.

What the operator reviews

From the run record alone, the operator must be able to see: the brief, the changed files and diff, the reviewer's exact commands and observed results, the screenshots the visual reviewer read, and the commit. Produce those, and say plainly what was not tested (references/verification.md).