feat(pstack): refresh workflows and guide without model changes

CHANGELOG.md

@@ -4,6 +4,12 @@ summary: Timeline of guardrail helper changes mirrored from Sweetistics and rela
 
 # Changelog
 
+## 2026-10-11: PStack workflow and guide refresh
+- Ported PStack 0.15.17 through `978ca6e9c0`, preserving all existing models, efforts, panel sizes, aliases, fallback policy, and executable helpers.
+- Added explicitly invoked `poteto-help` and `ketchup`, prompting references, and the ten-page PStack guide with upstream images.
+- Applied upstream prompt distillation and Architect grounding correction; changed only the Codex invocation, agent, transcript, installation, goal, and scheduler interfaces.
+- Removed remaining PStack per-skill license copies and source banners, preserving the root license and existing skill instructions.
+
 ## 2026-10-04: PStack workflow refresh
 - Ported upstream PStack 0.15.9 workflows through `e43c7ee26e`, preserving every local model, effort, panel, and model-routing override.
 - Added `correct`, `benchmark-checklist`, and `principle-explain-the-number`; strengthened Architect ownership/API checks and schema-first TypeScript validation examples.

README.md

@@ -57,6 +57,8 @@ skills/wacrawl -> ../../oss/wacrawl/.agents/skills/wacrawl
 
 Optional crawler/messaging symlinks may be absent on Bram's machine; agents must check before use.
 
+The [PStack guide](docs/pstack/README.md) covers setup, prompting, design, verification, and overnight work. Use `$poteto-help` for a question or `$ketchup` to catch up on the current chat.
+
 ## Agent Instructions
 
 Shared hard rules live in `AGENTS.MD`.

docs/pstack/01-setup.md

@@ -0,0 +1,63 @@
+# Set up pstack
+
+In this page you install the skills, pick which models pstack uses, and run your first task. Setup is one command plus a short conversation.
+
+## Install the skills
+
+From the agent-scripts checkout, run:
+
+```bash
+scripts/sync-skills --dry-run
+scripts/sync-skills
+```
+
+The helper mirrors the skills into Codex's skill discovery directory.
+
+## Pick your models
+
+Run:
+
+```text
+$setup-pstack
+```
+
+[`$setup-pstack`](../../skills/setup-pstack/SKILL.md) detects the models you have access to, asks for a reasoning budget, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes `${CODEX_HOME:-$HOME/.codex}/skills/poteto-mode/references/models.md`, a small role file the routed pstack skills read.
+
+The defaults and reasoning budget are recorded in `${CODEX_HOME:-$HOME/.codex}/skills/poteto-mode/references/models.md`. `unlimited` keeps the role defaults. `large`, `medium`, and `small` select `xhigh`, `high`, and `medium` reasoning, within the configured model's supported efforts.
+
+You only override what you care about. A role with no line in the rule keeps the skill's default. To restore a default, delete that role's line. A rerun of `$setup-pstack` keeps any role whose model differs from the default. When a default changes, a rule written before the change still pins the old default, so delete those role lines, or delete the file, then run `$setup-pstack` again.
+
+You might be wondering what happens if you use Auto. Set a role to `inherit-parent` or `auto` and pstack omits the subagent `model` field, so the subagent inherits your parent chat model. Both values mean the same thing, and neither is a model slug. 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 `swarm workers`, the default model for every `$swarm` worker unless a race names a model for each arm.
+
+## Accept the verification offer, or don't
+
+At the end of setup, `$setup-pstack` 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 `.agents/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 it in depth.
+
+If you're new to pstack, say yes. An agent that can check its own work keeps going until the check passes. An agent that can't hands every result back to you to check by hand. Of everything in this guide, the verification skill pays off the most.
+
+After setup, start a new chat. The routed skills read the role file when they run.
+
+## Keep the cost in check
+
+pstack spends extra tokens on subagents and review panels. That's the price of the rigor. To spend fewer:
+
+- Rerun `$setup-pstack` and pick a smaller reasoning budget or cheaper models. A strong model in the main chat with cheaper, faster models in the code roles is a good split.
+- Set a role to `auto` or `inherit-parent` so it runs on the chat's own model.
+- Shorten a panel list. Each entry runs one subagent.
+- Save `$poteto-mode` for work that needs rigor. A small, obvious edit doesn't.
+
+## 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. Its first items 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. Start each new task with `$poteto-mode` so Codex loads the skill and picks its playbook.
+
+Next: [Route work through `$poteto-mode`](./02-poteto-mode.md).

docs/pstack/02-poteto-mode.md

@@ -0,0 +1,131 @@
+# Route work through `$poteto-mode`
+
+`$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)
+
+## 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>`.
+
+## What goes in a prompt
+
+A useful prompt carries up to five things, and each one fits in a sentence:
+
+- **The goal.** Say what's wrong, or what you want.
+- **The done check.** It must be able to pass or fail. "Make it better" and "work on it for an hour" aren't checks.
+- **The proof you want to see.** Ask for the real command output, a video of the flow, the stored value, or a before-and-after number.
+- **What you already know.** A symptom, a repro step, a log line, or a link saves the agent a search.
+- **The real constraints.** "repro first", "don't change any code yet", "zero behavior change", and "let me review before proceeding" each change what the agent does.
+
+Here's one prompt with all five:
+
+```text
+$poteto-mode the csv export drops its last row since yesterday's deploy. failing job id is 4812. repro first, then fix. done means the 60k-row fixture exports every row. show me the row counts before and after.
+```
+
+Two things are worth leaving out:
+
+- **The how.** Say what to achieve, and leave the agent room to find a better path than the one you'd pick. The same goes for a list of skills, covered in the pitfall below.
+- **Your theory of the cause, at first.** A stated guess narrows the search to wherever you pointed. Let the agent restate the problem before you share your hunch.
+
+For a noisy report, such as a long thread or a vague bug, make the restatement the first step:
+
+```text
+$poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet.
+```
+
+A misreading shows up in the restatement, before any code exists. Correct it there, and it costs you one message instead of one wrong fix.
+
+## Follow up short
+
+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 playbook holds the structure. Start each new task with `$poteto-mode`. [Set up pstack](./01-setup.md#run-your-first-task) shows how to start a task. 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 on one computer, they will fight over the working tree, the ports, and the build output. Give each independent attempt its own branch and worktree. Codex collaboration agents share the parent checkout unless their briefs point to separate worktrees.
+
+When the work has to stay local, ask for a worktree 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. Worktrees cost disk and machine resources, so a laptop runs only a handful at once. 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).

docs/pstack/03-understand.md

@@ -0,0 +1,79 @@
+# Understand the code before changing it
+
+Editing code you don't understand is how subtle regressions ship, and that's as true for the agent as for you. Agents usually fail in one of two ways. They misread what you want, or they don't have the context to do the work right. [What goes in a prompt](./02-poteto-mode.md#what-goes-in-a-prompt) handles the first. This page handles the second.
+
+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. Each one also makes the agent explain itself in words you can check. That's how you supervise an agent that may know the code better than you do.
+
+![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)
+
+## Start with a read-only investigation
+
+When the cause is unclear, ask for findings, not a fix:
+
+```text
+$poteto-mode investigate why background jobs time out every few hours. give me what we know, what data you used, and your best hypotheses. don't change any code yet.
+```
+
+"don't change any code yet" routes this to the [Investigation playbook](../../skills/poteto-mode/playbooks/investigation.md). It runs `$how`, adds `$why` for questions about motivation, and returns a cited explanation. For a choice between options, it returns a recommendation with a trade-offs table. Asking "what data you used" makes the agent separate its evidence from its guesses. When the findings point at a fix, start the fix as a new task.
+
+## 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.
+
+## 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.
+
+It works on the agent's own choices too:
+
+```text
+$teach me why you implemented it this way and not with a queue. what did you trade off, and why?
+```
+
+Teaching helps the agent as much as you. An agent that has to explain its work must read the code and back each claim with evidence, instead of stating it confidently and moving on.
+
+## 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. Your old chats hold context that a fresh agent lacks, so start new work on an old topic by loading it first, then hand over the new input:
+
+```text
+$recall my work on the virtualized list from yesterday, then read this bug report.
+```
+
+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).