pstack

pstack is a set of skills for rigorous engineering with coding agents. If you want to go fast, go deep first: the skills help an agent write less code and better code, and they let you run several agents in parallel and trust each one to apply the same engineering principles.

It is poteto's pstack, first published in cursor/plugins. This repository is a fork that runs on Claude Code, Codex, and Grok, in a terminal, in Orca, or in the Claude and ChatGPT desktop apps. Every skill, playbook, and bundled script was rewritten by hand, and none of it needs Cursor. docs/decursor-progress.md records how.

What this fork changes

A step names what it needs, not a tool. A skill says spawn-worker, ask-user, or wake-on-event. The resolve-capability skill is the contract: what each capability means, whose mechanism answers it, and what to do when nothing can. Each product's facts live in its own adapter under resolve-capability/adapters/. When Claude Code, Codex, Grok, or Orca change, that product's adapter changes and the other skills stay put. Removing a product means deleting its adapter folder, and adding one means adding a folder. docs/harness-adapters-design.md has the design.
Models are chosen for the task, from your own setup. /setup-pstack surveys the agent products and models on your computer, asks about your budget and preferences, and writes a select-model skill. A task reads it and decides which model to use and how: stay in the session, a subagent, another vendor's agent as a worker, or several models together. docs/select-model-design.md has the design.
Orca is an enhancement. Without it, a session still starts another vendor's agent by running that product's CLI (codex exec, claude -p, grok -p). Orca adds supervised workers, durable runs, an inbox, schedules, and remote environments.
Cursor-only features are gone. docs/removed-cursor-features.md records each one, what replaces it, and how to rebuild it.

Install

npx skills add ynginkim/pstack-orca -g -a claude-code -a codex -a grok -s '*' -y

This installs the skills for the three harnesses. Codex reads ~/.agents/skills/ directly, and Claude Code and Grok list them through links in ~/.claude/skills/ and ~/.grok/skills/. Start a new session afterwards. Run the same command again to update, and npx skills remove -g <name> to remove one. A skill runs as /name in Claude Code and as $name in Codex.

Inside Orca, install and update this way instead:

env -u CLAUDE_CONFIG_DIR npx skills add ynginkim/pstack-orca -g -a claude-code -a codex -a grok -s '*' -y

When Orca starts Claude Code under one of its accounts, it sets CLAUDE_CONFIG_DIR to that account's profile, and every command run from the session inherits it. With it set, the skills CLI (as of 1.7.4) writes links in ~/.claude/skills/ that point nowhere, and Claude Code stops listing the skills (vercel-labs/skills#456). Codex and Grok still see them. find ~/.claude/skills -maxdepth 1 -type l ! -exec test -e {} \; -print lists the broken links, and the command above repairs them.

The agents/ files are not installed by the skills CLI. poteto-mode and no-comments carry what they need and work without them.

Get started

Run /setup-pstack ($setup-pstack in Codex) once. It asks five questions about budget and model preferences, and one about linking the result into each product's skill folder.
Use /poteto-mode whenever you are doing anything that requires rigor.

New here? The pstack guide walks through a first real task, from setup and prompting through verification and overnight runs. Stuck, or unsure which skill fits? Ask /poteto-help.

Out of the box, with no select-model, poteto-mode keeps every seat on the harness it runs in. It gives prose, judgment, and the hardest changes that harness's strongest model, gives routine code and reading a faster one, and suggests /setup-pstack once in its reply.

Where it runs

Place	What it gives
A terminal, with Claude Code, Codex, or Grok	Each product's own subagents, and the other products' CLIs started headless from the shell.
Orca	The same terminals, plus supervised workers on any installed agent, durable runs, schedules, and remote environments.
The Claude desktop app (Code tab)	Claude Code with parallel sessions and optional worktrees. A shell, and no Orca.
The ChatGPT desktop app (Codex)	Codex with subagents, worktrees, and scheduled tasks. A shell, and no Orca.

Only the first two places have been run end to end here. In the Claude desktop app, /poteto-mode ran and showed its plan. In the ChatGPT desktop app, $poteto-mode ran, and the plan list did not appear. Everything else about the two apps is described from their documentation and from the same CLIs.

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.

It comes with twenty-three playbooks:

the twenty-three 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 bottom-up through github.
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. a swarm verifies each code-ready head, and every later change to the patch gets a fresh check.
autopilot-stack	autopilot-full without the merge. build and verify prs for the operator to review and land, stacking a pr only on a pr it builds on.
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.
opening a pr	open a ready pr from small ordered commits with a conventional commits title and a briefing-style body. invoked at the end of every other playbook.

When invoked it:

matches your task to a playbook and opens a plan whose first items are its steps, copied in verbatim.
runs detect.sh first, reads resolve-capability with the adapters for its harness and for each environment found, reads select-model, and decides which model runs each piece of work and how.
routes to the other skills as the steps fire.
writes unslopped replies framed for the consumer and the maintainer.

The full rules and playbooks live in skills/poteto-mode/SKILL.md. The skill stays in context until the chat is compacted, so type /poteto-mode again at the start of the next task.

For work that runs for hours, give the run a loop or a schedule: /loop in Claude Code, an Orca automation, or a scheduled task in the Codex app. poteto-mode works well with them, because each tick checks a predicate that can pass or fail.

Skills

/poteto-mode runs most of these for you when a step needs them (how, why, architect, arena, swarm, interrogate, unslop, deslop, no-comments, control-ui, control-cli, technical-writing, tdd, and the principles). The table below is for when you want one directly:

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

/interrogate review this pr.

all skills

skill	use it when
`/poteto-mode`	default entry point for any non-trivial task.
`/poteto-help`	you're new to pstack, or unsure which skill, playbook, or principle fits. finds out what you're trying to do, answers that part, and hands you a prompt to type. runs only when you type `/poteto-help`.
`/in-your-own-words`	you want the agent to play back your goal and the problem before it starts. runs only when you type `/in-your-own-words`.
`/sharpen`	you want a prompt made deeper, not bigger, before you send it: what a top professional would do that you didn't ask for, the raw material they'd start from, their methods and tools, and an outside check that the result is right. hands back the rewritten prompt and leaves your choices open. doesn't do the task. runs only when you type `/sharpen`.
`/how`	you want a walkthrough of how a subsystem works.
`/why`	you want to know why something was built this way. discovers available MCPs at run time and queries each evidence category in parallel (source control, issue tracker, long-form docs, real-time chat, infra observability, error tracking, analytics warehouse).
`/recall`	you're starting or resuming work and want your recent context on a topic rebuilt from your own chat history and the shared record, handed back as a tight current-state brief.
`/ketchup`	you want what changed in this chat since your last message, in plain words and small visuals, with every item waiting on you listed and decidable from the reply alone, even when that makes the reply long.
`/ketchup-video`	you want the `/ketchup` catch-up as a short subtitled video of slides, with the calls waiting on you as text under it.
`/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.
`/architect`	you're about to write code that crosses a function boundary and want the caller's usage, types, and module shape settled first.
`/arena`	you want N parallel attempts at the same thing, then to grab the best parts of each.
`/swarm`	you want N parallel workers across different slices or races, then one aggregated report.
`/interrogate`	you have a diff and want different models to try to break it, keeping only findings a run proves.
`/automate-me`	you want your own `-mode` skill, drafted from how you've actually worked.
`/setup-pstack`	you want pstack set up for this computer and for you. surveys the agent products and models you have, asks about your budget and preferences, and generates the `select-model` skill that every task reads to choose its models.
`/create-model-selection-skill`	`/setup-pstack` runs it for you. surveys this computer, asks the preference questions, and writes `select-model`.
`resolve-capability`	not something you type. the contract that other skills read, with one adapter per product under `adapters/` (claude code, codex, grok, orca). together they say how each thing a step asks for (start a worker, ask you, wait for an event) is done where you are.
`/reflect`	a long task landed and you want the recipe captured as a skill edit.
`/correct`	you keep correcting agents for the same mistakes. mines history for mistake classes, fixes each at the highest level that works (architecture, then types, lint, and ci, then tests, with docs last), and keeps a table pairing each rule with what enforces it.
`/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.
`/tdd`	you're fixing a bug and there's a cheap local test path. write the failing test first, then the fix.
`/benchmark-checklist`	you ran a benchmark or measured a speedup or regression. vets the number (limiter, tuning, errors, repeat runs, end-to-end relevance) before you report or act on it.
`/deslop`	before commit. removes code slop the branch added: defensive checks a trusted path doesn't need, casts that dodge the type system, deep nesting, code that doesn't match its file. leaves comments to `/no-comments`.
`/no-comments`	strip comments before review; spawns Comment Sicko, fixes accepted findings, offers encodings for claimed constraints.
`/typescript-best-practices`	you're reading or editing typescript. grounds the type-system-discipline principle in syntax.
`/figure-it-out`	no bundled playbook fits. designs a rigorous, auditable playbook for the task.
`/show-me-your-work`	you want a reviewable decision trail. logs decisions to a tsv you can commit.
`/control-ui`	you want a web, ide, or electron ui driven for real and checked with screenshots, snapshots, or profiles. uses your harness's browser tool, or builds a temporary playwright or devtools-protocol harness.
`/control-cli`	you want a cli or tui driven for real with fixed input and checked with transcripts or profiles. uses your harness's terminal tool, or builds a temporary tmux or pty harness.
`/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.
`/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.
`/create-formal-verification-skill`	tests can't reach the case that breaks a race, retry, state machine, parser, or unsafe code. verifies one property with the tool that fits and generates a project-local skill to recheck it on every change.
`/maintain-formal-verification-skill`	code your formal verification covers has changed since it was last checked. updates the model, harness, or properties to match the code, reruns, and says whether each failure is drift in the verification or a bug in the code.
`/statechart`	someone who owns the behavior needs to see it, not read a spec. checks a tla+ model, draws what the user sees as a mermaid statechart, marks each state that breaks a rule, and gives the shortest path to each one.
`/unslop`	you're cleaning up writing. removes AI tells.
`/bro`	you want the last message restated in plain human language, no jargon.
`/technical-writing`	layered doc standard (Diátaxis + Google developer style + STE + Global English) for docs, RFCs, readmes, PR descriptions, commit messages.

Examples

Mostly you type /poteto-mode at the start of a task and let it route to a playbook. The other skills fire as the steps need them.

all the examples

bug fix:           /poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even
                   when idle. repro first, then fix and verify.
perf:              /poteto-mode a big list takes a second or two to load even though we virtualize.
                   run a cpu trace and tell me why.
feature:           /poteto-mode build a small feature behind a feature flag. verify it really works.
prototype:         /poteto-mode build two prototypes of the markdown renderer so we can compare.
                   spawn an agent for each.
multi-phase:       /poteto-mode open source these skills as a plugin. nothing internal leaks, work
                   in a temp dir, show me the dependency graph first.
overnight run:     /poteto-mode i'm going to bed. land the stack even if ci flakes. i want
                   everything merged by morning.
babysit:           /poteto-mode check on pr 123. anything outstanding?
visual parity:     /poteto-mode the row spacing is too tall when this flag is on. the second image
                   is correct. repro and fix until it matches.
figure it out:     /poteto-mode i'm stepping away. migrate every caller from the synchronous store
                   to the new async one, keeping behavior identical. i want to trust it was done
                   right when i'm back.
how:               /how do we cancel runs? do we have an n+1 when we look up every run to cancel?
why:               /why is this feature flag not on yet?
architect:         design this instrumentation to be high signal with no false positives. /architect
                   this first.
arena:             /arena take my prompt to the arena verbatim. i want to compare their proposals
                   with yours.
swarm:             /swarm check every package under packages/ against its check.sh. one worker per
                   package. one report.
interrogate:       /interrogate review this pr.
tdd:               /tdd implement
unslop:            can we unslop and tighten the new changes?
reflect:           /reflect that took too long. capture what we learned so the next run doesn't
                   repeat it.
correct:           /correct
show-me-your-work: /show-me-your-work keep a decision trail i can review when i'm back.
automate-me:       /automate-me
help:              /poteto-help which skill should i use to review this branch?

The `poteto-agent` and Comment Sicko subagents

/poteto-mode runs in the chat that receives it. That chat owns the playbook, the plan, and every subagent spawn.

pstack ships poteto-agent as the wrapper for delegates spawned during a run. It reads poteto-mode in full, including its principles index, before doing any work. Where your harness has no such agent type, poteto-mode starts a general-purpose subagent with the same instruction as its first line. Do not start a poteto-agent to run the playbook itself.

pstack also ships Comment Sicko, a comment reviewer. Usually invoke it through /no-comments, which carries its prompt, and not directly.

Principles

Twenty-four 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-four 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.
attack-the-premise	core	Apply when 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.
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, 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 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.
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.
test-behavior-not-implementation	verification	Apply when you write, change, or keep 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.
explain-the-number	verification	Apply 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.
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.

Not shipped here

There is no skill that drives a native desktop window. The drive-app capability in resolve-capability says how each environment does it.
Skill authoring and /loop come from your harness. The authoring playbook covers the rest.

Why are there no planning skills?

Your harness already has a plan mode, and it works with pstack. But the best spec is code. If you do want a plan, /poteto-mode covers it with the multi-phase plan playbook, but it is not a default.

Make it yours

poteto-mode is one person's style. You may not want exactly that.

Type /automate-me. It mines your recent transcripts, drafts a <your-name>-mode skill from how you have 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. Run /setup-pstack again whenever you add an agent product or change your mind. To change one preference, edit its sentence under ## Preferences in ~/.agents/skills/select-model/SKILL.md.

Contributing

PRs are welcome. Before you open one:

node scripts/lint-rewritten.mjs keeps Cursor wording and product names out of rewritten skills. A skill names capabilities, and each product's adapter holds that product's facts. node scripts/check-ownership.mjs fails when a product's name or tool appears outside its own adapter.
.agents/skills/verify-pstack proves a change by running it in real Claude Code, Codex, and Grok sessions, through Orca or headless with no Orca at all. It is for contributors and is not installed by the skills CLI.
MIRROR.md says how upstream changes arrive: as a weekly issue, not as a merge.
CURSOR-DEPENDENCIES.md lists the Cursor-dependent lines that have not been rewritten yet.

License

MIT. /deslop, /control-ui, and /control-cli are adapted from Cursor's cursor-team-kit, which is MIT-licensed by Cursor. Each of those skill folders carries its LICENSE.