supipowers 0.2.7 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supipowers",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "OMP-native workflow extension inspired by Superpowers.",
   "type": "module",
   "scripts": {
@@ -9,12 +9,23 @@
     "test:watch": "vitest",
     "build": "tsc -p tsconfig.build.json"
   },
-  "keywords": ["omp-extension", "workflow", "agent", "superpowers"],
+  "keywords": [
+    "omp-extension",
+    "workflow",
+    "agent",
+    "superpowers"
+  ],
   "license": "MIT",
   "bin": {
-    "supipowers": "./bin/install.mjs"
+    "supipowers": "bin/install.mjs"
   },
-  "files": ["src", "skills", "bin", "README.md", "LICENSE"],
+  "files": [
+    "src",
+    "skills",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
   "dependencies": {
     "@clack/prompts": "^0.10.0"
   },
@@ -32,7 +43,11 @@
     "vitest": "^4.0.0"
   },
   "omp": {
-    "extensions": ["./src/index.ts"],
-    "skills": ["./skills"]
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
   }
 }

package/skills/debugging/SKILL.md

@@ -1,23 +1,62 @@
 ---
 name: debugging
-description: Systematic debugging approach — investigate before fixing
+description: Systematic debugging — find root cause before attempting fixes, 4-phase investigation process
 ---
 
-# Debugging Skill
+# Systematic Debugging
 
-## Process
+## Iron Law
 
-1. **Reproduce**: Can you reliably trigger the bug?
-2. **Isolate**: What's the smallest input that triggers it?
-3. **Investigate**: Read the relevant code. Trace the execution path.
-4. **Hypothesize**: Form a theory about the root cause.
-5. **Verify**: Add logging or a test that confirms the theory.
-6. **Fix**: Make the minimal change that fixes the root cause.
-7. **Validate**: Run the reproducer and existing tests.
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
 
-## Rules
+Symptom fixes are failure. If you haven't completed Phase 1, you cannot propose fixes.
 
-- Never guess-and-fix. Investigate first.
-- After 3 failed fix attempts, step back and question your assumptions.
-- Fix the root cause, not the symptom.
-- Add a test that would have caught this bug.
+## Phase 1: Root Cause Investigation
+
+Complete this phase before proposing any fix.
+
+1. **Read error messages carefully.** Don't skip; they often contain solutions.
+2. **Reproduce consistently.** Exact steps, every time.
+3. **Check recent changes.** `git diff`, new dependencies, config changes.
+4. **Gather evidence** in multi-component systems: diagnostic instrumentation at each boundary.
+5. **Trace data flow** backward through call stack to find original trigger.
+
+## Phase 2: Pattern Analysis
+
+1. Find working examples in codebase.
+2. Compare against references completely (not skimming).
+3. Identify differences between working and broken.
+4. Understand dependencies and assumptions.
+
+## Phase 3: Hypothesis and Testing
+
+1. Form a single, specific hypothesis (not vague).
+2. Test minimally: smallest possible change, one variable at a time.
+3. Verify before continuing. If wrong → form NEW hypothesis, not more fixes.
+4. Admit uncertainty. Don't pretend to know.
+
+## Phase 4: Implementation
+
+1. Create failing test case first.
+2. Implement single fix addressing root cause only.
+3. Verify: test passes, no other tests broken.
+4. **If fix doesn't work:**
+   - < 3 attempts: Return to Phase 1 with new information
+   - ≥ 3 attempts: **STOP** and question the architecture. Discuss with human partner.
+
+## Red Flags — STOP and Follow the Process
+
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "One more fix attempt" (when already tried 2+)
+- Each fix reveals new problem in different place
+
+## When to Use (Especially)
+
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- Already tried multiple fixes
+- Don't fully understand the issue

package/skills/planning/SKILL.md

@@ -1,29 +1,82 @@
 ---
 name: planning
-description: Guides collaborative planning and task breakdown for implementation
+description: Guides collaborative brainstorming, design, and planning — from idea to implementation plan with review gates
 ---
 
 # Planning Skill
 
-Guide the user through planning an implementation. This skill is loaded by `/supi:plan`.
+Guide the user through a complete planning flow: brainstorm → design → spec → review → plan. This skill is loaded by `/supi:plan`.
+
+<HARD-GATE>
+Do NOT write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
 
 ## Process
 
-1. **Understand**: Ask one clarifying question at a time. Prefer multiple choice.
-2. **Propose**: Offer 2-3 approaches with trade-offs and your recommendation.
-3. **Break down**: Generate bite-sized tasks with clear boundaries.
+Follow these phases in order. Do not skip or combine them.
+
+### Phase 1: Explore Project Context
+
+Before asking questions, understand the current state:
+- Check files, docs, recent commits
+- Understand existing architecture and patterns
+- If the request covers multiple independent subsystems, flag it immediately and help decompose into sub-projects
+
+### Phase 2: Ask Clarifying Questions
+
+- One question at a time — never overwhelm with multiple questions
+- Prefer multiple choice when possible, open-ended is fine too
+- Focus on: purpose, constraints, success criteria
+- Continue until you have enough clarity to propose approaches
+
+### Phase 3: Propose 2-3 Approaches
+
+- Present 2-3 different approaches with trade-offs
+- Lead with your recommended option and explain why
+- Wait for the user to choose before proceeding
+
+### Phase 4: Present Design
+
+Once aligned on approach:
+- Scale each section to its complexity (a few sentences if straightforward, up to 200-300 words if nuanced)
+- Cover: architecture, components, data flow, error handling, testing
+- Ask after each section whether it looks right so far
+- Apply YAGNI ruthlessly — remove unnecessary features
+- Design for isolation: smaller units with clear boundaries
+
+### Phase 5: Write Design Doc
 
-## Task Format
+Once the user approves the design:
+- Save to `docs/supipowers/specs/YYYY-MM-DD-<topic>-design.md`
+- Use clear, concise writing
+- Commit the design document to git
 
-Each task must have:
+### Phase 6: Spec Review Loop
+
+After writing the design doc:
+1. Dispatch a spec-document-reviewer sub-agent to verify completeness
+2. If **Issues Found**: fix the issues, re-dispatch the reviewer
+3. Repeat until **Approved** (max 5 iterations, then surface to human)
+
+### Phase 7: User Review Gate
+
+Ask the user to review the spec before proceeding:
+
+> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."
+
+Wait for their response. Only proceed once approved.
+
+### Phase 8: Create Implementation Plan
+
+Break into bite-sized tasks (2-5 minutes each). Each task must have:
 - Name with parallelism: `[parallel-safe]` or `[sequential: depends on N]`
 - **files**: Exact paths the agent will touch
 - **criteria**: Acceptance criteria (testable)
 - **complexity**: `small` | `medium` | `large`
 
-## Plan Structure
+Include exact code in the plan, not vague descriptions. Use checkbox syntax (`- [ ]`) for tracking steps.
 
-Use this template:
+## Plan Structure
 
 ```
 ---
@@ -43,12 +96,19 @@ tags: [<relevant>, <tags>]
 - **files**: src/path/to/file.ts
 - **criteria**: <what success looks like>
 - **complexity**: small
+
+- [ ] Step 1: Write the failing test
+- [ ] Step 2: Run test to verify it fails
+- [ ] Step 3: Write minimal implementation
+- [ ] Step 4: Run test to verify it passes
+- [ ] Step 5: Commit
 ```
 
 ## Principles
 
-- Each task should be completable in 2-10 minutes
+- Each task should be completable in 2-5 minutes
 - Tasks that touch different files are parallel-safe
 - Tasks that depend on others' output are sequential
 - Include test files in the files list
 - Prefer small, focused tasks over large ones
+- DRY, YAGNI, TDD, frequent commits

package/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: receiving-code-review
+description: Receiving code review feedback — verify before implementing, technical rigor not performative agreement
+---
+
+# Receiving Code Review
+
+## Core Principle
+
+Code review requires technical evaluation, not emotional performance.
+Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+1. **READ:** Complete feedback without reacting.
+2. **UNDERSTAND:** Restate the requirement in your own words, or ask for clarification.
+3. **VERIFY:** Check against codebase reality.
+4. **EVALUATE:** Is this technically sound for THIS codebase?
+5. **RESPOND:** Technical acknowledgment or reasoned pushback.
+6. **IMPLEMENT:** One item at a time, test each change.
+
+## Forbidden Responses
+
+Never use performative agreement:
+- "You're absolutely right!"
+- "Great point!"
+- "Excellent catch!"
+- "Thanks for catching that!"
+
+Instead: restate requirements, ask clarifying questions, take action.
+
+Acceptable responses:
+- "Fixed. [description of what changed]"
+- "Good catch — [issue]. Fixed in [location]."
+- "I disagree because [technical reason]. Here's why: ..."
+
+## Handling Unclear Feedback
+
+If ANY item is unclear, stop and ask for clarification before implementing anything.
+Items may be related — clarify all unclear items before starting work.
+
+## Source-Specific Handling
+
+**From your human partner:** Trusted. Implement after understanding.
+
+**From external reviewers:** Verify technically. Check for breaking changes. Question whether the reviewer understands the full context.
+
+## YAGNI Check
+
+For suggested "professional features" — grep the codebase for actual usage.
+If unused, suggest removal instead of implementing.
+
+## Implementation Order
+
+1. Clarify all unclear items first
+2. Blocking issues (must fix)
+3. Simple fixes (quick wins)
+4. Complex fixes (may need discussion)
+5. Test each change before moving to the next
+
+## When to Push Back
+
+Push back when feedback would:
+- Introduce bugs or break existing behavior
+- Add unnecessary complexity (YAGNI violation)
+- Contradict the codebase's established patterns
+- Solve a problem that doesn't exist
+
+Use technical reasoning, not defensiveness.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Agree immediately | Verify against codebase first |
+| Implement all at once | One at a time, test each |
+| Skip unclear items | Ask first, implement second |
+| Performative gratitude | Technical acknowledgment only |
+| Defensive pushback | Reasoned technical argument |
+| Trust without verifying | Check codebase reality |
+| Implement suggested feature | YAGNI check — is it actually needed? |
+
+## The Bottom Line
+
+External feedback = suggestions to evaluate, not orders to follow.
+Verify. Question. Then implement.
+No performative agreement. Technical rigor always.

package/skills/tdd/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: tdd
+description: Test-driven development — write the test first, watch it fail, write minimal code to pass
+---
+
+# Test-Driven Development
+
+## Iron Law
+
+**NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.**
+
+Write code before the test? Delete it. Start over. No exceptions.
+
+## Red-Green-Refactor
+
+### RED — Write Failing Test
+
+- One behavior per test. "and" in the name? Split it.
+- Clear name that describes behavior.
+- Real code, not mocks (unless unavoidable).
+
+**Watch it fail. MANDATORY.**
+- Confirm: fails (not errors), failure message expected, fails because feature missing.
+- Test passes? You're testing existing behavior. Fix the test.
+
+### GREEN — Minimal Code
+
+Write the simplest code that makes the test pass.
+
+- Don't add features, refactor other code, or "improve" beyond the test.
+
+**Watch it pass. MANDATORY.**
+- Confirm: test passes, other tests still pass, output pristine.
+- Test fails? Fix code, not test.
+
+### REFACTOR — Clean Up (After Green Only)
+
+- Remove duplication, improve names, extract helpers.
+- Keep tests green. Don't add behavior.
+
+## Verification Checklist
+
+Before marking work complete:
+
+- [ ] Every new function/method has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for expected reason (feature missing, not typo)
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass with pristine output
+- [ ] Tests use real code (mocks only if unavoidable)
+- [ ] Edge cases and errors covered
+
+## Red Flags — STOP and Start Over
+
+- Code before test
+- Test after implementation
+- Test passes immediately
+- Can't explain why test failed
+- Tests added "later"
+- Rationalizing "just this once"
+
+All of these mean: delete code, start over with TDD.
+
+## Testing Anti-Patterns
+
+- Don't test mock behavior instead of real behavior
+- Don't add test-only methods to production classes
+- Don't mock without understanding dependencies
+- Mocks are tools to isolate, not things to test
+
+## When Stuck
+
+| Problem | Solution |
+|---------|----------|
+| Don't know how to test | Write wished-for API. Write assertion first. Ask. |
+| Test too complicated | Design too complicated. Simplify interface. |
+| Must mock everything | Code too coupled. Use dependency injection. |
+| Test setup huge | Extract helpers. Still complex? Simplify design. |
+
+## Bug Fix Flow
+
+Bug found? Write a failing test reproducing it. Follow the TDD cycle.
+The test proves the fix and prevents regression. Never fix bugs without a test.

package/skills/verification/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: verification
+description: Verification before completion — evidence before claims, always
+---
+
+# Verification Before Completion
+
+## Iron Law
+
+**NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.**
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+Evidence before assertions, always.
+
+## The Gate Function (Mandatory Before Any Status Claim)
+
+1. **IDENTIFY:** What command proves this claim?
+2. **RUN:** Execute the FULL command (fresh, complete).
+3. **READ:** Full output. Check exit code. Count failures.
+4. **VERIFY:** Does output confirm the claim?
+   - If NO: State actual status with evidence.
+   - If YES: State claim WITH evidence.
+5. **ONLY THEN:** Make the claim.
+
+Skip any step = lying, not verifying.
+
+## Common Failure Patterns
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags — STOP Before Claiming
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+- About to commit/push/PR without verification
+- Trusting agent success reports without checking
+- Relying on partial verification
+- Thinking "just this once"
+
+## When to Apply
+
+ALWAYS before:
+- Any variation of success/completion claims
+- Any expression of satisfaction about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents

package/src/commands/plan.ts

@@ -1,10 +1,29 @@
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
 import { loadConfig } from "../config/loader.js";
 import { savePlan } from "../storage/plans.js";
-import { notifySuccess, notifyInfo } from "../notifications/renderer.js";
+import { notifySuccess, notifyInfo, notifyError } from "../notifications/renderer.js";
+import {
+  generateVisualSessionId,
+  createSessionDir,
+  getScriptsDir,
+  parseServerInfo,
+} from "../visual/companion.js";
+import { buildVisualInstructions } from "../visual/prompt-instructions.js";
+import { buildPlanningPrompt, buildQuickPlanPrompt } from "../planning/prompt-builder.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+/** Module-level tracking for cleanup */
+let activeSessionDir: string | null = null;
+
+export function getActiveVisualSessionDir(): string | null {
+  return activeSessionDir;
+}
+
+export function setActiveVisualSessionDir(dir: string | null): void {
+  activeSessionDir = dir;
+}
+
 export function registerPlanCommand(pi: ExtensionAPI): void {
   pi.registerCommand("supi:plan", {
     description: "Start collaborative planning for a feature or task",
@@ -24,39 +43,85 @@ export function registerPlanCommand(pi: ExtensionAPI): void {
       const isQuick = args?.startsWith("--quick");
       const quickDesc = isQuick ? args.replace("--quick", "").trim() : "";
 
+      // ── Visual companion consent ──────────────────────────────────
+      let visualUrl: string | null = null;
+      let visualSessionDir: string | null = null;
+
+      if (ctx.hasUI && !isQuick) {
+        const modeChoice = await ctx.ui.select(
+          "Planning mode",
+          [
+            "Terminal only",
+            "Terminal + Visual companion (opens browser)",
+          ],
+          { helpText: "Visual companion shows mockups and diagrams in a browser · Esc to cancel" },
+        );
+        if (!modeChoice) return;
+
+        if (modeChoice.startsWith("Terminal + Visual")) {
+          const sessionId = generateVisualSessionId();
+          visualSessionDir = createSessionDir(ctx.cwd, sessionId);
+          const scriptsDir = getScriptsDir();
+
+          // Install server dependencies if needed
+          const nodeModules = path.join(scriptsDir, "node_modules");
+          if (!fs.existsSync(nodeModules)) {
+            notifyInfo(ctx, "Installing visual companion dependencies...");
+            const installResult = await pi.exec("npm", ["install", "--production"], { cwd: scriptsDir });
+            if (installResult.code !== 0) {
+              notifyError(ctx, "Failed to install visual companion dependencies", installResult.stderr);
+              visualSessionDir = null;
+            }
+          }
+
+          if (visualSessionDir) {
+            // Stop any previous visual companion
+            if (activeSessionDir) {
+              const stopScript = path.join(scriptsDir, "stop-server.sh");
+              await pi.exec("bash", [stopScript, activeSessionDir], { cwd: scriptsDir });
+            }
+
+            // Start the server (pass session dir via env command since ExecOptions has no env)
+            const startScript = path.join(scriptsDir, "start-server.sh");
+            const startResult = await pi.exec("env", [
+              `SUPI_VISUAL_DIR=${visualSessionDir}`,
+              "bash",
+              startScript,
+            ], { cwd: scriptsDir });
+
+            if (startResult.code === 0) {
+              const serverInfo = parseServerInfo(startResult.stdout);
+              if (serverInfo) {
+                visualUrl = serverInfo.url;
+                activeSessionDir = visualSessionDir;
+                notifyInfo(ctx, "Visual companion ready", visualUrl);
+              } else {
+                notifyError(ctx, "Visual companion started but no connection info received");
+                visualSessionDir = null;
+              }
+            } else {
+              const errorMsg = startResult.stderr || startResult.stdout;
+              notifyError(ctx, "Failed to start visual companion", errorMsg);
+              visualSessionDir = null;
+            }
+          }
+        }
+      }
+
+      // ── Build prompt ──────────────────────────────────────────────
       let prompt: string;
       if (isQuick && quickDesc) {
-        prompt = [
-          "Generate a concise implementation plan for the following task.",
-          "Skip brainstorming — go straight to task breakdown.",
-          "",
-          `Task: ${quickDesc}`,
-          "",
-          "Format the plan as markdown with YAML frontmatter (name, created, tags).",
-          "Each task should have: name, [parallel-safe] or [sequential] annotation,",
-          "**files**, **criteria**, and **complexity** (small/medium/large).",
-          "",
-          skillContent ? "Follow these planning guidelines:\n" + skillContent : "",
-          "",
-          "After generating the plan, save it and confirm with the user.",
-        ].join("\n");
+        prompt = buildQuickPlanPrompt(quickDesc, skillContent || undefined);
       } else {
-        prompt = [
-          "You are starting a collaborative planning session with the user.",
-          "",
-          args ? `The user wants to plan: ${args}` : "Ask the user what they want to build or accomplish.",
-          "",
-          "Process:",
-          "1. Understand the goal — ask clarifying questions (one at a time)",
-          "2. Propose 2-3 approaches with trade-offs",
-          "3. Generate a task breakdown once aligned",
-          "",
-          "Format the final plan as markdown with YAML frontmatter (name, created, tags).",
-          "Each task: name, [parallel-safe] or [sequential] annotation,",
-          "**files**, **criteria**, **complexity** (small/medium/large).",
-          "",
-          skillContent ? "Follow these planning guidelines:\n" + skillContent : "",
-        ].join("\n");
+        prompt = buildPlanningPrompt({
+          topic: args || undefined,
+          skillContent: skillContent || undefined,
+        });
+      }
+
+      // Append visual companion instructions if active
+      if (visualUrl && visualSessionDir) {
+        prompt += "\n\n" + buildVisualInstructions(visualUrl, visualSessionDir);
       }
 
       pi.sendMessage(