From 88106309f40613e14deb6352370ca0e5ac37e190 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Sat, 13 Jun 2026 20:52:34 -0400 Subject: [PATCH] feat(plugin): add 4 Scribe-native process-skills (restore superpowers gap) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Superpowers was uninstalled but its replacements were never built (only using-scribe shipped) — a live functional hole. Author the 4 the operator wants back, each integrated with Scribe's toolset rather than generic copies: - writing-plans -> start_planning / kind=plan task, not local .md - systematic-debugging -> capture issue (symptom->cause->fix, tag issue) on resolve - verification -> log results to the task work-log; honest done - brainstorming -> recall prior thinking first; capture the decision note Skipped TDD + receiving-code-review per operator (well-covered by Claude/them). Manifest + using-scribe list now advertise only the 4 that ship. Remove the stale docs/superpowers/*.md reference in _INSTRUCTIONS (superpowers is gone). Plugin 0.1.6 -> 0.1.7. Refs plan 821 (Phase 3 of 755). Co-Authored-By: Claude Opus 4.8 (1M context) --- plugin/.claude-plugin/plugin.json | 4 +- plugin/skills/brainstorming/SKILL.md | 34 +++++++++++++++ plugin/skills/systematic-debugging/SKILL.md | 35 ++++++++++++++++ plugin/skills/using-scribe/SKILL.md | 7 ++-- plugin/skills/verification/SKILL.md | 32 ++++++++++++++ plugin/skills/writing-plans/SKILL.md | 46 +++++++++++++++++++++ src/scribe/mcp/server.py | 9 ++-- 7 files changed, 156 insertions(+), 11 deletions(-) create mode 100644 plugin/skills/brainstorming/SKILL.md create mode 100644 plugin/skills/systematic-debugging/SKILL.md create mode 100644 plugin/skills/verification/SKILL.md create mode 100644 plugin/skills/writing-plans/SKILL.md diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index 56f4e7b..63bc343 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "scribe", - "description": "Scribe second brain for Claude Code: MCP tools over your notes/tasks/projects/rules, a session-start push channel that surfaces your always-on rules + active-project context, and a set of universal process-skills (brainstorm, debug, TDD, plan, verify). Replaces superpowers + file-memory with one app-backed plugin.", - "version": "0.1.6", + "description": "Scribe second brain for Claude Code: MCP tools over your notes/tasks/projects/rules, a session-start push channel that surfaces your always-on rules + active-project context, and a set of process-skills (writing-plans, systematic-debugging, verification, brainstorming). Replaces superpowers + file-memory with one app-backed plugin.", + "version": "0.1.7", "author": { "name": "Bryan Van Deusen" }, "mcpServers": { "scribe": { diff --git a/plugin/skills/brainstorming/SKILL.md b/plugin/skills/brainstorming/SKILL.md new file mode 100644 index 0000000..f803082 --- /dev/null +++ b/plugin/skills/brainstorming/SKILL.md @@ -0,0 +1,34 @@ +--- +name: brainstorming +description: Use when exploring options or shaping a direction before committing — open up the solution space instead of jumping to the first idea. Triggers on "how should we approach X", "what are the options", weighing trade-offs, or any open-ended design question. Recall prior thinking first; capture the decision after. +--- + +# Brainstorming + +Widen before you narrow. The first idea is rarely the best; the goal is a few +real options and a reasoned choice — not a single path defended after the fact. + +## Recall first + +`search` Scribe before generating from scratch — a prior decision, note, or +brainstorm on this often already exists. Build on it instead of repeating it. + +## Open up + +- Generate a few genuinely *different* options, not variations of one. Include at + least one you don't initially favor. +- For each: the core idea, what it's good at, and its main cost or risk — briefly. +- Resist converging until the space is actually explored. + +## Then choose + +- Recommend one, and say *why* — the trade-off that decided it, not just the pick. +- Surface the 1–2 places you made an interpretive call, so the operator can + redirect before it's baked in. + +## Capture the decision + +When a direction is chosen, record it in Scribe (`create_note`, e.g. tag +`decision`): the choice, the alternatives weighed, and the reason. That's what +keeps the same question from being re-litigated later — and what a future +session reads to understand *why*, not just *what*. diff --git a/plugin/skills/systematic-debugging/SKILL.md b/plugin/skills/systematic-debugging/SKILL.md new file mode 100644 index 0000000..c29c853 --- /dev/null +++ b/plugin/skills/systematic-debugging/SKILL.md @@ -0,0 +1,35 @@ +--- +name: systematic-debugging +description: Use when diagnosing a bug, failure, or unexpected behavior — investigate methodically instead of guessing. Triggers on "why is this failing/breaking", a stack trace, a flaky test, or any "it should work but doesn't". On resolution, capture the issue in Scribe so it isn't re-debugged from scratch. +--- + +# Systematic debugging + +Find the *root cause*, don't patch the symptom. Move one step at a time — a +guessed fix that "seems to work" often just moves the bug somewhere else. + +## Recall first + +Before digging in, `search` Scribe for the symptom — a prior `issue` note may +already hold the cause and the fix. Don't re-debug what's already solved. + +## The loop + +1. **Reproduce** — get a reliable, minimal repro. If you can't reproduce it, you + can't confirm you fixed it. +2. **Observe** — read the actual error / log / state. Don't theorize past the + data you have. +3. **Isolate** — narrow to the smallest failing case; change one variable at a + time so each result actually means something. +4. **Hypothesize → test** — state the single most likely cause, then test *that + one thing*. Confirm or rule it out before moving on; don't stack guesses. +5. **Root cause** — keep going until you can explain *why* it failed, not just + what made it stop. "It works now" without "because X" is unfinished. +6. **Fix + verify** — fix the cause, then re-run the repro to confirm it's gone. + +## Capture the issue (so it's findable) + +When resolved, record it in Scribe (`create_note`, tag `issue`): **symptom → +root cause → fix → how it was verified**. Even a problem fixed in passing is +worth two lines — that's how the next person (or you) avoids re-deriving it. If +the fix was tracked as a task, log the resolution there and set it `done`. diff --git a/plugin/skills/using-scribe/SKILL.md b/plugin/skills/using-scribe/SKILL.md index fccccfb..2b9b599 100644 --- a/plugin/skills/using-scribe/SKILL.md +++ b/plugin/skills/using-scribe/SKILL.md @@ -106,7 +106,6 @@ rulebook — it leaks to every other project that gets it. ## Other Scribe process-skills -This plugin also ships focused process-skills — brainstorming, systematic -debugging, test-driven development, writing-plans, verification, receiving code -review. Reach for the matching one when its situation arises, the same way you -reach for this skill. +This plugin also ships focused process-skills — writing-plans, systematic +debugging, verification, and brainstorming. Reach for the matching one when its +situation arises, the same way you reach for this skill. diff --git a/plugin/skills/verification/SKILL.md b/plugin/skills/verification/SKILL.md new file mode 100644 index 0000000..486fe17 --- /dev/null +++ b/plugin/skills/verification/SKILL.md @@ -0,0 +1,32 @@ +--- +name: verification +description: Use before claiming a task is done or a change works — confirm it actually does, then record that you did. Triggers when you're about to report completion, mark a task done, or say "it works" / "fixed". Guards against declaring success on unverified work. +--- + +# Verification before completion + +"Done" means verified, not "written." Before you claim a change works or set a +task `done`, confirm it against reality and record what you checked. + +## Verify against reality + +- Exercise the actual behavior — run it, test it, observe the output. Prefer the + real path over "it should work by inspection." +- Check the thing the user actually asked for, not a proxy for it. +- If you *can't* verify something (no environment, needs hardware, needs the + operator), say so explicitly — name what's unverified rather than letting it + read as passed. + +## Record the result, then close + +- Log what you verified, and how, to the task with `add_task_log` — the check is + part of the record, not a private step. +- Only then set the task `done`. Never mark finished work you haven't confirmed, + and never leave confirmed work sitting at `in_progress`. +- If verification surfaced a problem, capture it (tag `issue`) and keep the task + open — a found problem is a pivot to record, not something to quietly skip. + +## Honesty over optimism + +A truthful "verified X; could not verify Y" is worth more than a confident +"done." The record is only useful if `done` reliably means done. diff --git a/plugin/skills/writing-plans/SKILL.md b/plugin/skills/writing-plans/SKILL.md new file mode 100644 index 0000000..36e37e6 --- /dev/null +++ b/plugin/skills/writing-plans/SKILL.md @@ -0,0 +1,46 @@ +--- +name: writing-plans +description: Use before starting any non-trivial or multi-step piece of work — produce a clear plan BEFORE diving in. Triggers when the user asks you to plan, design an approach, scope an effort, or tackle work big enough to need ordered steps. The plan lives in a Scribe kind=plan task (via start_planning), not a local file. +--- + +# Writing plans + +A plan is **how** you'll execute a chunk of work — the design plus an ordered, +checkable list of steps — written *before* you start, so the approach is +reviewable and the work stays trackable. + +## Start the plan in Scribe, not a file + +For non-trivial work, call **`start_planning(project_id, title)` FIRST** — +before any design or implementation. It creates a `kind=plan` task seeded with a +template and returns the task id plus the project's applicable rules. The plan +lives in that task: edit the body with `update_task`, record progress with +`add_task_log`. **Do not** write plans or specs to local `.md` files — the task +is the record, not a file on disk. + +Before designing from scratch, **recall**: `search` Scribe for a related prior +plan or decision. Often the thinking (or half of it) already exists. + +## What a good plan contains + +- **Goal** — what "done" looks like, and why, in a sentence or two. +- **Approach** — the key design decisions and the trade-offs you chose, briefly. +- **Steps** — an ordered checklist, each step small enough to verify on its own; + note which files/areas each touches. +- **Verification** — how you'll know it actually works (a test, CI, an + observable behavior), not just "it's written." + +## While executing + +- Keep the plan **honest**: tick steps as they land; record decisions, findings, + and pivots with `add_task_log` rather than silently rewriting the body. +- If reality diverges from the plan, **update the plan** — one that no longer + matches what you're doing is worse than none. +- Set the plan task `in_progress` when you start and `done` when it's complete. + +## Match depth to the work + +A two-step change deserves a two-line plan; a multi-day effort deserves +milestones and sub-tasks. Don't over-plan the trivial, and don't under-plan +something that will sprawl. The point is a shared, reviewable intent — not +ceremony. diff --git a/src/scribe/mcp/server.py b/src/scribe/mcp/server.py index 0cebf68..519192b 100644 --- a/src/scribe/mcp/server.py +++ b/src/scribe/mcp/server.py @@ -151,11 +151,10 @@ Plans are tasks with kind=plan, and Scribe is the canonical home for them. When you begin non-trivial work, call start_planning(project_id, title) FIRST — before any brainstorming, design, or plan-writing skill runs. start_planning seeds the plan body, returns the project's applicable_rules, and gives you the -task id you'll write into. If a skill or habit tells you to save a plan or spec -to `docs/superpowers/plans/*.md` or `docs/superpowers/specs/*.md`, that path is -superseded here: put the spec/plan content in the kind=plan task's body via -update_task, and record progress with add_task_log. Local .md files are not -the record — the task is. +task id you'll write into. If a habit tells you to save a plan or spec to a local +`.md` file, that's superseded here: put the spec/plan content in the kind=plan +task's body via update_task, and record progress with add_task_log. Local .md +files are not the record — the task is. Deletes are recoverable: every delete_* tool moves the entity (and its descendants) to the trash and returns a deleted_batch_id. Use list_trash() to