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.
2.8 KiB
Pipelines maintenance
Consent (hard rule)
The operator owns this system. No change to it happens without their explicit consent in the current conversation: new pipelines or versions, definition and stage-prompt edits, orchestration scripts, briefs and the conventions they carry, the packaged skill and templates, deploys, installs and deletions. Read-only investigation and reporting need no consent. Ask first and name exactly what would change; a request for a fix is not consent for a particular mechanism.
When a change alters user-facing behavior, or you learn a confirmed runtime
limitation, record the stale documentation instead of editing the shared document in
the same change: leave a per-item note at docs/notes/<slug>.md naming what changed and
which packaged OpenCode skill reference in internal/author/skill/references/, README
or topic doc is now stale and what should change there. The manual-only docs-fold
pipeline folds docs/notes/ into the shared docs and references; an item never edits a
shared document itself. Keep SKILL.md a concise,
task-directed index: preserve ask-first authoring and never preload every reference.
Separate current capabilities, dated verification evidence, deployment state and
unimplemented ideas. Do not turn mocked or structural checks into live claims.
For new references, update internal/author/install.go's managed file inventory.
Run the author package tests: they check embedding, reference links, installation,
upgrades and protection of user modifications. Never hand-edit an installed copy
as the source of truth; refresh it with the current-source pipelines skill install
only when installation is requested. Do not deploy runtime changes merely because
the skill is updated. Keep the shared docs and packaged references consistent through
the single docs-fold writer rather than editing them per item: leave a
docs/notes/<slug>.md note.
Maintenance workflow
Top-level agents advance work through the pipelines CLI; the agent is the brain
and there is no orchestration script, driver, polling loop or lane machinery, and none
may be written. Choose the pipeline by the area the work is in — Android, TUI,
Server, Generic, Plan and land, UI sweep, Probe — each reading the project's
own map (android/AGENTS.md, internal/tui/AGENTS.md, internal/server/AGENTS.md)
for how that technology is built, tested, run and captured. Inspect the retained
plan/implement/review outputs and diffs, execute the checks independently, and iterate
on concrete failures rather than trusting stage summaries. An executing stage performs
its own role directly and never recursively launches a workflow. If a pipeline is
unavailable, ask instead of silently bypassing it. Never hardcode a disposable server
URL as a project default; the configured endpoint is authoritative.