superpowers-mcp 6.3.1 → 6.3.3

package/package.json

@@ -2,7 +2,7 @@
   "name": "superpowers-mcp",
   "displayName": "Superpowers MCP",
   "description": "Superpowers skills library (TDD, debugging, collaboration workflows) as an MCP server for VSCode and Antigravity",
-  "version": "6.3.1",
+  "version": "6.3.3",
   "publisher": "superpowers",
   "license": "MIT",
   "repository": {

package/skills/subagent-driven-development/SKILL.md

@@ -173,6 +173,14 @@ its own text agrees with itself — the tests it specifies against the code it
 specifies, the files it creates against the files it later touches. "The scan
 is clean" without those rows is not a scan you ran.
 
+**When the plan's header declares `Plan shape: skeleton-first`,** the
+table gets a final section: the DISPATCH PLAN — group the pending tasks
+into waves. Tasks in the same wave are mutually file-disjoint and consume
+no interface still under construction — dispatch each wave's implementers
+concurrently, one worktree per task, and integrate before the next wave;
+tasks that fail those conditions serialize. On a skeleton-first plan, a
+scan without a dispatch plan is not a scan you ran.
+
 Write the table to the ledger. Rule on everything you find before execution
 begins — each finding against the plan text that mandates it — and record
 each ruling in the ledger. If the scan is clean, proceed without comment.
@@ -187,6 +195,10 @@ Use the least powerful model that can handle each role to conserve cost and incr
 
 **Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
 
+When a task carries a **Tier:** field, follow it — the planner already
+ruled: mechanical → the cheapest available model; judgment → a standard
+model. Do not re-litigate the tier at dispatch.
+
 **Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
 
 **Architecture and design tasks**: use the most capable available model.
@@ -208,7 +220,10 @@ most expensive — which silently defeats this section.
 **Turn count beats token price.** Wall-clock and context cost scale with how
 many turns a subagent takes, and the cheapest models routinely take 2-3× the
 turns on multi-step work — costing more overall. Use a mid-tier model as the
-floor for reviewers and for implementers working from prose descriptions.
+floor for reviewers and for implementers working from task contracts or
+prose descriptions — unless the task's Tier line says mechanical: the
+planner has already ruled the deliverable fully specified, so treat a
+mechanical-tier contract like spelled-out content.
 When the task's plan text contains the complete code to write, the
 implementation is transcription plus testing: use the cheapest tier for
 that implementer. Single-file mechanical fixes also take the cheapest tier.
@@ -260,7 +275,13 @@ and fix-round diffs need it.
   know; (4) your resolution of any ambiguity you noticed in the brief;
   (5) the report-file path and report contract. Exact values (numbers,
   magic strings, signatures, test cases) appear only in the brief. Never
-  make a subagent read the whole plan file.
+  make a subagent read the whole plan file. When the brief is a contract
+  (goal, success criteria, interfaces) rather than written-out code, item
+  (3) also carries the elaboration the contract leaves to dispatch time:
+  the interfaces as actually built by completed tasks, environment facts
+  and discoveries from earlier reports, and any amendment rulings. There
+  the success criteria name the cases the tests must cover, and the
+  implementer designs its own code and tests within the contract.
 - **Report file:** name the implementer's report file after the brief
   (brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
   the dispatch prompt. The implementer writes the full report there and
@@ -281,6 +302,26 @@ and fix-round diffs need it.
 - Record the implementer's agent identity from the dispatch result —
   fix-loop rounds 1-3 resume this agent.
 - Never dispatch multiple implementation subagents in parallel (conflicts).
+  The one exception is a skeleton-first plan whose dispatch plan shows two
+  or more pending tasks mutually file-disjoint with none consuming an
+  interface still under construction. Dispatch those implementers
+  concurrently, each in its own worktree:
+  - Record the integration base commit in the ledger before the first
+    concurrent dispatch.
+  - Create one worktree per concurrent task off that base
+    (`git worktree add <repo-root>/.worktrees/task-<N> -b task-<N>
+    <base>`); each dispatch's `Work from:` is its own worktree, and its
+    BASE is that worktree's HEAD.
+  - Review each task's diff as usual when it reports. Integrate reviewed
+    branches in plan order: merge each into the integration branch
+    (`git merge --no-ff task-<N>`), and run that task's verification
+    commands after each merge.
+  - A merge conflict or post-merge verification failure is that task's
+    fix-loop round 1: rebase the task branch onto the current
+    integration head in its worktree, then resume its implementer
+    there. Never resolve conflicts yourself.
+  - Remove each worktree (`git worktree remove`) once its branch is
+    integrated, and record the integrated range in the ledger as usual.
 
 Template: [implementer-prompt.md](implementer-prompt.md)
 
@@ -442,6 +483,19 @@ message as your other bookkeeping:
 - `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
   tripped breaker
 
+**On a skeleton-first plan,** write one plan-check line with the
+completion line. Re-read the remaining tasks against what this task
+actually established — interfaces as built, environment facts,
+discoveries in the report — and append either `Plan holds` or
+`Amendment: Task <M>: <what changes and why>` to the ledger. An
+amendment is plan authority applied at the plan layer: from then on the
+amended text IS the plan's text, and it rides into every affected task's
+dispatch under item (3). In-flight tasks in the same concurrent wave are
+not aborted mid-flight; any interface divergences are surfaced and
+resolved through the standard integration merge, rebase, and fix-loop
+protocol. Never dispatch a task whose brief a completed task's report has
+already invalidated.
+
 Then mark the todo complete and move on. Never move to the next task while
 the review has open Critical/Important issues that are neither fixed nor
 parked-with-ruling at the cap.

package/skills/subagent-driven-development/implementer-prompt.md

@@ -5,8 +5,11 @@ Use this template when dispatching an implementer subagent.
 ```
 Subagent (general-purpose):
   description: "Implement Task N: [task name]"
-  model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
-         model silently inherits the session's most expensive one]
+  model: [MODEL — REQUIRED: when the brief carries a Tier line, set from it:
+         mechanical → the cheapest model the subagent tool offers; judgment →
+         a standard mid-tier model. Otherwise choose per SKILL.md Model
+         Selection. An omitted model silently inherits the session's most
+         expensive one]
   prompt: |
     You are implementing Task N: [task name]
 

package/skills/using-superpowers/SKILL.md

@@ -57,6 +57,8 @@ If your harness appears here, read its reference file for special instructions:
 - Pi: `references/pi-tools.md`
 - Antigravity: `references/antigravity-tools.md`
 - Hermes Agent: `references/hermes-tools.md`
+- Devin CLI: `references/devin-tools.md`
+- OpenCode: `references/opencode-tools.md`
 
 ## User Instructions
 

package/skills/using-superpowers/references/devin-tools.md

@@ -0,0 +1,41 @@
+# Devin CLI Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Devin CLI these resolve to the tools below.
+
+## Tools
+
+| Action skills request | Devin CLI tool |
+|---|---|
+| Read a file | `read_file` / `view_file` |
+| Create a new file | `write_to_file` |
+| Edit a file (targeted patch) | `replace_file_content` / `edit_file` |
+| Run a shell command | `run_command` |
+| Search file contents | `grep_search` |
+| Find files by name | `find_by_name` / `list_dir` |
+| Fetch a URL / read a webpage | `read_url_content` / `browser` |
+| Search the web | `search_web` |
+| Dispatch a subagent | `invoke_subagent` / `spawn_agent` |
+| Task tracking | `task_list` / session todo list |
+| Ask user question | `ask_question` |
+| Invoke a skill | Native `skill` tool or `read_skill` via MCP |
+
+## Instructions file
+
+When a skill mentions "your instructions file," on Devin CLI this is **`DEVIN.md`** or **`AGENTS.md`** in the project root directory.
+
+## Invoking a skill
+
+Devin CLI auto-discovers skills from installed plugins. To invoke a superpowers skill, invoke the native skill runner or call the MCP tool:
+
+```
+skill(name="brainstorming")
+```
+
+If native skill resolution is unavailable, fall back to reading the skill file directly or via the MCP server's `read_skill` tool.
+
+## Subagent dispatch
+
+When executing Subagent-Driven Development (SDD) or parallel dispatch, use Devin's subagent capability (`invoke_subagent`):
+
+- **Implementers**: Dispatch focused implementer subagents for single task isolation.
+- **Reviewers**: Dispatch fresh, independent reviewer subagents to review against specifications.

package/skills/using-superpowers/references/opencode-tools.md

@@ -0,0 +1,32 @@
+# OpenCode Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On OpenCode these resolve to the tools below.
+
+## Tools
+
+| Action skills request | OpenCode tool |
+|---|---|
+| Read a file | `read_file` |
+| Create a new file | `write_file` |
+| Edit a file (targeted patch) | `edit_file` |
+| Run a shell command | `bash` / `terminal` |
+| Search file contents | `grep` / `search_files` |
+| Find files by name | `find_files` |
+| Fetch a URL / read a webpage | `fetch_url` |
+| Search the web | `web_search` |
+| Invoke a skill | `use_skill(name="...")` or MCP `read_skill` |
+| List available skills | `find_skills` or MCP `list_skills` |
+
+## Instructions file
+
+When a skill mentions "your instructions file," on OpenCode this is **`AGENTS.md`** or **`OPENCODE.md`** in the project root directory.
+
+## Invoking a skill
+
+OpenCode discovers registered skills via its plugin ecosystem or MCP server. To invoke a skill:
+
+```
+use_skill(name="brainstorming")
+```
+
+Or when running through the Superpowers MCP Server, use `read_skill(skill_name="brainstorming")`.

package/skills/writing-plans/SKILL.md

@@ -22,6 +22,30 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 
 If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
 
+## Two Plan Shapes
+
+Before mapping files, classify the plan's shape and say the
+classification out loud — "this composes three subsystems, so I'll plan
+it skeleton-first" — so your human partner can override it:
+
+- **Task-by-task (default)** — tasks build the feature a component at a
+  time, each step carrying the actual content the engineer needs. Use it
+  for changes to code that already exists, for a spec that touches one
+  subsystem, and whenever the alternative's conditions do not clearly
+  hold. The rest of this skill describes this shape.
+- **Skeleton-first (alternative)** — Task 1 is the thinnest end-to-end
+  slice through every subsystem the spec composes; later tasks widen it
+  one component at a time, each from a contract rather than written-out
+  code. Use it when the spec composes more than one subsystem AND a
+  running end-to-end slice early is worth a longer total build. Read
+  [skeleton-first-plans.md](skeleton-first-plans.md) before writing one
+  — it adds one line to the plan header and replaces this skill's task
+  granularity, task template, and plan-failure list.
+
+When in doubt, plan task-by-task. Skeleton-first buys an earlier running
+system and pays for it in total wall clock; it is a trade, not an
+upgrade.
+
 ## File Structure
 
 Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

package/skills/writing-plans/skeleton-first-plans.md

@@ -0,0 +1,131 @@
+# Skeleton-First Plans
+
+The alternative plan shape from writing-plans' Two Plan Shapes router.
+Each section below replaces the same-named section of
+[SKILL.md](SKILL.md); everything SKILL.md says that is not named here
+still binds — Scope Check, File Structure, Task Right-Sizing, the plan
+header, Self-Review, and the Execution Handoff.
+
+## Overview
+
+Write a plan that carries the decisions, not the keystrokes:
+decomposition, file structure, interfaces, constraints, and a precise
+contract per task. Assume the engineer is skilled and designs their own
+code and tests from a precise contract, but knows nothing about our
+codebase, toolset, or problem domain — every name, path, constraint, and
+behavior they must match is stated explicitly. DRY. YAGNI. TDD.
+Frequent commits.
+
+## When This Shape Fits
+
+Use it when the spec composes more than one subsystem and a running
+end-to-end slice early is worth a longer total build: the value arrives
+as soon as real input reaches real output, and every later task widens
+something that already runs.
+
+Do not use it for a change to one subsystem, or when the whole point is
+to land the finished thing as fast as possible. This shape spends its
+first task on a slice that does almost nothing, and it spends planning
+effort on contracts and interfaces the task-by-task shape gets for free
+by writing the code out.
+
+## Plan Document Header
+
+The header is SKILL.md's, plus one line directly under the **Goal:**
+line, which is how executors know which shape they are running:
+
+```markdown
+**Plan shape:** skeleton-first
+```
+
+## Walking Skeleton First
+
+Task 1 builds the thinnest end-to-end slice through every subsystem the
+spec composes — real input to real output — before any task deepens a
+single layer; later tasks widen the skeleton.
+
+The test of a skeleton is that it runs. A first task that builds the
+data loader, the schema, or the config layer is a foundation, not a
+skeleton: nothing runs until something above it exists. A skeleton
+reaches the output — thinly, with one real case — through every
+subsystem the spec names.
+
+## Task Contracts, Not Task Scripts
+
+A task states WHAT must exist when it is done, precisely enough that a
+skilled engineer can build it without asking you anything, without
+prescribing HOW:
+
+- **Goal:** one short paragraph naming the deliverable and its role in
+  the feature.
+- **Success criteria:** concrete, checkable behaviors — exact commands
+  to run and what they must show, the cases tests must cover (including
+  failure cases), constraints that bind the implementation.
+- **Notes:** what the engineer needs and cannot discover alone — spec
+  sections to read, files worth reading first, known pitfalls.
+
+The Interfaces block carries the exact names, signatures, and types;
+the success criteria carry the behaviors; the engineer supplies the
+code and the test design. TDD and frequent commits remain required.
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Interfaces:**
+- Consumes: [what this task uses from earlier tasks — exact signatures]
+- Produces: [what later tasks rely on — exact function names, parameter
+  and return types. A task's implementer sees only their own task; this
+  block is how they learn the names and types neighboring tasks use.]
+
+**Goal:** [one paragraph — the deliverable and its role in the feature]
+
+**Success criteria:**
+- Run: `pytest tests/exact/path/to/test.py -v` — all tests pass; tests
+  cover [the specific behaviors and failure cases, named concretely]
+- [observable behavior the deliverable must exhibit, with the exact
+  command or input/output that demonstrates it]
+- [constraint that binds the implementation, copied from the spec]
+
+**Notes:** [spec sections to read; files to read first; known pitfalls]
+
+**Tier:** mechanical | judgment. Mechanical = the deliverable is fully
+specified by Files + Interfaces + success criteria above (most tasks in
+a well-specified plan are mechanical); judgment = multi-file
+coordination, debugging, or real design latitude remains. The
+implementer's model follows this field — mark it deliberately.
+
+**Commit:** one commit ending the task; message named here.
+````
+
+## No Vague Contracts
+
+Every contract must be checkable by someone who did not write it. These
+are **plan failures** — never write them:
+- "TBD", "TODO", "implement later", "fill in details"
+- Goals naming activity instead of a deliverable ("improve error handling")
+- Success criteria with no observable check ("works correctly", "handles edge cases")
+- Interfaces blocks omitting a name, signature, or type another task consumes
+- "Similar to Task N" (state this task's own contract in full — the engineer may be reading tasks out of order)
+- References to types, functions, or methods not defined in any task's Interfaces block
+
+## Self-Review
+
+Run SKILL.md's Self-Review checklist, reading step 2 against "No Vague
+Contracts" above rather than "No Placeholders".
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "Task 1 is the data loader — that's the foundation" | A foundation is a layer. The skeleton runs real input to real output through every subsystem the spec names, thinly. |
+| "The skeleton can return a hardcoded value for now" | It may be thin, but the path must be real: real input, real wiring, real output. A hardcoded response tests nothing end to end. |
+| "A contract without the code is vague" | Vague is an uncheckable success criterion. Exact names, exact commands, exact expected output — no code. |
+| "I'll write the test code into the task to be safe" | The success criteria name the cases; the implementer designs the tests. Written-out tests are the task-by-task shape. |
+| "Skeleton-first is the better shape, so I'll use it here" | It costs total wall clock. Without more than one subsystem and a reason to want an early running slice, plan task-by-task. |

package/skills/writing-skills/render-graphs.js

@@ -15,11 +15,11 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 
 function extractDotBlocks(markdown) {
   const blocks = [];
-  const regex = /```dot\n([\s\S]*?)```/g;
+  const regex = /```dot\r?\n([\s\S]*?)```/g;
   let match;
 
   while ((match = regex.exec(markdown)) !== null) {
@@ -69,7 +69,7 @@ ${bodies.join('\n\n')}
 
 function renderToSvg(dotContent) {
   try {
-    return execSync('dot -Tsvg', {
+    return execFileSync('dot', ['-Tsvg'], {
       input: dotContent,
       encoding: 'utf-8',
       maxBuffer: 10 * 1024 * 1024
@@ -110,11 +110,12 @@ function main() {
   // Check if dot is available. Run the binary directly rather than probing
   // with `which`, which is not a command on Windows.
   try {
-    execSync('dot -V', { stdio: 'ignore', encoding: 'utf-8' });
+    execFileSync('dot', ['-V'], { stdio: 'ignore' });
   } catch {
     console.error('Error: graphviz (dot) not found. Install with:');
-    console.error('  brew install graphviz    # macOS');
-    console.error('  apt install graphviz     # Linux');
+    console.error('  brew install graphviz         # macOS');
+    console.error('  apt install graphviz          # Linux');
+    console.error('  winget install Graphviz.Graphviz # Windows');
     process.exit(1);
   }