Skip to content

pstack: refresh the docs and add a docs-vs-tree check - #704

Merged
poteto merged 6 commits into
mainfrom
lauren/pstack-docs-pass-e1b2
Oct 17, 2026
Merged

poteto merged 6 commits into
mainfrom
lauren/pstack-docs-pass-e1b2

Conversation

@poteto

@poteto poteto commented Oct 17, 2026 •

Copy link
Copy Markdown
Collaborator

This brings the pstack README and guide in line with the current tree. It also adds a script that finds the next drift.

Stale claims fixed

  • The README said Cursor ships a built-in /babysit. Cursor now ships /autopilot.
  • The README and the overnight page said autopilot-full runs a full verifier swarm on every later push. The playbook runs the full swarm on the code-ready head. After that, a rebase or a small fix gets one fresh verifier, and only new behavior or a large diff gets the full swarm again.
  • The README said that in Custom Mode, poteto-mode decides on its own when to apply, and that you can opt out by saying so. Neither the skill nor the Cursor docs back that. Both Custom Mode links now go straight to the Custom Mode section of the skills docs.
  • The README listed the files that make the Claude Code tree go stale. That list grew when the tree started to copy the README and the guide, so the README now says to run the generator after any pstack change, and that the copy includes the README and the guide.
  • The poteto-mode page said autopilot runs a PR queue. It also runs a stack.

Check script

node scripts/check-pstack-docs.mjs lists the skills, slash commands, playbooks, and agents in the tree and compares them with what the docs name. It also checks relative links, anchors, whole-set counts, and model names. On main it finds one problem, the /babysit claim. On this branch it finds none. CI does not run it yet.

Prose pass

Each guide page already keeps to one Diátaxis mode, so no page was split. The prose commit makes only sentence-level edits. It removes idioms, metaphors, comma splices, and mid-sentence colons, and it changes no claims.

The Claude Code tree copies the README and the guide, so one commit regenerates those copies. validate-plugins.mjs and generate-pstack-harness-trees.mjs --check pass.


Note

Low Risk
Changes are limited to documentation and a validation script; no runtime product or auth paths are modified.

Overview
This PR refreshes pstack documentation so the README and guide match the current skills tree, and adds scripts/check-pstack-docs.mjs to catch future drift (slash commands, links/anchors, inventory counts, README tables, model names).

Accuracy fixes include replacing the stale built-in /babysit claim with /autopilot, tightening autopilot-full verifier behavior (full swarm on code-ready head; lighter checks on small follow-up pushes), simplifying Custom Mode wording and linking to the official anchor, and broadening harness regen instructions now that the Claude copy includes the README and guide.

The guide gets a sentence-level prose pass (no structural Diátaxis changes). The new checker is not wired into CI yet (per PR description).

Reviewed by Cursor Bugbot for commit 339f8ba. Bugbot is set up for automated code reviews on this repo. Configure here.

cursoragent and others added 5 commits October 17, 2026 16:41
scripts/check-pstack-docs.mjs lists pstack's skills, playbooks, and agents
from the tree. It checks pstack/README.md and pstack/docs/guide for unknown
or renamed slash commands, broken relative links and anchors, whole-set
counts, unknown subagent types, model names that setup-pstack does not use,
and skills, playbooks, or agents missing from the README tables.
Remove idioms, metaphors, comma splices, and mid-sentence colons that
the technical-writing and unslop standards flag. No claims change.
The Claude Code tree now ships pstack/README.md and pstack/docs/guide/, so the docs-pass edits to those files need regenerated copies for --check to pass.
@poteto
poteto force-pushed the lauren/pstack-docs-pass-e1b2 branch from 8e18a49 to 45ccae0 Compare October 17, 2026 23:44
The link pattern needed ')' right after the target, so [x](a.md "title") and [x](<a.md>) were never checked and a broken one passed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants