Skip to content

Cursor plugin specification and official plugins

TypeScript

docs(pstack): bring guide current with new skills and playbooks (#188)

lauren424829e3e0f7
diff --git a/pstack/docs/guide/02-poteto-mode.md b/pstack/docs/guide/02-poteto-mode.md
index d2d7b025..48d25d04 100644
--- a/pstack/docs/guide/02-poteto-mode.md
+++ b/pstack/docs/guide/02-poteto-mode.md
@@ -25,7 +25,7 @@ flowchart TD
J --> K
```
-The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, babysitting a PR or stack to merge-ready, shipping a verified stack, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set.
+The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set.
## Say the goal, not the ceremony
@@ -73,6 +73,14 @@ If you run several agents against one repository, they will fight over the worki
Each task in its own branch and worktree means no agent stomps another's files. The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) already works from a worktree for code changes, so mostly you only say this when a specific base or location matters.
+Worktrees accumulate. When disk gets tight, ask:
+
+```text
+/poteto-mode what's eating my disk? prune the worktrees that are safe to prune.
+```
+
+The [Worktree cleanup playbook](../../skills/poteto-mode/playbooks/worktree-cleanup.md) classifies every worktree by merge state, uncommitted work, and which chats still touch it. It deletes only what that evidence clears and pauses for your call on anything holding uncommitted work.
+
## Leave it running
When you step away, say what done means and go:
diff --git a/pstack/docs/guide/05-build-and-clean.md b/pstack/docs/guide/05-build-and-clean.md
index 24c63480..c38bc44a 100644
--- a/pstack/docs/guide/05-build-and-clean.md
+++ b/pstack/docs/guide/05-build-and-clean.md
@@ -58,6 +58,18 @@ For prose, `/unslop` takes a target and any extra rules you have:
You'll develop your own shorthand. The skill reads intent fine from terse prompts like `unslop that, tighten it`.
+## Strip the comments with `/no-comments`
+
+Comments need their own pass, and not from the agent that wrote them. An author defends its comments the way you'd defend yours. So before review, hand them to fresh eyes:
+
+```text
+/no-comments the diff
+```
+
+[`/no-comments`](../../skills/no-comments/SKILL.md) spawns [Comment Sicko](../../agents/comment-sicko.md), a read-only reviewer with a short keep list: license headers, doc comments on a public API, links that explain what code can't, behavior forced by an external dependency you can't reshape. Everything else goes. A surprise in your own code gets no such pass. The comment comes back as a refactor flag, and `/no-comments` fixes the flags it accepts at the root cause. When a comment claims a constraint, "do not remove", the skill offers to encode the claim as a type, test, or lint. Either way, the comment comes out.
+
+The division of labor is worth keeping straight. `/deslop` cleans slop out of the code, `/unslop` cleans it out of prose, and `/no-comments` hands the comments to a reviewer who didn't write them.
+
**Pitfall:** cleanup is not optional polish. A diff with narrating comments and defensive dead weight reads as unfinished to reviewers, and the extra code is where the next bug hides. If the diff feels padded, say `deslop it` before you commit, not after review calls it out.
Next: [Verify and ship](./06-verify-and-ship.md).
diff --git a/pstack/docs/guide/06-verify-and-ship.md b/pstack/docs/guide/06-verify-and-ship.md
index 2a84d2a8..67cecbac 100644
--- a/pstack/docs/guide/06-verify-and-ship.md
+++ b/pstack/docs/guide/06-verify-and-ship.md
@@ -1,6 +1,6 @@
# Verify the result and open a PR
-"It compiles" is not evidence. The [Prove It Works principle](../../skills/principle-prove-it-works/SKILL.md) makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, generating a verification skill for your app, and shipping.
+"It compiles" is not evidence. The [Prove It Works principle](../../skills/principle-prove-it-works/SKILL.md) makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, generating a verification skill for your app, opening the PR, and driving it to merged.
![A prototype plane flies a real test course while she times it with a stopwatch and robots film and checklist the run; the terminal reads verify: pass, evidence: captured.](./images/verification.jpg)
@@ -50,7 +50,7 @@ Apps change and feature maps rot. When yours drifts, run:
[`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) audits the generated skill: one read-only source reader per feature in parallel, then one live pass that drives every mapped feature. It ends in exactly one of three outcomes. `clean` means full coverage and nothing to ship. `changed` means one PR of proven corrections, confined to the verification skill's own directory. `blocked` names the blocker. It never edits product code. If the live pass catches a product regression, it reports the regression instead of papering over it in docs.
-## Ship it
+## Open the PR
```text
/poteto-mode open the pr. small ordered commits, evidence in the description.
@@ -58,7 +58,30 @@ Apps change and feature maps rot. When yours drifts, run:
The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) works from a worktree, rebases the work into small ordered commits, cleans the diff, unslops the prose, and returns the PR link. Five narrow PRs beat one fat one, and stacked follow-ups beat a growing branch.
-> [!NOTE]
-> pstack doesn't bundle PR monitoring or stacked-PR tooling. After the PR opens, use Cursor's built-in PR tools to watch CI and process review comments. Judge each comment against your intent before changing code. Reviewers, human and bot, file real catches and noise in the same list.
+## Drive the PR to merge-ready with Babysit
+
+An open PR starts collecting blockers immediately. Checks fail, reviewers comment, trunk moves. Hand that churn to the [Babysit playbook](../../skills/poteto-mode/playbooks/babysit.md):
+
+```text
+/poteto-mode babysit this pr. get it green.
+```
+
+Babysit watches the PR with a bundled watcher and takes blockers in order: conflicts, then review threads, then CI. Every known fix batches into one push, so the checks restart once instead of after every fix. The comment triage is skeptical, because humans and bots file real catches and noise in the same list. A real finding gets a fix, and noise gets dismissed with the disproof posted on the thread. When all you want is status, ask smaller and Babysit answers without starting the loop:
+
+```text
+/poteto-mode check on pr 123. anything outstanding?
+```
+
+Babysit stops at merge-ready. It never merges, even with everything green, because merging is a different decision.
+
+## Land the stack with Shipping
+
+Green is not the same as safe. When you're ready to land, say so:
+
+```text
+/poteto-mode land the stack.
+```
+
+The [Shipping playbook](../../skills/poteto-mode/playbooks/shipping.md) verifies each PR independently before it arms anything. One fresh agent per PR proves the behavior live, and the agent that judges a change is never the one that wrote it. Then Shipping lands only the contiguous verified run from the bottom, through Graphite merge-when-ready, and reports the first PR that breaks the chain. A verified PR sitting above an unverified one waits, because merging it would pull the gap in underneath.
Next: [Run work while you sleep](./07-overnight.md).
diff --git a/pstack/docs/guide/07-overnight.md b/pstack/docs/guide/07-overnight.md
index 9f7d891b..30300c9d 100644
--- a/pstack/docs/guide/07-overnight.md
+++ b/pstack/docs/guide/07-overnight.md
@@ -54,6 +54,28 @@ When you're back, ask for the run in review form:
Before the skill hands back its summary, it spawns a reviewer on a different model family to read the trail and the transcript, and the reply ends with an Attention section listing what deserves your scrutiny. Read that section first, then the log rows it points at. You're auditing decisions, not re-reading the whole night.
+## When the night holds a queue, not a task
+
+The contract above drives one task to one finish condition. Some nights hold more, a queue of independent changes or a whole program. Three playbooks scale the same trust up.
+
+[Autopilot-full](../../skills/poteto-mode/playbooks/autopilot-full.md) runs a queue of independent PRs to merged. Each PR gets one owner agent that carries it from build through merge, and no owner merges on its own verdict. A swarm of fresh verifiers checks every merge-ready head, and only a clean verdict authorizes the merge:
+
+```text
+/poteto-mode full autopilot on this queue. each item is independent. i want them merged by morning.
+```
+
+[Autopilot-stack](../../skills/poteto-mode/playbooks/autopilot-stack.md) runs the same owner loop but ships nothing. You wake up to one linear Graphite stack with a verifier's verdict on every link, and you review and land it yourself. Pick it over Autopilot-full when the changes are coupled, or when you want your own eyes on the work before anything merges:
+
+```text
+/poteto-mode autopilot these five changes but stack them, don't ship. i'll land the stack in the morning.
+```
+
+[Orchestrate](../../skills/poteto-mode/playbooks/orchestrate.md) is for a program that outlives any single agent: multi-day, many stacked PRs, fleets of subagents under one standing coordinator chat. The coordinator authors briefs, collects what its subagents finish, keeps the lowest unmerged PR green, and never writes code itself. It's deliberately heavy machinery. If one agent could finish the work in a session, the playbook itself routes you back to the overnight contract above:
+
+```text
+/poteto-mode orchestrate the store migration. own it until every package is converted and merged. i'll check in twice a day.
+```
+
**Pitfall:** a duration is not a finish condition. "work on this for 4 hours" gives the agent nothing to check, and you'll wake up to four hours of motion instead of a result. Give `/loop` a predicate that can pass or fail.
Next: [Steer with principle names](./08-principles.md).
diff --git a/pstack/docs/guide/09-make-it-yours.md b/pstack/docs/guide/09-make-it-yours.md
index 784756f7..6723069b 100644
--- a/pstack/docs/guide/09-make-it-yours.md
+++ b/pstack/docs/guide/09-make-it-yours.md
@@ -40,6 +40,16 @@ Writing a skill matches the [Authoring or modifying a skill playbook](../../skil
One special case has its own generator. A skill that must drive your app and prove behavior is a verification skill, so use [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md) and [`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) instead. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers both.
+## Write docs to a standard with `/technical-writing`
+
+Skills aren't the only prose you ship. For docs, RFCs, readmes, PR descriptions, and commit messages:
+
+```text
+/technical-writing review the readme changes
+```
+
+[`/technical-writing`](../../skills/technical-writing/SKILL.md) applies a layered standard with one goal, prose a tired engineer understands on the first read. It picks the document's mode first (tutorial, how-to, reference, or explanation), then works sentence by sentence: who does what, one thought per sentence, nothing readable two ways. Use it to review what you or an agent just wrote, or name it up front when you ask for a doc.
+
## Test a skill change blind
A skill edit affects every future session, so test it like the experiment it is:
diff --git a/pstack/docs/guide/10-recipes-and-pitfalls.md b/pstack/docs/guide/10-recipes-and-pitfalls.md
index 81176d66..da0af5e6 100644
--- a/pstack/docs/guide/10-recipes-and-pitfalls.md
+++ b/pstack/docs/guide/10-recipes-and-pitfalls.md
@@ -70,6 +70,14 @@ apply prove it works. show me the real output, not the build log.
You rarely need more words. You need the right name, and [the principles page](./08-principles.md) is the vocabulary.
+## Get the reply in plain words
+
+```text
+/bro
+```
+
+That's the whole prompt. [`/bro`](../../skills/bro/SKILL.md) restates the last message like one human talking to another, no jargon, shorter. Use it when a reply is technically thorough and you still don't know what it said.
+
## The pitfalls
- **Enumerating skills in the prompt.** "use /how then /architect then /arena" reorders steps the playbook already sequences. State the goal and constraints. Name a skill only to override a default.
diff --git a/pstack/docs/guide/README.md b/pstack/docs/guide/README.md
index f6fd3e80..e3766019 100644
--- a/pstack/docs/guide/README.md
+++ b/pstack/docs/guide/README.md
@@ -8,9 +8,9 @@ Here's what you'll learn:
2. [Route work through `/poteto-mode`](./02-poteto-mode.md). Give it a goal and watch it pick a playbook.
3. [Understand the code](./03-understand.md). `/how`, `/why`, `/teach`, and `/recall` before you edit anything.
4. [Design the change](./04-design.md). `/architect`, `/arena`, `/swarm`, and `/interrogate` before code locks in a shape.
-5. [Build and clean the change](./05-build-and-clean.md). The build playbooks, `/tdd`, and `/unslop`.
-6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, then open a focused PR.
-7. [Run work while you sleep](./07-overnight.md). An overnight contract and a decision log you can audit.
+5. [Build and clean the change](./05-build-and-clean.md). The build playbooks, `/tdd`, `/unslop`, and `/no-comments`.
+6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, then open a focused PR and drive it to merged.
+7. [Run work while you sleep](./07-overnight.md). An overnight contract, a decision log you can audit, and the playbooks that scale past one agent.
8. [Steer with principle names](./08-principles.md). The 21 names that redirect an agent mid-task.
9. [Make it yours](./09-make-it-yours.md). Your own mode, plus how to test a skill change.
10. [Recipes and pitfalls](./10-recipes-and-pitfalls.md). Prompts to copy and mistakes to skip.