Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Installation and Setup

Setting up pstack takes one install command and one short conversation about models. This chapter covers Cursor first and then the differences in Claude Code, which is the only other host the plugin documents.

Install in Cursor

In a Cursor chat, run:

/add-plugin pstack

Cursor confirms that the plugin is installed. Each skill is a plain file at skills/<name>/SKILL.md inside the plugin, so you can read any of them to see exactly what the agent will be told.

Install in Claude Code

In Claude Code, add the marketplace and then install the plugin:

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

Three differences follow from this.

  1. Names take a prefix. Claude Code prefixes plugin commands and agents, so /poteto-mode becomes /pstack:poteto-mode and setup becomes /pstack:setup-pstack.
  2. Updates are manual by default. For third-party marketplaces, Claude Code does not turn on auto-update, which means pstack remains at whichever version you installed. You can switch it on through /plugin: go to the marketplaces tab, pick cursor-plugins, and choose enable auto-update. For a single manual update, run claude plugin update pstack@cursor-plugins.
  3. Cursor-only steps are skipped. When a step needs a feature that exists only in Cursor, such as Bugbot, Cursor Automations, or Cursor cloud agents, the agent writes a one-line note in the form Skipped in Claude Code: <step>. <reason>. and moves on. It does not stop, ask, or retry.

Because the skills are written with Cursor’s tool and path names, pstack includes a Claude Code adapter that the agent reads once per session. It maps each Cursor name to its Claude Code equivalent. A few examples:

In the skills (Cursor)In Claude Code
TaskAgent
AskQuestionAskUserQuestion (plain text in -p mode)
subagent_type: "poteto-agent"pstack:poteto-agent
environment: "cloud"isolation: "worktree"
.cursor/skills/.claude/skills/
.cursor/rules/*.mdc (always-applied rules)CLAUDE.md, or AGENTS.md when there is no CLAUDE.md

The adapter also says that a non-Claude model slug, such as a Gemini model, cannot be passed in Claude Code. The agent omits the model field, so that subagent runs on the session model, and says so.

What /setup-pstack does

Run /setup-pstack once after installing. It decides which model fills each role (a kind of work that pstack delegates, such as bug-fix code or review) and writes the answer to a small rule file that every pstack skill reads.

The steps are:

  1. Detect. It lists the model slugs that a subagent can actually use in this session. It never writes a slug it has not confirmed. If it cannot detect any, it asks you to paste them.
  2. Load. If a rule file already exists, it treats the recorded budget and role values as your current choices. Lines for retired roles are dropped, and recognized old defaults (for example an older Gemini panel seat) are replaced. It tells you which values it changed.
  3. Ask for a budget and confirm. It offers 3 reasoning budgets: large (xhigh reasoning), medium (high reasoning), and small (medium reasoning). It then shows every role with its model and asks whether to accept the list or change specific roles.
  4. Validate. Every real slug must be in the detected set and at xhigh or below.
  5. Write. It overwrites the whole rule file, so that running setup again gives the same result.

The rule file goes to a different place in each host:

HostRule file
Cursor~/.cursor/rules/pstack-models.mdc (with alwaysApply: true)
Claude Code~/.claude/rules/pstack-models.md (no frontmatter)

The rule applies to new sessions, so start a new chat after setup.

Overrides and reruns

You override only what you care about. A role with no line in the file keeps the skill’s default, so deleting a line restores that default.

A rerun keeps every role whose model differs from the default. When pstack changes a default, a file written earlier still pins the old value until you run /setup-pstack again; that run replaces the old defaults it recognizes and reports which. To drop a pinned value it does not recognize, delete that line or the whole file first.

How the model roles work

The rule file has one line per role. The default file, which matches the large budget, looks like this:

# defaults: 3
# budget: large (xhigh)
feature, refactoring: claude-opus-5-5-xhigh-fast
bug-fix: claude-opus-5-5-xhigh-fast
perf-issue: claude-opus-5-5-xhigh-fast
hillclimb: claude-opus-5-5-xhigh-fast
judgment and prose: claude-opus-5-5-xhigh-fast
arena runners: claude-fable-5-2-high, claude-opus-5-5-high-fast, gemini-4-neon-high
arena cross-judge pool: claude-opus-5-5-high-fast, gemini-4-neon-high
swarm workers: claude-opus-5-5-high-fast
interrogate reviewers: claude-fable-5-2-high, claude-opus-5-5-high-fast, gemini-4-neon-high

The roles fall into three groups:

  • Code delegates. Each code playbook reads its own line: feature, refactoring, bug-fix, perf-issue, or hillclimb. All default to Opus 5.5 at xhigh.
  • Judgment and prose. Writing and decisions also default to Opus 5.5 at xhigh.
  • Panels and workers. The /arena and /interrogate panels default to 3 seats from 3 model families: Fable 5.2, Opus 5.5, and Gemini 4 Neon, each at high. swarm workers is the default model for every /swarm worker and for trivial mechanical edits; verification also runs on it.

A few rules hold across all roles:

  • No role runs above xhigh.
  • medium lowers each role one effort level and small lowers it two, on the ladder xhigh, high, medium, low. Both spend fewer tokens.
  • Opus 5.5 always runs its -fast slug. A Gemini seat never runs above gemini-4-neon-high.
  • Outside a panel, Fable 5.2 runs only when you name it for the task, or after two Opus 5.5 runs of the same brief have failed their check. Difficulty alone never qualifies.

Panels, judges, and the parent model

A panel role is a list, and pstack runs one subagent per entry, so the length of the list sets the size of the panel. The arena cross-judge pool is also a list, but /arena runs only 1 judge. It takes the first entry from a vendor other than the parent chat’s vendor, and Fable counts as the same vendor as the other Claude models.

If you use Cursor’s Auto setting, write inherit-parent or auto as a role’s value. Both mean the same thing: pstack omits the subagent’s model field, so the role runs on the parent chat’s model. An alias entry in a panel list still counts toward the panel size, but it never acts as the cross-judge.

Keeping the cost in check

pstack spends extra tokens on subagents and review panels; the guide calls that the price of the rigor. To spend less:

  • Rerun /setup-pstack with a smaller budget or cheaper models. The guide suggests a strong model in the main chat and cheaper, faster models in the code roles.
  • Set a role to auto or inherit-parent so it runs on the chat’s own model.
  • Shorten a panel list, since each entry runs one subagent.
  • Keep /poteto-mode for work that needs rigor. A small, obvious edit does not.

Two optional offers at the end of setup

Setup ends with two offers, each made once.

First, if the project has no way to drive the real app for proof (no verify-* skill and no existing test rig of that kind), setup offers to run /create-verification-skill. That skill writes .cursor/skills/verify-<app>/, a project-local skill that teaches agents to launch your app, use it the way a user does, and capture evidence. It runs the new skill end to end once before handing it over, because a generated skill that was never executed counts only as a draft.

Second, if the project does not have one yet, setup offers to run /create-formal-verification-skill. Tests cover only the cases that someone remembered to write, whereas a formal verification skill checks a single key property, such as “a job never runs twice at once”, across every case inside a declared scope. The guide suggests it for code involving concurrency, retries, a state machine, or a parser: places where bugs are expensive and tests seldom hit the failing case.

If you decline either offer, setup moves on, and you can run the skill later. For newcomers the guide recommends accepting the first offer: an agent that can check its own work keeps going until the check passes, whereas one that cannot hands every result back to you. Of everything in the guide, it says, the verification skill pays off the most. The chapter Verification skills covers both kinds in depth.

Your first task

Pick something real but small and describe it the way you would to a colleague:

/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both.

Watch the todo list: its first items are the steps of the matched playbook, which for this prompt is Feature. The next chapter explains how /poteto-mode reaches that choice and how to write prompts for it.