pstack

pstack is a set of Agent Skills and workflow playbooks for careful software work. It helps an agent understand a codebase before editing it, choose a shape before writing code, and verify the real result before calling a task done.

I built it around a simple preference: one small, well-understood change is worth more than a large patch that merely looks plausible. When each change has evidence behind it, independent work can run in parallel without turning into noise.

pstack comes from poteto. Use it as-is, fork it, or keep the parts that fit how you work.

What this package is

This repository is an Agent Plugins 1.0.0 package and a portable fork of Cursor's pstack plugin.

The portable package has one component type:

plugin.json is the Agent Plugins manifest.
skills/ contains the Agent Skills. A compatible client discovers each immediate child directory with a SKILL.md file.

pstack does not ship an mcp.json because it has no MCP server. The nested playbooks, references, and scripts support their parent skills. They are not separate discovered skills.

The repository also contains client adapters and maintenance files:

package.json describes the Pi package.
profiles/ contains Pi settings fragments.
scripts/install.sh is a legacy fallback for clients that cannot load Agent Plugins and only read user skill directories.
docs/guide/ is the usage guide.
UPSTREAM.md records the fork boundary and sync rules.

The root skills/ tree is the source of truth. Do not copy a skill for one client or profile. Add it under skills/ and update the relevant adapter or profile.

Install

Agent Plugins-compatible clients

Use the client's Agent Plugins installation flow and point it at the repository root. The standard defines the package layout, not distribution or installation.

The client reads plugin.json, then discovers the skills under skills/. Do not run scripts/install.sh in this mode. That script copies skills into legacy user directories and bypasses plugin discovery.

Pi

Install the Pi package from Git:

pi install git:github.com/0x7067/pstack

From a local checkout, use:

pi install .

Run /reload after installation so the current session sees the skills.

The full catalog is the default package. A smaller Pi-only profile is available at profiles/pstack-lite.json. It selects ten skills and keeps one package source.

Full catalog: pi install git:github.com/0x7067/pstack@<sha>
Lite profile: install the root package, then replace its package entry in Pi settings with the filtered entry from profiles/pstack-lite.json. Pin the source to the SHA you installed. Do not add the profile beside an unfiltered pstack entry.

If you previously ran the legacy installer, Pi may load those copies from ~/.agents/skills before it loads the package. Keep the copies if another legacy client needs them. Pi-only users can remove the pstack copies from ~/.agents/skills so the package is the only source.

Clients without Agent Plugins support

Use this path only when the client cannot load an Agent Plugin and only reads skills from a user directory. If the client supports Agent Plugins, install the repository root as a plugin instead.

From the checkout, run:

scripts/install.sh

The installer copies each skill to ~/.agents/skills and creates a symlink for each skill under ~/.claude/skills. Use --dry-run to inspect the targets before writing them.

These are the invocation forms used by the direct skill-directory integrations:

Client	Example
Codex	`$poteto-mode`
Claude Code	`/poteto-mode`
oh-my-pi or prime-agent	`/skill:poteto-mode`

Use the client's own syntax when it exposes a different command form. Natural language also works: use the poteto-mode skill for this task.

Start here

Install pstack using the path for your client.
Run setup-pstack if you want model overrides for delegated work. Otherwise, every role inherits the parent model.
Use poteto-mode for a non-trivial task.

For a guided walkthrough, read the pstack guide. It covers setup, task routing, code exploration, design, implementation, verification, and long-running work.

A good first prompt names an outcome and a check:

Use poteto-mode. The export writes duplicate rows when a retry lands mid-run. Reproduce it first, then fix it and verify the result.

Use poteto-mode

poteto-mode is the default entry point. It stays out of the way for small requests and routes work that needs rigor.

When it applies, the skill:

Starts the harness's plan or todo tracker, or keeps the same checklist in the conversation.
Reads the principles index before choosing a path.
Matches the task to a playbook and copies the playbook's steps into the tracker.
Routes to focused skills such as how, why, architect, tdd, or interrogate as the steps require them.
Verifies the real artifact and reports the decisions and evidence.

The mode is sticky. It remains active for the conversation until you opt out. It uses the current harness's native subagents, recurring work, schedulers, and background execution when available. Without those features, it uses a bounded plan and reports the limit.

Playbooks

Playbook	Use it for
Investigation	Answering a read-only question about behavior, design, or history.
Bug fix	Reproducing a defect, finding its root cause, and fixing it with runtime evidence.
Perf issue	Tracing a measured slowdown and improving it against a baseline.
Hillclimb	Repeating measured experiments to improve one metric toward a target.
Runtime forensics	Diagnosing a live symptom such as a leak, idle CPU spin, or glitch.
Trace forensics	Diagnosing a captured profile or trace artifact.
Feature	Building new behavior from a named data shape.
Refactoring	Changing structure without changing behavior.
Prototype	Comparing cheap sketches before making a design decision.
Visual parity	Matching two UI implementations against visual evidence.
Authoring a skill	Writing or changing an Agent Skill.
Eval	Testing how a skill, prompt, or structure change affects agent behavior.
Babysit	Driving a pull request or stack through conflicts, review, and CI.
Shipping	Independently verifying a green stack before landing the contiguous run.
Autonomous run	Driving one task to a defined completion condition without stopping.
Orchestrate	Coordinating a project that spans many phases, pull requests, and agents.
Autopilot full	Running independent pull requests to merge with one owner per pull request.
Autopilot stack	Building and verifying one linear stack for the operator to land.
Session pickup	Resuming work from a transcript, cloud-agent URL, or pushed branch.
Pause safely	Stopping in-flight work with a checkpoint that another session can resume.
Multi-phase plan	Organizing work that spans phases or stacked pull requests.
Worktree cleanup	Safely reclaiming space from stale worktrees and iOS simulators.
Opening a pull request	Preparing a focused pull request at the end of another playbook.

Other skills

Use these skills directly when you already know which kind of help you need. poteto-mode routes to many of them automatically.

Skill	Use it for
Architect	Settling a function boundary, its callers, types, and module shape before implementation.
Arena	Running competing design or implementation attempts and combining the useful parts.
Automate me	Drafting a personal mode from how you actually work.
Blast radius	Finding what a small-looking change could break.
Bro	Restating the last message in plain language.
Comment Sicko	Reviewing comments without changing the code.
Create verification skill	Generating a project-local skill that proves app behavior.
Figure it out	Designing a rigorous path when no bundled playbook fits.
How	Explaining runtime flow, ownership, and layering.
Hillclimb	Running a sustained, measured improvement loop.
Interrogate	Trying to break a change with independent judgment and review.
Maintain verification skill	Keeping a project's verification map aligned with the app.
Make bot UI	Building a UI whose actions call an existing agent or automation endpoint.
No comments	Finding and removing narrating comments before review.
Pause safely	Creating a clean resume point before going offline or restarting.
Recall	Rebuilding recent context from the shared record and chat history.
Reflect	Capturing lessons from a completed task for the next run.
Session pickup	Taking over another agent's in-flight work.
Setup pstack	Configuring model roles for the active harness.
Show me your work	Keeping an auditable decision trail.
Swarm	Splitting independent work across parallel workers.
TDD	Writing a failing test before fixing a behavior.
Teach	Building an explanation of a change from how and why evidence.
Technical writing	Writing readmes, RFCs, PR descriptions, and other technical documents.
TypeScript best practices	Applying type-system discipline to TypeScript.
Unslop	Removing AI tells from writing.
Why	Finding the reasons behind a design or decision.

Principles

poteto-mode reads this index before it chooses a playbook. Read the linked skill when a principle shapes a decision.

Principle	Rule
Laziness protocol	Prefer deletion and the smallest change that solves the problem.
Foundational thinking	Choose the core types and data structures before writing logic.
Redesign from first principles	Treat the requirement as foundational instead of bolting it onto the old design.
Subtract before you add	Remove dead weight and redundant paths before adding more structure.
Minimize reader load	Reduce layers and hidden state between a question and its answer.
Outcome-oriented execution	Converge on the target architecture instead of preserving throwaway intermediate states.
Experience first	Choose a useful, polished result over implementation convenience.
Exhaust the design space	Compare competing prototypes before committing to a design.
Build the lever	Build the tool that performs or proves non-trivial work.
Model the domain	Encode domain rules in a structure instead of scattered conditionals.
Boundary discipline	Validate at system boundaries and keep internal logic typed and direct.
Type-system discipline	Make illegal states unrepresentable and derive types from authoritative data.
Make operations idempotent	Make partial reruns converge on the same end state.
Migrate callers, then delete legacy APIs	Move callers and remove the old API in the same change wave.
Separate before serializing shared state	Remove sharing first. Serialize only when one shared writer is a real invariant.
Prove it works	Verify the actual artifact instead of trusting a proxy or a self-report.
Fix root causes	Trace symptoms to their cause instead of adding guards that hide them.
Sequence verifiable units	Break multi-step work into small units and verify each before continuing.
Guard the context window	Route bulk work to subagents and keep summaries in the main thread.
Never block on the human	Proceed when the next step is reversible and let the human course-correct later.
Encode lessons in structure	Put durable rules in metadata, scripts, checks, or runtime behavior.

Models and harnesses

pstack uses the active harness's capabilities instead of requiring a custom agent-file format. It uses native plans, todos, subagents, background execution, recurring work, and browser or connector tools when the harness exposes them. A missing capability narrows the workflow. It does not block the task.

Run setup-pstack once per harness when you want overrides. It writes ~/.agents/pstack/models/<harness>.md. A missing role inherits the parent model. Use only model identifiers that the active harness confirms.

The pstack-harness skill owns the adapter rules. Read it before using model overrides, delegation, questions, recurring work, transcripts, or surface-driving tools.

Guide and maintenance

Read the guide for a first task and the full workflow.

Before opening a change, run:

npm run check
npm test
scripts/install.sh --dry-run

The first two commands validate the package and skills. The last command checks the legacy installer without writing to your home directory. Use it because the installer is still part of the fallback path, not because Agent Plugins clients need it.

Read UPSTREAM.md before importing changes from the original Cursor repository. Keep client-specific behavior out of the portable skills unless the harness adapter owns it.

License

MIT