[chhoumann]

Why

A Codex agent following poteto-mode should open the playbook it matched on the first try. The Playbooks section says to open a playbook's steps at playbooks/<title>.md and names no base, while line 8 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, and the agent spends a turn finding skills/poteto-mode/playbooks/. @adryanev reported it and diagnosed it in #71.

What changed

• One anchored substitution in tools/substitutions.json. The sentence now reads "open its full steps at playbooks/<title>.md from this file (skills/poteto-mode/playbooks/<title>.md)". "From this file" is how line 8 states its base, and the parenthetical is a suffix that holds in the plugin cache and in a repo checkout. Lauren's sentence is the same at the pin and at cursor/plugins main 6b03002, so the rule will keep matching after the next sync.
• The forked SKILL.md carries the rule's text. tools/forks.json declares poteto-mode's SKILL.md a fork, and the sync keeps a fork's copy, so the copy needs the same words. Deriving upstream at the pin with the new rules and diffing it against the copy gives the same fork lines as on main, byte for byte, line 132's .audit/<task-slug>.todo.md sentence included.
• Release 2.2.9. VERSION, the CHANGES.md entry with the evidence below, the stamped manifests, and the README's two tag examples.

Evidence

• poteto-mode: agents read playbooks from skills/playbooks, which does not exist #71's own logs. 16 failures from 2026-11-04 to 2026-11-08, across 15 sessions, all Codex shell reads, 13 on 2.2.1 and 3 on 2.2.8.
• This Mac's Codex logs. 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, on 2.0.0-rc.5, rc.9, rc.15, rc.17, 2.1.0, and 2.2.0. 5 of the 6 ran on gpt-6.1-sol and 1 on gpt-6-astra, and 5 of the 6 read the playbook in the same call as a sibling skill. Each was followed by a read of the right path 5 to 29 seconds later. In each case Codex had handed the model the whole SKILL.md, Playbooks sentence included, a few seconds before, so a cut read does not explain it. A plain grep finds 17 lines in 10 rollout files, because Codex logs a command's output twice and forked or compacted rollouts copy their parent's history.
• Claude Code. Its sessions on this Mac show no such read. Every Claude Code transcript that names the path quotes a Codex one. Claude Code names a skill's base directory when it loads the skill.
• Other relative paths. The playbooks name each other as playbooks/<title>.md, from poteto-mode's directory rather than their own, and Babysit and Multi-phase plan name ../references/bugbot-triage.md. No session on this Mac shows a failed read of either kind, so this PR leaves them. The plugin's other failed reads on this Mac are of a release directory that a later update had removed (2.0.0-rc.16), which no wording fixes.

Proof

These runs used T3 0.1.8-nightly.20261108.4367 on this Mac. There were 12 fresh Codex threads, each in its own 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 branch, or of main (2.2.8) as the control, and that the installed plugin is 2.2.8. Each was also told to change no file, start no subagent, and write no MISTAKES, LEARNINGS, or DESIRES file. Three ran per arm on each model. The counts come from each thread's Codex rollout, not from its reply.

Arm	codex/gpt-6-astra xhigh	codex/gpt-6.1-sol xhigh
This branch	3 of 3 opened /private/tmp/pb229/plugins/pstack/skills/poteto-mode/playbooks/investigation.md first try	3 of 3 first try, one in the same cat as why and unslop
2.2.8 control	3 of 3 first try	3 of 3 first try

The control did not reproduce the failure. That fits the logs' rate of 6 in 93, at which six runs see no failure about two times in three. So these runs show that the new sentence resolves to the right file, including in the batched read where the failures happened. They do not measure the rate drop, which would take hundreds of runs per arm. No thread changed a file, and the repositories, projects, and threads are deleted.

Verification

• bun install --frozen-lockfile and bun tools/generate.mjs --check pass, with 17 generated files current.
• GIT_CONFIG_GLOBAL=/dev/null bun test tests/ --timeout 30000 gives 561 pass, 56 skip, 0 fail.
• bun tools/sync.mjs <component> <pin> --dry-run for pstack, cursor-team-kit, and thermos at c742dd6 exits 0, and its report matches main's line for line, so there is no undeclared fork and no rule that matches nothing.
• Neither hooks file changes.

Closes #71

---

Note

Low Risk
Documentation-only skill instruction and release metadata; no runtime, auth, or installer logic changes beyond version bumps.

Overview
Release 2.2.9 clarifies where poteto-mode playbooks live so Codex agents do not resolve playbooks/<title>.md under the wrong skills/ base when they batch-read sibling skills.

The Playbooks line in poteto-mode/SKILL.md now says paths are from this file and adds the concrete suffix skills/poteto-mode/playbooks/<title>.md, matching how bundled skills are described. The same wording is anchored in tools/substitutions.json so forked copies stay correct on sync. Version stamps and README install-tag examples are updated to 2.2.9; CHANGES.md documents the #71 diagnosis and release notes.

^{Reviewed by Cursor Bugbot for commit de942f0. Bugbot is set up for automated code reviews on this repo. Configure here.}