pi-pstack

i'm poteto. i'm not a president or ceo, but i've worked with millions of lines of code at Meta, Netflix, and Cursor. i'm also on the react core team where i help build and maintain react compiler.

there's a growing sense that ai writes too much slop code. i agree. i don't want to ship like a team of twenty slop artists. throughput without quality is not a goal i aspire to. if you want to go fast, go deep first.

pstack is my answer. these are the same skills i use everyday to ship high quality code. this turns pi into a real engineering team. the goal is not to maximize loc, in fact it's the opposite. pstack helps you write less, but higher quality code.

pstack gives you fearless parallelism. when you can go deep on one agent and trust it to write good, verifiable code, you can truly parallelize with confidence. start multiple subagents up with poteto-mode and trust that they'll apply rigorous engineering principles to their work.

pi gives you the best of all worlds. every frontier model has its strengths and weaknesses. use any model with pstack. in fact, many of my skills use multi-model workflows to take advantage of each model's unique strengths.

fork it. improve it. make it yours. PRs are welcome!

pi port. this is a native pi package port of cursor/plugins → pstack (plus the cursor-team-kit skills pstack depends on). all subagent mechanics now run on pi-subagents instead of cursor's task tool. dropped in the port because they have no pi equivalent: the benny automation pack, grokbot, and pr-review-canvas. see porting notes.

install

# required companion: subagent orchestration (worker / scout / reviewer agents, workflows, steering)
pi install npm:pi-subagents

# the package itself (git install)
pi install git:github.com/ngctro/pi-pstack

# or pin a release tag (recommended; move the pin with `pi update --extensions`)
pi install git:github.com/ngctro/pi-pstack@v0.1.0

restart pi, or run /reload. that's it — the extension registers /poteto-mode, /setup-pstack, and /pstack, the skills load from skills/, and the custom subagents (poteto-agent, comment-sicko, ci-watcher, thermo-nuclear-code-quality-review) load through pi-subagents.

recommended companions (optional, all on pi.dev/packages, sorted by how much pstack leans on them):

package	installs	why
npm:pi-subagents	required	every playbook that fans out: subagent tool, worker/scout/reviewer builtins, async runs, worktree isolation, steering, schedules
npm:@trevonistrevon/pi-loop	recommended	/loop wake loops + MonitorCreate background watches. babysit, autonomous-run, and the overnight playbooks degrade without it
npm:@narumitw/pi-goal	recommended	/goal session objective with budgets. autopilot-full / autopilot-stack arm one on your go
npm:pi-mcp-adapter	optional	MCP tools. /skill:why maps MCP servers to evidence categories (tickets, chat, observability); subagents can request them via mcp:<server> in agent frontmatter
npm:pi-intercom	optional	cross-session coordination. children get contact_supervisor for need_decision escalations (used by orchestrate)

bun is only needed for the poteto-mode helper scripts (scripts/watch-pr/, scripts/orch/); they auto-install their npm deps on first run.

get started

two steps:

1. run /setup-pstack and choose which models you want.
2. use /poteto-mode whenever you're doing anything that requires rigor.

new here? the pstack guide walks you through a first real task, from setup and prompting through verification and overnight runs.

that's it. the other skills are situational; the mode skill uses them for you as needed. out of the box the mode splits work by model strength: precisely-specified code goes to your strongest instruction-following model, fast mechanical code goes to your fast code model, and prose and judgment go to your strongest reasoning model. /setup-pstack changes any of it.

usage

use /poteto-mode at the start of a task. it reads your request, picks from a set of playbooks, and runs the other skills as the steps need them.

/poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even when idle. repro
first, then fix and verify.

/poteto-mode i'm going to bed. land the stack even if ci flakes. i want everything merged by
morning.

when invoked it:

1. opens a todo list. the first item is reading the inline principles index in the skill.
2. matches your task to a playbook and copies the steps in verbatim.
3. routes to the other skills as the steps fire.
4. writes unslopped replies framed for the consumer and the maintainer.

the full rules and playbooks live in skills/pstack/poteto-mode/SKILL.md.

/poteto-mode is also a sticky mode: the extension keeps it on across turns and injects a reminder into the system prompt every turn, so it applies itself when a playbook matches or the task needs rigor and stays out of the way otherwise. /pstack off (or /pstack on, /pstack status) toggles it.

/poteto-mode works extremely well with pi-loop's /loop command. you can make pi work for many hours without sacrificing rigor.

the twenty-two playbooks

playbook	for
investigation	a read-only question. how does x work, why was y built this way, are we sure.
bug fix	reproduce a defect, root-cause it, and fix with runtime evidence.
perf	trace a measured slowness and improve it against a baseline.
hillclimb	sustained, scientific improvement of one metric against a target, looping hypotheses with before/after measurement and one commit per accepted win.
runtime forensics	diagnose a live symptom (leak, idle-cpu spin, glitch) from instrumentation.
trace forensics	diagnose a captured profiling artifact (cpuprofile, trace, spindump, heap snapshot).
feature	new or changed behavior, built from a named data shape.
refactoring	a behavior-preserving change to structure or shape.
prototype	a throwaway sketch to make a design or behavioral decision cheaply, or to settle an empirical fork by observing it.
visual parity	pixel-exact ui equivalence between two implementations.
authoring a skill	writing or editing a SKILL.md.
eval	test how a skill or prompt change affects agent behavior, blinded.
babysit	drive a pr or a stack to merge-ready: conflicts, review threads, ci.
shipping	independently verify a green stack, then land the contiguous verified run with graphite merge-when-ready.
autonomous run	drive a long task to completion without stopping.
orchestrate	a standing project handed to one coordinator chat: multi-day, many stacked prs, fleets of subagents.
autopilot-full	run independent prs to merged with one owner per pr and root verification of each merge-ready head.
autopilot-stack	build and verify one linear graphite stack for the operator to review and land.
session pickup	resume or take over a prior agent's in-flight work.
pause safely	suspend in-flight work cleanly so it can be resumed later.
multi-phase plan	work that spans phases or stacked PRs.
worktree cleanup	reclaim disk by pruning merged or abandoned worktrees and stale ios simulators, safety-gated.

skills

/poteto-mode runs most of these for you when a step needs them (how, why, architect, arena, swarm, interrogate, unslop, no-comments, technical-writing, tdd, and the principles). the table below is for when you want one directly. pi invokes them as /skill:<name>:

/skill:how do we cancel runs? do we have an n+1 when we look up every run to cancel?

/skill:interrogate review this pr.

pstack skills

skill	use it when
/poteto-mode	default entry point for any non-trivial task.
/skill:how	you want a walkthrough of how a subsystem works.
/skill:why	you want to know why something was built this way. discovers available evidence sources at run time (MCP servers via pi-mcp-adapter, git/gh) and queries each category in parallel (source control, issue tracker, long-form docs, real-time chat, infra observability, error tracking, analytics warehouse).
/skill:recall	you're starting or resuming work and want your recent context on a topic rebuilt from your own session history and the shared record, handed back as a tight current-state brief.
/skill:blast-radius	you have a small-looking change and want to know what else it could break, with the one fact it's safe because of proven by running code, not asserted.
/skill:architect	you're about to write code that crosses a function boundary and want the caller's usage, types, and module shape settled first.
/skill:arena	you want N parallel attempts at the same thing, then to grab the best parts of each.
/skill:swarm	you want N parallel workers across different slices or races, then one aggregated report.
/skill:interrogate	you have a diff and want several different models to try to break it, including a strict code-quality lens.
/skill:automate-me	you want your own -mode skill, drafted from how you've actually worked.
/setup-pstack	you want to pick which models pstack uses per role. detects your models and writes .pi/pstack.json.
/skill:reflect	a long task landed and you want the recipe captured as a skill edit.
/skill:teach	you want to actually understand a change or subsystem, not just have it summarized. runs how + why and weaves one plain explanation, built up diagram by diagram.
/skill:tdd	you're fixing a bug and there's a cheap local test path. write the failing test first, then the fix.
/skill:no-comments	strip comments before review; spawns Comment Sicko, fixes accepted findings, offers encodings for claimed constraints.
/skill:typescript-best-practices	you're reading or editing typescript. grounds the type-system-discipline principle in syntax.
/skill:figure-it-out	no bundled playbook fits. designs a rigorous, auditable playbook for the task.
/skill:show-me-your-work	you want a reviewable decision trail. logs decisions to a tsv you can commit.
/skill:create-verification-skill	your project has no scripted way to prove app behavior. generates a project-local verify skill with a feature map, for any language or platform.
/skill:maintain-verification-skill	your verify skill's feature map has drifted from the app. source wave + one live pass, at most one PR of proven corrections.
/skill:unslop	you're cleaning up writing. removes AI tells.
/skill:bro	you want the last message restated in plain human language, no jargon.
/skill:technical-writing	layered doc standard (Diátaxis + Google developer style + STE + Global English) for docs, RFCs, readmes, PR descriptions, commit messages.

team kit skills (bundled from cursor-team-kit)

skill	use it when
/skill:deslop	remove AI slop from the branch diff before commit.
/skill:create-skill	author or edit a SKILL.md for pi (pi-flavored rewrite of cursor's built-in).
/skill:control-cli	drive, inspect, and profile an interactive CLI/TUI through a tmux/PTY harness.
/skill:control-ui	drive and inspect a web/IDE/Electron UI through Playwright or raw CDP.
/skill:verify-this	prove a change does what it claims, with before/after evidence.
/skill:fix-ci	diagnose and fix a failing CI run.
/skill:loop-on-ci	keep watching CI until green, with structured handoffs.
/skill:fix-merge-conflicts	resolve a conflicted branch against its base.
/skill:get-pr-comments	pull unresolved review threads for the current PR.
/skill:new-branch-and-pr	branch, commit hygiene, and a review-ready PR in one pass.
/skill:make-pr-easy-to-review	restructure a diff so reviewers spend attention on the right thing.
/skill:review-and-ship	full pre-merge pass: review threads, ci, evidence, ship decision.
/skill:run-smoke-tests	fast post-change smoke pass.
/skill:check-compiler-errors	sweep compiler/type errors into fixed.
/skill:thermo-nuclear-code-quality-review	extremely strict maintainability audit (pairs with the like-named agent).
/skill:what-did-i-get-done	summarize a work period from sessions, commits, and PRs.
/skill:weekly-review	roll a week of work into themes and follow-ups.
/skill:workflow-from-chats	mine recent sessions for durable preferences and turn them into skills/rules.

the subagents

pstack also ships a subagent that runs poteto's style end to end. spawn it through the pi-subagents subagent tool with agent: "poteto-agent". it reads poteto-mode in full, including its inline principles index, before doing any work. substituting worker skips that read and drifts.

/poteto-mode and agent: "poteto-agent" route through the same wrapper.

also bundled:

• comment-sicko — read-only comment reviewer. usually invoke through /skill:no-comments, not directly.
• ci-watcher — watch PR CI for the current branch and report pass/fail with failure links.
• thermo-nuclear-code-quality-review — the harsh maintainability audit agent (parent gathers the diff and file contents, then invokes it).

principles

twenty-one short skills, one principle each. poteto-mode indexes them inline and reads that index at task start. the standalone files are there so other skills can reference a principle by name, and so the index can point at the full rule for each.

all twenty-one principles

principle	group	rule
laziness-protocol	core	Bias toward deletion and the smallest change that solves the problem.
foundational-thinking	core	Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious.
redesign-from-first-principles	core	Redesign as if the requirement had been a foundational assumption from day one, instead of bolting it on.
subtract-before-you-add	core	Remove dead weight, redundant validators, and stub references first, then build on the simpler base.
minimize-reader-load	core	Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope.
outcome-oriented-execution	core	Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code.
experience-first	core	Choose user delight over implementation convenience; ship fewer polished features over more rough ones.
exhaust-the-design-space	core	Build 2-3 competing prototypes and compare side by side before committing.
build-the-lever	core	Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun.
model-the-domain	architecture	Encode the domain in a structure instead of scattered conditionals.
boundary-discipline	architecture	Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions.
type-system-discipline	architecture	Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, refuse to lie to the compiler, exhaust variants, derive from authoritative schemas.
make-operations-idempotent	architecture	Converge to the same end state regardless of partial prior runs.
migrate-callers-then-delete-legacy-apis	architecture	Migrate callers and delete the old API in the same wave instead of preserving compatibility layers.
separate-before-serializing-shared-state	architecture	Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant.
prove-it-works	verification	Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'.
fix-root-causes	verification	Trace each symptom to its root cause and fix it there; reproduce first, ask why until you reach it, resist nil-check guards that silence crashes.
sequence-verifiable-units	verification	Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer.
guard-the-context-window	delegation	Route bulk to subagents; keep summaries in the main thread, not raw payloads.
never-block-on-the-human	delegation	Proceed, present the result, let the human course-correct after the fact; reserve confirmation for irreversible actions.
encode-lessons-in-structure	meta	Encode the rule as a lint, metadata flag, runtime check, or script instead of more text.

model config

type /setup-pstack. it calls the extension's pstack_models tool to list every model pi can run, shows you each role (code, judgment, the review panels), and writes .pi/pstack.json (project) or ~/.pi/agent/pstack.json (global):

{
  "roles": {
    "feature, refactoring": "openai-codex/gpt-5.6-sol:high",
    "bug-fix": "openai-codex/gpt-5.6-sol:high",
    "how critics": ["anthropic/claude-opus-4-6:high", "openai-codex/gpt-5.6-sol:high", "xai/grok-4.6-fast", "anthropic/claude-fable-5:high"],
    "swarm workers": "xai/grok-4.6-fast"
  }
}

panel roles (how critics, arena runners, architect runners, interrogate reviewers, arena cross-judge pool) take arrays; one subagent runs per entry. inherit-parent or auto runs a role on the parent chat model. the extension injects this config into the system prompt every turn and every skill reads it, so it behaves like an always-applied rule; skills fall back to inline role defaults when an entry is absent.

extension surface

surface	what it does
/poteto-mode [task]	loads the poteto-mode skill and applies it; turns sticky mode on
/setup-pstack [task]	loads the setup-pstack skill
/pstack status|on|off	shows or toggles sticky poteto mode; reports the active model config
pstack_models tool	lists every available model (id, reasoning, context window, cost) for role mapping
system prompt injection	sticky poteto reminder + the role map from .pi/pstack.json

not shipped here

• the benny automation pack (cursor-specific slack triage automation) — not ported.
• grokbot and pr-review-canvas from cursor-team-kit — cursor-specific, no pi equivalent.
• /deslop, control-cli, control-ui, and create-skill are shipped, under skills/team-kit/.

why are there no planning skills?

pi already has great planning surfaces (plan mode, task lists) which work great with pstack. but personally, i don't believe in planning. the best spec is code. if you do want to make a plan, /poteto-mode covers it, but it's not a default.

make it yours

poteto-mode is my style. you may not want exactly that.

type /skill:automate-me. it mines your recent pi sessions, drafts a <your-name>-mode skill from how you've actually worked, and routes through pstack underneath. you keep pstack as the base and end up with your own routing skill alongside poteto-mode.

models are configurable too. type /setup-pstack. it detects the models you have access to and writes a small always-applied config mapping each role (code, judgment, the review panels) to a model. every skill reads it and falls back to sensible defaults when the config is absent, so you override only what you want.

credits and license

pstack is by poteto, original plugin at cursor/plugins/pstack; cursor-team-kit skills by Cursor. this is an unofficial port to the pi coding agent package ecosystem. MIT, same as upstream.