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

pstack: refresh the docs and add a docs-vs-tree check#704
poteto merged 6 commits into
mainfrom
lauren/pstack-docs-pass-e1b2

Conversation

@poteto

@poteto poteto commented Oct 17, 2026 •
edited
Loading

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
@cursoragent @poteto
feat(pstack): add a check that diffs the docs against the skill tree
beb798b 
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.
@cursoragent @poteto
docs(pstack): fix stale claims about autopilot, custom modes, and the…
4f4a798 
… harness
@cursoragent @poteto
pstack docs: plain-language pass on the guide and README
d0dd26b 
Remove idioms, metaphors, comma splices, and mid-sentence colons that
the technical-writing and unslop standards flag. No claims change.
@cursoragent @poteto
docs(pstack): drop an unbacked claim about custom mode turns
b01e5c0
@poteto
docs(pstack): regenerate the Claude Code tree for the docs pass
45ccae0 
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
@poteto
fix(pstack): check links that carry a title in check-pstack-docs
339f8ba 
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.
@poteto
poteto marked this pull request as ready for review October 17, 2026 23:56
@poteto
poteto merged commit 019a6a2 into main Oct 17, 2026
2 checks passed
@omegamaster86 omegamaster86 mentioned this pull request Oct 18, 2026
Merged
@cursor cursor Bot mentioned this pull request Oct 18, 2026
Merged
@fullerzz fullerzz mentioned this pull request Oct 18, 2026
Merged
@chhoumann chhoumann mentioned this pull request Oct 18, 2026
Merged
@sandwichlegend sandwichlegend mentioned this pull request Oct 18, 2026
Merged
caelaxie added a commit to pstack-ports/devin-pstack that referenced this pull request Oct 18, 2026
@caelaxie @cursoragent
sync pstack through upstream 182f2ce (#2)
07dea45 
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
baseline `2418e86` matches upstream pstack at
[`e5136d8`](cursor/plugins@e5136d8)
([#633](cursor/plugins#633)). diffed the
baseline tree against `pstack/` at `e5136d8` and at its parent
`850d7f2`. the parent still has the pre-#633 principle text. the only
path in `e5136d8` that the baseline lacks is `pstack/.cursor-plugin/`,
which this port never carried (devin uses `.devin-plugin/plugin.json`).

upstream `main` has no pstack commits after `019a6a2`. version is still
`0.15.25` upstream, so plugin.json, `.devin-plugin/plugin.json`, and the
readme stay at `0.15.25`. synced to
`019a6a20592c10bf92869e5740368f578a9997fd`.

ported:
-
[`99743e9`](cursor/plugins@99743e9)
([#634](cursor/plugins#634)) cut marginal
sections from `interrogate/references/lead-judgment.md`,
`principle-migrate-callers-then-delete-legacy-apis`,
`principle-type-system-discipline`, and `swarm`. kept the existing devin
frontmatter (`triggers: [user]`) and the existing devin swarm wording.
the #634 readme table edit drops "refuse to lie to the compiler" from
the upstream principle index. this port's readme no longer has that
index, and the phrase lived only in the skill description, which is
updated.
-
[`0317eb8`](cursor/plugins@0317eb8)
([#700](cursor/plugins#700)) brand via a type
guard in `typescript-best-practices` `SKILL.md` and
`references/patterns.md`. kept `triggers: [user, model]` and the dropped
`paths` frontmatter.
-
[`a968159`](cursor/plugins@a968159)
([#702](cursor/plugins#702)) `poteto-mode`
frontmatter `name` is now `poteto-mode`. `make-bot-ui` already had
`name: make-bot-ui` from the devin port. other skills already matched
their folders.
-
[`019a6a2`](cursor/plugins@019a6a2)
([#704](cursor/plugins#704)) guide prose and the
autopilot-full claim in `docs/guide/02` through `10`. kept existing
devin wording (`/pstack:` prefixes, cloud sessions, `.devin` paths).

skipped:
-
[`e5136d8`](cursor/plugins@e5136d8)
([#633](cursor/plugins#633)) is already the
baseline.
-
[`182f2ce`](cursor/plugins@182f2ce)
([#637](cursor/plugins#637)) is claude code
generated-tree install. core `pstack/skills` is unchanged. the "benny is
cursor-only" sentence is skipped because this port already runs benny as
devin sessions.
-
[`a968159`](cursor/plugins@a968159)
generator check in `scripts/generate-pstack-harness-trees.mjs`. that
script builds the claude code tree and does not apply to this repo.
-
[`1b80080`](cursor/plugins@1b80080)
([#705](cursor/plugins#705)) is claude code
packaging. it edits `docs/harness/claude-code.md`, the generated
`harness/pstack/claude-code` tree, the generator, and the claude code
install blurb in the upstream readme. no skill text under
`pstack/skills` changes. this port has no claude code adapter.
-
[`019a6a2`](cursor/plugins@019a6a2)
`scripts/check-pstack-docs.mjs` and the regenerated claude code copies.
the check hardcodes a `pstack/` subdirectory, the full upstream readme
tables, and a sibling `cursor-team-kit`. this repo is the plugin at the
root with a short devin readme, so the script does not apply as-is. the
upstream readme edits that only touch the claude code install blurb, the
cursor custom-mode paragraph, and the built-in `/babysit` to
`/autopilot` rename are also skipped. this port's readme does not have
those sections, and `docs/guide/01-setup.md` already tells devin to pin
the style in `AGENTS.md` instead of a cursor custom mode. the
autopilot-full claim from that readme table is ported in
`docs/guide/07-overnight.md`.

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a
href="https://cursor.com/agents/bc-5e99de38-babb-516d-92d0-296b6550796a?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-5e99de38-babb-516d-92d0-296b6550796a&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: Kaitian Xie <[email protected]>
@cursor
cursor Bot deleted the lauren/pstack-docs-pass-e1b2 branch October 18, 2026 19:50
@MondayNotAGoodDay MondayNotAGoodDay mentioned this pull request Oct 19, 2026
Merged
MondayNotAGoodDay added a commit to MondayNotAGoodDay/skills that referenced this pull request Oct 19, 2026
@MondayNotAGoodDay
Follow pstack 0.15.27 (#3)
5df7935 
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## 跟进了什么

上游 pstack 从 0.15.25（`6ce45c59`，2026-10-14）到了 0.15.27（`0148b78c`，[#713](https://github.com/cursor/plugins/pull/713)），并接上没有改版本号的 [#715](https://github.com/cursor/plugins/pull/715)（`f9be7aa00c2b2bf4b13562143a6918445e06b99d`，2026-10-18）。接到现有 fork 上，没有整目录覆盖。这次 pin 写在 `UPSTREAM.md`。

- 新技能：`/create-formal-verification-skill`。`/setup-pstack` 在验证技能之后再问一次要不要生成它。`poteto-help` 和指南对上了这个入口。
- `/ketchup` 改成把每一个等待用户的决定都列出来，回复本身就能做出决定。事情本身压在 100 词以内，条目多了就变长，不为了卡字数而删条目（[#692](https://github.com/cursor/plugins/pull/692)、[#708](https://github.com/cursor/plugins/pull/708)）。
- `/sharpen` 不再禁止把改写后的提示交还来（[#712](https://github.com/cursor/plugins/pull/712)）。
- 四条 principle 改成推理而不是死规则：`attack-the-premise`、`fix-root-causes`、`make-operations-idempotent`、`test-behavior-not-implementation`（[#633](https://github.com/cursor/plugins/pull/633)）。`correct` 的测试句一并改了。`poteto-mode` 里对应的一行说明跟着改，spawn 段没动。
- 四处边际段落拿掉：`interrogate` 的 lead judgment、`migrate-callers`、`type-system-discipline`、`swarm` 的引言、N 的说明和结果表（[#634](https://github.com/cursor/plugins/pull/634)）。`swarm` 仍走 profile 的 `role` / `isolation` / `inherit`。
- TypeScript 品牌用类型守卫写，不再用 `as`（[#700](https://github.com/cursor/plugins/pull/700)）。
- 指南按上游刷新了用词，并写上了形式化验证、`/ketchup`、`/sharpen`、`/in-your-own-words`（[#704](https://github.com/cursor/plugins/pull/704)、[#715](https://github.com/cursor/plugins/pull/715)）。fork 里已经改成 harness-neutral 的句子保留，包括项目技能仍写到 `.agents/skills/`。

## 跳过的安装专用 PR

- [#637](cursor/plugins#637) 和 [#705](cursor/plugins#705) 只改 Claude Code 安装：`docs/harness/claude-code.md`、生成的 harness 树、README 里的 `/plugin install`。这个 fork 走 skills.sh，不引入 `.claude-plugin/plugin.json`，这两个 PR 也没有改到这里实际发出的技能正文。
- [#702](cursor/plugins#702) 把 `Poteto Mode` 改成 `poteto-mode`，把 `Make Bot UI` 改成 `make-bot-ui`。这个 fork 的 `poteto-mode` 已经跟目录名一致，且不发 `make-bot-ui`。
- [#704](cursor/plugins#704) 里的 docs-vs-tree 脚本在 `pstack/` 外，检查的是生成的 Claude Code 树。这里不构建那棵树，所以没带脚本；指南正文的刷新已经接上。
- [#710](cursor/plugins#710) 和 [#713](cursor/plugins#713) 只改插件清单的版本号。这个仓库没有 `plugin.json`，版本记在 `UPSTREAM.md`。

## 保留的 fork 约定

- Spawn 仍走 profile：`role` / `access` / `run`，`inherit`，面板上的 `ask`。技能正文不点名 harness 工具，也不写模型 slug。
- 没有把模型 slug、`Task` / `subagent_type` 或 `pstack-models.mdc` 写回去。`setup-pstack` 的 harness 提示（`references/harness-hints.md`）没动。
- `inherit` 仍表示不覆盖模型。harness 拒绝调整后用 profile 值并说明。
- `poteto-agent` 和 Comment Sicko 仍是提示文件（`skills/poteto-mode/references/poteto-agent.md`、`skills/no-comments/references/comment-sicko.md`）。
- 历史、循环、提问仍是 profile 能力（`history`、`loop`、`ask`）。配方里仍是 `loop until done`，不是 `/loop`。
- 技能目录仍是 skills.sh 要的 `skills/<name>/SKILL.md`，frontmatter 有 `name` 和 `description`，`name` 与目录名一致。上游笔记里的 `.agents/skills/` 没有拿来覆盖这个布局。生成的项目技能仍写到 `.agents/skills/`。
- `eli5`、`show-me`、`html-plan` 没动。`third_party/pstack/LICENSE` 没动。没有引入 `make-bot-ui` 或 Benny。

## 校对

- `npx skills add . --list` 找到 57 个技能（上一次是 56），包括 `create-formal-verification-skill`、`ketchup`、`sharpen`、`eli5`、`show-me`。frontmatter 的 `name` 与目录名一致。
- 改过的技能里没有冲突标记，也没有写回模型 slug 或 `pstack-models.mdc`。

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a href="https://cursor.com/agents/bc-feb72324-ccdf-58a8-88fc-65839b7d8caf?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a href="https://cursor.com/background-agent?bcId=bc-feb72324-ccdf-58a8-88fc-65839b7d8caf&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>
This was referenced Oct 19, 2026
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@poteto @cursoragent