Skip to content
Open
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 @@ -10,7 +10,7 @@
"name": "t3-pstack",
"source": "./plugins/pstack",
"description": "pstack for T3 Code: rigorous agent workflows whose panels and fan-outs run across model families through T3. Original pstack by Lauren Tan (poteto).",
"version": "2.2.8"
"version": "2.3.0"
}
]
}
50 changes: 50 additions & 0 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,56 @@

This file is the release changelog, with one `## <version> - <title>` entry per release, newest first. The Cursor-to-T3 rewrite rules live in [`tools/substitutions.json`](tools/substitutions.json), and the [sync boundary](CONTRIBUTING.md#the-sync-boundary) in `CONTRIBUTING.md` defines how a change to upstream's skill content is declared.

## 2.3.0 - Lauren's `bf0c7cd`: why and how are one file each, and the defaults move to Fable 5.2, Opus 5.5, and Gemini 4 Carbon

t3-pstack moves to Lauren Tan's pstack at cursor/plugins `bf0c7cd` ([pstack #1236](https://github.com/cursor/plugins/pull/1236)) for all three components, and pstack's version moves from 0.15.36 to 0.15.42. Only pstack changed upstream. cursor-team-kit and thermos have no change between `c742dd6` and `bf0c7cd`, and their pins move with pstack's.

**What changed upstream.**

- `why` is one short file. It answers from the record, the commits and PR discussions that introduced the target and each later change, and other sources when that trail is thin. It cites what the authors wrote, marks its own inferences, and says what the record does not answer. Its investigators, synthesizer, evidence categories, and all twelve files under `references/` are gone, and so are the `why investigators` and `why synthesizer` roles.
- `how` is one file with one read-only subagent that explores and explains in one pass. Its explorer and explainer prompts are gone, and so are the `how explorer` and `how explainer` roles. poteto-mode no longer routes a nontrivial change to `how`. The Feature, Bug fix, Perf issue, Hillclimb, Refactoring, and Investigation playbooks, `architect`, `no-comments`, and Comment Sicko trace the code themselves. `recall` starts its own investigator per source instead of borrowing `why`'s, and `teach` drops `why`'s narrowing advice.
- New default models. `hardest tasks` runs on Fable 5.2 at max. `feature, refactoring`, `bug-fix`, `perf-issue`, and `hillclimb` run on Opus 5.5 at xhigh. `swarm workers`, `reflect tooling`, and verification run on Opus 5.5 at high in fast mode. Each panel (`arena runners`, `arena cross-judge pool`, `architect runners`, `interrogate reviewers`) runs one entry each on Fable 5.2 at high, Opus 5.5 at high in fast mode, and Gemini 4 Carbon at high. Grok 4.7 is no longer a default. Fable is its own family, apart from the other Claude models, and arena's cross-judge comes from another vendor, where Fable and the other Claude models are one vendor.
- setup-pstack's budget now moves each role's own default effort, so `large` keeps it, `unlimited` raises it a step, and `medium` and `small` lower it one and two steps. It writes a `# defaults: 2` line, and on a sheet without one it replaces the values an older setup wrote as defaults. poteto-mode keeps honoring a sheet without that line and tells the user once per session to rerun `/setup-pstack`.
- `sharpen`'s rewritten prompt asks the agent to prototype any choice an experiment can settle and to recommend an option from what it observed. Product and preference calls stay with the user. reflect's synthesizer swaps a model-rename example for a function rename.
- `statechart` reports SANY's own error section, with line and column, when SANY cannot read a spec, instead of a Java stack trace. A Mermaid arrow from outside a parent state ends at the parent's border, and the parent's start marker carries on to the state inside. New tests cover both.

**What the port adapted, and why.**

The defaults in `plugins/pstack/models.json` map Lauren's to T3 entries that `orchestrator_capabilities` lists on this Mac, on janus, and on agents-fsn1:

| Tier | Roles | 2.2.8 | 2.3.0 |
| --- | --- | --- | --- |
| `default` | `feature, refactoring`, `bug-fix`, `perf-issue`, `hillclimb`, `judgment and prose`, `reflect judgment, divergent, synthesizer` | `claudeAgent/claude-opus-5-5 effort=xhigh`, with `bug-fix`, `perf-issue`, and `hillclimb` on `strongest` | `claudeAgent/claude-opus-5-5 effort=xhigh` |
| `strongest` | `hardest tasks` | `claudeAgent/claude-fable-5-1 effort=xhigh` | `claudeAgent/claude-fable-5-2 effort=max` |
| `fast` (new) | `swarm workers`, `reflect tooling` | on `default` | `claudeAgent/claude-opus-5-5 effort=high fastMode=true` |
| `panel` | the four panel roles | Opus 5.5, `codex/gpt-6.1-sol`, and `grok/grok-4.7`, each at xhigh | `claudeAgent/claude-fable-5-2 effort=high`, `claudeAgent/claude-opus-5-5 effort=high fastMode=true`, `antigravity/gemini-4-carbon thinking_level=high` |

Gemini 4 Carbon is reachable. All three machines list `antigravity/gemini-4-carbon`, Google's own driver, with `thinking_level` at low, medium, or high and no speed option. A Codex pool on each machine also routes a `gemini-4-carbon-high`, but a plain Codex instance lists no Gemini model. A `delegate_task` to `antigravity/gemini-4-carbon thinking_level=high` returned `completed` with the summary `OK`. On `claudeAgent`, Fable 5.2 lists `effort` up to max and no `fastMode`, and Opus 5.5 lists `fastMode`.

- **Fable is its own family.** T3's family rule, the first segment of a model ID's last `/` part, now has Lauren's exception: a `claude-fable-*` model's family is `claude-fable`. `t3-sheet.mjs`'s `family()` and the rule's text in poteto-mode, arena, and setup-pstack say so. A panel of Fable and Opus counts as two families, as Lauren's does, so the default panel spans three families and two vendors. A rejected Fable entry falls back to another Fable target, not to Opus. Lauren's vendor rule for the cross-judge is adopted as written, and the port's rule that the judge first tries a model that ran fewer candidates now reads "vendor".
- **Retired roles are harmless.** Every sheet setup-pstack wrote in 2.x has the four `how` and `why` lines, as the sheets on all three machines do. With the roles gone from `models.json`, the sheet checker printed `"how explorer" is not a pstack role` and three more lines for the Mac sheet, so `doctor` would have failed "machine sheet valid" on every machine. `models.json` now lists those labels under `retired`, and `t3-sheet.mjs`, setup-pstack's check, and `doctor` pass a retired line unchecked. setup-pstack drops those lines on its next run, as Lauren's step 2 now says by naming them.
- **The defaults marker is adopted.** setup-pstack's sheet block, stamped from `models.json`, now carries `# defaults: 2`, and the checker already skips `#` lines. Lauren's migration matches Cursor slugs (`grok-*`, `claude-opus-*`) that no T3 sheet ever held, so its T3 form matches the defaults every 2.x setup wrote, since `models.json` did not change between 2.0.0-rc.1 and 2.2.8. It replaces `claudeAgent/claude-fable-5-1` in `bug-fix`, `perf-issue`, `hillclimb`, or `hardest tasks`, `claudeAgent/claude-opus-5-5` in `reflect tooling` or `swarm workers`, and a panel list of exactly Opus 5.5, GPT-6.1 Sol, and Grok 4.7, each with any options. A Grok entry in any other list stays, because Grok was a T3 default only inside that three-entry panel. On the three machines' sheets, the only value it replaces is janus's `strongest judgment: claudeAgent/claude-fable-5-1 effort=xhigh`.
- **A research delegate runs on the parent model.** Dispatch on T3 said a research delegate no role names runs on the `how explorer` entry. It now omits `target`, as Lauren's `how` and `recall` Task calls name no model. `how`'s one child is a `delegate_task` child with `role: "research"` and no `target`, and `recall`'s investigators are children with full tool access, since they need MCP.
- **Substitutions.** Six rules that anchored on the deleted `why` text, or on sentences upstream dropped, are deleted. Seven are re-anchored to upstream's new sentences: poteto-help's harness note, the verification default, the code default, `how`'s spawn, arena's judge order, the playbooks' `swarm workers` default, and arena's family sentence. Ten are new. They cover the `swarm workers` and panel defaults in poteto-mode, its defaults-marker sentence, the Gemini and Fable reasoning limits, `recall`'s investigators, and five rules that give setup-pstack's upstream text its T3 form. Two of those five name the sheet step and open its fence, so the generator stamps the sheet block over Lauren's rule, and the fork's changed lines drop from 81 to 34. Two replacements change. The reasoning-option list adds `thinking_level` on Antigravity, and Dispatch on T3 takes the two changes above.
- **The forks.** Before the sync, the four non-forked files whose rules changed took the new rules' output at `c742dd6`, as in 2.2.0, so each synced as a clean update. The poteto-mode and setup-pstack forks took the same change through a three-way merge of the old and new rules' output at `c742dd6`. Without it, poteto-mode's merge would have kept the old `how explorer` sentence with no conflict, because the base and upstream sides agreed there. setup-pstack had three conflicts, resolved by keeping its T3 sheet text and taking Lauren's retired-role examples, the relative budget, Fable as a family, the vendor rule, and the defaults migration in its T3 form. Every other fork changes as many lines as at `c742dd6`.

Rerunning setup-pstack on `large` now sets each panel entry to `high`, `reflect tooling` and `swarm workers` to `high`, and `hardest tasks` to `max`, as Lauren's does, because the budget moves each role's own default.

**Verification.** On macOS 27.0.1 with T3 0.1.10-nightly.20261113.4630, Claude Code 2.1.325, and Codex 0.169.0:

- `bun tools/generate.mjs --check` reports 15 generated files current. `GIT_CONFIG_GLOBAL=/dev/null bun test tests/ --timeout 30000` passes 564, skips 56, and fails 0. The installer's end-to-end test passes 18 of 18, and the poteto-mode script tests pass 113 of 113 with typecheck and Prettier clean.
- The skill script tests pass 373 of 373 with `TLA2TOOLS` and `JAVA` pointed at the mise-installed TLC 1.7.4 and Temurin 25 and with a physical `TMPDIR`. As CI runs them, without TLC, they pass 269, skip 70, and fail only the launcher symlink test, which fails the same way on `main` under `/var` and passes with a physical `TMPDIR`, as 2.1.0 recorded.
- The dry run at `bf0c7cd` passes for all three components, with no undeclared fork and no substitution that matches nothing.
- `doctor` on a copy of this Mac's sheet reports "machine sheet valid" on `main` and on this release. Without `retired`, the checker fails that sheet on the four `how` and `why` lines.

Three fresh root threads on `claudeAgent/claude-opus-5-5` at `effort=xhigh` read poteto-mode and the changed skills from this release's tree in place of the installed 2.2.8, in a throwaway two-commit repository. The threads, the repository, and the project are deleted since.

- `/why` on why the cache defaults its TTL to 5 seconds read the nine-line skill, answered from the commit that cut the TTL, quoted its reason, marked two claims as inferences, listed what the record does not answer, and started no subagent.
- `/how` on how `fetchUser` serves a miss, a hit, and an expired entry started one `delegate_task` child with `role: "research"` and no `target`, which ran on the parent's `claudeAgent/claude-opus-5-5`, and presented its explanation after rerunning five of its results. It also told the user once that the sheet has no `# defaults: 2` line and to rerun `/setup-pstack`.
- setup-pstack's steps 1, 2, and 4 on a copy of this Mac's sheet dropped the four `how` and `why` lines, carried `strongest judgment` over to `hardest tasks`, replaced no value, and wrote a candidate with `# defaults: 2`. The checker printed `ok: every role line parses and dispatches on this T3` and exited 0 on the candidate and on the unmodified copy. The real sheet's hash did not change.

This is a minor release. setup-pstack gains the defaults migration, the defaults add a provider and a tier, and `how` and `why` lose their fan-outs, as 2.2.0's removal of a shipped tool was minor. It is not a major release, because no user has to act. A sheet written by any 2.x release passes `doctor` and setup-pstack's check with its `how` and `why` lines, and poteto-mode keeps honoring its lines. Neither hooks file changes. Rerun `/setup-pstack` to take the new defaults and drop the retired lines. On Codex, run `npx -y github:chhoumann/t3-pstack update` after it, as after every release.

## 2.2.8 - The worktree audit reads git refs by their full name and holds a branch's open PR

The worktree audit marks a worktree `safe` to prune when its HEAD is merged into the base or its branch has a PR that is not open. Three lookups could read unmerged or open work as safe.
Expand Down
4 changes: 2 additions & 2 deletions CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ Names for the concepts this repo's design discussions keep reaching for. Archite
- **Installer** - `tools/install.mjs`, the package's `t3-pstack` bin, run as `npx -y github:chhoumann/t3-pstack <install|update|doctor>`. It installs the plugin in every Claude Code and Codex home T3 can run, trusts the Codex session-start hook, moves the model sheet to its machine path, and checks the result.
- **Frozen hooks file** - `hooks/hooks.json` or `hooks/codex-hooks.json`, pinned in `tools/frozen-hooks.json`. Codex trusts a hook by a hash of its entry, so a change stops the hook in every Codex home until the installer reruns. What the hook says lives in `session-start.sh` and the routing text, which change freely.
- **Model policy** - the role defaults in `plugins/pstack/models.json`, as tiers of T3 entries. The generator stamps them into each skill's Models section and setup-pstack's sheet block.
- **Role** - a named unit of delegated work with its own model choice (`arena runners`, `how explorer`, `swarm workers`). The role vocabulary lives in `models.json`.
- **Panel** - a role whose value is a list (`arena runners`, `architect runners`, `interrogate reviewers`, `arena cross-judge pool`). A panel spans at least two model families; a family is the first segment of a model ID's last `/` part.
- **Role** - a named unit of delegated work with its own model choice (`arena runners`, `hardest tasks`, `swarm workers`). The role vocabulary lives in `models.json`, which also lists the retired roles whose lines an older sheet may still carry.
- **Panel** - a role whose value is a list (`arena runners`, `architect runners`, `interrogate reviewers`, `arena cross-judge pool`). A panel spans at least two model families; a family is the first segment of a model ID's last `/` part, except that a `claude-fable-*` model's family is `claude-fable`.
- **Substitution** - a rule in `tools/substitutions.json` that rewrites one upstream sentence or token into its T3 form. An anchored insert is a substitution that keeps the upstream sentence and appends T3 text.
- **Fork** - a file the port keeps in its own form, declared in `tools/forks.json` with its reason. Every upstream change to it needs a person.
- **Port-only file** - a file under a component's local path that upstream does not carry, such as the manifests, the hooks, `models.json`, and `settle.ts`.
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ GIT_CONFIG_GLOBAL=/dev/null bun test tests/ --timeout 30000

The generator stamps `VERSION` into the Claude Code and Codex manifests, the marketplace entry, and `package.json`. It renders each model-consuming skill's Models section and setup-pstack's sheet block from `plugins/pstack/models.json`, lists the plugin's agents in the Claude Code manifest, and copies the license and notice files into the installed plugin. It checks each skill's frontmatter, every local Markdown link, the plugin layout, agent frontmatter, the Codex marketplace, and both hooks files against their pins in `tools/frozen-hooks.json`. CI runs `bun tools/generate.mjs --check`, which writes nothing and fails naming each generated file that is stale or orphaned, so commit the generator's output. `.pre-commit-config.yaml` runs the same check before each commit once you run `prek install` (or `pre-commit install`).

Change model defaults in `models.json`, never in a skill body. A role names a tier (`default`, `strongest`, or `panel`), and each tier holds T3 entries in the grammar `t3-sheet.mjs` checks. The panel must span two model families. A role may carry an `alias`, the label a sheet written before upstream renamed the role still uses.
Change model defaults in `models.json`, never in a skill body. A role names a tier (`default`, `strongest`, `fast`, or `panel`), and each tier holds T3 entries in the grammar `t3-sheet.mjs` checks. The panel must span two model families. A role may carry an `alias`, the label a sheet written before upstream renamed the role still uses. When upstream drops a role, move its label to `retired`, so the checker and `doctor` pass the line a released sheet still carries.

If you touched `skills/poteto-mode/scripts/`:

Expand Down
Loading
Loading