pstack, an Agent Skill Collection: Its Development Principles and How to Use It

To trust AI-generated code, you need to understand the system before implementing and verify the result afterward. pstack is an agent skill collection by poteto. The author says it values the quality of generated code over its quantity, with the goal of getting things done with less code. This article introduces pstack's development principles and how to use it.

How pstack drives development

In pstack, you start a task with /poteto-mode. poteto-mode picks a playbook based on the user's request. A playbook is a procedure prepared for each type of task, such as fixing a bug or adding a feature. The playbook then calls the skills it needs along the way. The official guide recommends telling the agent your goal and how to confirm it is done, rather than spelling out every step.

For example, for a bug fix request, the agent selects the Bug fix playbook. Roughly speaking, the Bug fix playbook instructs the agent to proceed in the following order:

Actually reproduce the bug
Form hypotheses and narrow down the cause using runtime evidence
Design the fix and delegate the implementation
Verify the fix with the operation that originally reproduced the bug

pstack's development principles

pstack collects principles for producing high-quality code, drawn from poteto's experience working with millions of lines of code at Meta, Netflix, and Cursor. pstack helps you write less code, but of higher quality. The principles are defined as skills named principle-*, and skills such as how and architect turn those principles into concrete work procedures. This section introduces the main principles and the skills related to them.

Understand the existing system before implementing

how is a skill that investigates how existing code works and explains its structure and execution flow. Rather than just listing related files, it aims to build an understanding of the system you are about to change.

For a caching bug, for example, it looks into where the data is stored and when it is read. It also traces who holds the value and how a failed result affects the next call. Without this understanding, you might end up adding retry conditionals on the caller side when the real problem is how the cache is managed.

By making investigation a separate step, pstack encourages the agent to understand the cause before making changes, rather than deciding where to fix based only on the first symptom it finds.

Decide the shape of data and boundaries first

Model the Domain is the principle of expressing business rules and state as data structures. One example it gives is representing the possible states as a state machine instead of managing several booleans separately. At the same time, it asks you not to force abstractions and to keep code simple when its shape is already clear.

architect is the skill that turns this principle into a design procedure. It sketches types, function signatures, and module boundaries first, compares several structurally different options, and then moves on to implementation. By default, architect proceeds to implementation once it has synthesized a design. If you want to review the design along the way, explicitly ask for a checkpoint like this:

/architect Review the cache design. Before implementing, stop at a checkpoint and show me the public functions and how state is held.

Keep the change as small as necessary

Laziness Protocol is the principle of consolidating duplicated decisions and choosing the smallest diff that solves the problem. Before adding code, consider whether the existing structure can be simplified.

This does not mean shorter code is always better. For example, adding an abstraction unrelated to a bug fix widens the scope reviewers have to check. Keeping the change to what is necessary makes it easier to follow what caused the problem and which change resolves it.

Prove completion with real behavior

Prove It Works is the principle of checking the actual artifact instead of judging a task complete based only on a successful compile or the agent's own report. It also emphasizes leaving a verification script that can be re-run.

For a bug fix, you retry the operation that originally failed and confirm it now behaves as expected. Beyond passing tests, what matters is whether those tests capture the original bug. A test that would pass even before the fix is not sufficient evidence for it.

Don't leave multi-model feedback to humans

interrogate is a skill that consolidates reviews from multiple models. It does not just collect each model's findings. It sorts them into issues to fix, suggestions to consider, findings to note, and findings to dismiss. It is not a procedure that automatically applies the findings to the code.

The fact that multiple models flagged the same issue is useful input, but it does not prove the finding is correct. In the end, each finding is evaluated against the target code and the requirements.

Getting started with Claude Code

pstack works with either Cursor or Claude Code. This section walks through installing it in Claude Code.

Add the plugin

The official README explains how to install it in Claude Code with the following commands:

/plugin marketplace add cursor/plugins
/plugin install pstack@cursor-plugins

Configure models and reasoning budget

Next, run the following skill for initial setup:

/setup-pstack

setup-pstack is a procedure that detects the available models and lets you choose a model and reasoning budget for each role. When I tried it, it suggested Opus for the roles that require judgment, and for other implementation and investigation work, inheriting the model used in the current session.

The model settings are saved to ~/.claude/rules/pstack-models.md. To change them, run setup-pstack again.

If you get stuck using pstack or aren't sure which skill fits, you can ask the /poteto-help skill. For example, you can ask it for tips on using pstack like this:

Trying it out

Once you're set up, choose poteto-mode from the / menu and enter your request. Playbooks are procedures contained in poteto-mode, and there are no commands like /bug-fix to call them directly. poteto-mode picks the right playbook for your request. The key when using /poteto-mode is not to specify how to fix things, but to state the goal and how to verify it.

For example, my tag list page had a problem where it returned a 500 error, so I made the following request:

/pstack:poteto-mode https://azukiazusa.dev/tags returns a 500 in production. Reproduce it first, find the root cause, then fix it. It doesn't reproduce with curl, only when you open the page directly in a browser. Done means /tags returns a 200 on a local preview build and the tag list is displayed. As evidence, show me the actual responses (status and error logs) before and after the fix. Note that production uses the real repositories with CF_ENV=production, while development uses mocks.

You can see that it loaded the bug-fix playbook and proceeded in order: first confirming the reproduction steps, then gathering evidence to identify the cause, and finally designing and implementing the fix.

The cause was that when a slug was an empty string, key values were duplicated and hydration failed. The server response itself was a 200, and the 500 error page was shown in the browser because of the hydration failure, which is why curl could not reproduce it. You could patch the code as a stopgap, but the real fix is to prevent slugs from becoming empty strings. Following the Fix Root Causes principle, the agent did not jump to a code fix and instead proposed a way to correct the tags whose slug was set to an empty string. It also pointed out a bug in the code that generates tags when an article is created, and laid out a plan to fix the problem at its root.

Finally, following the Prove It Works principle, it checked the responses before and after the fix on the development server and used them as evidence for the fix.

Let's try another playbook. For example, if you want an explanation of a repository's design and code structure, make a request like this:

/pstack:poteto-mode Explain the design and code structure of this repository. I also want to know the design intent and the rules the code is written by. Done means an overview of the design and a diagram of the code structure.

It loaded the investigation playbook and answered the request. The investigation playbook is for answering questions without changing code. Its output is a cited explanation or a recommendation. As shown below, it drew diagrams of the repository structure and of the flow until an article is published, and explained the design intent in prose.

Summary

pstack is a skill collection that shares a way of working through investigation, design, implementation, and verification, and poteto-mode picks a playbook based on the request
pstack emphasizes keeping diffs small and judging completion by checking the actual artifact
Trying a bug fix task shows that it proceeds through investigation and design to find the root cause before implementing the fix
Asking for an explanation of the code selects the investigation playbook, which returns a cited explanation without changing any code