superpowers-mcp 6.3.2 → 6.3.4

package/README.md

@@ -2,34 +2,93 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![Version](https://img.shields.io/badge/version-6.3.2-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.3.4-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-This document summarizes the information and usage instructions for packaging the original Superpowers skills library into an independent MCP Toolpack.
+This document summarizes the information and usage instructions for packaging the Superpowers skills and autonomous workflow system into an independent, high-performance, and secure **Model Context Protocol (MCP)** server.
 
 ---
 
 ## 🚀 How to Install and Use
 
-### Supported Environments
+### Supported Environments & Harnesses
 
-**Antigravity**, **Cursor**, **VSCode**, and other AI editors that support the MCP toolchain.
+- **AI Code Editors & IDEs**: **Antigravity (AGY)**, **Cursor**, **VSCode** (GitHub Copilot), **Devin Desktop**, **MiniMax Code Desktop**, **Codex**.
+- **AI Desktop Applications & Harnesses**: **Hermes Desktop**, **Kimi Work**.
+- **Local & Self-Hosted AI Platforms**: **AnythingLLM**, **LibreChat**.
 
-### Chatting with the AI Agent
+### MCP Capabilities Provided
 
-Once installed or configured, your AI Agent (such as Copilot or Antigravity Cascade) will be able to recognize the `Superpowers Skills`.
+| Protocol Feature | Items / Count | Description |
+| :--- | :--- | :--- |
+| **Tools** | `list_skills`, `read_skill` | Discover, search, and load full skill instructions and checklists on demand. |
+| **Prompts** | 9 Native Prompts | `session-start`, `feature-pipeline`, `structured-debug`, `skill-composition`, `sdd-implementer`, `sdd-task-reviewer`, `sdd-re-review`, `spec-reviewer`, `plan-reviewer` |
+| **Resources** | 14 Direct Skill URIs | `skill://superpowers/<skill-name>` (Standard direct URI access) |
+
+### Chatting with the AI Agent (Basic Usage)
 
-**You can ask things like:**
+Once installed or configured, your AI Agent will automatically discover and invoke `Superpowers Skills` and `Prompts`.
 
-- "List all superpowers skills"
-- "Use read_skill to read the brainstorming skill, and then help me analyze the implementation of this feature"
-- "Apply the session-start prompt" (Simulates the original startup injection mechanism)
+**Basic Interaction Examples:**
+- **Initialize Engineering Discipline:** "Apply `session-start` prompt" (Injects Superpowers rules & context)
+- **Discover Available Skills:** "List all superpowers skills"
+- **Load an Atomic Skill:** "Use `read_skill` to load the `brainstorming` skill and help me explore requirements"
 
 ---
 
-## 🛠️ MCP Configuration
+## ⚡ Targeted One-Click Setup
+
+To get up and running with Superpowers instantly without intrusive background modifications, use our **targeted, privacy-respecting** one-click setup tool.
+
+> [!NOTE]
+> **Run From Any Directory**: You do NOT need to clone this repository or navigate to a specific folder. You can execute these commands directly from **any directory** in your terminal. The installer automatically targets global configuration files rooted in your user home directory (`~`), instantly enabling Superpowers across all your workspaces.
+
+> [!TIP]
+> **Transparency & Zero-Pollution Principle**: Superpowers will NEVER silently scan or bulk-modify unselected editors like adware. You explicitly choose the client you use, ensuring 100% transparent and safe modification via **atomic write swap** (zero crash risk, **zero disk pollution by default** without dumping `.bak` files, zero impact on your existing MCP servers).
+
+### 1. Choose Your AI Agent / Editor (Targeted One-Liner)
+
+Select your client and run the corresponding command in your terminal:
+
+| Harness / Client | Supported OS | One-Click Setup Command | Global Config Location |
+| :--- | :--- | :--- | :--- |
+| **Antigravity (Google DeepMind)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target antigravity` | `~/.gemini/config/mcp_config.json` |
+| **Pi Desktop / Pi Agent** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target pi-desktop` | `~/.pi/agent/mcp.json` |
+| **Cursor** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target cursor` | `~/.cursor/mcp.json` |
+| **GitHub Copilot (VS Code)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target copilot` | `Code/User/mcp.json` *(VS Code `servers` schema)* |
+| **Hermes Desktop / Agent** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target hermes` | `~/.hermes/config.yaml` *(Win: `%LOCALAPPDATA%\hermes`)* |
+| **Kimi Work / Kimi Code** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target kimi` | `~/.kimi-code/mcp.json` |
+| **Claude Desktop** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target claude` | `Claude/claude_desktop_config.json` |
+| **Devin Desktop (formerly Windsurf)** | macOS / Windows / Linux | `npx -y superpowers-mcp setup --target devin` | `~/.config/devin/mcp_config.json` *(or `windsurf`)* |
+
+*(If using Bun, append `--bun` for faster startup, e.g., `npx -y superpowers-mcp setup --target cursor --bun`)*
+
+---
+
+### 2. Setup via Curl or PowerShell
+
+- **macOS / Linux (via Curl with explicit target):**
+  ```bash
+  curl -fsSL https://raw.githubusercontent.com/Poseidoncode/superpowers-mcp/main/scripts/install.sh | bash -s -- --target cursor
+  ```
+
+- **Windows (via PowerShell with explicit target):**
+  ```powershell
+  & ([scriptblock]::Create((irm https://raw.githubusercontent.com/Poseidoncode/superpowers-mcp/main/scripts/install.ps1))) -Target cursor
+  ```
+
+#### Advanced Flags:
+- `--dry-run`: Preview changes without writing to disk.
+- `--remove`: Safely remove Superpowers configuration from the targeted client.
+- `--backup`: Create a timestamped `.bak` backup before modifying (Default: disabled, zero-pollution).
+- `--bun`: Use `bunx` instead of `npx` in the generated configuration.
+- `--target <name>`: Explicit target name (aliases supported, e.g. `code`, `vscode`, `kimi-code`).
+
+---
 
-Add the following settings to your IDE (e.g., Cursor, Antigravity, or VSCode MCP settings). 
+## 🛠️ Manual MCP Configuration
+
+If you prefer configuring manually, add the following settings to your IDE or MCP client (e.g., Cursor, Antigravity, VSCode, AnythingLLM, etc.).
 
 ### Method : NPX / BUNX (Recommended)
 
@@ -57,234 +116,96 @@ This is the easiest way as it handles path resolution automatically.
 
 ---
 
-## 💡 Common Skills & Scenarios
+## 🔄 Skill Compositions & Workflow Pipelines
 
-| Skill Name | Community Recommended Scenario | Core Value |
-| :--- | :--- | :--- |
-| `brainstorming` | Before starting a new feature, exploring requirements and design. | Prevents the AI from jumping straight into writing code. |
-| `writing-plans` | Before multi-file refactoring or complex migrations. | Establishes a clear execution blueprint. |
-| `systematic-debugging` | When encountering any errors or abnormal behavior. | Enforces "root cause analysis" instead of guessing. |
-| `test-driven-development` | When implementing logically challenging features. | Ensures code is accompanied by tests, achieving Red-Green-Refactor. |
-| `verification-before-completion` | Before claiming "it's fixed" or "it's done". | Evidence-based completion confirmation. |
+For complex, multi-step engineering tasks, use these **one-click end-to-end pipelines** where the AI guides you step-by-step (see detailed guide: [`docs/skill-compositions.md`](docs/skill-compositions.md)):
 
----
+### 1. New Feature Development Pipeline
+```
+brainstorming ➔ writing-plans ➔ using-git-worktrees ➔ subagent-driven-development (TDD) ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
+```
+- **One-Click Command:** "Please apply `feature-pipeline` to build [Feature Name]"
+- **Workflow:** Clarifies requirements (Spec) ➔ Decomposes plan ➔ Isolates worktree ➔ Implements via fresh subagents & TDD ➔ Runs full test suite ➔ Conducts code review ➔ Finishes branch.
 
-## 🔄 Recommended Prompt Sequences
+### 2. Structured Troubleshooting Pipeline
+```
+systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔ test-driven-development ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
+```
+- **One-Click Command:** "Please apply `structured-debug` to investigate this error: [Paste Trace / Logs]"
+- **Workflow:** Hypothesizes root causes ➔ Isolates worktrees for parallel agents ➔ Authors failing reproduction tests ➔ Applies targeted fix ➔ Confirms zero regressions ➔ Reviews fix ➔ Finishes branch.
 
-### 1. New Feature Development Sequence
-1. "Read the brainstorming skill to confirm requirements and architecture."
-2. "Read the writing-plans skill to create an execution plan with specific steps."
-3. "Read the test-driven-development skill to implement the feature with tests."
-4. "Read the verification-before-completion skill to run test suites and ensure everything works."
+### 3. Dynamic Workflow Guide
+- **One-Click Command:** "Please apply `skill-composition` for [Refactoring / Migration / Legacy Codebase]"
+- **Workflow:** Dynamically recommends the optimal multi-skill composition for large refactors, migration safety nets, or onboarding:
+  - **Large Refactoring & Migration:** `brainstorming` ➔ `writing-plans (skeleton-first)` ➔ `using-git-worktrees` ➔ `subagent-driven-development` ➔ `verification-before-completion` ➔ `requesting-code-review` ➔ `finishing-a-development-branch`
+  - **Legacy Codebase Safety Net:** `brainstorming` ➔ `writing-plans` ➔ `test-driven-development (characterization)` ➔ `systematic-debugging` ➔ `verification-before-completion`
 
-### 2. Emergency Hotfix Sequence
-1. "Read the systematic-debugging skill to locate the root cause of the current issue."
-2. "Read the test-driven-development skill to write a failing test for the bug and fix it."
-3. "Read the verification-before-completion skill to validate the applied hotfix."
 
 ---
 
-## 📋 Supported Skills Overview (14 Total)
-
-To help you choose the right skill, we've categorized them into 6 logical phases of software development:
-
-### 🚀 1. Planning & Design
-- `brainstorming`: Software design and requirements analysis process
-  - Visual Companion for browser-based mockups and design reviews (just-in-time)
-- `writing-plans`: Creating detailed implementation plans
-
-### 💻 2. Implementation & Debugging
-- `executing-plans`: Executing created implementation plans
-- `test-driven-development`: TDD (Test-Driven Development) workflow
-- `systematic-debugging`: Systematic debugging and root cause analysis
-
-### 🛡️ 3. Quality & Review
-- `verification-before-completion`: Evidence-based verification before completion
-- `requesting-code-review`: Initiating pre-checks for code reviews
-- `receiving-code-review`: Receiving and addressing code review feedback
-- `finishing-a-development-branch`: Finalizing and integrating feature branches
-
-### 🌿 4. Version Control
-- `using-git-worktrees`: Managing multiple branches using Git Worktrees
-
-### 🤖 5. Advanced Agent Controls
-
-These skills are designed for orchestrating complex meta-execution patterns within supported IDEs (like Antigravity or Cursor).
-
-- **`subagent-driven-development`**: Driving sub-agents to execute tasks
-  - **Usage**: Used to execute a predefined plan task-by-task. The system spawns a fresh "implementer" sub-agent per task, followed by a consolidated **task reviewer** (spec compliance + code quality) sub-agent, plus a **whole-branch final review** at the end. A **Pre-Flight Plan Review** scans for task conflicts before execution begins. Plans run in plan-scoped workspaces (`.superpowers/sdd/<plan>/`), the controller rules on conflicts and records them in the ledger instead of stopping, and small same-shape tasks are batched into a single dispatch.
-  - **Model Selection**: Choose sub-agent models based on task complexity — cheaper models for mechanical work, capable models for architecture and subtle concurrency changes.
-  - **Example**: "Read the subagent-driven-development skill, then execute the tasks listed in docs/plans/feature-plan.md one by one."
-- **`dispatching-parallel-agents`**: Dispatching tasks to parallel agents
-  - **Usage**: Used for tackling multiple *independent* issues (e.g., 3 unrelated failing tests or 3 separate web research topics). The AI will adopt a parallel-execution mindset, addressing each task independently without crossing state or experiencing context pollution, significantly speeding up output generation.
-  - **Debugging Example**: "Read the dispatching-parallel-agents skill, then dispatch 3 parallel agents to investigate the independently failing tests A, B, and C."
-  - **Research Example**: "Read the dispatching-parallel-agents skill, then search the web for React 19 features, Vue 3.5 updates, and Svelte 5 Runes in parallel — summarize each independently."
-
-### ⚙️ 6. Customization & Meta
-- `using-superpowers`: Guidelines and self-checks for using Superpowers
-- `writing-skills`: Writing and expanding new custom skills
+## 📋 Supported Skills Overview (14 Core Skills & Scenarios)
+
+To help you choose the right skill, we have structured all 14 skills across the Software Development Lifecycle (SDLC), merging core capabilities and community-recommended scenarios:
+
+| # | SDLC Phase | Skill Name | What It Does (Purpose & Core Value) | Recommended Scenario |
+| :-: | :--- | :--- | :--- | :--- |
+| 1 | **🚀 Planning & Design** | **`brainstorming`** | **Requirements & Architecture Design**: Explores options and constraints before coding; outputs Design Specs; includes Visual Companion browser UI review. | Before starting any new feature or major change; prevents jumping straight into code. |
+| 2 | **🚀 Planning & Design** | **`writing-plans`** | **Implementation Planning**: Decomposes specs into bite-sized, testable tasks annotated with Recommended Skills and file contracts. | Before multi-file refactoring, complex migrations, or major implementations. |
+| 3 | **💻 Implementation** | **`executing-plans`** | **In-Session Plan Execution**: Executes planned tasks step-by-step with checkpoint reviews in the current session. | Batch execution of plans within the same session without spawning subagents. |
+| 4 | **💻 Implementation** | **`subagent-driven-development`** | **Subagent-Driven Development (SDD)**: Dispatches fresh, context-isolated subagents per task with dual-layer adversarial reviews. | Recommended execution model for complex plans to eliminate context pollution. |
+| 5 | **💻 Implementation** | **`test-driven-development`** | **Test-Driven Development (TDD)**: Enforces strict Red ➔ Green ➔ Refactor cycles ensuring robust test coverage. | When implementing logically challenging features or critical algorithms. |
+| 6 | **🔍 Debugging** | **`systematic-debugging`** | **Systematic Root Cause Debugging**: Deconstructs complex errors into testable hypotheses with validation experiments. | When encountering any unexpected error, test failure, or intermittent bug. |
+| 7 | **🛡️ Quality & Review** | **`verification-before-completion`** | **Evidence-Based Verification**: Mandates running the full repository test suite, linter, and type checks. | Before claiming "it works" or "it is done"; provides tangible proof of completion. |
+| 8 | **🛡️ Quality & Review** | **`requesting-code-review`** | **Initiating Code Reviews**: Packages diffs and reports for multi-dimensional architectural and quality reviews. | Before merging branches or finalizing tasks to ensure architectural integrity. |
+| 9 | **🛡️ Quality & Review** | **`receiving-code-review`** | **Processing Review Feedback**: Systematically evaluates review feedback, applies fixes, and records rulings. | When addressing review findings systematically without losing context. |
+| 10 | **🛡️ Quality & Review** | **`finishing-a-development-branch`** | **Branch Integration & Cleanup**: Manages PR/merge, cleans up Git worktrees, and deletes temporary branches cleanly. | After all verifications pass to cleanly integrate the feature into the main branch. |
+| 11 | **🌿 Version Control** | **`using-git-worktrees`** | **Physical Git Isolation**: Creates isolated worktree directories for features or debugging to prevent race conditions. | When working on concurrent tasks or running parallel multi-agent investigations. |
+| 12 | **🤖 Advanced Agents** | **`dispatching-parallel-agents`** | **Parallel Agent Orchestration**: Dispatches concurrent subagents in isolated workspaces to investigate multiple hypotheses simultaneously. | When facing multiple failing tests or investigating independent theories in parallel. |
+| 13 | **🤖 Advanced Agents** | **`using-superpowers`** | **Superpowers Foundation & Discipline**: Establishes mandatory skill discovery, loading discipline, and priority rules. | Automatically loaded at session start to enforce software engineering standards. |
+| 14 | **🤖 Advanced Agents** | **`writing-skills`** | **Skill Authoring & Maintenance**: Guides the creation, testing, and packaging of new Superpowers skills. | When creating custom skills or enhancing existing skill instructions. |
 
 ---
 
 ## 🆕 Recent Updates
 
-### v6.3.2 (Latest)
-
-- **writing-plans — Two Plan Shapes Router & Skeleton-First Plans**:
-  - `skills/writing-plans/SKILL.md` introduces the **Two Plan Shapes** router (`task-by-task` default vs `skeleton-first` alternative) to determine architecture upfront.
-  - New [`skills/writing-plans/skeleton-first-plans.md`](skills/writing-plans/skeleton-first-plans.md) defines the Walking Skeleton pattern (Task 1 builds the thinnest running end-to-end slice across all subsystems), Task Contracts (strict interfaces and observable behaviors without code scripts), and deliberate `Tier: mechanical | judgment` tagging.
-- **subagent-driven-development (SDD) — Wave Dispatch & Parallel Worktree Protocol**:
-  - SDD controller performs **Dispatch Plan** scanning on skeleton-first plans, grouping mutually file-disjoint tasks into waves for concurrent dispatch.
-  - **Parallel Worktree Protocol**: Runs concurrent tasks in dedicated `.worktrees/task-<N>` worktrees, with sequential plan-order merges and automatic rebase-to-fix loops on merge conflict or test regression.
-  - Step 5 adds the post-completion `Plan holds` / `Amendment:` check line, ensuring in-flight tasks complete cleanly while downstream tasks inherit updated plan contracts.
-- **SDD — Tier-Driven Model Selection**:
-  - SDD dispatcher and `implementer-prompt.md` respect task `Tier:` markings (`mechanical` → fastest/cheapest tier; `judgment` → standard tier), saving tokens without redundant re-adjudication.
-- **writing-skills — Binary Execution Hardening (`render-graphs.js`)**:
-  - Replaced `execSync` shell execution with direct `execFileSync('dot', ['-Tsvg'], ...)` to eliminate shell injection risks. Added 10MB buffer limits, Windows CRLF support (`\r?\n`), and Windows `winget` installation guidance.
-- **Tests & Verification**: Full regression suites pass 100% across MCP protocol, Security Edge Cases, SDD Bash (11 assertions), PowerShell (70 assertions), and Graphviz rendering.
-
-### v6.3.1
-
-- **SDD Ownership Markers & Path Normalization**: `sdd-workspace` (Bash) and `sdd-workspace.ps1` (PowerShell) now manage plan-scoped workspaces using `plan-path` markers with canonical physical path normalization (`pwd -P` and dynamic `pwd` detection). Same-basename plans (e.g. `docs/alpha/plan.md` vs `docs/beta/plan.md`) safely disambiguate into distinct `.superpowers/sdd/` workspaces, preventing artifact and ledger overwrites.
-- **SDD Review Package Range Mechanical Guards**: `review-package` and `review-package.ps1` now enforce `git merge-base --is-ancestor BASE HEAD` and `git rev-list --count BASE..HEAD > 0` (exiting with code 3 on error) to reject invalid or empty commit ranges and prevent false-pass review approvals.
-- **SDD Helper Resilience on Stripped Permissions**: `task-brief` and `review-package` invoke `sdd-workspace` via explicit `"${BASH:-bash}"`, surviving environments where execution bits (`+x`) are stripped during archive extraction.
-- **TDD Verification Floor**: `skills/test-driven-development/SKILL.md` explicitly defines "green" as passing the entire repository test suite (e.g., bare `npm test`, `pytest`, `cargo test`) before declaring a task complete.
-- **Code Review Merge-Base Anchoring**: `skills/requesting-code-review/SKILL.md` now anchors multi-commit review `BASE_SHA` to `git merge-base origin/main HEAD` to prevent phantom deletions when `origin/main` advances.
-- **Brainstorming Tooling Decision Gate**: `skills/brainstorming/SKILL.md` adds a proactive tooling inquiry (linter, formatting, unit/e2e tests, fuzzing) during the Design Presentation phase for new projects, recording choices into the spec's `Global Constraints`.
-- **Tests & Coverage**: Added `tests/sdd/test-sdd-workspace.sh` (11 assertions) and expanded PowerShell suites (70 assertions across 5 files). Full test suites passing 100%.
-
-### v6.3.0
-
-- **Upstream sync with obra/superpowers v6.3.0** — all applicable improvements adopted, fork-specific security hardening and PowerShell support preserved.
-  - **brainstorming — three-path router**: every request is classified `spike` / `bounded` / `architectural` up front; the ceremony scales with the task but the approval gate never does. Hidden complexity upgrades the path mid-task — never downgrades.
-  - **subagent-driven-development — rulings, not stalls**: conflicts, ambiguities, and plan defects are ruled on and ledgered (`Ruling: ...`) instead of parking the session on a human; only four named conditions stop execution. Pre-flight conflict scans produce a ledgered table, small same-shape tasks batch into one dispatch, subagent waits use bounded stretches, and all three prompts carry the no-subagents contract.
-  - **Hermes Agent support**: new `hermes-tools.md` reference maps skill actions to Hermes tools (`delegate_task`, `skill_view`, …).
-  - **Codex**: V1/V2 multi-agent differences, `followup_task` fix-round resume, and event-subscription `wait_agent` guidance.
-  - **writing-plans**: plan template now carries a `Spec:` field.
-  - **finishing-a-development-branch**: worktree removal-refused procedure — never `--force` on your own initiative.
-- **Fixes from dual-agent code review**: merged-path "commit them to \<branch\>" no longer strands files outside the base branch (finishing-a-development-branch); `sdd-workspace.ps1` slug derivation matches `basename` on all platforms (`PLAN.MD` stays `PLAN.MD`).
-- **Not adopted (deliberate)**: upstream's v6.3.0 server simplification (it removed loopback-only enforcement, `O_NOFOLLOW` reads, nonce CSP, and the local brand SVG) — this package keeps its hardened server; upstream's `.ps1` deletions and plugin-only restructuring also don't apply to this MCP server layout.
-- **Tests**: MCP flow, render-graphs (8 assertions), and the full PowerShell suite (64 assertions) all pass.
-
-### v6.2.4
-
-- **Upstream alignment — persistent brainstorm sessions**: with `--project-dir`, the companion now persists its session key to `.superpowers/brainstorm/.last-token` (owner-only, gitignored) alongside `.last-port` and reuses it across restarts — an already-open browser tab stays connected after a restart, no URL re-sharing needed. Ephemeral `/tmp` sessions keep rotating the key per invocation, and an explicit `BRAINSTORM_TOKEN` env var still wins and is never persisted. Delete `.last-token` (server stopped) to force a fresh key.
-- **Token-file read path hardened** (`readPrivateFile`): symlinked or multi-link `.last-token` files are rejected instead of being adopted as the session key, with the read performed through an `O_NOFOLLOW` fd whose identity is re-checked and tightened to 0600 — closing the asymmetry with the already-hardened write path (found by independent security review).
-- **Diagnosability**: a failed token-file write now logs `Failed to write private token file:` instead of silently degrading to per-start key rotation.
-- **start-server.ps1 env hygiene**: an ephemeral (no `--project-dir`) launch no longer inherits a stale project key/port from the invoking pwsh session.
-- **Tests**: companion suite now 31 assertions — token persistence across restarts, pre-seeded file honored, symlinked token file rejected, rotation preserved without a token file; test cleanup is failure-safe (try/finally). PowerShell suite asserts `.last-token` matches the served key.
-
-### v6.2.3
-
-- **Hardened Brainstorming Visual Companion (`server.cjs`)**: the local loopback-only HTTP+WebSocket server is crash-resistant against filesystem races (a deleted content dir or a screen vanishing mid-read degrades to the waiting page / 404 instead of killing the process), and its watcher self-heals after the content dir is deleted and recreated (Linux inotify + macOS FSEvents). WebSocket handshakes are validated against RFC 6455 (version/upgrade/connection/key), control-frame payloads are capped at 125 bytes, clients have idle/partial-frame deadlines, and the oldest connection is evicted when the cap is full. Security headers now include `nosniff` and a nonce CSP; generated keys rotate per invocation; screen, skill, event, and user-event reads/logs are size-capped and state files are private.
-- **Companion security defaults**: the server only binds to loopback HTTP, rotates its key on every invocation, stores browser authentication only in an HttpOnly/SameSite cookie after the initial URL, and blocks unnonce'd scripts in screen HTML. Remote browsers must use an authenticated SSH tunnel; a restart requires sharing the new `server-info` URL.
-- **`/files/` double-`writeHead` crash fixed** (found by subagent review): files are read *before* headers are sent, and reads use `O_NOFOLLOW` + fd-based `fstat` + size cap, closing the check-then-read TOCTOU.
-- **Process-lifecycle safety**: `start-server.sh/.ps1` now prove a PID is a live brainstorm server of this session (server-instance-id + cmdline check, same as stop-server) before signalling it; `stop-server.sh` resolves paths canonically before deleting temp sessions so `/tmp/../` tricks can't escape the temp root; relative `--project-dir` is resolved up front; `server-instance-id` is written without BOM so cross-shell identity checks work on Windows PowerShell 5.1.
-- **SkillsManager hardening**: skill reads use `O_NOFOLLOW` on POSIX (symlink-swap TOCTOU); a failed rescan returns the last-good cache instead of poisoning it; skill names containing consecutive dots (e.g. `a..b`) are now findable — lookups are map-only and never touch the filesystem.
-- **MCP protocol polish**: malformed percent-encoding in resource URIs now returns `InvalidRequest` (-32600) instead of leaking an internal error.
-- **Dependencies**: exact verified overrides pin `hono` to 4.13.0, `@hono/node-server` to 2.0.11, and `fast-uri` to 4.1.2 (resolving the relevant advisories). `npm audit`: **0 vulnerabilities**.
-- **Test suite**: `npm test` builds first and runs the JavaScript edge-case/security, MCP server flow, and companion-server regression suites. The 63-assertion PowerShell suite runs separately with `tests/powershell/run-tests.sh` and skips gracefully when `pwsh` is unavailable.
-- **Independent review**: the security and correctness findings were addressed with per-invocation auth rotation, loopback-only HTTP, nonce CSP, bounded reads, private state writes, and deterministic cross-platform tests.
-
-### v6.2.2
-
-- **Symlink Traversal Prevention**: `SkillsManager.readSkillContent()` now canonicalizes paths with `fs.realpath` before checking boundaries, preventing symlink-based arbitrary file reads; `getSafeSkillsPath` also blocks dangerous system-directory prefixes.
-- **Compatibility & Protocol**: Added UTF-8 BOM support for frontmatter and skill content, and enforced RFC 3986 encoding/decoding for resource URIs containing spaces or special characters.
-- **Correctness & Tests**: Force reloads now invalidate the content cache, concurrent reload locking is safer, multiline YAML descriptions accept tab or space indentation, and `tests/edge_cases_test.js` covers these security and cache behaviors.
-
-### v6.2.1
-
-- **PowerShell Script Test Suite**: Added `tests/powershell/` with 63 assertions across 5 suites for `sdd-workspace.ps1`, `task-brief.ps1`, `review-package.ps1`, `find-polluter.ps1`, and the brainstorm `start-server.ps1`/`stop-server.ps1` lifecycle. Run with `tests/powershell/run-tests.sh`; it skips gracefully when `pwsh` is unavailable.
-- **stop-server.ps1 Cross-Platform Fix**: `Get-CimInstance Win32_Process` is Windows-only; the script now uses `ps` on Unix so the server-id check works correctly on macOS/Linux.
-- **Cleanup**: Removed `skills/using-superpowers/references/copilot-tools.md`, an orphaned reference file already pruned upstream.
-
-### v6.2.0
-- **Upstream Sync with obra/superpowers v6.2.0**: Synchronized upstream improvements across all skills while preserving local security enhancements and PowerShell helpers.
-  - **subagent-driven-development Restructure**: Plan-scoped workspaces (`.superpowers/sdd/<plan>/`) so concurrent plans can never read or overwrite each other's artifacts. Resume-based review-fix loop with a five-round circuit breaker, plus a new scoped `re-review-prompt.md` for re-reviews after fixes.
-  - **test-driven-development**: `testing-anti-patterns.md` replaced by upstream `writing-good-tests.md`.
-  - **finishing-a-development-branch**: Adopted the upstream rewrite (includes the same worktree-path capture fix previously patched locally; branch discard is now explicit-request-only).
-  - **Skills-wide compression**: Recap and persuasion sections removed across many `SKILL.md` files, reducing prompt token footprint.
-  - **gemini-tools.md**: Restored to the updated upstream version; `visual-companion.md` gains a Gemini CLI launch section.
-- **PowerShell Parity Fixes**:
-  - All SDD `.ps1` scripts ported to the new plan-scoped `PLAN_FILE` interfaces; `find-polluter.ps1` gained the `./`-prefix and `**/` collapse fixes from the bash version.
-  - **Exit-code parity**: Fixed `Write-Error` under `$ErrorActionPreference = "Stop"` swallowing the intended exit codes — validation failures now correctly exit 2 and a missing task exits 3, matching the bash scripts.
-  - **`sdd-workspace.ps1` slug derivation**: Strips only a trailing `.md` (matching bash `basename`), instead of any file extension.
-- **Version Alignment**: `package.json`, `package-lock.json`, and the MCP server handshake version are now consistent at 6.2.0.
-
-### v6.0.3
-- **Command Injection Fix**: Replaced `cp.exec()` with `cp.execFile()` in the brainstorming Visual Companion server (`server.cjs`) for the `BRAINSTORM_OPEN_CMD` launcher path. The old code concatenated the env var with the URL via the shell; the new code passes arguments as an argv array, eliminating shell metacharacter injection regardless of env var content.
-- **Dependency Security (overrides)**: Added `overrides` block in `package.json` enforcing minimum versions for transitive dependencies:
-  - `@hono/node-server`: 1.19.14 → **2.0.11** — fixes Windows path traversal in serve-static via encoded backslash ([GHSA-frvp-7c67-39w9](https://github.com/advisories/GHSA-frvp-7c67-39w9))
-  - `fast-uri`: 3.1.2 → **4.1.1** — fixes host confusion via IDN canonicalization ([GHSA-4c8g-83qw-93j6](https://github.com/advisories/GHSA-4c8g-83qw-93j6)) and literal backslash authority delimiter ([GHSA-v2hh-gcrm-f6hx](https://github.com/advisories/GHSA-v2hh-gcrm-f6hx))
-  - `body-parser`: 2.2.2 → **2.3.0** — fixes DoS when invalid limit value silently disables size enforcement ([GHSA-v422-hmwv-36x6](https://github.com/advisories/GHSA-v422-hmwv-36x6))
-- **Upstream Bug Fixes**:
-  - `find-polluter.sh`: Now accepts `./`-prefixed paths (not just bare paths) and supports top-level test files by collapsing `**/` in the pattern
-  - `finishing-a-development-branch/SKILL.md`: Captures `WORKTREE_PATH` before Step 5 changes directory, fixing a cleanup regression. Added detached HEAD push variant for Option 2
-
-### v6.0.2
-- **Modular Refactoring & Performance Upgrades**:
-  - **Decoupled Architecture**: Extracted file system access, metadata caching, and parsing logic into a dedicated [`src/skills-manager.ts`](src/skills-manager.ts), leaving [`src/server.ts`](src/server.ts) purely focused on MCP protocol handling.
-  - **O(1) Map-Based Cache**: Replaced the $O(N)$ double-array scan with case-insensitive, dual-key (by name and directory name) memory caches for fast $O(1)$ lookups.
-  - **Async I/O Pipeline**: Swapped synchronous file API calls (`readdirSync`, `readFileSync`) with promises and `Promise.all` concurrent execution, unlocking high-throughput performance.
-  - **Markdown Cache**: Cached stripped skill content in memory to avoid repetitive disk reads when tools are invoked frequently.
-- **Security Hardening**:
-  - **ReDoS Prevention**: Replaced regex-based frontmatter parser with a safe, line-by-line state machine parser, completely eliminating CPU exhaustion risks and supporting multiline YAML descriptions.
-  - **Path Traversal Shield**: Added strict alphanumeric white-listing (`/^[a-zA-Z0-9-_]+$/`) on skill name inputs to prevent traversal attacks.
-  - **Directory Injection Check**: Validated `SKILLS_PATH` to actively reject potentially hostile system root folders.
-  - **Path & Username Leak Protection**: Caught native file system errors and masked them into generic, path-free `McpError` payloads.
-  - **Windows Build and Script Safety**: Handled Windows `chmodSync` platform checks in `esbuild.js` and skipped Symlinks in `copy-skills.js` to prevent recursive file copy loops.
-
-- **Upstream Security Cherry-Picks**: Applied security hardening from obra/superpowers v6.1.1:
-  - **WebSocket frame size validation**: Added `MAX_FRAME_PAYLOAD_BYTES (10 MB)` check in `decodeFrame()` to prevent oversized frame attacks (CWE-789). Dual protection — BigInt extended-length and general post-resolution guard.
-  - **Hardlink containment**: Added `stat.nlink !== 1` check in `isRegularFileInsideContentDir()` prevents path traversal via hardlinks.
-  - **`escapeHtmlText()` extraction**: Extracted inline `escHtml` closure into a reusable named function for consistent HTML escaping.
-  - **URL parsing refactor**: Extracted `pathnameOf()` and `queryKey()` helpers, reducing duplicate inline URL logic in `handleRequest()`.
-- **`review-package` Path Resolution Fix**: Fixed `sdd-workspace` invocation to use absolute path resolution (`$(cd "$(dirname "$0")" && pwd)`) instead of relative path, fixing CWD-dependent failures.
-- **Windows Native Helper Scripts**: Added PowerShell wrappers for Visual Companion startup/shutdown, SDD review/task helpers, and systematic-debugging polluter detection.
-- **Skill Documentation Enhancements**:
-  - `subagent-driven-development`: Added `plan-mandated` review guidance for handling plan conflicts.
-  - `writing-skills`: Strengthened prohibition vs. recipe guidance with empirical evidence from wording tests.
-  - `test-driven-development`: Fixed table formatting for clarity.
-  - `writing-skills/anthropic-best-practices`: Updated image CDN URLs.
-- **`helper.js` Comment Alignment**: Added 4 clarifying inline comments to align with upstream documentation without changing behavior. DOM-safe `showTombstone()` preserved (no `innerHTML` regression).
-- **Cleanup**: Removed obsolete `walkthrough.md` (v5.1.0 upgrade guide).
-
-### v6.0.1
-- **Security Fix — Reflected XSS (#2)**: Fixed server-side reflected cross-site scripting in `skills/brainstorming/scripts/server.cjs`. The `bootstrapPage()` function was called with the user-supplied `keyFromQuery` parameter (even though validated via `timingSafeEqualStr`). Changed to use the server-side `TOKEN` constant instead, eliminating user-tainted data from the HTML response sink. Zero behavior change (the validated value is identical).
-
-### v6.0.0
-- **Upstream Sync with obra/superpowers v6.1.1**: Major synchronization bringing upstream improvements across all skills.
-- **subagent-driven-development Redesign**: Consolidated two-stage review (spec → code quality) into a single "task reviewer" sub-agent, plus added a broad **whole-branch final review** at completion. New **Pre-Flight Plan Review** catches task conflicts before execution begins. Added **Model Selection Guidance** to optimize cost vs. turn count.
-- **using-superpowers Simplified**: Removed platform-specific sections and Graphviz diagram. Introduced **per-platform reference files** (`antigravity-tools.md`, `pi-tools.md`) and updated `codex-tools.md` for cleaner multi-environment support.
-- **brainstorming Visual Companion**: Changed to **just-in-time** offering — no longer offered upfront, only when a visual question actually arises.
-- **Type Safety & Code Quality**: Fixed `Record<string,string>` cast in `server.ts` with proper `typeof` guard. Replaced remaining `innerHTML` with safe DOM methods. Removed redundant checks and verbose comments across the codebase.
-
-### v5.1.2
-- **Security Hardening**: Removed the last remaining `innerHTML` usage in `skills/brainstorming/scripts/helper.js`, replacing it with safe DOM creation methods — now zero `innerHTML` in the entire codebase.
-- **Dependency Security**: Upgraded `hono` from `4.12.23` to `4.12.26` to patch 5 advisories including CORS origin reflection, Lambda body-limit bypass, and Set-Cookie header merging.
-- **Clean Slate**: All 37 Dependabot advisories and npm audit warnings now fully resolved — zero outstanding vulnerabilities.
-
-### v5.1.1
-- **Security Audit & Hardening**: Conducted a full-scale security audit and updated `.gitignore` rules to prevent potential secret leaks.
-- **Vulnerability Patches**: Patched XSS vulnerability in brainstorming Visual Companion (`helper.js`) by replacing unsafe `innerHTML` usage with secure DOM APIs. Upgraded `path-to-regexp` to `8.4.2` to resolve a high-severity ReDoS vulnerability.
-- **Dev Dependencies**: Bumped `esbuild` to `0.28.1`.
-
-### v5.1.0
-- **Inline Self-Review**: Replaced heavyweight subagent review loops (Spec Review, Plan Review) in `brainstorming` and `writing-plans` with lightweight inline self-review checklists, significantly improving efficiency by eliminating subagent overhead.
-- **Git Worktree Redesign**: Rewrote `using-git-worktrees` and `finishing-a-development-branch` with a `detect-and-defer` mechanism, natively supporting AI editors' (like Claude Code) built-in worktree tools while safely falling back to git CLI commands.
-- **Token Optimization**: Removed obsolete `Integration` sections from all skills, reducing prompt token footprints.
-- **Consolidation**: Consolidated the independent `code-reviewer` agent directly into `requesting-code-review`.
-
-### v4.3.2
-- **Security**: Fixed XSS vulnerability in brainstorming Visual Companion
-- **Docs**: Updated README and SECURITY with accurate version info
-
-### v4.3.0
-- Initial MCP server implementation
-- 14 core skills migrated from original Superpowers
+### v6.3.4 (Latest)
+
+- **Universal One-Click Global Setup Engine (`src/setup-runner.ts`, `scripts/`)**:
+  - One-click zero-dependency configuration for 8 major AI environments: Antigravity, Pi Desktop / Pi Agent, Cursor, GitHub Copilot (VS Code), Hermes Desktop / Agent, Kimi Work / Kimi Code, Claude Desktop, and Devin Desktop.
+  - Added CLI executables `superpowers-setup` and `superpowers-mcp setup` with cross-platform installers ([`install.sh`](scripts/install.sh) and [`install.ps1`](scripts/install.ps1)).
+  - **Explicit Consent & Anti-Virus Design**: Mandated explicit `--target <client>` requirement, completely eliminating unprompted bulk disk scanning or blind crawling (`--all` removed).
+  - **Atomic File Operations & Race Defense (`safeWriteConfig`)**: Implemented non-destructive atomic writes via temporary files with process IDs and cryptographically random 8-byte nonces (`crypto.randomBytes(8)`), exclusive creation (`wx`), and atomic `renameSync`.
+  - **Symlink Preservation & Permissions**: Preserves symlink destinations with `realpathSync`, restricts created directories to `0o700` and config files to `0o600`.
+  - **Injection Defense & JSONC Parsing**: Parameter escaping via `JSON.stringify`, JSONC comment tolerance, and `isPlainObject` prototype pollution defense.
+  - **CLI Transport Stdio Isolation**: Front-intercepts setup CLI commands in `src/server.ts` before MCP Stdio transport initialization.
+  - **Comprehensive Test Suite**: Added [`tests/setup_test.js`](tests/setup_test.js) with 21 unit assertions (100% PASS).
+- **Skill Compositions & End-to-End Orchestration Pipelines (`src/server.ts`, `docs/`)**:
+  - Added 3 new MCP workflow prompts: `feature-pipeline`, `structured-debug`, and `skill-composition`.
+  - Comprehensive localized documentation in [`docs/skill-compositions.md`](docs/skill-compositions.md) (EN), [`docs/skill-compositions.zh-TW.md`](docs/skill-compositions.zh-TW.md) (ZH-TW), [`docs/skill-compositions.ja.md`](docs/skill-compositions.ja.md) (JA), and [`docs/skill-compositions.ko.md`](docs/skill-compositions.ko.md) (KO) with horizontal Mermaid flowcharts and ASCII workflow diagrams.
+  - Enhanced [`skills/using-superpowers/SKILL.md`](skills/using-superpowers/SKILL.md) and [`skills/writing-plans/SKILL.md`](skills/writing-plans/SKILL.md) with `Recommended Skill` task metadata standards and controller-to-subagent dispatch protocols.
+  - Added [`tests/prompts_compositions_test.js`](tests/prompts_compositions_test.js) with 7 comprehensive assertions (100% PASS).
+- **Prompts Security Hardening & Lifecycle Fixes (`src/server.ts`)**:
+  - Upgraded `interpolateTemplate` to single-pass regex replacement, eliminating cascading placeholder injection risks.
+  - Enforced universal `getStringArg` with a 32 KB clamp and `hasOwnProperty` validation across all 9 prompts.
+  - Augmented `structured-debug` with Stage 6 (findings resolution via `receiving-code-review`) and Stage 7 (branch finishing and cleanup via `finishing-a-development-branch`).
+- **Full Security Audit & Verification**:
+  - Verified 0 vulnerabilities across `npm audit` with exact dependency overrides for `hono`, `@hono/node-server`, `fast-uri`, and `qs`. All 5 test suites (100+ assertions) passing 100%. Updated [`SECURITY.md`](SECURITY.md).
+
+### v6.3.3
+
+- **MCP Standard Prompts Support (`src/server.ts`)**:
+  - Implemented standard prompt handlers, registering 6 prompts (`session-start`, `sdd-implementer`, `sdd-task-reviewer`, `sdd-re-review`, `spec-reviewer`, `plan-reviewer`) for native IDE prompt-picker usage.
+- **Multi-Harness Reference Mappings**:
+  - Added platform references for Devin CLI ([`references/devin-tools.md`](skills/using-superpowers/references/devin-tools.md)) and OpenCode ([`references/opencode-tools.md`](skills/using-superpowers/references/opencode-tools.md)).
+- **Multi-Lingual Documentation Alignment**:
+  - Aligned MCP capability tables (Tools, Prompts, Resources) and multi-harness matrices across all supported languages.
+- **Test Suite Expansion**:
+  - Added automated test assertions for `prompts/list` and `prompts/get` parameter injection.
+
+👉 *For the complete release history, see [CHANGELOG.md](CHANGELOG.md).*
 
 ---
 
 ## 🙏 Acknowledgments
 
-This project is a fork and adaptation of the original [Superpowers](https://github.com/obra/superpowers) project by [obra](https://github.com/obra). We are grateful for their work in defining the agentic skills framework and software development methodology that powers this MCP server.
+This project is a fork and adaptation of the original [Superpowers](https://github.com/obra/superpowers) project by [obra](https://github.com/obra). We are grateful for their pioneering work in defining the agentic skills framework and software development methodology that powers this MCP server.