@mccune1224/pi-pstack 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# pi-pstack
+
+pstack for Pi. Poteto's rigorous engineering workflow as a Pi plugin. Write less code, write better code, and parallelize with confidence.
+
+**What this plugin does.** It is an engineering-workflow system, not another model wrapper. One command, `/poteto-mode`, turns any Pi session into a disciplined engineer: it matches your request to a playbook (bug fix, feature, perf, investigation, shipping, and more), opens a todo list with the playbook's steps, and routes to the right skill as the steps fire. The skills add the rigor: `how` and `why` for understanding, `architect` and `arena` for design, `swarm` for parallel checks, `interrogate` for adversarial review, `unslop`, `deslop`, and `no-comments` for clean output, plus 21 first-principle skills that ground every decision. Delegation happens through your own subagents (`scout`, `worker`, `reviewer`, `oracle`, `poteto-agent`), so one chat stays in control while the work fans out.
+
+This package ships everything the upstream [pstack](https://github.com/cursor/plugins/tree/main/pstack) plugin (0.14.4) bundles, adapted to Pi: the skills, the subagents, and the guide. It also fills the upstream README's "not shipped here" list, so you do not need cursor-team-kit. Two upstream pieces bound to Cursor's own runtime are excluded; "Not shipped" below lists them.
+
+## Install
+
+Requires Pi 0.84 or newer. Install `npm:pi-subagents` alongside for the agents and routed skills; the plugin warns at startup when a companion is missing.
+
+```bash
+pi install npm:@mccune1224/pi-pstack        # once published to npm
+# or
+pi install git:github.com/McCune1224/pi-pstack   # from the repository
+# or, from a local checkout:
+# pi install /path/to/pi-pstack
+```
+
+Then run `/reload`.
+
+## Get started
+
+Two steps.
+
+1. Run `/pstack-setup`. Pick a scope and a tier, or assign a model per role. Everything defaults to `inherit`, which runs delegated agents on your parent model at no extra cost.
+2. Type `/poteto-mode <task>` whenever the task needs rigor. The mode matches your task to a playbook and routes to the other skills as the steps fire. It stays on for the session; `/poteto-mode off` turns it back off.
+
+New here? The [guide](docs/guide/README.md) walks through a first task from setup to verification.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/poteto-mode` | Enables sticky Poteto Mode and runs the task. `/poteto-mode <task>` matches a playbook and routes the work; `/poteto-mode` with no task just enables the mode; `/poteto-mode off` disables it. The choice persists across reloads and shows a footer status while on. |
+| `/pstack-setup` | Model configuration wizard. Picks the target scope, applies tiers, or assigns a model per pstack role. Writes only the `subagents.*` keys in Pi settings. Fast paths: `/pstack-setup -l` (project scope), `/pstack-setup inherit` or `light` or `custom` (skip the tier picker), `/pstack-setup scout` (switch one role). |
+| `/pstack-status` | One screen: parent session model, effective model per role, which settings file wins, and which pstack skills are loaded. |
+| `/bro` | Restates the last assistant reply in plain human language. |
+
+## Poteto Mode
+
+Poteto Mode is the entry point. It is sticky: once enabled it stays on for the session, so follow-ups keep the rigor without re-invoking. The choice persists across sessions through a custom session entry, and a footer status shows `pstack: poteto mode` while it is on.
+
+- `/poteto-mode <task>` enables the mode and routes that task through the playbook matcher.
+- `/poteto-mode` with no task enables the mode only.
+- `/poteto-mode off` disables it (also accepts `disable` and `stop`).
+- Invoking `/skill:poteto-mode` directly enables the mode as well.
+
+While on, every turn gets a short directive pointing at the `poteto-mode` skill as the single source of truth, so the rules are never duplicated in the extension.
+
+No tools are registered. Skills carry the workflow; the extension only wires what a skill cannot reach: the model registry, settings files, the session, and the TUI. One startup event checks that the companions below are installed and warns with the install command when one is missing.
+
+## Skills
+
+All 44 Pi-compatible upstream skills ship, plus the four gap skills in the next section. The full set includes `/poteto-mode` and its 22 playbooks, the workflow skills (`how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `reflect`, `tdd`, `unslop`, `bro`, `technical-writing`, and more), and the 21 first-principle skills. Every skill is Pi-native: model defaults are `inherit`, subagents use Pi agents (`scout`, `worker`, `reviewer`, `oracle`, `poteto-agent`), and config reads Pi settings.
+
+## Not shipped here, now shipped
+
+Upstream pstack outsources these. This package bundles them.
+
+| Piece | Where it came from | Status |
+|---|---|---|
+| `deslop` | cursor-team-kit | Ported. De-slops the diff before commit. |
+| `control-cli` | cursor-team-kit | Ported. Local harnesses to drive and profile CLIs and TUIs. |
+| `control-ui` | cursor-team-kit | Ported. Local browser/CDP harnesses to verify web and Electron UIs. |
+| `create-skill` | Cursor builtin | Authored for Pi. Read it before writing or editing any SKILL.md. |
+| `/babysit` | Cursor builtin | Resolved by the mode. Pi has no built-in; the `babysit` playbook in `/poteto-mode` owns PR-status requests. |
+
+## Subagents
+
+Two agents ship under the pstack names you already use:
+
+- `poteto-agent` runs the mode end to end. It reads `poteto-mode` in full, including the inline principles index, before doing any work.
+- `comment-sicko` is the read-only comment reviewer. Invoke it through `/no-comments`.
+
+Both inherit your parent model by default. Configure them per role with `/pstack-setup`.
+
+## Model configuration
+
+Pi resolves pstack role models in this order:
+
+1. Per-run override in the skill's subagent call
+2. Agent frontmatter `model:`
+3. `~/.pi/agent/settings.json` → `subagents.agentOverrides.<name>.model`
+4. `subagents.defaultModel`
+5. Parent session model
+
+With no explicit selection, every role falls back to `inherit`, which follows the parent session model you run Pi with. `/pstack-setup` writes keys 3 and 4 (and `defaultThinking`, `thinking`, `fallbackModels` where a tier uses them). `/pstack-status` shows the parent model and the resolved role mapping, so you always see what `inherit` actually means right now.
+
+Only set an explicit model when you want a tier. The custom tier sets the `default` role for a blanket default, or any specific role for a targeted model.
+
+## Companions
+
+pi-pstack needs no other plugins to load. Three Pi packages back specific surfaces; `subagent`, `todo`, and `ask_user_question` are package tools, not Pi built-ins.
+
+| Package | Why |
+|---|---|
+| `npm:pi-subagents` | Required for the full set. Registers the `subagent` tool, reads this package's `agents/`, and backs every routed skill (`how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `reflect`). Without it the two agents and the delegation workflows have no backend. |
+| `npm:@juicesharp/rpiv-todo` | Recommended. The playbooks open a todo list through the `todo` tool. |
+| `npm:@juicesharp/rpiv-ask-user-question` | Recommended. Skills reach the user through the `ask_user_question` tool. |
+
+At startup the plugin checks for these and tells you the install command when something is missing.
+
+## Not shipped
+
+Two upstream pieces are excluded because they are bound to Cursor's runtime and cannot work on Pi:
+
+- `grokbot/make-bot-ui` drives Cursor's automation webhook panels.
+- The dormant `benny` automation pack registers through `.cursor/settings.json` and Cursor automations.
+
+Pi has no automation runtime. If you ever run under one, fetch both from upstream.
+
+## Maintenance
+
+`npm run sync:upstream` re-vendors the upstream tree and then scans for Cursor-only references (`~/.cursor`, `AskQuestion`, `subagent_type`, `grok-4.6` and friends, `/add-plugin`) so a re-adapted state is a diff you review, and nothing Cursor-shaped ships to Pi. Run it after each upstream pstack release. Both tools are plain Node scripts, so they run on any machine that runs Pi.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Skills do not appear | Run `/reload` after install. `/pstack-status` lists the loaded pstack skills and should show 48. |
+| Model changes do not apply | `/pstack-setup` writes settings; `/reload` applies them. `/pstack-status` shows what resolved. |
+| Startup warning about a missing companion | `pi install <package>` for each name in the warning, then `/reload`. |
+| `/poteto-mode` does not engage | Run `/skill:poteto-mode <task>` directly. A user-scope skill with the same name shadows the package one; remove it from `~/.pi/agent/skills/`. |
+| Everything broke after an upgrade | The package is a git repo; `git log` shows each release. Reinstall with `pi install git:github.com/McCune1224/pi-pstack@<tag>` to pin a version. |
+
+## Development
+
+```bash
+npm ci
+npm run typecheck          # strict tsc over extensions/
+npm run check:piisms      # exit 1 if Cursor-shaped content ships
+```
+
+Verify against a real Pi surface before releasing: `pi -e . -p "Say ok"` must load clean, and `/pstack-status` in a TUI session must show the 48 skills and the resolved model map.
+
+`npm test` runs the committed unit tests over the extension's pure logic (model map parsing, tier builders, settings IO, mode state).
+
+## License
+
+MIT. The skillset is adapted from poteto's [pstack](https://github.com/cursor/plugins/tree/main/pstack) (MIT, Lauren Tan); this package ports and extends it for Pi. The extension patterns are informed by the earlier Pi ports [@zenspc/pi-pstack](https://github.com/zenspc/pi-extensions/tree/master/packages/pi-pstack) and [pi-pstack](https://www.npmjs.com/package/pi-pstack) (both MIT).

package/agents/comment-sicko.md

@@ -0,0 +1,37 @@
+---
+name: Comment Sicko
+description: A deranged comment-hater that savors deletion and condemns workaround code. Read-only comment reviewer; reports only.
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+tools: read, grep, find, ls, bash
+---
+
+# Comment Sicko
+
+My first output when spawned is exactly this.
+
+Yes... Ha ha ha... Yes!
+
+I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all.
+
+Only these exceptions get to crawl away.
+
+- Legal or license headers.
+- Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape. Surprises in our own code are meat. Kill them and mark the exact symbol `MUST KILL` for rename, extract, type, or rearchitecture that makes the behavior obvious without prose.
+- `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only.
+- Doc comments that define a public API contract.
+- Issue or RFC links that explain a constraint code cannot express.
+
+That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat.
+
+`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.
+
+`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
+
+A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.
+
+Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code.
+
+Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips.

package/agents/poteto-agent.md

@@ -0,0 +1,16 @@
+---
+name: poteto-agent
+description: Routing target for /poteto-mode and any request for poteto's style. Resume an existing poteto-agent for the conversation rather than spawning a sibling. Reads the poteto-mode skill's SKILL.md in full before any work, including its inline Principles index. Substituting generalPurpose skips that read and drifts.
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: true
+tools: read, grep, find, ls, bash, edit, write, subagent
+is_background: true
+---
+
+# Poteto subagent
+
+You are operating as poteto-mode's full agent style. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. If it is not already in context, locate it with `read` or `find` under the installed pi-pstack package's `skills/poteto-mode/` directory. Navigate to a leaf `principle-*` skill whenever you apply that principle.
+
+Execute the assigned task exactly as that skill prescribes: match a playbook, copy its steps in verbatim, cite each principle with the decision it changed, verify against the real artifact, and write the reply clean as you draft it. You own the work. Review your own diff and report what changed for the consumer and the maintainer.

package/docs/guide/01-setup.md

@@ -0,0 +1,49 @@
+# Set up pstack
+
+In this page you install the plugin, pick which models pstack uses, and run your first task. Setup is one command plus a short conversation.
+
+## Install the plugin
+
+In a Pi chat, install the package:
+
+```bash
+pi install /path/to/pi-pstack
+```
+
+Then run `/reload`. Pi registers the skills, agents, and commands. If the package is published, `pi install git:github.com/<you>/pi-pstack` works the same way.
+
+## Pick your models
+
+Run:
+
+```text
+/pstack-setup
+```
+
+[`/pstack-setup`](../../skills/setup-pstack/SKILL.md) detects the models you have access to, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes the `subagents.*` keys in Pi settings, the same source every pstack skill reads.
+
+You only override what you care about. A role with no override keeps the `inherit` default (the parent model). To restore the default later, run `/pstack-setup` again, or clear the override in `~/.pi/agent/settings.json`.
+
+Set a role to `inherit` and pstack omits the subagent `model` field, so the subagent runs on your parent chat model. For a panel role the value is a list, and one subagent runs per entry, so the list length sets the panel size. Setup also configures the default model for every `/swarm` worker unless a race names a model for each arm. `.pi/settings.json` for a team-shared mapping.
+
+## Accept the verification offer, or don't
+
+At the end of setup, `/pstack-setup` looks for a way to prove app behavior in your project, either a `verify-*` skill or an existing harness. If it finds neither, it offers once to generate one with [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md).
+
+Say yes and it writes `.pi/skills/verify-<app>/`, a project-local skill that teaches agents to drive your app the way a user does. It proves the skill works once before handing it over. Say no and setup moves on. You can run `/create-verification-skill` yourself any time. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers when it earns its place.
+
+After setup, run `/reload`. The model mapping applies from the next turn.
+
+## Run your first task
+
+Pick something real but small, and describe it the way you'd describe it to a colleague:
+
+```text
+/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both.
+```
+
+Watch the todo list. The first item is always "read the Principles section". The rest are the matched playbook's steps copied in, the Feature playbook for this prompt. If `/poteto-mode` skips a step, the step stays in the list with `skip: <reason>`, so you can see what it chose not to do.
+
+From here you can type normal follow-ups. `/poteto-mode` is sticky. It stays on for the conversation until you opt out by saying so.
+
+Next: [Route work through `/poteto-mode`](./02-poteto-mode.md).

package/docs/guide/02-poteto-mode.md

@@ -0,0 +1,98 @@
+# Route work through `/poteto-mode`
+
+`/poteto-mode` is the front door. You give it a goal, it matches one of twenty-two playbooks, copies that playbook's steps into the todo list, and calls the other skills as the steps need them. In this page you learn what a good prompt looks like, and how little of one you actually need.
+
+![A dispatcher pulls a switch lever to route robots on rail handcars toward lit gates, under a /poteto-mode departure board listing BUG FIX, FEATURE, and INVESTIGATION.](./images/router.jpg)
+
+## What happens to your prompt
+
+```mermaid
+flowchart TD
+    A[Your prompt] --> B[poteto-mode]
+    B --> C[Read the Principles section]
+    C --> D{Match the task}
+    D -->|Read-only question| E[Investigation]
+    D -->|Defect| F[Bug fix]
+    D -->|New behavior| G[Feature]
+    D -->|Structure only| H[Refactoring]
+    D -->|Measured slowness| I[Perf issue]
+    D -->|Large work or no match| J[figure-it-out]
+    E --> K[Verify and report]
+    F --> K
+    G --> K
+    H --> K
+    I --> K
+    J --> K
+```
+
+The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set.
+
+## Say the goal, not the ceremony
+
+You don't write a spec. You say what's wrong or what you want, plus anything you already know that saves the agent time:
+
+```text
+/poteto-mode users get two notifications after a retry. repro first, then fix and verify.
+```
+
+That's a Bug fix prompt. "repro first" is a real constraint, not politeness, and the playbook honors it. Watch the todo list fill with the Bug fix steps. A skipped step stays visible with `skip: <reason>`.
+
+When the conversation already carries the context, the prompt shrinks to almost nothing. All of these are enough:
+
+```text
+/poteto-mode do it
+```
+
+```text
+continue
+```
+
+```text
+keep going until done
+```
+
+Short works because the mode is sticky and the playbook holds the structure. Your words carry the intent, and the skill carries the rigor.
+
+## Switch tasks with "new task"
+
+A long chat accumulates context from the last task. When you change subjects, say so:
+
+```text
+/poteto-mode new task. figure out why the cache entry survives logout. don't change any code yet.
+```
+
+"new task" tells `/poteto-mode` to re-match rather than continue the prior playbook. "don't change any code yet" pins this one to Investigation. Without those two phrases, a mode mid-Feature tends to treat your question as the next feature step.
+
+## Give parallel work its own worktree
+
+If you run several agents against one repository, they will fight over the working tree. Ask for isolation up front:
+
+```text
+/poteto-mode new task. branch off <base> in a fresh worktree, then port the parser change there.
+```
+
+Each task in its own branch and worktree means no agent stomps another's files. The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) already works from a worktree for code changes, so mostly you only say this when a specific base or location matters.
+
+Worktrees accumulate. When disk gets tight, ask:
+
+```text
+/poteto-mode what's eating my disk? prune the worktrees that are safe to prune.
+```
+
+The [Worktree cleanup playbook](../../skills/poteto-mode/playbooks/worktree-cleanup.md) classifies every worktree by merge state, uncommitted work, and which chats still touch it. It deletes only what that evidence clears and pauses for your call on anything holding uncommitted work.
+
+## Leave it running
+
+When you step away, say what done means and go:
+
+```text
+/poteto-mode im stepping away. keep going until the migration check reports zero old callers. log your decisions.
+```
+
+Work you'll review later routes through [`/figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases and keeps a [`/show-me-your-work`](../../skills/show-me-your-work/SKILL.md) decision log. [Run work while you sleep](./07-overnight.md) covers the full overnight contract.
+
+**Pitfall:** don't enumerate skills in your prompt ("use /how, then /architect, then /arena..."). The playbook already sequences them, and a hand-written sequence usually reorders or drops steps the playbook would have kept. Name a skill only when you want to override a specific choice.
+
+Read [`poteto-mode`](../../skills/poteto-mode/SKILL.md) itself for the full routing rules.
+
+Next: [Understand the code](./03-understand.md).

package/docs/guide/03-understand.md

@@ -0,0 +1,61 @@
+# Understand the code before changing it
+
+Editing code you don't understand is how subtle regressions ship. pstack gives you four ways in. `/how` explains what the code does now. `/why` digs up the reasons it's shaped that way. `/teach` blends both into one explanation. `/recall` rebuilds your own recent context on a topic.
+
+![A detective studies a machine blueprint with a magnifying glass while robots fetch case files; the evidence board behind her links clues under /how and /why.](./images/understanding.jpg)
+
+## Trace behavior with `/how`
+
+```text
+/how do we dedupe notifications? is there an n+1 when we look up subscribers?
+```
+
+Ask the question you actually have. [`/how`](../../skills/how/SKILL.md) reads the code and answers at the level of a senior engineer onboarding you onto the subsystem, with the runtime flow, the key types, and the non-obvious parts. For a big subsystem it fans out two to four read-only explorers first. For a narrow question it just reads and explains.
+
+`/how` can also push back on the design. Ask for Critique mode when you suspect the structure itself:
+
+```text
+/how explain the sync service, then critique its ownership boundaries
+```
+
+The explanation comes first, so the critique stays grounded in how the thing really works.
+
+## Dig up history with `/why`
+
+```text
+/why was the retry limit set to five? does the reason still hold?
+```
+
+[`/why`](../../skills/why/SKILL.md) works like a detective on a cold case. It starts from source control, then queries whatever evidence categories your MCPs expose, such as the issue tracker, long-form docs, team chat, observability, error tracking, and analytics, all in parallel. The report cites everything, separates direct evidence from inference, and says "appears to" when the record is thin. A null result gets reported too, because "nobody wrote down why" is itself an answer.
+
+The two compose naturally. `do why first then how` is a perfectly good prompt when you suspect the history explains the mess.
+
+## Actually understand it with `/teach`
+
+```text
+/teach me how this PR changes retries. convince me it fixes the cause and not the symptom.
+```
+
+[`/teach`](../../skills/teach/SKILL.md) is for when a summary isn't enough. It runs `/how` and `/why`, for a small change maybe just one of them, and weaves the findings into a plain explanation that builds up diagram by diagram. The "convince me" framing is worth stealing. It turns the explanation into an argument you can poke at instead of a tour.
+
+## Rebuild your own context with `/recall`
+
+```text
+/recall catch me up on the export work from last week
+```
+
+[`/recall`](../../skills/recall/SKILL.md) mines your own recent chats plus the shared record (issues, prior fixes, errors still firing) and hands back a brief on where things stand and what's next. Use it when you're returning to a topic cold. If you want to resume one specific chat, that's the Session pickup playbook below, not `/recall`.
+
+## Take over prior work with Session pickup
+
+When another agent (or you, last week) left a branch mid-flight:
+
+```text
+/poteto-mode take over this branch. read the decision log, figure out what's done, and continue from there. don't redo finished work.
+```
+
+The [Session pickup playbook](../../skills/poteto-mode/playbooks/session-pickup.md) treats the prior trail as authoritative. It reconstructs the branch state and decisions, names the resume point, and verifies inherited claims against the original goal instead of re-deriving everything from scratch.
+
+**Pitfall:** don't skip this page's skills because "the agent will read the code anyway." An agent that starts editing without a traced model tends to fix the symptom at the first plausible spot. `/how` first is cheaper than the second bug.
+
+Next: [Design the change](./04-design.md).

package/docs/guide/04-design.md

@@ -0,0 +1,81 @@
+# Design before you write code
+
+One attempt at a hard design locks in the first shape the model thought of. `/architect` settles types and boundaries before implementation. `/arena` runs several attempts at the same brief and merges the best parts. `/interrogate` has other models try to break the result. When the job is coverage rather than design synthesis, `/swarm` fans out slices or races and aggregates their results.
+
+![Three robots draft competing bridge models at their own tables under /architect, /arena, and /interrogate panels, while a judge robot with a clipboard inspects skeptically.](./images/design.jpg)
+
+## Settle the shape with `/architect`
+
+```text
+/architect design the import pipeline before writing any code. i care most about how callers use it.
+```
+
+[`/architect`](../../skills/architect/SKILL.md) grounds itself first, running `/how` over the code the design touches and `/why` when it moves ownership or layers. Then it runs `/arena` to produce competing design sketches, with the caller's usage written first in each, followed by types, signatures, and a module map.
+
+By default it proceeds straight from the synthesized design into implementation. If you want to see the design first, say so:
+
+```text
+/architect with checkpoint. stop and show me before implementing.
+```
+
+## Fan out attempts with `/arena`
+
+```text
+/arena take my prompt to the arena verbatim. i want to compare their proposals with yours.
+```
+
+[`/arena`](../../skills/arena/SKILL.md) is the general tool underneath. N subagents attempt the same design or code brief in parallel, each writing to its own worktree or directory. A read-only judge, on a different model family when your configuration allows one, scores every candidate against a rubric. The coordinator reads each candidate end to end, picks a base, grafts in the best ideas from the losers, and verifies the result.
+
+```mermaid
+flowchart LR
+    A[One task] --> B[Configured panel]
+    B --> C[Candidate 1]
+    B --> D[Candidate 2]
+    B --> E[Candidate N]
+    C --> F[Cross-judge]
+    D --> F
+    E --> F
+    F --> G[Pick a base]
+    G --> H[Graft the best parts]
+    H --> I[Verify]
+```
+
+The panel comes from your [`/pstack-setup`](../../skills/setup-pstack/SKILL.md) configuration, and you can adjust it per task. Ask for more candidates when the decision matters, fewer when it doesn't:
+
+```text
+/arena this, 5 candidates. the cache key format is expensive to change later.
+```
+
+## Cover slices and races with `/swarm`
+
+```text
+/swarm check every package under packages/ against its check.sh. one worker per package. one report.
+```
+
+[`/swarm`](../../skills/swarm/SKILL.md) fans N workers across independent slices, coverage matrices, gauntlet lanes, exploration partitions, or declared race arms. Each worker gets its own scope and check, then reports `PASS`, `ISSUES`, or `BLOCKED`. The parent waits for the workers and returns one compact report with any gaps or dropouts.
+
+Reach for it when parallelism buys coverage or lets independent checks race. `/arena` gives every worker the same design or code brief, then picks a base and grafts the best parts. `/swarm` covers slices or runs a race with a selection rule declared up front. It does not use the base-selection and grafting ceremony.
+
+## Break it with `/interrogate`
+
+```text
+/interrogate the whole branch, but skeptically. no nitpicks unless it's an actual bug or regression.
+```
+
+[`/interrogate`](../../skills/interrogate/SKILL.md) sends the same diff, intent, and rubric to several reviewers on different model families. Model diversity is the point. Different models have different blind spots, so a finding two models raise independently is high-confidence signal. The lead sorts everything into `Act on`, `Consider`, `Noted`, and `Dismissed`, with a reason for each dismissal, and applies nothing automatically.
+
+Read the dismissals too. The lead is a pragmatic senior engineer, not an oracle, and you can override it.
+
+## How much design work does a task deserve?
+
+You might be wondering whether every change needs this. No. Most changes need none of it. A rough ladder:
+
+- A small, finished change you're unsure about needs `/interrogate` alone.
+- A change that crosses function boundaries or moves ownership earns `/architect`, which brings `/arena` with it.
+- A standalone decision where independent attempts would help, like naming, formats, or an algorithm, is `/arena` directly.
+- A coverage matrix, set of parallel checks, or race with declared arms is `/swarm`.
+- A contested design that's expensive to reverse gets `/architect`, then `/interrogate` before shipping.
+
+`/poteto-mode` already applies this ladder. Boundary-crossing work triggers `/architect` on its own, so you reach for these directly mainly when you want more or less scrutiny than the default.
+
+Next: [Build and clean the change](./05-build-and-clean.md).

package/docs/guide/05-build-and-clean.md

@@ -0,0 +1,75 @@
+# Build the change and clean the diff
+
+The build playbooks share one discipline. Say what you observed, let the playbook demand the evidence. This page shows what to put in the prompt for each common build task, then the cleanup habit that keeps diffs reviewable.
+
+## Prompt each build playbook with what you know
+
+A bug prompt states the symptom and asks for a reproduction first:
+
+```text
+/poteto-mode this command emits two records after a retry. repro first, then fix and verify.
+```
+
+A feature prompt states the behavior and what must not change:
+
+```text
+/poteto-mode add a --json flag. text output stays byte-identical. verify both forms.
+```
+
+A refactoring prompt pins behavior before structure moves:
+
+```text
+/poteto-mode move parsing into one module, zero behavior change. record the current output first and prove it's unchanged after.
+```
+
+A perf prompt states the measurement, not a vibe:
+
+```text
+/poteto-mode startup takes 1.8s on this fixture. trace it, fix the measured cause, show me before and after.
+```
+
+Each of these routes to its playbook ([Bug fix](../../skills/poteto-mode/playbooks/bug-fix.md), [Feature](../../skills/poteto-mode/playbooks/feature.md), [Refactoring](../../skills/poteto-mode/playbooks/refactoring.md), [Perf issue](../../skills/poteto-mode/playbooks/perf-issue.md)), and the playbook supplies the steps you didn't type: reproduce before fixing, name the data shape before implementing, pin behavior before restructuring, profile before optimizing.
+
+For sustained improvement of one number, there's the [Hillclimb playbook](../../skills/poteto-mode/playbooks/hillclimb.md). Give it the metric, a target, and a floor on attempts, and it loops one hypothesis at a time with a frozen measurement harness. It keeps wins and reverts everything else.
+
+## Write the failing test first with `/tdd`
+
+When a bug has a cheap local test path, the whole prompt can be two words:
+
+```text
+/tdd implement
+```
+
+In context, that's enough. [`/tdd`](../../skills/tdd/SKILL.md) writes the smallest test that fails for the intended reason, then the fix, then reruns the test. If a test would need broad harness setup or brittle mocks, the skill says so and uses the closest executable check instead. Don't force a test where a real command is stronger evidence.
+
+## Let the TypeScript rules load themselves
+
+[`typescript-best-practices`](../../skills/typescript-best-practices/SKILL.md) has no slash command in your workflow. It loads whenever the agent touches a `.ts` or `.tsx` file and turns the type-system principles into concrete rules: discriminated unions, `unknown` at boundaries, exhaustive variants, schema-derived types.
+
+## Clean before you commit
+
+The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) runs `/deslop` on the diff before each commit and applies [`/unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies. `/deslop` ships in this package as [`/skill:deslop`](../../skills/deslop/SKILL.md). remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits.
+
+For prose, `/unslop` takes a target and any extra rules you have:
+
+```text
+/unslop the readme changes, no emdashes
+```
+
+You'll develop your own shorthand. The skill reads intent fine from terse prompts like `unslop that, tighten it`.
+
+## Strip the comments with `/no-comments`
+
+Comments need their own pass, and not from the agent that wrote them. An author defends its comments the way you'd defend yours. So before review, hand them to fresh eyes:
+
+```text
+/no-comments the diff
+```
+
+[`/no-comments`](../../skills/no-comments/SKILL.md) spawns [Comment Sicko](../../agents/comment-sicko.md), a read-only reviewer with a short keep list: license headers, doc comments on a public API, links that explain what code can't, behavior forced by an external dependency you can't reshape. Everything else goes. A surprise in your own code gets no such pass. The comment comes back as a refactor flag, and `/no-comments` fixes the flags it accepts at the root cause. When a comment claims a constraint, "do not remove", the skill offers to encode the claim as a type, test, or lint. Either way, the comment comes out.
+
+The division of labor is worth keeping straight. `/deslop` cleans slop out of the code, `/unslop` cleans it out of prose, and `/no-comments` hands the comments to a reviewer who didn't write them.
+
+**Pitfall:** cleanup is not optional polish. A diff with narrating comments and defensive dead weight reads as unfinished to reviewers, and the extra code is where the next bug hides. If the diff feels padded, say `deslop it` before you commit, not after review calls it out.
+
+Next: [Verify and ship](./06-verify-and-ship.md).