From d2c36bb899ec71fa9464a0a99671521cbde93d33 Mon Sep 17 00:00:00 2001 From: Christian Bager Bach Houmann Date: Mon, 9 Nov 2026 06:04:36 +0100 Subject: [PATCH 1/2] fix(poteto-mode): say what a playbook's path is relative to The Playbooks section said to open a playbook at `playbooks/.md` without a base, while the head of the file gives bundled skills as `../<name>/SKILL.md` from this file. Codex agents that read a playbook in one shell call with sibling skills gave it that skills/ base and opened skills/playbooks/<title>.md, which does not exist (#71). An anchored substitution now says the path is from this file and spells out skills/poteto-mode/playbooks/<title>.md. poteto-mode's SKILL.md is a declared fork, so its copy carries the substitution's text, and its own lines against derived upstream are unchanged. --- plugins/pstack/skills/poteto-mode/SKILL.md | 2 +- tools/substitutions.json | 6 ++++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/plugins/pstack/skills/poteto-mode/SKILL.md b/plugins/pstack/skills/poteto-mode/SKILL.md index 899b431..f91d5b5 100644 --- a/plugins/pstack/skills/poteto-mode/SKILL.md +++ b/plugins/pstack/skills/poteto-mode/SKILL.md @@ -129,7 +129,7 @@ Comments follow the same rule as the reply. Write them clean as you go. Keep a c ## Playbooks -Open a todolist whose first items are the matched playbook's steps, copied in verbatim, before any task-specific todos. A step you choose not to do stays in the list with a one-line `skip: <reason>`. Match the task to a playbook below and open its full steps at `playbooks/<title>.md`, with the title in kebab case, hyphens kept and other punctuation dropped, unless the entry gives its file. Copy its steps in verbatim. Keep the todolist in the session's task tool when it has one, such as `update_plan` on Codex. Without one, keep it as an uncommitted Markdown checklist at `.audit/<task-slug>.todo.md` in the work dir, beside the decision trail, so sessions that share a checkout never write one file. +Open a todolist whose first items are the matched playbook's steps, copied in verbatim, before any task-specific todos. A step you choose not to do stays in the list with a one-line `skip: <reason>`. Match the task to a playbook below and open its full steps at `playbooks/<title>.md` from this file (`skills/poteto-mode/playbooks/<title>.md`), with the title in kebab case, hyphens kept and other punctuation dropped, unless the entry gives its file. Copy its steps in verbatim. Keep the todolist in the session's task tool when it has one, such as `update_plan` on Codex. Without one, keep it as an uncommitted Markdown checklist at `.audit/<task-slug>.todo.md` in the work dir, beside the decision trail, so sessions that share a checkout never write one file. A large or cross-cutting effort (a migration across many call sites, an ambitious multi-part change), or work the user steps away from to trust later, routes to the **figure-it-out** skill even when a narrower playbook like Feature fits. Use **figure-it-out** whenever no bundled playbook fits. It designs a bespoke, rigorous playbook for the task. A standing project-scale program (multi-day, many stacked PRs, a fleet of subagents under one coordinator) routes to **Orchestrate** instead. figure-it-out designs one bespoke run, orchestrate runs the program. diff --git a/tools/substitutions.json b/tools/substitutions.json index 3081c90..afd6c08 100644 --- a/tools/substitutions.json +++ b/tools/substitutions.json @@ -162,6 +162,12 @@ "replacement": "Bundled skills live at `../<name>/SKILL.md` from this file, so put this file's absolute path in every `poteto-agent` prompt.\n\nOn Codex, read this file whole before acting, in a shell call of its own with `max_output_tokens: 10000`. A smaller output budget cuts lines out of its middle. If a read of it shows `tokens truncated`, read it again that way.", "rationale": "Codex's model picks a shell read's output budget, often 3000 to 6000 tokens for a SKILL.md, and Codex 0.162.1 then cuts the middle of anything longer, which here is the Subagents section that holds the T3 dispatch rules. The head of a cut read survives, so the instruction sits there. tests/agent-skills.test.mjs keeps the file inside the 10000-token budget it names." }, + { + "pattern": "open its full steps at `playbooks/<title>.md`,", + "files": "^skills/poteto-mode/SKILL\\.md$", + "replacement": "open its full steps at `playbooks/<title>.md` from this file (`skills/poteto-mode/playbooks/<title>.md`),", + "rationale": "Codex agents that read a playbook in one shell call with sibling skills give it the skills/ base that `../<name>/SKILL.md` names, and open skills/playbooks/<title>.md, which does not exist (#71, by @adryanev). The path gets its base the way bundled skills do." + }, { "pattern": "- About to `AskQuestion` on a", "replacement": "- About to ask the user a question on a", From de942f0e033c555c8158ad8bde5b0049b8b66bcd Mon Sep 17 00:00:00 2001 From: Christian Bager Bach Houmann <christian@bagerbach.com> Date: Mon, 9 Nov 2026 06:04:36 +0100 Subject: [PATCH 2/2] release: 2.2.9 --- .claude-plugin/marketplace.json | 2 +- CHANGES.md | 12 ++++++++++++ README.md | 4 ++-- VERSION | 2 +- package.json | 2 +- plugins/pstack/.claude-plugin/plugin.json | 2 +- plugins/pstack/.codex-plugin/plugin.json | 2 +- 7 files changed, 19 insertions(+), 7 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 42ce84d..573277c 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.2.9" } ] } diff --git a/CHANGES.md b/CHANGES.md index 0c48664..5fe4c42 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,18 @@ This file is the release changelog, with one `## <version> - <title>` entry per release, newest first. The Cursor-to-T3 rewrite rules live in [`tools/substitutions.json`](tools/substitutions.json), and the [sync boundary](CONTRIBUTING.md#the-sync-boundary) in `CONTRIBUTING.md` defines how a change to upstream's skill content is declared. +## 2.2.9 - poteto-mode says where its playbooks are + +poteto-mode's Playbooks section told the agent to open a playbook's steps at `playbooks/<title>.md` and did not say what that path is relative to. The head of the same file gives bundled skills as `../<name>/SKILL.md` from this file. A Codex agent that reads a playbook in one shell call with sibling skills gives the playbook that `skills/` base too, as in `cat <plugin>/skills/how/SKILL.md <plugin>/skills/playbooks/investigation.md`. That read fails with `No such file or directory`, because the playbooks are in `skills/poteto-mode/playbooks/`, and the agent spends a turn finding them. The sentence now reads "open its full steps at `playbooks/<title>.md` from this file (`skills/poteto-mode/playbooks/<title>.md`)". Thanks to @adryanev for the report and the diagnosis in [#71](https://github.com/chhoumann/t3-pstack/issues/71). + +#71 counts 16 of these failures in the reporter's session logs from 2026-11-04 to 2026-11-08, across 15 sessions, all shell reads in Codex, 13 on 2.2.1 and 3 on 2.2.8. This Mac's Codex sessions show the same failure. From 2026-10-15 to 2026-11-08, 33 Codex sessions read a playbook from an installed t3-pstack 93 times. 6 of those reads used `skills/playbooks/<title>.md`, in 3 sessions, from 2026-10-15 to 2026-10-28, on 2.0.0-rc.5, rc.9, rc.15, rc.17, 2.1.0, and 2.2.0. One long-lived session made 4 of them among its 39 playbook reads. 5 of the 6 read the playbook in the same call as a sibling skill, and each was followed by a read of the right path 5 to 29 seconds later. A plain grep of the logs finds 17 lines, because Codex logs a command's output twice and a forked or compacted session copies its parent's history. Claude Code's sessions on this Mac show none, since Claude Code names a skill's base directory when it loads the skill. + +The change is a substitution in `tools/substitutions.json`, anchored on Lauren's sentence, which is the same at the pin and at cursor/plugins `main` as of `6b03002`. `tools/forks.json` declares poteto-mode's `SKILL.md` a fork, so its copy carries the substitution's text, and its own lines differ from derived upstream exactly as in 2.2.8. The playbooks name each other the same way, as in `playbooks/shipping.md`, and the Babysit playbook names `../references/bugbot-triage.md`. No session on this Mac shows a failed read of either kind, so this release leaves them. + +These runs used T3 0.1.8-nightly.20261108.4367 on macOS. Each was a fresh Codex thread in a throwaway git repository, asked why a small duration parser returns 60000 for `1m30s`, a question for the Investigation playbook. Each was told to read and follow poteto-mode from a checkout of this release, or of 2.2.8 as the control, and that the installed plugin is 2.2.8. Three threads ran per arm on `codex/gpt-6-astra` and three on `codex/gpt-6.1-sol`, all at `reasoningEffort=xhigh`. All 6 threads on this release opened `<checkout>/plugins/pstack/skills/poteto-mode/playbooks/investigation.md` on the first try, one of them in the same `cat` as two sibling skills. All 6 threads on 2.2.8 did too, so the control did not reproduce the failure. That fits the logs, where 6 reads in 93 went wrong, 5 of them on `gpt-6.1-sol`, and at that rate six runs see no failure about two times in three. Before each failure in the logs, Codex had handed the model the whole SKILL.md, Playbooks sentence included, a few seconds earlier, so a cut read does not explain it. The repositories and threads are deleted since. + +This release syncs nothing from Lauren's pstack, so all three components stay pinned at cursor/plugins `c742dd6`. At that pin each component's dry run reports no undeclared fork and no substitution that matches nothing. Neither hooks file changes. This is a patch release, and no setting or workflow has to change. 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/README.md b/README.md index 62232a9..02fe7e6 100644 --- a/README.md +++ b/README.md @@ -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.2.9 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.2.9`, 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. diff --git a/VERSION b/VERSION index 23a63f5..a6333e4 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.2.8 +2.2.9 diff --git a/package.json b/package.json index 9c49243..81e9956 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "t3-pstack", "private": true, - "version": "2.2.8", + "version": "2.2.9", "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 8f7ec8d..6badc55 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.2.9", "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 94cdd77..4497fee 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.2.9", "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",