Skip to main content

​
Order Books

An order book is an operator-curated Flywheel campaign. It replaces a prose list of “special orders” with a durable queue whose lane capacity, prerequisites, planning checks, pickup posture, and completion rules Overdeck enforces. Use an order book when the sequence matters: a migration campaign, a refactor that must stay behind a serial gate, or a release-hardening run whose scope must not expand into the normal backlog. The design mockup shows the core model: Lane A overlaps up to its configured limit, Lane B admits one issue at a time, and DRAIN stops new pickup while in-flight work finishes.

​
Order books and the backlog

The backlog sequencer is Overdeck’s ranked pool of possible work. An order book is a deliberate subset with explicit execution order. Membership in the active book counts as operator release, even when:
That setting still holds every off-book issue. The Flywheel can work through the book without opening the rest of the backlog.

​
Build a book

Open Order Book in the dashboard, or go directly to /orders.
  1. Click + New book, enter a name, and create the draft.
  2. Add open issues from search or from the ranked backlog-candidates rail. Adding an issue changes the plan only; it does not dispatch work.
  3. Put parallel-safe work in Lane A. Put work that must serialize against the same subsystem in Lane B.
  4. Drag rows to change lane order, or use the lane-swap action to move an issue between A and B.
  5. Set Lane A concurrency and, when needed, an optional brief-overlay path.
  6. Resolve every blocking validation finding, then click Queue book. A queued book is ready.
  7. Click Start run when the book should become the active Flywheel campaign.
The book strip keeps drafts, queued books, the active book, and completed history together. The lifecycle strip marks the current state:

​
Add from other surfaces

You can promote an issue without leaving its current view:
  • Add to order book appears in the shared issue action menu used by the board and issue drawer.
  • Backlog rows expose + Order book and ask only whether the issue belongs in Lane A or Lane B.
These are narrow add actions. Editing, validation, settings, ordering, and lifecycle controls remain on /orders.

​
Read the page

​
Pickup posture

OPEN permits eligible book items to dispatch and renders blue-tinted — dispatch is live, machine working. DRAIN blocks every new book dispatch and renders amber — a human paused pickup. Work already in the pipeline continues toward a terminal state. Run settings always show posture attribution — who set it, when, and why — beneath the posture control, regardless of which posture is active. If the recorded reason predates the current posture (for example, a leftover “Operator paused new pickup.” reason after reopening), an amber stale-reason flag calls that out.

​
Lane A

Lane A is parallel. The Lane A concurrency setting controls how many Lane A issues may be in flight at once. A new dispatch is refused when that count is full.

​
Lane B

Lane B is strictly serial. A second Lane B issue cannot start while another Lane B item is in flight. Each compact row leads with the lane position, such as B11 · book, then the issue id. Rows also show prerequisite, PRD, and re-verification state.

​
Start validation

The validation panel separates blockers from warnings. Start is blocked when:
  • an issue is closed or cannot be resolved as open;
  • an issue belongs to another non-complete book;
  • a prerequisite is missing;
  • prerequisites form a cycle; or
  • a Lane B issue has no draft PRD or canonical spec.
A Lane B issue marked for planning at pickup turns the missing-PRD result into a warning. Warnings stay visible but do not prevent queueing or starting. Use Preview brief to inspect the scope that the Flywheel will receive before the run starts.

​
Setup and Progress

Setup contains the book editor, run settings, add rails, and validation. Run settings save automatically per field: each field shows its own saved or error state beside its label, and a failed save offers Retry rather than silently discarding the change. Progress turns the book into a live checklist. For held issues it shows the same mechanical conditions used by the server dispatch gate:
  • book membership;
  • OPEN or DRAIN pickup posture;
  • a free lane slot;
  • terminal prerequisites; and
  • completed PRD re-verification.
The Flywheel page and issue tree also show read-only order-book projections. Those projections link to /orders?project=<key> for the project the book actually lives in, so the link lands on the right books.

​
Pick the project

Order books are per-project state, and the page header carries a Project picker listing every project Overdeck has registered. It opens on the project the server resolved for you, and choosing another one reloads the page against that project’s books — every read and write the page makes is scoped to the selection, so you cannot edit one project’s book while looking at another’s. The selection is mirrored into the URL as /orders?project=mind-your-now, which makes it a shareable deep link: opening that URL selects the project before the first load. Without the parameter the page shows the project containing the dashboard server’s own working directory, exactly as it did before.

​
Use the CLI

The dashboard is the complete editor, but the CLI covers common create, inspect, lane, and start operations:
add defaults to Lane A. --after <issue> inserts after an existing item in the target lane. --reverify keeps the issue held until its PRD has been checked against current main. Queue the validated draft from /orders or from the terminal, then start it with either command:
queue is the CLI form of the dashboard’s Queue book action — it moves a draft to ready so the Flywheel can pick the book up from the ready queue. It refuses a book that is not a draft rather than re-queueing a running or completed campaign. Both start commands use the same validator and singleton Flywheel run gate. If validation or gate acquisition fails, the book remains ready.

​
Work on another project’s books

Every pan orders verb takes --project <key>, naming a project from your registry, so you do not have to cd into a project to manage its campaign:
Without the flag, the command resolves the project that contains your current directory, as before. An unregistered key fails with Unknown project: <key> instead of reporting the book as missing.

​
What drained means

A book is drained only when every item is terminal. For order-book progress, terminal means either:
  • the issue is closed; or
  • the issue is parked with a recorded reason.
The server derives this result from canonical issue state. The orchestrator cannot declare a book drained through prose or a status message. When the Progress view reports drained, complete the run:
The command refuses a non-drained book and names every remaining issue. --force exists for an intentional operator override:

​
Retrospectives

If the run exposed a concrete improvement, write it to:
Useful findings include a doctrine correction, a substrate bug to file, or a brief-template change. pan flywheel complete adds the file under ## Retrospective in the run report. When there is no finding, do not invent a ceremony. The report records:

​
What happens after completion

pan flywheel complete writes the report, clears the active-run gate, marks the current book complete, and chooses the next action mechanically: This continuation happens in the existing persistent Flywheel path; it does not create a one-shot agent. Continuation looks across projects, not only the one that just finished: when the completing project’s queue is empty, Overdeck checks every registered project in registry order and starts the first ready book it finds, in that project’s own repo and with that project’s flywheel brief. pan flywheel complete names the project when this happens, so the output reads started RUN-42 with order book 2026-08-01-frontend-sweep (project: mind-your-now). This scan is not limited by the finished run’s scope. Marking a book ready is your explicit release of that work, so a ready book anywhere is already authorized; scope only governs whether the Flywheel may pull unlisted issues from the backlog. If you do not want a queued book to start automatically, leave it as a draft until you do.

​
Intentional off-book work

During an orders-bound run, Overdeck rejects work-agent dispatch for issues outside the book. If the exception is deliberate, the operator can use:
Overdeck records every accepted exception in the run’s orders-overrides.jsonl. The override applies to that dispatch only; it does not release the backlog.