# 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 --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// queue.md the project's markdown queue: items, briefs, state notes.md recon, decisions, open questions, blockers - `` is `-<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 --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 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 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 --json --yes`. Keep the returned run id. 5. **Be woken when it finishes — do not poll.** `pipelines wait […]` 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 --json`; read the outcomes and evidence; verify the branch landed with `git merge-base --is-ancestor 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.