diff --git a/agents/pm-agent.md b/agents/pm-agent.md index 8000427..3f56efb 100644 --- a/agents/pm-agent.md +++ b/agents/pm-agent.md @@ -1,145 +1,20 @@ # PM Agent (Product Manager) -## Role Positioning +## Core Goal +Responsible for requirement discovery, PRD writing, and product planning to ensure a clear, testable, and valuable product definition. -**Product Manager** - Responsible for requirement discovery, PRD writing, and product planning. +## Workflow (Input & Output) -## Core Responsibilities +| Stage | Action | Input | Output (STRICT PATH) | Skill/Tool | +|-------|--------|-------|----------------------|-----------| +| Brainstorming | Explore user needs & ideas | User's initial ideas | `docs/brainstorm/{date}-{feature}-design.md` | `brainstorming` | +| PRD Writing | Produce structured requirements | `docs/brainstorm/{date}-{feature}-design.md` | `docs/prd/{date}-{feature}.md` | `write-a-prd` | +| Validation | Deep validation & gap filling | First draft of PRD | Enhanced PRD (Update `docs/prd/...`) | `grill-me` | -1. **Requirement Discovery** - Understand user needs through interviews -2. **PRD Writing** - Produce structured Product Requirement Documents (including Functional & Non-Functional requirements) -3. **User Stories** - Define clear user stories -4. **Acceptance Criteria** - Set testable acceptance criteria -5. **Prioritization** - Prioritize features and requirements - -## Skills Used - -### Stage 1: Brainstorming -- **Skill**: `brainstorming` -- **Input**: User's initial ideas -- **Output**: `docs/brainstorm/{date}-{feature}-design.md` -- **Content**: - - Problem Statement - - Target Users - - Feature List - - Technical Proposal Suggestions - -### Stage 3: PRD Writing -- **Skill**: `write-a-prd` -- **Input**: CEO Review results -- **Output**: `docs/prd/{date}-{feature}.md` -- **Content**: - - Problem Statement - - Solution - - User Stories (Detailed list) - - Implementation Decisions - - Testing Decisions - - Non-Functional Requirements (Performance, Security, etc.) - - Out of Scope - -### Stage 3.5: Deep Validation (Grill-Me) -- **Skill**: `grill-me` -- **Trigger**: Proactively invoked after the first draft of the PRD to ensure no gaps -- **Input**: First draft of PRD -- **Validation Items**: - - Completeness of each functional requirement - - Edge cases of user stories - - Omissions of non-functional requirements (Critical) - - Testability of acceptance criteria -- **Output**: Enhanced PRD - -## PRD Template Structure - -```markdown -# PRD: {feature_name} - -## Metadata -- Date: {date} -- Status: Draft | Review | Approved -- Author: PM Agent - -## Problem Statement -{problem_description} - -## Solution -{solution} - -## User Stories -1. As a {role}, I want {feature}, so that {benefit} -2. ... - -## Implementation Decisions -- {technical_decisions} -- {architecture_decisions} - -## Testing Decisions -- {testing_strategy} -- {priority_test_items} - -## Non-Functional Requirements -### NFR-001: Performance -- Description: (e.g., Response time < 200ms, Supports 100 concurrency) -- Measurement: -### NFR-002: Reliability/Security -- Description: -- Measurement: - -## Out of Scope -- {omitted_features} - -## Functional Requirements -### FR-001: {requirement_title} -- Description: -- Priority: P0 | P1 | P2 -- User Stories: - -## Acceptance Criteria -### AC-001: {acceptance_item} -- Given: -- When: -- Then: -- Automated: Yes/No -``` -## Working Principles - -1. **User-Centric** - All requirements start from the user's perspective -2. **Clear and Specific** - Avoid vague descriptions, strive for executability -3. **Complete Coverage** - Consider normal flows, exception cases, and non-functional constraints -4. **Testability** - Every requirement should have clear acceptance criteria -5. **Iterative Refinement** - Mandatory deep validation via `grill-me` before finalization - -## Collaboration with Other Agents - -``` -PM Agent ←→ CEO Reviewer: Receive review feedback, adjust scope -PM Agent → Backend Agent: Provide PRD for API design -PM Agent → UX Agent: Provide requirements for prototype design -PM Agent → QA Agent: Provide acceptance criteria for testing -``` - -## Decision Authority - -- Define product features and scope -- Set requirement priority -- Determine acceptance criteria -- Suggest technical solutions (not the final decision) - -## Deliverables Checklist - -- [ ] Brainstorm document completed in `docs/brainstorm/` -- [ ] PRD document completed in `docs/prd/` -- [ ] User stories clear and complete -- [ ] Acceptance criteria testable -- [ ] Non-functional requirements (NFR) explicitly defined and measurable -- [ ] Grill-me deep validation completed - -## Common Issues Handling - -**Q: User requirements are unclear?** -A: Use brainstorming skill for multiple rounds of interviews until requirements are clear. - -**Q: Technical feasibility is doubtful?** -A: Mark risks in Implementation Decisions and discuss with Backend Agent. - -**Q: Scope is too large?** -A: Collaborate with CEO Reviewer to split into multiple phases and define the MVP. +## Key Deliverables +- [ ] **Brainstorm Document**: Problem statement, target users, and feature list. (Path: `docs/brainstorm/`) +- [ ] **Product Requirement Document (PRD)**: + - Detailed User Stories. + - Testable Acceptance Criteria (AC). + - Measurable Non-Functional Requirements (NFR - Performance, Security). + - Explicit Out of Scope definitions. (Path: `docs/prd/`) \ No newline at end of file diff --git a/skills/brainstorming/README.zh-TW.md b/skills/brainstorming/README.zh-TW.md new file mode 100644 index 0000000..bbff4fb --- /dev/null +++ b/skills/brainstorming/README.zh-TW.md @@ -0,0 +1,33 @@ +# 腦力激盪 (Brainstorming) 技能指南 + +## 概述 +`brainstorming` 技能旨在將模糊的想法轉化為精確的設計方案。它強制執行「先設計，後開發」的原則，避免在實作過程中因假設錯誤而導致的重複工作。 + +## 🚀 運作流程 +1. **上下文探索**：AI 分析專案現有代碼、文檔及提交記錄。 +2. **釐清需求**：透過**一次一個問題**的對話，確認目的、限制與成功標準。 +3. **方案對比**：提供 2-3 種實現方式及其優缺點（Trade-offs），並給出推薦建議。 +4. **分段設計**：詳細說明架構、元件與數據流，每段需經用戶確認。 +5. **文件化 (Spec)**：將共識記錄於 `docs/brainstorm/` 下的設計文檔中。 +6. **最終審核**：AI 自查 $\rightarrow$ 用戶審核文檔 $\rightarrow$ 批准。 +7. **轉入計畫**：調用 `writing-plans` 技能制定詳細實作計畫。 + +## 🌐 視覺助手 (Visual Companion) 使用說明 +當文字不足以表達視覺概念（如 UI 佈局、架構圖）時，AI 會啟動視覺助手。 + +### 如何使用 +1. **啟動**：AI 請求權限 $\rightarrow$ 用戶同意 $\rightarrow$ AI 提供 `localhost` 連結。 +2. **互動**： + - 用戶打開連結查看 AI 生成的 HTML 原型圖或圖表。 + - 用戶可直接在網頁上**點擊選項**（例如：選擇佈局 A 或 B）。 +3. **反饋迴圈**： + - AI 讀取用戶的點擊紀錄與終端機文字反饋。 + - AI 更新 HTML 內容 $\rightarrow$ 用戶再次查看 $\rightarrow$ 直到達成共識。 + +### 適用場景 +- ✅ **使用視覺助手**：UI 原型、佈局對比、導航結構、系統架構圖、流程圖。 +- ❌ **使用終端機**：需求定義、邏輯討論、API 規格、技術權衡。 + +## 🔒 安全與隱私 +- **完全本地化**：視覺助手運行於本地伺服器，所有數據僅在本地傳輸，**絕無資料外傳**行為。 +- **透明控制**：所有視覺助手操作均需用戶明確同意後方可啟動。 diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index a787aff..3840c2f 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -159,4 +159,4 @@ A browser-based companion for showing mockups, diagrams, and visual options duri A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser. If they agree to the companion, read the detailed guide before proceeding: -`skills/brainstorming/visual-companion.md` +`skills/brainstorming/visual-companion.md` \ No newline at end of file diff --git a/skills/brainstorming/scripts/frame-template.html b/skills/brainstorming/scripts/frame-template.html index dcfe018..64d44d3 100644 --- a/skills/brainstorming/scripts/frame-template.html +++ b/skills/brainstorming/scripts/frame-template.html @@ -195,20 +195,20 @@ -
-

Superpowers Brainstorming

-
Connected
-
+
+

Superpowers Brainstorming

+
Connected
+
-
-
- -
+
+
+
+
-
- Click an option above, then return to the terminal -
+
+ Click an option above, then return to the terminal +
- + \ No newline at end of file diff --git a/skills/brainstorming/scripts/helper.js b/skills/brainstorming/scripts/helper.js index 111f97f..a7cd15b 100644 --- a/skills/brainstorming/scripts/helper.js +++ b/skills/brainstorming/scripts/helper.js @@ -85,4 +85,4 @@ }; connect(); -})(); +})(); \ No newline at end of file diff --git a/skills/brainstorming/scripts/server.cjs b/skills/brainstorming/scripts/server.cjs index 562c17f..bfb8a4c 100644 --- a/skills/brainstorming/scripts/server.cjs +++ b/skills/brainstorming/scripts/server.cjs @@ -115,12 +115,12 @@ function wrapInFrame(content) { function getNewestScreen() { const files = fs.readdirSync(CONTENT_DIR) - .filter(f => f.endsWith('.html')) - .map(f => { - const fp = path.join(CONTENT_DIR, f); - return { path: fp, mtime: fs.statSync(fp).mtime.getTime() }; - }) - .sort((a, b) => b.mtime - a.mtime); + .filter(f => f.endsWith('.html')) + .map(f => { + const fp = path.join(CONTENT_DIR, f); + return { path: fp, mtime: fs.statSync(fp).mtime.getTime() }; + }) + .sort((a, b) => b.mtime - a.mtime); return files.length > 0 ? files[0].path : null; } @@ -131,8 +131,8 @@ function handleRequest(req, res) { if (req.method === 'GET' && req.url === '/') { const screenFile = getNewestScreen(); let html = screenFile - ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8')) - : WAITING_PAGE; + ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8')) + : WAITING_PAGE; if (html.includes('')) { html = html.replace('', helperInjection + '\n'); @@ -170,10 +170,10 @@ function handleUpgrade(req, socket) { const accept = computeAcceptKey(key); socket.write( - 'HTTP/1.1 101 Switching Protocols\r\n' + - 'Upgrade: websocket\r\n' + - 'Connection: Upgrade\r\n' + - 'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n' + 'HTTP/1.1 101 Switching Protocols\r\n' + + 'Upgrade: websocket\r\n' + + 'Connection: Upgrade\r\n' + + 'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n' ); let buffer = Buffer.alloc(0); @@ -267,7 +267,7 @@ function startServer() { // macOS fs.watch reports 'rename' for both new files and overwrites, // so we can't rely on eventType alone. const knownFiles = new Set( - fs.readdirSync(CONTENT_DIR).filter(f => f.endsWith('.html')) + fs.readdirSync(CONTENT_DIR).filter(f => f.endsWith('.html')) ); const server = http.createServer(handleRequest); @@ -303,8 +303,8 @@ function startServer() { const infoFile = path.join(STATE_DIR, 'server-info'); if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile); fs.writeFileSync( - path.join(STATE_DIR, 'server-stopped'), - JSON.stringify({ reason, timestamp: Date.now() }) + '\n' + path.join(STATE_DIR, 'server-stopped'), + JSON.stringify({ reason, timestamp: Date.now() }) + '\n' ); watcher.close(); clearInterval(lifecycleCheck); @@ -351,4 +351,4 @@ if (require.main === module) { startServer(); } -module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES }; +module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES }; \ No newline at end of file diff --git a/skills/brainstorming/scripts/start-server.sh b/skills/brainstorming/scripts/start-server.sh index 9ef6dcb..7ad39d4 100755 --- a/skills/brainstorming/scripts/start-server.sh +++ b/skills/brainstorming/scripts/start-server.sh @@ -145,4 +145,4 @@ done # Timeout - server didn't start echo '{"error": "Server failed to start within 5 seconds"}' -exit 1 +exit 1 \ No newline at end of file diff --git a/skills/brainstorming/scripts/stop-server.sh b/skills/brainstorming/scripts/stop-server.sh index 2bf841f..fdc4c17 100755 --- a/skills/brainstorming/scripts/stop-server.sh +++ b/skills/brainstorming/scripts/stop-server.sh @@ -53,4 +53,4 @@ if [[ -f "$PID_FILE" ]]; then echo '{"status": "stopped"}' else echo '{"status": "not_running"}' -fi +fi \ No newline at end of file diff --git a/skills/brainstorming/spec-document-reviewer-prompt.md b/skills/brainstorming/spec-document-reviewer-prompt.md index 0c254b8..c436fc7 100644 --- a/skills/brainstorming/spec-document-reviewer-prompt.md +++ b/skills/brainstorming/spec-document-reviewer-prompt.md @@ -46,4 +46,4 @@ Task tool (general-purpose): - [suggestions for improvement] ``` -**Reviewer returns:** Status, Issues (if any), Recommendations +**Reviewer returns:** Status, Issues (if any), Recommendations \ No newline at end of file diff --git a/skills/brainstorming/visual-companion.md b/skills/brainstorming/visual-companion.md index 2113863..05f0682 100644 --- a/skills/brainstorming/visual-companion.md +++ b/skills/brainstorming/visual-companion.md @@ -136,20 +136,20 @@ Write just the content that goes inside the page. The server wraps it in the fra

Consider readability and visual hierarchy

-
-
A
-
-

Single Column

-

Clean, focused reading experience

-
-
-
-
B
-
-

Two Column

-

Sidebar navigation with main content

-
-
+
+
A
+
+

Single Column

+

Clean, focused reading experience

+
+
+
+
B
+
+

Two Column

+

Sidebar navigation with main content

+
+
``` @@ -163,13 +163,13 @@ The frame template provides these CSS classes for your content: ```html
-
-
A
-
-

Title

-

Description

-
-
+
+
A
+
+

Title

+

Description

+
+
``` @@ -177,7 +177,7 @@ The frame template provides these CSS classes for your content: ```html
- +
``` @@ -185,13 +185,13 @@ The frame template provides these CSS classes for your content: ```html
-
-
-
-

Name

-

Description

-
-
+
+
+
+

Name

+

Description

+
+
``` @@ -199,8 +199,8 @@ The frame template provides these CSS classes for your content: ```html
-
Preview: Dashboard Layout
-
+
Preview: Dashboard Layout
+
``` @@ -208,8 +208,8 @@ The frame template provides these CSS classes for your content: ```html
-
-
+
+
``` @@ -217,8 +217,8 @@ The frame template provides these CSS classes for your content: ```html
-

Pros

  • Benefit
-

Cons

  • Drawback
+

Pros

  • Benefit
+

Cons

  • Drawback
``` @@ -227,8 +227,8 @@ The frame template provides these CSS classes for your content: ```html
Logo | Home | About | Contact
-
Navigation
-
Main content area
+
Navigation
+
Main content area
@@ -284,4 +284,4 @@ If the session used `--project-dir`, mockup files persist in `.superpowers/brain ## Reference - Frame template (CSS reference): `scripts/frame-template.html` -- Helper script (client-side): `scripts/helper.js` +- Helper script (client-side): `scripts/helper.js` \ No newline at end of file diff --git a/skills/grill-me/README.zh-TW.md b/skills/grill-me/README.zh-TW.md new file mode 100644 index 0000000..468ca72 --- /dev/null +++ b/skills/grill-me/README.zh-TW.md @@ -0,0 +1,22 @@ +# 壓力測試 (Grill-me) 技能指南 + +## 概述 +`grill-me` 是一個「對抗式」的審核技能。它的目的不是為了通過，而是為了**找出漏洞**。AI 會像嚴厲的審核員一樣，對你的計畫或設計進行無情地追問，直到所有潛在的模糊地帶、依賴關係和邊緣案例都被解決。 + +## 🚀 運作流程 +1. **深入剖析**：AI 掃描你的計畫，找出所有決策分支和潛在的風險點。 +2. **逐一擊破**：AI **一次只問一個問題**，強迫你針對特定決策點給出明確答案。 +3. **遞進解析**：沿著設計樹（Design Tree）向下走，先解決核心依賴，再解決細節問題。 +4. **提供建議**：在追問的同時，AI 會提供它認為的「最佳實踐」或「推薦答案」供你參考。 +5. **驗證事實**：如果問題可以透過閱讀代碼來回答，AI 會主動探索代碼而非詢問用戶。 + +## 📥 輸入與輸出 +- **輸入**：一個初步的開發計畫、設計方案或功能想法。 +- **輸出**： + - **過程**：一系列深度的對話追問。 + - **結果**：一個被全面壓力測試過、消除所有模糊之處的**共識方案**。 + +## 💡 使用時機 +- 當你覺得計畫「看起來沒問題」但擔心有遺漏時。 +- 在進入正式實作前，想要確保沒有任何未定義的行為時。 +- 當你需要一個「魔鬼代言人」來挑戰你的設計決策時。 diff --git a/skills/write-a-prd/README.zh-TW.md b/skills/write-a-prd/README.zh-TW.md new file mode 100644 index 0000000..48320ff --- /dev/null +++ b/skills/write-a-prd/README.zh-TW.md @@ -0,0 +1,36 @@ +# 產品需求文檔 (Write-a-PRD) 技能指南 + +## 概述 +`write-a-prd` 技能將抽象的功能需求轉化為結構化的產品需求文檔 (PRD)。它結合了用戶訪談、代碼分析和模組設計，最終產出一份開發者可直接執行的技術準則。 + +## 🚀 運作流程 +1. **需求挖掘**：要求用戶提供詳細的問題描述與初步解決方案想法。 +2. **現況核實**：探索現有代碼庫，驗證用戶的假設並理解技術現狀。 +3. **壓力訪談**：調用類似 `grill-me` 的邏輯，對方案的每個細節進行深度追問，直到達成共識。 +4. **模組設計**： + - 規劃需要建立或修改的模組。 + - 追求**深層模組 (Deep Modules)**：將複雜功能封裝在簡單、穩定且可獨立測試的接口中。 + - 與用戶確認模組劃分及測試優先級。 +5. **正式撰寫**：根據標準模板撰寫 PRD。 +6. **提交發佈**：將 PRD 保存為文件並提交為 **GitHub Issue**。 + +## 📥 輸入與輸出 +### 輸入 (Input) +- 用戶對問題的詳細描述。 +- 潛在的解決方案想法。 +- 現有代碼庫的上下文。 + +### 輸出 (Output) +- **路徑**：`docs/prd/{date}-{feature}.md` +- **格式 (PRD 模板)**： + - **問題陳述 (Problem Statement)**：從用戶視角描述目前面臨的痛點。 + - **解決方案 (Solution)**：從用戶視角描述解決後的狀態。 + - **用戶故事 (User Stories)**：格式為 `作為 <角色>, 我想要 <功能>, 以便於 <獲益>`。 + - **實作決策 (Implementation Decisions)**：模組變更、接口定義、架構決定、Schema 變更等（不含具體文件路徑）。 + - **測試決策 (Testing Decisions)**：定義測試標準、確定測試模組及參考案例。 + - **超出範圍 (Out of Scope)**：明確定義本次開發**不**包含的功能。 + - **補充筆記 (Further Notes)**：其他相關資訊。 + +## 🔒 注意事項 +- **工作環境**：建議在獨立的 `worktree` 中運行。 +- **同步性**：最終 PRD 必須同步至 GitHub Issue 以便團隊追蹤。