feat(upstream): sync pstack to 2cbf585

.github/workflows/validate.yml

@@ -45,7 +45,7 @@ jobs:
       - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
         with:
           repository: cursor/plugins
-          ref: f5bdd6826fd0a0d9cbc4347134c3a74a200b9d9d
+          ref: 2cbf58508f40de470d7490b55c51d71241928fa2
           path: .upstream/cursor-plugins
           sparse-checkout: pstack
       - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5

README.md

@@ -67,7 +67,7 @@ claude plugin install mstack@mstack
 Plugin skills are namespaced, for example `/mstack:meta-mode`, and the agents
 appear as `mstack:meta-agent` and `mstack:comment-reviewer`. Run
 `claude plugin details mstack` to see the inventory and its projected token
-cost; the 50 skill descriptions add about 3,000 tokens to every session.
+cost; the 53 skill descriptions add about 3,100 tokens to every session.
 `claude plugin marketplace update mstack` picks up new releases, because the
 plugin `version` tracks the npm version.
 
@@ -420,7 +420,7 @@ target directory and restores backups if a commit fails.
 
 ## Included skills
 
-The current bundle contains 50 skills. It includes the 47 entries in the
+The current bundle contains 53 skills. It includes the 50 entries in the
 portable pstack tree and three skills adapted from `mattpocock/skills`:
 
 - Engineering principles for boundaries, domain modelling, idempotence,
@@ -431,6 +431,8 @@ portable pstack tree and three skills adapted from `mattpocock/skills`:
   workflow.
 - `meta-mode` for routing a multi-step task through the capabilities available
   in the current harness.
+- `benchmark-checklist` and `correct` for vetting a measured number and for
+  fixing repeated agent mistakes at the repository level.
 
 The bundle includes the pstack workflow and principle names. `meta-mode` is the
 portable replacement for pstack's `poteto-mode`; it describes capabilities and
@@ -465,7 +467,7 @@ To check the complete skill trees against both pinned upstreams, run:
 npm run skill-baseline -- --check --source /path/to/pstack --matt-source /path/to/mattpocock-skills
 ```
 
-This checks every file in all 50 skill trees, including references, playbooks,
+This checks every file in all 53 skill trees, including references, playbooks,
 and scripts. It also checks tools moved out of skill directories. Local
 additions and intentional upstream omissions are recorded explicitly. Both
 source checkouts must be clean and at their pinned commits. `npm test` checks

THIRD_PARTY_NOTICES.md

@@ -5,7 +5,7 @@
 The skills in this repository are adapted from the `pstack` plugin in
 [`cursor/plugins`](https://github.com/cursor/plugins/tree/main/pstack/skills),
 with the current complete snapshot pinned at commit
-[`7366ac128bdf95f45e6734f412b49a4031800169`](https://github.com/cursor/plugins/commit/7366ac128bdf95f45e6734f412b49a4031800169).
+[`2cbf58508f40de470d7490b55c51d71241928fa2`](https://github.com/cursor/plugins/commit/2cbf58508f40de470d7490b55c51d71241928fa2).
 The first port of selected skills was pinned at commit
 [`799151d91b6e12ee7dbd09f708eec108d7de9b3b`](https://github.com/cursor/plugins/commit/799151d91b6e12ee7dbd09f708eec108d7de9b3b).
 
@@ -32,10 +32,11 @@ Adapted upstream skill names:
 - `principle-build-the-lever`
 
 The bundle also includes these principles from the current upstream tree, pinned
-at commit [`7366ac128bdf95f45e6734f412b49a4031800169`](https://github.com/cursor/plugins/commit/7366ac128bdf95f45e6734f412b49a4031800169):
+at commit [`2cbf58508f40de470d7490b55c51d71241928fa2`](https://github.com/cursor/plugins/commit/2cbf58508f40de470d7490b55c51d71241928fa2):
 
 - `principle-attack-the-premise`
 - `principle-encode-lessons-in-structure`
+- `principle-explain-the-number`
 - `principle-exhaust-the-design-space`
 - `principle-experience-first`
 - `principle-foundational-thinking`
@@ -54,7 +55,7 @@ Cursor-only commands or paths.
 
 The remaining pstack workflow skills are included under their original names.
 The portable bundle renames `poteto-mode` to `meta-mode` and `poteto-agent` to
-`meta-agent`. The source inventory is recorded in `profiles/skills.json`.
+`meta-agent`. The `poteto-help` skill is not included. The source inventory is recorded in `profiles/skills.json`.
 Source commits and renames are recorded in `profiles/upstreams.json`. The
 non-skill upstream artifacts are retained as follows:
 

agents/meta-agent.md

@@ -1,6 +1,6 @@
 ---
 name: meta-agent
-description: Routing target for `/meta-mode` and requests for the mstack workflow. Resume an existing `meta-agent` for the conversation rather than spawning a sibling. Read the `meta-mode` skill's `SKILL.md` in full before any work, including its playbook map.
+description: Routing target for `/meta-mode` and requests for the mstack workflow. Spawn a fresh `meta-agent` for each new task, and resume one only when the new work needs state that lives in that agent, such as its local checkout, its uncommitted changes, or a process it still runs, as meta-mode's Subagents section lists. Read the `meta-mode` skill's `SKILL.md` in full before any work, including its playbook map.
 ---
 
 # Meta subagent

docs/guide/01-setup.md

@@ -21,7 +21,7 @@ Run:
 /setup-mstack
 ```
 
-[`/setup-mstack`](../../skills/setup-mstack/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 `~/.config/mstack/models.json`, the portable configuration every mstack skill reads.
+[`/setup-mstack`](../../skills/setup-mstack/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 `~/.config/mstack/models.json`, the portable configuration every mstack skill reads.
 
 You only override what you care about. To restore a role to the parent chat model, set it to `inherit-parent` or run `/setup-mstack` again. Setup preserves other choices and Harness overrides.
 
@@ -33,10 +33,21 @@ At the end of setup, `/setup-mstack` looks for a shared verification contract, a
 
 If it finds neither a reusable verification workflow nor a repository driver, setup offers once to run [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md). When you accept, the generator writes `.harness/verify/<app>/contract.md`, its feature map, and thin discovery wrappers. It proves one feature in the real app before handing over the result. Model setup alone does not start the app or create a team policy.
 
-You can run `/create-verification-skill` yourself any time. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers the proof. For a team using both native pstack and mstack, follow [the mixed-Harness adoption guide](./11-mixed-harness.md) to add the shared project workflow and CI checks.
+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 the proof. For a team using both native pstack and mstack, follow [the mixed-Harness adoption guide](./11-mixed-harness.md) to add the shared project workflow and CI checks.
+
+If you're new to mstack, 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 session. The model configuration applies to new sessions.
 
+## Keep the cost in check
+
+mstack spends extra tokens on subagents and review panels. That's the price of the rigor. To spend fewer:
+
+- Rerun `/setup-mstack` 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 `inherit-parent` so it runs on the chat's own model.
+- Shorten a panel list. Each entry runs one subagent.
+- Save `/meta-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:
@@ -47,6 +58,6 @@ Pick something real but small, and describe it the way you'd describe it to a co
 
 Watch the todo list. Its first items are the matched playbook's steps copied in, the Feature playbook for this prompt. If `/meta-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. `/meta-mode` is sticky. It stays on for the conversation until you opt out by saying so.
+From here you can type normal follow-ups. `/meta-mode` stays active for the current task and fades as the chat moves on. When it fades, start the next task with `/meta-mode`, or pin it for the whole chat if your Harness can pin a skill or mode. Mid-chat, "new task" makes it match a fresh playbook.
 
 Next: [Route work through `/meta-mode`](./02-meta-mode.md).

docs/guide/02-meta-mode.md

@@ -37,6 +37,37 @@ You don't write a spec. You say what's wrong or what you want, plus anything you
 
 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
+/meta-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
+/meta-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
@@ -51,7 +82,7 @@ continue
 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.
+Short works because the playbook holds the structure, and `/meta-mode` stays active for the current task. [Set up mstack](./01-setup.md#run-your-first-task) says what to do when it fades. Your words carry the intent, and the skill carries the rigor.
 
 ## Switch tasks with "new task"
 
@@ -63,15 +94,17 @@ A long chat accumulates context from the last task. When you change subjects, sa
 
 "new task" tells `/meta-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
+## Give parallel work its own machine
+
+If you run several agents against one repository on one computer, they will fight over the working tree, the ports, and the build output. The cleanest isolation is a worker on its own machine or remote environment, when the active Harness offers one. Each gets its own branch, so it can install dependencies, run your app, and record the result without touching your machine. Ask the parent chat to hand the work to remote workers.
 
-If you run several agents against one repository, they will fight over the working tree. Ask for isolation up front:
+When the work has to stay local, ask for a worktree up front:
 
 ```text
 /meta-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/meta-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.
+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/meta-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:
 

docs/guide/03-understand.md

@@ -1,9 +1,21 @@
 # Understand the code before changing it
 
-Editing code you don't understand is how subtle regressions ship. mstack 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.
+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-meta-mode.md#what-goes-in-a-prompt) handles the first. This page handles the second.
+
+mstack 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
+/meta-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/meta-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
@@ -30,13 +42,27 @@ The two compose naturally. `do why first then how` is a perfectly good prompt wh
 
 [`/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. 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`.
+[`/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