supermind-claude 2.1.1 → 4.0.2

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,169 @@
+<!-- Forked from obra/superpowers (MIT license) by Jesse Vincent and Prime Radiant. Adapted for Supermind orchestrator. -->
+---
+name: writing-plans
+description: Creates atomic implementation plans with dependency graphs — used by orchestrator Plan phase
+injects_into: [orchestrator-plan]
+forked_from: obra/superpowers (MIT)
+---
+
+# Writing Plans
+
+## Overview
+
+Create granular, atomic implementation plans with dependency graphs. Each task is a self-contained work unit completable by a fresh-context executor in 2-5 minutes.
+
+Over-specify rather than under-specify. Executors get fresh context — they don't know what you know. Include exact file paths, function names, line numbers, and code snippets.
+
+**Announce at start:** "Using writing-plans to create the implementation plan."
+
+## Input
+
+Read the design from `.planning/phases/phase-N/discussion.md` (output of brainstorming). If no discussion file exists, read the user's requirements directly.
+
+## Scope Check
+
+If the design 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.
+
+## File Structure
+
+Before defining tasks, map out which files will be created or modified and what each one is responsible for.
+
+- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
+- Prefer smaller, focused files over large ones that do too much.
+- Files that change together should live together. Split by responsibility, not by technical layer.
+- In existing codebases, follow established patterns.
+
+This structure informs the task decomposition.
+
+## Task Spec Format
+
+Each task in the plan uses this format:
+
+```markdown
+---
+id: task-N
+type: write-feature|fix-bug|refactor|write-test|research
+dependsOn: [task-ids]
+---
+
+## Task: [descriptive name]
+
+### What to do
+[Clear, specific instructions — not vague directions]
+
+### Files to read first
+- `path/to/file.js` — reason why this file matters for context
+
+### Files to modify/create
+- `path/to/file.js` — what changes to make
+
+### Acceptance criteria
+- [ ] [specific, verifiable criterion]
+- [ ] [another criterion]
+
+### Verification
+- [exact command to run to prove it works]
+- [expected output]
+```
+
+## Task Granularity
+
+Each task should be:
+- **Completable in 2-5 minutes** by an executor with fresh context
+- **Self-contained** — the task spec has everything needed (files to read, what to change, acceptance criteria)
+- **Independently testable** — each task has verification steps
+- **Small enough** that an executor can hold the full context in one pass
+
+**Example bite-sized steps within a task:**
+- "Write the failing test" — one step
+- "Implement the minimal code to make it pass" — one step
+- "Run tests and verify" — one step
+- "Commit" — one step
+
+## No Placeholders
+
+Every task must contain the actual content an executor needs. These are **plan failures** — never write them:
+- "TBD", "TODO", "implement later", "fill in details"
+- "Add appropriate error handling" / "add validation" / "handle edge cases"
+- "Write tests for the above" (without actual test code)
+- "Similar to Task N" (repeat the content — executors may read tasks out of order)
+- Steps that describe what to do without showing how (code blocks required for code steps)
+- References to types, functions, or methods not defined in any task
+
+## Methodology Injection
+
+Each task should specify which methodology skills apply based on its type:
+- `write-feature` or `write-test` tasks: TDD (red-green-refactor)
+- `fix-bug` tasks: systematic-debugging (REPRODUCE-ISOLATE-FIX-VERIFY)
+- All tasks: verification-before-completion, anti-rationalization
+
+## Planning Process
+
+1. **Read the design** from `discussion.md` or user requirements
+2. **Map file structure** — which files will be created or modified
+3. **Decompose into atomic tasks** following the task spec format above
+4. **Identify dependencies** between tasks (task B needs task A's output)
+5. **Arrange into a dependency graph** — tasks with no dependencies form Wave 1, tasks depending on Wave 1 form Wave 2, etc.
+6. **Plan-checker pass** (max 3 iterations):
+   - Does each task have clear acceptance criteria?
+   - Are dependencies correctly identified?
+   - Can each task be completed with only its task spec?
+   - Are there circular dependencies? (reject if so)
+   - Does the full set of tasks implement the complete design?
+   - Are there placeholder violations? (see No Placeholders above)
+   - Do types, method signatures, and names stay consistent across tasks?
+7. **Save the plan** to `.planning/phases/phase-N/plans/plan.md`
+8. **Save individual task specs** to `.planning/phases/phase-N/tasks/task-N.md` (one file per task)
+
+## Plan Document Header
+
+Every plan starts with:
+
+```markdown
+# [Feature Name] Implementation Plan
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Files affected:** [List of files created/modified]
+
+**Dependency graph:**
+Wave 1: [task-1, task-2]  <- independent, parallel
+Wave 2: [task-3 (needs task-1)]  <- sequential dependency
+Wave 3: [task-4 (needs task-2, task-3)]
+
+---
+```
+
+## Self-Review
+
+After writing the complete plan, review with fresh eyes:
+
+1. **Spec coverage:** Skim each requirement. Can you point to a task that implements it? List any gaps.
+2. **Placeholder scan:** Search for red flags from the No Placeholders section. Fix them.
+3. **Type consistency:** Do the types, method signatures, and property names used in later tasks match what was defined in earlier tasks?
+4. **Dependency completeness:** Does every task that reads a file created by another task list that dependency?
+5. **Test coverage:** Are tests distributed throughout the plan, not bunched at the end?
+
+If you find issues, fix them inline. If you find a requirement with no task, add the task.
+
+## Output
+
+After saving the plan and task specs:
+
+```
+Plan complete:
+- Plan: .planning/phases/phase-N/plans/plan.md
+- Tasks: .planning/phases/phase-N/tasks/task-{1..N}.md
+- Waves: [count] waves, [count] tasks total
+- Ready for execution via executing-plans skill
+```
+
+## Key Principles
+
+- **Over-specify.** Executors get fresh context. They don't know what you know.
+- **Include exact file paths**, function names, line numbers where relevant.
+- **Include code snippets** in the task spec if the approach is specific.
+- **Plan for testing throughout** — don't leave all tests to the end.
+- **DRY, YAGNI, TDD, frequent commits.**

package/templates/CLAUDE.md

@@ -8,7 +8,10 @@
 ## Commands
 <!-- Fill in or run /supermind-init to auto-detect -->
 ```bash
-# npm run dev / start / build / test etc.
+# npm run dev      — start development server
+# npm run build    — production build
+# npm test         — run test suite
+# npm run lint     — lint source files
 ```
 
 ## Tech Stack
@@ -19,85 +22,144 @@
 
 ## Shell & Git Permissions
 
-A PreToolUse hook (`bash-permissions.js`) handles all Bash permission classification automatically. It parses compound commands, splits on `&&`/`||`/`;`, and classifies each segment. You do not need to worry about permission prompts for safe commands — the hook handles it.
+A PreToolUse hook (`bash-permissions.js`) classifies every Bash command automatically. It parses compound commands and splits on `&&`/`||`/`;` before classifying each segment individually. Most commands run without any prompt. Only the categories below are banned outright or require explicit approval.
 
-**Auto-approved** (standalone or in any compound):
-- **Read-only shell**: ls, cat, head, tail, find, sed (without -i), grep, echo, pwd, jq, etc.
-- **Safe writes**: mkdir, touch, cp, mv
-- **Utilities**: base64, claude CLI (config/mcp/plugin subcommands)
-- **Read-only git**: status, diff, log, show, blame, rev-parse, check-ignore, branch listing, tag listing, config (read-only: --get, --list)
-- **Non-destructive git writes**: add, commit, stash (bare/push/save/list/show), worktree add, worktree list, branch create, branch rename
-- **gh CLI**: read-only gh commands (pr list/view/diff, issue list/view, repo view, gh api GET — not merge, close, delete, or mutating API calls)
+**Banned — always requires approval:**
+- `rm`, `rmdir`, `del` — destructive file removal
+- Any command using `--force` or `--hard` flags (regardless of the base command)
+- Destructive git operations: `push` (to remote), `pull`, `fetch`, `reset`, `revert`, `rebase`, `clean`, `checkout` (when used to discard changes), `restore`, `branch -D`
+- Destructive stash operations: `stash drop`, `stash pop`, `stash clear`
+- GitHub mutations: `gh pr merge`, `gh pr close`, `gh issue close`, `gh repo delete`, `gh release create`, `gh release delete`, any mutating `gh api` call (non-GET)
+- `npm publish` — publishing to the registry always requires human confirmation
 
-**Worktree-only** (auto-approved only when `cd` targets a `.worktrees/` path or CWD is inside one):
-- git merge, git worktree remove, git worktree prune, git branch -d
+**Worktree-only** (auto-approved only when CWD is inside `.worktrees/`):
+- `git merge` — merging back from a feature worktree
+- `git worktree remove` — cleaning up a worktree directory
+- `git worktree prune` — pruning stale worktree entries
+- `git branch -d` — deleting a merged branch after cleanup
 
-**Always requires approval**:
-- push, pull, fetch, reset, revert, rebase, clean, checkout (discarding), restore, branch -D
-- stash drop, stash pop, stash clear (destructive stash operations)
-- Any command with --force or --hard
-- rm, rmdir, del
+In all other contexts, these four commands still require user approval.
 
-**User-approved commands**: The file `~/.claude/supermind-approved.json` contains commands the user has permanently approved. If asked to approve a command permanently, edit this file to add the command string. Manage via `npx supermind-claude approve "command"`.
+**Everything else is auto-approved:**
+- Read-only shell: `ls`, `cat`, `head`, `tail`, `find`, `grep`, `sed` (without `-i`), `awk`, `echo`, `pwd`, `jq`, `wc`, `sort`, `uniq`, etc.
+- Safe writes: `mkdir`, `touch`, `cp`, `mv`
+- Utilities: `base64`, `curl` (read), `node`, `npx`, `claude` CLI (config/mcp/plugin subcommands)
+- Read-only git: `status`, `diff`, `log`, `show`, `blame`, `rev-parse`, `check-ignore`, branch listing, tag listing, `config --get`/`--list`
+- Non-destructive git writes: `add`, `commit`, `stash push`/`save`/`list`/`show`, `worktree add`, `worktree list`, branch create, branch rename, `tag` (local)
+- gh read-only: `pr list`/`view`/`diff`, `issue list`/`view`, `repo view`, `gh api` GET requests, `gh run view`
 
-Compound commands with `&&`, `||`, `;` and pipes are fully supported — no need to split into separate calls.
+**User overrides**: `~/.claude/supermind-approved.json` contains commands permanently approved by the user. If asked to approve a command permanently, add the command string to that file. Manage via `supermind approve "command"`.
 
-## Worktree Development Workflow
+Compound commands with `&&`, `||`, `;`, and pipes are fully supported — no need to split into separate calls.
 
-When implementing changes beyond a trivial edit, use a worktree. The bar is low — if it touches more than 2-3 files, involves logic changes, or follows an implementation plan, it goes through a worktree.
+## Subagent Strategy
 
-Always use **subagent-driven development** for implementation.
+Always use **subagent-driven development** for implementation work. This means spawning multiple parallel subagents to execute independent tasks instead of running everything in a single thread.
 
-### Setup
+**Task granularity:** Each subagent task should touch at most 3 files. Larger tasks must be decomposed into smaller, independent pieces before dispatch. Smaller tasks are easier to parallelize, easier to review, and produce cleaner commit history.
 
-Use the superpowers `/using-git-worktrees` skill for worktree creation. It handles:
-- Directory selection (`.worktrees/` preferred, already configured)
-- `.gitignore` safety verification (adds entry + commits if missing)
-- Dependency installation (auto-detects package.json, Cargo.toml, etc.)
-- Baseline test verification (reports failures before work begins)
+**Parallelism:** Prefer 10 parallel subagents over 3 sequential ones. Any tasks that share no state and have no ordering dependency must run in parallel. Never serialize work that can parallelize — the goal is minimum wall-clock time, not minimum subagent count. If you find yourself writing "then do X, then do Y, then do Z" for three unrelated changes, those should be three parallel subagents.
 
-**Constraint:** The skill must branch from `HEAD` (the current local branch), never from a remote ref.
+**Milestone decomposition:** If an implementation plan has more than 8 tasks, split into milestones before starting. Each milestone is a coherent, independently committable unit of work. Run all tasks within a milestone in parallel, then review, commit, and advance to the next milestone. Do not start milestone N+1 until milestone N is committed and clean.
 
-### Process (runs fully autonomously — no approval needed at any step)
+**Autonomy:** Subagents execute without stopping to ask for permission. If a subagent hits a blocker that genuinely cannot be resolved by reading the codebase or making a reasonable judgment call, surface it — but most uncertainty should be resolved autonomously.
 
-1. **Create worktree** — invoke `/using-git-worktrees` as described above
-2. **Implement** all changes in the worktree directory using subagent-driven development
-3. **Commit** all work in the worktree
-4. **Review** — run the superpowers `code-reviewer` agent against the changes
-5. **Fix everything** — address ALL issues found by the reviewer (critical, minor, style, naming — everything). Do not ask what to fix. Fix all of them. Then re-review until the reviewer passes clean.
-6. **Living docs check** — before merging, check if the changes affect anything documented in ARCHITECTURE.md (or DESIGN.md). For each changed file, verify that any claims the docs make about that file's behavior, constants, or patterns are still accurate. If updates are needed, make them and commit in the worktree branch.
-7. **Finish** — invoke `/finishing-a-development-branch` to merge back and clean up. The skill handles:
-   - Merging the worktree branch into the originating branch
-   - Removing the worktree directory
-   - Deleting the temporary branch
+**What counts as independent:** Two tasks are independent if neither reads a file the other writes, they do not share mutable in-memory state, and their commit order does not matter for correctness. When in doubt, run them in parallel — conflicts in parallel commits are far cheaper to resolve than the time lost to needless serialization.
 
-### Rules
+## Development Lifecycle
 
-- The worktree branch must always be created from and merged back into the **same branch** — the one you are currently on locally. Never merge into a different branch.
-- `git merge`, `git worktree remove`, `git worktree prune`, and `git branch -d` are auto-approved **only** within this worktree workflow. In all other contexts, these still require user approval.
-- The code reviewer must find zero remaining issues before merging. If it finds problems, fix them and run the reviewer again. Repeat until clean.
-- Never skip the review step. Never skip "minor" fixes. Every finding gets fixed.
-- This entire process — create, implement, review, fix, merge, clean up — executes without stopping to ask for permission.
-- **Branch safety:** If the current branch is `main` or `master` when a code change is requested, create a feature branch first (`feature/…`, `fix/…`, or `chore/…`) before making any changes. Never commit directly to `main` or `master`.
+This entire lifecycle executes autonomously — no stopping to ask for permission at any step. The user receives one summary when the lifecycle is complete.
 
-## MCP Servers
-Use these naturally when relevant — don't wait to be asked.
+**Branch safety:** If the current branch is `main` or `master` when a code change is requested, create a feature branch first (`feature/…`, `fix/…`, or `chore/…`) before making any changes. Never commit directly to `main` or `master`.
 
-- **Magic MCP** — `component_builder`, `component_inspiration`, `component_refiner`, `logo_search` — use when building/refining UI components
-- **Airis Gateway** (Docker, localhost:9400) — cold-start sub-servers:
-  - **context7** — Library docs lookup
-  - **playwright** — Browser automation/testing
-  - **serena** — Symbolic code navigation (run `activate_project` on first use)
-  - **tavily** — Web search/research
-  - **chrome-devtools** — Chrome debugging
-  - **shadcn** — shadcn/ui component search
+**Lifecycle overview:**
+1. Setup — branch + worktree + deps + baseline
+2. Design & Plan — read docs, spec or brainstorm, milestone plan
+3. Implementation — parallel subagents, milestone commits
+4. Test & Verify — tests + code review + fix everything + re-review
+5. Pre-merge — update docs, version bump, changelog
+6. Merge — merge to originating branch, clean up worktree
+
+### Phase 1 — Setup
+- Verify the current branch is not `main`/`master`; create a feature branch if it is
+- Invoke `/using-git-worktrees` to create an isolated worktree in `.worktrees/`
+  - The skill verifies `.gitignore` safety and adds an entry if missing
+  - It installs dependencies automatically (detects package.json, Cargo.toml, pyproject.toml, etc.)
+  - It reports baseline test results before work begins
+- Branch must be created from the current local `HEAD`, never from a remote ref
+- Do not proceed if baseline tests are broken — surface failures first
+
+### Phase 2 — Design & Plan
+- Read `ARCHITECTURE.md` and `DESIGN.md` to understand existing patterns, conventions, and constraints before proposing any approach
+- **Complex changes** — new subsystem, cross-cutting refactor, ambiguous requirements, or significant design tradeoffs: invoke `/brainstorming` to explore the design space, then write a milestone-based implementation plan; do not start implementation until the plan is reviewed
+- **Simple changes** — clear, contained requirements with no meaningful design decisions open: invoke `/brainstorming` to quickly explore the approach, then write a milestone-based implementation plan
+- If the plan exceeds 8 tasks, decompose into milestones now — not during implementation
+
+### Phase 3 — Implementation
+- Execute using the Subagent Strategy: spawn parallel subagents for all independent tasks within a milestone
+- Commit at each milestone boundary with a descriptive commit message that explains why the change was made, not just what changed
+- Do not advance to the next milestone before the current one is committed
+- Do not implement beyond the written plan without flagging the addition
+
+### Phase 4 — Test & Verify
+- Run the full test suite; fix all failures before proceeding — do not leave failing tests as "known issues"
+- Invoke the `code-reviewer` agent against all changes in the branch
+- Fix **every** finding — critical, important, minor, style, naming, and suggestions. Do not ask which to fix. Fix everything.
+- Re-run the reviewer after applying fixes. Repeat until the reviewer returns zero findings.
+- Never skip the review step. Never defer "minor" fixes. Every finding is addressed before moving on.
+
+### Phase 5 — Pre-merge
+- Compare `ARCHITECTURE.md` and `DESIGN.md` against every changed file; update any stale claims about behavior, constants, file layout, APIs, data models, or environment variables
+- Bump the version following semver: patch for bug fixes, minor for new features, major for breaking changes to public interfaces
+- Update `CHANGELOG.md` with a concise summary of what changed and why
+- Commit all pre-merge updates (docs, version, changelog) in the worktree branch
+
+### Phase 6 — Merge
+- Invoke `/finishing-a-development-branch` to merge back and clean up
+- The skill merges the worktree branch into the **originating branch only** — the branch that was active in Phase 1. Never merge into a different branch.
+- The skill removes the worktree directory and deletes the temporary branch
+- Confirm the merge succeeded and the working tree is clean before reporting done
+
+## Vendor Skills
+
+Supermind skills extend Claude Code with reusable, versioned behaviors. Skills live in `~/.claude/skills/` and are invoked with `/skill-name` during a session. Install and manage them with the `supermind` CLI:
+
+```bash
+supermind skill add <github-url>          # Install a skill (project-local by default)
+supermind skill add <github-url> --global # Install a skill globally
+supermind skill update [name]             # Update a specific skill
+supermind skill update --all              # Update all installed skills to latest versions
+supermind skill list                      # List all installed skills and their current versions
+supermind skill remove <name>             # Uninstall a skill and remove it from skills-lock.json
+```
+
+Installed skills and their pinned versions are recorded in `~/.claude/skills-lock.json`. Commit `skills-lock.json` to your repository to share the exact skill set with your team and ensure consistent behavior across all machines.
+
+{{MCP_SECTION}}
 
 ## UI Changes
-- When making any UI/frontend changes, invoke the `/ui-ux-pro-max` skill for design guidance and quality checks.
+
+When making any UI/frontend changes, invoke the `/ui-ux-pro-max` skill for design guidance and quality checks before finalizing the implementation.
+
+The skill provides:
+- Design token and color palette validation
+- Typography and spacing consistency checks
+- Component accessibility review
+- Responsive behavior assessment
+- Recommendations aligned with the project's existing design language
+
+Do not ship UI changes without running this skill. Design quality is a first-class concern, not a post-implementation polish step.
 
 ## Living Documentation
-- The session-start hook automatically reads `ARCHITECTURE.md` and `DESIGN.md` (if it exists) at the beginning of every conversation.
-- After code changes, update `ARCHITECTURE.md` if files, APIs, dependencies, or environment variables changed.
-- After design/UI changes, update `DESIGN.md` if colors, fonts, spacing, or components changed.
-- Run `/supermind-living-docs` to manually sync documentation with recent changes.
-- If `ARCHITECTURE.md` is missing, run `/supermind-init` to create one.
+
+Living documentation means `ARCHITECTURE.md` and `DESIGN.md` stay accurate as the code evolves. They are not written once and forgotten — they are updated as part of every development lifecycle.
+
+**Automatic loading:** The session-start hook reads `ARCHITECTURE.md` and `DESIGN.md` at the start of every conversation so Claude always has current context without being asked.
+
+**When to update `ARCHITECTURE.md`:** After any code change that affects file layout, module responsibilities, public APIs, environment variables, configuration schema, external dependencies, or build/deploy steps.
+
+**When to update `DESIGN.md`:** After any UI/design change that affects the color palette, typography, spacing scale, component library, layout patterns, or interaction conventions.
+
+**Manual sync:** Run `/supermind-living-docs` at any time to audit both documents against recent changes and update anything stale.
+
+**Bootstrap:** If `ARCHITECTURE.md` is missing, run `/supermind-init` to generate it from the current codebase. This also creates `DESIGN.md` if the project has a UI layer.

package/cli/lib/plugins.js

@@ -1,23 +0,0 @@
-'use strict';
-
-function getPluginDefaults() {
-  return {
-    enabledPlugins: {
-      'superpowers@claude-plugins-official': true,
-      'claude-md-management@claude-plugins-official': true,
-      'frontend-design@claude-plugins-official': true,
-      'ui-ux-pro-max@ui-ux-pro-max-skill': true,
-      'pr-review-toolkit@claude-plugins-official': true,
-      'security-guidance@claude-plugins-official': true,
-      'elements-of-style@superpowers-marketplace': true,
-    },
-    extraKnownMarketplaces: {
-      'ui-ux-pro-max-skill': {
-        source: { source: 'github', repo: 'nextlevelbuilder/ui-ux-pro-max-skill' },
-      },
-      // superpowers-marketplace is a built-in Claude Code marketplace — no source config needed
-    },
-  };
-}
-
-module.exports = { getPluginDefaults };