Playbooks: Planning and Starting
This chapter covers 5 playbooks that sit at the entrance to a larger piece of work. Multi-phase plan produces only a plan. Feature owns a change’s design while delegating its code. Prototype settles a decision with a throwaway sketch. Session pickup resumes another agent’s work, and Pause safely stops work cleanly so it can be resumed later.
Two terms appear throughout:
- Operator: the human who directs the run and gives the go for execution and irreversible steps.
- Trunk: the repository’s main branch, which PRs branch from and land on.
Multi-phase plan: a checklist an owner runs box by box
Source: multi-phase-plan.md
This playbook produces the plan for a change that spans several phases or PRs. The plan is the deliverable, and the playbook writes no code. It is meant to be a checklist that an owner works through box by box while the operator audits each box from its evidence.
The user guide recommends asking for a plan only after the design has settled, with a prompt such as turn this design into a plan. small verifiable PRs, each with its own verification steps. If the change touches 1 or 2 files and the approach is obvious, the playbook says so and stops without writing a plan.
The steps:
- Settle open questions by prototype (see Prototype below). Ask the operator only about product or preference calls that no run could settle.
- Write the plan file. It opens with what changes, the PR ids in landing order, and a dependency graph showing which PRs branch independently from trunk, which wait for others, and which files each may touch.
- Give each PR its own section. One PR carries one change with its own evidence, following the
principle-sequence-verifiable-unitsskill. Each section has checkboxes for its dependencies, the files it edits, the single change it builds, the visible result, and its verification. - Return the plan path and stop. Execution begins only on the operator’s explicit go.
Tests by themselves are not verification. A PR counts as verified only once its unit, live, and perf boxes are all ticked. The live box requires driving the real surface through a concrete scenario with a pass predicate. The perf box names the metric and the probe, a trunk baseline taken beforehand, and the value at which the check would fail. If a PR changes an interaction, it does not merge until the operator has reviewed it.
The reply gives the plan path, the PR ids with their dependencies, the set of PRs gated on review, and whatever remains unproven.
Feature: own the design, delegate the typing
Source: feature.md
Feature builds new or changed behavior. The agent owns the design and is responsible for planning, review, and verification, but it delegates the code-writing to a subagent and stays in the lead. A change that crosses a function boundary gets its shape from the architect skill.
The steps:
- Trace the affected subsystem, then use
architectfor the shape. - Write the throughput checkpoint, a set of 4 todo items that decide how the work can be split: blocking first steps (gates that run before any fan-out), independent workstreams (disjoint files or layers that can run in parallel), shared mutable state (split the target by default, per
principle-separate-before-serializing-shared-state), and the smallest safe decomposition. A dimension that does not apply keeps its item, markedn/a: <reason>. - Delegate the code to a subagent on the model from the
feature, refactoringline of the model config. The brief names file paths, success criteria, and the data shape with its organizing structure, perprinciple-model-the-domain(a state machine instead of scattered booleans, a table instead of branching). Where several shapes are valid, such as error handling, abstraction layer, or test structure, delegate through thearenaskill so competing runners surface the alternatives. - Verify on the matching surface. An “inconclusive” result, or a check on the wrong surface, is flagged and does not count as a pass.
- Rebase into small, ordered commits and stack follow-ups, building and verifying each unit before the next.
- If the design is contested, run
interrogatebefore shipping. - Run the Opening a PR playbook.
Delegation is mandatory. The playbook allows no “skip with a reason” escape, and the Laziness Protocol does not override it, because the gain is separation between author and reviewer rather than fewer lines. A subagent that is itself forbidden to spawn meets the rule by owning the diff directly.
Tightly coupled work (one feature, one migration) goes to a single owner who keeps the checkpoint inline and fans out internally after the blocking phase. Fan-out at the parent level is reserved for slices that produce independent artifacts, such as audits, cross-subsystem investigations, or competing experiments. At phase boundaries the checkpoint is rewritten, and a fresh owner is spawned rather than chaining interrupts to the old one.
The reply covers what was built, the choices and their reasons, the throughput checkpoint, and open decisions, with design alternatives in tables.
Prototype: settle a decision with a throwaway sketch
Source: prototype.md
Prototype makes a design decision cheaply. Its output is the decision plus a disposable artifact, never shippable code; the real build follows the Feature playbook. It applies to visual questions (layout, interaction, density) and to empirical forks about behavior, timing, or approach. SKILL.md makes this a Non-negotiable: a fork you could settle by running something is prototyped instead of asked. With no decision to make, the work goes to Feature.
The steps:
- Scope the single decision the prototype exists to make.
- When the design space is open, gather prior art and summarize it as a moodboard of themes, palettes, and layouts so the user can pick directions. Skip this when the direction is already set.
- Build in an isolated scratch directory, away from production source. A visual decision uses vanilla HTML, CSS, and JavaScript or the lightest stack that renders the idea; a behavioral decision uses the smallest script that exercises the question. No production framework, tests, or abstractions.
- Put compared alternatives behind one switcher (buttons or a keypress), each variant labeled. The playbook calls this a cheap form of
principle-exhaust-the-design-space. - Verify on the matching surface: screenshot and drive each visual variant through the control skill, or log the timing and output for a behavioral one. Observation serves as the test here.
- Present alternatives, trade-offs, and a recommendation, then hand the chosen direction to Feature (or to
architectfor the shape).
This is the one playbook where the Laziness Protocol’s “smallest change” and the usual verification bar are inverted. Speed beats polish, code quality is irrelevant, and there is no planning; the rigor lies in choosing the right design cheaply. The agent may propose variations the user did not ask for, and it may discard one approach to try another.
The reply lists the variants, the evidence (screenshots or observed output), the trade-offs, a recommendation, and the scratch path, and it says plainly that the prototype is throwaway.
Session pickup: resume from the trail, do not redo it
Source: session-pickup.md
Session pickup takes over another agent’s in-flight work and identifies the exact resume point. The prior agent’s trail (a local transcript, a cloud-agent URL, or a pushed branch) is treated as authoritative input. The user guide separates it from the recall skill: use Session pickup when you want to resume one specific chat.
The steps:
- Locate the trail. A local transcript lives under the active workspace’s
agent-transcripts/directory, whose path the system prompt gives. Read the metadata overview and the last messages first, then scan back for decision points. A long transcript is parsed in a subagent so that only the reduced timeline reaches the main thread, perprinciple-guard-the-context-window. - Reconstruct the operational state: branch and worktree, what already landed (
git log,git diffagainst the base), open todos, and decisions already made. - Compare what shipped with what was planned and name the resume point. Do not re-run the prior reproduction or repeat completed work.
- Route the remaining work to the matching playbook and pick a verdict: continue the execution, ship a finished recommendation, ratify or override an earlier conclusion, or write a postmortem of a failed run. The pickup playbook ends here, and the routed playbook owns the rest.
- Verify the inherited claims against the original goal on the real artifact, per
principle-prove-it-works. A passing self-report from the prior agent is not proof.
Never glob across ~/.cursor/projects/*/. That crosses workspace boundaries and reads private chats from unrelated projects. Likewise, a “let me verify from scratch” pass is a warning sign: it treats an authoritative trail as untrustworthy.
The reply says where the prior agent stopped, what was inherited versus redone (ideally nothing), the resume point, and the outcome.
Pause safely: a clean stop with a resume note
Source: pause-safely.md
Pause safely stops work at a clean point and leaves a checkpoint from which a cold-start agent, one with none of the current context, can resume. It runs only on an explicit request to pause, for example before you go offline or restart Cursor. Phrases such as “keep going”, “going to bed, keep going”, or “don’t stop” never trigger it.
The steps:
- Halt at a safe boundary. Either complete the atomic step in progress or undo it, begin no new work, and cancel every nested subagent.
- Take no irreversible action for the sake of pausing. No new PR and no push, unless one was already out.
- Make the work durable by committing uncommitted edits as a single
wip:commit on the current branch. If the tree is broken, say so in one line of the commit body. - Write the resume note outside the context: intent, current activity, progress and what is verified, current state, next steps, key files, and gotchas. When context compaction is the trigger, write it to a file such as
/tmp/<slug>-resume.md. If ashow-me-your-worktrail already exists, point to it instead of duplicating it.
The reply announces a pause and is not a final report. It says where the work stands in the loop, what is on disk versus only in the agent’s head (by path, without pasted diffs), the commits made and whether the tree is clean, and the first action on resume. The user guide pairs this playbook with Session pickup: a fresh chat resumes from the note through that playbook.