superpowers-mcp - npm Package Compare versions

Comparing version 4.3.0 to 4.3.1

README.zh-TW.md

+# Superpowers MCP Toolpack 使用指南
+
+[English](README.md) | [繁體中文](README.zh-TW.md)
+
+本文檔總結了將原始 Superpowers 技能庫打包成獨立 MCP Toolpack 的相關資訊與使用說明。
+
+---
+
+## 🚀 安裝與使用方式
+
+### 支援的環境
+
+**Antigravity**、**Cursor**、**VSCode**，以及其他支援 MCP 工具鏈的 AI 編輯器。
+
+### 與 AI Agent 對話
+
+安裝或配置完成後，您的 AI Agent（例如 Copilot 或 Antigravity Cascade）將能夠識別並使用 `Superpowers Skills`。
+
+**您可以這樣提問：**
+
+- "列出所有 superpowers 技能"
+- "使用 read_skill 讀取 brainstorming 技能，然後幫我分析這個功能的實作"
+- "套用 session-start prompt"（模擬原始的啟動注入機制）
+
+---
+
+## 🛠️ MCP 配置
+
+將以下設定加入您的 IDE（例如 Cursor, Antigravity, 或 VSCode 的 MCP 設定）。
+
+### 方法：NPX / BUNX（推薦）
+
+這是最簡單的方式，因為它會自動處理路徑解析。
+
+#### 使用 Bun（較快）
+```json
+{
+  "superpowers": {
+    "command": "bunx",
+    "args": ["-y", "superpowers-mcp"]
+  }
+}
+```
+
+#### 使用 Node/NPM
+```json
+{
+  "superpowers": {
+    "command": "npx",
+    "args": ["-y", "superpowers-mcp"]
+  }
+}
+```
+
+---
+
+## 💡 常用技能與情境
+
+| 技能名稱 | 社群推薦使用情境 | 核心價值 |
+| :--- | :--- | :--- |
+| `brainstorming` | 啟動新功能前，探索需求與設計。 | 防止 AI 直接衝進去寫 code。 |
+| `writing-plans` | 進行多檔案重構或複雜迁移前。 | 建立明確的執行藍圖。 |
+| `systematic-debugging` | 遇到任何報錯或行為異常時。 | 強制執行「根因分析」而非亂猜。 |
+| `test-driven-development` | 實作具邏輯挑戰的功能時。 | 確保代碼隨附測試，實現 Red-Green-Refactor。 |
+| `verification-before-completion` | 聲稱「修好了」或「做完了」之前。 | 證據導向的完工確認。 |
+
+---
+
+## 🔄 推薦的指令 (Command Sequences)
+
+### 1. 新功能開發
+1. `[superpowers:brainstorm : 確認需求與架構]`
+2. `[superpowers:writing-plans : 寫下具體步驟]`
+3. `[superpowers:test-driven-development : 撰寫測試與實作]`
+4. `[superpowers:verification-before-completion : 跑測試確認無誤]`
+
+### 2. 緊急修復 (Hotfix)
+1. `[superpowers:systematic-debugging : 定位問題根源]`
+2. `[superpowers:test-driven-development : 寫一個失敗測試重現問題，再修復]`
+3. `[superpowers:verification-before-completion : 驗證修復結果]`
+
+---
+
+## 📋 支援技能總覽 (共 14 個)
+
+為了解決技能太多難以選擇的問題，我們將這 14 個技能依照軟體開發的 6 個階段進行了分類：
+
+### 🚀 1. 規劃與設計 (Planning & Design)
+- `brainstorming`: 軟體設計與需求分析流程
+- `writing-plans`: 建立詳細的實作計畫
+
+### 💻 2. 開發與除錯 (Implementation & Debugging)
+- `executing-plans`: 執行已建立的實作計畫
+- `test-driven-development`: TDD（測試驅動開發）工作流
+- `systematic-debugging`: 系統性除錯與根因分析
+
+### 🛡️ 3. 品質驗證與審查 (Quality & Review)
+- `verification-before-completion`: 完工前的證據導向驗證
+- `requesting-code-review`: 發起程式碼審查的預先檢查
+- `receiving-code-review`: 接收與處理程式碼審查回饋
+- `finishing-a-development-branch`: 收尾開發分支與整合
+
+### 🌿 4. 版本控制 (Version Control)
+- `using-git-worktrees`: 使用 Git Worktrees 管理多重分支
+
+### 🤖 5. 代理進階控制 (Advanced Agent Controls)
+
+這是特別針對在支援多重代理 (Multi-Agent) 協作或具備強大推論能力的 IDE（如 Antigravity 或 Cursor）中所設計的高階操作技巧。
+
+- **`subagent-driven-development`**: 驅動子代理執行複雜任務
+  - **具體用法**：適用於「執行已規劃好的詳細計畫」。針對每一個小任務，AI 會派發全新的「實作代理」去寫 Code，完成後立刻啟動「規格審查」與「品質審查」的雙重把關，審查通過才進入下一關。
+  - **指令範例**：`[superpowers:subagent-driven-development : 請依照 docs/plans/feature-plan.md 的內容，幫我逐一派發子代理實作]`
+- **`dispatching-parallel-agents`**: 派發平行代理同步執行任務
+  - **具體用法**：適用於「同時處理多個互不干擾的獨立問題」（例如 3 個無關聯的 Bug，或 3 個獨立的網路查詢需求）。AI 會切換為平行處理的思維模型，將各個問題視為獨立專案同時處理，避免記憶混亂（Context 污染）並加速多任務產出。
+  - **偵錯範例**：`[superpowers:dispatching-parallel-agents : 現在有 A, B, C 三個獨立的測試報錯，請派發 3 個代理同時去排查並修復]`
+  - **查詢範例**：`[superpowers:dispatching-parallel-agents : 幫我派發 3 個代理去網路上分別查詢：1. React 19 新特性, 2. Vue 3.5 更新重點, 3. Svelte 5 的 Runes 系統，並各自整理成摘要]`
+
+### ⚙️ 6. 系統與自定義 (Meta & Customization)
+- `using-superpowers`: Superpowers 核心操作指南與自我檢查
+- `writing-skills`: 撰寫與擴充新的自訂技能
+
+---
+
+## 🙏 致謝
+
+本專案是透過 fork 與改編自 [obra](https://github.com/obra) 的原始 [Superpowers](https://github.com/obra/superpowers) 專案。我們非常感謝他們在定義 Agentic 技能框架與軟體開發方法論上的貢獻，這些成為了這個 MCP Server 的基石。

package.json

@@ -5,3 +5,3 @@ {
   "description": "Superpowers skills library (TDD, debugging, collaboration workflows) as an MCP server for VSCode and Antigravity",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "publisher": "superpowers",
@@ -8,0 +8,0 @@ "license": "MIT",

README.md

 # Superpowers MCP Toolpack Usage Guide
 
+[English](README.md) | [繁體中文](README.zh-TW.md)
+
 This document summarizes the information and usage instructions for packaging the original Superpowers skills library into an independent MCP Toolpack.
@@ -7,18 +9,2 @@
 
-## 🏗️ Project Structure Overview
-
-The MCP Toolpack is located in the project root directory:
-
-```text
-superpowers-mcp/
-├── package.json                  ← NPM package manifest defining the built-in MCP Server registration and commands
-├── src/
-│   └── server.ts                 ← MCP stdio server implementation (contains 14 skills)
-├── skills/                       ← Offline packaged skills library (copied from the main project)
-└── out/
-    └── server.js (325 KB)         ← Compiled MCP Server
-```
-
----
-
 ## 🚀 How to Install and Use
@@ -42,14 +28,16 @@
 
-## 🛠️ Manual MCP Configuration
+## 🛠️ MCP Configuration
 
-If your IDE or AI agent environment requires manual configuration of the MCP Server, please add the following settings (specifying the local npm package or absolute physical path):
+Add the following settings to your IDE (e.g., Cursor, Antigravity, or VSCode MCP settings). 
 
+### Method : NPX / BUNX (Recommended)
+
+This is the easiest way as it handles path resolution automatically.
+
+#### Using Bun (Faster)
 ```json
 {
   "superpowers": {
-    "command": "node",
-    "args": ["/path/to/superpowers-mcp/out/server.js"],
-    "env": {
-      "SKILLS_PATH": "/path/to/superpowers-mcp/skills"
-    }
+    "command": "bunx",
+    "args": ["-y", "superpowers-mcp"]
   }
@@ -59,16 +47,79 @@ }
 
-> 💡 If you installed via npm globally, you can use `$(npm root -g)/superpowers-mcp` as the path prefix.
+#### Using Node/NPM
+```json
+{
+  "superpowers": {
+    "command": "npx",
+    "args": ["-y", "superpowers-mcp"]
+  }
+}
+```
 
 ---
 
+## 💡 Common Skills & Scenarios
+
+| 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. |
+
+---
+
+## 🔄 Recommended Prompt Sequences
+
+### 1. New Feature Development Sequence
+1. `[superpowers:brainstorm : Confirm requirements and architecture]`
+2. `[superpowers:writing-plans : Create an execution plan with specific steps]`
+3. `[superpowers:test-driven-development : Implement the feature with tests]`
+4. `[superpowers:verification-before-completion : Run test suites to ensure everything works]`
+
+### 2. Emergency Hotfix Sequence
+1. `[superpowers:systematic-debugging : Locate the root cause of the current issue]`
+2. `[superpowers:test-driven-development : Write a failing test for the bug and fix it]`
+3. `[superpowers:verification-before-completion : 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
+- `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
-- `writing-plans`: Creating detailed implementation plans
-- `subagent-driven-development`: Driving sub-agents to execute tasks
+
+### 🛡️ 3. Quality & Review
+- `verification-before-completion`: Evidence-based verification before completion
 - `requesting-code-review`: Initiating pre-checks for code reviews
-- ... and 8 other core skills.
+- `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 will spawn a fresh "implementer" sub-agent for a single task, followed by "spec reviewer" and "code quality reviewer" sub-agents to ensure high-quality output before moving to the next task.
+  - **Example**: `[superpowers:subagent-driven-development : 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**: `[superpowers:dispatching-parallel-agents : Tests A, B, and C are failing independently. Dispatch 3 parallel agents to investigate and fix them]`
+  - **Research Example**: `[superpowers:dispatching-parallel-agents : Dispatch 3 parallel agents to search the web for: 1. React 19 features, 2. Vue 3.5 updates, 3. Svelte 5 Runes. Summarize each independently]`
+
+### ⚙️ 6. Customization & Meta
+- `using-superpowers`: Guidelines and self-checks for using Superpowers
+- `writing-skills`: Writing and expanding new custom skills
+
 ---
@@ -75,0 +126,0 @@

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

570253

1.51%

Number of package files

40

2.56%

Number of lines in readme file

127

67.11%

No dependency changes