“if you want to go fast, go deep first.”
pstack is the pack of agent skills Lauren Tan (poteto) ships in cursor/plugins under the MIT license. One router skill, /poteto-mode, picks a playbook for the task and pulls in the other skills as each step needs them. The README states the aim: “pstack helps you write less, but higher quality code.” This report reads every SKILL.md, playbook and agent file at commit eb4db2b, runs the pack’s own scripts and checks, and explains how each piece is built and which parts are worth reusing.
The public copy is cursor/plugins/pstack. It installs in Cursor with /add-plugin pstack, and in Claude Code from a generated harness/pstack/ tree (/plugin install pstack@cursor-plugins). Of the 147 commits touching pstack/, 141 are authored as “lauren”.
A folder with a SKILL.md (YAML frontmatter plus Markdown), sometimes with references/ and scripts/. 56 of the 57 skills set disable-model-invocation: true; the exception is /setup-pstack. Nothing loads because a word in a prompt matched.
The README: “personally, i don't believe in planning. the best spec is code.” Planning lives in Cursor’s plan mode and in the multi-phase-plan playbook, not in a default step.
A prompt names a goal and a check that can pass or fail. The router picks a playbook and copies its steps into the todo list. Those steps call workflow skills, which fan out to subagents on the model assigned to each role. Principles constrain the choices, and nothing counts as done until it is proven on the real artifact.
Subagents spawned inside playbook steps run as poteto-agent, which loads poteto-mode first. Panels (arena, architect, interrogate) run one subagent per model listed for the role.
A few strict conventions carry most of the design. They are the part to copy into another pack.
The name is the folder. The frontmatter name matches the directory, and other files cite a principle as principle-<name> instead of pasting it.
The description carries the trigger. Principles open with “Apply when…”, so the router’s index can quote the trigger and the rule in one line.
Explicit invocation only. 56 of 57 SKILL.md files set disable-model-invocation: true. A skill runs when typed or when a playbook step reads it by path.
Orchestrators delegate to references. Multi-agent skills keep subagent prompts in references/, one file per receiving role. The Files list in each explorer entry below is computed from the tree.
Pick a skill to see how to call it, how it works, a few lines quoted from its file, its files and the design lesson. Word counts are wc -w of the SKILL.md at this commit.
The router copies a playbook’s steps into the todo list verbatim. Steps here are paraphrased; stances, quotes and Reply lines are copied from the files.
Re-checked at eb4db2b. Babysit never merges: “Babysitting never authorizes merging.” Shipping lands on request, bottom-up, one PR at a time. Autopilot-full owners merge only what the swarm verified: “The owner merges only what you verified, tested on the trunk it lands on.” Autopilot-stack owners never “retarget, merge, close a PR, or arm auto-merge”.
Each card gives the trigger and rule from the router’s index, then a line from the leaf file that works as the test. Cards marked stub point at leaves that were cut down to a fragment (see the findings).
Refactoring, sizing a diff, or tempted to add abstractions, layers, or signal threading.
Bias to deletion and the smallest change that solves the problem.
Make the smallest change that solves the problem. Fewer lines beat "elegant" boilerplate.
Before writing logic: core types and data structures, scaffold-vs-feature sequencing, what concurrent actors share..
Ask "does every subsequent phase benefit from this existing?"
Integrating a new requirement into an existing design.
Redesign as if it had been foundational from day one.
Ask: "if we were writing this from scratch with this new requirement, what would we build?"
Two or more fixes that share one premise have failed the same gate.
Write the premise down and test it directly before you write another fix that assumes it.
Do not start the next fix before the premise is written down and tested.
Sequencing an addition, refactor, or rewrite.
Remove dead weight first, then build on the simpler base.
When a reference has no novel content, delete it rather than leaving a stub
Reviewing or shaping code that's hard to trace.
Count layers and hidden state, collapse one-caller wrappers, shrink mutable scope.
can a new reader answer "where does X come from?" and "what can change X?" in under 30 seconds? If not, cut layers or cut state.
Planned rewrites and migrations with explicit phase boundaries.
Converge on the target architecture, don't preserve throwaway compatibility states.
Intermediate breakage is acceptable when it is planned, scoped, and reversible
Product, UX, or feature-scope tradeoffs.
Choose user delight over implementation convenience.
The engineer who maintains the code next is a user too.
A novel interaction or architectural decision with no precedent.
Build 2-3 competing prototypes and compare before committing.
It also applies to product design decisions where user experience depends on feel, not logic.
Any non-trivial work.
Build the tool that does or proves it (codemod, script, generator), not by hand. The tool is the artifact a reviewer reruns.
If you cited it and there is no codemod, script, generator, or delegate skill in the diff, you didn't apply it.
Writing stateful logic, or code that branches a lot or repeats a shape assumption across files.
Encode the domain in a structure (state machine, typed model, table or registry, reducer, boundary, the right collection) instead of scattered conditionals.
The sign that you skipped this is a new feature that grows an existing if/else chain by one more branch, or a second boolean that must stay in sync with the first.
Wiring validation, error handling, or framework adapters.
Guards at system boundaries, trust internal types, keep business logic pure.
"Is this data crossing a system boundary right now?" If not, validation is redundant.
Designing types or a signature in any typed language.
Make illegal states unrepresentable, brand primitives, parse external data at boundaries.
If two arguments share a primitive type but mean different things, brand them.
Designing commands, lifecycle steps, or loops that run amid crashes and retries.
Converge to the same end state.
If any answer is "it depends on what state was left behind," the operation needs a reconciliation step.
Introducing a new internal API while old callers exist.
Migrate and delete in one wave.
Update tests to assert the new contract, and delete tests that only protect pre-refactor implementation details
Concurrent actors might write the same file, branch, key, or object.
Eliminate the sharing first.
Instructions and conventions are not concurrency control.
After a task, before declaring done.
Verify against the real artifact, not a proxy or "it compiles".
When verification fails, suspect the observation method before suspecting the system
Debugging.
Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate.
If a workaround needs a paragraph-long comment to justify it, the code is wrong. Fix the code, not the comment.
Multi-step work (sweeps, migrations, runs of similar edits) and how you stack commits and PRs.
Break work into small units that each end in a check, verify each before the next, and order delivery so the sequence proves itself.
When a lever does the edits, the per-unit check is nearly free. Run it anyway.
Writing, changing, or keeping a test.
Assert what the code's users can observe, so the test fails when that behavior breaks and keeps passing when only the internals change.
Keep a test that catches the first edit and survives the second. Rewrite or delete the rest.
Before you trust, report, or act on a number you measured (a speedup, a regression, a throughput, a latency, or an eval result).
Find what limits it, and rule out that it measured something other than the work you think.
If you cannot say why the number is not twice as good, you do not know what you measured.
Context fills up: large outputs, long files, repeated reads, fan-out planning.
Route bulk to subagents, keep summaries in the main thread.
Limit files per phase, set turn budgets, account for mechanism costs.
Tempted to ask "should I do X?" on reversible work.
Proceed, present the result, let the human course-correct.
Irreversible actions (force-push, delete production data, send external messages) still require confirmation.
You catch yourself writing the same instruction a second time.
Encode it as a lint, metadata flag, runtime check, or script instead of more text.
If the fix is structural, only use the structural fix. The instruction is the symptom.
/setup-pstack writes one line per role into ~/.cursor/rules/pstack-models.mdc (an always-apply rule for every project). Fast Grok models do the reading and mechanical edits; Opus judges, writes and takes the hardest work; panels list both families.
| Role line | Default |
|---|---|
| feature, refactoring | grok-4.7-xhigh-fast |
| bug-fix | grok-4.7-xhigh-fast |
| perf-issue | grok-4.7-xhigh-fast |
| hillclimb | grok-4.7-xhigh-fast |
| judgment and prose | claude-opus-5-5-xhigh |
| hardest tasks | claude-opus-5-5-xhigh |
| how explorer | grok-4.7-xhigh-fast |
| how explainer | claude-opus-5-5-xhigh |
| why investigators | grok-4.7-xhigh-fast |
| why synthesizer | claude-opus-5-5-xhigh |
| reflect tooling | grok-4.7-xhigh-fast |
| reflect judgment, divergent, synthesizer | claude-opus-5-5-xhigh |
| arena runners | claude-opus-5-5-xhigh, grok-4.7-xhigh-fast |
| arena cross-judge pool | claude-opus-5-5-xhigh, grok-4.7-xhigh-fast |
| swarm workers | grok-4.7-xhigh-fast |
| architect runners | claude-opus-5-5-xhigh, grok-4.7-xhigh-fast |
| interrogate reviewers | claude-opus-5-5-xhigh, grok-4.7-xhigh-fast |
/add-plugin pstack # Cursor /plugin marketplace add cursor/plugins # Claude Code /plugin install pstack@cursor-plugins
Install, then run /setup-pstack once.
A rule file written before a default changed still pins the old model. A rerun keeps roles set to something other than the default, so delete stale lines (or the file) and run /setup-pstack again.
About 11.3k lines of Bun, TypeScript, Node and shell, with 1.9k lines of tests. Each script turns a rule the agent could forget into a check that exits non-zero.
| Script | Used by | What it enforces (verified) |
|---|---|---|
check-plan.mjs | multi-phase-plan | Lints a plan file against the required skeleton. Exits 1 when it finds problems and 2 on bad usage. |
scripts/watch-pr/ | babysit, shipping | Polls a PR and returns a typed verdict. Exit codes in policy.ts: 0 ready or complete, 2 merge conflicts, 3 review threads, 4 failing checks, 6 merge gate, 7 query failure, 5 timeout. |
scripts/orch/ | orchestrate | File-backed state for the coordinator, “one command in and one line out”. “The CLI never spawns, waits, or wakes anything.” |
worktree-audit.sh | worktree-cleanup | Read-only table (SIZE AGE MERGED DIRTY REMOTE PR LAST_CHAT BUCKET) sorting worktrees into hold-wip, hold-open-pr, verify-recent-chat, safe and review. Without -b it warns and uses origin/main. “The bucket is advice, not permission.” |
log.sh | show-me-your-work | Appends a timestamped TSV row. In a test run it stripped tabs inside cells and prefixed =cmd with ', blocking spreadsheet formula injection. |
bootstrap.ts | watch-pr, orch | Installs the scripts’ dependency keyed on package.json and bun.lock. |
bun test (Bun, 5 files) failed on the first cold run: 59 pass, 1 fail, 1 error across 60 tests. The next four runs all passed 68 of 68. The same cold-start failure appeared on the previous commit, so it looks like a first-run setup race, not a broken test. The failing test name was not captured.
The guide says a prompt carries up to five things, each one sentence long.
The goal. What is wrong, or what is wanted.
The done check. “It must be able to pass or fail.” “"Make it better" and "work on it for an hour" aren't checks.”
The proof. Real command output, a video, the stored value, or a before-and-after number.
What is already known. A symptom, repro step, log line or link.
Real constraints. “repro first”, “don't change any code yet”, “zero behavior change”.
/poteto-mode the csv export drops its last row since yesterday's deploy. failing job id is 4812. repro first, then fix. done means the 60k-row fixture exports every row. show me the row counts before and after.
All five in one prompt, from docs/guide/02-poteto-mode.md.
Two things stay out: a list of skills, because “a hand-written sequence usually reorders or drops steps the playbook would have kept”, and a theory of the cause, because “A stated guess narrows the search to wherever you pointed.”
/poteto-mode im going to bed. migrate every caller to the new parser in a fresh worktree off <base>. done means zero old callers, all parser fixtures pass, old api deleted. keep a decision log. don't ask me before committing. /loop until done. if you're truly stuck after a few hours, stop and write up why.
The overnight contract, from docs/guide/07-overnight.md.
“A loop you don't trust just produces unchecked work faster, and the mess compounds with every iteration.”
docs/guide/07-overnight.md, “Earn the trust before the loop”
Gaps found while reading every file, plus the results of the repo’s own consistency checks.
Only one skill can fire from a prompt’s wording. /setup-pstack is the single SKILL.md without disable-model-invocation: true. typescript-best-practices (“Use when reading or editing any .ts or .tsx file.”) and tdd read like auto-triggers but only run when typed or read by the router.
Five principle leaves are fragments. After #571 (08bd59b, 11 Oct) and #634 (99743e9, 15 Oct), the bodies of exhaust-the-design-space, encode-lessons-in-structure, guard-the-context-window, laziness-protocol and migrate-callers-then-delete-legacy-apis start mid-thought. exhaust-the-design-space opens with “It also applies to product design decisions…”, leaning on a description the body no longer restates. They are marked stub in the principles grid.
Swarm’s Phase A skips a number. Its steps run 1, 2, 4, 5. A step 3 was removed without renumbering.
why’s failure-mode list has one entry. “Common Failure Modes to Avoid” ends after the single “Recency bias” bullet.
unslop’s rule list has gaps. 28 rules, with numbers 1, 2, 4, 6 and 21 missing after cuts. Rule 17 asks for sentence-case headings; this page uses Title Case by the publisher’s house rule.
Two playbooks lack parts of the shape. opening-a-pr and worktree-cleanup have no “You own…” stance line, and opening-a-pr and babysit have no **Reply:** line. Every other playbook has both.
The docs check passes. scripts/check-pstack-docs.mjs reports “57 skills (33 commands, 24 principles), 23 playbooks, 2 agents … 0 problems”, and generate-pstack-harness-trees.mjs --check reports “harness/pstack is up to date.” Both only pass on a full checkout: in a sparse one that omits cursor-team-kit, the first flags /deslop three times.
A reading of the files and history, not a benchmark.
Replies label claims, playbooks end in proof on the real artifact, and scripts such as watch-pr and check-plan exit non-zero instead of trusting prose.
Comment Sicko, cross-family arena judges and the swarm that “never wrote the code” separate building from reviewing.
The history is full of cut passes (#419, #538, #571). The shortest non-stub principle is 110 words.
Panels, swarms and cross-model reviews multiply model calls, and the playbooks are heavy for small changes even with skip: <reason>.
Outside the scripts, every rule depends on the model following text. The cut passes also leave fragments behind (see the stubs).
Defaults assume Opus 5.5 plus Grok 4.7, GitHub or Origin, and Bugbot. /automate-me exists to draft a personal mode instead.
Ordered by payback for effort, judged from which skills the rest of the pack depends on.
A scripted way to prove behavior per app. /create-verification-skill is what “verified” means everywhere else in the pack.
Reply rules that demand evidence. Failing-then-passing output pasted verbatim, and claims labeled.
Author and critic in separate agents. Start with a comment-stripping critic and a judge who never sees model names.
One router, small playbooks. A stance line, numbered steps copied into todos, and a Reply: contract.
Turn repeated corrections into structure. /correct’s ladder: architecture, then types or lint, then a test, then docs.
Explicit-only skills with the rule in the description. disable-model-invocation: true plus “Apply when…”.
Prune and re-test. Delete instructions the current model follows unprompted, then check the stubs that pruning leaves.
“Add pstack plugin” lands in cursor/plugins.
Versions 0.2 to 0.9.1; per-role models via /setup-pstack (#121); the hillclimb playbook.
model-the-domain principle; create- and maintain-verification-skill (#150); a parity sweep with the private skill tree (#156); the swarm skill.
Autopilot playbooks, /no-comments with Comment Sicko, /technical-writing, bro, babysit, shipping, orchestrate and worktree-cleanup.
0.15.0. Defaults move to Opus 5.5 and Grok 4.7 on 22 Sep (#414); #419 cuts “19 more instructions Opus 5.5 does not need”.
/correct, /poteto-help, /ketchup; Sol dropped (#511); distill pass (#538); #571 cuts sections from seven skills.
0.15.26 to 0.15.29: formal verification skills, Claude Code harness, /sharpen restored to its original prompt.
0.15.30 adds /statechart, which draws TLA+ models as charts.