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.
79 lines
4.6 KiB
Markdown
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.
|