superpowers-mcp 6.3.6 → 6.3.7

package/package.json

@@ -2,12 +2,15 @@
   "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.6",
+  "version": "6.3.7",
+  "engines": {
+    "node": ">=18"
+  },
   "publisher": "superpowers",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Poseidoncode/superpowers-mcp"
+    "url": "git+https://github.com/Poseidoncode/superpowers-mcp.git"
   },
   "homepage": "https://github.com/Poseidoncode/superpowers-mcp",
   "keywords": [
@@ -23,8 +26,8 @@
     "agent"
   ],
   "bin": {
-    "superpowers-mcp": "./out/server.js",
-    "superpowers-setup": "./out/setup.js"
+    "superpowers-mcp": "out/server.js",
+    "superpowers-setup": "out/setup.js"
   },
   "files": [
     "out/server.js",
@@ -43,7 +46,9 @@
     "build": "node esbuild.js --production",
     "watch": "node esbuild.js --watch",
     "pretest": "npm run build",
-    "test": "node tests/edge_cases_test.js && node tests/run_test.js && node tests/brainstorm_server_test.js && node tests/prompts_compositions_test.js && node tests/setup_test.js",
+    "test": "node tests/edge_cases_test.js && node tests/run_test.js && node tests/brainstorm_server_test.js && node tests/prompts_compositions_test.js && node tests/upstream_sync_test.js && node tests/mcp_coverage_test.js && node tests/drift_test.js && node tests/setup_test.js",
+    "drift": "node scripts/upstream-drift.js --fetch",
+    "drift:record": "node scripts/upstream-drift.js --record",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {

package/scripts/upstream-drift.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+/**
+ * Upstream drift report for the skills this fork ships.
+ *
+ * The fork imports upstream superpowers content in reviewed batches. Between
+ * batches nothing records which upstream files moved, so every sync starts with
+ * a manual hunt. This tool stores the upstream blob SHAs captured at the last
+ * sync (tests/upstream-sync-baseline.json) and reports:
+ *
+ *   - adopted skill files that changed, appeared or disappeared upstream
+ *   - tracked files that are missing from this fork
+ *   - upstream skills this fork deliberately does not adopt
+ *   - files this fork adds on top of upstream
+ *
+ * Usage:
+ *   node scripts/upstream-drift.js              # offline: baseline integrity + coverage
+ *   node scripts/upstream-drift.js --fetch      # compare the baseline against upstream
+ *   node scripts/upstream-drift.js --record     # refresh the baseline from upstream
+ *
+ * Options:
+ *   --ref <ref>          upstream ref to read (default: the baseline ref, else "dev")
+ *   --repo <owner/name>  upstream repository (default: obra/superpowers)
+ *   --ignore <skill>     record an upstream skill as deliberately not adopted
+ *                        (repeatable; --record only)
+ *   --json               machine-readable report
+ *   --fail-on-drift      exit 1 when an adopted file drifted (skipped on a
+ *                        truncated upstream listing)
+ *
+ * `--record` refuses truncated upstream listings so an incomplete API response
+ * can never replace the last complete baseline.
+ *
+ * The upstream git tree is read through `gh api` when the GitHub CLI is
+ * available and falls back to the public GitHub API (Node 18+). Zero
+ * dependencies. Only --record writes, and it writes the baseline file only.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const REPO_ROOT = path.join(__dirname, "..");
+const SKILLS_DIR = path.join(REPO_ROOT, "skills");
+const BASELINE_PATH = path.join(REPO_ROOT, "tests", "upstream-sync-baseline.json");
+const DEFAULT_REPO = "obra/superpowers";
+const DEFAULT_REF = "dev";
+const MAX_LISTED = 40;
+const NETWORK_TIMEOUT_MS = 20000;
+
+function parseArgs(argv) {
+    const opts = { fetch: false, record: false, json: false, failOnDrift: false, help: false, ref: "", repo: "", ignore: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--fetch") opts.fetch = true;
+        else if (arg === "--record") opts.record = true;
+        else if (arg === "--json") opts.json = true;
+        else if (arg === "--fail-on-drift") opts.failOnDrift = true;
+        else if (arg === "--help" || arg === "-h") opts.help = true;
+        else if (arg === "--ref" || arg === "--repo" || arg === "--ignore") {
+            const value = argv[++i];
+            if (!value) throw new Error(`Missing value for ${arg}`);
+            if (arg === "--ref") opts.ref = value;
+            else if (arg === "--repo") opts.repo = value;
+            else opts.ignore.push(value);
+        } else {
+            throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    return opts;
+}
+
+function printHelp() {
+    console.log(`Upstream drift report for the skills this fork ships.
+
+  node scripts/upstream-drift.js            offline baseline integrity + local coverage
+  node scripts/upstream-drift.js --fetch    compare the baseline against upstream
+  node scripts/upstream-drift.js --record   refresh the baseline from upstream
+
+Options: --ref <ref>  --repo <owner/name>  --ignore <skill>  --json  --fail-on-drift`);
+}
+
+/** The skill directory an upstream path belongs to ("skills/<name>/..." -> "<name>"). */
+function skillNameOf(filePath) {
+    const parts = String(filePath).split("/");
+    return parts.length > 2 && parts[0] === "skills" ? parts[1] : "";
+}
+
+function readBaseline(baselinePath = BASELINE_PATH) {
+    const parsed = JSON.parse(fs.readFileSync(baselinePath, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || typeof parsed.files !== "object" || parsed.files === null) {
+        throw new Error(`${path.relative(REPO_ROOT, baselinePath)} is missing its "files" map`);
+    }
+    return parsed;
+}
+
+/** Walk the fork's skills tree and return the upstream-style paths it covers. */
+function localSkillPaths(skillsDir = SKILLS_DIR) {
+    const found = new Set();
+    const walk = (dir, relative) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const nextRelative = relative ? `${relative}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                walk(path.join(dir, entry.name), nextRelative);
+            } else if (entry.isFile()) {
+                found.add(`skills/${nextRelative}`);
+            }
+        }
+    };
+    if (fs.existsSync(skillsDir)) {
+        walk(skillsDir, "");
+    }
+    return found;
+}
+
+/**
+ * Classify the current upstream tree against the recorded baseline.
+ *
+ * `added` and `changed`/`removed` cover the skills this fork adopts, so they are
+ * actionable drift. Files that belong to a skill the fork does not adopt (and
+ * has not listed in ignoredUpstreamSkills) land in `unadoptedFiles`, which is a
+ * decision to make rather than drift to review.
+ */
+function classifyDrift(baselineFiles, upstreamFiles, ignoredSkills = []) {
+    const adoptedSkills = new Set(Object.keys(baselineFiles).map(skillNameOf).filter(Boolean));
+    const ignored = new Set(ignoredSkills);
+    const changed = [];
+    const added = [];
+    const removed = [];
+    const unadoptedFiles = [];
+    for (const [filePath, sha] of Object.entries(upstreamFiles)) {
+        if (Object.prototype.hasOwnProperty.call(baselineFiles, filePath)) {
+            if (baselineFiles[filePath] !== sha) changed.push(filePath);
+            continue;
+        }
+        const skill = skillNameOf(filePath);
+        if (adoptedSkills.has(skill)) added.push(filePath);
+        else if (!ignored.has(skill)) unadoptedFiles.push(filePath);
+    }
+    for (const filePath of Object.keys(baselineFiles)) {
+        if (!Object.prototype.hasOwnProperty.call(upstreamFiles, filePath)) removed.push(filePath);
+    }
+    const byPath = (a, b) => a.localeCompare(b);
+    return {
+        changed: changed.sort(byPath),
+        added: added.sort(byPath),
+        removed: removed.sort(byPath),
+        unadoptedFiles: unadoptedFiles.sort(byPath),
+    };
+}
+
+/** Compare the recorded baseline with what the fork actually ships. */
+function classifyCoverage(baseline, localPaths) {
+    const files = baseline.files || {};
+    const ignored = new Set(Array.isArray(baseline.ignoredUpstreamSkills) ? baseline.ignoredUpstreamSkills : []);
+    const localSkillDirs = new Set([...localPaths].map(skillNameOf).filter(Boolean));
+    const upstreamSkillDirs = new Set((baseline.upstreamSkills || Object.keys(files).map(skillNameOf)).filter(Boolean));
+    const byPath = (a, b) => a.localeCompare(b);
+    return {
+        missingLocal: Object.keys(files).filter((filePath) => !localPaths.has(filePath)).sort(byPath),
+        localExtra: [...localPaths].filter((filePath) => !Object.prototype.hasOwnProperty.call(files, filePath)).sort(byPath),
+        unadoptedSkills: [...upstreamSkillDirs].filter((name) => !localSkillDirs.has(name) && !ignored.has(name)).sort(byPath),
+        forkOnlySkills: [...localSkillDirs].filter((name) => !upstreamSkillDirs.has(name)).sort(byPath),
+        ignoredSkills: [...ignored].sort(byPath),
+    };
+}
+
+const encodePath = (value) => String(value).split("/").map(encodeURIComponent).join("/");
+
+async function fetchUpstreamTree(repo, ref) {
+    const endpoint = `repos/${encodePath(repo)}/git/trees/${encodeURIComponent(ref)}?recursive=1`;
+    let raw = null;
+    let source = "gh api";
+    let ghError = "";
+    try {
+        raw = execFileSync("gh", ["api", endpoint], {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: NETWORK_TIMEOUT_MS,
+        });
+    } catch (err) {
+        raw = null;
+        ghError = err && err.stderr ? String(err.stderr).trim().split("\n")[0] : String((err && err.message) || "");
+    }
+    if (!raw) {
+        source = "api.github.com";
+        const response = await fetch(`https://api.github.com/${endpoint}`, {
+            headers: { accept: "application/vnd.github+json", "user-agent": "superpowers-mcp-drift" },
+            signal: AbortSignal.timeout(NETWORK_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            throw new Error(`Could not read ${repo}@${ref} (gh failed${ghError ? `: ${ghError}` : ""}; GitHub API HTTP ${response.status})`);
+        }
+        raw = await response.text();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (err) {
+        throw new Error(`Could not parse the upstream tree response: ${err.message}`);
+    }
+    const files = {};
+    for (const entry of parsed.tree || []) {
+        if (entry && entry.type === "blob" && typeof entry.path === "string" && entry.path.startsWith("skills/")) {
+            files[entry.path] = entry.sha;
+        }
+    }
+    return { commit: parsed.sha || "", files, source, truncated: Boolean(parsed.truncated) };
+}
+
+function list(title, entries) {
+    if (entries.length === 0) return;
+    console.log(`${title} (${entries.length}):`);
+    for (const entry of entries.slice(0, MAX_LISTED)) console.log(`  - ${entry}`);
+    if (entries.length > MAX_LISTED) console.log(`  ... and ${entries.length - MAX_LISTED} more`);
+}
+
+function reportCoverage(coverage) {
+    list("Tracked upstream files missing from the fork", coverage.missingLocal);
+    list("Upstream skills this fork does not adopt", coverage.unadoptedSkills);
+    list("Fork-only skills (not tracked upstream)", coverage.forkOnlySkills);
+    list("Fork-only files (not tracked upstream)", coverage.localExtra);
+    list("Upstream skills recorded as deliberately not adopted", coverage.ignoredSkills);
+}
+
+function reportDrift(drift) {
+    list("Adopted skill files changed upstream since the baseline", drift.changed);
+    list("New upstream files inside adopted skills", drift.added);
+    list("Adopted skill files removed upstream", drift.removed);
+    list("New upstream files in skills this fork does not adopt", drift.unadoptedFiles);
+}
+
+function requireCompleteTreeForRecord(tree) {
+    if (tree.truncated) {
+        throw new Error("Refusing to record a truncated upstream tree; the existing baseline was left unchanged");
+    }
+}
+
+async function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+        printHelp();
+        return;
+    }
+
+    let baseline = null;
+    try {
+        baseline = readBaseline();
+    } catch (err) {
+        if (!opts.record) throw err;
+        console.log(`No usable baseline yet (${err.message}); --record will create one.`);
+        baseline = { repo: DEFAULT_REPO, ref: DEFAULT_REF, commit: "", capturedAt: "", files: {}, upstreamSkills: [], ignoredUpstreamSkills: [] };
+    }
+    const localPaths = localSkillPaths();
+
+    if (opts.record) {
+        const repo = opts.repo || baseline.repo || DEFAULT_REPO;
+        const ref = opts.ref || baseline.ref || DEFAULT_REF;
+        const ignored = [...new Set([...(baseline.ignoredUpstreamSkills || []), ...opts.ignore])].sort();
+        const tree = await fetchUpstreamTree(repo, ref);
+        requireCompleteTreeForRecord(tree);
+        const previousFiles = baseline.files || {};
+        const previousDrift = classifyDrift(previousFiles, tree.files, ignored);
+
+        // Track only the upstream files this fork actually ships: the baseline
+        // states which upstream blobs were imported, so a later deletion of an
+        // adopted file shows up as a missing local path.
+        const files = {};
+        for (const filePath of Object.keys(tree.files).sort()) {
+            if (localPaths.has(filePath)) files[filePath] = tree.files[filePath];
+        }
+        const upstreamSkills = [...new Set(Object.keys(tree.files).map(skillNameOf).filter(Boolean))].sort();
+        const recorded = { repo, ref, commit: tree.commit, capturedAt: new Date().toISOString().slice(0, 10), files, upstreamSkills, ignoredUpstreamSkills: ignored };
+        fs.writeFileSync(BASELINE_PATH, JSON.stringify(recorded, null, 2) + "\n", "utf-8");
+
+        console.log(`Baseline recorded from ${tree.source}: ${repo}@${ref} ${tree.commit.slice(0, 12)} — ${Object.keys(files).length} tracked files of ${Object.keys(tree.files).length} upstream skill files`);
+        if (Object.keys(previousFiles).length > 0) {
+            const moved = previousDrift.changed.length + previousDrift.added.length + previousDrift.removed.length;
+            console.log(moved === 0
+                ? "No adopted skill file moved upstream since the previous baseline."
+                : `warning: ${moved} adopted skill file(s) moved upstream since the previous baseline — record only what you actually reviewed.`);
+        }
+        if (opts.ignore.length > 0) {
+            console.log(`Recorded as deliberately not adopted: ${opts.ignore.join(", ")}`);
+        }
+        reportCoverage(classifyCoverage(recorded, localPaths));
+        return;
+    }
+
+    const repo = opts.repo || baseline.repo || DEFAULT_REPO;
+    const ref = opts.ref || baseline.ref || DEFAULT_REF;
+    const coverage = classifyCoverage(baseline, localPaths);
+    const tracked = Object.keys(baseline.files).length;
+    const ignored = Array.isArray(baseline.ignoredUpstreamSkills) ? baseline.ignoredUpstreamSkills : [];
+
+    if (!opts.fetch) {
+        if (opts.json) {
+            console.log(JSON.stringify({ baseline: { repo, ref, commit: baseline.commit, capturedAt: baseline.capturedAt, tracked }, coverage }, null, 2));
+            return;
+        }
+        console.log(`Baseline: ${repo}@${ref} ${String(baseline.commit).slice(0, 12)} (captured ${baseline.capturedAt})`);
+        console.log(`Tracked upstream skill files: ${tracked}`);
+        reportCoverage(coverage);
+        console.log("\nRun `node scripts/upstream-drift.js --fetch` to compare the baseline against upstream.");
+        return;
+    }
+
+    const tree = await fetchUpstreamTree(repo, ref);
+    const drift = classifyDrift(baseline.files, tree.files, ignored);
+    const driftCount = drift.changed.length + drift.added.length + drift.removed.length;
+    if (opts.json) {
+        console.log(JSON.stringify({
+            baseline: { repo, ref, commit: baseline.commit, capturedAt: baseline.capturedAt, tracked },
+            upstream: { ref, commit: tree.commit, tracked: Object.keys(tree.files).length, source: tree.source, truncated: tree.truncated },
+            drift,
+            driftCount,
+            coverage,
+        }, null, 2));
+    } else {
+        console.log(`Baseline: ${repo}@${baseline.ref} ${String(baseline.commit).slice(0, 12)} (captured ${baseline.capturedAt})`);
+        console.log(`Upstream: ${repo}@${ref} ${String(tree.commit).slice(0, 12)} via ${tree.source}`);
+        reportDrift(drift);
+        reportCoverage(coverage);
+        if (driftCount === 0) {
+            console.log("\nNo drift in adopted skill files.");
+        } else {
+            console.log(`\n${driftCount} adopted skill file(s) changed upstream. Review them before the next sync.`);
+        }
+        if (drift.unadoptedFiles.length > 0) {
+            console.log(`${drift.unadoptedFiles.length} upstream file(s) belong to skills this fork does not adopt — adopt or record them with --ignore.`);
+        }
+        if (tree.truncated) {
+            console.log("warning: the upstream listing was truncated, so this comparison may be partial.");
+        }
+    }
+    if (opts.failOnDrift && driftCount > 0 && !tree.truncated) {
+        process.exitCode = 1;
+    }
+}
+
+if (require.main === module) {
+    main().catch((err) => {
+        console.error(`❌ upstream-drift: ${err.message}`);
+        process.exitCode = 2;
+    });
+}
+
+module.exports = { parseArgs, skillNameOf, readBaseline, localSkillPaths, classifyDrift, classifyCoverage, requireCompleteTreeForRecord };

package/skills/brainstorming/SKILL.md

@@ -11,12 +11,48 @@ Start by classifying how much process the request needs, then work
 through your path: understand the context, refine the idea, present a
 design, and get your human partner's approval.
 
+## Establish Shared Understanding
+
+The outcome of brainstorming is an understanding your human partner can
+recognize and correct, grounded in what they want to accomplish.
+
+1. **Discover intent.** Use the request and available context to identify
+   the intended outcome, who it is for, and what success looks like. When
+   that information is missing, ask one focused question about purpose or
+   intended use before proposing features or an approach. Knowing the app
+   genre does not tell you why your partner wants it. Gathering missing
+   requirements does not ask them to authorize the task again.
+2. **Write back your understanding.** Summarize the intended outcome,
+   relevant constraints, and success criteria in a short note your partner
+   can assess. Separate what they said from assumptions. Invite correction
+   and incorporate their answer before treating this as the design brief.
+3. **Carry intent into the design.** Preserve the agreed understanding in
+   the selected path's design artifact: the written spec for architectural
+   work, or the in-chat design/probe for bounded work and spikes. Check
+   proposed features and technical choices against that understanding.
+
+When the request already supplies the purpose and constraints, reflect
+that understanding instead of asking the same questions again. Keep the
+note concise; its accuracy and the opportunity to correct it matter.
+
 <HARD-GATE>
-Do NOT invoke any implementation skill, write any code, scaffold any
-project, or take any implementation action until you have told your
-human partner what you intend and they have approved it. This applies
-to EVERY task on EVERY path below — the ceremony scales with the task;
-the approval gate never does.
+Before taking any implementation action, including invoking an
+implementation skill, writing product code, scaffolding, installing
+product dependencies, or creating an external project, complete the
+selected path's prerequisites:
+
+- Spike: the human partner approves the question and probe.
+- Bounded: the human partner approves the short in-chat design.
+- Architectural: the human partner reviews and approves the written spec,
+  then reviews the written implementation plan and selects its execution
+  method. Conversational design approval only permits writing the spec;
+  written-spec approval only permits invoking writing-plans.
+
+A reply approves the stage actually presented. Approval of an idea or
+feature scope does not approve artifacts that do not exist yet. Resume
+at the earliest incomplete stage; do not turn one approval into permission
+to skip the rest of the selected path. Read-only project exploration is
+allowed while those prerequisites remain incomplete.
 </HARD-GATE>
 
 ## Three Paths
@@ -53,18 +89,17 @@ stop, say so, and step up. Nothing downgrades mid-task.
 
 ## Anti-Pattern: "Too Simple To Need Approval"
 
-Every path ends with your human partner approving your intent before
-implementation. A todo list, a single-function utility, a config
-change — the design may be two sentences in chat, but you MUST present
-it and get approval. "Simple" tasks are where unexamined assumptions
-cause the most wasted work. What scales with simplicity is the
-artifact, never the approval.
+Every path ends with your human partner approving the required design
+before implementation. A bounded change may need only two sentences in
+chat. A new todo-list project is architectural and requires the written
+spec and planning handoffs. Scale the artifact to the selected path;
+complete that path's reviews before implementation.
 
 ## Red Flags
 
 | Thought | Reality |
 |---------|---------|
-| "This is too simple to need a design" | Simple means a short design, not no design. Two sentences in chat, then approval. |
+| "This is too simple to need a design" | Follow the selected path: a bounded change gets a short chat design; an architectural change gets the written spec and planning handoffs. |
 | "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. |
 | "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |
 | "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. |
@@ -98,7 +133,7 @@ your path and complete them in order.
 4. **Propose 2-3 approaches** — with trade-offs and your recommendation
 5. **Present design** — in sections scaled to their complexity, get user approval after each section
 6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
-7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
+7. **Planning-handoff review** — simulate the next planning stage, rate and inventory its burdens, and take the required bounded branch (see below)
 8. **User reviews written spec** — ask user to review the spec file before proceeding
 9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
 
@@ -119,7 +154,7 @@ digraph brainstorming {
     "Present design sections" [shape=box];
     "User approves design?" [shape=diamond];
     "Write design doc" [shape=box];
-    "Spec self-review\n(fix inline)" [shape=box];
+    "Planning-handoff review\n(rate; burden ledger; bounded branch)" [shape=box];
     "User reviews spec?" [shape=diamond];
     "Invoke writing-plans skill" [shape=doublecircle];
     "Hidden complexity? Upgrade path" [shape=box];
@@ -139,8 +174,8 @@ digraph brainstorming {
     "Present design sections" -> "User approves design?";
     "User approves design?" -> "Present design sections" [label="no, revise"];
     "User approves design?" -> "Write design doc" [label="yes"];
-    "Write design doc" -> "Spec self-review\n(fix inline)";
-    "Spec self-review\n(fix inline)" -> "User reviews spec?";
+    "Write design doc" -> "Planning-handoff review\n(rate; burden ledger; bounded branch)";
+    "Planning-handoff review\n(rate; burden ledger; bounded branch)" -> "User reviews spec?";
     "User reviews spec?" -> "Write design doc" [label="changes requested"];
     "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
 }
@@ -169,6 +204,7 @@ is the whole process.
 - For appropriately-scoped projects, ask questions one at a time to refine the idea
 - Prefer multiple choice questions when possible, but open-ended is fine too
 - Only one question per message - if a topic needs more exploration, break it into multiple questions
+- A request for context is not an answer - if the user asks for trade-offs, implications, or examples instead of choosing, give them that and then re-ask the same question. It stays the only open question until they decide; don't pair it with a new one
 - Focus on understanding: purpose, constraints, success criteria
 
 **Exploring approaches:**
@@ -209,15 +245,79 @@ is the whole process.
 - Use elements-of-style:writing-clearly-and-concisely skill if available
 - Commit the design document to git
 
-**Spec Self-Review:**
-After writing the spec document, look at it with fresh eyes:
-
-1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
-2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
-3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
-4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.
-
-Fix any issues inline. No need to re-review — just fix and move on.
+**Planning-Handoff Review:**
+This is the spec self-review. Before asking for review, set the conversation
+aside and temporarily act as a
+fresh planning agent whose only inputs are the finished spec and the repository.
+Begin mapping how you would turn the spec into an implementation plan, but do not
+write that plan. Trace each affected entry point through the relevant components
+and state transitions. Note each point where planning would require you to
+rediscover design intent or invent a binding decision rather than choose an
+implementation detail. Include placeholders, internal contradictions, scope
+problems, and ambiguous requirements in this assessment; they are handoff seams,
+not a separate review stage.
+
+Rate the spec's planning-handoff readiness from 0.0–9.9 and explain what
+prevents the next higher rating using repository and artifact evidence:
+0 = reject; 2 = major redesign; 4 = substantial design rescue; 6 = usable but
+planning must reconstruct a binding decision; 8 = handoff-ready with only
+planning-owned choices; 9.9 = rare exemplary ceiling, never perfection. The
+rating prompts the assessment; it does not decide whether the artifact improves.
+
+Translate every design-owned reason preventing the next higher rating into a
+burden ledger before editing. One burden is one independent binding decision or
+piece of design reconstruction the planning agent must resolve before it can
+specify implementation work. Record planning-owned choices separately rather
+than counting them as burdens. For each burden, state the repository or artifact
+evidence, what the planner would have to invent, and its weight:
+
+- **minor (1):** a localized clarification or reconstruction;
+- **major (2):** an unresolved binding decision or cross-component design
+  uncertainty. Record contradictions and departures from the approved design
+  separately; they are not ordinary tradeable burdens.
+
+After the initial rating and ledger, take exactly one branch:
+
+- If the rating is below 9.0 **or** the ledger contains any burden, preserve the
+  initial draft, return to the spec-writer role, and make one bounded improvement
+  pass targeting the evidence-based reasons preventing 9.0 and the named
+  burdens. Do not resolve a purely planning-owned choice merely to raise the
+  rating.
+- Only if the rating is at least 9.0 **and** the burden ledger is empty, make no
+  edit.
+
+The bounded pass is the only review-driven editing phase after the first
+complete draft. It may clarify, reconcile, and complete the spec using the
+approved design, stated requirements, and repository evidence; preserve the
+binding decisions already approved in the conversation. When an improvement
+would require a new or changed binding design decision, leave it as a burden
+instead of choosing it.
+
+After the pass, close editing and reassess both versions read-only. Trace every
+concept changed by the pass through the whole spec, including the state model,
+entry points, failure/recovery rules, and acceptance criteria. Give a fresh
+rating, build the final burden ledger from scratch, and compare it with the
+initial ledger. Include burdens that moved or appeared elsewhere. Check
+separately for a newly introduced major burden, contradiction, departure from
+approved design, or scope change. More specific wording is not automatically an
+improvement.
+
+Select the revised draft only when its total weighted burden is lower and it
+introduces no new major burden, contradiction, or design departure. New minor
+burdens are permitted only when the total burden still falls. Otherwise restore
+the preserved initial draft. Restoring the original is the only spec mutation
+permitted after reassessment: do not fix the revised draft or begin another
+pass. Present the selected spec through the normal user review handoff, and
+commit the selected draft — with any changes the user requests afterwards — so
+that handoff always points at a committed revision.
+Keep the ratings, burden ledgers, and comparison in your private review; do not
+add them to the spec or require them as a separate handoff artifact.
+If the original was restored, mention briefly that the tentative revision was
+rejected and the original retained; do not add a separate review artifact.
+
+Accept, restore, and report based on burden—not whether the rating rose. The
+review never grants permission to begin planning. Do not produce task sequencing,
+invoke `writing-plans`, or repeat the pass.
 
 **User Review Gate:**
 After the spec review loop passes, ask the user to review the written spec before proceeding:

package/skills/brainstorming/scripts/start-server.ps1

@@ -67,7 +67,9 @@ $projectDir = ""
 $foreground = $false
 $forceBackground = $false
 $bindHost = "127.0.0.1"
+if ($env:BRAINSTORM_HOST) { $bindHost = $env:BRAINSTORM_HOST }
 $urlHost = ""
+if ($env:BRAINSTORM_URL_HOST) { $urlHost = $env:BRAINSTORM_URL_HOST }
 $idleTimeoutMinutes = ""
 
 for ($i = 0; $i -lt $args.Count; $i++) {
@@ -151,17 +153,34 @@ if ($env:CODEX_CI -and -not $foreground -and -not $forceBackground) {
     $foreground = $true
 }
 
-$sessionId = "$PID-$([DateTimeOffset]::UtcNow.ToUnixTimeSeconds())"
+$baseSessionId = "$PID-$([DateTimeOffset]::UtcNow.ToUnixTimeSeconds())"
 $brainstormRoot = ""
 if ($projectDir -ne "") {
     $brainstormRoot = Join-Path $projectDir ".superpowers/brainstorm"
+    # $PID is the invoking host process, so two starts in the same second from
+    # one pwsh session would resolve to the same id and die on the live
+    # session's redirected log file. Take the next free directory instead.
+    $sessionId = $baseSessionId
     $sessionDir = Join-Path $brainstormRoot $sessionId
+    $sessionSuffix = 2
+    while (Test-Path -LiteralPath $sessionDir) {
+        $sessionId = "$baseSessionId-$sessionSuffix"
+        $sessionDir = Join-Path $brainstormRoot $sessionId
+        $sessionSuffix++
+    }
     # Reuse the last bound port and session key so a restart keeps an
     # already-open browser tab connected to the same URL with a valid cookie.
     $env:BRAINSTORM_PORT_FILE = Join-Path $brainstormRoot ".last-port"
     $env:BRAINSTORM_TOKEN_FILE = Join-Path $brainstormRoot ".last-token"
 } else {
+    $sessionId = $baseSessionId
     $sessionDir = Join-Path ([System.IO.Path]::GetTempPath()) "brainstorm-$sessionId"
+    $sessionSuffix = 2
+    while (Test-Path -LiteralPath $sessionDir) {
+        $sessionId = "$baseSessionId-$sessionSuffix"
+        $sessionDir = Join-Path ([System.IO.Path]::GetTempPath()) "brainstorm-$sessionId"
+        $sessionSuffix++
+    }
     # $env: assignments persist in the invoking pwsh session; a stale project
     # token/port file from an earlier --project-dir run must not leak into an
     # ephemeral session (it would defeat key rotation and could overwrite the

package/skills/brainstorming/scripts/start-server.sh

@@ -23,8 +23,8 @@ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_DIR=""
 FOREGROUND="false"
 FORCE_BACKGROUND="false"
-BIND_HOST="127.0.0.1"
-URL_HOST=""
+BIND_HOST="${BRAINSTORM_HOST:-127.0.0.1}"
+URL_HOST="${BRAINSTORM_URL_HOST:-}"
 IDLE_TIMEOUT_MINUTES=""
 while [[ $# -gt 0 ]]; do
   case "$1" in