@mccune1224/pi-pstack 0.1.0 → 0.2.0

package/README.md

@@ -1,142 +1,94 @@
 # pi-pstack
 
-pstack for Pi. Poteto's rigorous engineering workflow as a Pi plugin. Write less code, write better code, and parallelize with confidence.
+Poteto's engineering workflow on the Pi Agent Harness. Fifty skills, two agents, and an extension that wires the workflow into the parts of Pi a skill file cannot reach: settings, sessions, compaction, and the context window.
 
-**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.
+pstack is Lauren Tan's plugin for Cursor. Two other Pi ports carry the same name. This one differs in kind, not in degree: it is the port that treats Pi as a harness to build on. The skills are the same rigorous core everywhere. What you do with the rest of the machine is what this package is for.
 
-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.
+## What only this port ships
+
+**A setup wizard that writes Pi's own settings.** `/pstack-setup` asks for a reasoning budget (unlimited, large, medium, small), then maps six roles onto the models your session can reach. It writes the `subagents.*` keys in `settings.json`, the same keys every other Pi tool reads. Nothing private, nothing parallel, hand-editable.
+
+**A context guard with the principle enforced.** While Poteto Mode is on, the extension meters the context window every turn. At 70 percent it tells you to hand long output to files. At 85 it tells you to capture the decision state. At 92 it offers one-key compaction. The HUD below the editor shows the meter live.
+
+**Compaction that keeps the run.** When Poteto Mode compacts, the summary is shaped around what the run needs to survive: the matched playbook and its step, the decision ledger with the principles cited, what was verified and how, file paths, next actions. Pi's default compaction summarizes a chat. This one resumes a job.
+
+**A doctor.** `/pstack-doctor` validates both settings files, flags role typos that would silently do nothing, checks the package agents' frontmatter, counts the vendored playbooks, names missing companion packages, and reports the upstream pin.
+
+**A port you can prove.** Every adaptation from upstream Cursor pstack is declared as data in `scripts/pi-deltas.json`. `npm run verify:sync` classifies all 100+ vendored files and fails on anything unexplained. A rule that stops matching is itself a failure, and the check is mutation-tested: `npm run verify:guards` injects hand edits, deleted rules, and stale baselines to prove the checker catches 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.
+Requires Pi 0.84 or newer. Install [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) alongside it; it registers the `subagent` tool every routed workflow uses, and this package warns at startup when it is absent.
 
 ```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
+pi install npm:@mccune1224/pi-pstack
+# or from the repository
+pi install git:github.com/McCune1224/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.
+1. Run `/pstack-setup`. Pick a scope, a budget, and a tier, or assign models per role. Everything defaults to `inherit`: delegated agents run on your parent model, at no extra cost, with no thinking floor. That is the recommended start.
+2. Run `/poteto-mode <task>` when the task needs rigor. The mode is sticky. Follow-ups keep the playbook discipline until `/poteto-mode off`, and the footer shows the state while it is on.
 
-New here? The [guide](docs/guide/README.md) walks through a first task from setup to verification.
+New here? The [guide](docs/guide/README.md) walks a first task from install to verified ship.
 
 ## 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.
+| `/poteto-mode` | Enable sticky Poteto Mode and optionally run a task. `<task>` matches one of 23 playbooks and copies its steps into a todo list verbatim. `off` disables. Tab completes playbook names. The choice survives a reload. |
+| `/pstack-setup` | Model configuration. Reasoning budget first, then scope, tier, or a single role. Fast paths: `-l`, `inherit`, `light`, `custom`, a budget word like `small`, or a bare role name like `scout`. |
+| `/pstack-status` | Parent session model, resolved model and thinking level per role, the recorded budget, the winning settings file, the loaded skill inventory, and the system-prompt token cost of what the model sees. |
+| `/pstack-doctor` | Install diagnostics: settings validity, unknown roles, agent frontmatter, playbook count, companion tools, upstream pin. |
+| `/bro` | Restates the last reply in plain human language. |
 
-| 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. |
+No tools are registered. Skills carry the workflow; the extension only reaches what skills cannot.
 
-## Subagents
+## How it uses the harness
 
-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 |
+| Pi mechanism | What pstack does with it |
 |---|---|
-| `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. |
+| `subagents.*` settings keys | Role models and thinking levels, user or project scope, shared with the rest of Pi |
+| Session entries | Poteto Mode state, so the sticky mode survives reloads and restarts |
+| `before_agent_start` | A short mode directive that points at the `poteto-mode` skill, never a duplicated rule |
+| Context usage | The guard thresholds and the HUD meter |
+| Compaction events | The poteto summary shape, with fallback to Pi's default on any failure |
+| Widgets and status | The `pstack: poteto mode` footer and the live roles, budget, and context line |
 
-At startup the plugin checks for these and tells you the install command when something is missing.
+Because the model map lives in Pi's own settings, it is not private to this package. The project scope in `.pi/settings.json` wins over the user scope when both exist.
 
-## Not shipped
+## The skills
 
-Two upstream pieces are excluded because they are bound to Cursor's runtime and cannot work on Pi:
+50 ship and load together: 23 workflow skills, 23 first-principle leaves, and 4 Pi-only additions (`control-cli`, `control-ui`, `create-skill`, `deslop`). Upstream disables model invocation for most of them, so Pi filters 45 out of the system prompt and the mode skill reaches them by name as steps fire; the 5 Pi offers on its own judgment cost about 400 prompt tokens. `/pstack-status` prints the live number for your install.
 
-- `grokbot/make-bot-ui` drives Cursor's automation webhook panels.
-- The dormant `benny` automation pack registers through `.cursor/settings.json` and Cursor automations.
+Two agents ship under the upstream names: `poteto-agent` runs the mode end to end, `comment-sicko` reviews comments through `/no-comments`. Both inherit your parent model until `/pstack-setup` says otherwise.
 
-Pi has no automation runtime. If you ever run under one, fetch both from upstream.
+The [guide](docs/guide/README.md) has a chapter per workflow stage, and [compare.md](docs/compare.md) puts this port next to upstream and the other Pi port with reproducible numbers.
 
-## Maintenance
+## Keeping the port current
 
-`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
+```bash
+git clone --depth 400 https://github.com/cursor/plugins.git /tmp/upstream-plugins
+npm run sync:upstream      # vendor upstream at the pinned ref and apply the declared deltas
+npm run verify:sync        # classify every file, fail on anything unexplained
+npm run check:piisms       # fail if Cursor-only content would ship
+npm run verify:guards      # mutation-test the checker itself
+```
 
-| 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. |
+The pin, the two commits it covers, and what each upstream change became here are written up in [compare.md](docs/compare.md).
 
 ## Development
 
 ```bash
-npm ci
-npm run typecheck          # strict tsc over extensions/
-npm run check:piisms      # exit 1 if Cursor-shaped content ships
+npm test          # node:test over the extension logic, 44 cases
+npm run typecheck
 ```
 
-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).
+Extension logic is split into testable units: `settings.ts` (model maps and budgets), `context-guard.ts` (thresholds), `compaction.ts` (the summary contract), `doctor.ts` (validators), `skill-budget.ts` (prompt cost). Tests run on plain node, no build step.
 
 ## 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).
+MIT. Upstream pstack is Lauren Tan's work; this port follows upstream and names every place it departs.

package/agents/comment-sicko.md

@@ -34,4 +34,4 @@ A long justification without a proven keep-list exception is a confession. Kill
 
 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.
+Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips.

package/agents/poteto-agent.md

@@ -11,6 +11,6 @@ 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.
+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 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.
+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/compare.md

@@ -0,0 +1,122 @@
+# How this port compares
+
+Two things get compared here. Upstream `cursor/plugins`' pstack, which is the source we vendor, and `@zenspc/pi-pstack`, the other Pi port on npm.
+
+Every number below is reproducible. The commands are at the end.
+
+## Versions compared
+
+| Thing | Version | Ref |
+|---|---|---|
+| Upstream pstack | 0.15.2 | `5bf2b1544db739998121a306340631963c2ff3de` |
+| This port | 0.2.0 | working tree |
+| `@zenspc/pi-pstack` | 0.6.0 | published 2026-09-09 |
+
+The version this port was vendored from before this change was upstream 0.14.4. That is an eight-release gap, and the reason it existed is worth stating because it is the problem the port now solves.
+
+The old `sync-upstream.mjs` wiped the vendored tree and asked a human to re-apply every Pi adaptation by hand. The adaptations were never written down, so each sync threw them away. Nobody wants to redo that work, so the port sat still. The fix was to record the adaptations as data instead of as tribal knowledge.
+
+## What upstream changed after the 0.15.2 pin
+
+Upstream added two commits after the ref this port was pinned to, without a version bump. Both are covered as of this release.
+
+| Upstream change | What this port did |
+|---|---|
+| bug-fix, perf-issue, and hillclimb code-delegate defaults moved to `grok-4.6-fast-xhigh` (#365) | Adopted by the sync lever and then erased by it. The `pi-model-defaults` rule rewrites every pinned slug to `inherit`, so the three playbooks came out byte-identical and needed no new rule. This is the port working as designed: upstream retunes its model panel, and Pi readers keep the parent-model default. |
+| `/setup-pstack` asks for a reasoning budget first: unlimited, large, medium, or small, mapped onto the effort ladder and recorded in the rule (#366) | Ported natively. `/pstack-setup` asks the same four budgets and writes Pi's own `subagents.defaultThinking` (`large` is `xhigh`, `medium` is `high`, `small` is `medium`, `unlimited` clears the key), so a role with an explicit level keeps it. The recorded budget reads back off the settings, not out of a private file. |
+
+## What upstream changed between 0.14.4 and 0.15.2
+
+| Upstream change | What this port did |
+|---|---|
+| Density and mannered-prose pass across every skill | Adopted. This is the bulk of the diff, 98 files. |
+| Two new principle leaves, `principle-attack-the-premise` and `principle-test-behavior-not-implementation` | Adopted, and both added to the mode's principle index. |
+| Critique mode removed from the `how` skill, with `references/critic-prompt.md` and `references/critique-rubric.md` deleted and the callers in `architect` and the investigation playbook updated | Adopted. The two reference files were deleted here too. |
+| Model invocation disabled for `how`, `why`, `unslop`, `typescript-best-practices`, and `make-bot-ui` | Adopted. Pi now hides those four from the model's prompt list, so they are reached by name through `/poteto-mode` or directly with `/skill:<name>`. See the measurement below for why this makes the other port's skill-stripping feature even smaller than it looked. |
+| A rule that every claim carries its evidence or its label | Adopted into the reply contract. |
+| Operator-neutral pronouns in the autopilot and multi-phase playbooks | Adopted. Ours also drops the "lands herself" phrasing. |
+| Forge-neutral shipping that reaches GitHub or Origin instead of requiring Graphite | Adopted. A reader without Graphite is no longer blocked. |
+| Semicolons, em dashes, and connector colons replaced with periods and commas across the skill prose | Adopted. |
+| A plugin logo and the Cursor marketplace asset | Skipped. It is a marketplace asset for Cursor's plugin directory. |
+| `make-bot-ui` moved to the skills root and registered | Excluded. It drives Cursor's Grok Bot webhook through `api2.cursor.sh`, which Pi cannot reach. `control-ui` covers the same job locally. |
+| Cursor model slugs reintroduced as role defaults | Rewritten. Every pinned slug becomes `inherit`, because Pi runs a delegate on the parent session model unless you assign one. |
+
+One upstream change we deliberately did not take. Upstream 0.15.2 replaced the mode skill's opening non-negotiable with a weaker citation rule and dropped the instruction to make reading the Principles the first todo. Upstream's own guide flow diagram still shows that step. This port keeps the stronger instruction, and `skills/poteto-mode/SKILL.md` is declared as an override with a baselined hash so an upstream edit to that file fails the check instead of silently reverting us.
+
+## Capabilities against `@zenspc/pi-pstack` 0.6.0
+
+| Capability | This port | `@zenspc/pi-pstack` 0.6.0 |
+|---|---|---|
+| Upstream content | 50 skills, current to 0.15.2 | 47 skills, current to the 0.15.x line |
+| Workflow skills the model sees | 5 of 50, because this port keeps upstream's `disable-model-invocation` flags | 4 of 47, because the port deletes those flags and strips the skills at runtime instead |
+| Setup | `/pstack-setup` interactive wizard. Budget picker, scope picker, three tiers, per-role picker, and argument fast paths (`-l`, `inherit`, `light`, `custom`, a budget word, a bare role name) | `/setup-pstack` writes a JSON file. No picker, no budget |
+| Where role models live | Pi's own `subagents.*` keys in `settings.json`, shared with the rest of Pi and hand-editable | A private `~/.pi/agent/pstack/models.json` that nothing else reads |
+| Reasoning budget | Four budgets written to `subagents.defaultThinking`, read back on re-runs, per-role levels win | None |
+| Status surface | `/pstack-status` prints the parent session model, the resolved model for every role, the settings file that won, the loaded skill inventory, and the system-prompt token cost of the model-visible skills | `/pstack status` reports whether pstack is on or off |
+| Sticky mode | Persisted as a session entry, survives a reload, shows a footer status, and shows a HUD line below the editor while on | A session entry and a footer status |
+| Context guard | Metered every turn while the mode is on: advice at 70 and 85 percent, one-key compaction at 92, live meter in the HUD | None |
+| Compaction | While the mode is on, compaction summaries are shaped around the playbook, decision ledger, and verification state, falling back to Pi's default on any failure | Pi's default compaction |
+| Install diagnostics | `/pstack-doctor` validates settings, flags unknown roles, checks agent frontmatter, counts playbooks, names missing companions, reports the pin | None |
+| Plain-language restate | `/bro` is a command | `bro` is a skill only |
+| Missing-dependency check | At startup, names each missing companion package, what it provides, and the install command | None |
+| Pi-only skills | `control-cli`, `control-ui`, `create-skill` have no counterpart in the other port | Absent |
+| Port drift control | `scripts/pi-deltas.json` declares every adaptation, `npm run verify:sync` classifies every vendored file and fails on anything unexplained, and a rule that stops matching is itself a failure | None. A re-vendor is a manual diff |
+| Prompt-cost transparency | Measured and printed by `/pstack-status` | Strips skills without reporting the number |
+| Skill visibility toggle | None. Follows upstream's static `disable-model-invocation` flags, which hide 45 of 50 skills | `/pstack on|off` toggles skill visibility at runtime |
+| Role model resolution | Recomputed from the settings chain on every status call, so `inherit` always shows what it currently means | Reads its own config file |
+| Tests | 44 committed tests over the extension logic and the sync rule engine | `check-plan` tests plus watch-pr tests |
+
+We are behind in exactly one respect that matters to a stranger: release cadence. The other port has shipped six releases since 2026-08-22 and this one is at 0.2.0.
+
+## The one place the other port does more, and what we did instead
+
+`@zenspc/pi-pstack` ships `/pstack on|off`, a runtime toggle that adds and removes pstack's skills from the model's prompt list. It is a real convenience and it is the single thing that port has which this one does not.
+
+It exists because of a design difference, not a missing capability. Upstream 0.15.2 marks `how`, `why`, `unslop`, and `typescript-best-practices` with `disable-model-invocation: true`, and Pi honours it by leaving them out of the prompt. This port keeps upstream's flags. The other port deletes those flags from its copy and gives the user a runtime toggle instead, so the default state is the same on both and the toggle is the addition.
+
+We measured both sides before deciding whether to grow our own equivalent.
+
+```
+total skills: 50
+hidden by Pi from upstream's flags: 45
+offered to the model: 5, control-cli, control-ui, create-skill, deslop, setup-pstack
+their four toggleable skills, how, why, unslop, typescript-best-practices: about 373 tokens
+the five this port leaves offered: about 402 tokens
+all nine together: about 776 tokens
+```
+
+The two designs land in the same place by default. Their toggle can hide about 373 tokens; this port already hides those same 373 tokens because upstream asked Pi to. What separates them is the mechanism and the reporting.
+
+A static frontmatter flag costs no extension state, survives an upgrade, and works in any Pi session including one where this extension failed to load. A runtime toggle needs mode state, a command, and a way to re-apply the strip on every turn. We kept the flag, and we spent the equivalent effort on telling you the number instead. `/pstack-status` prints the live cost, and undoing a flag is documented in the README as one deleted line plus `/reload`.
+
+If you want the toggle specifically, the other port has one and this one does not. That is an honest difference rather than a gap we are hiding, and the measurement above is why we did not build the same thing.
+
+## Related projects
+
+Three Pi ports of pstack exist. This one is a third, named `@mccune1224/pi-pstack` to stay distinct.
+
+The extension code here was written for this package. A line-level comparison of `extensions/index.ts` against `@zenspc/pi-pstack`'s `extensions/pstack/index.ts` finds 19 identical non-trivial lines out of 276, all of them Pi API boilerplate such as the `session_start` registration. There is no shared implementation to attribute.
+
+The skills are a different matter. They are adapted from upstream pstack, which is MIT and copyright Lauren Tan. That attribution is in the LICENSE and at the end of the README. If you are looking for the other Pi ports, they are [`@zenspc/pi-pstack`](https://github.com/zenspc/pi-extensions/tree/master/packages/pi-pstack) and [`pi-pstack`](https://www.npmjs.com/package/pi-pstack).
+
+## How to reproduce
+
+```bash
+git clone --depth 400 https://github.com/cursor/plugins.git /tmp/upstream-plugins
+npm run verify:sync        # per-file classification, exits non-zero on anything unexplained
+npm run check:piisms       # exits non-zero on any Cursor-only reference
+npm test                   # extension logic and sync rule engine
+
+# count what Pi exposes to the model and what it costs
+node -e '
+const { readdirSync, readFileSync } = require("node:fs");
+for (const name of readdirSync("skills").sort()) {
+  const src = readFileSync(`skills/${name}/SKILL.md`, "utf8");
+  const fm = (src.match(/^---\n([\s\S]*?)\n---/) || [])[1] || "";
+  if (!/disable-model-invocation:\s*true/.test(fm)) console.log(name);
+}'
+
+# compare skill inventories with the other port
+npm pack @zenspc/pi-pstack && tar xzf zenspc-pi-pstack-*.tgz
+diff <(ls skills) <(ls package/skills)
+```

package/docs/guide/01-setup.md

@@ -1,16 +1,16 @@
 # 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.
+In this page you install the package, 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:
+## Install the package
 
 ```bash
-pi install /path/to/pi-pstack
+pi install npm:@mccune1224/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.
+From a checkout, `pi install /path/to/pi-pstack` works the same way. Then run `/reload`, and Pi registers the skills, the agents, and the commands.
+
+Install [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) alongside it. It provides the `subagent` tool that every routed workflow uses. pstack checks at startup and names the missing package when it is absent.
 
 ## Pick your models
 
@@ -20,11 +20,36 @@ Run:
 /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.
+[`/pstack-setup`](../../skills/setup-pstack/SKILL.md) reads the models your session can reach, asks where to save the map, asks for a reasoning budget, and offers three tiers: all-inherit, light, or a per-role picker. Fast paths skip the questions, so `/pstack-setup -l` writes to the project, `/pstack-setup inherit` takes the cheapest tier, `/pstack-setup small` sets a small reasoning budget, and `/pstack-setup scout` changes one role.
+
+The budget is Pi's own thinking ladder: `large` sets `xhigh` reasoning for every role that has no explicit level, `medium` sets `high`, `small` sets `medium`, and `unlimited` leaves each role at its own setting. It writes `subagents.defaultThinking`, so a role you configured individually keeps its level.
+
+It writes the `subagents.*` keys in Pi settings, which is the same place every other Pi tool reads model choices from:
+
+- User scope: `~/.pi/agent/settings.json`
+- Project scope: `.pi/settings.json`, which wins when both exist
 
-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`.
+Every role defaults to `inherit`, which runs the delegate on your parent session model at no extra cost. That is the recommended setting. Set a role explicitly only when you want a tier, and `/pstack-status` shows the resolved map and names the file that won.
+
+Because pstack uses Pi's own settings, the mapping is not private to this package. Anything else that reads `subagents.*` sees the same choices, and you can edit the file by hand.
+
+## Check what is loaded
+
+Run:
+
+```text
+/pstack-status
+```
+
+[`/pstack-status`](../../extensions/index.ts) prints the parent session model, the effective model for every role, the recorded budget, the settings file that won, and how many pstack skills are loaded. It also reports the system-prompt cost of the skills Pi exposes to the model.
+
+Something look off? Run:
+
+```text
+/pstack-doctor
+```
 
-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.
+[`/pstack-doctor`](../../extensions/doctor.ts) checks both settings files for bad model slugs, thinking levels, and role typos that would silently do nothing, verifies the package agents' frontmatter, counts the vendored playbooks, names missing companion packages, and reports the upstream pin.
 
 ## Accept the verification offer, or don't
 
@@ -32,7 +57,7 @@ At the end of setup, `/pstack-setup` looks for a way to prove app behavior in yo
 
 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.
+The model map applies from the next turn. Pi re-reads settings per turn, so no reload is needed.
 
 ## Run your first task
 
@@ -42,8 +67,8 @@ Pick something real but small, and describe it the way you'd describe it to a co
 /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.
+Watch the todo list. The first item is always to 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.
+From here you can type normal follow-ups. `/poteto-mode` is sticky. It stays on for the session, the choice persists across reloads, and the footer shows `pstack: poteto mode` while it is on, with a live context meter in the HUD below the editor. `/poteto-mode off` turns it back off.
 
 Next: [Route work through `/poteto-mode`](./02-poteto-mode.md).

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

@@ -1,6 +1,6 @@
 # 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.
+`/poteto-mode` is the front door. You give it a goal, it matches one of twenty-three 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)
 

package/docs/guide/03-understand.md

@@ -12,14 +12,6 @@ Editing code you don't understand is how subtle regressions ship. pstack gives y
 
 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

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

@@ -48,7 +48,7 @@ In context, that's enough. [`/tdd`](../../skills/tdd/SKILL.md) writes the smalle
 
 ## 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.
+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). The bar is the same either way: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits.
 
 For prose, `/unslop` takes a target and any extra rules you have:
 

package/docs/guide/06-verify-and-ship.md

@@ -82,6 +82,6 @@ Green is not the same as safe. When you're ready to land, say so:
 /poteto-mode land the stack.
 ```
 
-The [Shipping playbook](../../skills/poteto-mode/playbooks/shipping.md) verifies each PR independently before it arms anything. One fresh agent per PR proves the behavior live, and the agent that judges a change is never the one that wrote it. Then Shipping lands only the contiguous verified run from the bottom, through Graphite merge-when-ready, and reports the first PR that breaks the chain. A verified PR sitting above an unverified one waits, because merging it would pull the gap in underneath.
+The [Shipping playbook](../../skills/poteto-mode/playbooks/shipping.md) verifies each PR independently before it arms anything. One fresh agent per PR proves the behavior live, and the agent that judges a change is never the one that wrote it. Then Shipping lands only the contiguous verified run from the bottom, one PR at a time through GitHub by default or Origin when its CLI is available, and reports the first PR that breaks the chain. A verified PR sitting above an unverified one waits, because merging it would pull the gap in underneath.
 
 Next: [Run work while you sleep](./07-overnight.md).

package/docs/guide/07-overnight.md

@@ -12,7 +12,7 @@ A good handoff has the goal, the finish condition, permissions, and an escape ha
 /poteto-mode im going to bed. migrate every caller to the new parser in a fresh worktree off <base>.
 done means zero old callers, all parser fixtures pass, old api deleted.
 keep a decision log. don't ask me before committing.
-/loop until done. if you're truly stuck after a few hours, stop and write up why.
+keep going until done. if you're truly stuck after a few hours, stop and write up why.
 ```
 
 Walk through what each line buys you:
@@ -64,7 +64,7 @@ The contract above drives one task to one finish condition. Some nights hold mor
 /poteto-mode full autopilot on this queue. each item is independent. i want them merged by morning.
 ```
 
-[Autopilot-stack](../../skills/poteto-mode/playbooks/autopilot-stack.md) runs the same owner loop but ships nothing. You wake up to one linear Graphite stack with a verifier's verdict on every link, and you review and land it yourself. Pick it over Autopilot-full when the changes are coupled, or when you want your own eyes on the work before anything merges:
+[Autopilot-stack](../../skills/poteto-mode/playbooks/autopilot-stack.md) runs the same owner loop but ships nothing. You wake up to one linear base-branch stack with a verifier's verdict on every link, and you review and land it yourself. Pick it over Autopilot-full when the changes are coupled, or when you want your own eyes on the work before anything merges:
 
 ```text
 /poteto-mode autopilot these five changes but stack them, don't ship. i'll land the stack in the morning.

package/docs/guide/08-principles.md

@@ -1,6 +1,6 @@
 # Steer with principle names
 
-pstack ships 21 principles as individual skills. `/poteto-mode` reads their index at the start of every multi-step task, applies the ones the task triggers, and names each applied principle in its reply along with the decision it changed.
+pstack ships 23 principles as individual skills. `/poteto-mode` reads their index at the start of every multi-step task, applies the ones the task triggers, and names each applied principle in its reply along with the decision it changed.
 
 You don't invoke principles. You use their names to steer. Each name points at a complete rule the agent has already read, so one phrase redirects the work more precisely than a paragraph of instructions.
 
@@ -26,13 +26,14 @@ separate before serializing shared state. give each attempt its own worktree, no
 
 Each phrase lands because the rule behind it is specific. The agent still has to say, in its reply, which decision the rule changed. A principle citation with no decision behind it is the tell that it name-dropped instead of applying.
 
-## The 21, briefly
+## The 23, briefly
 
 The core principles decide how much to build and when to rethink the design:
 
 - [Laziness Protocol](../../skills/principle-laziness-protocol/SKILL.md) prefers deletion and the smallest change that solves the problem.
 - [Foundational Thinking](../../skills/principle-foundational-thinking/SKILL.md) chooses the core data structures before writing logic.
 - [Redesign from First Principles](../../skills/principle-redesign-from-first-principles/SKILL.md) integrates a new requirement as if it had been there from day one.
+- [Attack the Premise](../../skills/principle-attack-the-premise/SKILL.md) questions the premise that two or more failed fixes shared, after a census of which actors hold the imbalance.
 - [Subtract Before You Add](../../skills/principle-subtract-before-you-add/SKILL.md) removes dead weight before building on top of it.
 - [Minimize Reader Load](../../skills/principle-minimize-reader-load/SKILL.md) collapses layers and hidden state a reader must hold in their head.
 - [Outcome-Oriented Execution](../../skills/principle-outcome-oriented-execution/SKILL.md) converges rewrites on the target design instead of preserving throwaway compatibility states.
@@ -54,6 +55,7 @@ The verification principles define what counts as proof:
 - [Prove It Works](../../skills/principle-prove-it-works/SKILL.md) verifies the real artifact, not a proxy.
 - [Fix Root Causes](../../skills/principle-fix-root-causes/SKILL.md) reproduces and traces to the cause before changing code.
 - [Sequence Work into Verifiable Units](../../skills/principle-sequence-verifiable-units/SKILL.md) ends each small unit in a check before starting the next.
+- [Test Behavior, Not Implementation](../../skills/principle-test-behavior-not-implementation/SKILL.md) calls the code the way its users do and asserts a literal expected value, and deletes a test that would still pass if every imported function returned `undefined`.
 
 The delegation principles keep parallel work sane:
 

package/docs/guide/10-recipes-and-pitfalls.md

@@ -2,7 +2,7 @@
 
 Prompts worth copying, then the mistakes everyone makes once. Swap in your own paths and finish conditions. The recipes are deliberately informal. That's how they get typed in practice, and the skills read intent fine.
 
-![She tastes a finished dish while robots cook from a recipe box, with pinned cards reading /how, /tdd, and /loop above the counter.](./images/recipes.jpg)
+![She tastes a finished dish while robots cook from a recipe box, with pinned cards reading /how and /tdd above the counter.](./images/recipes.jpg)
 
 ## Understand an unfamiliar subsystem
 
@@ -81,7 +81,7 @@ That's the whole prompt. [`/bro`](../../skills/bro/SKILL.md) restates the last m
 ## The pitfalls
 
 - **Enumerating skills in the prompt.** "use /how then /architect then /arena" reorders steps the playbook already sequences. State the goal and constraints. Name a skill only to override a default.
-- **A vague finish condition.** "make it better" gives `/loop` nothing to check. Give a command or artifact that can pass or fail.
+- **A vague finish condition.** "make it better" gives the run nothing to check. Give a command or artifact that can pass or fail.
 - **Parallel agents in one worktree.** They overwrite each other and the diff becomes archaeology. Say "own worktree per attempt" and the isolation is free.
 - **Using `/arena` for coverage.** `/arena` repeats one design or code brief, then picks a base and grafts the best parts. `/swarm` partitions slices or declared race arms and aggregates one report.
 - **Accepting every review comment.** Bots and humans both file real catches and noise in one list. `/interrogate` sorts findings into act-on and dismissed buckets with reasons, and you can override either way.

package/docs/guide/README.md

@@ -4,14 +4,14 @@ pstack works best when you stop micromanaging the agent. You describe what you w
 
 Here's what you'll learn:
 
-1. [Set up pstack](./01-setup.md). Install the plugin and pick your models.
+1. [Set up pstack](./01-setup.md). Install the package and pick your models.
 2. [Route work through `/poteto-mode`](./02-poteto-mode.md). Give it a goal and watch it pick a playbook.
 3. [Understand the code](./03-understand.md). `/how`, `/why`, `/teach`, and `/recall` before you edit anything.
 4. [Design the change](./04-design.md). `/architect`, `/arena`, `/swarm`, and `/interrogate` before code locks in a shape.
 5. [Build and clean the change](./05-build-and-clean.md). The build playbooks, `/tdd`, `/unslop`, and `/no-comments`.
 6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, then open a focused PR and drive it to merged.
 7. [Run work while you sleep](./07-overnight.md). An overnight contract, a decision log you can audit, and the playbooks that scale past one agent.
-8. [Steer with principle names](./08-principles.md). The 21 names that redirect an agent mid-task.
+8. [Steer with principle names](./08-principles.md). The 23 names that redirect an agent mid-task.
 9. [Make it yours](./09-make-it-yours.md). Your own mode, plus how to test a skill change.
 10. [Recipes and pitfalls](./10-recipes-and-pitfalls.md). Prompts to copy and mistakes to skip.