DEV-1181: port pstack 0.15.30-0.15.32 (statechart, ketchup-video)

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 2026-10-24: sync with pstack 0.15.32
+
+Upstream: [cursor/plugins](https://github.com/cursor/plugins) pstack at `9580c23` (0.15.32), by Lauren Tan (poteto), MIT.
+
+- **New `/statechart`** ([#741](https://github.com/cursor/plugins/pull/741), [#776](https://github.com/cursor/plugins/pull/776), [#779](https://github.com/cursor/plugins/pull/779), [#791](https://github.com/cursor/plugins/pull/791)). Draws how a system moves between states as a Mermaid statechart generated from a TLA+ model, with each bug TLC finds as a numbered path. Also turns an agreed chart into a TLA+ skeleton, or audits code against an existing spec. The skill and its `scripts/` are upstream's at 0.15.32, unchanged: nothing in them is Cursor-specific.
+- **New `/ketchup-video`** ([#797](https://github.com/cursor/plugins/pull/797)). `/ketchup` as a short silent video of slides, with the waiting calls as text under it. T3 wiring: "chat" becomes "thread", and the video is embedded in the thread by its absolute path.
+- **`/reflect` keeps edits out of the installed checkout** ([#800](https://github.com/cursor/plugins/pull/800)). Upstream forbids editing skills under `plugins/cache/`. Here the equivalent is the p3-stack checkout that `install.sh` symlinks into `~/.agents/skills/`: reflect replaces the symlink with a copy and edits the copy, which `install.sh` then leaves alone. Never opens a PR or pushes.
+- **`/swarm` report wording** ([#807](https://github.com/cursor/plugins/pull/807)). Phase D names "a result table" instead of "the table". The step renumbering in #807 was already right here, because p3-stack kept the "Set N" step that upstream had dropped.
+- `/p3-help` routes to `/ketchup-video` and `/statechart`. The README lists both and credits the new upstream commit. `NOTICE` names the new commit.
+
+Not ported, because p3-stack has no counterpart:
+
+- Version bumps to 0.15.31 and 0.15.32 ([#792](https://github.com/cursor/plugins/pull/792), [#798](https://github.com/cursor/plugins/pull/798)): no `plugin.json`.
+- `watch-pr` fixes ([#801](https://github.com/cursor/plugins/pull/801), [#802](https://github.com/cursor/plugins/pull/802)): `watch_pull_request` replaces `scripts/watch-pr`.
+- `check-plan.mjs` ([#803](https://github.com/cursor/plugins/pull/803)), `orch` ([#804](https://github.com/cursor/plugins/pull/804)), `worktree-audit.sh` ([#805](https://github.com/cursor/plugins/pull/805)): p3-mode ships no scripts. Delegation and worktrees go through T3 tools.
+- Claude Code marketplace auto-update note ([#806](https://github.com/cursor/plugins/pull/806)): install is a symlink from a git clone. `git pull` updates it.
+- `create-formal-verification-skill` pointer to `/statechart` ([#794](https://github.com/cursor/plugins/pull/794)): that skill is not ported yet. Carry the line over when it is.
+- `docs/guide` sections for `/statechart` and `/ketchup-video` (#741, #797): p3-stack has no guide.
+
+### Follow-up
+
+Still not ported:
+
+- `create-formal-verification-skill` (with #794)
+- `maintain-formal-verification-skill`
+- `in-your-own-words`
+
 ## 2026-10-21: sync with pstack 0.15.29
 
 Upstream: [cursor/plugins](https://github.com/cursor/plugins) pstack at `88d4751` (0.15.29), by Lauren Tan (poteto), MIT.

NOTICE

@@ -4,4 +4,4 @@ Copyright (c) 2026 Uzair Ansar (T3 Code adaptation)
 This product adapts pstack from https://github.com/cursor/plugins/tree/main/pstack,
 by Lauren Tan (poteto), licensed under the MIT License.
 Last synced with upstream cursor/plugins pstack at commit
-88d47514b82e7c44f00f2b2a72ff6dd12158038c (pstack 0.15.29).
+9580c23696ac8d7abed0c166f2f9918800afb819 (pstack 0.15.32).

README.md

@@ -33,12 +33,12 @@ cd p3-stack
 
 ## Skills
 
-architect, arena, automate-me, benchmark-checklist, blast-radius, bro, correct, create-verification-skill, figure-it-out, how, interrogate, ketchup, maintain-verification-skill, make-bot-ui, no-comments, p3-help, recall, reflect, setup-p3, sharpen, show-me-your-work, swarm, tdd, teach, technical-writing, typescript-best-practices, unslop, why.
+architect, arena, automate-me, benchmark-checklist, blast-radius, bro, correct, create-verification-skill, figure-it-out, how, interrogate, ketchup, ketchup-video, maintain-verification-skill, make-bot-ui, no-comments, p3-help, recall, reflect, setup-p3, sharpen, show-me-your-work, statechart, swarm, tdd, teach, technical-writing, typescript-best-practices, unslop, why.
 
 ## Principles
 
 The twenty-four principle skills are indexed inside `p3-mode` and referenced by the other skills by name.
 
 ## Credit
 
-p3-stack adapts [pstack](https://github.com/cursor/plugins/tree/main/pstack) by [poteto](https://x.com/poteto). The skills, principles, and language are hers; the T3 Code rewiring is this repo's, started by Uzair Ansar. Synced with upstream [cursor/plugins](https://github.com/cursor/plugins) pstack at [`88d4751`](https://github.com/cursor/plugins/tree/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack) (0.15.29) by Lauren Tan (poteto). MIT, see [LICENSE](LICENSE) and [NOTICE](NOTICE). Changes per sync are in [CHANGELOG.md](CHANGELOG.md).
+p3-stack adapts [pstack](https://github.com/cursor/plugins/tree/main/pstack) by [poteto](https://x.com/poteto). The skills, principles, and language are hers; the T3 Code rewiring is this repo's, started by Uzair Ansar. Synced with upstream [cursor/plugins](https://github.com/cursor/plugins) pstack at [`9580c23`](https://github.com/cursor/plugins/tree/9580c23696ac8d7abed0c166f2f9918800afb819/pstack) (0.15.32) by Lauren Tan (poteto). MIT, see [LICENSE](LICENSE) and [NOTICE](NOTICE). Changes per sync are in [CHANGELOG.md](CHANGELOG.md).

skills/ketchup-video/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: ketchup-video
+description: "Catch the user up like /ketchup, with a short silent video of slides for what happened and the waiting calls as text under it. Use for /ketchup-video."
+disable-model-invocation: true
+---
+
+# Ketchup video
+
+Follow [`/ketchup`](../ketchup/SKILL.md), but show what happened in a short silent video instead of its summary and visuals. Its window starts at the last message the user wrote before `/ketchup-video`, not before any earlier `/ketchup`. Writing and rendering the video, outside the repo, is the one exception to its read-only rule. The reply is ketchup's opening sentence, the video embedded in the thread by its absolute path, one line naming any work left that you can do yourself, and the action items. When the video shows a call's options, call each option by the name the video gives it. If the render fails, say so in one line and give only the calls.
+
+## Slides
+
+Use the screenshots, recordings, diffs, and data the work produced, not the thread's prose about them. Before you draw, write the one sentence the user should leave with and one line per slide. Drop each slide that does not change what the user knows. Use at most 10 slides, and fewer is better. Neither note goes in the reply.
+
+Each slide makes one point. Build the slides on one picture and change it from slide to slide, rather than cut to an unrelated one. A color or shape means the same thing on every slide. Show the work in pictures, such as how a system works, a PR stack with each PR's state, a before and after of a fix, or options side by side. Point at what changed with arrows, highlights, and motion. A slide is never a bullet list, a status list, a table, or boxes with nothing connecting them.
+
+Keep text to the minimum. Put each label on the thing it names, in plain words a person would say, not tags like "Tests: pass". Never caption what a picture shows, and never give a fact twice, across slides or in the text under them.
+
+Show what came of each thing the user asked for, and whether it is done, still running, failed, or not checked. Never show something done that still waits on the user. Show any bug found and fixed on the way. If a visible change has no screenshot, say so on its slide and name what changed on screen. Draw only from facts you have. Never invent a number, and never draw a screen you did not capture.
+
+## Render
+
+Render one silent landscape video, such as an mp4, with motion between slides. Every frame is the slide itself, edge to edge. Make the frames from the slides, never by recording a screen. Hold each slide long enough to read its words, at least one second for each three words it adds. Words inside a screenshot do not count. Before you embed the video, look at one frame from each slide in the rendered file, and count the words it adds against its hold in that file. Fix any slide you cannot read in that time, render again, and check again.

skills/p3-help/SKILL.md

@@ -46,6 +46,7 @@ The default answer is `/p3-mode`, which runs most of the others when its steps n
 | Understand a change or subsystem, explained plainly | [`/teach`](../teach/SKILL.md) |
 | Catch up on their own recent work on a topic | [`/recall`](../recall/SKILL.md) |
 | Catch up on what changed in this thread since their last message, in plain words and small visuals, with every item waiting on them listed and decidable from the reply alone | [`/ketchup`](../ketchup/SKILL.md) |
+| Catch up like `/ketchup`, in a short silent video of slides, with the waiting calls as text under it | [`/ketchup-video`](../ketchup-video/SKILL.md) |
 | Know what a small diff could break outside itself | [`/blast-radius`](../blast-radius/SKILL.md) |
 | Settle types and module shape before code that crosses a function boundary | [`/architect`](../architect/SKILL.md) |
 | Get several attempts at one brief, merged into the best one | [`/arena`](../arena/SKILL.md) |
@@ -59,6 +60,7 @@ The default answer is `/p3-mode`, which runs most of the others when its steps n
 | Hear the last reply again in plain words | [`/bro`](../bro/SKILL.md) |
 | Give agents a scripted way to drive the app and prove behavior | [`/create-verification-skill`](../create-verification-skill/SKILL.md) |
 | Bring a verification skill and its feature map back in line with the app | [`/maintain-verification-skill`](../maintain-verification-skill/SKILL.md) |
+| Show a PM or designer what the user sees as a chart checked by a model, with each bug drawn as a numbered path, turn an agreed chart into a TLA+ skeleton, or audit the code against its TLA+ spec | [`/statechart`](../statechart/SKILL.md) |
 | Vet a performance number before reporting or acting on it | [`/benchmark-checklist`](../benchmark-checklist/SKILL.md) |
 | Run a large or cross-cutting change, or one to review after stepping away | [`/figure-it-out`](../figure-it-out/SKILL.md) |
 | Keep a decision log during a run, and review it afterward | [`/show-me-your-work`](../show-me-your-work/SKILL.md) |

skills/reflect/SKILL.md

@@ -48,6 +48,8 @@ Before applying any Accepted edit, present the synthesizer's full Accepted/Rejec
 
 Backlog items file to whatever devex / backlog tracker your team uses automatically. Only the Accepted list waits for approval.
 
+Never edit a skill through its symlink into the p3-stack checkout. `install.sh` links each skill there, so an edit lands in the checkout and blocks the next pull. Before approval, show its destination, `.agents/skills/<skill>/` or `~/.agents/skills/<skill>/`. After approval, replace the symlink with a copy of the skill folder and edit the copy. `install.sh` skips a folder that is not a symlink, so the copy survives reinstalls. Never open a PR or push.
+
 For each approved Accepted item, follow the Routing field exactly:
 
 - Trivial existing-skill edit (a one-line bullet, a tightened sentence, a stale fact corrected): parent does directly.

skills/statechart/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: statechart
+description: "Draw how any system moves between states, such as a product flow, a protocol, or a service, as a Mermaid statechart from a TLA+ model. Each bug is a numbered path with blue borders to a state that breaks a rule. Use for /statechart, to show a bug as a path through states, or to turn an agreed chart into a TLA+ skeleton."
+disable-model-invocation: true
+---
+
+# Statechart
+
+The chart shows how a system moves between states, in the words of the person who reads it. The scripts call that person the reader, as in `readerActions` and reader steps. The reader decides whether the behavior is right. The reader can be a PM who reads a product flow, an engineer who reads a protocol or a service, or a reviewer who reads a design. Label each state with what the reader can observe or cares about, such as "Paying" in an app or "Lease held, write pending" in a lock service. Label each step with the event that moves the system, such as "tap Pay" in an app, "the request reads the count" in a service, or "the lease expires" in a lock service. Keep variable and action names out of labels.
+
+Run `node <skill dir>/scripts/statechart.mjs --help` for the commands and for how to read a chart. Work in a scratch folder outside the repo. The command writes its files next to its input. The first run installs TLC and Java with mise, which downloads about 305 MB and needs the network. The help's TLC section tells how to use a TLC and Java that you have.
+
+## Pick the direction
+
+Use `from-spec` when a TLA+ model exists, or when the code or design is concrete enough to model. Use `from-chart` when there is no model, and the people who own the behavior should agree on it before anyone builds or changes it.
+
+If the code already has a TLA+ spec, start from a copy of that spec. Add the variables that the labels and rules need, and keep the spec's existing invariants. To audit the code against that spec, make the copy model what the code does, and pass the spec unchanged as `--against`. Check it with the config that its authors say it passes, and pass that config as `--against-config` unless it has the spec's file name. One mapping labels both models, so label states and steps from variables that both have. A label that reads a variable that only the copy has must test `"name" in v` first, and label the spec's states another way. When a model describes code, tie every variable and action to code that a reviewer can open, and take its name from that code. Make each action one indivisible step in the code. Put the file and line of the code that checks each condition of an action in a comment on that condition, as in `\* pay.ts:120`.
+
+## Spec to chart
+
+1. Choose the chart's states. When the reader cares about something that a label would hide, put it in the label, such as "Paying, charged twice" when the screen still says "Paying" after a second charge. Start with few states. Split a state when the split separates two bugs, or when the reader must see a step that leaves the label the same, such as a request that reads a count, because the chart does not draw such a step.
+2. Write each rule that the reader agrees to as one invariant, with the reader's sentence as its comment. A rule can be about any state in the model: what a screen shows, what a request returns, a stored value, or a message between parts. When the model describes code, the rule also names the code that can change that state. If the model has no variable for what a rule is about, add the variable. Do not drop the rule. For a rule that applies once everything settles, define `Settled == ~ENABLED System`, where `System` is the disjunction of the actions that happen without the reader. For a rule that applies at a narrower point, such as after each request finishes, write a predicate for that point and make the rule hold where it is true. For a goal that the system must be able to reach, write a rule that says the goal never happens, and pass that rule with `--expect-broken`. The path that breaks it is then a way to the goal. The chart still draws the goal as a state that breaks a rule, and `stories.md` tells it as a bug, so name each goal rule in the hand-off. Report each other broken rule as a bug. Never weaken a rule to make the chart pass.
+3. Run `from-spec`, then fill in the mapping file it writes. Put the labels in `state` and `step`. When the chart must separate what the reader does from what happens around the reader, list the reader's actions in `readerActions` by action name. Leave the list empty when every action counts the same. When the overview is too large to read, add `--cover`. The overview then keeps only the shortest path to each settled state, plus every bug path, and the command lists what it leaves out. When two bugs end in the same state for different reasons, add `cause` and make it name each reason. To color the states by what the reader cares about, such as "Order shipped", return that group from `group`. The legend names the groups, and in the PNG a state that breaks a rule is red in place of its group color.
+4. If there is a proposed fix, model it and pass that model as `--fixed`.
+5. Render each chart with `--png` and look at every PNG. Check that each numbered path reads in order. If a label reads like code, fix `state` or `step` and run the command again.
+6. When the model describes code, replay each bug's story against the real code, as a test or a live repro, one step per model action. Drive only entry points that a user, a client, or another part of the system reaches, and assert only what they can observe. A test that asserts a flag that it sets, or that searches the source text, proves nothing. When a run proves part of the story and reading the code proves the rest, say which part each proves. When the test copies code that it cannot import, give the commit and line range of the copy, and list what the copy leaves out. If a bug does not reproduce, assume the model is wrong until you show otherwise. Fix the model, not the rule. For a design with no code yet, the TLC trace is the evidence, and the hand-off must say so.
+
+## Chart to spec
+
+1. Draw the chart that the reader agrees to. Use one region for each part that changes independently, such as a device's connection and the job that the device runs. Add one `%% never` line per rule, with the reader's sentence. Draw an event that stops or restarts a part, such as "the app closes" or "the process restarts", as an edge to the state that comes next. Run `render CHART.mmd` to get a PNG of the chart for the reader.
+2. Run `from-chart`. If a rule breaks, the agreed chart has a design bug. Take the bug to the people who agreed to the chart.
+3. Add the real code's guards and variables to the spec that `from-chart` wrote, and run `from-chart` again. For each difference it prints, ask the reader whether the code is wrong or the chart needs a correction.
+
+## Hand off
+
+Give the PNG and the Mermaid source of each chart to the person who must decide. Add one line per bug with the rule it breaks, its steps as the chart numbers them, whether it reproduced, and whether the proposed fix fixes it. A broken PROPERTY has no path on the chart, so give the TLC counterexample that `stories.md` names for it. With `--against`, also say whether the spec already lists it: in the configs that `stories.md` names, in the spec's notes on what the model leaves out, or not at all. When the model describes code, do not report that a rule holds while the command lists conditions with no file and line. Take every count you quote from `summary.json`. Attach `stories.md` and the command that regenerates everything. Say what the model leaves out.