01d5dad9b9
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.
4.6 KiB
4.6 KiB
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
maininto its branch, resolves any conflict there with the context of the change it just made, runs the checks again, then merges the branch intomainand 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 --yesfrom 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.