Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"name": "pstack",
"source": "./plugins/pstack",
"description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.",
"version": "1.16.0-adam.20261101",
"version": "1.16.0-adam.20261102",
"author": {
"name": "Lauren Tan (original)"
},
Expand Down
7 changes: 5 additions & 2 deletions .claude/skills/verify-open-pstack/features/registry.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
"principle-redesign-from-first-principles", "principle-separate-before-serializing-shared-state",
"principle-sequence-verifiable-units", "principle-subtract-before-you-add",
"principle-test-behavior-not-implementation", "principle-type-system-discipline",
"recall", "reflect", "setup-pstack", "sharpen", "show-me-your-work", "statechart", "swarm", "tdd", "teach",
"recall", "reflect", "setup-pstack", "sharpen", "show-me-your-work", "statechart", "statechart-diagram", "swarm", "tdd", "teach",
"technical-writing", "thermo-nuclear-code-quality-review", "typescript-best-practices",
"unslop", "what-did-i-get-done", "why"
],
Expand Down Expand Up @@ -70,14 +70,17 @@
"plugins/pstack/skills/poteto-mode/scripts/bun.lock",
"plugins/pstack/skills/poteto-mode/scripts/check-plan.tsconfig.json",
"plugins/pstack/skills/show-me-your-work/scripts/log.sh",
"plugins/pstack/skills/statechart/scripts/**"
"plugins/pstack/skills/statechart/scripts/**",
"plugins/pstack/skills/statechart-diagram/scripts/**",
"plugins/pstack/skills/statechart-diagram/hooks/**"
],
"project": [
".claude/skills/verify-open-pstack/**", ".agents/skills/verify-open-pstack",
"AGENTS.md", "CLAUDE.md", "tests/skill-collision-repro.sh", ".github/workflows/ci.yml", "package.json",
".github/workflows/windows-hooks.yml"
],
"nonRuntime": [
"plugins/pstack/skills/statechart-diagram/assets/**", "plugins/pstack/skills/statechart-diagram/evals/**",
"README.md", "REVIEW.md", "CHANGES.md", "LICENSE", "LICENSE.md", "UPSTREAM.md", "FORK.md", "TEAM-INSTALL.md",
"NOTICE.md", "README-UPSTREAM.md", "LICENSE-cursor-team-kit", "LICENSE-superpowers",
".gitignore", ".mergify.yml", "docs/**", "assets/**",
Expand Down
8 changes: 8 additions & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,14 @@
Mergify auto-queue is live: ready PRs to main require passing verify, Unfret and exact-head live-gate, and no unresolved review thread; workflow changes require operator queueing.
This port applies the Cursor → Claude Code substitutions in skill bodies. Earlier drafts left them flagged; this revision resolves them. A later pass added a Codex build that shares the same skills; see [Codex port](#codex-port) below.

## 1.16.0-adam.20261102 adds /statechart-diagram

**New skill.** `/statechart-diagram` draws the `chart.mmd` and `report.md` that `/statechart` writes as a square plate in pen and coloured pencil on paper, after Kevin Ngo's statechart-art: Pele lays the chart out in a hand font, `scripts/plate.mjs` draws it with `@napi-rs/canvas` (no browser), objects from the reader's world sit beside the states they belong to, TLC's marks are drawn as red cards, red paths and a "rule broken" stamp, and the small line under the title reports what TLC checked. It runs on Node 20 or later and installs Pele, the canvas and two Open Font License fonts with `npm install` in its `scripts/` on first use. The skill is model-invocable; `/statechart` stays typed only.

**New hook.** `PostToolUse` on Bash runs `hooks/after-statechart` through the existing `run-hook.cmd` wrapper. The script reads the tool call, and when the `/statechart` runner has just written a `chart.mmd`, it adds one note to the model's context asking for the plate; on every other command it is silent and exits in a few milliseconds, and without Node it exits 0. `/statechart`'s hand-off asks for the plate as well, so the chain also holds where hooks do not run.

**Listings.** `README.md`, `docs/reference.md`, `poteto-help` and the verifier's skill registry name the new skill.

## 1.16.0-adam.20261101 syncs to Cursor pstack 0.15.36

Adam's fork at `1.16.0-adam.20261101` merges released Open Pstack 1.16.0 and layers Lauren Tan's pstack skill changes from 0.15.30 to 0.15.36 (`ae5650f`) on top. The fork's front-door gate, cloud installer, verifier additions and model sheet stay. See `FORK.md` for the patch table and `UPSTREAM.md` for every exclusion.
Expand Down
1 change: 1 addition & 0 deletions FORK.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ This fork is the pinned source for the pstack plugin on Adam Vellequette's Claud
| 4 | `scripts/front-door.py`, `plugins/pstack/.front-door.json`, every `SKILL.md`, `skills/*/agents/openai.yaml` | `front-door.py passive` makes every skill explicit-only (Claude Code: `disable-model-invocation: true`; Codex: `allow_implicit_invocation: false`) and adds a read-by-path note to the router. `front-door.py active` restores the port byte for byte. The release branch shipped passive until the front-door switch on 2026-10-05; it is active since (the commit that made it so says so). | Installed skills must not steer running lanes before the front door switches. The safety review (2026-10-04) found the port lets every skill start on its own. |
| 6 | `plugins/pstack/skills/poteto-mode/scripts/orch/` (`orch.ts`, `store.ts`, `orch.test.ts`), `scripts/package.json` | Kept after Cursor pstack 0.15.36 deleted them with the agentic Orchestrate playbook; the test list keeps `orch`. | The harness's `chief-of-staff` skill runs its program against this store CLI (`PSTACK_ORCH`). The playbook text no longer names it. Dropping the files is Adam's call, after the chief-of-staff runtime moves off them. |
| 5 | `scripts/cloud-setup.sh`, `tests/cloud-setup-test.sh` | New files. The script installs the kit into a Claude Code cloud session as the personal skills-directory plugin `pstack@skills-dir`. | A cloud session loads no plugin from the Mac or from a repo's settings. See "Cloud sessions" below. |
| 8 | `plugins/pstack/skills/statechart-diagram/`, `plugins/pstack/hooks/after-statechart`, `plugins/pstack/hooks/hooks.json`, `plugins/pstack/skills/statechart/SKILL.md` | New skill and hook. `/statechart-diagram` draws a `/statechart` chart as a hand-drawn plate; the `PostToolUse` hook asks for it once the statechart runner has written `chart.mmd`, and `/statechart`'s hand-off asks for it too. | A chart the owner keeps is a drawing, not Mermaid text; the chain runs without anyone remembering to ask (decided 2026-11-02). |
| 7 | `.claude/skills/verify-open-pstack/` | `REPO` is this fork. `features/formal.ts` holds the recipes for the two formal verification skills, `skill-invocation:poteto-mode` runs a route-only case, a skill's `agents/openai.yaml` selects its Codex invocation surface, and `FORK.md`, `TEAM-INSTALL.md`, the operator scripts and the cloud-setup test are non-runtime paths. With `--account-router` and `--native-model`, `scripts/routing.ts` runs each native session through the harness account router and its `pstack-verify-run` launcher and checks the admission and completion receipts; `harness.ts` and `io.ts` carry the auth-link cleanup and cancellation handling that go with it. Dependency: `~/.agents/harness/scripts/account-router` and `pstack-verify-run`. The two formal cases run Claude with `bypassPermissions` inside their fixture, as the port's setup cases do, because Claude Code 2.1.316 refuses a `Write` under any `.claude/skills/` folder in `dontAsk` mode; a routed Claude run therefore cannot select them, while a routed Codex run can. | The verifier publishes live-gate evidence only to this fork and must exercise the surfaces the fork ships. |

Last upstream sync: port release `v1.16.0`, merged 2026-11-01, with Cursor pstack 0.15.30 to 0.15.36 layered on top (the November 1, 2026 update below). Patch 3 (the two router index lines) is retired: upstream's router names both skills.
Expand Down
1 change: 1 addition & 0 deletions NOTICE.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ Files authored for this port (not derived from upstream):
- `plugins/pstack/skills/babysit/SKILL.md` (independently authored; workflow informed by Cursor's public `/babysit` behavior)
- `plugins/pstack/agents/pstack-<family>-<effort>.md` for the Fable, Opus, Sonnet, Opus 5.5 and Haiku 5.5 families (Claude-native lanes at each selectable effort)
- `plugins/pstack/hooks/hooks.json`, `plugins/pstack/hooks/session-start`, `plugins/pstack/hooks/session-start-context.md`, and `plugins/pstack/hooks/.gitattributes` (the auto-fire hook, its mandate, and LF checkout on Windows)
- `plugins/pstack/skills/statechart-diagram/` (fork addition: draws a `/statechart` chart as a plate in pen and coloured pencil; an independent re-implementation of the technique in Kevin Ngo's statechart-art, MIT; its `scripts/` install Pele (MIT), `@napi-rs/canvas` (MIT) and the Caveat and Patrick Hand fonts (SIL Open Font License) from npm on first use) and `plugins/pstack/hooks/after-statechart` (the hook that asks for the plate once `/statechart` has written a chart)
- `NOTICE.md` (this file)
- `README.md`
- `REVIEW.md` (the review panel's usage and waiver-scope mandate, #153; adapted from mastra-pilot's `REVIEW.md`, not from upstream)
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,7 @@ That is the main workflow. The other skills are there when poteto-mode needs the
| `sharpen` | You want a prompt rewritten deeper, not bigger, before you send it. It returns the rewritten prompt and does not do the task. |
| `ketchup-video` | You want the `/ketchup` catch-up as a short subtitled video of slides, with the calls waiting on you as text under it. |
| `statechart` | Someone who owns the behavior needs to see it as a chart checked by a TLA+ model, with the shortest path to each state that breaks a rule. |
| `statechart-diagram` | A `/statechart` chart should become a hand-drawn plate in pen and coloured pencil that a client or a team will keep. It runs by itself after `/statechart` writes a chart. |

Plugin skills include `pstack:` in their name. In Claude Code, invoke a native skill such as `/pstack:architect`. In Codex, ask for the skill, such as `Use pstack:architect for this design.` See the [technical reference](docs/reference.md) for the full list.

Expand Down
4 changes: 3 additions & 1 deletion UPSTREAM.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ open-pstack tracks [Cursor's pstack](https://github.com/cursor/plugins/tree/main
| Path | `pstack/` |
| Commit | `ae5650febf4320793844c12c4adaa937f417f8da` |
| Upstream version | `0.15.36` |
| open-pstack version | `1.16.0-adam.20261101` |
| open-pstack version | `1.16.0-adam.20261102` |

The table above is the current Cursor sync point. Open Pstack 1.16.0 imported the 0.15.29 sync at `88d47514b82e7c44f00f2b2a72ff6dd12158038c`; Adam's fork (`FORK.md`) layers the skill changes from 0.15.30 to 0.15.36 on top of it. `README-UPSTREAM.md` preserves the upstream pstack README verbatim. `CHANGES.md` and `NOTICE.md` describe the adaptations and provenance.

Expand Down Expand Up @@ -49,6 +49,8 @@ The table above is the current Cursor sync point. Open Pstack 1.16.0 imported th

## Local port-patch ledger

- **statechart hand-off draws the plate**: Cursor's `statechart` ends its Hand off with the chart, the bug lines and the rerun command. The fork adds one more sentence: invoke `statechart-diagram` on the output folder, once, because the plugin's `after-statechart` hook asks for the same. `statechart-diagram` and the hook are fork additions, not upstream content.

- **#235 — Claude transcript folder encoding**: the port wrote Claude Code's per-project transcript path into `recall`, `automate-me` and the `session-pickup` playbook. Claude Code encodes each `/` and each `.` in the workspace path as `-`, so a `.claude/worktrees/` session's folder holds `--claude-worktrees-`. Keep both characters in those three lines during syncs.
- **#140 — Reflect transcript resolution**: Cursor's Reflect step 1 reads the `agent-transcripts/` directory its system prompt names; the port had substituted Claude Code's per-project directory, which left Codex without a lookup. The port replaces that step's body with one line that points to `plugins/pstack/skills/poteto-mode/references/codex-tools.md#active-transcripts`, and leaves the rest of `reflect/SKILL.md` unchanged. That mapping section holds the harness specifics: the Claude per-project scope, layouts, candidate and scan limits, opening-message verification, the Codex resolver call, and the 2,000-word digest fallback. The port-authored Bun resolver `plugins/pstack/skills/poteto-mode/scripts/resolve-codex-transcript.ts`, started through the `sh` launcher `resolve-codex-transcript` next to it so project Bun config and `.env` files cannot affect it, looks up the parent's known chat ID in Codex's read-only `threads` index, checks rollout scope and ownership, and prints opening-message metadata without transcript text. Preserve this divergence during upstream syncs: keep step 1 as the one-line pointer and keep the mapping section and resolver.
- **#120 — harness config homes** (tracked for #105): Cursor's setup destination is `~/.cursor/rules/`. The shared port resolves nonempty `CLAUDE_CONFIG_DIR` / `CODEX_HOME`, otherwise `$HOME/.claude` / `$HOME/.codex`, once at `plugins/pstack/skills/poteto-mode/references/codex-tools.md#harness-config-homes`. `setup-pstack/SKILL.md` reuses that home for reads, sheet/integration writes, snapshots, restoration, and readback; Claude preserves the literal legacy import at the default home and renders exactly `@./pstack-models.md` for redirected homes, keeping spaces and `#` in the config-directory name out of the import line; reruns replace the one import whose target basename is `pstack-models.md`, append if absent, and stop if duplicated. Preserve this intentional divergence during upstream syncs. The named config-home invariant in `tests/skill-collision-repro.sh` rejects literal default destinations outside the legacy import, requires the literal default-home rendering and zero/one/many import rules, and verifies unset/empty/space-containing resolution without daily writes. See `CHANGES.md` for the port correction and `tests/setup-config-home-repro.sh` for redirected live-evidence preparation. The Cursor sync point is unchanged.
Expand Down
1 change: 1 addition & 0 deletions docs/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,7 @@ The table uses the short upstream names. Claude Code exposes each native skill w
| `/ketchup` | catch up on everything in this session since your last message (typed only) |
| `/ketchup-video` | the same catch-up as a short subtitled video of slides, with the waiting calls as text under it (typed only) |
| `/statechart` | check a TLA+ model and draw it as a Mermaid statechart, with the shortest path to each state that breaks a rule (typed only) |
| `/statechart-diagram` | draw a `/statechart` chart as a hand-drawn plate in pen and coloured pencil; called by the `after-statechart` hook once `/statechart` writes a chart |
| `/poteto-help` | find the skill, playbook, or principle for a question about pstack (typed only) |
| `/in-your-own-words` | play back your goal and the problem before work starts (typed only) |
| `/sharpen` | rewrite a prompt deeper, not bigger, before you send it; returns the rewritten prompt and does not do the task (typed only) |
Expand Down
2 changes: 1 addition & 1 deletion plugins/pstack/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "pstack",
"displayName": "pstack",
"version": "1.16.0-adam.20261101",
"version": "1.16.0-adam.20261102",
"description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence. Ported from cursor/plugins/pstack for Claude Code and Codex.",
"author": {
"name": "Lauren Tan"
Expand Down
2 changes: 1 addition & 1 deletion plugins/pstack/.codex-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "pstack",
"version": "1.16.0-adam.20261101",
"version": "1.16.0-adam.20261102",
"description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence. Codex port of the Claude Code plugin; skills are shared, tool names resolve via skills/poteto-mode/references/codex-tools.md.",
"author": {
"name": "Lauren Tan"
Expand Down
12 changes: 12 additions & 0 deletions plugins/pstack/hooks/after-statechart
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
#!/usr/bin/env bash
# Runs the statechart-diagram hand-off check after a Bash tool call. The check is a Node script; without
# Node the hook has nothing to say and exits 0, so the plugin still works where only bash is installed.
set -euo pipefail

case "$0" in
*/*|*\\*) dir="${0%[/\\]*}" ;;
*) dir=. ;;
esac
node_bin="$(command -v node 2>/dev/null || true)"
[ -n "$node_bin" ] || exit 0
exec "$node_bin" "$dir/../skills/statechart-diagram/hooks/after-statechart.mjs"
14 changes: 14 additions & 0 deletions plugins/pstack/hooks/hooks.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,20 @@
}
]
}
],
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" after-statechart",
"commandWindows": "C:\\Windows\\System32\\cmd.exe /d /v:on /s /c \"\"!PLUGIN_ROOT!\\hooks\\run-hook.cmd\" after-statechart\"",
"timeout": 10,
"statusMessage": "Checking whether /statechart wrote a chart"
}
]
}
]
}
}
1 change: 1 addition & 0 deletions plugins/pstack/skills/poteto-help/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,7 @@ The default answer is `/poteto-mode`, which runs most of the others when its ste
| Formally verify a race, invariant, or other property that tests rarely reach | [`/create-formal-verification-skill`](../create-formal-verification-skill/SKILL.md) |
| Bring a formal verification back in line after the code it covers changed, and learn whether a failure is drift or a bug | [`/maintain-formal-verification-skill`](../maintain-formal-verification-skill/SKILL.md) |
| Show a PM or designer what the user sees as a chart checked by a TLA+ model, with the shortest path to each state that breaks a rule | [`/statechart`](../statechart/SKILL.md) |
| Turn a `/statechart` chart into a hand-drawn plate in pen and coloured pencil, with the reader's world around it, for a client, a post or a deck | [`/statechart-diagram`](../statechart-diagram/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) |
Expand Down
Loading
Loading