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.
152 lines
8.0 KiB
Markdown
152 lines
8.0 KiB
Markdown
# Project work ledger and sessions
|
|
|
|
Work in a project is not a chat. It is a durable ledger: what is queued, what is
|
|
running, what has landed, and what is blocked. A session — this conversation — reads
|
|
the ledger, launches the runs, is woken when they finish, and reports.
|
|
|
|
**The agent is the brain.** It advances the queue by hand through the `pipelines`
|
|
CLI: it reads the queue, picks the item, launches the run(s) itself, is woken when they
|
|
finish, reconciles against the server, and starts the next item. There is **no
|
|
orchestration script, no driver, no polling loop and no lane machinery, and none may be
|
|
written.** Where a check is needed, run the command directly.
|
|
|
|
State lives in exactly three places:
|
|
|
|
- the **server** is authoritative for run state — `pipelines inspect <run-id> --json`;
|
|
- the **queue file** is authoritative for intent — what is queued, in what order, and
|
|
what is finished;
|
|
- the **conversation** holds this session's working memory.
|
|
|
|
Never keep progress in a script's own files. A session that dies and comes back reads
|
|
the queue file and continues. This is the multi-project lifecycle on top of
|
|
`references/orchestration.md` (work items, briefs, pipeline choice) and
|
|
`references/queue.md` (parallel items, one worktree per item, landing).
|
|
|
|
## Where the ledger lives
|
|
|
|
Keep state **outside repositories**, under one work root, so it never collides with an
|
|
item's worktree or a commit:
|
|
|
|
${XDG_STATE_HOME:-$HOME/.local/state}/pipelines/work/
|
|
registry.json every project this machine knows
|
|
projects/<slug>/
|
|
queue.md the project's markdown queue: items, briefs, state
|
|
notes.md recon, decisions, open questions, blockers
|
|
|
|
- `<slug>` is `<basename>-<8 hex of sha256(absolute project root)>`. **Resolve a
|
|
worktree to its main repository** so every item shares the project's one queue.
|
|
- `PIPELINES_WORK_DIR` overrides the work root. `registry.json` maps projects to
|
|
roots; add a project the first time it is worked on and keep it current.
|
|
- `queue.md` is the resume point (`references/queue.md`): read it top to bottom and
|
|
take the first unfinished item. `notes.md` is the operator's record: keep it truthful
|
|
about decisions taken and left open, never narrate it as a diary.
|
|
- The CLI's configured endpoint and the area map's default pipeline come from the CLI
|
|
and the project's own map, not from a script. Do not write a per-project state file
|
|
for a script to read.
|
|
|
|
## Operations
|
|
|
|
Map one operator sentence to one operation. Do the operation, then answer with the
|
|
status block — nothing else. **You launch the runs yourself**; nothing else does it.
|
|
|
|
| Operator says | Do |
|
|
| --- | --- |
|
|
| start / work on X | Reconnoitre, register the project, write the queue file, then launch the first item's run yourself. |
|
|
| status / how is it going | Read the server and the queue, then print the status block. |
|
|
| queue "…" / add … | Reconnoitre, split into small items, append them to the queue file, launch what is ready. |
|
|
| pause / stop for now | Launch nothing new. The runs already in flight finish; reconcile them when they do. |
|
|
| resume / continue | Reconcile against the server, then launch the next item. |
|
|
| drop item N | Mark its item failed in the queue file with a reason. Never silently delete work. |
|
|
| done / stop everything | Stop launching, wait for what is in flight, and report what landed and what remains. |
|
|
|
|
**Reconcile before acting, always.** The server is authoritative for run state; the
|
|
queue file is authoritative for intent. On every invocation: read the project's
|
|
`queue.md`; for each item marked running, `pipelines inspect <run-id> --json` and settle
|
|
it (running → keep waiting; succeeded → verify it landed and mark it done;
|
|
failed/interrupted → mark it failed with the diagnostic). Only then do the requested
|
|
operation. Never trust your memory of a run's status, and never start a second run for
|
|
an item whose request key is already admitted — reuse the original `--request-key` so a
|
|
redispatch attaches instead of duplicating.
|
|
|
|
Status block (these lines, no prose around them):
|
|
|
|
pipelines — active
|
|
queue: 4 pending · 1 running (run 185 · reviewer · 6m) · 12 done · 2 failed
|
|
next: 0005-graph-arrows on "TUI"
|
|
blocked: none
|
|
|
|
## The brief, and per-item directives
|
|
|
|
Write every brief exactly as `references/orchestration.md` describes. An item in
|
|
`queue.md` may open its brief with up to three directive lines, stripped before the
|
|
prompt is sent:
|
|
|
|
# pipeline: TUI
|
|
# workspace: /path/to/item-worktree
|
|
# device: emulator-5556
|
|
|
|
Goal: …
|
|
|
|
`pipeline` overrides the default for that item; `workspace` names the item's own
|
|
worktree (create it with `git worktree add -b <item> <path> main`, `references/queue.md`);
|
|
`device` is for the brief's own text. Number items `0001-…`, `0002-…` so order is
|
|
explicit.
|
|
|
|
## Advancing the queue by hand
|
|
|
|
There is no driver. You advance the queue yourself, through the CLI:
|
|
|
|
1. **Read the queue top to bottom** and take the first unfinished item.
|
|
2. **Choose the pipeline by area** (`references/orchestration.md`): `Android`, `TUI`,
|
|
`Server`, `Generic`, `Plan and land`, `UI sweep`, `Probe`. Each area pipeline reads
|
|
the project's own map for its build, test, run and capture commands.
|
|
3. **Create the item's worktree and branch**: `git worktree add -b <item> <path> main`.
|
|
One worktree per item is what lets independent items run at once without the
|
|
workspace guard becoming a bottleneck (`references/queue.md`).
|
|
4. **Launch the run from that worktree**:
|
|
`pipelines run <pipeline> <brief> --json --yes`. Keep the returned run id.
|
|
5. **Be woken when it finishes — do not poll.** `pipelines 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 — or arm a timer and check on the tick. No
|
|
polling loop, no cursor file, no driver script, ever.
|
|
6. **Reconcile.** `pipelines inspect <run-id> --json`; read the outcomes and evidence;
|
|
verify the branch landed with `git merge-base --is-ancestor <branch> main` (exit 0 =
|
|
landed); mark the item in `queue.md`; then start the next item — or several
|
|
independent items at once.
|
|
|
|
**Parallelism is your judgement, bounded by real conflicts only**: two items editing
|
|
the same files at once, the one capture device, or the provider's spend cap. Launch as
|
|
many independent runs as the machine can carry without overload; serialise only for a
|
|
real conflict and say which limit is binding. Never present serialisation as the
|
|
operator's decision.
|
|
|
|
**Landing stays the pipeline's job**: the committer stage merges and lands its own
|
|
work. There is no merger, no resolver and nothing to hand to a script. You verify the
|
|
landing gate (`references/queue.md`); you do not perform the merge.
|
|
|
|
## Sleeping and waking
|
|
|
|
- Before the operator sleeps: reconcile, make sure the queue has enough items to cover
|
|
the night, and launch what is ready with a background `pipelines wait`.
|
|
- Configure a **failure notification** (`references/notifications.md`) so a failed run
|
|
is not silent. A run that fails is recorded and the next item starts; do not add
|
|
retry loops to make it look busy.
|
|
- On waking, reconcile first, then answer with the status block: what landed, what
|
|
failed and why, what is next.
|
|
|
|
## Conciseness
|
|
|
|
The operator wants the result, not the shift report.
|
|
|
|
- Match the answer's length to the question. A yes/no or one-line question gets one or
|
|
two sentences; never answer a narrow question with a sectioned report.
|
|
- Answer the question that was asked first. Put any extra fact that changes a decision in
|
|
a single clause, not in a new section.
|
|
- Answer with the status block for status; do not narrate waiting or re-print the
|
|
queue when nothing changed.
|
|
- Report a run by its outcome and evidence (`references/verification.md`), not the
|
|
steps you took to watch it.
|
|
- Ask only for a decision the operator owns (accept, publish, restart, install). Batch
|
|
the day's questions rather than asking per item.
|
|
- Never claim a check, build or screenshot you did not run.
|