The method#

A prep cook does the prep so the chef can cook. Prepcook does the prep on a bug — reproduces it, explains it, fixes it, reviews the fix, opens the pull request — and the engineer who owns the ticket signs off.

Prepcook works a bug the way a careful engineer would, in a fixed order: make it happen, explain it, fix the mechanism, have someone else check the fix, then ship it. Each step is a stage, each stage is a column on the board, and a card moves through them left to right:

To Do → Plan → Execute → Review → Shipped │ Clean up

Five columns and the Clean up rail. Some of what a card goes through is a state of the card rather than a column: an investigation that has posted its report is triaged and stays in Plan, and a card in Shipped has a pull request that is open, merged or closed without merging.

The orchestrator watches the columns from Plan onwards. When a card assigned to you enters one, it starts that stage's work: an agent session in the card's git worktree for Plan, Execute and Review, or its own work for Shipped and Clean up. To Do is where cards wait for a person to start them; a card waits for a person again when it is triaged, or when its pull request merged or closed. A forward move goes one column at a time; any card can be moved back, or straight to Clean up, which takes it only when its pull request merged, when it never had one, or — for one closed without merging — once a person confirms discarding the branch and worktree.

A card is in the workflow when it has a work class (bug, investigation, story, epic, subtask). A card imported from the tracker gets one from its issue type. A card made on the board gets one from its tag: tag it bug before moving it to Plan (when a card carries several class tags, the first in that order wins). A card filed by another service through POST /api/cards gets the one the request names (api.md). The work class picks the playbook each stage's agent starts from (playbooks.md).

A card is one of three things: a bug to fix, an investigation to explain, or a piece of planned work (a story, an epic, a sub-task).

The stages#

Shipped#

Shipped holds a card from the moment its pull request opens until a person cleans it up, and what the card shows comes from the pull request, not the column:

A card with several pull requests is open while any one is open, merged when none is open and one merged, and closed only when every one closed unmerged.

Clean up refuses a card whose pull request is still open, with the reason, on the board and on the server alike; a closed, unmerged one goes in only with the discard confirmed (discard_confirmed_at on the card). A card that never had a pull request — an investigation, a story closed without code — goes straight in. A ticket a person closes in the tracker retires its card the same way: an open pull request keeps the card in Shipped and is announced on the board's channel, and a closed one counts as confirmed.

Plan comes first because a fix without a reproduction is a guess (reproduce-first.md). Every approved bug RCA is filed in the knowledge store and linked into the root-cause graph (rca-graph.md).

Which agent runs which stage#

Settings → Agents names the profile each stage runs, globally or per board (configuration.md). Left unset, Plan runs the default coding agent profile and every other stage runs that agent's cheaper variant (Claude Code's Sonnet) when the default profile names no variant. Plan is where the design judgment is, so it gets the full model. The rest is where the sessions pile up: Execute carries out a plan a person already approved, in the change and then every fix round, CI fix, rebase and merge-request description; Review is a fresh full-diff session every round; comment replies and the RCA graph's analysis run often and only read. Together they spend most of a subscription seat's session budget. A follow-up continues its own session, so it can change variant but never agent.

Investigations#

An investigation is a reported problem Prepcook reproduces and explains but does not fix — typically filed by a support agent from a customer conversation, which then translates the answer for the customer.

• Plan runs exactly as for a bug, from the investigation:planning playbook: the app stood up, the harness first, the REPRODUCTION: comment, then the RCA and its verdict. The agent then posts a TRIAGE REPORT comment in a fixed shape — ## What happens, ## Where, ## Why (from the RCA, one paragraph), ## Scope (who and what is affected, and whether it is configuration or a defect, with the evidence), ## Workaround (or "none found") and ## Confidence (high, medium or low, with one line why) — and stops. It does not plan a fix or write a spec.
• Triaged. Once that comment is on the card, the orchestrator records the report on the card — which is what makes it triaged — sends investigation_completed to the board's notification targets (notifications.md), and copies the report onto the tracker ticket (moving it to status_mapping.triaged when that is set; on an incident, as a note, resolving it only with incidents.resolve_on_triage). The card stays in Plan under an amber Needs you header reading "Triaged — report ready", with Convert to bug and Close on it, and counts in the "need you" pill. There is no approval gate, in Chef mode or Prep mode, and nothing more runs for it.
• Close. An investigation that needs no fix is closed: Close moves it to Clean up, which takes it because it never had a pull request.
• Convert. An engineer who wants it fixed converts the card — the class label's menu on the card (Convert to bug), or POST /api/cards/{id}/convert (api.md). The tag and class change; every comment, attachment, the RCA and the harness stay. When the RCA is at high confidence and the harness is still on disk, they are the plan: the conversion is recorded as its approval and the card goes straight to Execute, where bug:executing starts in the same worktree. Otherwise it goes back to Plan and is planned as a bug. Converting to a story always plans again.

An investigation never executes: the Executing gate refuses it ("investigation cards do not execute; convert to a bug first"), and so does the board.

A board whose team added a column named Triaged keeps using it: a triaged investigation moves there, with the same amber header and actions, instead of staying in Plan. The transition rules leave that column alone.

Stories, epics and sub-tasks take the same columns. In Plan a story gets an implementation spec, an epic a plan with a breakdown into sub-tasks, and a sub-task a spec for its slice; the card cannot advance while the spec has open questions. In Execute an epic creates its sub-tasks instead of code. Nothing but a bug, and an investigation in Plan, stands the app up.

Boards made before Shipped#

A project made before the five columns keeps its own — To Do, Plan, Triaged, Execute, Review, Push MR, Close, Clean up — and keeps working: nothing is migrated. Push MR is read as Shipped (the pull request is opened and watched there, with the same chips); a merge moves the card on to Close as it always did, and fires the tracker's done transition as it lands; Close shows the same amber Merged — close card; and the Triaged column goes on receiving triaged investigations. The needs-column tag is no longer applied; one left on a card is an ordinary tag you can delete.

To move such a board to the five columns, open the board's project menu (…), Edit project settings, and under Project Statuses:

1. Empty Close: drag each merged card to Clean up (or back to Push MR, where it shows Merged — close card until you do).
2. Rename Push MR to Shipped with Edit name.
3. Delete status on Close, and on Triaged if you no longer want it; a column with cards in it offers Move issues first — move triaged investigations to Plan, where they keep their triaged state.
4. Save. The next poll reads the new names; no card needs to move.

A board whose fifth column is named Done keeps working as it is: Done is read as Shipped. Renaming it to Shipped with Edit name is all it takes to match a new board.

A board can keep any of the older columns it likes: Close and Triaged work whenever they exist, and Shipped, Done and Push MR are the same stage under three names.

The two modes#

The same stages run in two modes. The mode is Settings → Orchestrator → Autonomy mode, global or per board.

Chef mode (autonomy off, the default). Prepcook works your tickets and you move them. You import tickets from the tracker or make cards on the board, drag them between columns, and approve plans in Lavish, the review page each plan opens in (the Review plan button on the card). Stories and epics get a spec or a breakdown the way bugs get an RCA. A review's REQUEST CHANGES still starts a fix round on its own; advancing an approved card is yours.

Prep mode (autonomy on). Prepcook works on its own, on the machine meant to run unattended. Tickets the tracker's pickup filters select are imported as they arrive. Cards move themselves: a plan that clears the bar (an RCA at high confidence, a spec with no open questions) approves itself and goes to Execute; one below the bar is escalated to Slack and waits in Plan for a person, whose decision comes from the tracker ticket, the card or the approvals API (approvals.md). A finished, verified fix goes to Review, and an approved review goes to Shipped.

Either way a person merges. When an engineer takes a ticket over, Prepcook steps aside (working-alongside-people.md).

Without a tracker#

A tracker is optional. With none configured, every card is made on the board and the card is the only record: nothing is imported, nothing is posted to a ticket, and no sweep that reads a ticket's status runs. Every stage still runs, plan decisions come from Lavish, the card or the API, and the pull request is still opened. A card made on the board while a tracker is configured is treated the same way. The quickstart uses this path.

Tickets or incidents#

Where cards come from is the ticketing mode (Settings → Integrations → Ticketing, ticketing.mode).

Tickets (the default). The source is a ticket tracker — Jira, or GitHub Issues through the gh CLI — and each ticket's type picks its work class. Stages show on the ticket as the statuses (on GitHub, the labels) that status_mapping names.

Incidents. The source is an incident tool — PagerDuty. Every open incident on the configured services becomes an investigation card in Plan: Prepcook acknowledges it, reproduces and explains the problem, and adds the triage report to the incident as a note. It never pages anyone and resolves the incident only when configured to (incidents.md).

The two modes above (Chef and Prep) apply in either.

More#

• scripts.md: how Prepcook installs, starts, seeds and tests the app.
• playbooks.md: the prompt each stage's agent starts from.
• approvals.md: every way a plan is decided.
• incidents.md: Prepcook as a first responder on PagerDuty incidents.
• api.md: filing, reading and converting cards, and the other HTTP endpoints scripts use.
• configuration.md: every setting and its default.
• toolkit/README.md: the same method at your terminal, without the board.