pstack for Codex and Claude Code

English | 简体中文

One source tree, one configuration, two native host entry points. This independent local adaptation tracks Lauren Tan's MIT-licensed upstream pstack 0.15.21 at 997ffc7f. It is not maintained by Lauren Tan, Cursor, OpenAI, or Anthropic.

The 55 skills, 23 playbooks, engineering principles, agent prompts, and Node helpers are shared. Only the plugin manifests and two short runtime adapters differ. Codex retains its installed pstack-codex name; Claude Code uses pstack from the same directory.

Install and use

Clone the repository once per machine, then register that same checkout with each host. See setup and updates for prerequisites and existing installations.

git clone https://github.com/mtmtian/pstack-remix.git "$HOME/plugins/pstack-remix"
cd "$HOME/plugins/pstack-remix"
codex plugin marketplace add "$PWD"
codex plugin add pstack-codex@pstack-local
claude plugin marketplace add "$PWD"
claude plugin install pstack@pstack-local --scope user

Marketplace registration is needed only once per host. Host caches are generated installation copies; edit only the checkout. Machines already using pstack-codex@personal can retain that registration if it points to the same checkout; do not install a duplicate under a second marketplace.

• Codex entry: $pstack-codex:poteto-mode.
• Claude Code entry: /pstack:poteto-mode.
• Optional setup: $pstack-codex:setup-pstack or /pstack:setup-pstack.

Preferences are shared in ~/.config/pstack/config.json. Roles inherit the main conversation unless configured; workers receive the resolved policy and do not need setup. Concrete model choices are host-scoped so one vendor's model ID never leaks into another host. The exception is an external agent's own model, such as xagent:claude/claude-opus-5-5: xagent hands it to that agent's CLI from either host, so it can be shared. Shared reasoning and panel-size preferences apply to both when the actual runtime supports them. Shared required_panel_members adds external agents such as xagent:grok to every panel on both hosts, and those entries are never silently skipped. Shared auxiliary_panel_members marks external members, such as xagent:gemini, whose failure after a retry is reported as a gap instead of blocking a panel the other members finished. Shared xagent_effort_caps, such as {"gemini": "high"}, keeps an external agent's effort within the levels its CLI's model accepts. On Codex and Claude Code, an agent type whose definition sets its own effort keeps it; shared reasoning reaches the rest, including external agents. See the runtime contract.

Examples below use $skill as a short reference to the bundled skill; in Claude Code invoke /pstack:skill or read its file through the host's skill interface.

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. If you are new to pstack or unsure which skill fits, invoke $poteto-help for guidance and a prompt to send.

just use $poteto-mode

This skill is the main shortcut for rigorous engineering work. It comes with twenty-three playbooks.

$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 stepping away. prepare and verify the stack in an isolated worktree. stop at
the first unresolved check and leave an auditable decision log. I will authorize remote landing separately.

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 prepare or land the contiguous verified run bottom-up when an authorized forge tool is available.
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 through verification and, only with authorized remote access, merge them with one owner per PR and root verification of every code-ready or patch-changing round.
autopilot-stack	build and verify one linear base-branch 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.
opening a pr	prepare a ready PR from small ordered commits with a conventional commits title and a briefing-style body when a PR is requested and authorized.

when invoked it:

1. matches your task to a playbook and opens a todo list whose first items are its steps, copied in verbatim.
2. routes to the other skills as the steps fire.
3. writes unslopped replies framed for the consumer and the maintainer.

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

$poteto-mode is also a sticky conversation instruction: once entered it stays on across turns, applying itself when a playbook matches or the task needs rigor and staying out of the way otherwise. Opt out any time by saying so.

For a long finite task, explicitly start the host's native goal with /goal. A goal drives work toward a finish condition; its continuation and completion behavior comes from the selected host adapter. It is not a timer and requires an explicit request. Recurring or scheduled work uses an available automation or scheduling interface separately. pstack does not install a timer or claim that a goal will wake itself on a schedule.

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:

$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 are new to pstack or unsure which skill or playbook fits; it gives guidance and a prompt without starting the work.
$in-your-own-words	you want the agent to play back your goal and the problem before it starts.
$sharpen	you want a task approached the way a top expert would, aimed at what you're really after, without overspecifying it or deciding your choices for you.
$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 a few plain sentences and small visuals, with just enough context on each action item to make the call.
$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 several different models to try to break it, including a strict code-quality lens.
$automate-me	you want your own -mode skill, drafted from how you've actually worked.
$make-bot-ui	you want the optional webhook UI workflow; bot credentials, sender keys, and network exposure remain host-dependent and are not enabled by default.
$setup-pstack	you want to pick which models pstack uses per role. detects your models and writes a config rule.
$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.
$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. It grounds the type-system-discipline principle in syntax and loads through the host workflow.
$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.
$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.
$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

Most users 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, and any skill can be invoked directly.

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.
long finite run:   $poteto-mode i'm stepping away. prepare and verify the stack in an isolated
                   worktree. stop at the first unresolved check and leave an auditable log.
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

Shared agent prompts

The shared poteto-agent and comment-sicko files are native Claude Code agent definitions. Codex passes their bodies to supported collaboration roles instead of inventing custom agent types. Both read the same runtime and skills. The chat that receives $poteto-mode runs the playbook; poteto-agent wraps the delegates it spawns and never runs the playbook itself. Comment Sicko has read-only tools in Claude and requires a matching read-only role/scope in Codex.

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.

Host adapters

Shared runtime owns configuration, scope, evidence, and shared skill discovery. Codex and Claude Code define their native delegation, goal, and scheduling interfaces. Do not turn one host's tool names into instructions for the other. Inside T3 Code, the T3 overlay sits on top of either host and dispatches workers, schedules, and PR watches through T3's orchestration tools, with its own hosts.t3 model section.

Upstream Cursor control helpers are replaced by available project harnesses and host tools. External writes retain the user's authorization boundaries. Installing this package does not create a goal, timer, bot, or webhook.

make it yours

poteto-mode encodes one opinionated engineering style. Your project may want different defaults.

type $automate-me. it mines your recent transcripts, 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 through setup-pstack, which reads and updates the single shared JSON file. Host-specific overrides preserve existing choices. Defaults need no setup.

Keeping up with upstream

Run the CI checks locally with bash scripts/check.sh after installing the locked build dependencies. GitHub Actions checks the minimum runtime versions, macOS behavior, TypeScript, and distributed bundle freshness on every PR.

Run node <plugin-root>/scripts/check-upstream.mjs. The read-only report compares the pinned UPSTREAM.json commit with the latest pstack change. Review the diff once in this shared tree, preserve both host adapters, run node --test scripts/config.test.mjs, validate/discover both plugins, then refresh both installations per the setup guide. Do not overwrite this adaptation with the upstream Cursor directory.

automations

pstack also ships a dormant Benny automation pack. Benny is a complete on-demand configuration package for issue triage and UI evidence. It has not been enabled with remote Slack access or a recurring schedule. Its files are not registered as slash skills. Configure it only through the documented local automation interface after checking the available host connectors and authorization.

license

MIT