Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/guide/05-build-and-clean.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ In context, that's enough. [`/tdd`](../../skills/tdd/SKILL.md) writes the smalle

## Clean before you commit

The [Opening a PR playbook](../../skills/marius-mode/playbooks/opening-a-pr.md) runs `/deslop` on the diff before each commit and applies [`/unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies. `/deslop` ships in the `cursor-team-kit` plugin, not in pstack. If you don't have it, ask for the same outcome in plain words: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits.
The [Opening a PR playbook](../../skills/marius-mode/playbooks/opening-a-pr.md) rereads the diff against the laziness protocol before each commit and applies [`/unslop`](../../skills/unslop/SKILL.md) to the PR description and commit bodies. `/deslop` ships in the `cursor-team-kit` plugin, not in pstack. If you don't have it, ask for the same outcome in plain words: remove narrating comments, unsupported guards, dead compatibility paths, and unrelated edits.

For prose, `/unslop` takes a target and any extra rules you have:

Expand All @@ -68,7 +68,7 @@ Comments need their own pass, and not from the agent that wrote them. An author

[`/no-comments`](../../skills/no-comments/SKILL.md) spawns [Comment Sicko](../../skills/no-comments/references/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.
The division of labor is worth keeping straight. The laziness reread 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.

Expand Down
16 changes: 2 additions & 14 deletions docs/guide/07-overnight.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,26 +54,14 @@ Before the skill hands back its summary, it spawns a reviewer on a different mod

## 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.
The contract above drives one task to one finish condition. Some nights hold a queue of changes instead.

[Autopilot-full](../../skills/marius-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 starts a round at the owner's code-ready head and again at every later push that changes the patch. Only a clean verdict on the patch that merges authorizes the merge:

```text
/marius-mode full autopilot on this queue. each item is independent. i want them merged by morning.
```

[Autopilot-stack](../../skills/marius-mode/playbooks/autopilot-stack.md) runs the same owner loop but ships nothing. You wake up to one linear base-branch 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:
[Autopilot-stack](../../skills/marius-mode/playbooks/autopilot-stack.md) runs one owner agent per change and ships nothing. You wake up to one linear base-branch stack with a verifier's verdict on every link, and you review and land it yourself:

```text
/marius-mode autopilot these five changes but stack them, don't ship. i'll land the stack in the morning.
```

[Orchestrate](../../skills/marius-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
/marius-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).
2 changes: 1 addition & 1 deletion docs/superpowers/plans/2026-09-30-tstack.md
Original file line number Diff line number Diff line change
Expand Up @@ -952,7 +952,7 @@ Edit `skills/marius-mode/SKILL.md` in place:
- [ ] **Step 5: Review with Marius**

Show the full diff (`git diff main -- skills/marius-mode`). Iterate until Marius says it reads like him.
Then run: `node scripts/check.mjs && grep -rn $'—' skills/marius-mode`
Then run: `node scripts/check.mjs` (it bans the em dash character)
Expected: `check: ok`, and the grep prints nothing.

- [ ] **Step 6: Commit, push, open PR 5**
Expand Down
2 changes: 1 addition & 1 deletion scripts/check.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ export const PORTABLE_KEYS = new Set(["name", "description", "license", "allowed
export const BANNED_TERMS = [
"AskQuestion", "Task tool", "subagent_type", "generalPurpose", "pstack-models", "setup-pstack",
"cursor-team-kit", "create-skill", "~/.cursor/", "poteto-mode", "poteto-agent",
"grok-", "gpt-5", "claude-opus-",
"grok-", "gpt-5", "claude-opus-", "deslop", "control-ui", "control-cli", "\u2014",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Apply the new banned terms to the user guide

The new terms are checked only under skills/, so user-facing guide regressions still pass validation; the current docs/guide/05-build-and-clean.md demonstrates this with deslop and cursor-team-kit on line 51 and another deslop instruction on line 73. Include docs/guide in the term scan and clean these references so the validator enforces the repository's harness-neutral requirement across the documented interface.

AGENTS.md reference: AGENTS.md:L13-L13

Useful? React with 👍 / 👎.

];
export const TERM_SCAN_ROOTS = ["skills"];
export const ALLOWED_TERMS = {
Expand Down
18 changes: 16 additions & 2 deletions scripts/check.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -64,10 +64,10 @@ test("backtick skill paths resolve from the skill root; placeholders are ignored

test("bold skill references must name an existing skill", () => {
const root = fixture({
"skills/alpha/SKILL.md": skill("alpha", "Use the **deslop** skill, the **laziness-protocol** principle skill, and the **principle-laziness-protocol** skills.\n"),
"skills/alpha/SKILL.md": skill("alpha", "Use the **ghost** skill, the **laziness-protocol** principle skill, and the **principle-laziness-protocol** skills.\n"),
"skills/principle-laziness-protocol/SKILL.md": skill("principle-laziness-protocol"),
});
assert.deepEqual(check(root), ['skills/alpha/SKILL.md:6: unknown skill "deslop"']);
assert.deepEqual(check(root), ['skills/alpha/SKILL.md:6: unknown skill "ghost"']);
});

test("banned terms are errors unless allowlisted for that file", () => {
Expand All @@ -90,3 +90,17 @@ test("model slugs are banned terms", () => {
'skills/alpha/SKILL.md:6: banned term "claude-opus-"',
]);
});

test("cursor-team-kit skill names are banned terms", () => {
const root = fixture({ "skills/alpha/SKILL.md": skill("alpha", "Run `/deslop`, then drive it with control-ui or control-cli.\n") });
assert.deepEqual(check(root), [
'skills/alpha/SKILL.md:6: banned term "deslop"',
'skills/alpha/SKILL.md:6: banned term "control-ui"',
'skills/alpha/SKILL.md:6: banned term "control-cli"',
]);
});

test("the em dash character is a banned term", () => {
const root = fixture({ "skills/alpha/SKILL.md": skill("alpha", "Fast \u2014 and wrong.\n") });
assert.deepEqual(check(root), ['skills/alpha/SKILL.md:6: banned term "\u2014"']);
});
10 changes: 5 additions & 5 deletions skills/create-verification-skill/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: create-verification-skill
description: "Generate a project-local verification skill that drives your app the way a user does — any language, framework, or platform. Use for /create-verification-skill, \"make a control skill for this repo\", or when a project has no scripted way to prove UI/CLI/service behavior."
description: "Generate a project-local verification skill that drives your app the way a user does, for any language, framework, or platform. Use for /create-verification-skill, \"make a control skill for this repo\", or when a project has no scripted way to prove UI/CLI/service behavior."
disable-model-invocation: true
---

Expand All @@ -14,18 +14,18 @@ Answer these from the codebase and only ask the user what you cannot observe:

- **Surface:** what does a user actually touch? A web UI, a CLI/TUI, a desktop app, an API, a mobile app, a library? A repo can have several; pick the primary one and note the rest.
- **Run:** how does the app start locally? Prefer the repo's own documented dev command (package scripts, Makefile, README quickstart). Note ports, env vars, seed data, auth.
- **Drive:** how can an agent interact with it programmatically? Existing harnesses first — Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port. Only then pick a generic recipe: browser/CDP for web and Electron, a tmux/PTY harness for CLI/TUI, plain HTTP for services.
- **Drive:** how can an agent interact with it programmatically? Existing harnesses first: Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port. Only then pick a generic recipe: browser/CDP for web and Electron, a tmux/PTY harness for CLI/TUI, plain HTTP for services.
- **Observe:** what evidence can be captured? Screenshots, terminal transcripts, response bodies, logs, exit codes, DB state.
- **Isolate:** can two instances run side by side (ports, data dirs, profiles)? If not, say so in the generated skill: refusing to double-drive a shared instance beats corrupting the user's session.

If the checkout doesn't build or start as-is, fix that first (or report it precisely) before generating; a skill written against a broken base teaches wrong steps. When an irrelevant missing asset blocks startup (a static dir the API never serves, a sample config), the generated skill may create it, clearly marked as verification scaffolding, and remove it in cleanup.

## 2. Generate the skill

Write `.cursor/skills/verify-<app>/SKILL.md` with YAML frontmatter (`name: verify-<app>` and a `description` that names the app, the surface, and when to reach for it — without frontmatter the skill never registers) and these sections, each grounded in what the interview actually found (no placeholders left):
Write `.cursor/skills/verify-<app>/SKILL.md` with YAML frontmatter (`name: verify-<app>` and a `description` that names the app, the surface, and when to reach for it. Without frontmatter the skill never registers.) and these sections, each grounded in what the interview actually found (no placeholders left):

- **Launch:** the exact command that starts the app for verification, and how to tell it's ready (a log line, a port answering, a prompt). Include teardown. For a short-lived CLI or TUI there is no server to keep alive: launch means build the binary (or install deps) once, then start each drive in its own isolated PTY or tmux session.
- **Doctor:** one read-only check that answers "is this instance worth driving?" — process up, right version/build, port owned by us, auth valid. An agent runs this first whenever anything looks off.
- **Doctor:** one read-only check that answers "is this instance worth driving?": process up, right version/build, port owned by us, auth valid. An agent runs this first whenever anything looks off.
- **Drive:** the harness recipe with real selectors/commands from this repo, not examples. Prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order.
- **Evidence:** what to capture for a proof and where it goes. State the proof standards: exercise the real user path, not internal setters or test-only endpoints; capture the action and the resulting state, not just the final screen; verify side effects (files written, rows inserted, messages sent) alongside what's visible; mocks only where a production boundary already isolates the external system. When the safe path is a dry-run or test mode, verify what it actually skips by observing (files, network, git refs) rather than trusting its name: some dry-runs still touch the network or open a browser.
- **Cleanup:** how to tear down instances the run created. Never kill by process name; kill what you started. Cleanup removes instances and scratch state, never the evidence: proof artifacts survive the teardown, in a location the skill names.
Expand All @@ -37,7 +37,7 @@ Create `.cursor/skills/verify-<app>/features/README.md` plus one file per user-f

## 4. Prove the generated skill before handing it over

Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough; the map exists so later runs can cover the rest), capture evidence, clean up. After cleanup, confirm the evidence still exists at the named location — a cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable.
Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough; the map exists so later runs can cover the rest), capture evidence, clean up. After cleanup, confirm the evidence still exists at the named location. A cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable.

## 5. Offer the maintenance loop

Expand Down
10 changes: 5 additions & 5 deletions skills/maintain-verification-skill/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ A feature map rots the moment the app changes. This skill is the upkeep loop for

Pick one, and say which:

- **clean** — every feature got source and live coverage; nothing worth shipping. No branch, no PR.
- **changed** — one PR ships proven doc, harness, or map corrections.
- **blocked** — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.
- **clean**: every feature got source and live coverage; nothing worth shipping. No branch, no PR.
- **changed**: one PR ships proven doc, harness, or map corrections.
- **blocked**: coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.

## Edit scope

Expand All @@ -28,9 +28,9 @@ Only edit the verification skill's own directory (its SKILL.md, features/, and a

2. **Source wave.** One read-only subagent per feature file, launched concurrently. Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.

3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.
3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map. Require a concrete source path before calling one missing.

4. **Live pass.** Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model — one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising — doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness — failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once — restart whatever the fix invalidated, nothing more — before calling the pass `blocked`. A feature that can't be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run — including those re-proofs — so nothing outlives the run (evidence stays, per the skill).
4. **Live pass.** Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model: one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising. Doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness, so failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once (restart whatever the fix invalidated, nothing more) before calling the pass `blocked`. A feature that can't be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run, including those re-proofs, so nothing outlives the run (evidence stays, per the skill).

5. **Triage.** Wrong or missing user-POV description → doc drift, fix it. Working behavior the harness can't drive → harness gap, fix it; a harness fix follows the same helpers rule as generation (scripts executable, invocation documented in the skill body). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR.

Expand Down
Loading
Loading