pstack Complete Guide: High-Quality Engineering Workflows for AI Coding Agents
TL;DR
pstack is a plugin system for AI coding agents that enforces rigorous engineering practices. Created by Lauren Tan (@poteto) from the React Core Team and Cursor, it transforms AI agents from "slop code generators" into disciplined engineering teammates.
Key Features:
- 23 specialized playbooks (bug fix, feature development, performance optimization, autonomous runs)
- 24 design principles (Laziness Protocol, Attack the Premise, Prove It Works, etc.)
- Multi-model orchestration (Opus for judgment, Sonnet for coding)
- Verification-first approach (prove before shipping)
Philosophy: "If you want to go fast, go deep first." Quality over quantity.
Installation (Claude Code):
/plugin marketplace add cursor/plugins
/plugin install pstack@cursor-plugins
/pstack:setup-pstack
Basic Usage:
/pstack:poteto-mode Fix the duplicate row bug in export. Reproduce first, then fix and verify.
Table of Contents
- What is pstack?
- Philosophy: Deep First, Then Fast
- Installation & Setup
- Core Concept: Just Use
/pstack:poteto-mode - 23 Playbooks
- 24 Design Principles
- Multi-Model Architecture
- Practical Examples
- Advanced Usage
- Troubleshooting
- References
What is pstack?
pstack is a collection of skills (prompts + workflows) that turn AI coding agents into rigorous engineers. It was created by Lauren Tan, who works on millions of lines of code at Meta, Netflix, and Cursor, and maintains React Compiler on the React Core Team.
The Problem: Slop Code
AI agents often generate "slop code":
- Unnecessary abstractions
- Missing edge case handling
- Unverified changes
- No root cause analysis
- Generic error messages
The Solution: Structured Workflows
pstack provides:
- Playbooks — Step-by-step workflows for 23 task types
- Principles — 24 design rules that guide decisions
- Verification — Every change must be proven against the real app
- Multi-model orchestration — Right model for each task
Result: Less code, higher quality, fearless parallelism.
Philosophy: Deep First, Then Fast
"If you want to go fast, go deep first."
Traditional approach:
- Generate lots of code quickly
- Fix bugs reactively
- Hope tests catch problems
pstack approach:
- Understand the root cause first
- Design before implementing
- Verify against real artifacts
- One commit per proven improvement
Example: Bug Fix Playbook
Traditional:
1. Read symptom
2. Write fix
3. Test
4. Ship
pstack:
1. Reproduce symptom locally
2. Trace to root cause
3. Test the premise itself
4. Implement minimal fix
5. Verify on real app
6. Write tests
7. Ship with evidence
This takes longer upfront but prevents:
- Fixing symptoms instead of causes
- Multiple attempts at the same bug
- Breaking other parts of the system
- Shipping unverified code
Installation & Setup
For Claude Code Users
- Add marketplace:
/plugin marketplace add cursor/plugins
- Install pstack:
/plugin install pstack@cursor-plugins
- Configure models:
/pstack:setup-pstack
You'll choose:
- Budget: unlimited / large / medium / small
- Model per role: Which model handles coding vs. judgment
Recommended for most users: medium budget (high reasoning)
For Cursor Users
/add-plugin pstack
/setup-pstack
Cursor supports full multi-model orchestration (Claude + Grok + GPT).
Verification
Check installation:
claude plugin list
Should show:
❯ pstack@cursor-plugins
Version: 0.15.32
Status: ✔ enabled
Core Concept: Just Use /pstack:poteto-mode
You don't need to memorize 23 playbooks. Just use one command:
/pstack:poteto-mode [your task]
poteto-mode automatically:
- Reads your request
- Picks the right playbook
- Creates a task list
- Executes the workflow
- Calls other skills as needed
Examples
Bug fix:
/pstack:poteto-mode There's a subtle bug where scroll drifts every 750ms even when idle. Reproduce first, then fix and verify.
→ Selects Bug fix playbook
Feature with design exploration:
/pstack:poteto-mode Add user authentication. Compare multiple design approaches before implementing.
→ Selects Feature playbook + calls /pstack:architect
Overnight autonomous work:
/pstack:poteto-mode I'm going to bed. Land the entire stack (PRs #123-125) even if CI flakes. I want everything merged by morning.
→ Selects Autonomous run + Shipping playbooks
When You're Stuck
/pstack:poteto-help Which skill should I use to review this branch?
It answers with:
- The right skill/playbook
- A prompt template to copy
- Links to relevant documentation
23 Playbooks
Each playbook is a specialized workflow. You don't invoke them directly—/pstack:poteto-mode picks the right one.
Investigation & Diagnosis (6 playbooks)
| Playbook | Use Case |
|---|---|
| investigation | Read-only questions ("How does X work?", "Why was Y built this way?") |
| bug fix | Reproduce → root cause → fix → verify |
| perf | Trace measured slowness and improve against baseline |
| hillclimb | Sustained improvement of one metric (hypothesis → measure → commit per win) |
| runtime forensics | Diagnose live symptoms (leak, CPU spin, glitch) from instrumentation |
| trace forensics | Diagnose captured artifacts (cpuprofile, trace, heap snapshot) |
Development (4 playbooks)
| Playbook | Use Case |
|---|---|
| feature | New/changed behavior, built from named data shape |
| refactoring | Behavior-preserving structural change |
| prototype | Throwaway sketch to make design decisions cheaply |
| visual parity | Pixel-exact UI equivalence between implementations |
Skills & Evaluation (2 playbooks)
| Playbook | Use Case |
|---|---|
| authoring a skill | Writing/editing a SKILL.md file |
| eval | Test how a skill or prompt change affects agent behavior (blinded) |
PR & Shipping (3 playbooks)
| Playbook | Use Case |
|---|---|
| babysit | Drive PR to merge-ready (conflicts, review threads, CI) |
| shipping | Independently verify green stack, then land bottom-up |
| opening a pr | Create PR from small ordered commits with conventional title |
Autonomous Execution (5 playbooks)
| Playbook | Use Case |
|---|---|
| autonomous run | Drive long task to completion without stopping |
| orchestrate | Multi-day project: many stacked PRs, fleets of subagents |
| autopilot-full | Run independent PRs to merged with one owner per PR |
| autopilot-stack | Build and verify one linear stack for operator to review |
Session Management (3 playbooks)
| Playbook | Use Case |
|---|---|
| session pickup | Resume or take over prior agent's in-flight work |
| pause safely | Suspend in-flight work cleanly for later resumption |
| multi-phase plan | Work spanning phases or stacked PRs |
| worktree cleanup | Reclaim disk by pruning merged/abandoned worktrees |
24 Design Principles
When an agent makes a decision, it names which principle guided that choice.
Core Principles (10)
| Principle | When to Apply | Key Idea |
|---|---|---|
| Laziness Protocol | Refactoring, abstractions | Bias to deletion. Smallest change that solves the problem. |
| Foundational Thinking | Before writing logic | Core types and data structures first. |
| Redesign from First Principles | Integrating new requirement | Redesign as if foundational from day one. |
| Attack the Premise | Two fixes share one premise | Test the premise directly. |
| Subtract Before You Add | Sequencing additions | Remove dead weight first. |
| Minimize Reader Load | Hard-to-trace code | Count layers, collapse wrappers, shrink mutable scope. |
| Outcome-Oriented Execution | Rewrites, migrations | Converge on target, don't preserve throwaway states. |
| Experience First | UX tradeoffs | User delight over implementation convenience. |
| Exhaust the Design Space | Novel decisions | Build 2-3 competing prototypes before committing. |
| Build the Lever | Non-trivial work | Build the tool (codemod, script), not by hand. |
Architecture Principles (6)
| Principle | When to Apply | Key Idea |
|---|---|---|
| Model the Domain | Stateful logic, many branches | Encode domain in structure (state machine, typed model). |
| Boundary Discipline | Validation, error handling | Guards at boundaries, trust internal types. |
| Type System Discipline | Designing types | Make illegal states unrepresentable. |
| Make Operations Idempotent | Commands, lifecycle steps | Converge to same end state. |
| Migrate Callers Then Delete | New API while old exists | Migrate and delete in one wave. |
| Separate Before Serializing | Concurrent writes | Eliminate sharing first. |
Verification Principles (5)
| Principle | When to Apply | Key Idea |
|---|---|---|
| Prove It Works | Before declaring done | Verify against real artifact, not proxy. |
| Fix Root Causes | Debugging | Trace to first wrong state, fix there. |
| Sequence Verifiable Units | Multi-step work | Small units, verify each before next. |
| Test Behavior, Not Implementation | Writing tests | Assert what users observe. |
| Explain the Number | Acting on measurements | Find what limits it, rule out false signal. |
Delegation Principles (2)
| Principle | When to Apply | Key Idea |
|---|---|---|
| Guard the Context Window | Context fills up | Route bulk to subagents, keep summaries in main. |
| Never Block on the Human | Reversible work | Proceed, present result, let human course-correct. |
Meta Principles (1)
| Principle | When to Apply | Key Idea |
|---|---|---|
| Encode Lessons in Structure | Repeated mistakes | Build tools/checks to prevent recurrence. |
Using Principles
During a task, mention a principle to redirect:
Apply Laziness Protocol. This abstraction is unnecessary.
To learn more, invoke the principle as a skill:
/pstack:principle-laziness-protocol
Multi-Model Architecture
pstack splits work by model strength.
Default Model Strategy (Cursor)
| Role | Model | Reasoning |
|---|---|---|
| Coding (feature, refactoring, bug-fix) | Grok 4.7 xhigh-fast | Fast, good at code generation |
| Judgment (hardest tasks, prose) | Opus 5.5 xhigh | Best reasoning, writing quality |
| Panels (arena, architect) | Opus + Grok | Multi-model diversity |
Claude Code Limitations
Claude Code only supports Claude family directly:
- opus
- sonnet (current session model)
- haiku
- inherit-parent (use session model)
For Grok/GPT, use CLI wrappers like /codex.
Configuring Models
/pstack:setup-pstack
Budget options:
unlimited(max reasoning) — Highest cost, best for critical taskslarge(xhigh reasoning) — Default, balancedmedium(high reasoning) — Cost-conscioussmall(medium reasoning) — Simple tasks
Per-role customization:
# ~/.claude/rules/pstack-models.md
# budget: large (xhigh)
feature, refactoring: sonnet high
bug-fix: opus high
judgment and prose: opus high
arena runners: opus high, sonnet high
Practical Examples
Example 1: Fix a Bug
Task:
/pstack:poteto-mode Export writes duplicate rows when a retry lands mid-run. Reproduce first, then fix and verify.
What pstack does:
- Selects Bug fix playbook
- Reproduces bug locally (runs the actual app)
- Traces to root cause (not just symptoms)
- Applies Attack the Premise principle
- Implements minimal fix (Laziness Protocol)
- Verifies on real app (Prove It Works)
- Writes tests
- Opens PR with evidence
Result: Root cause fixed, not just patched. Future retries won't have the same issue.
Example 2: Design a Feature
Task:
/pstack:poteto-mode Add user authentication. Compare JWT, OAuth, and session-based approaches before implementing.
What pstack does:
- Calls
/pstack:architectautomatically - Generates 3 design proposals in parallel
- Compares trade-offs (security, scalability, complexity)
- Asks you to choose (AskUserQuestion)
- Implements chosen design
- Creates verification skill to test auth flow
- Opens PR
Principle applied: Exhaust the Design Space (compare before committing)
Example 3: Performance Optimization
Task:
/pstack:poteto-mode Page load is 3 seconds. Improve to under 1 second. Measure with Lighthouse.
What pstack does:
- Selects Hillclimb playbook
- Measures baseline (3s)
- Profiles to find bottleneck
- Hypothesizes improvement
- Implements one change
- Measures again (Explain the Number principle)
- Commits if faster, reverts if not
- Repeats until target (< 1s) reached
- Opens PR with before/after metrics
Result: Evidence-based optimization, not guesswork.
Example 4: Overnight Autonomous Run
Task:
/pstack:poteto-mode I'm going to bed. Merge the entire stack (PRs #123, #124, #125) by morning. Retry if CI flakes.
What pstack does:
- Selects Autonomous run + Shipping playbooks
- Independently verifies each PR
- Runs CI, retries on flakes
- Merges bottom-up (verified PRs only)
- Records decisions (Show Me Your Work skill)
- Reports results in the morning
Principle applied: Never Block on the Human (autonomous decisions with audit log)
Advanced Usage
Parallel Execution (Swarm)
Run multiple independent tasks simultaneously:
/pstack:swarm Test these components in parallel:
- Login page
- Dashboard
- Settings
- Profile
Each component gets its own subagent. Results collected when all finish.
Design Bakeoff (Arena)
Compete multiple implementations, choose the best:
/pstack:arena Implement this search feature 3 different ways. Pick the fastest.
Generates 3 implementations in parallel, benchmarks, selects winner.
Adversarial Review (Interrogate)
Multi-model critical review:
/pstack:interrogate Review this PR for security and performance issues.
Multiple models (Opus + Sonnet) review independently, then cross-judge.
Custom Playbooks
Create project-specific workflows (advanced):
- Create
SKILL.mdin.claude/skills/ - Follow pstack skill format
- Invoke with
/pstack:your-skill-name
Troubleshooting
Q: Skill not recognized
Symptom:
Unknown skill: pstack:poteto-mode
Fix:
claude plugin list # Check if enabled
claude plugin enable pstack@cursor-plugins # Enable if needed
Q: Which skill should I use?
Fix:
/pstack:poteto-help [your question]
Example:
/pstack:poteto-help How do I review this code?
Q: Cursor features don't work in Claude Code
This is expected. Claude Code version skips:
- Cursor Automations
- Bugbot
- Cursor cloud agents
You'll see:
Skipped in Claude Code: [step]. [reason].
Q: Agent ignores principles
Fix: Explicitly invoke the principle first:
/pstack:principle-laziness-protocol
Then run your task. The agent will have the principle fresh in context.
Q: How to change model settings?
Fix:
/pstack:setup-pstack
Re-run to update ~/.claude/rules/pstack-models.md.
Key Takeaways
- Start simple: Just use
/pstack:poteto-mode [task] - Specify goals clearly: "Reproduce first, then fix" is better than "fix the bug"
- Trust the workflow: Don't micromanage—let playbooks run
- Use principles to steer: "Apply Laziness Protocol" redirects mid-task
- Verify everything: pstack won't ship without proof
The golden rule: "If you want to go fast, go deep first."
References
Official Resources
- GitHub Repository: cursor/plugins/pstack
- Author: Lauren Tan (@poteto) — React Core Team, Cursor
- License: MIT
Community Resources
- Japanese Guide (by @uehaj): pstack構造メモ — Technical deep dive into pstack's architecture and skill composition
- YC Launch: Herdr — Agent multiplexer — Discussion of parallel agent execution patterns that inspired pstack workflows
Related Tools
- Claude Code: Anthropic's official CLI
- Cursor: AI-first code editor
- Agent Multiplexers: Herdr, Orca, cmux — Tools for managing multiple AI agents
Further Reading
- Agent Plugins Standard — Cross-agent plugin specification
- Conventional Commits — Commit message format used in pstack's "opening a pr" playbook
- React Compiler — Lauren Tan's work on the React Core Team
About This Guide
This comprehensive guide was created to help developers adopt pstack's rigorous engineering workflows with AI coding agents. Whether you're using Claude Code, Cursor, or other AI assistants, pstack provides the structure needed to ship production-quality code with confidence.
Questions or feedback? Find me on X/Twitter or open an issue on the pstack repository.
Last updated: October 24, 2026