diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 42ce84d6..3f9b76af 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -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" } ] } diff --git a/CHANGES.md b/CHANGES.md index 0c486643..7117101f 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,56 @@ This file is the release changelog, with one `## - ` 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. diff --git a/CONTEXT.md b/CONTEXT.md index 75f1a4e9..2ce57413 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -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`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fcb6ad8b..735b7ce5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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/`: diff --git a/README.md b/README.md index 62232a9d..3aa73d06 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # t3-pstack -pstack for [T3 Code](https://github.com/pingdotgg/t3code). It is Lauren Tan's (poteto's) [pstack](https://github.com/cursor/plugins/tree/main/pstack), with its Cursor mechanics rewritten in place for T3. Every subagent, panel, fan-out, schedule, and PR watch dispatches through T3's `t3-code` MCP tools, so an `interrogate`, `arena`, or `architect` panel can run Claude, GPT, and Grok reviewers side by side, from a Claude Code thread or a Codex thread. +pstack for [T3 Code](https://github.com/pingdotgg/t3code). It is Lauren Tan's (poteto's) [pstack](https://github.com/cursor/plugins/tree/main/pstack), with its Cursor mechanics rewritten in place for T3. Every subagent, panel, fan-out, schedule, and PR watch dispatches through T3's `t3-code` MCP tools, so an `interrogate`, `arena`, or `architect` panel can run Claude, Gemini, GPT, and Grok reviewers side by side, from a Claude Code thread or a Codex thread. The skill text is Lauren's. A generated set of substitutions rewrites only what names Cursor (its `Task` tool, its model slugs, its `.mdc` rule, its cloud agents, `/loop`), and a few declared forks carry what a substitution cannot. Nothing else needs loading: the T3 rules sit where Lauren's dispatch rules sit. @@ -14,9 +14,9 @@ npx -y github:chhoumann/t3-pstack update npx -y github:chhoumann/t3-pstack doctor ``` -`npx -y github:chhoumann/t3-pstack` runs the installer from the latest commit on `main`. Each Claude Code home's marketplace auto-updates from `main` too, and each Codex home's marketplace stays on the release tag the installer pinned. To run one release's installer, name its tag, as in `npx -y github:chhoumann/t3-pstack#v2.2.8 doctor`. +`npx -y github:chhoumann/t3-pstack` runs the installer from the latest commit on `main`. Each Claude Code home's marketplace auto-updates from `main` too, and each Codex home's marketplace stays on the release tag the installer pinned. To run one release's installer, name its tag, as in `npx -y github:chhoumann/t3-pstack#v2.3.0 doctor`. -`install` and `update` are the same command, and a second run changes nothing. With Node 20 or later, it installs or updates the `t3-pstack@t3-pstack` plugin in every Claude Code and Codex config home T3 can run: `~/.claude` and `~/.codex`, `$CLAUDE_CONFIG_DIR` and `$CODEX_HOME`, and the home of each `claudeAgent` and `codex` instance in T3's settings, disabled ones included. Name any other home with `--claude-home <dir>` or `--codex-home <dir>`. Each home's `t3-pstack` marketplace must come from `chhoumann/t3-pstack`, or from `--source <owner/repo|git URL|dir>` on the same run, and a home whose marketplace has another source is left as it is. A run never switches a home's source, so a home already on `chhoumann/t3-pstack` stays on it under another `--source`, and `doctor` warns and prints the commands that move it. A local directory needs a path such as `./t3-pstack`, since `owner/repo` always means GitHub. On Codex it also trusts t3-pstack's session-start hook, once its hooks file is the one this release pins. Codex runs a plugin's hook only once it is trusted, and T3's Codex sessions never ask, so without this step the hook never runs. Codex 0.164 and later tie that trust to every file in the installed plugin, so each release turns the hook off until the installer trusts it again. So the installer pins each Codex home's `t3-pstack` marketplace to the release's tag, such as `v2.2.8`, and Codex's own auto-upgrade leaves that tag where it is. A release reaches a Codex home only when `update` runs, and that run trusts the hook again. A local directory has no tag, so a marketplace from one stays unpinned. Run `update` after each release. +`install` and `update` are the same command, and a second run changes nothing. With Node 20 or later, it installs or updates the `t3-pstack@t3-pstack` plugin in every Claude Code and Codex config home T3 can run: `~/.claude` and `~/.codex`, `$CLAUDE_CONFIG_DIR` and `$CODEX_HOME`, and the home of each `claudeAgent` and `codex` instance in T3's settings, disabled ones included. Name any other home with `--claude-home <dir>` or `--codex-home <dir>`. Each home's `t3-pstack` marketplace must come from `chhoumann/t3-pstack`, or from `--source <owner/repo|git URL|dir>` on the same run, and a home whose marketplace has another source is left as it is. A run never switches a home's source, so a home already on `chhoumann/t3-pstack` stays on it under another `--source`, and `doctor` warns and prints the commands that move it. A local directory needs a path such as `./t3-pstack`, since `owner/repo` always means GitHub. On Codex it also trusts t3-pstack's session-start hook, once its hooks file is the one this release pins. Codex runs a plugin's hook only once it is trusted, and T3's Codex sessions never ask, so without this step the hook never runs. Codex 0.164 and later tie that trust to every file in the installed plugin, so each release turns the hook off until the installer trusts it again. So the installer pins each Codex home's `t3-pstack` marketplace to the release's tag, such as `v2.3.0`, and Codex's own auto-upgrade leaves that tag where it is. A release reaches a Codex home only when `update` runs, and that run trusts the hook again. A local directory has no tag, so a marketplace from one stays unpinned. Run `update` after each release. `doctor` reports on the same homes and changes nothing itself: each marketplace's source, each Codex marketplace's pin, the installed version, whether its files are all there, whether it is enabled, the Codex hook's trust, Claude Code records that pin an old version, plain copies of the plugin's skills, and the model sheet. It exits 1 on any problem and prints a fix for each. @@ -34,7 +34,7 @@ The plugin carries 66 skill directories, 24 of them `principle-*` leaves, and 4 ## Staying current -This repository syncs from Lauren's tree directly, synced against upstream `c742dd6`. `tools/upstream.json` pins each component, `tools/substitutions.json` holds the rewrite rules and a denylist of Cursor terms, and `tools/forks.json` declares every file the port keeps in its own form and why. `bun tools/sync.mjs <component> <sha>` derives each upstream file through the rules, merges it three ways with the port's copy, and fails on an undeclared fork, a denylist hit, or a rule that no longer matches upstream. [CONTRIBUTING.md](CONTRIBUTING.md#the-sync-boundary) has the details. +This repository syncs from Lauren's tree directly, synced against upstream `bf0c7cd`. `tools/upstream.json` pins each component, `tools/substitutions.json` holds the rewrite rules and a denylist of Cursor terms, and `tools/forks.json` declares every file the port keeps in its own form and why. `bun tools/sync.mjs <component> <sha>` derives each upstream file through the rules, merges it three ways with the port's copy, and fails on an undeclared fork, a denylist hit, or a rule that no longer matches upstream. [CONTRIBUTING.md](CONTRIBUTING.md#the-sync-boundary) has the details. ## Data handling diff --git a/VERSION b/VERSION index 23a63f52..276cbf9e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.2.8 +2.3.0 diff --git a/package.json b/package.json index 9c492435..9adcdd0d 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "t3-pstack", "private": true, - "version": "2.2.8", + "version": "2.3.0", "description": "The installer and development tooling for t3-pstack, Lauren Tan's pstack rewritten in place for T3 Code. The plugin itself lives in plugins/pstack.", "author": { "name": "Christian Bager Bach Houmann", diff --git a/plugins/pstack/.claude-plugin/plugin.json b/plugins/pstack/.claude-plugin/plugin.json index 8f7ec8db..75f30aa5 100644 --- a/plugins/pstack/.claude-plugin/plugin.json +++ b/plugins/pstack/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "t3-pstack", "displayName": "t3-pstack (pstack for T3 Code)", - "version": "2.2.8", + "version": "2.3.0", "description": "pstack for T3 Code: Lauren Tan's pstack with its Cursor mechanics rewritten in place for T3, so subagents, panels, schedules, and PR watches dispatch through T3's orchestration and panels mix Claude, GPT, and Grok.", "author": { "name": "Christian Bager Bach Houmann", diff --git a/plugins/pstack/.codex-plugin/plugin.json b/plugins/pstack/.codex-plugin/plugin.json index 94cdd777..9f578ab2 100644 --- a/plugins/pstack/.codex-plugin/plugin.json +++ b/plugins/pstack/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "t3-pstack", - "version": "2.2.8", + "version": "2.3.0", "description": "pstack for T3 Code on a Codex host: Lauren Tan's pstack with its Cursor mechanics rewritten in place for T3, so subagents, panels, schedules, and PR watches dispatch through T3's orchestration.", "author": { "name": "Christian Bager Bach Houmann", diff --git a/plugins/pstack/agents/comment-sicko.md b/plugins/pstack/agents/comment-sicko.md index 209e3704..14c2402f 100644 --- a/plugins/pstack/agents/comment-sicko.md +++ b/plugins/pstack/agents/comment-sicko.md @@ -23,7 +23,7 @@ That list is my only leash. When I am not sure a keep clause applies, the commen `eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`. -`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat. +`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I trace the named symbol or call, run `/why` from the **why** skill on it, or both. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat. A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code. diff --git a/plugins/pstack/models.json b/plugins/pstack/models.json index 5f249b12..0df20759 100644 --- a/plugins/pstack/models.json +++ b/plugins/pstack/models.json @@ -1,30 +1,28 @@ { "tiers": { "default": "claudeAgent/claude-opus-5-5 effort=xhigh", - "strongest": "claudeAgent/claude-fable-5-1 effort=xhigh", + "strongest": "claudeAgent/claude-fable-5-2 effort=max", + "fast": "claudeAgent/claude-opus-5-5 effort=high fastMode=true", "panel": [ - "claudeAgent/claude-opus-5-5 effort=xhigh", - "codex/gpt-6.1-sol reasoningEffort=xhigh", - "grok/grok-4.7 reasoningEffort=xhigh" + "claudeAgent/claude-fable-5-2 effort=high", + "claudeAgent/claude-opus-5-5 effort=high fastMode=true", + "antigravity/gemini-4-carbon thinking_level=high" ] }, "roles": [ { "role": "feature, refactoring", "tier": "default", "skill": "poteto-mode" }, - { "role": "bug-fix", "tier": "strongest", "skill": "poteto-mode" }, - { "role": "perf-issue", "tier": "strongest", "skill": "poteto-mode" }, - { "role": "hillclimb", "tier": "strongest", "skill": "poteto-mode" }, + { "role": "bug-fix", "tier": "default", "skill": "poteto-mode" }, + { "role": "perf-issue", "tier": "default", "skill": "poteto-mode" }, + { "role": "hillclimb", "tier": "default", "skill": "poteto-mode" }, { "role": "judgment and prose", "tier": "default", "skill": "poteto-mode" }, { "role": "hardest tasks", "alias": "strongest judgment", "tier": "strongest", "skill": "poteto-mode" }, - { "role": "how explorer", "tier": "default", "skill": "how" }, - { "role": "how explainer", "tier": "default", "skill": "how" }, - { "role": "why investigators", "tier": "default", "skill": "why" }, - { "role": "why synthesizer", "tier": "default", "skill": "why" }, - { "role": "reflect tooling", "tier": "default", "skill": "reflect" }, + { "role": "reflect tooling", "tier": "fast", "skill": "reflect" }, { "role": "reflect judgment, divergent, synthesizer", "tier": "default", "skill": "reflect" }, { "role": "arena runners", "tier": "panel", "skill": "arena" }, { "role": "arena cross-judge pool", "tier": "panel", "skill": "arena" }, - { "role": "swarm workers", "tier": "default", "skill": "swarm" }, + { "role": "swarm workers", "tier": "fast", "skill": "swarm" }, { "role": "architect runners", "tier": "panel", "skill": "architect" }, { "role": "interrogate reviewers", "tier": "panel", "skill": "interrogate" } - ] + ], + "retired": ["how explorer", "how explainer", "why investigators", "why synthesizer"] } diff --git a/plugins/pstack/skills/architect/SKILL.md b/plugins/pstack/skills/architect/SKILL.md index b1dbc7f3..a0b47795 100644 --- a/plugins/pstack/skills/architect/SKILL.md +++ b/plugins/pstack/skills/architect/SKILL.md @@ -20,7 +20,7 @@ Open a todolist with one entry per phase before starting. ## Phase A: Ground the problem -Build a real mental model of every system the new code touches. Run the **how** skill over the relevant subsystems. Naming a file isn't grounding. Produce the architectural explanation `how` prescribes. If the design redefines ownership or layering, also run the **why** skill on the existing shape so the rationale becomes a constraint, not a guess. +Build a real mental model of every system the new code touches. Trace the relevant subsystems. Naming a file isn't grounding. Write an architectural explanation of each. If the design redefines ownership or layering, also run the **why** skill on the existing shape so the rationale becomes a constraint, not a guess. Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate. @@ -69,7 +69,7 @@ Use judgment. A few edge cases don't condemn an architecture. Some problems are When you scrap: -1. Re-run the **how** skill over what's been built. +1. Trace what's been built. 2. Redesign as if the new constraints had been day-one assumptions, per redesign-from-first-principles. 3. Subtract before adding, per the **subtract-before-you-add** principle skill. The new sketch should be smaller than the old one before it grows. 4. Return to Phase B and re-run arena. @@ -82,4 +82,4 @@ The caller's usage is written first and the type sketch derived from it. One fil Role defaults on T3, stamped from `plugins/pstack/models.json`. A role line in the model sheet overrides each one. The sheet is `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), one per machine, and `/setup-pstack` writes it. When it is missing, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex). An entry is `<providerInstanceId>/<modelId>` plus `<optionId>=<value>` pairs, and it maps onto `delegate_task`'s `target`, with the provider instance as `providerInstanceId`, the model as `model`, and the pairs as `options`. It splits at its first `/`, so a model ID with its own `/`, such as OpenCode's `<provider>/<model>`, is written whole after it. Option IDs differ per provider, so take them from `orchestrator_capabilities`. `inherit-parent` or `auto` omits `target`. -- architect runners: `claudeAgent/claude-opus-5-5 effort=xhigh`, `codex/gpt-6.1-sol reasoningEffort=xhigh`, `grok/grok-4.7 reasoningEffort=xhigh` +- architect runners: `claudeAgent/claude-fable-5-2 effort=high`, `claudeAgent/claude-opus-5-5 effort=high fastMode=true`, `antigravity/gemini-4-carbon thinking_level=high` diff --git a/plugins/pstack/skills/arena/SKILL.md b/plugins/pstack/skills/arena/SKILL.md index 1346b09a..77306e7b 100644 --- a/plugins/pstack/skills/arena/SKILL.md +++ b/plugins/pstack/skills/arena/SKILL.md @@ -14,7 +14,7 @@ Every candidate gets the same prompt, so the prompt is the contract. 1. State the artifact each candidate is producing. 2. Derive the rubric, 3-6 concrete gradeable criteria for what success looks like on *this* task. It is the picker's tool in Phase D. Candidates only see the task. -3. Pick the runners. Use the `arena runners` line in the model sheet. If the sheet or that line is missing, run one each on the defaults in [Models](#models). An `auto` or `inherit-parent` entry in this line means the parent model, so omit `target` for it. If `delegate_task` rejects a configured entry, run that seat on another target of the same family from `orchestrator_capabilities` and say so. A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `grok`, whatever provider instance serves it. If the family has no other target, or `delegate_task` rejects that one too, drop the seat and say so. If dropped seats leave fewer than two runners, add runners until there are two, or one when the line has one entry. Run each added runner on a remaining runner's model, or omit `target` so it runs on the parent model when none remain, and say so. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill. +3. Pick the runners. Use the `arena runners` line in the model sheet. If the sheet or that line is missing, run one each on the defaults in [Models](#models). An `auto` or `inherit-parent` entry in this line means the parent model, so omit `target` for it. If `delegate_task` rejects a configured entry, run that seat on another target of the same family from `orchestrator_capabilities` and say so. A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `gemini`, whatever provider instance serves it, except that Fable (`claude-fable-*`) is its own family. If the family has no other target, or `delegate_task` rejects that one too, drop the seat and say so. If dropped seats leave fewer than two runners, add runners until there are two, or one when the line has one entry. Run each added runner on a remaining runner's model, or omit `target` so it runs on the parent model when none remain, and say so. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill. 4. Give each candidate its own output location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`), per the **separate-before-serializing-shared-state** principle skill. On T3 that worktree comes from `isolation: "worktree"`, or from `git worktree add` where poteto-mode's Dispatch on T3 says so. T3 makes an isolated worktree only once the candidate starts, so its brief names its own worktree as its output location, and its reply names the path. ## Phase B: Fan out @@ -25,7 +25,7 @@ If a candidate produces no output, proceed with N-1 and note the dropout. ## Phase C: Cross-judge -After all Phase B candidates complete, choose one model from the `arena cross-judge pool` line in the model sheet. If the sheet or that line is missing, choose from the `arena cross-judge pool` defaults in [Models](#models). Spawn one judge subagent, briefed to inspect only and change no file. The judge is never from the parent's family, as Phase A step 3 defines families. Try only the entries from another family, in pool order. An `auto` or `inherit-parent` entry is the parent model, so it never judges. Among the entries from another family, try first those whose model ran fewer candidates, so no model scores its own work when another can judge. Pool order decides among entries that ran as many, and the reply says when the judge ran a candidate. With the default runners and pool in [Models](#models), a Claude parent skips the Claude entry and gets the next one, and a parent from any other family gets the Claude entry first. If `delegate_task` rejects an entry, use the same model at the closest reasoning level or speed that `orchestrator_capabilities` lists for it, under any provider instance, or move to the next entry when there is none. If no entry from another family runs, try the default pool's entries from another family the same way. If none of those runs, skip the judge, pick the base alone in Phase D, and say so. If `orchestrator_capabilities` names no `inheritedModel`, try the pool's targets in pool order and say that the family check did not run. The judge sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing. +After all Phase B candidates complete, choose one model from the `arena cross-judge pool` line in the model sheet. If the sheet or that line is missing, choose from the `arena cross-judge pool` defaults in [Models](#models). Spawn one judge subagent, briefed to inspect only and change no file. The judge is never from the parent's vendor. A vendor is a family as Phase A step 3 defines families, except that `claude-fable-*` and `claude-*` are one vendor. Try only the entries from another vendor, in pool order. An `auto` or `inherit-parent` entry is the parent model, so it never judges. Among the entries from another vendor, try first those whose model ran fewer candidates, so no model scores its own work when another can judge. Pool order decides among entries that ran as many, and the reply says when the judge ran a candidate. With the default runners and pool in [Models](#models), a Claude parent, Fable included, gets the Gemini entry, and a parent from any other vendor gets the Fable entry first, then the Opus entry. If `delegate_task` rejects an entry, use the same model at the closest reasoning level or speed that `orchestrator_capabilities` lists for it, under any provider instance, or move to the next entry when there is none. If no entry from another vendor runs, try the default pool's entries from another vendor the same way. If none of those runs, skip the judge, pick the base alone in Phase D, and say so. If `orchestrator_capabilities` names no `inheritedModel`, try the pool's targets in pool order and say that the vendor check did not run. The judge sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing. ## Phase D: Pick a base @@ -51,5 +51,5 @@ One synthesized artifact, with a short synthesis note alongside naming the base Role defaults on T3, stamped from `plugins/pstack/models.json`. A role line in the model sheet overrides each one. The sheet is `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), one per machine, and `/setup-pstack` writes it. When it is missing, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex). An entry is `<providerInstanceId>/<modelId>` plus `<optionId>=<value>` pairs, and it maps onto `delegate_task`'s `target`, with the provider instance as `providerInstanceId`, the model as `model`, and the pairs as `options`. It splits at its first `/`, so a model ID with its own `/`, such as OpenCode's `<provider>/<model>`, is written whole after it. Option IDs differ per provider, so take them from `orchestrator_capabilities`. `inherit-parent` or `auto` omits `target`. -- arena runners: `claudeAgent/claude-opus-5-5 effort=xhigh`, `codex/gpt-6.1-sol reasoningEffort=xhigh`, `grok/grok-4.7 reasoningEffort=xhigh` -- arena cross-judge pool: `claudeAgent/claude-opus-5-5 effort=xhigh`, `codex/gpt-6.1-sol reasoningEffort=xhigh`, `grok/grok-4.7 reasoningEffort=xhigh` +- arena runners: `claudeAgent/claude-fable-5-2 effort=high`, `claudeAgent/claude-opus-5-5 effort=high fastMode=true`, `antigravity/gemini-4-carbon thinking_level=high` +- arena cross-judge pool: `claudeAgent/claude-fable-5-2 effort=high`, `claudeAgent/claude-opus-5-5 effort=high fastMode=true`, `antigravity/gemini-4-carbon thinking_level=high` diff --git a/plugins/pstack/skills/blast-radius/SKILL.md b/plugins/pstack/skills/blast-radius/SKILL.md index b296cce0..1f5c9514 100644 --- a/plugins/pstack/skills/blast-radius/SKILL.md +++ b/plugins/pstack/skills/blast-radius/SKILL.md @@ -30,10 +30,10 @@ Step 4 is usually one small script that imports the same library the app ships a ## Steps -1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Use `why` step 2 to pull the PR and commits. +1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Pull the PR and its commits. 2. Find the one fact it's safe because of. Most changes that look risky are safe because of a single fact, like "this call only drops already-dead cache entries and does nothing else". Find that fact. If it holds, most risky cases are cleared at once. Spend your time here, not on a long list of maybes. 3. Look where grep stops. Read the source of the library you call, and check its pinned version and any local patch. Work out when things run: microtasks, unmount and teardown, Solid versus React. Follow what a symbol search misses: the JSON an API returns, a DB column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream. -4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Same rules as `why`. Cite a real `file:line`, a search that finds nothing is still an answer, and never make up a caller or an API. +4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Cite a real `file:line`, a search that finds nothing is still an answer, and never make up a caller or an API. 5. Prove the one fact. Write a script or test that runs the real code, run it, and paste what happened. 6. For a big or wide change, run it as an `arena`. Ask more than one model the same question and merge the answers. Different models catch different real bugs. diff --git a/plugins/pstack/skills/how/SKILL.md b/plugins/pstack/skills/how/SKILL.md index 7bae233f..0cf45dc9 100644 --- a/plugins/pstack/skills/how/SKILL.md +++ b/plugins/pstack/skills/how/SKILL.md @@ -6,38 +6,16 @@ disable-model-invocation: true # How -Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code. - -Every spawn is a `delegate_task` child with `role: "research"` and a brief that says to inspect only and change no file. Explorers use the `how explorer` line in the model sheet (default in [Models](#models)), and every explainer uses the `how explainer` line (default in [Models](#models)). Set `target` from that line's entry, or from the default if the sheet or the line is missing. Leave `target` unset when the value is `auto` or `inherit-parent`. If `delegate_task` rejects an entry, use the default and say so. If it rejects the default, use another target of the same family from `orchestrator_capabilities`. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill. - -## 1. Assess complexity +Explore the codebase to answer "how does X work?" questions. If the scope is ambiguous, state your interpretation and explore. The user can redirect. -- **Simple** (a single module, a small utility, a narrow question such as "how does function X work"): no explorers. Spawn one explainer that explores and explains in one pass, built from `references/explainer-prompt.md` without the explorer-findings section. Go to step 4. -- **Complex** (a subsystem spanning multiple files or services, a cross-cutting feature, a full architectural overview): go to step 2. - -When in doubt, take the simple path. - -## 2. Explore (complex only) - -Decompose the question into 2 to 4 angles, each a distinct slice of the subsystem. Spawn all explorers in a single message, each with `references/explorer-prompt.md` and its angle filled in. - -## 3. Synthesize (complex only) - -Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in. - -## 4. Present - -Present the explainer's output. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it. - -## Output format +## 1. Explain -The explanation uses the sections defined in `references/explainer-prompt.md`, dropping any that do not apply: Overview, Key Concepts, How It Works, Where Things Live, Gotchas. +Spawn one `delegate_task` child with `role: "research"` that explores and explains in one pass. Leave `target` unset, so it runs on this chat's model. Give it the user's question and this brief: -## Models +> You are writing an architectural explanation for a senior engineer. Explore the codebase and write an explanation that a senior engineer unfamiliar with this area could read and walk away with a solid mental model. They should understand the architecture well enough to start working in it confidently. You have read-only access to the codebase. -Role defaults on T3, stamped from `plugins/pstack/models.json`. A role line in the model sheet overrides each one. The sheet is `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), one per machine, and `/setup-pstack` writes it. When it is missing, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex). An entry is `<providerInstanceId>/<modelId>` plus `<optionId>=<value>` pairs, and it maps onto `delegate_task`'s `target`, with the provider instance as `providerInstanceId`, the model as `model`, and the pairs as `options`. It splits at its first `/`, so a model ID with its own `/`, such as OpenCode's `<provider>/<model>`, is written whole after it. Option IDs differ per provider, so take them from `orchestrator_capabilities`. `inherit-parent` or `auto` omits `target`. +## 2. Present -- how explorer: `claudeAgent/claude-opus-5-5 effort=xhigh` -- how explainer: `claudeAgent/claude-opus-5-5 effort=xhigh` +Present the subagent's output. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it. diff --git a/plugins/pstack/skills/how/references/explainer-prompt.md b/plugins/pstack/skills/how/references/explainer-prompt.md deleted file mode 100644 index 3a36fb67..00000000 --- a/plugins/pstack/skills/how/references/explainer-prompt.md +++ /dev/null @@ -1,55 +0,0 @@ -# Explainer Prompt Template - -Build the explainer subagent's prompt from this template. Fill in the placeholders. - ---- - -You are writing an architectural explanation for a senior engineer. Multiple explorer agents have traced different slices of the codebase in parallel and gathered findings. Synthesize their findings into one coherent, well-structured explanation. - -## Original Question - -> {QUESTION} - -## Explorer Findings - -{EXPLORER_FINDINGS_ALL} - -## Instructions - -The explorers each investigated a different angle of the same subsystem. Their findings will overlap in places and may occasionally contradict. Reconcile them. Merge overlapping descriptions, resolve contradictions by checking the code yourself, and combine the separate slices into a unified picture. - -Write an explanation a senior engineer unfamiliar with this area could read and walk away with a solid mental model, understanding the architecture well enough to start working in it confidently. - -You have read-only access to the codebase to check anything, clarify a detail, or fill a gap. Use Read, Grep, and Glob as needed. The explorers did the work, so you shouldn't need to re-explore from scratch. - -## Output Format - -Use this structure, adapted to what makes sense for the question. Not every section is needed for every question. - -### Overview -1-2 paragraphs. What is this thing, what does it do, why does it exist. Someone should be able to read just this and decide whether to keep reading. - -### Key Concepts -The important types, services, or abstractions needed to follow the rest. Brief definitions, not exhaustive. - -### How It Works -The core of the explanation, and the longest section. Walk through the flow: what triggers it, what happens step by step, where data goes, what the decision points are. - -Use prose, not pseudocode. Reference specific files and functions so the reader knows where to look, but don't dump large code blocks unless a snippet is essential to a point. - -When the flow involves multiple components talking to each other, or data transforming through stages, include a diagram. Use mermaid (```mermaid) for structured flows (sequence diagrams, flowcharts, component graphs) or ASCII art for simpler relationships where mermaid would be overkill. Use your judgment. A diagram should clarify, not decorate. If prose covers the flow, skip the diagram. - -### Where Things Live -A brief file/directory map. Just the ones someone would need to start working here. - -### Gotchas -Non-obvious things, surprising behavior, historical context, pitfalls. Skip this section if there's nothing worth calling out. - -## Communication Style - -- Use concrete language, not abstractions-about-abstractions -- Say "the `UserService` calls `AuthClient.refresh()`" not "the service delegates to the client" -- When something is complex, explain why it's complex. Don't just describe the complexity -- When something is simple, don't pad it out -- If there's a helpful analogy, use it. If there isn't, don't force one -- If the explorers flagged open questions or gaps, acknowledge them rather than hiding them diff --git a/plugins/pstack/skills/how/references/explorer-prompt.md b/plugins/pstack/skills/how/references/explorer-prompt.md deleted file mode 100644 index 724bacfc..00000000 --- a/plugins/pstack/skills/how/references/explorer-prompt.md +++ /dev/null @@ -1,35 +0,0 @@ -# Explorer Prompt Template - -Build each explorer subagent's prompt from this template. Fill in the placeholders. - ---- - -Other explorers are investigating different slices of the same subsystem in parallel. Don't try to cover everything. Focus on your assigned angle and go deep. - -## Question - -> {QUESTION} - -## Your Exploration Angle - -{EXPLORATION_ANGLE} - -## Output - -### Components Found -The key types, services, classes, and abstractions. For each: name, file path, and a one-sentence description of what it does. - -### Flow -The execution flow step by step. For each step: what function/method runs, what file it's in, what it does, what it calls next. Include the data that flows between steps. - -### Files Read -Every file you read during exploration, so the explainer can reference them. - -### Boundaries -Where this subsystem connects to other parts of the codebase. The inputs and outputs. - -### Non-Obvious Things -Anything surprising, historically motivated, or easy to get wrong. Things that look like they should work one way but work another. - -### Open Questions -Anything you couldn't fully trace or understand. Be honest about gaps. diff --git a/plugins/pstack/skills/interrogate/SKILL.md b/plugins/pstack/skills/interrogate/SKILL.md index 60e3134b..99a4a8c6 100644 --- a/plugins/pstack/skills/interrogate/SKILL.md +++ b/plugins/pstack/skills/interrogate/SKILL.md @@ -34,4 +34,4 @@ Skip arena Phases C, D, and E. Adversaries find different failures, so the verdi Role defaults on T3, stamped from `plugins/pstack/models.json`. A role line in the model sheet overrides each one. The sheet is `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), one per machine, and `/setup-pstack` writes it. When it is missing, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex). An entry is `<providerInstanceId>/<modelId>` plus `<optionId>=<value>` pairs, and it maps onto `delegate_task`'s `target`, with the provider instance as `providerInstanceId`, the model as `model`, and the pairs as `options`. It splits at its first `/`, so a model ID with its own `/`, such as OpenCode's `<provider>/<model>`, is written whole after it. Option IDs differ per provider, so take them from `orchestrator_capabilities`. `inherit-parent` or `auto` omits `target`. -- interrogate reviewers: `claudeAgent/claude-opus-5-5 effort=xhigh`, `codex/gpt-6.1-sol reasoningEffort=xhigh`, `grok/grok-4.7 reasoningEffort=xhigh` +- interrogate reviewers: `claudeAgent/claude-fable-5-2 effort=high`, `claudeAgent/claude-opus-5-5 effort=high fastMode=true`, `antigravity/gemini-4-carbon thinking_level=high` diff --git a/plugins/pstack/skills/no-comments/SKILL.md b/plugins/pstack/skills/no-comments/SKILL.md index 89ba73ce..d3a1279d 100644 --- a/plugins/pstack/skills/no-comments/SKILL.md +++ b/plugins/pstack/skills/no-comments/SKILL.md @@ -17,7 +17,7 @@ Use the caller's files or diff. Otherwise use the current diff against the base ## Steps 1. Dispatch one `delegate_task` child (`mode: "async"`, `role: "review"`) whose brief opens with "Read `<plugin root>/agents/comment-sicko.md` in full and act as it says" (`<plugin root>` is the directory that holds this plugin's `skills/`). Pass the scope, and no worktree, because a worktree lacks the scope's uncommitted changes. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill. Do not restate its rules. -2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, run `/how` or `/why` on their symbol. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/no-comments`. +2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, trace their symbol or run `/why` on it. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/no-comments`. 3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, run `/architect` once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements. 4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. The **principle-fix-root-causes** and **principle-redesign-from-first-principles** skills guide intent only. Neither authorizes widening the fence nor fixing instances outside it. Never bolt on symptom guards. 5. Constraint comments say `do not remove`, `do not change wording`, or `talk to X before changing`. Leave keeps about things we cannot change. Offer the cheapest in-scope type, runtime, test, or CI lint. Wait for interactive approval. Unattended and eval require caller pre-approval. If approved, encode then delete. Otherwise delete, report the constraint open, and sketch out-of-scope work. diff --git a/plugins/pstack/skills/poteto-help/SKILL.md b/plugins/pstack/skills/poteto-help/SKILL.md index 7810ffdc..a708ca50 100644 --- a/plugins/pstack/skills/poteto-help/SKILL.md +++ b/plugins/pstack/skills/poteto-help/SKILL.md @@ -45,7 +45,7 @@ If cost is the worry, say where the tokens go and how to spend fewer. pstack spe t3-pstack is pstack rewritten for T3 Code, and it installs in Claude Code and Codex with `npx -y github:chhoumann/t3-pstack install`. -Its workflow skills, including `/poteto-mode`, `/how`, `/why`, and `/teach`, dispatch subagents through T3's `delegate_task` with per-role models, so those parts need a T3 thread. +Its workflow skills, including `/poteto-mode`, `/how`, and `/teach`, dispatch subagents through T3's `delegate_task`, some with per-role models, so those parts need a T3 thread. ## Start a task with `/poteto-mode` diff --git a/plugins/pstack/skills/poteto-mode/SKILL.md b/plugins/pstack/skills/poteto-mode/SKILL.md index 899b4316..ecdc7962 100644 --- a/plugins/pstack/skills/poteto-mode/SKILL.md +++ b/plugins/pstack/skills/poteto-mode/SKILL.md @@ -16,7 +16,6 @@ The Principles section below grounds every trigger. In your reply, name each pri Remaining triggers: - Your first message on a task → tell the user, in your own words, their goal, the problem they are solving, and, if the task ships a change, the smallest change you expect to meet it. Don't wait for confirmation. If the evidence rules out the change the user asked for, show it and stop. Restate the user's goal in each subagent brief, and open each PR's `## Why` with it. Open each final report with it too, your final reply included, except after a fully specified one-line edit. -- Nontrivial change, architecture decision, or "are we sure?" → the **how** skill. - About to ask the user a question on a "which approach", "how should I", or "what should this do" fork → classify it before you ask. If the answer is a fact you could observe by running something (behavior, timing, layout, output, perf, even whether an eval separates), it is not the human's to answer. Sketch it via the Prototype playbook (`playbooks/prototype.md`) and let the result decide. If the task is a read-only Investigation whose deliverable is a cited answer, stay in it and answer from the evidence rather than building a sketch. Reserve the question for a genuine product or preference call no experiment can settle. Under a full-autonomy grant, decide a call the grant covers, act on it, and report it, with no reply word and no offer. Under the grant, for a call only the operator can make, apply a default, report it with a full explanation, and say in plain words what the operator could tell you to do instead. The operator answers in their own words. Never give a shorthand token to type back. Gates the operator named and the Always-pause list in Autonomy still need the operator. - Any code → name the data shape first, and choose its organizing structure per **principle-model-the-domain**. - Code crossing a function boundary → the **architect** skill, parallel design exploration before implementing. @@ -91,11 +90,11 @@ Read the leaf skill in full for any principle you apply. Each entry names when i ## Subagents -**Brief any subagent you spawn inside a playbook step as a `poteto-agent`** (code-writing delegates, ad-hoc helpers). The chat that receives `/poteto-mode` runs the playbook. Never spawn a `poteto-agent` to run the playbook itself. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`, `swarm`) set their own brief and role for diverse-model review. Respect what the skill prescribes, don't override to `poteto-agent`. +**Brief any subagent you spawn inside a playbook step as a `poteto-agent`** (code-writing delegates, ad-hoc helpers). The chat that receives `/poteto-mode` runs the playbook. Never spawn a `poteto-agent` to run the playbook itself. Routed workflow skills (`interrogate`, `reflect`, `swarm`) set their own brief and role for diverse-model review. Respect what the skill prescribes, don't override to `poteto-agent`. -**Defaults for every `delegate_task` call.** `mode: "async"` (a steer or resume of a running child, a `t3_thread_send`, gets no `t3_thread_wait` either, because a waiting call holds your turn while other reports wait), full tool access (a read-only child gets "inspect only, change no file" in its brief), file pointers not inlined context, an explicit `target` per role (configurable via `/setup-pstack`. Role defaults in [Models](#models)). Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to your strongest judgment model (the `hardest tasks` default in [Models](#models)), whether the task needs judgment on vague intent or is a precisely specified sequence of steps to execute to the letter. Trivial mechanical edits go to your fast code model. Per-role lines in the model sheet that `/setup-pstack` writes override these defaults and the model choices in the routed skills (`how`, `why`, `arena`, `swarm`, `architect`, `interrogate`, `reflect`). A role with no line keeps its default, and a role line of `inherit-parent` or `auto` runs that role on the parent chat model (omit `target`). Each code playbook's configured model comes from its line (`feature, refactoring`, `bug-fix`, `perf-issue`, or `hillclimb`), and the hardest changes read `hardest tasks`. Prose and judgment read `judgment and prose`. +**Defaults for every `delegate_task` call.** `mode: "async"` (a steer or resume of a running child, a `t3_thread_send`, gets no `t3_thread_wait` either, because a waiting call holds your turn while other reports wait), full tool access (a read-only child gets "inspect only, change no file" in its brief), file pointers not inlined context, an explicit `target` per role (configurable via `/setup-pstack`. Role defaults in [Models](#models)). Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to your `hardest tasks` model (default in [Models](#models)), whether the task needs judgment on vague intent or is a precisely specified sequence of steps to execute to the letter. Trivial mechanical edits go to your `swarm workers` model (default in the **swarm** skill's Models section). Review and design panels default to one runner each on the panel entries in the **arena** skill's Models section. Per-role lines in the model sheet that `/setup-pstack` writes override these defaults and the model choices in the routed skills (`arena`, `swarm`, `architect`, `interrogate`, `reflect`). A role with no line keeps its default, and a role line of `inherit-parent` or `auto` runs that role on the parent chat model (omit `target`). Each code playbook's configured model comes from its line (`feature, refactoring`, `bug-fix`, `perf-issue`, or `hillclimb`), and the hardest changes read `hardest tasks`. Prose and judgment read `judgment and prose`. If the model sheet has no `# defaults: 2` line, an older setup wrote it. Keep honoring its lines, and tell the user once per session to rerun `/setup-pstack`. -**Match the model to the job.** Before each spawn, start from the role's line or default and pick the reasoning level and speed the job needs. The `/setup-pstack` budget sets each role's starting level, xhigh by default. Raise it one step, up to max, for the hardest or subtlest work. Lower it one step for judgment and two or more steps for routine work. Use fast mode, the provider's speed option (`fastMode=true` on Claude, a fast `serviceTier` such as `priority` on Codex), only when the job is urgent, meaning CI or trunk is red or a person is blocked on the result right now. Otherwise use standard speed, the entry without that option. Verification is the exception and stays on the `swarm workers` model and speed (default in the **swarm** skill's Models section). Change only the entry's reasoning option (`effort` on Claude, `reasoningEffort` on Codex and Grok) and its speed option, and keep the family the role names, so a diverse panel stays diverse. If the model has no value at that level, or no speed option, use its nearest one in `orchestrator_capabilities`. A role on `auto` or `inherit-parent` stays on the parent model. If `delegate_task` rejects the adjusted entry, do not try another adjusted entry. Use the role's line or default and say so. If `delegate_task` rejects that too, continue with the calling skill's fallback. An entry counts as rejected once `delegate_task` fails on it with `model_unavailable` or `provider_unavailable`, or rejects its options. Never pass a rejected entry, and skip any fallback whose entry is already rejected. When the calling skill has no fallback, use the closest target of the role's family that `orchestrator_capabilities` lists, or omit `target` so the subagent runs on the parent model when it lists none. When the calling skill's fallback runs out of entries without saying what to do next, omit `target` too. Say so in both cases. +**Match the model to the job.** Before each spawn, start from the role's line or default and pick the reasoning level and speed the job needs. The `/setup-pstack` budget sets each role's starting level, xhigh or high by default, and max for `hardest tasks`. Raise it one step, up to max, for the hardest or subtlest work. Lower it one step for judgment and two or more steps for routine work. Use fast mode, the provider's speed option (`fastMode=true` on Claude, a fast `serviceTier` such as `priority` on Codex), only when the job is urgent, meaning CI or trunk is red or a person is blocked on the result right now. Otherwise use standard speed, the entry without that option. Verification is the exception and stays on the `swarm workers` model and speed (default in the **swarm** skill's Models section). Change only the entry's reasoning option (`effort` on Claude, `reasoningEffort` on Codex and Grok, `thinking_level` on Antigravity) and its speed option, and keep the family the role names, so a diverse panel stays diverse. Fable (`claude-fable-*`) is its own family, apart from the other Claude models. If the model has no value at that level, or no speed option, use its nearest one in `orchestrator_capabilities`. So Gemini 4 Carbon on Antigravity, whose `thinking_level` tops out at `high` and which has no speed option, runs at `high` whenever the job calls for high or above. Claude lists no `fastMode` option for Fable 5.2, so an urgent Fable 5.2 subagent runs at standard speed and keeps its level. A role on `auto` or `inherit-parent` stays on the parent model. If `delegate_task` rejects the adjusted entry, do not try another adjusted entry. Use the role's line or default and say so. If `delegate_task` rejects that too, continue with the calling skill's fallback. An entry counts as rejected once `delegate_task` fails on it with `model_unavailable` or `provider_unavailable`, or rejects its options. Never pass a rejected entry, and skip any fallback whose entry is already rejected. When the calling skill has no fallback, use the closest target of the role's family that `orchestrator_capabilities` lists, or omit `target` so the subagent runs on the parent model when it lists none. When the calling skill's fallback runs out of entries without saying what to do next, omit `target` too. Say so in both cases. You own every subagent's work. Review the diff and write your own summary, don't pass through what it said. A second opinion is the same prompt against a different model. Agreement is high-signal. @@ -103,7 +102,7 @@ You own every subagent's work. Review the diff and write your own summary, don't **Dispatch on T3.** Every subagent is a `delegate_task` call from the chat that runs the playbook, same model family included, so every child shows up in T3. When you are a `delegate_task` child, you are a leaf. Do the work yourself, and start no subagent unless your brief names one. Give each call its own `clientRequestId`, stable across retries of that call, and keep each returned `taskId`. A child's completion wakes this thread, so end the turn instead of polling, and call `task_status` only when a result is needed mid-turn. `task_cancel` stops a child, and `task_status` confirms it stopped. A child gets only its brief, never your context, so pass absolute paths. `<plugin root>` is the absolute path of the directory that holds this plugin's `skills/` and `agents/`. A persona (`poteto-agent`, `comment-sicko`, `thermo-nuclear-review-subagent`, `thermo-nuclear-code-quality-review-subagent`) is a brief that opens with "Read `<plugin root>/agents/<name>.md` in full and act as it says", and a `poteto-agent` brief also names this file's absolute path. -A child starts in your checkout, which suits one writer while you write nothing. A writer that runs beside other writers or your own edits gets `isolation: "worktree"`, and T3 gives it a new worktree and branch from your thread's checkout at its `HEAD` commit. Commit what it builds on first, because uncommitted edits stay behind. A child that must start from another commit, such as a PR head or fresh trunk, gets `isolation: "worktree"` even when it only reads. Its brief names that commit or ref, and before anything else the child runs `git fetch` and moves its own branch there with `git reset --hard`. T3 can rename that branch during the run, so the brief tells the child to end its reply with the output of `pwd`, `git branch --show-current`, and `git rev-parse HEAD`. After review, bring its commits onto your branch with `git merge <branch>`, which fast-forwards when your branch has not moved. A PR opens only from a T3 thread's branch, yours or that of a child that owns the PR. In a repo with no commit yet, `delegate_task` refuses the worktree with `Unable to resolve the parent checkout commit`, so commit first. When this thread's project is not a git checkout, which gets the same refusal, when your work lives in a checkout other than the one `t3_worktree_status` names, or when you copy uncommitted changes into the child's worktree, create that worktree with `git worktree add` from `HEAD` instead. Remove that worktree and its branch after the result. A child sent into a worktree it does not own, one you made this way or one a finished worker left, keeps `isolation: "shared"`. Its brief names that absolute path as the only place it writes, and tells it to run every command there (`workdir` on Codex) and to edit by absolute path. Record your own `git status --porcelain` before you dispatch a writer to another checkout, and check after the result that it is unchanged. A step a playbook says to delegate goes to `delegate_task` on that role's sheet entry, not into your own tool calls, unless you state a reason such as a step too small to brief. A research delegate no role names runs on the `how explorer` entry. A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `grok`, whatever provider instance serves it, and your own family is the one in `orchestrator_capabilities`' `inheritedModel`. A rejected target runs on another target of the same family from `orchestrator_capabilities`, and you say so. `orchestrator_capabilities` lists a short set of models per provider, and its `search` finds the others. A required review with no reviewer from another family stays `BLOCKED: independent review`. +A child starts in your checkout, which suits one writer while you write nothing. A writer that runs beside other writers or your own edits gets `isolation: "worktree"`, and T3 gives it a new worktree and branch from your thread's checkout at its `HEAD` commit. Commit what it builds on first, because uncommitted edits stay behind. A child that must start from another commit, such as a PR head or fresh trunk, gets `isolation: "worktree"` even when it only reads. Its brief names that commit or ref, and before anything else the child runs `git fetch` and moves its own branch there with `git reset --hard`. T3 can rename that branch during the run, so the brief tells the child to end its reply with the output of `pwd`, `git branch --show-current`, and `git rev-parse HEAD`. After review, bring its commits onto your branch with `git merge <branch>`, which fast-forwards when your branch has not moved. A PR opens only from a T3 thread's branch, yours or that of a child that owns the PR. In a repo with no commit yet, `delegate_task` refuses the worktree with `Unable to resolve the parent checkout commit`, so commit first. When this thread's project is not a git checkout, which gets the same refusal, when your work lives in a checkout other than the one `t3_worktree_status` names, or when you copy uncommitted changes into the child's worktree, create that worktree with `git worktree add` from `HEAD` instead. Remove that worktree and its branch after the result. A child sent into a worktree it does not own, one you made this way or one a finished worker left, keeps `isolation: "shared"`. Its brief names that absolute path as the only place it writes, and tells it to run every command there (`workdir` on Codex) and to edit by absolute path. Record your own `git status --porcelain` before you dispatch a writer to another checkout, and check after the result that it is unchanged. A step a playbook says to delegate goes to `delegate_task` on that role's sheet entry, not into your own tool calls, unless you state a reason such as a step too small to brief. A research delegate no role names omits `target`, so it runs on the parent model. A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `gemini`, whatever provider instance serves it, except that Fable (`claude-fable-*`) is its own family, and your own family is the one in `orchestrator_capabilities`' `inheritedModel`. A rejected target runs on another target of the same family from `orchestrator_capabilities`, and you say so. `orchestrator_capabilities` lists a short set of models per provider, and its `search` finds the others. A required review with no reviewer from another family stays `BLOCKED: independent review`. **A review gate stays closed when no independent reviewer can run.** A reviewer child that fails or is interrupted gets a fresh `delegate_task` in its place. Keep the results of reviewers that finished. Never count your own review, passing tests, or CI as the independent verdict. While the gate is blocked, record `BLOCKED: independent review` in the todolist, keep merge-ready and shipping closed, and report which reviewers ran and which are missing. Work that doesn't depend on the review continues. A fan-out run only to explore may fall back to one labelled sequential pass. @@ -162,8 +161,8 @@ A large or cross-cutting effort (a migration across many call sites, an ambitiou Role defaults on T3, stamped from `plugins/pstack/models.json`. A role line in the model sheet overrides each one. The sheet is `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), one per machine, and `/setup-pstack` writes it. When it is missing, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex). An entry is `<providerInstanceId>/<modelId>` plus `<optionId>=<value>` pairs, and it maps onto `delegate_task`'s `target`, with the provider instance as `providerInstanceId`, the model as `model`, and the pairs as `options`. It splits at its first `/`, so a model ID with its own `/`, such as OpenCode's `<provider>/<model>`, is written whole after it. Option IDs differ per provider, so take them from `orchestrator_capabilities`. `inherit-parent` or `auto` omits `target`. - feature, refactoring: `claudeAgent/claude-opus-5-5 effort=xhigh` -- bug-fix: `claudeAgent/claude-fable-5-1 effort=xhigh` -- perf-issue: `claudeAgent/claude-fable-5-1 effort=xhigh` -- hillclimb: `claudeAgent/claude-fable-5-1 effort=xhigh` +- bug-fix: `claudeAgent/claude-opus-5-5 effort=xhigh` +- perf-issue: `claudeAgent/claude-opus-5-5 effort=xhigh` +- hillclimb: `claudeAgent/claude-opus-5-5 effort=xhigh` - judgment and prose: `claudeAgent/claude-opus-5-5 effort=xhigh` -- hardest tasks: `claudeAgent/claude-fable-5-1 effort=xhigh` (a `strongest judgment` line counts as this role) +- hardest tasks: `claudeAgent/claude-fable-5-2 effort=max` (a `strongest judgment` line counts as this role) diff --git a/plugins/pstack/skills/poteto-mode/playbooks/bug-fix.md b/plugins/pstack/skills/poteto-mode/playbooks/bug-fix.md index 7aa284b5..782141b8 100644 --- a/plugins/pstack/skills/poteto-mode/playbooks/bug-fix.md +++ b/plugins/pstack/skills/poteto-mode/playbooks/bug-fix.md @@ -5,7 +5,7 @@ Be scientific. Every shipped line traces to runtime evidence. Belt-and-suspenders that "might help" is a hypothesis, not a fix. It does not ship. When evidence refutes a hypothesis, revert what it motivated. The smallest change the evidence justifies ships, nothing more. 1. Reproduce it yourself on the matching surface via the control skill (Non-negotiables), even when a debug or instrumentation protocol says to ask the user to reproduce. Ask the user only with a stated, specific reason the control surface cannot reach the target, and only after driving it as far as it goes. If it won't reproduce directly, synthesize the trigger, tighten conditions, or instrument until it fires. -2. Binary-search the cause. Form the candidate hypotheses, then rule them out until one survives. Seed them with `how` over the affected subsystem and the **why** skill for regression history. Each pass, take the split that cuts the most remaining problem space, get runtime evidence, eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Don't guess. Drive a long or stubborn hunt with a `schedule_task` loop bound to this thread. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect/interrogate fan-out. +2. Binary-search the cause. Form the candidate hypotheses, then rule them out until one survives. Seed them with a trace of the affected subsystem and the **why** skill for regression history. Each pass, take the split that cuts the most remaining problem space, get runtime evidence, eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Don't guess. Drive a long or stubborn hunt with a `schedule_task` loop bound to this thread. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect/interrogate fan-out. 3. Plan the fix. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured bug-fix model (default in poteto-mode's [Models](../SKILL.md#models)) with a specific scope. 4. Verify on the same surface. The original repro now passes. "Inconclusive" or wrong-surface is not a pass. Flag it. Unit tests show branch behavior, not bug absence. 5. Stage the commits so the failing repro lands before the fix in git history. See the **tdd** skill for the failing-test-first cadence when the bug has a cheap local test path. Skip it when the test would be expensive, integration-heavy, or unclear. diff --git a/plugins/pstack/skills/poteto-mode/playbooks/feature.md b/plugins/pstack/skills/poteto-mode/playbooks/feature.md index 5bec4af2..0e2f76d4 100644 --- a/plugins/pstack/skills/poteto-mode/playbooks/feature.md +++ b/plugins/pstack/skills/poteto-mode/playbooks/feature.md @@ -2,7 +2,7 @@ **You own the design. Plan, review, verify.** Delegate implementation. Stay in the lead. -1. `how` over the affected subsystem. +1. Trace the affected subsystem. 2. `architect` for parallel design exploration. 3. Write the throughput checkpoint as four todo items. A dimension that genuinely does not apply (single file, no fan-out) keeps its item with `n/a: <reason>` rather than being dropped: - **Blocking first steps.** Gates run before fan-out. diff --git a/plugins/pstack/skills/poteto-mode/playbooks/hillclimb.md b/plugins/pstack/skills/poteto-mode/playbooks/hillclimb.md index f59f4a37..16e05397 100644 --- a/plugins/pstack/skills/poteto-mode/playbooks/hillclimb.md +++ b/plugins/pstack/skills/poteto-mode/playbooks/hillclimb.md @@ -4,7 +4,7 @@ Core discipline: one change, one measurement, keep or revert. Never stack untested changes, and never claim a win from code inspection (the **prove-it-works** principle skill). -1. Ground the workload and architecture before choosing the metric. Run the **how** skill over the target, name the realistic workload dimensions that can move the result (data size, history, state, concurrency), and select a case that reproduces the user's complaint. If no case reproduces it, fix the repro instead of hillclimbing. Then fix one metric, the direction that counts as better, and a checkable stop predicate that pairs a target with a floor on attempts so a lucky early win can't end the run (the example "at least 50% better than baseline and at least 10 iterations" is this shape). Use the user's numbers when given, otherwise agree them. +1. Ground the workload and architecture before choosing the metric. Trace the target, name the realistic workload dimensions that can move the result (data size, history, state, concurrency), and select a case that reproduces the user's complaint. If no case reproduces it, fix the repro instead of hillclimbing. Then fix one metric, the direction that counts as better, and a checkable stop predicate that pairs a target with a floor on attempts so a lucky early win can't end the run (the example "at least 50% better than baseline and at least 10 iterations" is this shape). Use the user's numbers when given, otherwise agree them. 2. Build the measurement harness, prove its sensitivity, then freeze it (the **build-the-lever** principle skill). Run contrasting realistic workloads and confirm the target case reproduces the symptom while easier cases separate as expected. If the harness cannot distinguish them, revise the workload or metric. Vet the harness with the **benchmark-checklist** skill before you freeze it, and make it print its error count and a count of the work done. Once frozen, one repeatable command emits the metric, sampled enough to clear the noise (median of N, not a single run). Record the baseline metric and a green run of the regression gate (the tests that must keep passing) before any change. 3. Open the decision log via the **show-me-your-work** skill. A `decision.tsv`, one row per attempt: id, hypothesis, change, before, after, delta, tests, verdict (kept or reverted), note. Read it before each attempt. Keep it out of the tree (gitignored). 4. Ground each hypothesis in the architecture model from step 1, so it names a specific mechanism ("defer X off the boot path because it blocks first paint"), not "try memoizing something". For a perf metric, order hypotheses by the performance mantras in step 2 of the Perf issue playbook (`playbooks/perf-issue.md`). Borrow only their order, not that step's stop rule. diff --git a/plugins/pstack/skills/poteto-mode/playbooks/investigation.md b/plugins/pstack/skills/poteto-mode/playbooks/investigation.md index cd119f04..854d56f6 100644 --- a/plugins/pstack/skills/poteto-mode/playbooks/investigation.md +++ b/plugins/pstack/skills/poteto-mode/playbooks/investigation.md @@ -4,9 +4,9 @@ Investigation requests are read-only. They produce a cited explanation or a recommendation, not a code change. -1. Route through the **how** skill. For motivation questions, also route through the **why** skill. +1. Trace the code the question is about. For motivation questions, also route through the **why** skill. 2. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only investigation`. -3. Produce the `how`-shaped output (Overview / Key Concepts / How It Works / Where Things Live / Gotchas), or a recommendation with a tradeoffs table if the request is a decision between alternatives. +3. Produce the output (Overview / Key Concepts / How It Works / Where Things Live / Gotchas), or a recommendation with a tradeoffs table if the request is a decision between alternatives. 4. Apply the **unslop** skill to the reply. No PR, no babysit, no `architect` unless the investigation precedes a code change. If it does, hand back to the user and re-route to Bug fix or Feature. diff --git a/plugins/pstack/skills/poteto-mode/playbooks/multi-phase-plan.md b/plugins/pstack/skills/poteto-mode/playbooks/multi-phase-plan.md index 9b0b2b8f..e2bcd309 100644 --- a/plugins/pstack/skills/poteto-mode/playbooks/multi-phase-plan.md +++ b/plugins/pstack/skills/poteto-mode/playbooks/multi-phase-plan.md @@ -149,7 +149,7 @@ Each live lane runs in its own worktree at the PR head. Drive through the contro ## Appendix D. Links and reading list -<Docs to read before editing. Which PRs get `<plugin root>/skills/how/SKILL.md` and `<plugin root>/skills/interrogate/SKILL.md`. The trail per `<plugin root>/skills/show-me-your-work/SKILL.md`.> +<Docs to read before editing. Which PRs get `<plugin root>/skills/interrogate/SKILL.md`. The trail per `<plugin root>/skills/show-me-your-work/SKILL.md`.> ```` **Reply:** the plan path, the PR ids with their dependencies and the review-gated set, what the prototypes proved and what stays unproven, and the check script's output. diff --git a/plugins/pstack/skills/poteto-mode/playbooks/perf-issue.md b/plugins/pstack/skills/poteto-mode/playbooks/perf-issue.md index b2672344..daf10d08 100644 --- a/plugins/pstack/skills/poteto-mode/playbooks/perf-issue.md +++ b/plugins/pstack/skills/poteto-mode/playbooks/perf-issue.md @@ -3,7 +3,7 @@ **You own the measurement story. Plan, review, verify the numbers.** Tie every fix to a measurement, don't read source instead of measuring. 1. Capture a baseline trace via the matching control skill. Vet the baseline, and each later number, with the **benchmark-checklist** skill. -2. `how` to ground hypotheses. Don't claim a perf ceiling without running it first. +2. Trace the code to ground hypotheses. Don't claim a perf ceiling without running it first. Try the performance mantras in order, cheapest first: 1. Don't do it. Stop work whose result nothing uses rather than cheapening it. 2. Do it, but don't do it again. diff --git a/plugins/pstack/skills/poteto-mode/playbooks/refactoring.md b/plugins/pstack/skills/poteto-mode/playbooks/refactoring.md index d5c0734e..6debca66 100644 --- a/plugins/pstack/skills/poteto-mode/playbooks/refactoring.md +++ b/plugins/pstack/skills/poteto-mode/playbooks/refactoring.md @@ -4,7 +4,7 @@ If the cleanup reveals a missing feature or a real bug, split it out and ship the structural change first against the pinned contract. A redesign is allowed, but name it and route to Feature. Large or cross-cutting structural work belongs to the **figure-it-out** skill. This playbook is the focused-to-medium change. -1. Pin the behavior contract first. Run the **how** skill over the affected subsystem to learn the contract, then write a characterization test, snapshot, or equivalence harness that captures current behavior before any structure moves. If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin. +1. Pin the behavior contract first. Trace the affected subsystem to learn the contract, then write a characterization test, snapshot, or equivalence harness that captures current behavior before any structure moves. If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin. 2. Name the structure the code is missing per **principle-model-the-domain**. Boring code stays when the shape is already clear and local. The reshape must delete branches or invalid states, not add indirection. 3. Name the target shape. State what the module layout, types, and call graph should be if built today (**principle-foundational-thinking**, **principle-redesign-from-first-principles**). If the target crosses a function boundary, run the **architect** skill for parallel design exploration of the shape before the move. 4. Subtract before you add. Delete dead code, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape (**principle-subtract-before-you-add**). The smallest change that reaches the target shape ships (**principle-laziness-protocol**). A speculative cleanup that "might help" gets reverted. diff --git a/plugins/pstack/skills/recall/SKILL.md b/plugins/pstack/skills/recall/SKILL.md index 14e2ce24..f6c2deeb 100644 --- a/plugins/pstack/skills/recall/SKILL.md +++ b/plugins/pstack/skills/recall/SKILL.md @@ -10,14 +10,14 @@ disable-model-invocation: true Keep it tight and on-topic. Read only what the in-scope threads need, then stop. -Your context lives in two records. Your own chat history holds what you did and decided. The shared record holds everything that happened around the same code under other names: the symptoms users keep reporting, the fixes that shipped and got reverted, the errors still firing in prod. That second record is what the **why** skill searches, across source control, the issue tracker, chat and issue channels, long-form docs, and error tracking. A feature with a long bug tail keeps most of its story there, so don't reconstruct it from your transcripts alone. +Your context lives in two records. Your own chat history holds what you did and decided. The shared record holds everything that happened around the same code under other names: the symptoms users keep reporting, the fixes that shipped and got reverted, the errors still firing in prod. That second record lives in source control, the issue tracker, chat and issue channels, long-form docs, and error tracking. A feature with a long bug tail keeps most of its story there, so don't reconstruct it from your transcripts alone. Your chat history lives in T3. `t3_thread_list` lists this project's threads newest first, `t3_thread_search` searches their titles and content within one project, and `t3_thread_read` reads one thread, bounded by `maxCharsPerItem`, with `afterPosition` to page. 1. Classify, then route. One specific prior chat to resume is the `session-pickup` playbook, not this. Turning habits into a durable skill is `automate-me`. A human-readable summary of your work is a different task. Recall loads working context across recent chats before you act. If the user already gave you a full state capsule (paths, branch, the change), use it and skip the mining. 2. Lock the scope before searching. Pin the window ("recent" is a real range, default the last 7 days), the topic if named, and the workspace (default the active one. Never read another project's transcripts without being asked). State the scope back. Never quietly turn "all" into "recent N". 3. Fan out across your chat history. Spawn parallel subagents on a fast, cheap model, each taking a slice of the corpus. Tell every subagent to order candidates by `updatedAt` from `t3_thread_list` and never by thread ID, grep the topic first and then read only the matching chats and only their relevant regions, and skip the current chat plus obvious noise (subagent, eval, and test chats). Each returns the same schema, one block per chat: topic, the user's goal, decisions, open threads, struggles and corrections, and artifacts (PRs, tickets, branches), each citing the thread ID. For one or two chats, skip the fan-out and search directly. The raw transcripts stay in the subagents. The main thread gets only their findings. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill. -4. Sweep the shared record whenever the topic names a feature, file, subsystem, area, or bug. This is the default, not a judgment call, and "my work on X" does not exempt it. Hand it to the **why** skill's source investigators, but steer their question from "why was this built this way" to "what's the current state, what's been tried and didn't hold, and what are users still reporting". Reuse its per-source playbooks, run the investigators in parallel with the chat-history mining, and inherit its posture: one investigator per source, null results are findings, skip an unavailable MCP and say so. Fold what comes back into the brief. Skip this step only for pure activity recall with no named target ("what did I do this week"), where your own history and live state are the entire answer. +4. Sweep the shared record whenever the topic names a feature, file, subsystem, area, or bug. This is the default, not a judgment call, and "my work on X" does not exempt it. Spawn one investigator per source, each a `delegate_task` child with full tool access, MCP included, and ask each "what's the current state, what's been tried and didn't hold, and what are users still reporting". Run them in parallel with the chat-history mining. Null results are findings. Skip an unavailable MCP and say so. Fold what comes back into the brief. Skip this step only for pure activity recall with no named target ("what did I do this week"), where your own history and live state are the entire answer. 5. Verify against live state. Take the PRs, branches, and tickets that the mining and the sweep surfaced and check them with `git` and `gh`. When the answer hinges on what an agent actually did (the tools it ran, files it read, errors it hit), read the full transcript, not just a trimmed local copy. 6. Write the brief to the contract below. Group by thread. Stay on the named topic. diff --git a/plugins/pstack/skills/reflect/SKILL.md b/plugins/pstack/skills/reflect/SKILL.md index e46c8393..746f78ae 100644 --- a/plugins/pstack/skills/reflect/SKILL.md +++ b/plugins/pstack/skills/reflect/SKILL.md @@ -82,5 +82,5 @@ Short list, no preamble: Role defaults on T3, stamped from `plugins/pstack/models.json`. A role line in the model sheet overrides each one. The sheet is `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), one per machine, and `/setup-pstack` writes it. When it is missing, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex). An entry is `<providerInstanceId>/<modelId>` plus `<optionId>=<value>` pairs, and it maps onto `delegate_task`'s `target`, with the provider instance as `providerInstanceId`, the model as `model`, and the pairs as `options`. It splits at its first `/`, so a model ID with its own `/`, such as OpenCode's `<provider>/<model>`, is written whole after it. Option IDs differ per provider, so take them from `orchestrator_capabilities`. `inherit-parent` or `auto` omits `target`. -- reflect tooling: `claudeAgent/claude-opus-5-5 effort=xhigh` +- reflect tooling: `claudeAgent/claude-opus-5-5 effort=high fastMode=true` - reflect judgment, divergent, synthesizer: `claudeAgent/claude-opus-5-5 effort=xhigh` diff --git a/plugins/pstack/skills/reflect/references/synthesizer.md b/plugins/pstack/skills/reflect/references/synthesizer.md index 6d1dfef0..3c8cb561 100644 --- a/plugins/pstack/skills/reflect/references/synthesizer.md +++ b/plugins/pstack/skills/reflect/references/synthesizer.md @@ -25,7 +25,7 @@ Drop (implementation details that drift): - "linter at SHA `bd91aa7` uses chars/4 heuristic" - "`<specific-skill-name>` has 175 tokens at limit 80" - "Bugbot flagged regex backtracking on May 2" -- "we renamed `gpt-4` to `gpt-4o` in `encodingForModel`" +- "we renamed `parseConfig` to `loadConfig` in `settings.ts`" Keep (durable patterns): - "closed regex enums for trigger detection are brittle. Prefer schema-validated structures" diff --git a/plugins/pstack/skills/setup-pstack/SKILL.md b/plugins/pstack/skills/setup-pstack/SKILL.md index 554719a8..55281a0a 100644 --- a/plugins/pstack/skills/setup-pstack/SKILL.md +++ b/plugins/pstack/skills/setup-pstack/SKILL.md @@ -11,11 +11,19 @@ Write the model sheet, `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pst ### 1. Detect available models -Call `orchestrator_capabilities`, or `acp-mcp-call orchestrator_capabilities '{}'` where the T3 tools are not exposed. Its provider instances and their models are the dependable source. A target is valid only when its provider instance can run a child task and lists the model. Note each provider's own option IDs and values, such as `effort` on Claude and `reasoningEffort` on Codex and Grok. Never write a target you have not seen there. The aliases `inherit-parent` and `auto` are always valid. +Call `orchestrator_capabilities`, or `acp-mcp-call orchestrator_capabilities '{}'` where the T3 tools are not exposed. Its provider instances and their models are the dependable source. A target is valid only when its provider instance can run a child task and lists the model. Note each provider's own option IDs and values, such as `effort` on Claude, `reasoningEffort` on Codex and Grok, and `thinking_level` on Antigravity. Never write a target you have not seen there. The aliases `inherit-parent` and `auto` are always valid. ### 2. Load current state -The default role-to-target mapping is the sheet shape in step 5 below. If the sheet already exists, read it and treat its `# budget` line and its role values as the current choices. If it does not, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex), where releases before 2.0.0-rc.3 kept the sheet, the same way. Otherwise start from those defaults. A line whose role is not in step 5, such as `how critics`, is from a retired role. Drop it. Carry a `strongest judgment` value over to `hardest tasks`, its new name. Also drop any value that is not a T3 entry, such as a bare family name, a `claude-` slug, or an `@<level>` suffix, and a `default effort` line. +The default role-to-target mapping is the sheet shape in step 5 below. If the sheet already exists, read it and treat its `# budget` line and its role values as the current choices. If it does not, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex), where releases before 2.0.0-rc.3 kept the sheet, the same way. Otherwise start from those defaults. A line whose role is not in step 5, such as `how explorer` or `why investigators`, is from a retired role. Drop it. Carry a `strongest judgment` value over to `hardest tasks`, its new name. Also drop any value that is not a T3 entry, such as a bare family name, a `claude-` slug, or an `@<level>` suffix, and a `default effort` line. + +A sheet without the `# defaults: 2` line comes from an older setup. That setup wrote a line for every role, so some of its values are old defaults, not choices. Before step 3, replace each of these values with the role's step 5 default: + +- `claudeAgent/claude-fable-5-1`, with any options, in `bug-fix`, `perf-issue`, `hillclimb`, or `hardest tasks`. +- `claudeAgent/claude-opus-5-5`, with any options, in `reflect tooling` or `swarm workers`. +- In a panel role (`arena runners`, `arena cross-judge pool`, `architect runners`, `interrogate reviewers`), a list of exactly `claudeAgent/claude-opus-5-5`, `codex/gpt-6.1-sol`, and `grok/grok-4.7`, with any options, in any order. + +Every other value is the user's choice and stays, including every `inherit-parent` or `auto` value. Tell the user which values you replaced. ### 3. Budget, map, and confirm @@ -26,9 +34,9 @@ The default role-to-target mapping is the sheet shape in step 5 below. If the sh - `medium - high reasoning` - `small - medium reasoning` -**(b) Apply it.** Build the working table from the defaults, and on a re-run keep any role you changed by provider, list, or alias (`inherit-parent`, `auto`). `unlimited`, `large`, `medium`, and `small` set the reasoning option of every entry, panel entries included, to `max`, `xhigh`, `high`, or `medium`. Use the option ID that provider lists. If the provider does not offer that value, use its highest value at or below the target, else mark the role as needing a choice. So Grok, whose reasoning tops out at `xhigh`, stays at `xhigh` under `unlimited`. `inherit-parent` and `auto` do not change. +**(b) Apply it.** Build the working table from the defaults, and on a re-run keep any role you changed by provider, family, list, or alias (`inherit-parent`, `auto`). Families are the ones Phase A of the **arena** skill defines, so Fable is its own family. Each role has a target effort, which is its default's effort moved by the budget. `large` keeps it, `unlimited` raises it one step, `medium` lowers it one step, and `small` lowers it two steps, on the ladder `max` > `xhigh` > `high` > `medium` > `low`. A target at either end of the ladder stays there. Most defaults are at `xhigh`, and each budget label names where those land. Set the reasoning option of every entry in the role, panel entries included, to the role's target, using the option ID that provider lists. If the provider does not offer that value, use its highest value at or below the target, else mark the role as needing a choice. `inherit-parent` and `auto` do not change. So `unlimited` raises an `effort=xhigh` default to `effort=max` and an `effort=high` default to `effort=xhigh`, and it keeps an `effort=max` default. Gemini 4 Carbon's `thinking_level` tops out at `high`, so under `unlimited` the fallback keeps it at `high`. `small` turns `effort=xhigh` into `effort=medium` and `effort=high` into `effort=low`. Each keeps any speed option its default has. Claude lists no `fastMode` option for Fable 5.2, and Antigravity lists no speed option for Gemini 4 Carbon, so never write one for them. -**(c) Show the roles and confirm.** Show every role with its entry, marking any target not in the detected set as needing a choice. Also list each line step 2 dropped. Ask whether to accept as-is or change specific roles, offering the detected targets plus `inherit-parent` and `auto` (both mean: this role runs on the parent chat's model) as the options. For panel roles (`arena runners`, `architect runners`, `interrogate reviewers`) the value is a list, and one subagent runs per entry, alias entries included, so the list length sets the count. A panel needs at least two model families among its targets. A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `grok`. `arena cross-judge pool` is also a list, but Arena runs one judge. It tries only values from a family other than the parent's. Among those it tries first the ones whose model ran fewer candidates, and list order decides among values that ran as many, so order it by preference. An `inherit-parent` or `auto` value never judges. `swarm workers` is the default target for every worker unless a race or comparison assigns another per arm. +**(c) Show the roles and confirm.** Show every role with its entry, marking any target not in the detected set as needing a choice. Also list each line step 2 dropped. Ask whether to accept as-is or change specific roles, offering the detected targets plus `inherit-parent` and `auto` (both mean: this role runs on the parent chat's model) as the options. For panel roles (`arena runners`, `architect runners`, `interrogate reviewers`) the value is a list, and one subagent runs per entry, alias entries included, so the list length sets the count. A panel needs at least two model families among its targets. A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `gemini`, except that Fable (`claude-fable-*`) is its own family. `arena cross-judge pool` is also a list, but Arena runs one judge. It tries only values from a vendor other than the parent's. Fable and the other Claude models are one vendor. Among those values it tries first the ones whose model ran fewer candidates, and list order decides among values that ran as many, so order it by preference. An `inherit-parent` or `auto` value never judges. `swarm workers` is the default target for every worker unless a race or comparison assigns another per arm. **(d) Ask about the session-start hook.** Ask whether t3-pstack's session-start hook should keep telling new chats when to enter `/poteto-mode`. Write `session hook: on` or `session hook: off`. @@ -38,29 +46,26 @@ Write the candidate to a temp file. Call `orchestrator_capabilities` again and s ### 5. Write the sheet -Overwrite the sheet with the candidate, creating its directory and writing through any symlink at its path (resolve it with `realpath`). If a different file is already there, run the checker on it and ask before you replace it. Overwrite the whole file so re-runs stay idempotent. Then replace `t3-pstack-models.md` in the host's config directory with a link to the sheet (`ln -sf`), so an older t3-pstack reads the same sheet. Step 2 already read what it held. On Codex, remove any pstack model rows an earlier setup pasted into `<codex-home>/AGENTS.md`. With every default kept, the sheet reads: +Overwrite the sheet with the candidate, creating its directory and writing through any symlink at its path (resolve it with `realpath`). The candidate carries the `# defaults: 2` line and a `# budget` line with the chosen label and the effort that label names. If a different file is already there, run the checker on it and ask before you replace it. Overwrite the whole file so re-runs stay idempotent. Then replace `t3-pstack-models.md` in the host's config directory with a link to the sheet (`ln -sf`), so an older t3-pstack reads the same sheet. Step 2 already read what it held. On Codex, remove any pstack model rows an earlier setup pasted into `<codex-home>/AGENTS.md`. With every default kept, the sheet reads: ```markdown # pstack model configuration (T3). One line per role. Delete a line to fall back to the skill default. # `inherit-parent` or `auto` as a value: the role runs on the parent chat's model (`delegate_task` omits `target`). Alias entries in a panel list still count toward its fan-out. +# defaults: 2 # budget: large (xhigh) feature, refactoring: claudeAgent/claude-opus-5-5 effort=xhigh -bug-fix: claudeAgent/claude-fable-5-1 effort=xhigh -perf-issue: claudeAgent/claude-fable-5-1 effort=xhigh -hillclimb: claudeAgent/claude-fable-5-1 effort=xhigh +bug-fix: claudeAgent/claude-opus-5-5 effort=xhigh +perf-issue: claudeAgent/claude-opus-5-5 effort=xhigh +hillclimb: claudeAgent/claude-opus-5-5 effort=xhigh judgment and prose: claudeAgent/claude-opus-5-5 effort=xhigh -hardest tasks: claudeAgent/claude-fable-5-1 effort=xhigh -how explorer: claudeAgent/claude-opus-5-5 effort=xhigh -how explainer: claudeAgent/claude-opus-5-5 effort=xhigh -why investigators: claudeAgent/claude-opus-5-5 effort=xhigh -why synthesizer: claudeAgent/claude-opus-5-5 effort=xhigh -reflect tooling: claudeAgent/claude-opus-5-5 effort=xhigh +hardest tasks: claudeAgent/claude-fable-5-2 effort=max +reflect tooling: claudeAgent/claude-opus-5-5 effort=high fastMode=true reflect judgment, divergent, synthesizer: claudeAgent/claude-opus-5-5 effort=xhigh -arena runners: claudeAgent/claude-opus-5-5 effort=xhigh, codex/gpt-6.1-sol reasoningEffort=xhigh, grok/grok-4.7 reasoningEffort=xhigh -arena cross-judge pool: claudeAgent/claude-opus-5-5 effort=xhigh, codex/gpt-6.1-sol reasoningEffort=xhigh, grok/grok-4.7 reasoningEffort=xhigh -swarm workers: claudeAgent/claude-opus-5-5 effort=xhigh -architect runners: claudeAgent/claude-opus-5-5 effort=xhigh, codex/gpt-6.1-sol reasoningEffort=xhigh, grok/grok-4.7 reasoningEffort=xhigh -interrogate reviewers: claudeAgent/claude-opus-5-5 effort=xhigh, codex/gpt-6.1-sol reasoningEffort=xhigh, grok/grok-4.7 reasoningEffort=xhigh +arena runners: claudeAgent/claude-fable-5-2 effort=high, claudeAgent/claude-opus-5-5 effort=high fastMode=true, antigravity/gemini-4-carbon thinking_level=high +arena cross-judge pool: claudeAgent/claude-fable-5-2 effort=high, claudeAgent/claude-opus-5-5 effort=high fastMode=true, antigravity/gemini-4-carbon thinking_level=high +swarm workers: claudeAgent/claude-opus-5-5 effort=high fastMode=true +architect runners: claudeAgent/claude-fable-5-2 effort=high, claudeAgent/claude-opus-5-5 effort=high fastMode=true, antigravity/gemini-4-carbon thinking_level=high +interrogate reviewers: claudeAgent/claude-fable-5-2 effort=high, claudeAgent/claude-opus-5-5 effort=high fastMode=true, antigravity/gemini-4-carbon thinking_level=high session hook: on ``` diff --git a/plugins/pstack/skills/setup-pstack/scripts/t3-sheet.mjs b/plugins/pstack/skills/setup-pstack/scripts/t3-sheet.mjs index e112e7f9..4c874685 100644 --- a/plugins/pstack/skills/setup-pstack/scripts/t3-sheet.mjs +++ b/plugins/pstack/skills/setup-pstack/scripts/t3-sheet.mjs @@ -36,10 +36,14 @@ export function parseEntry(text) { return { providerInstanceId: match[1], model: match[2], options }; } -// The family is the first segment (`claude`, `gpt`, `grok`) of the model ID's +// The family is the first segment (`claude`, `gpt`, `gemini`) of the model ID's // last `/` part, so a Claude model served by a Codex-driver pool still counts as // Claude, and an OpenCode route prefix such as `openrouter/` decides nothing. -export const family = (model) => model.split("/").pop().split("-")[0]; +// Fable is its own family, `claude-fable`, as Lauren's pstack has it since 0.15.42. +export function family(model) { + const id = model.split("/").pop(); + return /^claude-fable(?:-|$)/.test(id) ? "claude-fable" : id.split("-")[0]; +} // A panel's families among its concrete targets. An inherit entry does not // count: one sheet serves every thread on the machine, so its family depends on @@ -67,8 +71,10 @@ export function parseSheet(markdown) { // role with its `tier`, and the `alias` a released sheet may still use), its // tier defaults, and an `orchestrator_capabilities` catalog. A role with no // line runs on its tier's default, so that default must dispatch here too. +// A `retired` role's line is one a released sheet still carries and no skill +// reads, so it passes unchecked until setup-pstack drops it. // With no catalog, as in the installer's doctor, only the grammar is checked. -export function checkSheet(sheet, { roles, defaults, catalog }) { +export function checkSheet(sheet, { roles, defaults, catalog, retired = [] }) { const problems = []; const byRole = new Map(roles.flatMap((r) => [[r.role, r], ...(r.alias ? [[r.alias, r]] : [])])); const seen = new Set(); @@ -77,6 +83,7 @@ export function checkSheet(sheet, { roles, defaults, catalog }) { problems.push(`line ${line}: not a "<role>: <value>" line (lowercase role, one space after the colon, no indent or markup)`); continue; } + if (retired.includes(key)) continue; const canonical = byRole.get(key)?.role ?? key; if (seen.has(canonical)) problems.push(`"${key}" appears twice; only one line may set it`); seen.add(canonical); @@ -166,11 +173,12 @@ if (invoked === fileURLToPath(import.meta.url)) { console.error("usage: t3-sheet.mjs <sheet.md> <catalog.json>"); process.exit(2); } - const { roles, tiers } = JSON.parse(readFileSync(new URL("../../../models.json", import.meta.url), "utf8")); + const { roles, tiers, retired } = JSON.parse(readFileSync(new URL("../../../models.json", import.meta.url), "utf8")); const problems = checkSheet(parseSheet(readFileSync(sheetPath, "utf8")), { roles, defaults: tiers, catalog: JSON.parse(readFileSync(catalogPath, "utf8")), + retired, }); for (const problem of problems) console.log(problem); if (problems.length) process.exit(1); diff --git a/plugins/pstack/skills/sharpen/SKILL.md b/plugins/pstack/skills/sharpen/SKILL.md index 5b4a7b10..2a03402b 100644 --- a/plugins/pstack/skills/sharpen/SKILL.md +++ b/plugins/pstack/skills/sharpen/SKILL.md @@ -13,4 +13,4 @@ I want a deeper version of this task, not a bigger one. Before rewriting it, do Then rewrite my prompt to ask for exactly that. -Leave choices that are mine to make open instead of deciding them. +Have the rewritten prompt ask the agent to prototype any choice an experiment can settle and recommend an option based on what it observed. Leave product or preference choices that no experiment can settle for me to make. diff --git a/plugins/pstack/skills/statechart/scripts/backends/mermaid.ts b/plugins/pstack/skills/statechart/scripts/backends/mermaid.ts index 327220ca..21ad39cb 100644 --- a/plugins/pstack/skills/statechart/scripts/backends/mermaid.ts +++ b/plugins/pstack/skills/statechart/scripts/backends/mermaid.ts @@ -93,6 +93,52 @@ const esc = (s: string, quoted = false) => { const or = (names: Iterable<string>) => [...names].sort(byText).join(" or "); +type Edge = { from: string[]; start: boolean; to: string[]; label: string | undefined }; + +const within = (parent: string[], path: string[]) => + path.length >= parent.length && parent.every((p, i) => path[i] === p); +const wayIn = (e: Edge) => tupleKey([e.start, e.from]); + +export function drawnEdges(r: Region): Edge[] { + let out: Edge[] = []; + for (const s of r.states) + if (s.start) out.push({ from: [], start: true, to: s.path, label: undefined }); + for (const s of r.steps) + out.push({ + from: s.from, + start: false, + to: s.to, + label: s.label + (s.when ? ` [${s.when}]` : ""), + }); + const parents = new Map<string, string[]>(); + for (const s of r.states) + for (let i = 1; i < s.path.length; i++) { + const prefix = s.path.slice(0, i); + parents.set(tupleKey(prefix), prefix); + } + for (const parent of [...parents.values()].sort((a, b) => a.length - b.length)) { + const into = out.filter( + (e) => e.to.length > parent.length && within(parent, e.to) && !within(parent, e.from), + ); + if (!into.length || into.some((e) => wayIn(e) !== wayIn(into[0]))) continue; + const one = into.length === 1; + const at = out.indexOf(into[0]); + out = out.filter((e) => !into.includes(e)); + out.splice( + at, + 0, + { ...into[0], to: parent, label: one ? into[0].label : undefined }, + ...into.map((e) => ({ + from: parent, + start: true, + to: e.to, + label: one ? undefined : e.label, + })), + ); + } + return out; +} + const MARK_STYLES = { breaks: "fill:#ffecee,stroke:#e72e3b,stroke-width:2.5px,color:#cd2834", mayBreak: "fill:#fff3e6,stroke:#e8730c,stroke-width:2.5px,color:#b85a06", @@ -121,6 +167,9 @@ export function mermaidLines(chart: Chart) { if (s === undefined) known.set(path, (s = id(path))); return s; }; + const drawn = drawnEdges(r); + const line = (e: Edge, indent: string) => + `${indent}${e.start ? "[*]" : idOf(e.from)} --> ${idOf(e.to)}${e.label === undefined ? "" : `: ${esc(e.label)}`}`; const tree = (prefix: string[], indent: string, below: ChartState[]) => { const heads = new Map<string, ChartState[]>(); for (const s of below) append(heads, s.path[prefix.length], s); @@ -134,6 +183,9 @@ export function mermaidLines(chart: Chart) { if (inner.length) { out.push(`${indent}state "${esc(head, true)}" as ${id(path)} {`); tree(path, indent + " ", inner); + const key = tupleKey(path); + for (const e of drawn) + if (e.start && tupleKey(e.from) === key) out.push(line(e, `${indent} `)); out.push(`${indent}}`); } else if (leaf) { const sid = idOf(leaf.path); @@ -153,11 +205,7 @@ export function mermaidLines(chart: Chart) { } }; tree([], " ", r.states); - for (const s of r.states) if (s.start) out.push(` [*] --> ${idOf(s.path)}`); - for (const s of r.steps) - out.push( - ` ${idOf(s.from)} --> ${idOf(s.to)}: ${esc(s.label + (s.when ? ` [${s.when}]` : ""))}`, - ); + for (const e of drawn) if (!e.start || !e.from.length) out.push(line(e, " ")); return out; }; let body: string[]; diff --git a/plugins/pstack/skills/statechart/scripts/run.ts b/plugins/pstack/skills/statechart/scripts/run.ts index 4efd368e..017684f8 100644 --- a/plugins/pstack/skills/statechart/scripts/run.ts +++ b/plugins/pstack/skills/statechart/scripts/run.ts @@ -68,6 +68,7 @@ const TLC_TOOL = "http:tla2tools[url=https://github.com/tlaplus/tlaplus/releases/download/v1.7.4/tla2tools.jar,checksum=sha256:936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88]@1.7.4"; const JAVA_TOOL = "java@temurin-25"; export const PINNED_FLAGS = ["-workers", "1", "-fp", "0", "-lncheck", "final"]; +const SANY_ERRORS = /^\*\*\* ?(?:Errors|Abort messages|Parse Error)/m; type ChildResult = { status: number | null; @@ -227,6 +228,12 @@ const tail = (r: FileResult) => { return kept.join("").trim().split("\n").slice(-30).join("\n"); }; +const firstLines = (text: string) => { + const lines = text.trim().split("\n"); + if (lines.length > 40) lines.splice(40, Infinity, `... ${lines.length - 40} more lines`); + return lines.join("\n"); +}; + const stopOf = (r: FileResult): Stop => { const errors: Part[] = []; for (const m of r.error ? [] : messagesOf(r.output)) @@ -238,9 +245,14 @@ const stopOf = (r: FileResult): Stop => { ) errors.push(m); if (!errors.length) return { status: r.status, message: tail(r) }; - const lines = [...plainText(errors)].join("").trim().split("\n"); - if (lines.length > 40) lines.splice(40, Infinity, `... ${lines.length - 40} more lines`); - return { status: r.status, message: lines.join("\n") }; + return { status: r.status, message: firstLines([...plainText(errors)].join("")) }; +}; + +const sanyErrors = (r: FileResult) => { + if (r.error) return undefined; + const text = [...plainText(messagesOf(r.output))].join(""); + const at = text.search(SANY_ERRORS); + return at === -1 ? undefined : firstLines(text.slice(at)); }; const names = (rules: Rule[], kind: Rule["kind"]) => { @@ -305,8 +317,21 @@ export async function check(specFile: string, configFile: string): Promise<Check ["-o", "-I", folder, path.resolve(specFile)], ["-XX:TieredStopAtLevel=1"], ); - if (xml.status !== 0) - throw new Error(`SANY could not read ${specFile} (exit ${xml.status}):\n${tail(xml)}`); + if (xml.status !== 0) { + const errors = xml.error + ? undefined + : sanyErrors( + await runJava( + "sany-errors", + "tla2sany.SANY", + [path.resolve(specFile)], + ["-XX:TieredStopAtLevel=1"], + ), + ); + throw new Error( + `SANY could not read ${specFile} (exit ${xml.status}):\n${errors ?? tail(xml)}`, + ); + } const sany = readSany(fs.readFileSync(xml.stdout, "utf8")); const module = path.basename(specFile, ".tla"); const spec = { ...readSpec({ module, sany, checks }), folder }; diff --git a/plugins/pstack/skills/statechart/scripts/test/chart.test.ts b/plugins/pstack/skills/statechart/scripts/test/chart.test.ts index ef220432..95ba9e86 100644 --- a/plugins/pstack/skills/statechart/scripts/test/chart.test.ts +++ b/plugins/pstack/skills/statechart/scripts/test/chart.test.ts @@ -42,6 +42,7 @@ import { readTrace } from "../frontends/trace.ts"; import { readVerdict } from "../frontends/verdict.ts"; import { compile, project } from "../pipeline.ts"; import { fileLines } from "../run.ts"; +import { drawn } from "./drawn.ts"; const here = path.dirname(fileURLToPath(import.meta.url)); const corpus = (name: string, file: string) => path.join(here, "corpus", name, file); @@ -693,6 +694,48 @@ test("a step that leaves every child of a parent the same way is one arrow from assert.deepEqual(quits, [[open, closed]]); }); +test("a parent's only way in ends at the parent, and its start marker goes on to each state with that step's label", () => { + const graph = graphOf( + [ + ["ask", { at: "Asking" }, true], + ["flat", { at: "Layout.Flat" }], + ["parents", { at: "Layout.Parents" }], + ["drawn", { at: "Done.Drawn" }], + ], + [ + ["ask", "flat", "String"], + ["ask", "parents", "Array"], + ["flat", "drawn", "Draw"], + ], + ); + const { chart } = draw(graph, { state: (v) => String(v.at).split(".") }); + assert.deepEqual(drawn(chart).arrows.sort(), [ + "Asking --> Layout", + "Done start --> Drawn", + "Flat --> Done: Draw", + "Layout start --> Flat: String", + "Layout start --> Parents: Array", + ]); +}); + +test("a parent that two states lead into keeps an arrow from each, since one start marker cannot say where each came from", () => { + const graph = graphOf( + [ + ["a", { at: "A" }, true], + ["b", { at: "B" }], + ["p", { at: "P.p" }], + ["q", { at: "P.q" }], + ], + [ + ["a", "b", "Go"], + ["a", "p", "Left"], + ["b", "q", "Right"], + ], + ); + const { chart } = draw(graph, { state: (v) => String(v.at).split(".") }); + assert.deepEqual(drawn(chart).arrows.sort(), ["A --> B: Go", "A --> p: Left", "B --> q: Right"]); +}); + test("a label codes only the characters that Mermaid reads as syntax, so TLA+ values stay as TLC prints them", () => { const graph = graphOf( [ diff --git a/plugins/pstack/skills/statechart/scripts/test/cli.test.ts b/plugins/pstack/skills/statechart/scripts/test/cli.test.ts index 97b71c30..11f06a6f 100644 --- a/plugins/pstack/skills/statechart/scripts/test/cli.test.ts +++ b/plugins/pstack/skills/statechart/scripts/test/cli.test.ts @@ -9,6 +9,7 @@ import { setTimeout as sleep } from "node:timers/promises"; import { fileURLToPath, pathToFileURL } from "node:url"; import { plainText } from "../backends/plain-text.ts"; import { readMessages } from "../frontends/messages.ts"; +import { drawn } from "./drawn.ts"; const here = path.dirname(fileURLToPath(import.meta.url)); const corpus = path.join(here, "corpus"); @@ -881,18 +882,6 @@ test("a view with a group in a theme color draws that color and names the group assert.match(chart, new RegExp(`^ {2}class ${legend} teal$`, "m")); }); -const shown = (text: string) => text.replace(/#(\d+);/g, (_, n) => String.fromCodePoint(Number(n))); - -const drawn = (chart: string) => { - const names = new Map<string, string>(); - for (const m of chart.matchAll(/^ *(?:state "(.*)" as (s\d+) \{|(s\d+): (.*))$/gm)) - names.set(m[2] ?? m[3], shown(m[1] ?? m[4])); - const arrows: string[] = []; - for (const [, from, to, text] of chart.matchAll(/^ *(s\d+) --> (s\d+): (.*)$/gm)) - arrows.push(`${names.get(from)} --> ${names.get(to)}: ${shown(text)}`); - return { states: [...names.values()], arrows }; -}; - const byX = (labels: unknown[]) => `export const state = (v) => ${JSON.stringify(labels)}[v.x];\n`; const fanOut = (n: number) => { @@ -926,7 +915,7 @@ for (const [what, c] of [ view: byX([["a\0b"], ["a", "b"], ["c"], ["d"]]), status: 0, states: ["ab", "a", "b", "c", "d"], - arrows: ["ab --> b: Inc", "b --> c: Inc", "c --> d: Inc"], + arrows: ["a start --> b", "ab --> a: Inc", "b --> c: Inc", "c --> d: Inc"], says: /^TLC reached 4 states and 3 steps\. The chart draws 4 states and 3 arrows\.$/m, }, ], @@ -942,7 +931,14 @@ for (const [what, c] of [ ]), status: 0, states: ["R f", "S p", "R ab", "S q", "R a", "R b", "S r"], - arrows: ["S p --> S q: Inc", "S p --> S r: Inc"], + arrows: [ + "R f start --> S p", + "R ab start --> S q", + "R b start --> S r", + "R a start --> R b", + "S p --> R ab: Inc", + "S p --> R a: Inc", + ], says: /^The regions chart lets R f, S p go to R a\0b, S r by Inc, which the model never does\. So the chart draws parent states in place of regions\.$/m, }, ], @@ -964,7 +960,7 @@ for (const [what, c] of [ view: byX([["a\u0001b"], ["a", "b"], ["c"], ["d"]]), status: 0, states: ["a\u0001b", "a", "b", "c", "d"], - arrows: ["a\u0001b --> b: Inc", "b --> c: Inc", "c --> d: Inc"], + arrows: ["a start --> b", "a\u0001b --> a: Inc", "b --> c: Inc", "c --> d: Inc"], says: /^TLC reached 4 states and 3 steps\. The chart draws 4 states and 3 arrows\.$/m, }, ], @@ -1002,7 +998,7 @@ for (const [what, c] of [ view: byX([["a"], ["P", "b\u0002c"], ["d"], ["e"]]), status: 1, states: ["a", "P", "b\u0002c", "d", "e"], - arrows: ["a --> b\u0002c: Next", "b\u0002c --> d: Next", "d --> e: Next"], + arrows: ["P start --> b\u0002c", "a --> P: Next", "b\u0002c --> d: Next", "d --> e: Next"], says: /^## NotOne breaks\nThe shortest path has 1 step:\n0\. a\n1\. Next: P \/ b\cBc$/m, }, ], @@ -1039,10 +1035,15 @@ for (const [what, c] of [ status: 0, states: ["R f", "S p", "R a", "S r", "R b", "S q", "R X\u0003a", "S q", "R X\u0003b", "S r"], arrows: [ - "S p --> S r: Go\u0003X", - "S p --> S q: Go\u0003X", - "S p --> S q: Go", - "S p --> S r: Go", + "R f start --> S p", + "R a start --> S r", + "R b start --> S q", + "R X\u0003a start --> S q", + "R X\u0003b start --> S r", + "S p --> R a: Go\u0003X", + "S p --> R b: Go\u0003X", + "S p --> R X\u0003a: Go", + "S p --> R X\u0003b: Go", ], says: /^The regions chart lets R f, S p go to R a, S q by Go\cCX, which the model never does\. So the chart draws parent states in place of regions\.$/m, }, diff --git a/plugins/pstack/skills/statechart/scripts/test/corpus.test.ts b/plugins/pstack/skills/statechart/scripts/test/corpus.test.ts index 89343731..90a4104e 100644 --- a/plugins/pstack/skills/statechart/scripts/test/corpus.test.ts +++ b/plugins/pstack/skills/statechart/scripts/test/corpus.test.ts @@ -383,6 +383,44 @@ for (const [width, height, config, status, drawn, chart, header] of [ }, ); +for (const [what, tla, where] of [ + [ + "an unknown name", + ["---- MODULE Broken ----", "VARIABLE x", "Init == x = 0", "Next == x' = y", "===="], + /^line 4, col 14 to line 4, col 14 of module Broken\n+Unknown operator: `y'\.$/m, + ], + [ + "a parse error", + ["---- MODULE Broken ----", "VARIABLE x", "Init == x = = 0", "Next == x' = x", "===="], + /^Encountered "0" at line 3, column 15/m, + ], + [ + "twelve unknown names", + [ + "---- MODULE Broken ----", + "VARIABLE x", + "Init == x = 0", + ...Array.from({ length: 12 }, (_, i) => `D${i} == u${i}`), + "Next == x' = x", + "====", + ], + /^\*\*\* Errors: 12\n+line 4, col 7 to line 4, col 8 of module Broken\n+Unknown operator: `u0'\.$/m, + ], +] as const) + test( + `a spec with ${what} gets SANY's line and column, not a Java stack trace`, + { skip }, + async () => { + const base = writeSpec("Broken", [...tla], "INIT Init\nNEXT Next\n"); + await assert.rejects(check(`${base}.tla`, `${base}.cfg`), (error: Error) => { + assert.match(error.message, /^SANY could not read .*Broken\.tla \(exit 1\):\n/); + assert.match(error.message, where); + assert.doesNotMatch(error.message, /^\s+at tla2sany\./m); + return true; + }); + }, + ); + test( "check() leaves no statechart- folder in the temp dir when it returns and when it throws", { skip }, diff --git a/plugins/pstack/skills/statechart/scripts/test/corpus/Login/chart.mmd b/plugins/pstack/skills/statechart/scripts/test/corpus/Login/chart.mmd index 9733b21c..547bd3e6 100644 --- a/plugins/pstack/skills/statechart/scripts/test/corpus/Login/chart.mmd +++ b/plugins/pstack/skills/statechart/scripts/test/corpus/Login/chart.mmd @@ -6,12 +6,13 @@ stateDiagram-v2 s4: Checking second try s5: Wrong password, 1 try left s6: Checking last try + [*] --> s2 } s7: Reset email sent s8: Signed in s9: Locked out [*] --> s0 - s0 --> s2: YouSubmitAPassword + s0 --> s1: YouSubmitAPassword s2 --> s8: ThePasswordIsRight s2 --> s3: ThePasswordIsWrong s7 --> s0: YouSetANewPassword diff --git a/plugins/pstack/skills/statechart/scripts/test/drawn.ts b/plugins/pstack/skills/statechart/scripts/test/drawn.ts new file mode 100644 index 00000000..1290403c --- /dev/null +++ b/plugins/pstack/skills/statechart/scripts/test/drawn.ts @@ -0,0 +1,20 @@ +const shown = (text: string) => text.replace(/#(\d+);/g, (_, n) => String.fromCodePoint(Number(n))); + +export const drawn = (chart: string) => { + const names = new Map<string, string>(); + for (const m of chart.matchAll(/^ *(?:state "(.*)" as (s\d+) \{|(s\d+): (.*))$/gm)) + names.set(m[2] ?? m[3], shown(m[1] ?? m[4])); + const arrows: string[] = []; + const blocks: string[] = []; + for (const line of chart.split("\n")) { + const block = line.match(/^ *state ".*" as (\w+) \{$/); + if (block) blocks.push(block[1]); + if (/^ *\}$/.test(line)) blocks.pop(); + const m = line.match(/^ *(s\d+|\[\*\]) --> (s\d+)(?:: (.*))?$/); + const parent = names.get(blocks.at(-1) ?? ""); + if (!m || (m[1] === "[*]" && parent === undefined)) continue; + const from = m[1] === "[*]" ? `${parent} start` : names.get(m[1]); + arrows.push(`${from} --> ${names.get(m[2])}${m[3] === undefined ? "" : `: ${shown(m[3])}`}`); + } + return { states: [...names.values()], arrows }; +}; diff --git a/plugins/pstack/skills/statechart/scripts/test/labels.ts b/plugins/pstack/skills/statechart/scripts/test/labels.ts index a3d14998..82497246 100644 --- a/plugins/pstack/skills/statechart/scripts/test/labels.ts +++ b/plugins/pstack/skills/statechart/scripts/test/labels.ts @@ -1,5 +1,5 @@ import { inspect } from "node:util"; -import { mermaid as chartText } from "../backends/mermaid.ts"; +import { drawnEdges, mermaid as chartText } from "../backends/mermaid.ts"; import { checkView } from "../frontends/view.ts"; import type { Chart, ChartState, State, Step, View } from "../ir.ts"; import { walk } from "../passes/reach.ts"; @@ -398,6 +398,7 @@ function expected(chart: Chart): Want { const region = chart.regions[i]; const wrap = multi ? `r${i}` : null; if (wrap) nodes.set(wrap, { text: region.name, parent: "all", group: true }); + const drawn = drawnEdges(region); const tree = (prefix: string[], parent: string | null, below: ChartState[]) => { const heads = new Map<string, ChartState[]>(); for (const s of below) { @@ -413,19 +414,23 @@ function expected(chart: Chart): Want { else leaf = s; const node = id(region.name, path); nodes.set(node, { text: head, parent, group: inner.length > 0 }); - if (inner.length) tree(path, node, inner); - else if (leaf?.group !== undefined) used.add(chart.colors[String(leaf.group)]); + if (inner.length) { + tree(path, node, inner); + const key = JSON.stringify(path); + for (const e of drawn) + if (e.start && JSON.stringify(e.from) === key) + edges.push([`${node}_start`, id(region.name, e.to), e.label ?? ""]); + } else if (leaf?.group !== undefined) used.add(chart.colors[String(leaf.group)]); } }; tree([], wrap, region.states); - for (const s of region.states) - if (s.start) edges.push([`${wrap ?? "root"}_start`, id(region.name, s.path), ""]); - for (const s of region.steps) - edges.push([ - id(region.name, s.from), - id(region.name, s.to), - s.label + (s.when ? ` [${s.when}]` : ""), - ]); + for (const e of drawn) + if (!e.start || !e.from.length) + edges.push([ + e.start ? `${wrap ?? "root"}_start` : id(region.name, e.from), + id(region.name, e.to), + e.label ?? "", + ]); } let legend = 0; for (const [text, cls] of Object.entries(chart.colors)) diff --git a/plugins/pstack/skills/statechart/scripts/test/render.test.ts b/plugins/pstack/skills/statechart/scripts/test/render.test.ts index 5309a926..57ff41e9 100644 --- a/plugins/pstack/skills/statechart/scripts/test/render.test.ts +++ b/plugins/pstack/skills/statechart/scripts/test/render.test.ts @@ -6,6 +6,10 @@ import os from "node:os"; import path from "node:path"; import { before, test } from "node:test"; import { fileURLToPath, pathToFileURL } from "node:url"; +import { mermaid as chartText } from "../backends/mermaid.ts"; +import type { Graph } from "../ir.ts"; +import { walk } from "../passes/reach.ts"; +import { project } from "../pipeline.ts"; import { fuzz, type Html, type Mermaid, type Render } from "./labels.ts"; const here = path.dirname(fileURLToPath(import.meta.url)); @@ -75,6 +79,66 @@ test("random labels and colors keep their text and the chart's shape in Mermaid assert.ok(drawn > 400 && refused > 20, `${drawn} charts drawn, ${refused} refused`); }); +const pathPoints = (d: string) => { + const points: number[][] = []; + let [ax, ay] = [0, 0]; + for (const [, cmd, args] of d.matchAll(/([MLC])([^MLC]*)/g)) { + const n = args.split(/[ ,]/).filter(Boolean).map(Number); + const [x, y] = n.slice(-2); + if (cmd !== "M") + for (let t = 0; t <= 1; t += 1 / 64) { + const u = 1 - t; + points.push( + cmd === "L" + ? [ax + (x - ax) * t, ay + (y - ay) * t] + : [ + u ** 3 * ax + 3 * u * u * t * n[0] + 3 * u * t * t * n[2] + t ** 3 * x, + u ** 3 * ay + 3 * u * u * t * n[1] + 3 * u * t * t * n[3] + t ** 3 * y, + ], + ); + } + [ax, ay] = [x, y]; + } + return points; +}; + +test("an arrow into a parent from its only way in stays out of the parent's title bar in Pele 1.9.0", () => { + const graph: Graph = { states: new Map(), steps: [] }; + for (const [id, at] of [ + ["ask", "Asking your view for labels"], + ["flat", "Laying out the chart/Flat"], + ["parents", "Laying out the chart/Parent states"], + ["regions", "Laying out the chart/Regions"], + ]) + graph.states.set(id, { vars: { at }, start: id === "ask", breaks: [] }); + for (const [to, action] of [ + ["flat", "String"], + ["parents", "Array"], + ["regions", "Object"], + ]) + graph.steps.push({ from: "ask", to, action }); + const { chart } = project(graph, walk(graph), { state: (v) => String(v.at).split("/") }, []); + const { svg } = render(chartText(chart)); + const bars = [ + ...svg.matchAll( + /<g class="pele-cluster [^"]*" data-id="([^"]*)"><rect x="([\d.]+)" y="([\d.]+)" width="([\d.]+)"[^>]*\/><path d="M[\d.]+,([\d.]+)H/g, + ), + ].map(([, id, x, y, w, rule]) => ({ id, left: +x, right: +x + +w, top: +y, bottom: +rule })); + assert.equal(bars.length, 1); + const crossings: string[] = []; + for (const [, id, d] of svg.matchAll( + /<g class="pele-edge pele-transition" data-id="([^"]*)"><path d="([^"]*)"/g, + )) + for (const bar of bars) + if ( + pathPoints(d).some( + ([x, y]) => x > bar.left && x < bar.right && y > bar.top && y < bar.bottom, + ) + ) + crossings.push(`${id} crosses the title bar of ${bar.id}`); + assert.deepEqual(crossings, []); +}); + test("the theme in references/render.md colors each class that the charts use", () => { assert.ok(classes.size > 0); for (const name of classes) assert.match(theme, new RegExp(`\\.pele \\.${name} rect \\{`), name); diff --git a/plugins/pstack/skills/swarm/SKILL.md b/plugins/pstack/skills/swarm/SKILL.md index b9ac0ebc..7c50983d 100644 --- a/plugins/pstack/skills/swarm/SKILL.md +++ b/plugins/pstack/skills/swarm/SKILL.md @@ -44,4 +44,4 @@ Return one consolidated in-chat report with a result table, issue one-liners, ga Role defaults on T3, stamped from `plugins/pstack/models.json`. A role line in the model sheet overrides each one. The sheet is `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), one per machine, and `/setup-pstack` writes it. When it is missing, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex). An entry is `<providerInstanceId>/<modelId>` plus `<optionId>=<value>` pairs, and it maps onto `delegate_task`'s `target`, with the provider instance as `providerInstanceId`, the model as `model`, and the pairs as `options`. It splits at its first `/`, so a model ID with its own `/`, such as OpenCode's `<provider>/<model>`, is written whole after it. Option IDs differ per provider, so take them from `orchestrator_capabilities`. `inherit-parent` or `auto` omits `target`. -- swarm workers: `claudeAgent/claude-opus-5-5 effort=xhigh` +- swarm workers: `claudeAgent/claude-opus-5-5 effort=high fastMode=true` diff --git a/plugins/pstack/skills/teach/SKILL.md b/plugins/pstack/skills/teach/SKILL.md index 25369f3f..6146b65c 100644 --- a/plugins/pstack/skills/teach/SKILL.md +++ b/plugins/pstack/skills/teach/SKILL.md @@ -11,7 +11,7 @@ disable-model-invocation: true Teach sits on top of `how` and `why`. Get your bearings on what the work is and what it touches, then run `how` for how it works and `why` for why it's that way. Those are real skill invocations that do their own digging. Blend what they find into one plain explanation, lead with what matters to the person, and go deeper when they ask. Reword freely for teaching, with one exception. Keep `why`'s confidence language intact (its hedges are findings, not style). 1. Decide the few things they should walk away understanding. Choose them from why they're asking (about to change it, reviewing it, debugging it, new to it) and what they already know, both read from the conversation, not quizzed out of them. Skip what they plainly already know. Put the depth where their question is. -2. Let `how` and `why` do the work, don't redo it. Read the code yourself to get oriented, then run `how` for how it works and `why` for why. Run them in parallel and combine the results. Match the size to the question. Run both for a subsystem, maybe one is enough for a small change. Keep `why` narrow by default since its full sweep is slow. Put the narrowing in the ask itself (a scoped question, git plus a source or two) so `why` records the skipped categories per its own contract, and widen it only when the reasons are the point. +2. Let `how` and `why` do the work, don't redo it. Read the code yourself to get oriented, then run `how` for how it works and `why` for why. Run them in parallel and combine the results. Match the size to the question. Run both for a subsystem, maybe one is enough for a small change. 3. Start with a plain definition. Name the thing and say what it is in general terms, the way a senior engineer would say it out loud, with its common name if it has one. Then tie it to the case in front of you ("in X, we use this to ...") and build from there: how it works, the deeper reasons, the edge cases. For each part, explain the idea so it clicks: the problem it solves and how it actually works. Walk through what happens as the person does the thing (opens a long chat, scrolls up) when that is what makes it land. Listing functions and constants is reference, not teaching. Don't print framing labels ("the one idea to hold onto", "the thing to walk away with", "the key insight", "at its core", "TL;DR"). Give the smallest complete answer first, a sentence or two, not a dense paragraph, then stop. Add layers when they ask. Never a wall of text. 4. Keep it a conversation, not a lecture or a performance. Offer to go deeper or move on, and follow their lead. No quizzes. No pacing theater. Don't print "Pause", don't ask them to say it back, don't announce "the sentence to nail", and don't flag a part as important or hard ("here is the part worth slowing down on", "this is the tricky part", "here is where it gets interesting"). Just say it. When you would pause, stop and let them respond. Running one-shot with no live human, deliver it cleanly and put any offer to go deeper at the end. 5. Show, don't only tell, and build the picture up diagram by diagram. Open the diff, the code, or the debugger when that is the fastest way to land it. Draw when a picture lands faster than words. For anything with three or more moving parts, do not draw one diagram with all of them at once. Draw a short series instead, where each diagram redraws the last and adds a single part, so the reader watches the system assemble. A single all-at-once diagram, especially one saved for the end, is a reference, not teaching. Concretely, to teach a flow from A to B to C, draw it three times. First A to B. Then redraw and add C. Then redraw and add the return edge or the next piece. Match the medium to the idea, and use both kinds when both help. A mermaid diagram fits a flow or structure where the labels carry the meaning. When the idea is spatial, like layout, overlap, scroll position, or a before and after, reach for the image-generation tool and draw it marker-on-whiteboard style with a few short labels, since image models garble long text. Generate that picture, don't settle for describing it in words. The build-up rule holds for generated images too. A single simple point needs no figure. diff --git a/plugins/pstack/skills/why/SKILL.md b/plugins/pstack/skills/why/SKILL.md index 242086bc..99397830 100644 --- a/plugins/pstack/skills/why/SKILL.md +++ b/plugins/pstack/skills/why/SKILL.md @@ -1,105 +1,9 @@ --- name: why -description: "Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior." +description: "Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Returns a cited read on decisions and tradeoffs. Use how for runtime behavior." disable-model-invocation: true --- # Why -Investigate the motivation and intent behind code. The companion `how` skill answers what the code does and how it works. `why` answers what forces led to its shape. - -Each spawn below names a role line in the model sheet and a default. Set `target` from that line's entry, or from the default if the sheet or the line is missing. Leave `target` unset when the value is `auto` or `inherit-parent`. If `delegate_task` rejects an entry, use the default and say so. If it rejects the default, use another target of the same family from `orchestrator_capabilities`. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill. - -Every spawn is a `delegate_task` child with full tool access, MCP included, which the MCP-backed investigators and the synthesizer's citation spot-checks need. Investigators still shouldn't write anything. - -## Operating Posture - -Operate as a **careful, cautious, and precise investigator**. Be honest about what you know vs what you're inferring. Read `references/epistemics.md` for the full confidence framework and phrasing guide. The synthesizer must follow it. - -## Step 1. Understand the Target and the Question - -The **target** is usually a chunk of code, a pattern, a feature, or a named design decision. The **question** is usually a design rationale, a tradeoff, a motivating edge case, an external constraint, dead code, or a broad history sweep. - -If the target is vague ("why do we do it this way?" with no clear referent), make your best guess from conversation context (open files, recent edits, cursor location, what was just discussed). State your interpretation briefly so the user can redirect if you're off, then proceed. - -## Step 2. Establish the Code Anchor - -Before spawning investigators, build the seed context inline: file paths and line ranges, key symbols (functions, classes, constants), the last few commits touching the target, PR numbers from merge commits (pattern `(#1234)` in the subject line), and any linked ticket IDs. Run `git blame -L <start>,<end> <file>` for last-touch commits, `git log --follow -p -- <file>` for full history with patches through renames, `git log --oneline -20 -- <file>` for recent commits with PR numbers visible, and `git log -1 --format=%B <commit>` to extract PR numbers. Then pull the PR bodies and discussion for any substantive commit: `gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews`. This anchor goes to every investigator and to the synthesizer. - -## Step 3. Spawn Parallel Investigators - -**Default to the full parallel investigation.** The goal is a complete coverage map, not a minimal one. Document the null, don't skip the search. - -### Discovery - -Before spawning investigators, list the MCP servers whose tools this session exposes. - -Map each available MCP to one evidence category: - -1. Source control history -2. Issue / ticket tracker -3. Long-form documents -4. Real-time team chat -5. Infrastructure observability -6. Error / exception tracking -7. Product analytics warehouse - -Source control is always available through git and `gh`. For the other six, classify using the MCP name, server instructions, tool names, and resource descriptors. If an MCP could fit more than one category, choose the one matching its primary evidence. Record ambiguous cases in the coverage map. - -Spawn one investigator per category that has a matching MCP, all in a single message so they run concurrently, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. `target`: the `why investigators` line, default in [Models](#models). - -Each investigator's prompt is `references/investigator-prompt.md` filled in, plus: -- the category playbook `references/sources/<source>.md` for the selected MCP, adapted from the examples in `references/source-playbook.md` -- `references/sources/incident-postmortem.md` **if the target code looks defensive** (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers) -- the code anchor and the user's original question - -### Investigator roster, one per available evidence category - -Each category below is uniquely positioned to surface one shape of "why", shown after "Best at". Use it to know what to expect back, to name a gap when a category returns empty, and, only in the rare provably-irrelevant case, to justify a skip. - -1. **Source control** (git history, `gh` for PRs, code comments, tests). Always spawn, the only guaranteed source. Best at *implementation-time rationale captured during review*. -2. **Issue / ticket tracker** (e.g. Linear, Jira, GitHub Issues, Plane, Shortcut MCP). Best at *the product or business forcing function*. Strongest when the why is external to engineering. -3. **Long-form documents** (e.g. Notion, Confluence, Google Docs, Coda MCP). Best at *long-form design rationale*, written out before it becomes code. -4. **Real-time team chat** (e.g. Slack, Discord, Microsoft Teams, Mattermost MCP). Best at *real-time deliberation that never reached a doc*. Especially important when the source control, ticket, and doc paper trail is thin. -5. **Infrastructure observability** (e.g. Datadog, New Relic, Honeycomb, Grafana, Splunk MCP). Best at *infrastructure and runtime reality that motivated the code*. Strongest when the target reacts to an infra signal (timeouts, retries, rate limits, circuit breakers). -6. **Error / exception tracking** (e.g. Sentry, Rollbar, Bugsnag, Airbrake MCP). Best at *the specific exceptions and error trajectories that motivated defensive or corrective code*. Strongest for catch blocks, null guards, type checks, retries, and other defenses. -7. **Product analytics warehouse** (e.g. Databricks, Snowflake, BigQuery, ClickHouse, dbt, Redshift MCP). Best at *product and data reality that shaped the code*. Strongest for flag-gated code, experiment-driven ships, data migrations, and "where did this number come from" questions. - -### When to skip an investigator - -Only with an **explicit, written justification** that goes in the final Sources Consulted. Two valid reasons: - -- **No MCP is available for that category** in this environment. Flag it as a gap, not a choice: "Real-time team chat skipped. No matching MCP available, so the conversational record was not searchable." -- **The source is provably irrelevant**, not just "probably irrelevant." A high bar: "Error / exception tracking skipped. Target is a build-time script with no runtime code path." - -If your scope assessment suggests a single-commit trivial target where the PR description already contains the complete answer, you may answer inline **only after** confirming all seven available category searches would be redundant. Say so explicitly. This should be rare. - -## Step 4. Synthesize - -Spawn one synthesizer. `target`: the `why synthesizer` line, default in [Models](#models). It gets: -1. The investigator findings, including any null results and any categories skipped with justification -2. The code anchor -3. The user's original question -4. The epistemics framework from `references/epistemics.md` -5. The synthesizer prompt template from `references/synthesizer-prompt.md` - -## Step 5. Present - -Present the synthesizer's output to the user. You may lightly edit for clarity or add context from the conversation, but **do not rewrite the confidence language**. - -## Output Format - -The structure is the one in `references/synthesizer-prompt.md`: The Question, The Code in Question, What We Found, What We Can Reasonably Infer, Competing Hypotheses, What We Don't Know, Sources Consulted, Confidence Summary. Adapt as needed, but keep the confidence separation intact, and keep Sources Consulted as one line per investigator, including the ones that returned nothing or were skipped, with the reason. - -After Sources Consulted, if the user's `why` question is a precursor to changing this code, convert the lineage findings into a Preserve / Change / Avoid / Risk constraint set for planning the change. - -## Common Failure Modes to Avoid - -- **Recency bias**. Assuming the most recent commit is authoritative. The current shape is often the accretion of many earlier decisions. Trace back. - -## Models - -Role defaults on T3, stamped from `plugins/pstack/models.json`. A role line in the model sheet overrides each one. The sheet is `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), one per machine, and `/setup-pstack` writes it. When it is missing, read `t3-pstack-models.md` in the host's config directory (`$CLAUDE_CONFIG_DIR` or `~/.claude` on Claude Code, `$CODEX_HOME` or `~/.codex` on Codex). An entry is `<providerInstanceId>/<modelId>` plus `<optionId>=<value>` pairs, and it maps onto `delegate_task`'s `target`, with the provider instance as `providerInstanceId`, the model as `model`, and the pairs as `options`. It splits at its first `/`, so a model ID with its own `/`, such as OpenCode's `<provider>/<model>`, is written whole after it. Option IDs differ per provider, so take them from `orchestrator_capabilities`. `inherit-parent` or `auto` omits `target`. - -- why investigators: `claudeAgent/claude-opus-5-5 effort=xhigh` -- why synthesizer: `claudeAgent/claude-opus-5-5 effort=xhigh` +Answer from the record, not the code: read the commits and PR discussions that introduced the target and each later change, and other sources if the trail is thin. Cite what the authors wrote, mark your own inferences as inferences, and say what the record does not answer. diff --git a/plugins/pstack/skills/why/references/epistemics.md b/plugins/pstack/skills/why/references/epistemics.md deleted file mode 100644 index b18abf41..00000000 --- a/plugins/pstack/skills/why/references/epistemics.md +++ /dev/null @@ -1,71 +0,0 @@ -# Epistemics - -How to reason about confidence when evidence is historical, fragmentary, and sometimes contradictory, and how to tell the user without flattening it into false certainty. Code shows what it does, not *why it exists*. The why lives in commits, PRs, tickets, docs, and conversations, all incomplete, biased, and sometimes missing. Pretending otherwise produces confident-sounding guesses that mislead the user. - -## Confidence Tiers - -Every claim in the output must sit in one tier. The tier sets its section and its phrasing. - -### 1. Direct - -An explicit, textual citation answers the question: something an author actually *wrote* that says why, not "the code does X so the author must have wanted X." For example, a PR description "this fixes the bug where users with >1000 items couldn't paginate", a ticket "we're adding this because customer Acme requested it in their security review", a code comment "// clamp to 100 because the upstream API rejects larger values", a design doc "we chose option A over option B because we need persistence across restarts", or a chat message from the author "switching to this approach since the old one was flaky in tests". - -Phrasing: confident, present tense, cited. "This exists because X." - -### 2. Supported - -Multiple pieces of indirect evidence converge on one conclusion. No single source states it explicitly, but the pattern across sources makes it likely. For example, the PR title says "improve performance", the ticket is labeled "perf", and the surrounding commits all touch the same hot path. Or several tests added with the change all exercise very large inputs. Or the author's other PRs from the same week all name the same incident. - -Phrasing: confident but clearly derived, citing each item. "The evidence points strongly to X: [the specific pieces]." - -### 3. Inferred - -A reasonable reading of the context that nothing explicitly supports. It is *your interpretation*, not a fact from the record. For example, the PR doesn't say why, but the error was happening in production (per the incident channel timing) and the fix was rushed (merged the same day), so it was likely a hotfix. Or the function name suggests retry logic, and its retry count of 3 matches the team's 3-retry convention elsewhere in the codebase. - -Phrasing: hedged, with the chain explicit. "Given A and B, C seems likely because D." - -### 4. Speculative - -A plausible hypothesis on thin evidence, where other explanations fit equally well. Worth presenting, since the user may know which is right, but mark it as a guess. For example, "This might be a workaround for a browser bug that's since been fixed, but we found no contemporary evidence of that", or "It's possible this threshold was chosen to match an SLA commitment, but no SLA doc references it." - -Phrasing: "One possibility is X, but we have no direct evidence." Usually lives in Competing Hypotheses, alongside other possibilities. - -### 5. Unknown - -You looked and couldn't find out. A valid, important outcome. Document it. - -Phrasing: "We searched X, Y, and Z and found no evidence of why." Be specific about *what* you searched. "We couldn't find out" is less useful than "We searched the ticket tracker with keywords A and B, scanned the 6 PRs that touched this file since 2023, and grep'd the repo for string literals matching the threshold. None surfaced a rationale." - -## Phrasing Guide - -**Confidence words** imply Direct or Supported evidence and need a citation immediately adjacent. Never use them for inferences: "because", "the reason is", "was designed to" (claims author intent), "fixes" / "addresses" / "solves" (claims the change achieved its goal), "the team decided" (claims a group decision happened). - -**Hedges** signal interpretation, not report. Use them liberally in What We Can Reasonably Infer: "appears to", "seems to", "likely", "suggests", "is consistent with", "one reading is", "plausibly", "may have been", "the evidence points toward". - -**Words to avoid:** - -- "obviously". If it were obvious, the user wouldn't be asking -- "clearly". Almost always precedes a claim that isn't clear -- "of course". Same -- "just" (as in "it's just X for performance"). Dismissive and usually hides uncertainty -- "I think" / "I believe". You're synthesizing evidence, not giving a personal opinion. Use "the evidence suggests" instead. - -## Avoid Rationalization - -Code that "makes sense" today may have been written for reasons that no longer apply, or that were wrong at the time. Don't retrofit a clean rationale onto messy history. Don't assume the author did the "right" thing and work backward to justify it. Don't assume a consistent pattern was intentional when it might be copy-paste. Don't turn an absence of evidence into evidence of absence ("no one mentioned security concerns, so it must not have been a concern"). - -## The Sycophancy Trap - -Users often embed a hypothesis: "Why do we do it this way, I assume it's for performance?" Don't simply confirm it. The guess is a prompt for investigation, not a conclusion to validate. Treat it as one candidate among others and check the evidence independently. If the evidence supports it, say so with citations. If not, say so, and present what the evidence *does* support. - -## When Evidence Contradicts - -Surface both sources in the output, with citations. Don't pick the one that fits a tidier narrative. For example, the ticket says "we need this for customer X's compliance requirement" and the PR says "cleaning up tech debt in this area". Both may be true (the ticket motivated the work, the PR gave the author's framing), or one may be wrong. Let the user make the call. - -## When Evidence Is Missing - -An honest "we don't know" is one of the most valuable outputs. The user learns the answer isn't in the obvious places, that they'll need to ask a human (the original author, the product owner, the team lead), or that they can decide the question isn't worth pursuing further. Failing to mark a gap, and instead filling it with a confident guess, actively harms the user, because they'll act on the guess. Name each gap concretely: the question, the sources searched, what you searched for in each, and what you found (nothing, or only tangential material). - -## Before Finalizing - -Before the synthesizer delivers the output, it checks every claim in "What We Found" and "What We Can Reasonably Infer". Each claim has a citation or moves to Inferred or Hypotheses. Its phrasing matches its tier. It doesn't treat code as evidence for its own intent (if it does, remove or reclassify it). The output has a "What We Don't Know" section. If no gaps are mentioned, that's suspicious. Either the evidence was unusually complete or something is being swept under the rug. diff --git a/plugins/pstack/skills/why/references/investigator-prompt.md b/plugins/pstack/skills/why/references/investigator-prompt.md deleted file mode 100644 index e1c2bbf5..00000000 --- a/plugins/pstack/skills/why/references/investigator-prompt.md +++ /dev/null @@ -1,84 +0,0 @@ -# Investigator Prompt Template - -Fill in the placeholders. Append the one category playbook `sources/<source>.md` for this investigator's evidence category (index: `source-playbook.md`). If the target code looks defensive (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers), also append `sources/incident-postmortem.md` so the investigator runs incident-flavored queries inside its own source. - ---- - -You are investigating the historical context and motivation behind a piece of code. Other investigators search other sources in parallel, and a separate synthesizer combines all findings into the final answer. Go deep on your assigned source only. Gather evidence accurately rather than writing prose. - -Work like a **careful, cautious, and precise investigator**. Surface evidence and describe it accurately, including the parts that don't fit a tidy story. Boring and exact beats plausible. One verbatim quote with a precise citation is worth more than a paragraph of summary. - -## The Question - -> {QUESTION} - -## The Code Anchor - -**Target files:** {FILES_WITH_LINE_RANGES} - -**Key symbols:** {SYMBOLS} - -**Initial commits touching this code (most recent first):** -{COMMIT_LIST} - -**PR numbers extracted from commit messages:** {PR_NUMBERS} - -**Ticket IDs mentioned in commits or PR bodies (if any):** {TICKET_IDS} - -## Your Assigned Source - -{SOURCE_NAME} - -{SOURCE_PLAYBOOK_SECTION} - -## Investigation Loop - -1. **Cast a wide net first** so you don't miss related context. Only then narrow in on specific items. -2. **Read the whole thing.** Read each PR, ticket, doc, or thread fully, not just the title or summary. The key evidence is often in a comment, a subtask, or a follow-up. -3. **Follow links within your source only.** Pull the PR or commit a PR references, the parent or sibling of a ticket, the doc a doc links. Do NOT chase a cross-source reference. Record it under Additional Leads for that source's investigator. The one-investigator-per-category design depends on this. Chasing it duplicates work and confuses scope. -4. **Quote verbatim**, with the exact location (PR number, ticket ID, URL, commit hash, file:line), so the reader can confirm the claim in seconds. -5. **Record what you searched, not just what you found.** Write queries verbatim. An empty search is a finding. -6. **Resist the story.** If two items in your source disagree, record both. Don't suppress the inconvenient one. If three items line up and a fourth contradicts them, the contradiction is the most interesting finding. - -Before reporting a finding as strong, ask whether you would expect to find it if your current reading were wrong, and how the evidence would differ. **Never invent.** If you're tempted to round a partial finding up into a confident statement, stop and label it partial. The synthesizer counts on your output being accurate. - -## Epistemic Discipline - -- **Mechanics are not motivation.** A commit changing `limit = 50` to `limit = 100` shows the change, not necessarily why. Look for the reason in the commit message, PR description, linked ticket, or review comments. -- **No intent from code behavior or style.** You may read code to learn what the target *is*. "The author chose a functional approach" is an observation about code, not evidence of intent. Claim intent only where the author stated it. -- **Preserve uncertainty.** Say when evidence is ambiguous, or when one reading is more plausible but not certain. Don't collapse ambiguity to look decisive. -- **No silent substitutions.** If the question is about feature X and you only find evidence about feature Y, don't present Y's evidence as if it answers X. -- **Gather, don't conclude.** Collect the raw material honestly and completely. Don't answer the question, form a final opinion on "the why", or pick sides in contradictions. Don't speculate beyond what the evidence supports. A hunch with no evidence isn't evidence. The synthesizer does the reasoning. - -## Output Format - -Return your findings in this structure. The synthesizer reads it directly. - -### Source -Which source you investigated (source control, issue / ticket tracker, long-form documents, real-time team chat, infrastructure observability, error / exception tracking, product analytics warehouse, code comments, etc.). - -### What I Searched -The queries you ran, items you opened, and places you looked. Be specific. This shows how thorough the search was and what is still unsearched. - -### Direct Evidence Found -For each item that explicitly addresses the question: -- **What it says**: verbatim quote or accurate paraphrase -- **Where it's from**: PR #123, ticket ID, doc URL, chat permalink, commit hash, or file:line -- **Author and date** (if available) -- **Relevance**: one sentence on how it bears on the question - -### Indirect / Circumstantial Evidence -For each item that bears on the question without answering it: -- **What it is**: brief description -- **Where it's from**: location -- **What it suggests**: what a careful reader might infer, and the inference chain -- **Alternative readings**: if the same evidence could support a different interpretation, note it - -### Contradictions -Items that disagree with each other, with both citations. - -### Gaps -What you searched for and didn't find, specifically: "Searched the issue tracker for [query] across [time range]. No matching issues." - -### Additional Leads -Anything that suggests further investigation in a different source, for its investigator or a follow-up pass. For example, a chat thread that a PR mentions. diff --git a/plugins/pstack/skills/why/references/source-playbook.md b/plugins/pstack/skills/why/references/source-playbook.md deleted file mode 100644 index aa3d877c..00000000 --- a/plugins/pstack/skills/why/references/source-playbook.md +++ /dev/null @@ -1,17 +0,0 @@ -# Source playbooks - -The why skill spawns one investigator per available evidence category, each reading a single source-specific playbook below. The playbooks are concrete examples for common MCPs. Adapt them for a different MCP in the same category. - -| Category | Playbook | Example MCP it documents | -|---|---|---| -| Source control history | [`code-archaeology.md`](./sources/code-archaeology.md) | git, `gh` | -| Issue / ticket tracker | [`linear.md`](./sources/linear.md) | Linear (adapt for Jira, GitHub Issues, Plane, Shortcut) | -| Long-form documents | [`notion.md`](./sources/notion.md) | Notion (adapt for Confluence, Google Docs, Coda) | -| Real-time team chat | [`slack.md`](./sources/slack.md) | Slack (adapt for Discord, Microsoft Teams, Mattermost) | -| Infrastructure observability | [`datadog.md`](./sources/datadog.md) | Datadog (adapt for New Relic, Honeycomb, Grafana, Splunk) | -| Error / exception tracking | [`sentry.md`](./sources/sentry.md) | Sentry (adapt for Rollbar, Bugsnag, Airbrake) | -| Product analytics warehouse | [`databricks.md`](./sources/databricks.md) | Databricks SQL (adapt for Snowflake, BigQuery, ClickHouse, dbt) | - -Cross-cutting: - -- [`incident-postmortem.md`](./sources/incident-postmortem.md). Add this if the target code looks defensive (null checks, retry, timeout, rate limit, feature flag, egress guard, OOM handler). diff --git a/plugins/pstack/skills/why/references/sources/code-archaeology.md b/plugins/pstack/skills/why/references/sources/code-archaeology.md deleted file mode 100644 index e3555f80..00000000 --- a/plugins/pstack/skills/why/references/sources/code-archaeology.md +++ /dev/null @@ -1,51 +0,0 @@ -# Code Archaeology (git + in-repo) - -## What this source contains - -- Commit history (messages, dates, authors, diffs) -- PR descriptions, review comments, and discussion threads (via `gh`) -- Inline code comments, TODOs, FIXMEs, deprecation notes -- ADRs (architectural decision records) if the repo keeps them -- Tests, whose names and assertions often encode the edge cases that motivated a change -- Related files modified in the same commits (co-change signal) -- CHANGELOG entries and release notes in the repo -- Issue/ticket IDs in commit messages and PR bodies - -The most trustworthy source, tied directly to the code, and the most complete. Everything that went through the repo should be here. - -## How to search it - -Expand the seed commit list: - -```bash -# History through renames -git log --follow --oneline -- <file> - -# Pickaxe: commits that added or removed this exact text -git log -S '<exact_string_from_code>' -- <file> - -# Or for patterns: -git log -G '<regex>' -- <file> - -# Who wrote each line and when -git blame -L <start>,<end> <file> - -# One commit's full diff -git show <hash> - -# Commits between two points affecting this file -git log <old>..<new> -p -- <file> -``` - -Look for out-of-band docs: - -```bash -# ADRs often live in docs/adr/ or similar -rg -l -i 'architecture.decision' --glob '*.md' - -# TODOs and FIXMEs near the target -rg -n -C2 '(TODO|FIXME|HACK|XXX|NOTE)' <target_file> - -# Related tests -rg -l '<symbol>' --glob '*test*' -``` diff --git a/plugins/pstack/skills/why/references/sources/databricks.md b/plugins/pstack/skills/why/references/sources/databricks.md deleted file mode 100644 index 2770763f..00000000 --- a/plugins/pstack/skills/why/references/sources/databricks.md +++ /dev/null @@ -1,70 +0,0 @@ -# Databricks Analytics & System Tables - -## What this source contains - -Databricks is the product-analytics, data-pipeline, and warehouse-telemetry layer. It complements Datadog. Datadog is the *infra/runtime* view, Databricks is the *product/data* view (what users did, which experiments ran, how feature usage evolved, where a threshold constant came from). - -- **Product analytics events.** `your_warehouse.events.analytics_track_event` (raw) and typed, deduplicated per-event dbt models in `<your_analytics_db>.<schema>.<table>`. User behavior: feature invocations, clicks, accepts/rejects, submissions, client-reported errors. -- **Usage & billing events.** `your_warehouse.events.usage_event` / `<your_analytics_db>.<schema>.stg_usage_events`, `your_warehouse.events.raw_model_event` / `<your_analytics_db>.<schema>.stg_raw_model_events`. For cost- or volume-driven decisions. -- **Experiment / feature-flag data.** Exposure and outcome tables. **Schema is company-specific.** Probe with `SHOW TABLES` before assuming names. -- **System tables.** `system.query.history`, `system.compute.warehouses`, `system.billing.*`, `system.access.audit`. Answer "was this query expensive?", "how often did anyone run this?", "when did warehouse load spike?" -- **dbt lineage.** Models in `<your_analytics_db>.<schema>` reveal what pipelines depend on a table/field. Upstream changes frequently motivate consumer-code changes. -- **Databricks notebooks.** Exploratory analyses engineers wrote before code changes. **Not queryable via the SQL MCP.** If you suspect the rationale lives in a notebook, name it as a gap. - -## How to search it - -Use the Databricks SQL MCP. Primary tool: `execute_sql_read_only`. If it returns a `statement_id`, poll with `poll_sql_result` rather than re-running. - -**Orient before querying.** Schemas are company-specific. Probe before trusting a table name: - -```sql -SHOW TABLES IN <your_analytics_db>.<schema> LIKE '*<keyword>*'; -DESCRIBE TABLE <your_analytics_db>.<schema>.stg_<event>; -``` - -**Time-bound every query.** These tables are huge and unconstrained scans time out. Filter on `_timestamp` (events) or `start_time` (`system.query.history`) with a window bracketing the ship date, typically ~30 days before and after, wider only for strong reason. - -**Prefer typed dbt models over the raw table.** `<your_analytics_db>.<schema>.<table>` is deduplicated, typed, and liquid-clustered. `your_warehouse.events.analytics_track_event` has duplicates and untyped `properties_json`. Model-name pattern: `stg_<source>_<event_name_with_underscores>`, where `<source>` is `app`, `backend`, `website`, or `cli`. Confirm the exact model name with `SHOW TABLES` when the pattern alone doesn't resolve it. Drop to the raw table only when there's no dbt model yet, or you need events from inside the dbt refresh lag. - -**Column conventions on the typed dbt models** (knowing these avoids a `DESCRIBE` round-trip): - -- `_timestamp`, `_id`, `_auth_id`, `_request_id`, `event_name`. Standard on every model -- `properties_<name>`. Typed, underscore-cased event properties (`properties_entrypoint`, `properties_size_bytes`, …) -- `context_team_id`, `context_client_version`, `context_country`, `context_client_os`. Pre-extracted client context - -### Investigation patterns that tend to pay off - -Pick the table + column combination that matches the target: - -1. **Event usage trajectory.** Daily counts on the relevant `stg_*` model across a ±30d window around the PR merge. A step function from zero to steady volume within a day or two of the merge is strong circumstantial evidence the PR launched the feature. A decay to zero suggests a deprecation or deletion. -2. **Guard-rail / defensive-check origin.** Distribution (median / p99 / max) of the relevant `properties_<name>` column in the 14 days *before* the PR. A p99 that matches the target's threshold constant suggests the number was chosen from data. -3. **Experiment / feature-flag lookup.** `SHOW TABLES ... LIKE '*experiment*'` to find the exposure table, then pull exposure counts by variant for the relevant flag key near the PR date. -4. **Query-history evidence for migrations, backfills, or perf rewrites.** `system.query.history` filtered by `statement_text ILIKE '%<table_or_symbol>%'` with a tight `start_time` window surfaces the expensive queries that likely motivated the change (sort by `total_duration_ms` or aggregate `SUM(read_bytes)`, `COUNT(*)`). -5. **dbt lineage.** If the target reads from or writes into a `<your_analytics_db>.<schema>` model, the model's own git history (in this repo) often carries the rationale. Hand that lead back to the git investigator rather than chasing it yourself. - -## What good evidence looks like here - -Beyond the pattern shapes above: - -- An error-classifying event's count drops to near zero in the days after a defensive-code PR. Suggests the PR resolved that error class -- An exposure table row names the target's feature-flag key with a "shipped" / "concluded" decision around the PR ship date - -## Common pitfalls - -- **Instrumented ≠ caused.** An event's existence means someone cared enough to log it, not that the target code exists *because* of it. Pair with a PR/commit citation from the git investigator before claiming causation. -- **Silent instrumentation changes.** A step function in event volume may mean a new event started being logged, not that user behavior changed. Check for instrumentation PRs in the same window before reading the ramp as a feature-launch signal. -- **Schema drift.** Event properties evolve. A column on the typed dbt model today may not have existed when the target was written. Older data may carry the property only inside raw `properties_json`. -- **dbt refresh lag.** `<your_analytics_db>.<schema>.*` is rebuilt on a schedule (often hourly/daily). For events from the last few hours, fall back to `your_warehouse.events.*` and deduplicate by `_id`. -- **Company-specific tables.** Experiment, feature-flag, billing, and usage tables vary. Reporting a result from a table whose existence you never confirmed is a classic failure mode. Probe with `SHOW TABLES` / `DESCRIBE TABLE` first. -- **Retention cliff.** If the relevant window predates the table's retention or the dbt model's creation date, that's a *gap*, not a null result. Name it explicitly so the synthesizer doesn't read "no results" as "no activity." -- **Notebooks aren't queryable.** The SQL MCP can't see Databricks notebooks. If you suspect the rationale lives in one, return a gap. - -## What to return - -For each relevant finding: -- Type (product event / experiment exposure / usage or billing event / system-table row / dbt model) -- Fully-qualified table name and the exact query you ran -- Time window queried -- Compact numeric summary (counts, percentiles, first/last-seen timestamps). **Don't dump raw rows.** -- Temporal correlation with the target's ship date (e.g., "first row 2024-08-15, PR #49074 merged 2024-08-14") -- Relevance + strength: direct / circumstantial / weak diff --git a/plugins/pstack/skills/why/references/sources/datadog.md b/plugins/pstack/skills/why/references/sources/datadog.md deleted file mode 100644 index 536466dd..00000000 --- a/plugins/pstack/skills/why/references/sources/datadog.md +++ /dev/null @@ -1,97 +0,0 @@ -# Datadog Telemetry - -## What this source contains - -Datadog holds the runtime record, what actually happened in production, as opposed to what was planned or discussed. - -- **Metrics.** Counters, gauges, histograms instrumented by the team. A metric's *presence* is itself evidence that someone thought the number worth watching. -- **Monitors & alerts.** Conditions the team decided warranted waking someone up. A monitor firing on `rate_limit_hit > 10/min` is direct evidence the team worried about that threshold. -- **Dashboards.** Curated views of what the team considers important for a subsystem. -- **APM traces & spans.** Request-level runtime data, for "why is this slow" / "why is there a timeout here" questions. -- **Logs.** High-volume event records, often holding the error conditions that motivated defensive code. -- **Incidents.** Formal incident records with timelines and linked postmortems. -- **Notebooks.** The team's exploratory investigations, often with hypotheses and analyses. - -## How to search it - -Use the Datadog MCP. Start broad, then narrow. - -1. **Identify the owning service(s).** - - ``` - search_datadog_services (filter by name or team) - search_datadog_service_dependencies (see upstream/downstream) - ``` - -2. **Dashboards and monitors first.** - - ``` - search_datadog_dashboards (query: feature name, service name, symbol) - search_datadog_monitors (same queries) - ``` - - When a dashboard or monitor covers the target, note its queries and watched thresholds. The threshold is frequently the answer to "why is this clamped at N?" - -3. **Metrics around the target.** - - ``` - search_datadog_metrics (by name pattern, e.g., the feature or symbol) - get_datadog_metric_context (metadata: description, units, tags) - get_datadog_metric (timeseries; "was there a spike around the PR date?") - ``` - - Correlating a metric's trajectory with the target's add/change date is strong supporting evidence: "the `payment_timeout` metric spiked 2023-11-03, and the retry logic merged 2023-11-06." - -4. **Logs. Narrow, don't dump.** - - ``` - search_datadog_logs (raw log patterns near the target, set use_log_patterns=true) - analyze_datadog_logs (SQL-style aggregations, only when you need counts) - ``` - - Search with symbols, error strings, or feature names. **Strongly prefer time-bounded queries** (e.g., 30 days before/after the change). - -5. **APM spans and traces.** - - ``` - aggregate_spans (stats: "how often does this endpoint fail?") - search_datadog_spans (inspect individual spans) - get_datadog_trace (a specific trace ID) - ``` - - Useful for timeouts, retries, slow paths, and cross-service behavior. - -6. **Incidents.** - - ``` - search_datadog_incidents (by title, team, date range) - get_datadog_incident (full detail for a specific incident) - ``` - - If the target looks defensive, search for incidents around the time it was added. An incident whose timeline includes "added defensive check for X" is near-direct evidence. - -## What good evidence looks like here - -- A monitor whose query and threshold match the constraint the code enforces (code clamps to 100, monitor alerts when requests exceed 100/min) -- A dashboard created by the target's author, with widgets that correspond to what the code measures or guards against -- A metric showing a production spike immediately before the code was merged, and stable values after -- An incident record referencing the target code, the same symbols, or the same error strings -- Logs showing a specific error pattern the defensive code would prevent, timestamped in the window before the change - -## Common pitfalls - -- **Correlation is not causation.** A spike before a PR and stabilization after is suggestive, not definitive, since other changes may have landed in the same window. Check neighboring PRs. -- **Overfitting to the chart you found.** A chart reflects its maker's framing. A chart named "retry success rate" is evidence the team cared about retry success, not that it's why a specific line of code exists. -- **Vanished telemetry.** Metrics can be renamed, deleted, or have short retention. If you can't find data from the relevant window, that's a gap, not a null result. -- **Noise at scale.** Narrow log searches by service, tag, and time window aggressively. Use `analyze_datadog_logs` to aggregate rather than dumping raw logs. -- **Instrumented != caused.** A metric shows someone cared enough to measure something, not that the code was added *because* of it. Cross-reference with commit/PR dates. - -## What to return - -For each relevant item: -- Type (dashboard / monitor / metric / log pattern / trace / incident / notebook) -- Title or name -- Link or identifier (dashboard ID, monitor ID, metric name, incident ID) -- Owner/author and created/modified date -- The specific condition, query, or quote that bears on the question (verbatim where possible) -- Relevance: what this suggests about the target code, and how strong the connection is diff --git a/plugins/pstack/skills/why/references/sources/incident-postmortem.md b/plugins/pstack/skills/why/references/sources/incident-postmortem.md deleted file mode 100644 index e7397e7e..00000000 --- a/plugins/pstack/skills/why/references/sources/incident-postmortem.md +++ /dev/null @@ -1,5 +0,0 @@ -# Incident & Postmortem Context - -- **Linear**: look for tickets labeled `incident`, `sev-*`, `postmortem-action-item`, `reliability` -- **Slack**: search `#sev-*` and `#incident-*` channels around the dates the target code was added -- **Git**: commits with messages like "fix for incident", "add defensive check", "revert" followed by "re-apply with..." are strong signals diff --git a/plugins/pstack/skills/why/references/sources/linear.md b/plugins/pstack/skills/why/references/sources/linear.md deleted file mode 100644 index 899c643c..00000000 --- a/plugins/pstack/skills/why/references/sources/linear.md +++ /dev/null @@ -1,48 +0,0 @@ -# Linear Tickets - -## What this source contains - -- Issues describing features, bugs, and their motivation -- Project docs attached to issues (often PRDs or specs) -- Parent/sub-issue relationships (broader initiative → specific tickets) -- Comments on issues (clarifications, scope changes, "why we're doing this" rationale) -- Labels (e.g., `compliance`, `customer-request`, `perf`) that signal the type of motivation -- Status updates that explain scope changes -- Attachments and linked GitHub PRs - -Linear is where the product/business context often lives: the "we're doing this because customer X asked" or "this is for the Q3 compliance initiative" layer. - -## How to search it - -Use the Linear MCP. - -1. **Start with linked tickets.** If the seed commits or PRs reference ticket IDs (e.g., `ENG-1234`, `[BUG-567]`), fetch those first with `get_issue`. Read the full issue including comments. -2. **List related issues by keyword.** Use `list_issues` with text search for the feature name, key symbol, or business term. Try multiple phrasings. -3. **Walk the issue tree.** If you land on a sub-issue, fetch its parent. Sub-issues are tactical. Parents often carry the "why." -4. **Read project docs.** If the issue belongs to a project, use `get_project` and check attached docs. Project-level documents are where specs and rationale are most often captured. -5. **Check labels and milestones.** Labels hint at the category of motivation (customer-request, incident-followup, compliance). Milestones tie work to deadlines, which often reveal motivation. - -## What good evidence looks like here - -- An issue description stating the business problem: "Customer Acme needs X because of their SOC2 audit" -- A comment recording a decision: "We decided to go with approach B because approach A would require touching the billing service" -- A parent issue titled like an initiative: "Q3 Enterprise Readiness" or "Reduce Payment Failures" -- An attached PRD or spec -- Labels like `customer:acme`, `incident-followup`, `compliance`, `perf-regression` - -## Common pitfalls - -- **Scope drift.** The ticket the PR references may have been closed and reopened with a different scope. Read the whole history. -- **Mechanical templates.** Some teams require "Why" sections but fill them with boilerplate. Generic text ("improve user experience") is probably not a real answer. -- **Stale tickets.** Old tickets often reflect a version of the plan that changed. Check dates and cross-reference with the code's ship date. -- **Closed-as-duplicate chains.** Follow the duplicate-of relationships back to the canonical ticket. -- **Private workspace content.** If you can't access an issue, note that as a gap rather than guessing. - -## What to return - -For each relevant ticket: -- Ticket ID and title -- The problem/motivation quoted from the description or comments (not paraphrased. The synthesizer needs the exact text to cite) -- Labels, parent issue, project -- Author, created date, closed date -- Link to the ticket if available diff --git a/plugins/pstack/skills/why/references/sources/notion.md b/plugins/pstack/skills/why/references/sources/notion.md deleted file mode 100644 index d16230a4..00000000 --- a/plugins/pstack/skills/why/references/sources/notion.md +++ /dev/null @@ -1,55 +0,0 @@ -# Notion Docs - -## What this source contains - -- PRDs (product requirement documents) -- Technical specs and RFCs -- Architectural decision records (ADRs) -- Meeting notes from design reviews -- Team pages with domain context -- Postmortems from incidents -- Runbooks that may explain defensive code -- Strategy documents that set priorities - -Notion is where "why" often lives in long-form before it becomes code. A significant feature usually has a doc. - -## How to search it - -Use the Notion MCP. - -1. **Keyword searches with `notion-search`.** Try: - - The feature name - - Key symbols / class names from the target code - - Author handles (design docs are often authored before the code lands) - - Error strings or user-visible terms - - Time-bounded queries if you know when the code shipped -2. **Fetch candidate pages with `notion-fetch`.** Read the full content, not the preview. Rationale is often buried mid-document. -3. **Follow backlinks and child pages.** Design docs often have sub-pages for alternatives considered, appendices, or implementation notes. -4. **Check related databases.** `notion-query-data-sources` and `notion-query-meeting-notes` can surface meeting notes that discussed the decision. -5. **Search author-specific spaces.** If the PR author has a personal notebook (common at some companies), it may hold exploratory thinking that preceded the code. - -## What good evidence looks like here - -- A PRD with a "Problem statement" or "Motivation" section that matches the target code's purpose -- An "Alternatives considered" or "Rejected approaches" section -- A postmortem that names the target code as the fix for a specific incident -- Meeting notes that record "we decided X because Y" and tie to the same author/date range as the PR -- An ADR template filled out non-trivially (status, context, decision, consequences) - -## Common pitfalls - -- **Outdated docs.** Specs are often written before implementation and not updated. The doc may describe a plan that changed. Cross-check against the actual PR. -- **Doc vs. reality drift.** A spec may say "we'll do X" but the code actually does Y. Flag the divergence. The synthesizer will surface the contradiction. -- **Boilerplate templates.** Some orgs require a "Why" section that gets filled with fluff. Look for specificity. -- **Unlinked docs.** The most relevant doc may not be linked from anywhere. Broad keyword searches help. -- **Multiple drafts.** If a topic has multiple docs, find the one that was finalized or most recently updated. Check dates. -- **Access-restricted pages.** If you can't access a page, note it as a gap. - -## What to return - -For each relevant doc: -- Title and URL -- Authors and last-updated date -- The motivation text (verbatim quote), with page/section location -- Relevant linked pages (so the synthesizer can cite them) -- Whether the doc was finalized or draft diff --git a/plugins/pstack/skills/why/references/sources/sentry.md b/plugins/pstack/skills/why/references/sources/sentry.md deleted file mode 100644 index 8200fd9f..00000000 --- a/plugins/pstack/skills/why/references/sources/sentry.md +++ /dev/null @@ -1,66 +0,0 @@ -# Sentry Error History - -## How to search it - -Use the Sentry MCP. - -1. **Orient.** If you don't know the project slug and organization: - - ``` - find_organizations - find_projects - ``` - -2. **Search for issues related to the target.** - - ``` - search_issues (natural language, e.g., "errors in PaymentService timeout", "unhandled exceptions in uploadFile") - ``` - - Build queries from the exception class names the target handles, its function or class name, the error message strings it checks for, and its file path. - -3. **Narrow by release and time window.** - - ``` - search_issue_events (filter by release, time, environment, trace ID, tags) - get_issue_tag_values (for an issue, see distribution across versions, users, environments) - ``` - - For a suspected issue, check **first seen** and **last seen** (does the stop line up with the target's ship date?), the **affected releases** (which saw it, and which was the fix?), and the **frequency trajectory** (did it spike, then get resolved?). - -4. **Pull the full event for context.** - - ``` - get_sentry_resource (pass a Sentry URL or type+ID) - ``` - - Does the stack trace pass through the target code? Do the tags and breadcrumbs match the conditions the target defends against? - -5. **Check releases that landed near the target.** - - ``` - find_releases (around the commit date of the target) - ``` - - Cross-reference release version with the PR's merge date. - -6. **Use Seer sparingly.** - - ``` - analyze_issue_with_seer - ``` - - Seer's AI root-cause analyses are a hypothesis generator. Treat them as inference, not authoritative. The actual events and stack traces are the primary evidence. - -## What to return - -For each relevant issue: -- Issue ID and title -- Project and organization -- First seen / last seen timestamps -- Event count (and sampling rate if known) -- Affected releases -- A representative stack trace snippet showing relevance to the target (verbatim excerpt, not summary) -- First/last-seen correlation with the target's ship date -- Link to the issue -- Any author comments or resolution notes diff --git a/plugins/pstack/skills/why/references/sources/slack.md b/plugins/pstack/skills/why/references/sources/slack.md deleted file mode 100644 index cadd5618..00000000 --- a/plugins/pstack/skills/why/references/sources/slack.md +++ /dev/null @@ -1,17 +0,0 @@ -# Slack Conversations - -## How to search it - -Slack MCP tools vary. Check which Slack MCP is available and inspect its tool schema first. It may require `mcp_auth`. If authentication fails, stop and report the gap. - -1. **Author-bounded search.** Messages from the PR author around the PR merge date. Limits scope dramatically and often hits gold. -3. **PR URL search.** Slack often links PRs when they're reviewed or discussed. Search for the PR URL (or just `/pull/<number>`). -4. **Error string search.** If the code handles a specific error, search for the error string. Incident threads often surface. - -## Common pitfalls - -- **Channel archaeology limits.** Very old messages may be gone due to retention policies. If you can't find anything before a certain date, note the retention cliff. -- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them. That's a known limitation. -- **Speculative jokes as "decisions."** Slack is casual. "Lol just do the thing" isn't a decision, even if it preceded the commit. Look for considered discussion. -- **Context collapse in single messages.** Without the thread, a single message often reads differently than in context. Always fetch threads. -- **Auth failures.** If the MCP isn't authenticated, stop. Don't make up findings. Report that Slack wasn't searchable. diff --git a/plugins/pstack/skills/why/references/synthesizer-prompt.md b/plugins/pstack/skills/why/references/synthesizer-prompt.md deleted file mode 100644 index 287a350c..00000000 --- a/plugins/pstack/skills/why/references/synthesizer-prompt.md +++ /dev/null @@ -1,129 +0,0 @@ -# Synthesizer Prompt Template - -Fill in the placeholders. - ---- - -You are answering a "why" question about a piece of code by synthesizing findings from investigators who searched different historical sources (source control, issue / ticket tracker, long-form documents, real-time team chat, infrastructure observability, error / exception tracking, product analytics warehouse, and code comments). Produce a confidence-weighted, evidence-cited narrative that says honestly what the evidence supports, and just as honestly what it doesn't. - -## The Question - -> {QUESTION} - -## The Code Anchor - -**Target files:** {FILES_WITH_LINE_RANGES} - -**Key symbols:** {SYMBOLS} - -## Investigator Findings - -{ALL_INVESTIGATOR_FINDINGS} - -## Sources That Weren't Searched - -{SKIPPED_SOURCES_WITH_REASONS} - -## Epistemics Framework - -You MUST follow `references/epistemics.md`. Read it in full before writing. The key rules: - -1. Every claim must sit in one tier: **Direct**, **Supported**, **Inferred**, **Speculative**, **Unknown**. The tier sets its section and its phrasing. -2. Every Direct/Supported claim must have a citation (PR #, ticket ID, doc URL, chat permalink, commit hash, or file:line). -3. Inferred and Speculative claims must use hedged language ("appears to", "likely", "suggests", "one possibility is"). -4. Never cite code as evidence for its own intent. -5. Document gaps. Don't fill them with plausible-sounding guesses. -6. Treat a hypothesis embedded in the user's question as a candidate, not a conclusion. Check it independently. - -## Instructions - -1. **Read all investigator findings** and weigh the evidence yourself. Investigators gathered raw evidence, not conclusions. -2. **Merge overlaps.** When several investigators cite the same PR, ticket, or doc, give it one authoritative reference. -3. **Surface contradictions.** When two items disagree, show both. Don't pick one. -4. **Calibrate each claim.** Find its evidence and tier. Direct: cite it and state it plainly. Inferred: hedge it and show the inference. Speculative: mark it. No evidence: put it in the gaps. -5. **Verify citations by spot-checking.** If you're uncertain a cited item exists or says what the investigator claims, check it by reading the codebase or calling MCP tools. Don't propagate errors. Do not write files, commit, or modify external state. -6. **Don't overreach.** The user will act on this. Leave an open question open rather than fill it with a confident guess. - -## Output Format - -Write for the user, in this exact structure: - ---- - -### The Question - -Restate the user's question in one or two sentences. - -### The Code in Question - -File paths, line ranges, key symbols. Two or three lines to orient a cold reader. - -### What We Found - -Claims with textual evidence, each quoted or paraphrased and cited precisely: - -- **[Direct]** {Claim}. Source: [PR #123](url) / ticket ID / file:line. {Brief quote or paraphrase.} -- **[Supported]** {Claim}. Evidence: {list of items and what each contributes}. - -`[Direct]` is single-source, explicit evidence. `[Supported]` is multiple indirect items converging on a conclusion. - -### What We Can Reasonably Infer - -Claims stated nowhere but well-supported by indirect evidence. Each bullet must make the inference chain visible ("Given A and B, it's likely that C") and must use hedged language ("appears to", "likely", "suggests", "is consistent with"): - -- **[Inferred]** {Hedged claim}. Reasoning: {the specific evidence and the inference step}. - -Skip this section if there's nothing to infer. - -### Competing Hypotheses - -If the evidence fits multiple stories, present each. Don't force a winner the record doesn't support. For each hypothesis: - -- **Hypothesis:** {one-sentence statement} -- **Evidence for:** {specific items} -- **Evidence against or missing:** {what would need to be true but isn't, or what counter-signals exist} - -Skip this section if there's a single clear answer. - -### What We Don't Know - -Specific gaps: "We searched the issue tracker for [query1], [query2], [query3] and found no issue discussing the rate-limit threshold", not "We don't know why." Include: - -- Questions that went unanswered -- Searches that returned nothing -- Sources that were unavailable, and why (such as a missing real-time team chat MCP) -- People who would likely know but whom you can't ask - -### Sources Consulted - -What was actually searched, so the user can judge coverage and redirect: - -- **Source control history**: {file paths}, {number of commits reviewed}, PRs #{numbers}, and code comments searched. Or "Not searched. This should not happen because git and `gh` are always expected." -- **Issue / ticket tracker**: {ticket IDs and keyword searches}. Or "Not searched. No matching MCP available in this environment." -- **Long-form documents**: {page titles and search queries}. Or "Not searched. No matching MCP available in this environment." -- **Real-time team chat**: {channels searched, date ranges, queries}. Or "Not searched. No matching MCP available in this environment." -- **Infrastructure observability**: {dashboards, monitors, metrics, logs, traces, or incidents searched}. Or "Not searched. No matching MCP available in this environment." -- **Error / exception tracking**: {issues, events, or releases searched}. Or "Not searched. No matching MCP available in this environment." -- **Product analytics warehouse**: {fully-qualified tables queried, the time windows, and the numeric summaries (counts, percentiles, first/last-seen timestamps) that bore on the question}. Or "Not searched. No matching MCP available in this environment." - -### Confidence Summary - -One or two sentences on overall confidence, e.g.: - -> "The core rationale (A) is well-supported by direct PR and ticket evidence. The specific threshold value (100) is inferred from the surrounding context but not explicitly documented. The question of whether this was driven by a customer request could not be answered. No relevant issue tracker or long-form doc content surfaced, and real-time team chat search was unavailable." - ---- - -## Quality Check Before Returning - -Revise if any item fails: - -1. Does every claim in "What We Found" have a citation? If not, add one or move it to "Inferred" or "Hypotheses." -2. Is the phrasing tier-appropriate? (Direct claims can use "because". Inferred claims cannot.) -3. Did you surface every contradiction you noticed, or quietly pick one? -4. Does "What We Don't Know" name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps. -5. Did you check any hypothesis embedded in the question against the evidence rather than rubber-stamp it? -6. Did you cite code as evidence for its own intent? Remove it. Code is mechanics, not motivation. -7. Is the tone calibrated? A confident-sounding answer on weak evidence is the exact failure this skill exists to prevent. - -The value of this output is its honesty, not its authority. A reader who takes it to the original author, an engineering lead, or a product manager should know what's known, what's inferred, and what's missing, so they can ask the right follow-up questions. Optimize for being useful, not for looking decisive. diff --git a/tests/fixtures/t3-catalog.json b/tests/fixtures/t3-catalog.json index 3d04450e..dbaa6839 100644 --- a/tests/fixtures/t3-catalog.json +++ b/tests/fixtures/t3-catalog.json @@ -42,6 +42,10 @@ { "id": "fastMode", "type": "boolean" } ] }, + { + "id": "claude-fable-5-2", + "options": [{ "id": "effort", "values": ["low", "medium", "high", "xhigh", "max", "ultrathink"] }] + }, { "id": "claude-fable-5-1", "options": [{ "id": "effort", "type": "select", "options": [{ "id": "low" }, { "id": "medium" }, { "id": "high" }, { "id": "xhigh" }, { "id": "max" }] }] @@ -52,6 +56,14 @@ "canRunCrossProviderChildTask": true, "constraints": [] }, + { + "providerInstanceId": "antigravity", + "driverKind": "antigravity", + "models": [{ "id": "gemini-4-carbon", "options": [{ "id": "thinking_level", "values": ["low", "medium", "high"] }] }], + "canRunChildTask": true, + "canRunCrossProviderChildTask": true, + "constraints": [] + }, { "providerInstanceId": "cursor", "driverKind": "cursor", diff --git a/tests/generate.test.mjs b/tests/generate.test.mjs index 3ee9877d..59ae0bd1 100644 --- a/tests/generate.test.mjs +++ b/tests/generate.test.mjs @@ -68,24 +68,32 @@ describe("locators", () => { describe("regions", () => { test("every skill a role names gets that role's tier default stamped in its Models section", () => { - const marked = { ...models, tiers: { default: "x/marker-default", strongest: "x/marker-strongest", panel: ["a/claude-p", "b/gpt-p"] } }; + const marked = { + ...models, + tiers: { default: "x/marker-default", strongest: "x/marker-strongest", fast: "x/marker-fast", panel: ["a/claude-p", "b/gpt-p"] }, + }; for (const skill of new Set(models.roles.map((r) => r.skill))) { const file = `plugins/pstack/skills/${skill}/SKILL.md`; const stamped = applyRegions(file, readFileSync(join(repoRoot, file), "utf8"), marked, { strict: true }); for (const role of models.roles.filter((r) => r.skill === skill)) { - const expected = { default: "`x/marker-default`", strongest: "`x/marker-strongest`", panel: "`a/claude-p`, `b/gpt-p`" }[role.tier]; + const expected = { + default: "`x/marker-default`", + strongest: "`x/marker-strongest`", + fast: "`x/marker-fast`", + panel: "`a/claude-p`, `b/gpt-p`", + }[role.tier]; expect(stamped).toContain(`- ${role.role}: ${expected}`); } } }); test("applyRegions stamps in place and is idempotent", () => { - const file = "plugins/pstack/skills/how/SKILL.md"; - const text = "# how\n\n## Models\n\nstale\n\n## After\nkeep\n"; + const file = "plugins/pstack/skills/swarm/SKILL.md"; + const text = "# swarm\n\n## Models\n\nstale\n\n## After\nkeep\n"; const once = applyRegions(file, text, models, { strict: true }); expect(once).not.toContain("stale"); expect(once).toContain("## After\nkeep\n"); - expect(once).toContain("- how explorer: `claudeAgent/claude-opus-5-5 effort=xhigh`"); + expect(once).toContain("- swarm workers: `claudeAgent/claude-opus-5-5 effort=high fastMode=true`"); expect(applyRegions(file, once, models, { strict: true })).toBe(once); }); @@ -256,17 +264,17 @@ describe("deriveT3", () => { }); test("appends and stamps a Models section when upstream has none, naming the sheet and the entry grammar", () => { - const out = deriveT3("plugins/pstack/skills/how/SKILL.md", front(""), models); + const out = deriveT3("plugins/pstack/skills/swarm/SKILL.md", front(""), models); expect(out).toContain("body\n\n## Models\n\nRole defaults on T3, stamped from `plugins/pstack/models.json`."); expect(out).toContain("`t3-pstack-models.md`"); expect(out).toContain("It splits at its first `/`"); - expect(out.endsWith("- how explainer: `claudeAgent/claude-opus-5-5 effort=xhigh`\n")).toBe(true); - expect(deriveT3("plugins/pstack/skills/how/SKILL.md", out, models)).toBe(out); + expect(out.endsWith("- swarm workers: `claudeAgent/claude-opus-5-5 effort=high fastMode=true`\n")).toBe(true); + expect(deriveT3("plugins/pstack/skills/swarm/SKILL.md", out, models)).toBe(out); }); test("names the alias a released sheet may still use", () => { const out = deriveT3("plugins/pstack/skills/poteto-mode/SKILL.md", front("", "poteto-mode"), models); - expect(out).toContain("- hardest tasks: `claudeAgent/claude-fable-5-1 effort=xhigh` (a `strongest judgment` line counts as this role)"); + expect(out).toContain(`- hardest tasks: \`${models.tiers.strongest}\` (a \`strongest judgment\` line counts as this role)`); }); test("a file no region names passes through", () => { @@ -358,13 +366,13 @@ describe("plan, changes, apply", () => { test("a hand edit to a stamped Models line or to the sheet block is restored", () => { const root = repoCopy(); - const how = "plugins/pstack/skills/how/SKILL.md"; + const swarm = "plugins/pstack/skills/swarm/SKILL.md"; const setup = "plugins/pstack/skills/setup-pstack/SKILL.md"; const text = (rel) => readFileSync(join(root, rel), "utf8"); - writeFileSync(join(root, how), text(how).replace(/^- how explorer: .*$/m, "- how explorer: stale")); + writeFileSync(join(root, swarm), text(swarm).replace(/^- swarm workers: .*$/m, "- swarm workers: stale")); writeFileSync(join(root, setup), text(setup).replace(/^bug-fix: .*$/m, "bug-fix: stale")); const { files } = plan(root); - for (const rel of [how, setup]) expect(files[rel]).toBe(readFileSync(join(repoRoot, rel), "utf8")); + for (const rel of [swarm, setup]) expect(files[rel]).toBe(readFileSync(join(repoRoot, rel), "utf8")); }); test("apply rewrites only the files whose bytes differ", () => { diff --git a/tests/install.test.mjs b/tests/install.test.mjs index c1ab7198..864e5666 100644 --- a/tests/install.test.mjs +++ b/tests/install.test.mjs @@ -30,7 +30,7 @@ import { discoverHomes } from "../tools/install/homes.mjs"; import { doctorSheet, moveSheet } from "../tools/install/sheet.mjs"; const repoRoot = fileURLToPath(new URL("..", import.meta.url)); -const { roles, tiers } = JSON.parse(readFileSync(join(repoRoot, "plugins/pstack/models.json"), "utf8")); +const { roles, tiers, retired } = JSON.parse(readFileSync(join(repoRoot, "plugins/pstack/models.json"), "utf8")); const FIX = "rerun `npx -y github:chhoumann/t3-pstack install`"; const scratch = []; @@ -575,4 +575,16 @@ describe("the model sheet", () => { fix: "run /t3-pstack:setup-pstack in a T3 thread", }); }); + + test("doctor passes a sheet that still carries the retired how and why lines", () => { + const { homes, sheet } = machine(); + mkdirSync(join(sheet, ".."), { recursive: true }); + const released = ["bug-fix: claudeAgent/claude-opus-5-5 effort=xhigh", "how explorer: claudeAgent/claude-opus-5-5 effort=medium"]; + writeFileSync(sheet, `${released.join("\n")}\nwhy synthesizer: claudeAgent/claude-opus-5-5 effort=xhigh\n`); + expect(doctorSheet(sheet, homes, { catalog: null, roles, tiers, retired, hint: FIX })[0]).toEqual({ + name: "machine sheet valid", + ok: true, + detail: "every line parses (pass --catalog to check targets)", + }); + }); }); diff --git a/tests/models.test.mjs b/tests/models.test.mjs index 7b318bb2..6dd8ff99 100644 --- a/tests/models.test.mjs +++ b/tests/models.test.mjs @@ -37,7 +37,7 @@ describe("parseModels", () => { }; const role = (policy, label) => policy.roles.find((r) => r.role === label); - test.each(["default", "strongest", "panel"])("a missing %s tier throws naming it", (tier) => { + test.each(["default", "strongest", "fast", "panel"])("a missing %s tier throws naming it", (tier) => { expect(parse((p) => delete p.tiers[tier])).toThrow(`models.json: tiers has no "${tier}"`); }); @@ -55,7 +55,7 @@ describe("parseModels", () => { test("a single-model tier holds one entry and the panel a list of two families", () => { expect(parse((p) => (p.tiers.default = [p.tiers.default]))).toThrow('models.json: tier "default" must be one entry, not a list'); - expect(parse((p) => (p.tiers.panel = ["claudeAgent/claude-opus-5-5", "claudeAgent/claude-fable-5-1"]))).toThrow( + expect(parse((p) => (p.tiers.panel = ["claudeAgent/claude-opus-5-5", "codex_pool/claude-sonnet-5-5"]))).toThrow( "models.json: the panel needs at least two model families", ); expect(parse((p) => (p.tiers.panel = ["codex/gpt-6.1-sol", "codex/gpt-6.1-sol"]))).toThrow( @@ -70,22 +70,27 @@ describe("parseModels", () => { }); test("a duplicate role label or alias throws naming it", () => { - expect(parse((p) => p.roles.push({ ...role(p, "how explorer") }))).toThrow('models.json: role "how explorer" appears twice'); + expect(parse((p) => p.roles.push({ ...role(p, "swarm workers") }))).toThrow('models.json: role "swarm workers" appears twice'); expect(parse((p) => (role(p, "bug-fix").alias = "strongest judgment"))).toThrow( 'models.json: role "strongest judgment" appears twice', ); }); test("a role whose skill directory does not exist throws naming both", () => { - expect(parse(() => {}, (skill) => skill !== "why")).toThrow( - 'models.json: role "why investigators" names skill "why", which has no SKILL.md', + expect(parse(() => {}, (skill) => skill !== "swarm")).toThrow( + 'models.json: role "swarm workers" names skill "swarm", which has no SKILL.md', ); }); + + test("a retired label that is still a role throws, so a live line is never skipped", () => { + expect(parse((p) => p.retired.push("swarm workers"))).toThrow('models.json: "swarm workers" is both a role and retired'); + expect(parse((p) => delete p.retired)).toThrow('models.json: "retired" must be a list'); + }); }); describe("role labels reach the prose", () => { - // The prose may hyphenate a label ("how-explorer" for the sheet's - // "how explorer") and names only the first segment of a comma-joined label. + // The prose may hyphenate a label ("swarm-workers" for the sheet's + // "swarm workers") and names only the first segment of a comma-joined label. const normalize = (text) => text.toLowerCase().replace(/[-\s]+/g, " "); function skillProse(skill) { diff --git a/tests/sync.test.mjs b/tests/sync.test.mjs index 58b4a9d1..bf7e9fb3 100644 --- a/tests/sync.test.mjs +++ b/tests/sync.test.mjs @@ -119,18 +119,28 @@ describe("applySubstitutions", () => { test.each([ [ "skills/how/SKILL.md", - "Every spawn is a Task subagent with `subagent_type: generalPurpose` and `readonly: true`.", - 'Every spawn is a `delegate_task` child with `role: "research"` and a brief that says to inspect only and change no file.', + "Spawn one Task subagent with `subagent_type: generalPurpose` and `readonly: true` that explores and explains in one pass.", + 'Spawn one `delegate_task` child with `role: "research"` that explores and explains in one pass. Leave `target` unset, so it runs on this chat\'s model.', ], [ - "skills/why/SKILL.md", - "Each spawn below names a role line in the `pstack-models.mdc` rule and a default. Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message.", - "Each spawn below names a role line in the model sheet and a default. Set `target` from that line's entry, or from the default if the sheet or the line is missing. Leave `target` unset when the value is `auto` or `inherit-parent`. If `delegate_task` rejects an entry, use the default and say so. If it rejects the default, use another target of the same family from `orchestrator_capabilities`.", + "skills/reflect/SKILL.md", + "Each reviewer and the synthesizer name a role line in the `pstack-models.mdc` rule and a default. Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message.", + "Each reviewer and the synthesizer name a role line in the model sheet and a default. Set `target` from that line's entry, or from the default if the sheet or the line is missing. Leave `target` unset when the value is `auto` or `inherit-parent`. If `delegate_task` rejects an entry, use the default and say so. If it rejects the default, use another target of the same family from `orchestrator_capabilities`.", + ], + [ + "skills/recall/SKILL.md", + "Spawn one investigator subagent per source, in agent mode because readonly strips MCP access, and ask each", + "Spawn one investigator per source, each a `delegate_task` child with full tool access, MCP included, and ask each", ], [ "skills/arena/SKILL.md", - "Families go by prefix: `claude-*`, and `grok-*` with `cursor-grok-*` and `composer-*`. A refused `composer-*` entry runs on `grok-4.7-xhigh-fast`.", - "A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `grok`, whatever provider instance serves it.", + "Families go by prefix, and the longest matching prefix wins: `claude-fable-*`, `claude-*`, and `gemini-*`. Drop a leading `cursor-` before you compare. Any other slug's family is its text before the first hyphen. A family's default is its entry in the default list above.", + "A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `gemini`, whatever provider instance serves it, except that Fable (`claude-fable-*`) is its own family.", + ], + [ + "skills/poteto-mode/SKILL.md", + "If the rule has no `# defaults: 2` line, an older setup wrote it.", + "If the model sheet has no `# defaults: 2` line, an older setup wrote it.", ], [ "skills/interrogate/SKILL.md", @@ -171,7 +181,7 @@ describe("applySubstitutions", () => { // The T3 behavior the port adds on an upstream anchor: each must survive. test.each([ ["skills/poteto-mode/SKILL.md", "Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a \"done\" summary.", ["**Dispatch on T3.**", "dispatch ledger", "`BLOCKED: independent review`", "`clientRequestId`", "you are a leaf", "`isolation: \"worktree\"`", "`Unable to resolve the parent checkout commit`"]], - ["skills/arena/SKILL.md", "With the default pool, a Claude parent gets `grok-4.7-xhigh-fast`. A parent from any other family gets `claude-opus-5-5-xhigh` first.", ["no model scores its own work"]], + ["skills/arena/SKILL.md", "With the default pool, a Claude parent gets `gemini-4-carbon-high`. A parent from any other vendor gets `claude-fable-5-2-high` first, then `claude-opus-5-5-high-fast`.", ["no model scores its own work"]], ["skills/poteto-mode/playbooks/babysit.md", "Run `drive` and `background` under `/loop` in dynamic mode.", ["--timeout 540", "watch_pull_request", "--settle"]], ["skills/poteto-mode/playbooks/autopilot-full.md", "Each owner is a Cursor cloud agent that builds, opens its PR", ["`delegate_task` child", "`isolation: \"worktree\"`", "t3_thread_send"]], ["skills/no-comments/SKILL.md", '1. Spawn `Task` with `subagent_type: "comment-sicko"`. Pass the scope.', ["<plugin root>/agents/comment-sicko.md", "no worktree"]], diff --git a/tests/t3-sheet.test.mjs b/tests/t3-sheet.test.mjs index 9001a98c..22661d49 100644 --- a/tests/t3-sheet.test.mjs +++ b/tests/t3-sheet.test.mjs @@ -16,8 +16,8 @@ const root = fileURLToPath(new URL("..", import.meta.url)); const script = join(root, "plugins/pstack/skills/setup-pstack/scripts/t3-sheet.mjs"); const catalogPath = join(root, "tests/fixtures/t3-catalog.json"); const catalog = JSON.parse(readFileSync(catalogPath, "utf8")); -const { roles, tiers: defaults } = loadModels(); -const check = (text, over = catalog) => checkSheet(parseSheet(text), { roles, defaults, catalog: over }); +const { roles, tiers: defaults, retired } = loadModels(); +const check = (text, over = catalog) => checkSheet(parseSheet(text), { roles, defaults, catalog: over, retired }); const PANEL = "interrogate reviewers"; describe("parseEntry", () => { @@ -59,6 +59,12 @@ describe("parseEntry", () => { expect(family("gpt-6.1-sol")).toBe("gpt"); }); + test("Fable is its own family, apart from the other Claude models", () => { + expect(family("claude-fable-5-2")).toBe("claude-fable"); + expect(family("openrouter/anthropic/claude-fable-5-2")).toBe("claude-fable"); + expect(family("claude-opus-5-5")).toBe("claude"); + }); + test("rejects a bare alias, an @level, and a repeated option", () => { expect(() => parseEntry("opus")).toThrow("does not start with <providerInstanceId>/<modelId>"); expect(() => parseEntry("claudeAgent/claude-opus-5-5 @high")).toThrow('"@high" is not <optionId>=<value>'); @@ -89,8 +95,8 @@ describe("checkSheet against a catalog", () => { check( [ "bug-fix: claudeCode/claude-opus-5-5", - "how explorer: cursor/grok-4.7", - "why synthesizer: grok/grok-9", + "perf-issue: cursor/grok-4.7", + "judgment and prose: grok/grok-9", "swarm workers: claudeAgent/claude-opus-5-5 reasoningEffort=high", "feature, refactoring: codex/gpt-6.1-sol reasoningEffort=extreme", "hillclimb: claudeAgent/claude-opus-5-5 fastMode=yes", @@ -98,8 +104,8 @@ describe("checkSheet against a catalog", () => { ), ).toEqual([ 'bug-fix: claudeCode/claude-opus-5-5: no provider instance "claudeCode" in this T3', - 'how explorer: cursor/grok-4.7: "cursor" cannot run child tasks (Provider is not authenticated.)', - 'why synthesizer: grok/grok-9: "grok" does not list model "grok-9"', + 'perf-issue: cursor/grok-4.7: "cursor" cannot run child tasks (Provider is not authenticated.)', + 'judgment and prose: grok/grok-9: "grok" does not list model "grok-9"', 'swarm workers: claudeAgent/claude-opus-5-5: no option "reasoningEffort" (has effort, fastMode)', "feature, refactoring: codex/gpt-6.1-sol: reasoningEffort=extreme is not one of low, medium, high, xhigh, max, ultra", "hillclimb: claudeAgent/claude-opus-5-5: fastMode=yes is not one of true, false", @@ -108,27 +114,29 @@ describe("checkSheet against a catalog", () => { test("a catalog that lists each option's values as a plain array, as orchestrator_capabilities returns, checks values", () => { // A copy of a live orchestrator_capabilities result, trimmed to four - // providers. Its grok instance is disabled, so only the tier defaults that - // name grok fail; the Claude and Codex defaults at xhigh pass. + // providers. It lists no Fable 5.2 and no antigravity instance, so only the + // tier defaults that name those fail; the Opus defaults pass. const values = JSON.parse(readFileSync(join(root, "tests/fixtures/t3-catalog-values.json"), "utf8")); const problems = (lines) => check(lines.join("\n"), values); - const onlyGrokDefaults = (p) => p.includes("(no line, tier default): grok/grok-4.7: \"grok\" cannot run child tasks"); + const missingDefault = (p) => + p.includes('(no line, tier default): claudeAgent/claude-fable-5-2: "claudeAgent" does not list model "claude-fable-5-2"') || + p.includes('(no line, tier default): antigravity/gemini-4-carbon: no provider instance "antigravity" in this T3'); const valid = [ "bug-fix: claudeAgent/claude-opus-5-5 effort=high fastMode=true", "feature, refactoring: codex/gpt-6.1-sol reasoningEffort=xhigh serviceTier=priority", - "how explorer: cursor/grok-4.7 reasoning_effort=high fastMode=false contextWindow=256k", + "perf-issue: cursor/grok-4.7 reasoning_effort=high fastMode=false contextWindow=256k", ]; - expect(problems(valid).filter((p) => !onlyGrokDefaults(p))).toEqual([]); - expect(problems(valid).some(onlyGrokDefaults)).toBe(true); + expect(problems(valid).filter((p) => !missingDefault(p))).toEqual([]); + expect(problems(valid).some(missingDefault)).toBe(true); const invalid = [ "bug-fix: claudeAgent/claude-opus-5-5 effort=extreme", "hillclimb: claudeAgent/claude-opus-5-5 fastMode=yes", - "why synthesizer: grok/grok-4.7 reasoningEffort=high", + "judgment and prose: grok/grok-4.7 reasoningEffort=high", ]; - expect(problems(invalid).filter((p) => !onlyGrokDefaults(p))).toEqual([ + expect(problems(invalid).filter((p) => !missingDefault(p))).toEqual([ "bug-fix: claudeAgent/claude-opus-5-5: effort=extreme is not one of low, medium, high, xhigh, max, ultracode, ultrathink", "hillclimb: claudeAgent/claude-opus-5-5: fastMode=yes is not one of false, true", - 'why synthesizer: grok/grok-4.7: "grok" cannot run child tasks (Provider instance is disabled.)', + 'judgment and prose: grok/grok-4.7: "grok" cannot run child tasks (Provider instance is disabled.)', ]); }); @@ -142,15 +150,17 @@ describe("checkSheet against a catalog", () => { } }); - test("a role with no line is checked on its tier default, as on a machine without grok", () => { - const noGrok = structuredClone(catalog); - noGrok.providers = noGrok.providers.filter((p) => p.providerInstanceId !== "grok"); + test("a role with no line is checked on its tier default, as on a machine without Antigravity", () => { + const noGemini = structuredClone(catalog); + noGemini.providers = noGemini.providers.filter((p) => p.providerInstanceId !== "antigravity"); const panelRoles = roles.filter((r) => r.tier === "panel").map((r) => r.role); - expect(check("session hook: on", noGrok)).toEqual( - panelRoles.map((role) => `${role} (no line, tier default): grok/grok-4.7: no provider instance "grok" in this T3`), + expect(check("session hook: on", noGemini)).toEqual( + panelRoles.map( + (role) => `${role} (no line, tier default): antigravity/gemini-4-carbon: no provider instance "antigravity" in this T3`, + ), ); const lines = panelRoles.map((role) => `${role}: claudeAgent/claude-opus-5-5, codex/gpt-6.1-sol`).join("\n"); - expect(check(lines, noGrok)).toEqual([]); + expect(check(lines, noGemini)).toEqual([]); }); test("a panel on one family fails, whatever providers serve it", () => { @@ -158,6 +168,7 @@ describe("checkSheet against a catalog", () => { `${PANEL}: a panel needs at least two model families among its targets (inherit-parent does not count), got claude`, ]); expect(check(`${PANEL}: claudeAgent/claude-opus-5-5, grok/grok-4.7`)).toEqual([]); + expect(check(`${PANEL}: claudeAgent/claude-fable-5-2 effort=high, claudeAgent/claude-opus-5-5`)).toEqual([]); }); test("inherit-parent does not count toward a panel's two families", () => { @@ -182,11 +193,9 @@ describe("checkSheet against a catalog", () => { test("a provider that cannot run cross-provider children fails, and its entries do not count as a family", () => { const noCross = structuredClone(catalog); noCross.providers.find((p) => p.providerInstanceId === "grok").canRunCrossProviderChildTask = false; - const otherPanels = roles.filter((r) => r.tier === "panel" && r.role !== PANEL).map((r) => r.role); expect(check(`${PANEL}: claudeAgent/claude-opus-5-5, grok/grok-4.7`, noCross)).toEqual([ `${PANEL}: grok/grok-4.7: "grok" cannot run child tasks`, `${PANEL}: a panel needs at least two model families among its targets (inherit-parent does not count), got claude`, - ...otherPanels.map((role) => `${role} (no line, tier default): grok/grok-4.7: "grok" cannot run child tasks`), ]); }); @@ -235,6 +244,25 @@ describe("checkSheet against a catalog", () => { ]); }); + // 2.3.0 retired the how and why roles. Every sheet setup-pstack wrote before + // that carries their four lines, which no skill reads now. + test("a sheet written before the how and why roles retired still passes", () => { + const released = [ + "# pstack model configuration (T3)", + "", + "feature, refactoring: claudeAgent/claude-opus-5-5 effort=xhigh", + "strongest judgment: claudeAgent/claude-fable-5-1 effort=xhigh", + "how explorer: claudeAgent/claude-opus-5-5 effort=medium", + "how explainer: claudeAgent/claude-opus-5-5 effort=xhigh", + "why investigators: claudeAgent/claude-opus-5-5 effort=medium", + "why synthesizer: claudeAgent/claude-opus-5-5 effort=xhigh", + `${PANEL}: claudeAgent/claude-fable-5-1 effort=xhigh, codex/gpt-6.1-sol reasoningEffort=xhigh`, + "session hook: on", + ]; + expect(check(released.join("\n"))).toEqual([]); + expect(check("how explorer: provider-gone/model-gone")).toEqual([]); + }); + test("default effort, an unknown role, and a bad hook value fail; headings and blank lines pass", () => { expect(check("# Sheet\n\ndefault effort: session\nhow critics: grok/grok-4.7\nsession hook: of")).toEqual([ "default effort: T3 entries carry their own options; delete this line", diff --git a/tools/derive-t3.mjs b/tools/derive-t3.mjs index 93c91ee5..a557ed1d 100644 --- a/tools/derive-t3.mjs +++ b/tools/derive-t3.mjs @@ -92,6 +92,7 @@ export function sheetBlock(models) { return [ "# pstack model configuration (T3). One line per role. Delete a line to fall back to the skill default.", "# `inherit-parent` or `auto` as a value: the role runs on the parent chat's model (`delegate_task` omits `target`). Alias entries in a panel list still count toward its fan-out.", + "# defaults: 2", "# budget: large (xhigh)", ...rows, "session hook: on", diff --git a/tools/generate.mjs b/tools/generate.mjs index 7cf93318..5e6c0d28 100644 --- a/tools/generate.mjs +++ b/tools/generate.mjs @@ -200,7 +200,7 @@ export function validatePluginLayout(pluginRoot) { } } -const TIERS = ["default", "strongest", "panel"]; +const TIERS = ["default", "strongest", "fast", "panel"]; // Check models.json's shape, throwing with the offending tier, role, or entry // named. `skillExists(skill)` reports whether a role's skill directory carries @@ -244,6 +244,8 @@ export function parseModels(raw, skillExists) { if (!TIERS.includes(role.tier)) fail(`role "${role.role}" names tier "${role.tier}", which tiers does not define`); if (!skillExists(role.skill)) fail(`role "${role.role}" names skill "${role.skill}", which has no SKILL.md`); } + if (!Array.isArray(raw.retired)) fail('"retired" must be a list'); + for (const label of raw.retired) if (labels.has(label)) fail(`"${label}" is both a role and retired`); return raw; } diff --git a/tools/install.mjs b/tools/install.mjs index a89944e9..46b8988e 100755 --- a/tools/install.mjs +++ b/tools/install.mjs @@ -56,7 +56,7 @@ const USAGE = // Codex manifest names, with its pinned digest. function pluginFacts(root) { const plugin = join(root, "plugins/pstack"); - const { roles, tiers } = readJson(join(plugin, "models.json")); + const { roles, tiers, retired } = readJson(join(plugin, "models.json")); const hooks = readJson(join(plugin, ".codex-plugin/plugin.json")).hooks.replace(/^\.\//, ""); const skills = readdirSync(join(plugin, "skills"), { withFileTypes: true }).filter((entry) => entry.isDirectory()); return { @@ -65,6 +65,7 @@ function pluginFacts(root) { codexHook: { path: hooks, sha256: readJson(join(root, FROZEN_HOOKS))[`plugins/pstack/${hooks}`].sha256 }, roles, tiers, + retired, }; } @@ -123,7 +124,7 @@ async function run(argv, env, home) { } catch (err) { report.sheet.checks.push(check("move", false, err.message, hint)); } - report.sheet.checks.push(...doctorSheet(sheet, homes, { catalog, roles: facts.roles, tiers: facts.tiers, hint })); + report.sheet.checks.push(...doctorSheet(sheet, homes, { catalog, roles: facts.roles, tiers: facts.tiers, retired: facts.retired, hint })); const all = [...report.homes.flatMap((row) => row.checks), ...report.sheet.checks]; report.failed = all.filter((c) => !c.ok && !c.warn).length; report.warnings = all.filter((c) => !c.ok && c.warn).length; diff --git a/tools/install/sheet.mjs b/tools/install/sheet.mjs index 662395d6..6aa6574d 100644 --- a/tools/install/sheet.mjs +++ b/tools/install/sheet.mjs @@ -63,7 +63,7 @@ export function moveSheet(sheet, homes) { return steps; } -export function doctorSheet(sheet, homes, { catalog, roles, tiers, hint }) { +export function doctorSheet(sheet, homes, { catalog, roles, tiers, retired, hint }) { const old = homeSheets(homes).filter(isFile); if (!isFile(sheet)) { const differ = new Set(old.map((path) => readFileSync(path, "utf8"))).size > 1; @@ -79,7 +79,7 @@ export function doctorSheet(sheet, homes, { catalog, roles, tiers, hint }) { } return [check("machine sheet", false, "none, so every role runs on its skill's defaults", SETUP_HINT, true)]; } - const problems = checkSheet(parseSheet(readFileSync(sheet, "utf8")), { roles, defaults: tiers, catalog }); + const problems = checkSheet(parseSheet(readFileSync(sheet, "utf8")), { roles, defaults: tiers, catalog, retired }); const shadowing = old.filter((path) => !resolvesTo(path, sheet) && !sameBytes(path, sheet)); return [ check( diff --git a/tools/substitutions.json b/tools/substitutions.json index 3081c90a..b70f27cf 100644 --- a/tools/substitutions.json +++ b/tools/substitutions.json @@ -1,5 +1,35 @@ { "substitutions": [ + { + "pattern": "A rule without the `# defaults: 2` line comes from an older setup. That setup wrote a line for every role, so some of its values are old defaults, not choices. An old slug is one that matches `grok-*`. Before step 3, replace these values:\n\n- An old slug in `feature, refactoring`, `bug-fix`, `perf-issue`, `hillclimb`, `reflect tooling`, or `swarm workers` takes the role's step 5 default.\n- A `claude-opus-*` value in `hardest tasks` takes the role's step 5 default.\n- In a panel role (`arena runners`, `arena cross-judge pool`, `architect runners`, `interrogate reviewers`), a list of exactly one `claude-opus-*` entry and one old slug, in either order, takes the role's step 5 list. In any other list, each old slug becomes `claude-opus-5-5-high-fast`.\n\nEvery other value is the user's choice and stays, including an old slug in any other role and every `inherit-parent` or `auto` value.", + "replacement": "A sheet without the `# defaults: 2` line comes from an older setup. That setup wrote a line for every role, so some of its values are old defaults, not choices. Before step 3, replace each of these values with the role's step 5 default:\n\n- `claudeAgent/claude-fable-5-1`, with any options, in `bug-fix`, `perf-issue`, `hillclimb`, or `hardest tasks`.\n- `claudeAgent/claude-opus-5-5`, with any options, in `reflect tooling` or `swarm workers`.\n- In a panel role (`arena runners`, `arena cross-judge pool`, `architect runners`, `interrogate reviewers`), a list of exactly `claudeAgent/claude-opus-5-5`, `codex/gpt-6.1-sol`, and `grok/grok-4.7`, with any options, in any order.\n\nEvery other value is the user's choice and stays, including every `inherit-parent` or `auto` value.", + "rationale": "The sheet: upstream's migration of old defaults, matched against the defaults t3-pstack 2.0 through 2.2 wrote, since a T3 sheet never held a Cursor slug", + "files": "^skills/setup-pstack/SKILL\\.md$" + }, + { + "pattern": "So `unlimited` turns `claude-opus-5-5-xhigh` into `claude-opus-5-5-max` and `claude-opus-5-5-high-fast` into `claude-opus-5-5-xhigh-fast`, and it keeps `claude-fable-5-2-max`. Gemini tops out at `high`, so under `unlimited` the fallback keeps `gemini-4-carbon-high` as it is. `small` turns the first two into `claude-opus-5-5-medium` and `claude-opus-5-5-low-fast`. Fable 5.2 and Gemini have no fast slug, so never write one.", + "replacement": "So `unlimited` raises an `effort=xhigh` default to `effort=max` and an `effort=high` default to `effort=xhigh`, and it keeps an `effort=max` default. Gemini 4 Carbon's `thinking_level` tops out at `high`, so under `unlimited` the fallback keeps it at `high`. `small` turns `effort=xhigh` into `effort=medium` and `effort=high` into `effort=low`. Each keeps any speed option its default has. Claude lists no `fastMode` option for Fable 5.2, and Antigravity lists no speed option for Gemini 4 Carbon, so never write one for them.", + "rationale": "The sheet: a T3 entry carries its reasoning and speed as options, not as slug suffixes", + "files": "^skills/setup-pstack/SKILL\\.md$" + }, + { + "pattern": "with `alwaysApply: true`, the `# defaults: 2` line,", + "replacement": "with the `# defaults: 2` line,", + "rationale": "The sheet: a T3 sheet has no Cursor rule frontmatter", + "files": "^skills/setup-pstack/SKILL\\.md$" + }, + { + "pattern": "### 5. Write the rule\n", + "replacement": "### 5. Write the sheet\n", + "rationale": "The sheet: names the step the generator stamps the sheet block under", + "files": "^skills/setup-pstack/SKILL\\.md$" + }, + { + "pattern": "```\n---\ndescription: pstack per-role model choices (overrides skill defaults)\nalwaysApply: true\n---\n", + "replacement": "```markdown\n", + "rationale": "The sheet: opens the fence the generator stamps with the sheet from models.json, in place of upstream's rule", + "files": "^skills/setup-pstack/SKILL\\.md$" + }, { "pattern": "and mention once that a Custom Mode keeps it on.", "replacement": "and mention once that starting each task with `/poteto-mode` keeps it on.", @@ -55,8 +85,8 @@ "files": "^skills/poteto-help/SKILL\\.md$" }, { - "pattern": "pstack is built for Cursor, and it also installs in Claude Code with `/plugin marketplace add cursor/plugins`, then `/plugin install pstack@cursor-plugins`. There, each command takes a `pstack:` prefix, such as `/pstack:poteto-mode`. The [Claude Code adapter](../../docs/harness/claude-code.md) maps the Cursor names, and a step that needs a Cursor-only feature, such as Bugbot or Automations, is skipped with a one-line note.\n\nOther tools can read the skills, because they use the Agent Skills format. But most workflow skills, including `/poteto-mode`, `/how`, `/why`, and `/teach`, spawn Cursor subagents with per-role models, and Custom Modes and `/loop` are Cursor features, so those parts may not work there.", - "replacement": "t3-pstack is pstack rewritten for T3 Code, and it installs in Claude Code and Codex with `npx -y github:chhoumann/t3-pstack install`.\n\nIts workflow skills, including `/poteto-mode`, `/how`, `/why`, and `/teach`, dispatch subagents through T3's `delegate_task` with per-role models, so those parts need a T3 thread.", + "pattern": "pstack is built for Cursor, and it also installs in Claude Code with `/plugin marketplace add cursor/plugins`, then `/plugin install pstack@cursor-plugins`. There, each command takes a `pstack:` prefix, such as `/pstack:poteto-mode`. The [Claude Code adapter](../../docs/harness/claude-code.md) maps the Cursor names, and a step that needs a Cursor-only feature, such as Bugbot or Automations, is skipped with a one-line note.\n\nOther tools can read the skills, because they use the Agent Skills format. But most workflow skills, including `/poteto-mode`, `/how`, and `/teach`, spawn Cursor subagents, some with per-role models, and Custom Modes and `/loop` are Cursor features, so those parts may not work there.", + "replacement": "t3-pstack is pstack rewritten for T3 Code, and it installs in Claude Code and Codex with `npx -y github:chhoumann/t3-pstack install`.\n\nIts workflow skills, including `/poteto-mode`, `/how`, and `/teach`, dispatch subagents through T3's `delegate_task`, some with per-role models, so those parts need a T3 thread.", "rationale": "states where the port runs and how it installs (Precedence)", "files": "^skills/poteto-help/SKILL\\.md$" }, @@ -218,14 +248,14 @@ }, { "files": "^skills/poteto-mode/SKILL\\.md$", - "pattern": "Verification is the exception and stays on the `swarm workers` model and speed (`grok-4.7-xhigh-fast` by default).", + "regex": "Verification is the exception and stays on the `swarm workers` model and speed \\(`(?:claude|gpt|grok|gemini|composer)-[^`]+` by default\\)\\.", "replacement": "Verification is the exception and stays on the `swarm workers` model and speed (default in the **swarm** skill's Models section).", "rationale": "#613 per-job effort: a T3 entry carries its reasoning and speed as options, not as slug suffixes (The sheet)" }, { "files": "^skills/poteto-mode/SKILL\\.md$", "pattern": "Change only the effort level and whether the slug is fast,", - "replacement": "Change only the entry's reasoning option (`effort` on Claude, `reasoningEffort` on Codex and Grok) and its speed option,", + "replacement": "Change only the entry's reasoning option (`effort` on Claude, `reasoningEffort` on Codex and Grok, `thinking_level` on Antigravity) and its speed option,", "rationale": "#613 per-job effort: a T3 entry carries its reasoning and speed as options, not as slug suffixes (The sheet)" }, { @@ -234,6 +264,12 @@ "replacement": "If the model has no value at that level, or no speed option, use its nearest one in `orchestrator_capabilities`.", "rationale": "#613 per-job effort: a T3 entry carries its reasoning and speed as options, not as slug suffixes (The sheet)" }, + { + "files": "^skills/poteto-mode/SKILL\\.md$", + "pattern": "Gemini has no xhigh, max, or fast slug, so a Gemini subagent runs at high, such as `gemini-4-carbon-high`, whenever the job calls for high or above. Fable 5.2 has no fast slug, so an urgent Fable 5.2 subagent runs at standard speed and keeps its level.", + "replacement": "So Gemini 4 Carbon on Antigravity, whose `thinking_level` tops out at `high` and which has no speed option, runs at `high` whenever the job calls for high or above. Claude lists no `fastMode` option for Fable 5.2, so an urgent Fable 5.2 subagent runs at standard speed and keeps its level.", + "rationale": "#613 per-job effort: upstream's Gemini and Fable slug limits, as the option values orchestrator_capabilities lists for antigravity/gemini-4-carbon and claudeAgent/claude-fable-5-2 (The sheet)" + }, { "files": "^skills/poteto-mode/SKILL\\.md$", "pattern": "rejects the adjusted slug, do not try another adjusted slug.", @@ -247,15 +283,27 @@ "rationale": "Subagent policy (rejected target). T3's delegate_task fails with model_unavailable on a model its provider does not advertise, provider_unavailable on a disabled or unregistered provider instance, and invalid_request naming the options it rejects. None of these lists valid models, which orchestrator_capabilities does" }, { - "regex": "Defaults `(?:claude|gpt|grok|gemini|composer)-[^`]+` for code, `(?:claude|gpt|grok|gemini|composer)-[^`]+` for prose and judgment", + "regex": "Defaults `(?:claude|gpt|grok|gemini|composer)-[^`]+` for code, prose, and judgment", "replacement": "Role defaults in [Models](#models)", "rationale": "defaults come from the stamped Models section (Model names)", "files": "^skills/poteto-mode/SKILL\\.md$" }, { - "regex": "strongest judgment model \\(`(?:claude|gpt|grok|gemini|composer)-[^`]+`\\)", - "replacement": "strongest judgment model (the `hardest tasks` default in [Models](#models))", - "rationale": "defaults come from the stamped Models section (Model names)", + "regex": "Trivial mechanical edits go to your `swarm workers` model \\(default `(?:claude|gpt|grok|gemini|composer)-[^`]+`\\)\\.", + "replacement": "Trivial mechanical edits go to your `swarm workers` model (default in the **swarm** skill's Models section).", + "rationale": "defaults come from the stamped Models sections, and swarm workers is the swarm skill's role (Model names)", + "files": "^skills/poteto-mode/SKILL\\.md$" + }, + { + "regex": "Review and design panels default to one runner each on `(?:claude|gpt|grok|gemini|composer)-[^`]+`(?:(?:,| and|, and) `(?:claude|gpt|grok|gemini|composer)-[^`]+`)+\\.", + "replacement": "Review and design panels default to one runner each on the panel entries in the **arena** skill's Models section.", + "rationale": "defaults come from the stamped Models sections, and the panel tier is listed under arena's roles (Model names)", + "files": "^skills/poteto-mode/SKILL\\.md$" + }, + { + "pattern": "If the rule has no `# defaults: 2` line, an older setup wrote it.", + "replacement": "If the model sheet has no `# defaults: 2` line, an older setup wrote it.", + "rationale": "the T3 sheet replaces the Cursor rule (The sheet)", "files": "^skills/poteto-mode/SKILL\\.md$" }, { @@ -272,8 +320,8 @@ }, { "pattern": "Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a \"done\" summary.", - "replacement": "Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a \"done\" summary.\n\n**Dispatch on T3.** Every subagent is a `delegate_task` call from the chat that runs the playbook, same model family included, so every child shows up in T3. When you are a `delegate_task` child, you are a leaf. Do the work yourself, and start no subagent unless your brief names one. Give each call its own `clientRequestId`, stable across retries of that call, and keep each returned `taskId`. A child's completion wakes this thread, so end the turn instead of polling, and call `task_status` only when a result is needed mid-turn. `task_cancel` stops a child, and `task_status` confirms it stopped. A child gets only its brief, never your context, so pass absolute paths. `<plugin root>` is the absolute path of the directory that holds this plugin's `skills/` and `agents/`. A persona (`poteto-agent`, `comment-sicko`, `thermo-nuclear-review-subagent`, `thermo-nuclear-code-quality-review-subagent`) is a brief that opens with \"Read `<plugin root>/agents/<name>.md` in full and act as it says\", and a `poteto-agent` brief also names this file's absolute path.\n\nA child starts in your checkout, which suits one writer while you write nothing. A writer that runs beside other writers or your own edits gets `isolation: \"worktree\"`, and T3 gives it a new worktree and branch from your thread's checkout at its `HEAD` commit. Commit what it builds on first, because uncommitted edits stay behind. A child that must start from another commit, such as a PR head or fresh trunk, gets `isolation: \"worktree\"` even when it only reads. Its brief names that commit or ref, and before anything else the child runs `git fetch` and moves its own branch there with `git reset --hard`. T3 can rename that branch during the run, so the brief tells the child to end its reply with the output of `pwd`, `git branch --show-current`, and `git rev-parse HEAD`. After review, bring its commits onto your branch with `git merge <branch>`, which fast-forwards when your branch has not moved. A PR opens only from a T3 thread's branch, yours or that of a child that owns the PR. In a repo with no commit yet, `delegate_task` refuses the worktree with `Unable to resolve the parent checkout commit`, so commit first. When this thread's project is not a git checkout, which gets the same refusal, when your work lives in a checkout other than the one `t3_worktree_status` names, or when you copy uncommitted changes into the child's worktree, create that worktree with `git worktree add` from `HEAD` instead. Remove that worktree and its branch after the result. A child sent into a worktree it does not own, one you made this way or one a finished worker left, keeps `isolation: \"shared\"`. Its brief names that absolute path as the only place it writes, and tells it to run every command there (`workdir` on Codex) and to edit by absolute path. Record your own `git status --porcelain` before you dispatch a writer to another checkout, and check after the result that it is unchanged. A step a playbook says to delegate goes to `delegate_task` on that role's sheet entry, not into your own tool calls, unless you state a reason such as a step too small to brief. A research delegate no role names runs on the `how explorer` entry. A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `grok`, whatever provider instance serves it, and your own family is the one in `orchestrator_capabilities`' `inheritedModel`. A rejected target runs on another target of the same family from `orchestrator_capabilities`, and you say so. `orchestrator_capabilities` lists a short set of models per provider, and its `search` finds the others. A required review with no reviewer from another family stays `BLOCKED: independent review`.\n\nEnd every reply that ran a playbook with a dispatch ledger: one line per delegated step, naming the role and the `providerInstanceId/model` it ran on, or `in-thread: <reason>`.", - "rationale": "inserts the T3 dispatch policy at the end of the Subagents section (Tool actions; Subagent policy). A delegate_task child keeps delegate_task, so the leaf sentence stops the session-start routing from sending a child into a playbook's fan-out (#21). A writer gets T3's worktree isolation, which starts from the thread checkout's HEAD commit and refuses a thread whose project is not a git checkout or has no commit, so git worktree add stays only for those (#50). A child whose worktree gets uncommitted changes copied in, as interrogate's adversaries do, needs that fallback too, because isolation leaves uncommitted edits out. Isolation always starts at the parent's HEAD, so a child bound for a PR head or fresh trunk fetches and resets its own branch there, a child sent into a worktree it does not own works there by path, and the report names pwd so a parent learns a worktree it could not name at spawn (Cursor Bugbot on #68)", + "replacement": "Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a \"done\" summary.\n\n**Dispatch on T3.** Every subagent is a `delegate_task` call from the chat that runs the playbook, same model family included, so every child shows up in T3. When you are a `delegate_task` child, you are a leaf. Do the work yourself, and start no subagent unless your brief names one. Give each call its own `clientRequestId`, stable across retries of that call, and keep each returned `taskId`. A child's completion wakes this thread, so end the turn instead of polling, and call `task_status` only when a result is needed mid-turn. `task_cancel` stops a child, and `task_status` confirms it stopped. A child gets only its brief, never your context, so pass absolute paths. `<plugin root>` is the absolute path of the directory that holds this plugin's `skills/` and `agents/`. A persona (`poteto-agent`, `comment-sicko`, `thermo-nuclear-review-subagent`, `thermo-nuclear-code-quality-review-subagent`) is a brief that opens with \"Read `<plugin root>/agents/<name>.md` in full and act as it says\", and a `poteto-agent` brief also names this file's absolute path.\n\nA child starts in your checkout, which suits one writer while you write nothing. A writer that runs beside other writers or your own edits gets `isolation: \"worktree\"`, and T3 gives it a new worktree and branch from your thread's checkout at its `HEAD` commit. Commit what it builds on first, because uncommitted edits stay behind. A child that must start from another commit, such as a PR head or fresh trunk, gets `isolation: \"worktree\"` even when it only reads. Its brief names that commit or ref, and before anything else the child runs `git fetch` and moves its own branch there with `git reset --hard`. T3 can rename that branch during the run, so the brief tells the child to end its reply with the output of `pwd`, `git branch --show-current`, and `git rev-parse HEAD`. After review, bring its commits onto your branch with `git merge <branch>`, which fast-forwards when your branch has not moved. A PR opens only from a T3 thread's branch, yours or that of a child that owns the PR. In a repo with no commit yet, `delegate_task` refuses the worktree with `Unable to resolve the parent checkout commit`, so commit first. When this thread's project is not a git checkout, which gets the same refusal, when your work lives in a checkout other than the one `t3_worktree_status` names, or when you copy uncommitted changes into the child's worktree, create that worktree with `git worktree add` from `HEAD` instead. Remove that worktree and its branch after the result. A child sent into a worktree it does not own, one you made this way or one a finished worker left, keeps `isolation: \"shared\"`. Its brief names that absolute path as the only place it writes, and tells it to run every command there (`workdir` on Codex) and to edit by absolute path. Record your own `git status --porcelain` before you dispatch a writer to another checkout, and check after the result that it is unchanged. A step a playbook says to delegate goes to `delegate_task` on that role's sheet entry, not into your own tool calls, unless you state a reason such as a step too small to brief. A research delegate no role names omits `target`, so it runs on the parent model. A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `gemini`, whatever provider instance serves it, except that Fable (`claude-fable-*`) is its own family, and your own family is the one in `orchestrator_capabilities`' `inheritedModel`. A rejected target runs on another target of the same family from `orchestrator_capabilities`, and you say so. `orchestrator_capabilities` lists a short set of models per provider, and its `search` finds the others. A required review with no reviewer from another family stays `BLOCKED: independent review`.\n\nEnd every reply that ran a playbook with a dispatch ledger: one line per delegated step, naming the role and the `providerInstanceId/model` it ran on, or `in-thread: <reason>`.", + "rationale": "inserts the T3 dispatch policy at the end of the Subagents section (Tool actions; Subagent policy). A delegate_task child keeps delegate_task, so the leaf sentence stops the session-start routing from sending a child into a playbook's fan-out (#21). A writer gets T3's worktree isolation, which starts from the thread checkout's HEAD commit and refuses a thread whose project is not a git checkout or has no commit, so git worktree add stays only for those (#50). A child whose worktree gets uncommitted changes copied in, as interrogate's adversaries do, needs that fallback too, because isolation leaves uncommitted edits out. Isolation always starts at the parent's HEAD, so a child bound for a PR head or fresh trunk fetches and resets its own branch there, a child sent into a worktree it does not own works there by path, and the report names pwd so a parent learns a worktree it could not name at spawn (Cursor Bugbot on #68). A research delegate no role names, such as how's one explainer or recall's investigators, runs on the parent model, as upstream's Task call without a model does. The family rule keeps upstream's Fable exception", "files": "^skills/poteto-mode/SKILL\\.md$" }, { @@ -354,9 +402,10 @@ "files": "^skills/no-comments/SKILL\\.md$" }, { - "pattern": "Every spawn is a Task subagent with `subagent_type: generalPurpose` and `readonly: true`.", - "replacement": "Every spawn is a `delegate_task` child with `role: \"research\"` and a brief that says to inspect only and change no file.", - "rationale": "Per-skill notes: how" + "pattern": "Spawn one Task subagent with `subagent_type: generalPurpose` and `readonly: true` that explores and explains in one pass.", + "replacement": "Spawn one `delegate_task` child with `role: \"research\"` that explores and explains in one pass. Leave `target` unset, so it runs on this chat's model.", + "rationale": "Per-skill notes: how. Upstream's Task call names no model, so the child runs on the parent model, and its brief already says it has read-only access", + "files": "^skills/how/SKILL\\.md$" }, { "pattern": "Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message.", @@ -368,26 +417,6 @@ "replacement": "If `delegate_task` rejects an entry, use the default and say so. If it rejects the default, use another target of the same family from `orchestrator_capabilities`.", "rationale": "Subagent policy (rejected target)" }, - { - "pattern": "Every spawn is `generalPurpose` with `readonly: false` (agent mode). **Do not use readonly/Ask mode.** It strips MCP access, which disables the MCP-backed investigators and the synthesizer's citation spot-checks.", - "replacement": "Every spawn is a `delegate_task` child with full tool access, MCP included, which the MCP-backed investigators and the synthesizer's citation spot-checks need.", - "rationale": "Per-skill notes: why" - }, - { - "pattern": "Before spawning investigators, list the available MCPs from the Cursor environment. Use the available-tools map when present. Otherwise inspect the `mcps/` directory Cursor exposes for enabled MCP servers.", - "replacement": "Before spawning investigators, list the MCP servers whose tools this session exposes.", - "rationale": "Per-skill notes: why" - }, - { - "pattern": "`model`: the `why investigators` line", - "replacement": "`target`: the `why investigators` line", - "rationale": "The sheet" - }, - { - "pattern": "`model`: the `why synthesizer` line", - "replacement": "`target`: the `why synthesizer` line", - "rationale": "The sheet" - }, { "pattern": "Before fanning out, find this conversation's transcript in the `agent-transcripts/` directory the system prompt names. Do not glob across `~/.cursor/projects/*/`. That crosses workspace boundaries and reads private chats from unrelated projects.", "replacement": "Before fanning out, find this conversation's own transcript where this thread's host keeps it. Do not search other projects' transcripts. That crosses workspace boundaries and reads private chats from unrelated projects.", @@ -461,8 +490,8 @@ }, { "files": "^skills/arena/SKILL\\.md$", - "regex": "With the default pool, a Claude parent gets `(?:claude|gpt|grok|gemini|composer)-[^`]+`\\. A parent from any other family gets `(?:claude|gpt|grok|gemini|composer)-[^`]+` first\\.", - "replacement": "Among the entries from another family, try first those whose model ran fewer candidates, so no model scores its own work when another can judge. Pool order decides among entries that ran as many, and the reply says when the judge ran a candidate. With the default runners and pool in [Models](#models), a Claude parent skips the Claude entry and gets the next one, and a parent from any other family gets the Claude entry first.", + "regex": "With the default pool, a Claude parent gets `(?:claude|gpt|grok|gemini|composer)-[^`]+`\\. A parent from any other vendor gets `(?:claude|gpt|grok|gemini|composer)-[^`]+` first, then `(?:claude|gpt|grok|gemini|composer)-[^`]+`\\.", + "replacement": "Among the entries from another vendor, try first those whose model ran fewer candidates, so no model scores its own work when another can judge. Pool order decides among entries that ran as many, and the reply says when the judge ran a candidate. With the default runners and pool in [Models](#models), a Claude parent, Fable included, gets the Gemini entry, and a parent from any other vendor gets the Fable entry first, then the Opus entry.", "rationale": "Model names; Per-skill notes: arena (t3-pstack 1.0.2: the cross-judge does not score its own candidate when another entry can judge)" }, { @@ -513,6 +542,12 @@ "replacement": "each citing the thread ID.", "rationale": "Tool actions: Find an earlier conversation" }, + { + "pattern": "Spawn one investigator subagent per source, in agent mode because readonly strips MCP access,", + "replacement": "Spawn one investigator per source, each a `delegate_task` child with full tool access, MCP included,", + "rationale": "Subagent policy (readonly): a delegate_task child keeps its MCP tools, which the per-source investigators need", + "files": "^skills/recall/SKILL\\.md$" + }, { "pattern": "This skill orchestrates three others: an inline mining pass (see step 1), Cursor's built-in `create-skill` (authoring),", "replacement": "This skill orchestrates three others: an inline mining pass (see step 1), the harness's skill-authoring skill (`skill-creator` where installed, else the Agent Skills format),", @@ -713,7 +748,7 @@ "files": "^skills/poteto-mode/playbooks/" }, { - "pattern": "on the `swarm workers` model (default `grok-4.7-xhigh-fast`)", + "regex": "on the `swarm workers` model \\(default `(?:claude|gpt|grok|gemini|composer)-[^`]+`\\)", "replacement": "on the `swarm workers` model (default in the **swarm** skill's Models section)", "rationale": "Model names", "files": "^skills/poteto-mode/playbooks/" @@ -883,12 +918,6 @@ "rationale": "Model names", "files": "/SKILL\\.md$" }, - { - "regex": ", default `(?:claude|gpt|grok|gemini|composer)-[^`]+`", - "replacement": ", default in [Models](#models)", - "rationale": "Model names", - "files": "/SKILL\\.md$" - }, { "regex": " \\| `(?:claude|gpt|grok|gemini|composer)-[^`]+` \\| `references/", "replacement": " | default in [Models](#models) | `references/", @@ -896,9 +925,9 @@ "files": "^skills/reflect/SKILL\\.md$" }, { - "regex": "Families go by prefix: .*?`composer-\\*`\\. A refused `composer-\\*` entry runs on (?:`[^`]+`|Reviewer B's default)\\.", - "replacement": "A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `grok`, whatever provider instance serves it.", - "rationale": "The sheet (family rule); a refused entry already runs on another target of its family" + "pattern": "Families go by prefix, and the longest matching prefix wins: `claude-fable-*`, `claude-*`, and `gemini-*`. Drop a leading `cursor-` before you compare. Any other slug's family is its text before the first hyphen. A family's default is its entry in the default list above.", + "replacement": "A model's family is the first segment of its ID's last `/` part, such as `claude`, `gpt`, or `gemini`, whatever provider instance serves it, except that Fable (`claude-fable-*`) is its own family.", + "rationale": "The sheet (family rule), with upstream's Fable exception. A refused seat already runs on another target of its family from orchestrator_capabilities, so upstream's family default has no T3 use" }, { "pattern": "omit Task `model`", diff --git a/tools/upstream.json b/tools/upstream.json index da9d690b..024ba458 100644 --- a/tools/upstream.json +++ b/tools/upstream.json @@ -4,7 +4,7 @@ "pstack": { "upstreamPath": "pstack", "localPath": "plugins/pstack", - "sha": "c742dd61706fbacc1b95f1a20b7b988cf096ce6c", + "sha": "bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7", "exclude": [ ".cursor-plugin/", ".gitignore", @@ -20,7 +20,7 @@ "cursor-team-kit": { "upstreamPath": "cursor-team-kit/skills", "localPath": "plugins/pstack/skills", - "sha": "c742dd61706fbacc1b95f1a20b7b988cf096ce6c", + "sha": "bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7", "exclude": [ "check-compiler-errors/", "control-cli/", @@ -39,7 +39,7 @@ "thermos": { "upstreamPath": "thermos", "localPath": "plugins/pstack", - "sha": "c742dd61706fbacc1b95f1a20b7b988cf096ce6c", + "sha": "bf0c7cd80abdbf7fe47b634978a7d1b4071f71a7", "exclude": [ ".cursor-plugin/", "CHANGELOG.md",