pstack, the plugin that teaches coding agents the order of work

November 6, 2026

This English page is a machine translation of the Korean original, so some wording may read a little off.

Give a coding agent a bug, and this is often what happens. It opens files that look relevant, makes a plausible change, and says, "Fixed." You have to ask each time whether it reproduced the bug, whether that really was the cause, and whether it repeated the same steps after the fix. pstack is a tool designed to spare you those repeated questions.

pstack is a plugin in Cursor's official plugin repository, cursor/plugins. Its creator is Lauren Tan, who goes by poteto. The README introduces Tan as someone who built React Compiler on the React core team and worked at Meta, Netflix, and Cursor[1]. This article is based on version 0.15.36, licensed under MIT, as read on November 6, 2026[2].

A workflow, not a model

It helps to understand pstack as one of three layers.

Layer	What it does	Examples
Model	Reads, reasons about, and writes code	Claude, GPT, Grok
Runtime environment	Edits files, runs commands, and launches subagents	Cursor, Claude Code
pstack	Defines the order of work and the evidence needed to call it done	Reproduce, find the cause, compare candidates, verify actual results

Installing pstack does not make the model smarter. It gives the same model a fixed workflow so it does not rush or declare unverified work complete. The opening line of the README states that intent directly. "if you want to go fast, go deep first."[1]

One entry point, 23 playbooks, 24 principles

The core of pstack is a collection of skills. A skill is a SKILL.md file that describes when to use it and what procedure to follow. The agent reads and follows the file when needed. The repository contains 58 of these skill folders.

There is really only one thing to remember. Invoke the entry point, poteto-mode, and describe the task. The skill reads the request and selects a suitable playbook[3]. A playbook is a sequence of steps for a particular kind of work. There are 23, covering bug fixes, performance problems, features, refactoring, research, prototypes, PR maintenance, overnight autonomous runs, and more[1].

What happens after it selects a playbook shows how pstack works.

In its first message, it restates the user's goal, the problem to solve, and the smallest expected change in its own words. It does not wait for confirmation[3].
It copies the selected playbook's steps verbatim to the top of its task list. It keeps skipped steps and labels them skip: reason[3].
Of the 24 principles, such as proving a problem by reproducing it, fixing the root cause, and isolating shared state first, it names the ones used in its decisions. It may name a principle only if it has read that principle's file during the current session[3].
Every claim in its replies must carry evidence or a label in the same sentence. It identifies whether the claim is a measured result, an inference, or a guess[3].

The bug-fix playbook is specific[4]. First, reproduce the problem directly on the same screen or through the same command. Ask the user to reproduce it only when there is a concrete reason the tools cannot reach it. Next, form hypotheses about the cause and eliminate them through binary search. After the fix, verify it in the exact place where the problem was first reproduced. "Inconclusive" results or checks on a different screen do not count as a pass. The commit sequence also starts with a failing reproduction, with the fix built on top.

These are some commonly used skills. poteto-mode invokes them at the appropriate step, but you can also invoke them directly[1].

Skill	What it does
`how`	Traces and explains how a subsystem works
`why`	Searches commit history, issues, documentation, and conversations to explain why something was built this way
`architect`	Defines the caller's interface and types before writing code that crosses function boundaries
`arena`	Assigns the same task to several agents in parallel and combines their work around the best result
`swarm`	Splits work into pieces or races agents on the same task, then brings their work into one result
`interrogate`	Has multiple models try to break a change and keeps only defects demonstrated through execution
`blast-radius`	Checks through execution what else a seemingly small change could break
`create-verification-skill`	Creates a project-specific verification skill when there is no script for checking the app's behavior
`show-me-your-work`	Keeps a decision log for long tasks
`correct`	Turns repeated feedback into structural safeguards such as lint rules, types, or CI
`automate-me`	Reads your conversation history and drafts a personal `-mode` skill

Three ways to run multiple agents

pstack uses the phrase "fearless parallelism"[1]. The reasoning is that you need to trust one agent deeply before you can run several at once. It offers three distinct forms of parallel execution.

arena gives several candidates the same task with the same prompt[5]. Each candidate gets a separate worktree. Once they all finish, a model from a different family than the parent scores the candidates against a rubric. The parent also reads and scores them independently, then compares the two judgments. It uses the candidate that is easiest to refine as the base and manually brings over one or two useful pieces from the rejected candidates. If the candidates converge on similar results, it treats that as strong agreement. If they diverge sharply, it calls for redefining the task.

swarm either divides the work into pieces, such as one check per package, or races agents on the same task[6]. Workers report their results as one of PASS, ISSUES, or BLOCKED, with evidence. A result that omits the commits or measurement methods required by the brief is discarded, and the worker is launched once more. If the second attempt also omits them, that part remains a gap. A gap does not count as a pass.

interrogate is an adversarial review[7]. Reviewers receive a brief that says, "Break this change, and prove every finding through actual execution." Findings without a failing test, a reproduction script, or incorrect output are discarded. Opinions about style, naming, or structure that cannot be demonstrated through execution are also discarded. Only findings that the parent confirms by rerunning the same command are kept. It does not fix them.

All three methods assume a mix of models. The defaults are Grok for coding and Claude Opus for judgment and writing[1]. The arena skill explicitly prevents a model from the parent's family from serving as the judge[5]. You can change the model assigned to each role in the settings[8].

Installation and initial setup

In Cursor, two lines are enough[1].

/add-plugin pstack
/setup-pstack

setup-pstack configures two things[8]. The first is the reasoning budget. Choose from unlimited (max), large (xhigh, the default), medium (high), or small (medium), and the model's reasoning effort changes to that level for each role. Despite the name, this is not a spending or usage cap. The second is the model for each role. There are 17 role rows. Grok is the default for features and refactoring, bug fixes, performance, explorers, and workers. Opus is the default for judgment and writing, the hardest tasks, explanations, and synthesis. Roles involving several participants, such as arena, architect, and interrogate, accept a list of models. The length of the list determines the number of subagents launched. The result is saved to ~/.cursor/rules/pstack-models.mdc.

If Grok is unavailable or you do not want to use it, set those roles to inherit-parent (or auto). This leaves the subagent's model field empty so it uses the model from the parent conversation. It is not an actual model name[9]. At the end of setup, you are asked once whether to create a project verification skill. The guide recommends choosing "yes" on your first setup. It calls the verification skill the thing that "pays off the most" of everything in the guide[9].

When selecting /poteto-mode in Cursor, press option+enter (alt+enter on Windows) instead of enter to keep the mode active throughout the conversation. Combined with Cursor's /loop, it can handle tasks that run for hours[1].

In Claude Code, add the marketplace and install the plugin[1].

/plugin marketplace add cursor/plugins
/plugin install pstack@cursor-plugins

Commands carry the plugin name as a prefix, so you invoke them as /pstack:setup-pstack and /pstack:poteto-mode. Automatic updates are disabled because this is a third-party marketplace. Enable them in the marketplace tab under /plugin, or update manually with claude plugin update pstack@cursor-plugins[1].

The Claude Code version is a copy generated automatically from the original. An adapter document maps Cursor's names to their Claude Code equivalents[10]. There are three differences to understand before using it.

Models converge on one family. Claude Code subagents can select only opus, sonnet, haiku, or fable. Roles assigned to other families, such as Grok or GPT, run with the model field left empty and inherit the session model. They are instructed to disclose this fallback[10]. The Grok defaults in setup also become inherit-parent. If arena has no model available from another family to serve as judge, it skips that review and lets the parent choose alone[5]. Claude Code does not provide the benefit of perspectives from different model providers by default.
Skills are followed by reading their files. Because Claude Code's skill tool rejects most pstack skills, the integration switched to having the agent read and follow SKILL.md directly[10].
Cursor-only steps are skipped. Steps requiring Cursor Automations, Bugbot, Cursor cloud agents, or built-in PR tools leave a line saying Skipped in Claude Code and move on. PRs are opened with gh pr create[10].

Model settings are saved to ~/.claude/rules/pstack-models.md. The adapter document says not to put role rows in CLAUDE.md or AGENTS.md[10].

For Codex, OpenCode, and other environments, there is no official version, but community ports are available. Each port differs in the upstream version it follows and the skills it excludes. Choose one and follow that repository's installation instructions. There is also a warning that installing a port alongside the original in Claude Code causes a conflict because both use the pstack: prefix[11].

Port	Target	Characteristics
ScriptedAlchemy/pstack-codex	Codex	Describes itself as an unofficial, independent port. Tracks upstream 0.15.36
painhardcore/pstack	Codex, Claude Code, OpenCode	Adapts pstack to three environments, omitting some skills and autonomous execution playbooks
ericlitman/open-pstack	Claude Code, Codex	States that it is unofficial. Combines CLIs from multiple providers to mix model families
michael-denyer/pstack-claude	Claude Code, Codex, Gemini, and others	Renames components to match the target environment before installation

How to use it well

Limit the request to five things. The guide says to include the goal, the criteria for "done," the evidence you want, what you already know, and real constraints[12]. The criteria must distinguish a pass from a failure. "Make it better" and "work on it for an hour" are not checks. There are also two things to leave out: instructions on how to do the work and your initial guess about the cause. Offering a guess upfront narrows the search to where you pointed. The advice is to let the agent restate the problem first, then share your hypothesis. The guide also says not to list skills in the prompt. Selecting skills is poteto-mode's job.

/poteto-mode The session is lost when I log in and refresh.
Reproduce it first, and limit the fix to the cause you have confirmed.
Done means: show failure before the fix and success after it using the same reproduction steps.
Do not push or deploy.

The guide recommends choosing a real but small task as your first one. Its example is "add a --json flag to this command. text output stays byte-identical. verify both."[9]. Even the way to check the result is included in a single sentence.

Establish a way to verify the result first. pstack's principle is to prove the work through the actual artifact. If there is no way to launch the app and interact with it, that principle has nothing to stand on. For a project without verification scripts, it is better to start by running create-verification-skill to create a verification skill for that project[1][9].

Start unfamiliar code with how and why. Having the agent read the current flow and the reasons behind it before making changes reduces the chance of a plausible fix in the wrong place.

When designs differ, build them instead of asking. poteto-mode says that if execution can answer "which approach should we use," the agent should decide through prototypes rather than ask a person[3]. Only product judgments and preferences that experiments cannot resolve are left to the person. If there are two or more candidates, that is a place to use arena.

Run interrogate once before merging. Since it keeps only findings demonstrated through execution, the review results take less time to read.

Wait until it is reliable before assigning overnight work. Before starting an autonomous loop, the guide says to write down four things as a contract: the goal, the finish condition, permitted actions, and a way to stop[13]. "Work on this for 4 hours" is not a finish condition. The guide warns that "you'll wake up to four hours of motion instead of a result." When you return, start with the "Attention" section of the show-me-your-work log.

Do not use it for small tasks. Adding a playbook and multiple reviews to a single line of copy or an obvious one-line fix only consumes time and usage. The guide also recommends lowering the budget, shrinking panels, and reserving poteto-mode for work that needs rigor if you want to reduce costs[9].

Adapt it to your way of working. The README says that poteto-mode reflects its author's preferences and recommends using automate-me to build your own mode from your conversation history[1]. If your team has different verification methods, deployment steps, or restrictions, adapt it to those.

If you use Claude Code, you can start in this order.

After installation, run /pstack:setup-pstack, leave the budget at large, and set roles to inherit-parent because models from other families are unavailable.
Choose "yes" when asked whether to create a verification skill. If CI is the project's only means of verification, have the skill describe how to check CI results and the deployed URL after a push.
Choose one small, reproducible bug as the first task and include the five things above in the request.
Before merging, run /pstack:interrogate once to try to break the change.
If you need a review from another provider's model, run that model's CLI separately or consider a port that combines multiple families. Do not install the original and a port together.

Pitfalls to understand first

The default scope of autonomy is broad. The autonomy rules in poteto-mode say to proceed without asking not only with reversible work, but also with external actions such as team chat messages, ticket updates, and evaluation runs[3]. It stops for force-pushing shared branches, deployment, data deletion, and customer-facing messages. This may be broader than what the user meant by "just fix the code." It is safer to start on a disposable branch without production credentials. Writing "do not" in a prompt is different from enforcing a restriction through execution permissions.

Instructions are not enforcement. All of pstack's sequencing is written in prose. Issue #1160, opened on November 3, 2026, reported that a comment cleanup step in the autonomous execution playbook ran alongside the verification swarm, leaving code changed after verification had finished[14]. The same issue noted that deslop, control-ui, and control-cli belong to another plugin, cursor-team-kit, and that agents improvise when those skills are missing. It also proposed treating missing verification capabilities as BLOCKED rather than PASS. To use these three skills, you need to install cursor-team-kit as well[1]. On November 5, another report said the feature playbook's delegation step was ignored in Claude Code and over-applied in Codex. That issue was closed the same day[15]. The same instructions are followed differently across environments.

It changes quickly. pstack entered the repository as version 0.1.0 on May 23, 2026. By October 27, it had reached 0.15.36, with 79 versions released in just over five months. Of the 169 commits that changed pstack, 163 came directly from its creator[16]. Details in this article, especially default models and role names, may become outdated quickly. Read the current version's README before using it.

There are no numbers showing its effectiveness yet. This review found no public measurements showing what percentage of bugs pstack eliminates or how much faster it makes development. Since pstack includes a blind evaluation playbook[17], the most accurate way to assess it for adoption is to follow that process and measure it in your own repository.

Why another review finds more problems

A common pattern emerges when working with agents. A review identifies the biggest problem, you fix it, and another review finds a different problem. Have another AI review it, and more problems appear. pstack's interrogate reduces false positives by keeping only findings demonstrated through execution. But the skill itself has no conditions for rerunning it or criteria for stopping[7]. The table below breaks down the causes and suggests additions you could use alongside pstack. These are design judgments, not measured results.

Cause	What actually happens	Improvement
A review is a sample	A model review reports a few noticeable problems and stops. Each run selects a different few. The next problem was there from the start	Divide the review scope into cells by lens, such as correctness, edge-case inputs, error handling, security, and compatibility, and by unit, such as file or flow. Require a response for every cell, including "none"
Reviewers see different things	Another AI brings different criteria and produces findings that do not overlap	Put different AIs on the same code in parallel from the start, rather than adding them later, and have them use the same table
There is no basis for stopping	There is no basis for running another review or for stopping	Use the overlap between reviewers' findings to estimate how many remain undiscovered. Stop when a reviewer from a previously unused model family finds no new blocking defects
Only one location gets fixed	The same kind of mistake remains in other files, and a sibling appears in the next review	Classify each defect, search the whole codebase for the same kind, and fix them together
A fix creates a new problem	The change introduces a regression or opens a path previously hidden by another problem	Limit the next review to the changes and their impact, but rerun all tests
The criteria keep moving	Out-of-scope preferences keep appearing, and reviewer B asks you to remove what reviewer A asked you to add	Define blocking criteria upfront, such as an in-scope, reproducible failure, and pass rejected findings to the next reviewer with the reasons for rejection

The estimate in the third row uses capture-recapture, a method studied in software inspection research since the 1990s[18][19]. It originated as a statistical way to estimate populations that cannot be fully counted, such as fish in a pond. If two reviewers find n1 and n2 defects, with m overlapping, the estimated total is roughly n1 × n2 / m. If they find 10 and 8 defects, with 4 in common, the estimated total is around 20. That suggests about 6 remain beyond the 14 they found between them. Models from the same family tend to miss the same things, which pushes this estimate down. Mixing reviewers from different families is therefore a prerequisite for this method. The earlier limitation of using only the original pstack in Claude Code, where all reviewers belong to the same family, matters again here.

How to decide whether to adopt it

What you gain depends on how you work now.

Current approach	What to expect
You say "build it" and receive only the result	A large benefit. Investigation and verification become new steps
You explain the sequence in a long prompt every time	A moderate benefit. You no longer have to repeat the same instructions
Project rules, verification scripts, and CI are already solid	The benefit may be limited. First check how much it overlaps with existing procedures
Most of your requests are short code examples or conceptual questions	A small benefit. There are few opportunities to use a workflow designed for repository work

To measure the effect, run three conditions: an agent without the plugin, the same model with pstack, and multiple models with pstack. This separates the effect of the workflow from the effect of mixing models. The numbers to watch are not how quickly the first answer arrives. They are whether the work actually passes predefined criteria, how often work declared complete is still incomplete, how many times a person has to redirect the agent, how long it takes through verification, and total usage including subagents and retries. Add one metric from the previous section: the number of new defects that another AI, seeing the work for the first time after it was declared done, finds and reproduces.

References

[1] Lauren Tan. pstack README. cursor/plugins, accessed 2026-11-06.

[2] pstack plugin.json (0.15.36). cursor/plugins, accessed 2026-11-06.

[3] Lauren Tan. poteto-mode SKILL.md. cursor/plugins, accessed 2026-11-06.

[4] Lauren Tan. Bug fix playbook. cursor/plugins, accessed 2026-11-06.

[5] Lauren Tan. arena SKILL.md. cursor/plugins, accessed 2026-11-06.

[6] Lauren Tan. swarm SKILL.md. cursor/plugins, accessed 2026-11-06.

[7] Lauren Tan. interrogate SKILL.md. cursor/plugins, accessed 2026-11-06.

[8] Lauren Tan. setup-pstack SKILL.md. cursor/plugins, accessed 2026-11-06.

[9] Lauren Tan. pstack guide 1. Setup. cursor/plugins, accessed 2026-11-06.

[10] Lauren Tan. pstack in Claude Code. cursor/plugins, accessed 2026-11-06.

[11] open-pstack README. ericlitman/open-pstack, accessed 2026-11-06.

[12] Lauren Tan. pstack guide 2. poteto-mode. cursor/plugins, accessed 2026-11-06.

[13] Lauren Tan. pstack guide 7. Overnight. cursor/plugins, accessed 2026-11-06.

[14] pstack autopilot-full: require comment/slop passes before the swarm (#1160). cursor/plugins issue, 2026-11-03.

[15] poteto-mode Feature step 4 delegation is ignored on Claude Code and over-applied on Codex (#1176). cursor/plugins issue, 2026-11-05.

[16] pstack commit history. cursor/plugins, accessed 2026-11-06.

[17] Lauren Tan. Eval playbook. cursor/plugins, accessed 2026-11-06.

[18] S. G. Eick, C. R. Loader, M. D. Long, L. G. Votta, S. Vander Wiel. Estimating Software Fault Content Before Coding. ICSE 1992, pp. 59-65.

[19] L. C. Briand, K. El Emam, B. G. Freimut, O. Laitenberger. A Comprehensive Evaluation of Capture-Recapture Models for Estimating Software Defect Content. IEEE Transactions on Software Engineering 26(6), 2000, pp. 518-540.

pstack coding-agents claude-code cursor subagents agent-skills verification