docs: add Trad. Chinese READMEs for PM skills and align brainstorming output path

2026-04-09 15:37:46 +08:00 · 2026-04-09 15:37:46 +08:00 · 839afbf06d
parent b4b28eecd4
commit 839afbf06d
12 changed files with 177 additions and 211 deletions
--- 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/`)
--- a/skills/brainstorming/README.zh-TW.md
+++ 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 規格、技術權衡。
+
+## 🔒 安全與隱私
+- **完全本地化**：視覺助手運行於本地伺服器，所有數據僅在本地傳輸，**絕無資料外傳**行為。
+- **透明控制**：所有視覺助手操作均需用戶明確同意後方可啟動。
--- a/skills/brainstorming/scripts/frame-template.html
+++ b/skills/brainstorming/scripts/frame-template.html
@ -195,20 +195,20 @@
  </style>
 </head>
 <body>
-  <div class="header">
-    <h1><a href="https://github.com/obra/superpowers" style="color: inherit; text-decoration: none;">Superpowers Brainstorming</a></h1>
-    <div class="status">Connected</div>
-  </div>
+<div class="header">
+  <h1><a href="https://github.com/obra/superpowers" style="color: inherit; text-decoration: none;">Superpowers Brainstorming</a></h1>
+  <div class="status">Connected</div>
+</div>

-  <div class="main">
-    <div id="claude-content">
-      <!-- CONTENT -->
-    </div>
+<div class="main">
+  <div id="claude-content">
+    <!-- CONTENT -->
  </div>
+</div>

-  <div class="indicator-bar">
-    <span id="indicator-text">Click an option above, then return to the terminal</span>
-  </div>
+<div class="indicator-bar">
+  <span id="indicator-text">Click an option above, then return to the terminal</span>
+</div>

 </body>
 </html>
--- 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('</body>')) {
      html = html.replace('</body>', helperInjection + '\n</body>');
@ -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);
--- 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
 <p class="subtitle">Consider readability and visual hierarchy</p>

 <div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
-    <div class="letter">A</div>
-    <div class="content">
-      <h3>Single Column</h3>
-      <p>Clean, focused reading experience</p>
-    </div>
-  </div>
-  <div class="option" data-choice="b" onclick="toggleSelect(this)">
-    <div class="letter">B</div>
-    <div class="content">
-      <h3>Two Column</h3>
-      <p>Sidebar navigation with main content</p>
-    </div>
-  </div>
+   <div class="option" data-choice="a" onclick="toggleSelect(this)">
+      <div class="letter">A</div>
+      <div class="content">
+         <h3>Single Column</h3>
+         <p>Clean, focused reading experience</p>
+      </div>
+   </div>
+   <div class="option" data-choice="b" onclick="toggleSelect(this)">
+      <div class="letter">B</div>
+      <div class="content">
+         <h3>Two Column</h3>
+         <p>Sidebar navigation with main content</p>
+      </div>
+   </div>
 </div>
 ```

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

 ```html
 <div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
-    <div class="letter">A</div>
-    <div class="content">
-      <h3>Title</h3>
-      <p>Description</p>
-    </div>
-  </div>
+   <div class="option" data-choice="a" onclick="toggleSelect(this)">
+      <div class="letter">A</div>
+      <div class="content">
+         <h3>Title</h3>
+         <p>Description</p>
+      </div>
+   </div>
 </div>
 ```

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

 ```html
 <div class="options" data-multiselect>
-  <!-- same option markup — users can select/deselect multiple -->
+   <!-- same option markup — users can select/deselect multiple -->
 </div>
 ```

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

 ```html
 <div class="cards">
-  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
-    <div class="card-image"><!-- mockup content --></div>
-    <div class="card-body">
-      <h3>Name</h3>
-      <p>Description</p>
-    </div>
-  </div>
+   <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+      <div class="card-image"><!-- mockup content --></div>
+      <div class="card-body">
+         <h3>Name</h3>
+         <p>Description</p>
+      </div>
+   </div>
 </div>
 ```

@ -199,8 +199,8 @@ The frame template provides these CSS classes for your content:

 ```html
 <div class="mockup">
-  <div class="mockup-header">Preview: Dashboard Layout</div>
-  <div class="mockup-body"><!-- your mockup HTML --></div>
+   <div class="mockup-header">Preview: Dashboard Layout</div>
+   <div class="mockup-body"><!-- your mockup HTML --></div>
 </div>
 ```

@ -208,8 +208,8 @@ The frame template provides these CSS classes for your content:

 ```html
 <div class="split">
-  <div class="mockup"><!-- left --></div>
-  <div class="mockup"><!-- right --></div>
+   <div class="mockup"><!-- left --></div>
+   <div class="mockup"><!-- right --></div>
 </div>
 ```

@ -217,8 +217,8 @@ The frame template provides these CSS classes for your content:

 ```html
 <div class="pros-cons">
-  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
-  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
+   <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
+   <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
 </div>
 ```

@ -227,8 +227,8 @@ The frame template provides these CSS classes for your content:
 ```html
 <div class="mock-nav">Logo | Home | About | Contact</div>
 <div style="display: flex;">
-  <div class="mock-sidebar">Navigation</div>
-  <div class="mock-content">Main content area</div>
+   <div class="mock-sidebar">Navigation</div>
+   <div class="mock-content">Main content area</div>
 </div>
 <button class="mock-button">Action Button</button>
 <input class="mock-input" placeholder="Input field">
--- a/skills/grill-me/README.zh-TW.md
+++ 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 會主動探索代碼而非詢問用戶。
+
+## 📥 輸入與輸出
+- **輸入**：一個初步的開發計畫、設計方案或功能想法。
+- **輸出**：
+    - **過程**：一系列深度的對話追問。
+    - **結果**：一個被全面壓力測試過、消除所有模糊之處的**共識方案**。
+
+## 💡 使用時機
+- 當你覺得計畫「看起來沒問題」但擔心有遺漏時。
+- 在進入正式實作前，想要確保沒有任何未定義的行為時。
+- 當你需要一個「魔鬼代言人」來挑戰你的設計決策時。
--- a/skills/write-a-prd/README.zh-TW.md
+++ 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 以便團隊追蹤。