Playbooks: Shipping
This chapter covers 4 playbooks that move finished work toward trunk or measure whether it is actually better. Opening a PR defines how a pull request is written and opened. Shipping lands a stack of verified PRs. Hillclimb is a loop that improves one metric, and Eval compares variants of a skill or prompt in a blinded experiment.
2 terms appear throughout:
- Forge: the service that hosts the PRs. pstack uses the GitHub CLI (
gh) by default and switches to the Origin CLI (origin) when it is installed and can resolve the repository. - Stack: a chain of PRs in which each PR’s base branch is the branch of the PR below it, so the bottom PR targets trunk.
Opening a PR: the shared closing step
Source: opening-a-pr.md
Opening a PR describes itself as “invoked at the end of every other playbook”. In practice it is the last step of the playbooks that change code, such as Feature, Bug fix, Perf issue, Refactoring, Hillclimb, Visual parity, and Authoring a skill; the read-only playbooks (Investigation and the 2 forensics playbooks) never reach it. Its job is to make every PR look the same regardless of which playbook produced it.
The rules, in the order they apply:
-
Isolate the work. Work happens in a git worktree created from trunk, and unrelated changes stay out of it. Before opening, the commits are rebased into small units that could each land on their own.
-
Clean the diff. Before committing, the agent runs
/deslopfrom thecursor-team-kitplugin over the diff. -
Write the title as
type(scope): subject. If a real symbol carries the change, the subject names it. -
Write the body as a one-minute briefing of fewer than 40 lines. It uses these
##headings in this order and omits any that would be empty:## Why, which opens with the goal (a rule from the Non-negotiables inpoteto-mode).## What changed## Scope## Tradeoffs, limited to rejected alternatives that a reviewer would otherwise ask about.## Blast Radius## Verification
-
Stack follow-ups by base branch instead of growing one branch.
-
Open the PR ready for review. The agent uses the run’s own PR tool with
draft: false. Without such a tool, it usesgh pr createwithout--draft, ororigin pr create --status openwhen the Origin CLI resolves the repository.
Opening a PR does not start a babysit. Watching the PR until it is merge-ready belongs to the Babysit playbook (see Autonomous execution).
Shipping: land only what an independent agent verified
Source: shipping.md
Shipping is the fixed route for landing a green stack: the Non-negotiables in poteto-mode send “landing a green stack” here. The agent owns what lands. It verifies each PR independently, lands only the verified part of the stack from the bottom, and otherwise leaves the stack untouched while it merges.
Some vocabulary first:
- Verdict: the result a verifier posts on a PR, one of
PASS,PASS+NOTES, orFAIL. - Run: the contiguous sequence of verified PRs starting at the lowest unmerged PR.
- Ceiling: the top PR of that run.
The steps:
- Resolve the forge and verify each PR. The default tool is
gh. Whencommand -v originsucceeds and Origin can resolve the repository, all PR operations useorigin pr; if not, the agent keeps usingghand logs that it fell back. Graphite (gt) is never a requirement. Every PR receives a single verifier: a Cursor cloud agent that exercises the change the way a user would through the matching control skill (for examplecontrol-uiorcontrol-clifromcursor-team-kit), compares parent with head, and posts its verdict on the PR. - Land only the contiguous verified run. Starting from the lowest unmerged PR, the agent walks upward and stops at the first PR that lacks
PASSorPASS+NOTES. A verified PR that sits above an unverified one has to wait, because it depends on the code below it. There is one exception: a PR whose branch neither contains nor needs that code can be moved onto trunk and landed alone, but only after it receives a fresh verdict, since its earlier verdict was produced with the other code underneath. - Check that each verdict still describes the code. A verdict applies to a patch, and a chain rebase gives every PR above it a new SHA without failing any check. Before trusting an older verdict, the agent compares
git patch-idat the verdict SHA with the current head. If the patches differ only in tests, docs, or lint configuration, the result of a lane (the playbook’s word for one verification check run against the PR) can stand, provided what the lane ran builds identically at both SHAs apart from noise. The playbook defines noise as a difference that also appears between 2 builds of the verdict SHA, or an embedded commit SHA, and each kind of noise must be reported with its files. The new change itself still needs fresh checks and a review. A lane with no build output, such as a dev server, cannot demonstrate identical builds, so it is rerun. - Land bottom-up, one PR at a time. The PR the agent merges is always the lowest one in the run that has not merged yet, using
origin pr merge <pr>orgh pr merge <pr> --squash. Merging in any other order fails: on Origin, the plain command merges every PR beneath the named one as well, and on GitHub, a PR still based on its parent’s branch lands in that branch rather than in trunk. Afterwards the agent reads the PR again (origin pr view <pr>orgh pr view <pr> --json state,mergedAt,baseRefName). This check is needed because a merge command may report success when a merge queue has merely queued the PR, and because a requested auto-merge has not yet merged anything. A PR has landed when it appears as merged with trunk as its base. Following each merge, the agent retargets the next PR to trunk, moves its patch onto the merge result, and pushes the branch with--force-with-lease; whether its verdict still holds is then decided by the patch-id rule from step 3. The agent arms--autoonly on a PR whose verdict covers its current head. - Leave the stack alone while it lands. The retargeting in step 4 is the only permitted change to any branch or base. On GitHub, the agent watches with the bundled
watch-prscript, run aswatch-pr --queued-stackunder/loopwith the run’s PR numbers in--stack-prs(bottom to top, the same list on every restart), until it reportsCOMPLETEat the ceiling. On Origin, it re-reads the PR withorigin pr view <pr> --checkseach timeorigin pr checks <pr> --watchreturns. A base that moves to trunk after its parent merges is expected. If a merge stalls, the agent finds the reason before changing anything. - Stop at the ceiling. Landing more requires new verdicts, which means a new pass starting from step 1.
2 rules explain why the verification step cannot be skipped. A verdict from the agent that wrote the code does not count, since an author tends to confirm what it intended to build. Green CI and an approving bot review do not count either, because neither runs the change the way a user would.
The reply reports the verified run and its ceiling, each PR’s verdict and which agent produced it, what landed and how that was confirmed, and what the next gap in the stack needs.
Hillclimb: one change, one measurement, keep or revert
Source: hillclimb.md
Hillclimb is for sustained, iterative improvement of a single measurable quantity toward a target. A one-off fix belongs to Bug fix or Perf issue (see Troubleshooting); Hillclimb is the loop. The agent owns the metric and the integrity of the experiment, supervises and reviews, and delegates each attempt to a subagent on the configured hillclimb model (default claude-opus-5-5-xhigh-fast, set in ~/.cursor/rules/pstack-models.mdc by /setup-pstack).
Its core discipline is a single rule: one change, one measurement, then keep or revert. Untested changes are never stacked, and a win is never claimed from reading code, per principle-prove-it-works.
The steps:
- Understand the workload before choosing a metric. The agent traces the target, identifies the realistic dimensions that could shift the result (data size, history, state, concurrency), and selects a case that reproduces what the user complained about. When no case reproduces it, the agent repairs the reproduction instead of starting to hill-climb. Next, it settles on one metric, the direction that counts as an improvement, and a checkable stop predicate. The predicate combines a target with a minimum number of attempts, so an early lucky win cannot end the run; the playbook’s example is “at least 50% better than baseline and at least 10 iterations”. If the user has supplied numbers, those are used; if not, they are agreed with the user.
- Build the measurement rig, show that it is sensitive, and then freeze it (
principle-build-the-lever). When realistic workloads are contrasted, the target case has to reproduce the symptom and the easier cases have to separate as expected; otherwise the workload or the metric gets revised. The rig passes throughbenchmark-checklistand has to print both its error count and a count of the work it did. After the freeze, one repeatable command produces the metric, with enough samples to rise above noise (a median of N runs). Before anything changes, the agent records the baseline and a green run of the regression gate, that is, the tests that must keep passing. - Open a decision log through the
show-me-your-workskill: adecision.tsvfile, kept out of the tree (gitignored), with one row per attempt and the columns id, hypothesis, change, before, after, delta, tests, verdict (kept or reverted), and note. The agent reads it before each attempt. - Ground every hypothesis in the architecture from step 1, so that it names a specific mechanism. The playbook contrasts “defer X off the boot path because it blocks first paint” with the vague “try memoizing something”. For a performance metric, hypotheses follow the order of the Perf issue mantras, but without the Perf issue rule that stops at the first mantra that meets the target.
- Loop, one hypothesis per iteration. A subagent makes the change within a tight scope while the agent reviews the diff, per
principle-guard-the-context-window. Independent hypotheses can run in parallel subagents, each in its own worktree, perprinciple-separate-before-serializing-shared-state. Each attempt is measured before and after with the frozen rig, and the regression gate runs. A change is accepted only when the metric moves beyond noise and the gate stays green; anything else is reverted in full. Each accepted fix becomes one commit that stages only the changed files (git add <files>, never-A), and every attempt gets a log row whatever the outcome. If the run is unattended, it borrows only the wake mechanism from the Autonomous run playbook (see Autonomous execution), and keeps its own stop rule. - Push past the first plateau. After several rejections in a row, the agent changes the category of idea, combines near-misses, re-reads the source, or tries something bolder. Correctness and simplicity still outrank the number: a win that breaks behavior is reverted, and a simplification that holds the number is kept, per
principle-laziness-protocol. - Stop once the predicate holds, or once the ideas that remain are marginal and would cost more than they return. The agent may not loosen the predicate to claim success, and it may not give up while cheap hypotheses are still untested. When it is stuck, it reports that rather than repeating attempts.
- Run Opening a PR, with the accepted commits stacked in the order they landed.
The reply gives the metric and target, the change from baseline to final with the percentage delta, the number of iterations (kept versus reverted), one line per accepted fix, the decision.tsv path, and the best idea to try next.
Eval: compare variants in a blinded experiment
Source: eval.md
Eval answers whether a variant (a changed skill, prompt, or similar) actually behaves better, using an experiment in which the agents under test do not know they are being tested. The agent owns the experimental design: it plans, blinds, runs, and synthesizes. 2 roles take part. Candidates are agents that perform the task with the variant in place, and the judge is a separate agent that scores their outputs.
The blinding rules are non-negotiable:
- No directory, file, or prompt that a candidate sees contains the words
eval,test,judge,experiment,rubric,score,compare,benchmark,candidate, orarena. - The candidate prompt reads like an organic user request and states the goal only.
- Candidates are never asked to list the skills, principles, or files they applied. They may be asked for design notes in general. Chain-following, meaning whether a candidate actually read and applied the skills and principles the variant points it to, is graded from the shape of the code.
- Directory names and slugs are sanitized into project-like names a user might choose.
- Candidates are not told that other candidates exist.
- The judge may know that it is judging, but it sees outputs only under sanitized labels, never by model name.
- When 2 variants are compared, a single judge scores both sets in one pass on one scale, without knowing which set came from which variant.
The steps:
- Frame the experiment. State the variant under test and the behavior that counts as success, then write a rubric of 3 to 6 concrete criteria for the judge only.
- Prepare sanitized environments: one working directory per candidate with the variant installed, plus whatever context an organic task would have, such as a project skeleton and the skills the candidate would naturally read.
- Write one organic prompt, phrased the way a user would type it, with nothing that hints at what is being measured.
- Spawn N candidates in parallel on different models, following Phase B of the
arenaskill. All receive the same prompt, each in its own directory. An agent that only dispatches, polls, or packages results runs onclaude-opus-5-5-medium-fast. - Spawn one blinded judge from a different model family, following Phase C of
arena. It sees the rubric and the outputs under sanitized labels. - Verify chain-following from transcripts. The agent reads each candidate’s local transcript under the active workspace’s
agent-transcripts/directory and checks which files the candidate actually opened. It must not glob across~/.cursor/projects/*/, because that would cross workspace boundaries and read private chats from unrelated projects. The grade combines the files really read with the shape of the code, and ignores what the candidate claims about itself. - Read every candidate output end to end and compare it with the judge’s verdict. A disagreement indicates either a biased model or an ambiguous rubric. The agent then synthesizes a conclusion.
The reply covers the variant under test, the rubric, notes on each candidate, the judge’s verdict, the agent’s own synthesis, and a recommendation on whether to promote the variant.