fix(pstack): close three gaps in the Claude Code plugin

[poteto]

Why

Three things in the pstack Claude Code plugin did not work the way a user expects:

• /pstack:setup-pstack stopped without writing anything. The adapter told it that Claude Code does not read pstack-models.mdc and that it had nothing to write, so no skill could use the user's model choices.
• When a step needed Automations, Bugbot, Cursor cloud agents, or a built-in PR tool, the adapter only said "say so, skip that step, and continue." The model wrote several paragraphs about what it could not do, and the user had to find out which step was skipped.
• The tree did not include the guide or the README. /pstack:poteto-help linked to them on GitHub main, so Claude Code fetched them with WebFetch and asked the user for permission first.

What changed

All of the changes are in the Claude Code adapter, the generator, the generated tree, and two paragraphs of pstack/README.md. pstack/skills/** is byte-identical to main, so Cursor loads the same files as before.

• Model choices. Claude Code loads every .md file in ~/.claude/rules/ into each new session. The adapter now maps the Cursor rule ~/.cursor/rules/pstack-models.mdc to ~/.claude/rules/pstack-models.md. A new setup-pstack section in the adapter tells setup to:

  • detect models from the Agent tool schema,
  • write each role as <model> <effort>, such as opus high,
  • write the file with no frontmatter.

  It still never writes role lines into CLAUDE.md or AGENTS.md. A new Models row maps a role value such as opus high to model: "opus" and effort: "high".

• Cursor-only steps. The adapter now gives one exact line, Skipped in Claude Code: <step>. <reason>., then the model goes to the next step without stopping, asking, or retrying. When a later step needs what the skipped step made, such as a webhook URL or a key, the model leaves a placeholder and names it in that line. A table says what each feature maps to:

  • Bugbot comments on a GitHub PR are ordinary review threads, so the model triages them as usual.
  • environment: "cloud" maps to a worktree.
  • A built-in PR tool maps to the step's forge command. That is not a skip, so the model writes no line.

  The generator's term check now also matches "built-in PR tool", so a skill that names it gets the adapter line.

• Guide and README. The generator now copies pstack/docs/guide/ (pages and images) and pstack/README.md into harness/pstack/claude-code/, the same way it copies the skills. Relative links to these files now resolve in the tree, so poteto-help links to ../../docs/guide/01-setup.md instead of GitHub. The adapter's Paths table maps a github.com/cursor/plugins/blob/main/pstack/<path> URL to the local copy and tells the model never to fetch it. --check compares the guide and README the same way it compares the skills, so it catches drift in them too.

• pstack/README.md and the generated harness/pstack/README.md list the new sources and say where Claude Code writes model choices.

Tradeoffs

• The tree is bigger. The guide adds about 1,100 lines of markdown and six JPGs, about 2.2 MB, so the Claude Code install has a second copy of the guide. Without the images, guide pages show broken images in Claude Code. Linking the images to GitHub would avoid the copy, but --check would not catch image drift and the guide would not work offline.
• Four links still point at GitHub main: two in the README and two in guide page 7. They point at pstack/automations/benny, which is Cursor-only and is not in the tree. No skill tells the model to follow them.
• The rule file loads into every Claude Code session, not only pstack sessions, so each session has about 250 extra tokens. Claude Code has no per-plugin rules folder, and setup must write a file that Claude Code reads without the user doing more work.
• Claude Code loads the rule file only when a session starts. Setup says this, and the next session uses the new models.

Verification

All runs used real Claude Code 2.1.302 through the Agent SDK, each with a new HOME and the plugin loaded as a local plugin from a copy of the tree. In each pair, one run used the tree on main and one run used the tree from this PR.

• Setup writes a file that a later skill reads. On main, setup wrote nothing and told the user that per-role models do not work in Claude Code. With this PR, setup asked for a budget, wrote ~/.claude/rules/pstack-models.md (how explainer: opus high), and wrote nothing to CLAUDE.md or AGENTS.md. A new session in the same HOME then ran /pstack:how, which started its explainer with model: "opus", effort: "high". With no rule file, the same prompt started it with effort: "xhigh", the skill default. In a third session with a copy of that file, /pstack:poteto-help read the role from it.

• A Cursor-only step degrades cleanly. /pstack:make-bot-ui needs a Cursor Automations webhook routine. On main, the reply described the missing routine over several paragraphs and numbered steps. With this PR, the reply has one line: Skipped in Claude Code: creating the webhook routine, getting its URL and sender key, and requesting the key through a secret card. Claude Code has no Cursor Automations, so the URL and key are placeholders. The model then built the page with placeholder values.

• poteto-help works without WebFetch. When asked to quote guide page 1, the main tree made 1 WebFetch call to raw.githubusercontent.com and asked for permission. The tree from this PR made 0 WebFetch calls and quoted the page from docs/guide/01-setup.md in the plugin. When asked about an overnight run that finished nothing, the tree from this PR answered from the bundled guide page 7 with 0 WebFetch calls.

• Links. All 235 relative links in the bundled guide and README resolve inside the tree. 0 links leave the tree, and 0 links are broken.

• Drift. Each of these changes made --check exit 1 and name the path:

  • a hand edit to a guide page in the tree,
  • a change to a source guide page,
  • a change to the source README,
  • a stray file in the guide folder,
  • a changed image,
  • a deleted image.

  After each restore, --check exited 0.

• node scripts/generate-pstack-harness-trees.mjs --check and node scripts/validate-plugins.mjs exit 0. git diff --stat origin/main -- pstack/skills is empty.

---

Note

Low Risk
Docs, adapter, and generated harness output only; Cursor skill sources are unchanged and behavior is scoped to Claude Code installs.

Overview
Closes three Claude Code parity gaps without changing pstack/skills/** (Cursor still loads the same skill files).

Model setup. The adapter no longer tells /pstack:setup-pstack to bail out. It maps Cursor’s pstack-models.mdc rule to ~/.claude/rules/pstack-models.md, documents how to detect models from the Agent schema, write <model> <effort> role lines, and map those values when spawning agents.

Cursor-only steps. Steps that need Automations, Bugbot, cloud agents, or similar must emit a single Skipped in Claude Code: … line, continue without blocking, and use placeholders when later steps need skipped outputs. Built-in PR actions fall through to forge commands like gh (not a skip). The harness generator’s Cursor-term check now includes built-in PR tool.

Bundled docs. The harness tree generator copies docs/guide/ and pstack/README.md into harness/pstack/claude-code/ so help and guide links resolve locally instead of triggering WebFetch to GitHub. The adapter’s Paths table steers agents to read the bundled copy. README and harness README list the new regen sources (docs/guide/, this readme).

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