open-pstack technical reference

This page contains the full skill, dependency, runtime, and porting reference. For the plain-English introduction and quick start, see the main README.

Poteto's pstack, adapted to run in Claude Code and Codex without Cursor. One shared skill tree serves both harnesses; Grok remains available as a model-provider lane. Version 1.2.0 is synced to Cursor pstack v0.14.3 at bdf7aa355337897f167153e05069aca505dae17c. See UPSTREAM.md for the exact sync contract.

Original by Lauren Tan. This distribution builds on Michael Denyer's pstack-claude port and retains its history and MIT attribution. It imports seven MIT-licensed skills from cursor-team-kit: deslop, thermo-nuclear-code-quality-review, make-pr-easy-to-review, fix-ci, fix-merge-conflicts, get-pr-comments, what-did-i-get-done.

if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.

This is not a verbatim copy. Skill bodies have been edited so every Cursor-specific primitive resolves to its Claude Code or Codex equivalent — see Differences from upstream for the full list. The exhaustive per-skill audit lives in CHANGES.md; license attribution lives in NOTICE.md; the upstream README is preserved verbatim at README-UPSTREAM.md.

Install

Claude Code

This repo ships as a Claude Code marketplace containing one plugin (pstack).

/plugin marketplace add ericlitman/open-pstack
/plugin install pstack@open-pstack
/reload-plugins

The plugin auto-fires through a SessionStart hook on startup, /clear, and post-compact. The hook injects a small mandate that routes non-trivial engineering work into poteto-mode; the full skill loads only when invoked. Dispatched subagents ignore the mandate, and explicit user instructions take precedence. To opt out, delete hooks/hooks.json from the installed copy at ~/.claude/plugins/cache/open-pstack/pstack/<version>/hooks/hooks.json; a plugin update restores it.

Codex

The same plugin carries a .codex-plugin/plugin.json manifest and a root .agents/plugins/marketplace.json. Install it through the Codex marketplace:

codex plugin marketplace add ericlitman/open-pstack --ref main
codex plugin add pstack@open-pstack

Codex discovers the plugin skills under the pstack namespace, so they list as pstack:poteto-mode, pstack:tdd, and so on. The namespace comes from plugins/pstack/.codex-plugin/plugin.json. To enable the multi-model and parallel-subagent skills (interrogate, arena, how, why, reflect, architect), turn on subagents in ~/.codex/config.toml:

[features]
multi_agent = true

For local plugin development, you can clone the repository and link its skills directly:

git clone https://github.com/ericlitman/open-pstack
cd open-pstack
for s in plugins/pstack/skills/*/; do ln -s "$PWD/$s" ~/.agents/skills/"$(basename "$s")"; done

The marketplace install is the normal user path. Direct links are only for testing a checkout before publishing it. Remove the linked skill directories when the test is over.

Layout

.
├── .claude-plugin/marketplace.json   # Claude Code marketplace manifest (repo root)
├── .agents/plugins/marketplace.json  # Codex marketplace manifest (repo root)
├── plugins/pstack/                   # the plugin itself
│   ├── .claude-plugin/plugin.json    # Claude Code manifest
│   ├── .codex-plugin/plugin.json     # Codex manifest (skills: ./skills/)
│   ├── skills/                       # 52 skills shared by Claude Code and Codex
│   │   ├── poteto-mode/references/{codex-tools,provider-dispatch}.md  # tool + provider routing
│   │   └── poteto-mode/scripts/      # bun/bash/node tooling: watch-pr, orch, runner, check-plan.mjs, worktree-audit.sh
│   ├── hooks/                        # SessionStart auto-fire: injects the poteto-mode mandate (Claude Code only)
│   └── agents/                       # Claude subagents, including native Fable and Opus lanes at each selectable effort
├── tests/skill-collision-repro.sh    # native-skill package invariants and Claude invocation checks
├── LICENSE                           # pstack upstream MIT
├── LICENSE-cursor-team-kit           # cursor-team-kit upstream MIT
├── LICENSE-superpowers               # superpowers upstream MIT (hook runner)
├── NOTICE.md                         # attribution table
├── UPSTREAM.md                       # current Cursor sync point and update procedure
├── CHANGES.md                        # per-skill substitution audit
├── README.md                         # plain-English introduction and quick start
└── docs/reference.md                 # this technical reference

Plugin-internal skills/<name>/ path references in the docs below are relative to plugins/pstack/.

Running on Codex

The Codex build shares one skills/ tree with the Claude Code build. Nothing is forked or generated. Two narrow references keep runtime translation separate: codex-tools.md maps harness primitives and provider-dispatch.md maps model providers. pstack otherwise keeps the upstream Claude-native prose and adds a one-line Platform note to each skill that names a Claude primitive, so the port stays in lockstep with upstream sync.

Skill invocation. Codex loads SKILL.md natively. There is no Skill tool. You invoke a skill by name (ask for it, or pick pstack:poteto-mode from the list).
Package surface. The native skills/ tree is the only workflow source. The plugin ships no commands/ layer and does not link prompts into ~/.codex/prompts/. Codex would migrate such files into duplicate source-command skills while loading the native skill tree. The 21 principle-* leaves declare user-invocable: false. Claude keeps them out of its user picker; Codex 0.149.0 currently shows them despite that metadata (#8).
Tool and built-in mapping. Claude tool names and built-in skills resolve through codex-tools.md. Model execution resolves separately through provider-dispatch.md, so Codex can keep Sol native while invoking Claude and Grok externally.
Subagents. The Agent tool maps to Codex spawn_agent / wait_agent, enabled by multi_agent = true. Parallel fan-out is multiple spawn_agent calls in one turn. If the native Codex lane is unavailable, record that lane as a dropout; external Claude and Grok lanes still run, and no provider is silently substituted. There is no poteto-agent subagent type on Codex; route ad-hoc subagents by dispatching a spawn_agent told to read poteto-mode first.
Auto-fire. The hooks/ SessionStart injection is Claude Code-only; Codex has no plugin hook runtime. Enter pstack:poteto-mode by name, or add a standing instruction to ~/.codex/AGENTS.md if you want the same always-on routing.
Models. /setup-pstack writes provider-qualified descriptors and asks one requested effort per frontier family (low, medium, high, xhigh, max). The first-run panel is Fable 5 max, GPT-5.6 Sol max, Grok 4.6 xhigh, and Opus 5 xhigh. A rerun keeps each role's family and rewrites that family's effort. In Codex, Sol uses native spawn_agent; Claude and Grok use the deterministic external runner. In Claude Code, Fable and Opus use native agents; Sol and Grok use the runner. Children never detect the parent or reroute themselves.

Verified in fresh installed Claude Code and Codex sessions: the user-facing skills are discovered and namespaced under pstack; both parents fan out the frontier quad through the documented native/external route table, retain long-running handles without a default timeout, and cross-judge only after every candidate is terminal. The principle-* leaves remain available for poteto-mode to read by path. Claude honors their user-invocable: false metadata; Codex 0.149.0 does not (#8).

Dependencies

Nothing is declared in plugin.json. Install the one companion plugin yourself:

plugin-dev (from the claude-plugins-official marketplace) — the rewiring routes skill-authoring tasks (in automate-me, reflect, poteto-mode) to the plugin-dev:skill-development skill:
```
/plugin marketplace add anthropics/claude-plugins-official
/plugin install plugin-dev@claude-plugins-official
```
Until 0.9.2 this was a dependencies entry in plugin.json. The desktop app's --plugin-dir load mode can never resolve cross-marketplace dependencies and hard-disables the whole plugin, so 0.9.3 removed the declaration — full mechanism in the 0.9.3 entry of CHANGES.md. Without plugin-dev installed, only the skill-authoring routes degrade; everything else works.

Not declared as deps, but referenced in skill bodies:

run, verify, loop — Claude Code CLI built-ins (ship with the binary, always available).
gh CLI — system-level requirement of the babysit skill and the Babysit / Shipping playbooks. Install via brew install gh and authenticate with gh auth login.
bun — runs the vendored skills/poteto-mode/scripts/ tooling (watch-pr, orch, runner). Install via brew install oven-sh/bun/bun. bootstrap.ts installs dependencies for watch-pr and orch; the runner uses only Bun and Node built-ins, so it launches directly without an install/re-exec layer.
node — runs skills/poteto-mode/scripts/check-plan.mjs. The checker uses only Node built-ins and does not need Bun.
Claude Code, Codex, and Grok Build CLIs — the external runner uses the assigned subscribed CLI directly. Install and authenticate only the providers present in your model sheet. Same-provider work stays native; the runner refuses it.
gt (Graphite CLI) — only for the stack playbooks (Shipping, Orchestrate, the autopilots). Everything else works without it.
jq and rg (ripgrep) — only for scripts/worktree-audit.sh (the Worktree cleanup playbook). Without them the audit still runs but blanks its PR and LAST_CHAT columns, so it warns on stderr rather than returning a table that looks complete.

No third-party plugins. The harsher-critique escape hatch lives in the bundled thermo-nuclear-code-quality-review skill (imported from cursor-team-kit), not in an external plugin.

Skills

The table uses the short upstream names. Claude Code exposes each native skill with a /pstack: prefix, such as /pstack:poteto-mode. In Codex, ask for the namespaced skill, such as pstack:poteto-mode.

skill	use it when
`/poteto-mode`	default entry point for any non-trivial task
`/how`	walk through how a subsystem works
`/why`	investigate why something was built this way (parallel multi-MCP evidence)
`/architect`	settle types and module shape before writing code that crosses a function boundary
`/arena`	run N parallel attempts at the same task and pick the best parts
`/interrogate`	have four different models try to break a diff
`/automate-me`	draft your own personal -mode skill from recent transcripts
`/reflect`	capture a long task's lessons as a skill edit
`/tdd`	fix a bug by writing the failing test first, then the fix
`/typescript-best-practices`	ground type-system discipline in TypeScript syntax
`/teach`	understand a change or subsystem for real: `how` + `why` woven into one plain explanation
`/swarm`	fan out N parallel workers across slices or races, then one aggregated report
`/technical-writing`	write docs, RFCs, readmes, PR descriptions, and commit messages to one layered standard
`/bro`	restate the last message in plain human language, no jargon
`/figure-it-out`	design a rigorous, auditable playbook for a task no bundled playbook fits
`/show-me-your-work`	log decisions to a reviewable tsv decision trail
`/blast-radius`	find what a change could break beyond the diff and prove safety by running code
`/recall`	catch up on recent working context from chat history, live state, and the shared record
`/setup-pstack`	configure pstack per-role model choices and per-family requested effort
`/unslop`	clean up writing by removing AI tells
`/no-comments`	strip comments before review via the `comment-sicko` subagent, then fix what it finds
`/create-verification-skill`	generate a project-local verification skill and feature map
`/maintain-verification-skill`	re-sync a drifted verification skill and its feature map
`/deslop`	deslop a diff before commit
`/babysit`	monitor an open PR, fix CI/comments, keep it merge-ready
`/thermo-nuclear-code-quality-review`	extremely strict maintainability audit
`/make-pr-easy-to-review`	clean noisy history and improve PR description before review
`/fix-ci`	find failing PR checks, inspect logs, apply focused fixes
`/fix-merge-conflicts`	non-interactively resolve merge conflicts, validate, finalize
`/get-pr-comments`	fetch and summarize review comments from the active PR
`/what-did-i-get-done`	summarize authored commits over a user-chosen period

Subagents

poteto-agent ships unchanged. Spawn from a parent with subagent_type: "poteto-agent".

comment-sicko is the read-only comment reviewer the no-comments skill spawns. Upstream names it Comment Sicko; the port renames it to comment-sicko so the name is a valid subagent_type. Invoke it through /no-comments, not directly.

Fable and Opus each ship at low, medium, high, xhigh, and max. Names are pstack-<stem>-<effort>. pstack-fable-max and pstack-opus-xhigh remain. Each file pins model and effort, runs in the background, and denies nested Agent/Task dispatch. pstack dispatches them from provider-qualified descriptors; they are not user-facing workflows.

Differences from upstream

The port is editorial, not mechanical. Anywhere upstream pstack assumed Cursor-specific primitives, this port substitutes the Claude Code equivalent so refs actually resolve. Two prior ports (v1truv1us/ai-eng-system, Evan-Kim2028/agent-fleet) stop at namespacing — they vendor pstack under pstack/ and leave the Cursor refs intact. This port does the content surgery.

What's added

skills/babysit/ — Claude Code analog of Cursor's closed-source /babysit built-in. Wraps gh pr view / gh pr checks / gh run view --log-failed plus the loop skill for pacing. Independently authored; workflow informed by Cursor's public /babysit behavior — not a copy of Cursor's implementation. Since the v0.14.2 sync, poteto-mode routes PR-status requests to the ported playbooks/babysit.md instead, and this skill is the standalone /babysit entry point.
skills/deslop/ — imported verbatim from cursor-team-kit. Cleans AI tells out of diffs before commit.
skills/thermo-nuclear-code-quality-review/ — imported verbatim from cursor-team-kit. Used as the harsher-critique escape hatch in arena, interrogate, architect, and how (replaces the Cursor-original cross-vendor bridge).
skills/make-pr-easy-to-review/ — imported verbatim from cursor-team-kit. Composes with opening-a-pr and babysit.
skills/fix-ci/ — imported verbatim from cursor-team-kit. Narrower CI-fix primitive that babysit can route to.
skills/fix-merge-conflicts/ — imported verbatim from cursor-team-kit. Pairs with babysit step 5.
skills/get-pr-comments/ — imported verbatim from cursor-team-kit. Primitive for babysit step 4 and reflect.
skills/what-did-i-get-done/ — imported verbatim from cursor-team-kit. Commit summary over a chosen period.

What's substituted in skill bodies

Upstream (Cursor)	This port (Claude Code)
`Task` tool, `subagent_type: generalPurpose`, `readonly: false/true`	`Agent` tool with model/effort pins and `disallowedTools`; access mode is assigned by the parent, with writers isolated in worktrees
`AskQuestion` tool	`AskUserQuestion` tool
Cursor's built-in `/loop`	Claude Code's built-in `loop` skill
Cursor's built-in `/babysit`	`babysit` skill bundled in this plugin. From v0.14.0 upstream routes PR-status requests inside poteto-mode to `playbooks/babysit.md` instead; the port does the same, and `/babysit` stays the standalone entry point
Cursor's built-in `/create-skill`	`plugin-dev:skill-development` skill
`cursor-team-kit` `control-cli` (CLI/TUI driver)	Claude Code's `run` skill
`cursor-team-kit` `control-ui` (browser/Electron driver)	Claude Code's `verify` skill
Transcripts at `~/.cursor/projects/*/` or `agent-transcripts/`	`~/.claude/projects/<encoded-cwd>/*.jsonl` (where `<encoded-cwd>` is the workspace cwd with `/` → `-`)
Skill paths `.cursor/skills/`, `~/.cursor/plugins/`	`.claude/skills/`, `~/.claude/plugins/`
MCP discovery via Cursor's `mcps/` directory	Tool list at top of system prompt (`mcp__<server>__<name>` entries), or `.mcp.json`, or `claude mcp list`
Cursor cloud agents (`environment: "cloud"`, `cloud_base_branch`)	Local background subagents (`run_in_background: true`), isolated by git worktree
Cursor's `/goal` (standing objective across turns)	The program objective written into the run's standing orders and restated in the todolist
The Cursor agent store (path in the system prompt)	`~/.claude/orchestrate/<project-slug>/`, which survives the session restarts a multi-day program expects
Model rule `~/.cursor/rules/pstack-models.mdc`	Override sheet `~/.claude/pstack-models.md`, included from `CLAUDE.md`
Multi-model panels (arena, architect, interrogate, how-critics)	Provider dispatch restores the upstream frontier quad: `claude:claude-fable-5@max`, `codex:gpt-5.6-sol@max`, `grok:grok-4.6@xhigh`, `claude:claude-opus-5@xhigh`. Same-provider lanes stay native; external lanes use the bundled runner.

Cross-vendor dispatch

The earlier port collapsed panels to Claude-only models. The bundled runner restores upstream's cross-provider judgment signal without adding a daemon or model-router service. Claude Code shells out to Codex and Grok; Codex shells out to Claude and Grok. The top-level parent chooses every route and each external process receives a complete task directly, so there is no supervising model invocation and no child-side harness detection.

What's deliberately kept

The poteto-agent subagent ID and all references to it.
run_in_background: true on Agent calls (Claude Code supports it).
/loop, /deslop, /babysit slash references in skill bodies — they all resolve in Claude Code now.
The principle/playbook structure and every word of the principles themselves.

What's deliberately not ported

automations/benny/ (upstream 0452e08, the only pstack change between e46364b and v0.10.0) — a dormant Slack issue-triage and reproduce-and-fix automation pack built on Cursor's event-triggered automations. It registers no slash skills even upstream, so excluding it changes nothing about the ported plugin's behavior. Porting it would require Cursor's event-trigger runtime, Slack, and tracker plumbing that Open Pstack does not provide.
docs/guide/ (upstream 02c03a9, 0b7ef5b, 424829e) — the ten-chapter usage tutorial and its six screenshots (2.3 MB). It teaches pstack through Cursor's UI, sticky mode, and cloud agents, so a faithful port would be a rewrite rather than a sync, and none of it ships as skill content. Read it upstream at cursor/plugins/pstack/docs/guide; the concepts map through the substitution table above.
Sticky mode (upstream #144) — Cursor-only mode/icon/color/reminder frontmatter with no Claude Code equivalent. The port's 0.9.5 SessionStart hook is the analog and already carries the non-trivial / trivial / opt-out logic.
is_background: true on poteto-agent (upstream 99559f2) — Cursor names this key differently. Claude-native frontier definitions use background: true; ad-hoc poteto-agent calls remain background dispatches at the call site.
cursor-team-kit beyond the seven imported skills — the rest either duplicate Claude Code built-ins (verify-this → the verify skill and built-in verification discipline; check-compiler-errors → LSP diagnostics; control-cli/control-ui → run/verify, already the substitution targets) or overlap skills this port ships (loop-on-ci, review-and-ship, weekly-review vs babysit, fix-ci, make-pr-easy-to-review, what-did-i-get-done). pr-review-canvas is Cursor-UI-specific.

Forking note

Editing skill bodies forks this from upstream. Re-syncing to a future pstack release means re-applying the substitution table. The full re-port recipe is in CHANGES.md.

License

MIT. Three upstream LICENSE files are preserved:

LICENSE — pstack (Lauren Tan)
LICENSE-cursor-team-kit — Cursor (covers the deslop and thermo-nuclear-code-quality-review skills)
LICENSE-superpowers — superpowers, Jesse Vincent (covers the vendored hooks/run-hook.cmd)

FilesExpand file tree

reference.md

Latest commit

History