# 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 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 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 --json --yes` from that worktree. Nothing else advances it — there is no driver, and none may be written. - `pipelines wait […​]` 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.