supermind-claude 2.1.1 → 4.0.2

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,165 @@
+<!-- Forked from obra/superpowers (MIT license) by Jesse Vincent and Prime Radiant. Assumptions mode inspired by gsd-build/get-shit-done (MIT license). Adapted for Supermind orchestrator. -->
+---
+name: brainstorming
+description: Pre-implementation design exploration with interactive and assumptions modes — used by orchestrator Discuss phase
+injects_into: [orchestrator-discuss]
+forked_from: obra/superpowers (MIT)
+---
+
+# Brainstorming Ideas Into Designs
+
+Pre-implementation design exploration. Used by the orchestrator during the Discuss phase of Project Mode. Ensures Claude understands what to build before building it.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until a design is presented and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Modes
+
+### MODE 1 — Interactive (default)
+
+The default mode. Ask clarifying questions to understand what the user wants.
+
+- Ask questions **one at a time** — never batch multiple questions
+- Prefer **multiple choice** when possible — easier to answer than open-ended
+- Focus on: **purpose**, **constraints**, **success criteria**, **scope**
+- Only one question per message — if a topic needs more exploration, break it into multiple questions
+
+### MODE 2 — Assumptions (triggered by `--assumptions` flag)
+
+For users who know what they want and work in a codebase Claude can read. Instead of interviewing the user, analyze the codebase and present assumptions for correction.
+
+1. Read relevant files, recent commits, existing patterns, ARCHITECTURE.md, DESIGN.md
+2. Analyze the request against the codebase context
+3. Present a numbered list of assumptions:
+   > "Based on the codebase, here's what I think you want..."
+   >
+   > 1. **Location:** New code goes in `src/components/` following the existing pattern
+   > 2. **Pattern:** Uses the same factory pattern as `src/components/button.js`
+   > 3. **Testing:** Jest tests matching `*.test.js` convention
+   > 4. **Scope:** Only modifies the rendering pipeline, no API changes
+   > ...
+4. User corrects or confirms each assumption
+5. For anything the codebase can't answer, fall back to Interactive mode for those specific questions
+
+Assumptions mode is faster but requires a readable codebase. If the codebase lacks clear patterns or the request is highly ambiguous, fall back to Interactive mode entirely.
+
+## Process Flow
+
+```
+1. Explore project context (files, docs, recent commits)
+2. Detect scope (single feature vs. multi-system)
+3. Choose mode (interactive or assumptions based on flag)
+4. Build understanding of what to build
+5. Propose 2-3 approaches with trade-offs
+6. Present design, get user approval section by section
+7. Output: structured design document → .planning/phases/phase-N/discussion.md
+```
+
+### Step 1: Explore Project Context
+
+Before asking any questions or making assumptions, understand the project:
+
+- Check existing files, directory structure, and patterns
+- Read ARCHITECTURE.md and DESIGN.md if they exist
+- Review recent commits for current direction and momentum
+- Note conventions: naming, file organization, test patterns
+
+### Step 2: Detect Scope
+
+Before refining details, assess scope. If the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately:
+
+> "This looks like it has N independent subsystems. Rather than designing a monolith, let's break it into sub-projects that each get their own design cycle."
+
+Help decompose into sub-projects:
+- What are the independent pieces?
+- How do they relate?
+- What order should they be built?
+
+Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own discussion → plan → execution cycle.
+
+### Step 3: Choose Mode
+
+- **No flag or `--interactive`:** Use Interactive mode (Step 4a)
+- **`--assumptions` flag:** Use Assumptions mode (Step 4b)
+
+### Step 4a: Interactive — Build Understanding
+
+Ask questions one at a time to understand:
+- **Purpose:** What problem does this solve? Who is it for?
+- **Constraints:** Performance, compatibility, timeline, tech stack requirements?
+- **Success criteria:** How do we know it works?
+- **Scope:** What's explicitly out of scope?
+
+Keep asking until you have enough to propose approaches. Don't over-question simple projects.
+
+### Step 4b: Assumptions — Build Understanding
+
+Analyze the codebase and present assumptions (see MODE 2 above). After corrections, you should have the same understanding as the interactive path.
+
+### Step 5: Propose Approaches
+
+Propose 2-3 different approaches with trade-offs:
+- Lead with your recommended option and explain why
+- Include at least one simpler alternative
+- Be concrete: name files, patterns, dependencies
+- Call out what each approach trades off (complexity, flexibility, speed)
+
+### Step 6: Present Design
+
+Once the user picks an approach (or you've converged on one):
+- Present the design **section by section**
+- Scale detail to complexity: a few sentences if straightforward, paragraphs if nuanced
+- Ask after each section whether it looks right so far
+- Cover as appropriate: architecture, components, data flow, error handling, testing approach
+- Revise any section the user pushes back on before moving forward
+
+### Step 7: Output
+
+Save the validated design as a structured Markdown document to `.planning/phases/phase-N/discussion.md` (the orchestrator determines the phase number).
+
+The document should capture:
+- The problem statement
+- Key decisions and their rationale
+- The chosen approach
+- Component breakdown
+- Any constraints or non-goals identified during discussion
+
+## Key Principles
+
+- **One question at a time** — don't overwhelm with multiple questions
+- **Multiple choice preferred** — easier to answer than open-ended when possible
+- **YAGNI ruthlessly** — remove unnecessary features from designs. If the user didn't ask for it and the system doesn't need it, cut it
+- **Explore alternatives** — always propose 2-3 approaches before settling
+- **Design for isolation and clarity** — break into smaller units with one clear purpose, well-defined interfaces, and independent testability
+- **In existing codebases, follow existing patterns** — explore the current structure before proposing changes. Only deviate when existing patterns actively prevent the goal
+- **Incremental validation** — present design sections, get approval before moving on
+- **Scale to complexity** — a trivial change gets a few sentences of design; a system redesign gets paragraphs
+
+## Red Flags — STOP and Reassess
+
+| Signal | Action |
+|--------|--------|
+| Request describes 3+ independent subsystems | Decompose into sub-projects first |
+| User says "just build it" | Present a minimal design anyway — the HARD GATE applies |
+| You're designing features the user didn't mention | YAGNI — cut them |
+| Design requires modifying half the codebase | Scope is too large — decompose |
+| You can't explain a component's purpose in one sentence | Boundary is wrong — rethink |
+| Existing codebase has a pattern for this and you're ignoring it | Follow the pattern unless it's actively broken |
+
+## Verification Checklist
+
+Before transitioning to the Plan phase:
+
+- [ ] Project context explored (files, docs, recent commits)
+- [ ] Scope assessed — multi-system requests decomposed into sub-projects
+- [ ] User understands the problem and constraints
+- [ ] 2-3 approaches proposed with trade-offs
+- [ ] Design presented section by section with user approval
+- [ ] No unnecessary features in design (YAGNI applied)
+- [ ] Design follows existing codebase patterns where applicable
+- [ ] Structured design document saved to `.planning/phases/phase-N/discussion.md`

package/skills/code-review/SKILL.md

@@ -0,0 +1,144 @@
+<!-- Forked from obra/superpowers (MIT license) by Jesse Vincent and Prime Radiant. Adapted for Supermind executor injection. -->
+---
+name: code-review
+description: Structured code review methodology for the Verify phase — review criteria, issue classification, and anti-performative-agreement
+injects_into: [orchestrator-verify]
+forked_from: obra/superpowers (MIT)
+---
+
+# Code Review
+
+## Review Process
+
+Follow these steps in order. Do not skip steps.
+
+### 1. Understand the Intent
+
+Read the plan or task spec first. Understand what was supposed to be built before looking at code. If there is no plan, infer intent from commit messages and the diff itself — but flag the missing spec as a concern.
+
+### 2. Read All Changed Files
+
+Get the full diff against the base branch (`git diff <base>...HEAD`). Read every changed file completely — not just the diff hunks. Context around changes matters.
+
+### 3. Evaluate Against Criteria
+
+Check every change against all six criteria. Do not skip criteria because "it looks fine."
+
+#### a. Spec Compliance
+
+Does the code do what the plan said? Check each acceptance criterion. If a criterion is unmet, that is a critical issue regardless of code quality.
+
+#### b. Correctness
+
+- Logic errors, off-by-ones, fence-post errors
+- Edge cases: empty inputs, null/undefined, boundary values, overflow
+- Error handling: are errors caught? Are they handled correctly or silently swallowed?
+- Async correctness: race conditions, unhandled rejections, missing awaits
+
+#### c. Test Coverage
+
+- Are the important behaviors tested?
+- Are edge cases and error paths covered?
+- Do tests verify behavior, not implementation details?
+- Do tests actually fail when the feature is broken? (Not just "passes when correct")
+- Missing tests for new public functions or changed behavior = important issue
+
+#### d. Security
+
+- Injection: command injection, SQL injection, XSS, template injection
+- Path traversal: unsanitized user input in file paths
+- Secrets: API keys, passwords, tokens hardcoded or logged
+- Unsafe operations: eval, exec with unsanitized input, deserialization of untrusted data
+- Permissions: missing access checks, privilege escalation
+
+#### e. Maintainability
+
+- Clear naming: can you understand the code without reading the commit message?
+- Reasonable file sizes: single files doing too many things
+- No unnecessary complexity: abstractions that serve no current purpose, premature generalization
+- Comments where logic isn't self-evident (and no comments where it is)
+
+#### f. Consistency
+
+- Follows existing codebase patterns (naming conventions, module structure, export style)
+- Uses existing utilities instead of reimplementing
+- Matches the project's error handling pattern
+- Follows the project's test structure and naming
+
+## Issue Classification
+
+Every finding gets exactly one classification:
+
+| Classification | Meaning | Action Required |
+|---------------|---------|-----------------|
+| **Critical** | Must fix before merge. Bugs, security issues, spec violations, missing tests for core behavior. | Fix immediately. |
+| **Important** | Should fix before merge. Poor naming, missing edge case tests, unclear logic, inconsistency with codebase patterns. | Fix unless you can justify why not. |
+| **Suggestion** | Nice to have. Style preferences, minor simplifications, alternative approaches. | Optional — address if they improve clarity. |
+
+Rules:
+- If you're unsure whether something is Critical or Important, make it Critical. Err on the side of strictness.
+- A finding with no file/line reference is incomplete. Always include location.
+- "This could be better" without a concrete suggestion is not a finding. Say what to change.
+
+## Output Format
+
+```
+## Code Review: [task/feature name]
+
+### Summary
+One paragraph: overall assessment, confidence level, key observations.
+
+### Critical Issues
+- [file:line] Description. Why it matters. Suggested fix.
+
+### Important Issues
+- [file:line] Description. Why it matters. Suggested fix.
+
+### Suggestions
+- [file:line] Description.
+
+### Verdict
+PASS | NEEDS FIXES | FAIL
+```
+
+**Verdict rules:**
+- **PASS**: Zero critical issues AND zero important issues. Suggestions are acceptable.
+- **NEEDS FIXES**: Has critical or important issues that are fixable without redesign.
+- **FAIL**: Fundamental problems — wrong approach, missing core functionality, security vulnerability that requires architectural change.
+
+If a section is empty, write "None" — do not omit the section.
+
+## Receiving Review Feedback
+
+When you receive review feedback (as the implementer, not the reviewer), apply these rules:
+
+### Do Not Blindly Agree
+
+Performative agreement — accepting every finding without evaluation — is worse than pushing back. It produces bad fixes, wastes time, and erodes trust.
+
+For each finding, ask:
+1. **Is this correct?** Does the finding accurately describe a real problem?
+2. **Is this important?** Even if technically valid, does it matter for this change?
+3. **Does the suggested fix make sense?** The reviewer may be right about the problem but wrong about the solution.
+
+### When to Push Back
+
+- The finding misunderstands the code (reviewer missed context)
+- The finding is technically valid but the fix would make things worse
+- The suggestion conflicts with the plan/spec — the plan wins unless the suggestion reveals a flaw in the plan
+- The finding is about style preference, not correctness or clarity
+
+Push back with reasoning, not just "I disagree." Show why the current approach is correct or why the suggested change would cause problems.
+
+### When to Accept
+
+- The finding is correct and the fix improves the code — just fix it, don't argue
+- The finding reveals something you missed — acknowledge it and fix it
+- The finding is about consistency with codebase patterns — consistency wins over personal preference
+
+### Fix Protocol
+
+1. Fix ALL critical and important issues. No negotiation on critical.
+2. Suggestions are optional but should be addressed if they improve clarity.
+3. After fixing, re-run verification (tests, linter, etc.) to ensure fixes don't break anything.
+4. If a fix introduces new concerns, flag them — don't silently create new problems.

package/skills/executing-plans/SKILL.md

@@ -0,0 +1,138 @@
+<!-- Forked from obra/superpowers (MIT license) by Jesse Vincent and Prime Radiant. Adapted for Supermind orchestrator. -->
+---
+name: executing-plans
+description: Wave-based plan execution with progress tracking and failure handling — used by orchestrator Execute phase
+injects_into: [orchestrator-execute]
+forked_from: obra/superpowers (MIT)
+---
+
+# Executing Plans
+
+## Overview
+
+Guide the orchestrator through wave-based plan execution. Coordinate executor dispatch, track progress, handle failures. Every task runs in a fresh-context subagent — the orchestrator never executes code directly.
+
+**Announce at start:** "Using executing-plans to run the implementation plan."
+
+## Execution Process
+
+### 1. Load the Plan
+
+Read the plan and task specs from `.planning/phases/phase-N/`:
+- `plans/plan.md` — the full plan with dependency graph
+- `tasks/task-N.md` — individual task specs (one per executor)
+
+Review critically before starting. If concerns exist, raise them before executing.
+
+### 2. Build the Wave Plan
+
+Use the dependency graph from the plan to group tasks into waves. Tasks with no unresolved dependencies form the current wave. Use `buildWavePlan` from `executor.js` for topological sorting.
+
+```
+Wave 1: [Task A, Task B, Task C]    <- independent, parallel
+Wave 2: [Task D (needs A), Task E]  <- D waits for A, E independent
+Wave 3: [Task F (needs D+E)]        <- depends on wave 2
+```
+
+### 3. Execute Waves
+
+For each wave:
+
+**a. Dispatch executor subagents in parallel** (one per task, up to `maxParallel`):
+- Each executor gets: task spec + injected methodology skills + completion contract
+- Use `buildTaskPacket` from `executor.js` to assemble the task packet
+- Use `executeTask` from `executor.js` to build the Agent tool invocation
+- Respect `config.json` `maxParallel` setting (default: 3)
+
+**b. Wait for all executors in the wave to complete**
+
+**c. Record results in progress.md:**
+Update `.planning/phases/phase-N/progress.md` after each task completes.
+
+| Wave | Task | Status | Commit | Notes |
+|------|------|--------|--------|-------|
+
+Use `formatWaveProgress` from `executor.js` for the Markdown table.
+
+**d. Handle failures** (see Failure Handling below)
+
+### 4. Between Waves
+
+After each wave completes, before starting the next:
+- Verify no conflicts between executor outputs (`git status`)
+- Run the test suite to catch integration issues
+- If tests fail, diagnose before proceeding to the next wave
+
+### 5. After All Waves
+
+Run full verification:
+- Complete test suite
+- Lint check (if configured)
+- Build check (if configured)
+- Compare results against the original plan's acceptance criteria
+
+## Failure Handling
+
+### Single Task Failure
+1. Spawn a debugger executor with the error context (use `fix-bug` task type for systematic-debugging skill injection)
+2. Debugger gets: original task spec + error output + relevant file state
+3. If debugger succeeds: mark task as completed, continue
+4. If debugger also fails: mark task as **failed**, continue with remaining independent tasks, report to user
+
+### Multiple Task Failures in Same Wave
+- Pause execution immediately
+- Report full status: which tasks failed, which succeeded, error details
+- Ask user for direction before continuing
+
+### Dependency Failure
+- If a task fails and other tasks depend on it: skip all dependent tasks
+- Report the cascade: "Task X failed. Skipping tasks Y, Z which depend on it."
+- Continue with any independent tasks in subsequent waves
+
+## Progress Tracking
+
+Update `.planning/phases/phase-N/progress.md` after each task completes:
+
+```markdown
+# Execution Progress
+
+**Phase:** N
+**Started:** YYYY-MM-DD HH:MM
+**Status:** in_progress | completed | blocked
+
+| Wave | Task | Status | Commit | Notes |
+|------|------|--------|--------|-------|
+| 1 | Task description | completed | abc1234 | |
+| 1 | Task description | completed | def5678 | |
+| 2 | Task description | in_progress | | |
+| 2 | Task description | pending | | |
+
+## Failures
+- [task-id]: [error summary and resolution or escalation status]
+```
+
+Valid statuses: `pending`, `in_progress`, `completed`, `failed`, `skipped`
+
+## Completion
+
+When all waves are done and verification passes:
+- Update `progress.md` status to `completed`
+- Report summary: tasks completed, tasks failed/skipped, test results
+- Hand off to the finishing-branches skill for the Ship phase
+
+## When to Stop and Ask
+
+- Multiple failures in the same wave
+- Verification reveals regressions not caused by the current changes
+- A task's acceptance criteria are ambiguous and the executor can't resolve it
+- The plan has gaps that weren't caught during planning
+
+**Ask for clarification rather than guessing.**
+
+## Key Principles
+
+- **Fresh context per task.** Every executor starts clean. The task packet must be self-contained.
+- **Never execute code in the orchestrator.** All implementation happens in subagents.
+- **Atomic commits.** Each task produces exactly one commit.
+- **Fail fast, report clearly.** Don't silently retry — surface failures with context.
+- **Respect maxParallel.** Don't launch more concurrent executors than configured.

package/skills/finishing-branches/SKILL.md

@@ -0,0 +1,144 @@
+<!-- Forked from obra/superpowers (MIT license) by Jesse Vincent and Prime Radiant. Adapted for Supermind orchestrator. -->
+---
+name: finishing-branches
+description: Ship phase — push branch, open PR, clean up worktrees. Never merges to main/master.
+injects_into: [orchestrator-ship]
+forked_from: obra/superpowers (MIT)
+---
+
+# Finishing Branches
+
+## Overview
+
+Handle the Ship phase — push the feature branch, open a PR, and clean up worktrees. The orchestrator picks the appropriate option based on context.
+
+**Core principle:** Verify tests -> Choose option -> Execute -> Clean up.
+
+**Announce at start:** "Using finishing-branches to complete this work."
+
+## Step 1: Verify Tests
+
+Before anything else, run the project's test suite:
+
+```bash
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:** Stop. Do not proceed. Report failures and fix them first.
+
+**If tests pass:** Continue to Step 2.
+
+## Step 2: Choose Option
+
+The orchestrator picks one of three options:
+
+### Option A: Create PR (default for Ship phase)
+
+Push the feature branch and open a pull request.
+
+```bash
+# Push feature branch to remote
+git push -u origin <branch>
+```
+
+```bash
+# Open PR with summary from .planning/
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<bullets: what was built, tasks completed>
+
+## Test Results
+<test suite output summary>
+
+## Tasks Completed
+<from .planning/phases/phase-N/progress.md>
+EOF
+)"
+```
+
+- PR description auto-generated from `.planning/` state
+- Never set auto-merge — user merges manually
+- Clean up worktrees after PR is created (Step 3)
+
+### Option B: Keep Branch
+
+Keep the branch for continued work later.
+
+```bash
+# Stage and commit known files (avoid git add -A to prevent staging sensitive files)
+git add <known-files> && git commit -m "wip: <description>"
+```
+
+- Report branch name and current status
+- Leave worktrees intact — do NOT clean up
+- Report: "Keeping branch `<name>`. Worktree preserved at `<path>`."
+
+### Option C: Discard
+
+Throw away the work. **Requires explicit user confirmation.**
+
+```
+This will permanently delete:
+- Branch: <name>
+- All commits since branching
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact typed confirmation before proceeding.
+
+If confirmed:
+```bash
+git checkout <originating-branch>
+git branch -D <feature-branch>
+```
+
+Clean up worktrees after deletion (Step 3).
+
+## Step 3: Worktree Cleanup
+
+**For Options A and C only** (not B):
+
+```bash
+# Remove each worktree used during execution
+git worktree remove .worktrees/<name>
+
+# Prune stale worktree references
+git worktree prune
+
+# Delete merged worktree branches
+git branch -d worktree/<name>
+```
+
+## Safety Rules
+
+These are non-negotiable:
+
+- **NEVER merge to main/master.** The PR is the integration mechanism.
+- **NEVER force push.** No `--force`, no `--force-with-lease` unless the user explicitly requests it.
+- **NEVER set auto-merge** on the PR.
+- **Always verify tests** before offering any option.
+- **Always get typed confirmation** for Option C (discard).
+
+## Quick Reference
+
+| Option | Push | PR | Keep Worktree | Cleanup Branch |
+|--------|------|------|---------------|----------------|
+| A. Create PR | yes | yes | no | no (PR branch) |
+| B. Keep Branch | no | no | yes | no |
+| C. Discard | no | no | no | yes (force) |
+
+## Red Flags
+
+**Never:**
+- Proceed with failing tests
+- Merge to main/master
+- Delete work without typed confirmation
+- Force-push without explicit user request
+
+**Always:**
+- Verify tests first
+- Generate PR description from `.planning/` state
+- Clean up worktrees for Options A and C
+- Preserve worktrees for Option B