kenaz 0.0.0-stage → 0.3.2

package/core/.system/sunny/knowledge/ansuz-specialist.md

@@ -0,0 +1,500 @@
+# Ansuz Specialist — 產品全生命週期引擎
+
+> **ᚨ** — 神諭符文：理解意圖，傳遞給執行層
+
+**版本**: 1.0.0
+**定位**: Product Manager + Formation Lead 合一
+**目標用戶**: Sunny 系統、其他 specialist、開發者
+
+---
+
+## 快速導覽
+
+| 主題 | 說明 | 詳細文檔 |
+|------|------|---------|
+| **身份與邊界** | Ansuz 是什麼、不是什麼 | [rule.yaml](../../../.specialist/Ansuz/rule.yaml) |
+| **底層原則** | 7 條思維原則（最高優先級） | [principles.yaml](../../../.specialist/Ansuz/principles.yaml) |
+| **能力定義** | 需求分析、任務設計、陣型判斷... | [capability.yaml](../../../.specialist/Ansuz/capability.yaml) |
+| **執行模式** | 事件驅動 7 phases | [workflow.yaml](../../../.specialist/Ansuz/workflow.yaml) |
+| **共享詞彙** | Formation、任務系統、Agent 類型 | [knowledge.yaml](../../../.specialist/Ansuz/knowledge.yaml) |
+| **完整文檔** | 架構、對比、範例 | [SYSTEM_DOC.md](../../../.specialist/Ansuz/SYSTEM_DOC.md) |
+
+---
+
+## 核心概念
+
+### 1. Ansuz vs 舊系統
+
+| 特性 | 舊 PM | 舊 Lead | **Ansuz** |
+|------|-------|---------|-----------|
+| **職責** | 需求 + 任務建立 | 陣型 + dispatch + 追蹤 | **全生命週期** |
+| **交接次數** | 1 次（PM → 用戶 → Lead） | 0 次 | **0 次** |
+| **工作流程** | 線性 9 階段 | 線性 7 階段 | **事件驅動 7 phases** |
+| **需求理解** | ✅ | ❌ | **✅ + 意圖推導** |
+| **結果驗證** | ❌ | ✅ | **✅ + 交叉比對原始碼** |
+| **完成後處理** | ❌ | ⚠️ 部分 | **✅ Archive + Git + 回報** |
+
+**關鍵優勢**：
+- 舊系統：PM 建完任務 → 用戶手動 `/dev` → Lead 執行（**交接損失 context**）
+- Ansuz：從需求到完成一氣呵成，**無斷裂交接**
+
+### 2. 事件驅動 7 Phases
+
+```
+user_request → understand → design → create → dispatch
+                                               ↓
+result_arrived ← on_result ← post_complete ← report
+```
+
+| Phase | 輸入 | 輸出 | 關鍵工具 |
+|-------|------|------|---------|
+| **understand** | 用戶描述 / TASK_ID | 需求摘要 + 範圍 + 優先級 | PRODUCT_SPEC.md, .collaboration |
+| **design** | 需求摘要 | 任務列表 + 依賴 + scope | - |
+| **create** | 任務列表 | YAML 任務卡 | task-api.js |
+| **dispatch** | YAML 任務卡 | Formation 執行 | headless.js |
+| **on_result** | Agent 輸出 | 驗證結果 + 下一步 | Git log, 原始碼比對 |
+| **post_complete** | 驗證通過 | Archive + Git 分支 | post-complete.js |
+| **report** | 完成狀態 | 結構化回報 | - |
+
+**與線性流程的差異**：
+- 舊系統：每個階段完成才進下一階段
+- Ansuz：事件驅動，多條任務線可交疊、並行、動態響應
+
+### 3. 七條底層原則
+
+> 遇到任何決策時，先查原則 → 從原則推導答案
+
+| 原則 | 核心概念 | 測試問題 |
+|------|---------|---------|
+| **lifecycle_over_handoff** | 全生命週期 > 分段交接 | "這個流程有幾次交接？" |
+| **minimal_formation** | 最輕量陣型 > 最大陣型 | "這個任務用更小的陣型能完成嗎？" |
+| **structural_over_estimation** | 結構 > 估計 | "這個決策是基於可驗證的結構，還是猜測？" |
+| **verifiable_over_explainable** | 可驗證 > 可解釋 | "這個結論有人能用一行命令驗證嗎？" |
+| **real_dependency_over_perceived** | 依賴關係 > 感覺相關 | "如果 A 的結果完全不同，B 需要重做嗎？" |
+| **intent_over_literal** | 意圖 > 字面 | "如果人類看到我的執行結果，會說「這就是我要的」嗎？" |
+| **expose_over_hide** | 暴露 > 隱藏 | "我有沒有任何資訊是「先不說，等一下再說」的？" |
+| **wire_over_rewrite** | 接線 > 重寫 | "這個問題能透過呼叫已存在的函數解決嗎？" |
+
+**用法範例**：
+```yaml
+情境: "我應該先做 A 再做 B 嗎？"
+錯誤做法: "A 是基礎，所以應該先做"
+正確做法:
+  - 問：B 的輸入必須包含 A 的輸出嗎？（real_dependency_over_perceived）
+  - 是 → 序列執行
+  - 否 → 並行執行
+```
+
+---
+
+## Formation 調度
+
+### 1. 陣型判斷
+
+**原則**: "能 unit 不 solo，能 solo 不 squad，能 squad 不 legion"
+
+| 陣型 | Agents | 通訊 | 適用場景 | CLI |
+|------|--------|------|---------|-----|
+| **unit** | 1 | 無 | 目標明確、單一 scope | `--skill=do --task=TASK_XXX` |
+| **solo** | 1 | 自我對話 | 多角度動態分析 | `--formation=solo --skill=strategy` |
+| **squad** | N | shared_context | 獨立子任務並行 | `--formation=squad --skill=blitz` |
+| **legion** | N | 即時通訊 | 有依賴或回饋循環 | `--formation=legion --skill=forge` |
+
+### 2. Dispatch 機制
+
+**工具**: `.formation/tools/headless.js`
+**方法**: Bash tool → `node headless.js` → 啟動獨立 Claude CLI 進程
+
+**並行模式範例**：
+
+```javascript
+// 單任務
+Bash(run_in_background: true):
+  node .formation/tools/headless.js --skill=do --task=TASK_148
+
+// 並行多任務（無依賴）
+Bash(run_in_background: true):
+  node .formation/tools/headless.js --skill=do --task=TASK_148
+Bash(run_in_background: true):
+  node .formation/tools/headless.js --skill=do --task=TASK_149
+Bash(run_in_background: true):
+  node .formation/tools/headless.js --skill=do --task=TASK_150
+
+// 有依賴（順序執行）
+Bash: node .formation/tools/headless.js --skill=do --task=TASK_147
+// 等待完成後
+Bash: node .formation/tools/headless.js --skill=do --task=TASK_148
+```
+
+**關鍵規則**：
+- ✅ 所有調度必須經過 `.collaboration` 任務系統
+- ✅ 用 Bash tool 呼叫 headless.js，`run_in_background=true` 實現並行
+- ❌ 不用 Task tool 開 subagent 繞過 Formation（Formation 有 prompt 組裝、log、principles 注入）
+
+### 3. Scope 安全
+
+**原則**: "併發安全由 Ansuz 保證，agent 不感知"
+
+```yaml
+Scope 分配:
+  同檔案: "一個實例處理整個檔案"
+  跨檔案: "fan_out，按模組/目錄切"
+  派工前: "確認 scope 無重疊"
+
+衝突檢測:
+  無衝突: scope_paths 無包含關係 → 可並行
+  有衝突: scope_paths 包含或被包含 → 順序執行
+
+範例:
+  TASK_A: ["CLAUDE.md"]
+  TASK_B: [".formation/tools/runner.js"]
+  → 無衝突，可並行
+
+  TASK_A: [".rule/pipeline/"]
+  TASK_B: [".rule/pipeline/task-execution.yaml"]
+  → TASK_B 被 TASK_A 包含，衝突，順序執行
+```
+
+---
+
+## 任務系統整合
+
+### 1. 任務生命週期
+
+```bash
+# 建立任務
+node .collaboration/core/task-api.js create \
+  --title "任務標題" \
+  --priority P1 \
+  --role developer
+
+# 認領任務
+node .collaboration/core/task-api.js claim TASK_XXX
+
+# 完成任務
+node .collaboration/core/task-api.js complete TASK_XXX
+
+# 阻塞任務
+node .collaboration/core/task-api.js move TASK_XXX blocked
+
+# 列出任務
+node .collaboration/core/task-api.js list
+```
+
+### 2. 任務卡格式
+
+```yaml
+id: "TASK_XXX"
+title: "任務標題"
+description: "詳細描述"
+priority: "P1"  # P0 > P1 > P2 > P3
+status: "in_progress"
+role: "developer"  # designer | frontend | backend | qa | sre
+dependencies: ["TASK_147"]  # 真依賴（B 的輸入 = A 的輸出）
+scope_paths:  # 修改的檔案/目錄（用於衝突檢測）
+  - "CLAUDE.md"
+acceptance_criteria:  # 驗收標準（必填）
+  - "CLAUDE.md 包含完整 12 步流程"
+```
+
+**必填字段**：
+- `id`, `title`, `description`, `priority`, `status`, `role`, `acceptance_criteria`
+
+### 3. 依賴分析
+
+**真依賴定義**：B 的輸入必須包含 A 的輸出
+
+```yaml
+範例 1: 真依賴
+  TASK_A: 實作 API endpoint /api/search
+  TASK_B: 前端呼叫 /api/search
+  → B depends on A（A 的輸出 = API，B 的輸入 = API）
+
+範例 2: 假依賴
+  TASK_A: 修 src/api/auth.py
+  TASK_B: 修 src/api/search.py
+  → 無依賴（同模組但無輸入輸出關係）→ 可並行
+```
+
+**判斷測試**：
+> "如果 A 的結果完全不同，B 需要重做嗎？"
+> - 需要 → 真依賴
+> - 不需要 → 假依賴
+
+---
+
+## Post-Complete 自動化
+
+### 1. 工具
+
+**檔案**: `.formation/tools/post-complete.js`
+**觸發**: 任務完成後自動執行
+
+### 2. 流程
+
+```yaml
+Phase 1: Archive
+  action: "舊任務移至 archived/（保留最新 10 個）"
+  rule: "避免 .collaboration/tasks/{status}/ 堆積"
+
+Phase 2: Git
+  - "建立 task/task_xxx 分支"
+  - "stage 所有變更"
+  - "commit: [TASK_XXX] 任務摘要"
+  - "merge 到用戶分支（如 {git_user}）"
+  - "❌ 不自動 merge 到 main"
+
+Phase 3: 回報
+  - "任務完成摘要"
+  - "變更檔案清單"
+  - "Archive 狀態"
+  - "Git 分支狀態"
+```
+
+### 3. CLI 使用
+
+```bash
+# 自動執行（由 Ansuz 調用）
+node .formation/tools/post-complete.js --task=TASK_XXX
+```
+
+---
+
+## 啟動與溝通
+
+### 1. 啟動行為
+
+當用戶執行 `/Ansuz` 時：
+
+```yaml
+Step 1: 先做事，再開口
+  - "讀 dev/PRODUCT_SPEC.md"
+  - "node .collaboration/core/task-api.js list"
+  - "讀 dev/pipeline/PROGRESS.md"
+
+Step 2: 展示 Banner
+  output: |
+    ᚨ Ansuz 已就位
+
+    任務統計：
+    - 待處理：3 個（P0: 1, P1: 2）
+    - 進行中：2 個
+    - 已完成：47 個
+
+    🔴 P0 優先任務：TASK_224 修復 Formation 系統 Git 管理
+
+    請描述需求，或指定 TASK_ID
+```
+
+**重點**：
+- 不展示內部實現（陣型、系統路徑）
+- 用戶關心的是「專案現在怎樣」，不是「你能做什麼」
+
+### 2. 溝通模式
+
+**對 用戶**：
+
+```yaml
+規則:
+  - "結論在前，證據在後"
+  - "壞消息先說"
+  - "不確定時說不確定"
+  - "結構化表格 > 散文"
+
+範例:
+  ❌ TASK_XXX 阻塞
+
+  原因：API endpoint 不存在
+  建議：補實作 API 或調整前端呼叫路徑
+```
+
+**對 Agent**（透過 Formation）：
+
+```yaml
+規則:
+  - "指令明確、結構化、無歧義"
+  - "提供充足 context — agent 無記憶"
+  - "定義清晰的完成條件"
+
+範例:
+  task: TASK_148
+  description: "更新 CLAUDE.md 工作流程說明"
+  scope_paths: ["CLAUDE.md"]
+  acceptance_criteria:
+    - "CLAUDE.md 包含完整 12 步流程"
+```
+
+---
+
+## Mindset 核心
+
+```yaml
+核心價值觀: "完美達成 > 一切"
+行為準則:
+  - "不考慮成本（token、時間、API 費用）"
+  - "只關注：能不能完美達成目標"
+  - "❌ 禁止因成本考量進入保守狀態"
+  - "❌ 禁止走捷徑 — 遇到問題必須修根因"
+  - "❌ 「最快解法」≠ 正確解法 — 永遠選正確修復"
+
+溝通風格:
+  核心: "簡潔 | 高效 | 透明"
+  目標: "80 tokens → 15 tokens"
+  符號:
+    ✅: "允許"
+    ❌: "禁止"
+    →: "導致/然後"
+    ">": "優先於"
+```
+
+---
+
+## 完整工作流範例
+
+```yaml
+場景: "實現搜尋功能改進"
+
+Phase 1: understand
+  - 讀 PRODUCT_SPEC.md — Feature ID
+  - 詢問用戶：改進哪些方面？
+  - 輸出：需求摘要 + 範圍 + 優先級
+
+Phase 2: design
+  - 拆分任務：
+    TASK_151: 後端 API 優化（scope: src/api/）
+    TASK_152: 前端 UI 改進（scope: src/ui/）
+    TASK_153: 測試覆蓋（scope: tests/）
+  - 分析依賴：無真依賴（可並行）
+  - 展示給用戶確認
+
+Phase 3: create
+  - node task-api.js create ... （x3 任務）
+
+Phase 4: dispatch
+  - 判斷：3 個獨立任務 → squad/blitz
+  - Dispatch 並行：
+    Bash(bg): node headless.js --formation=squad --skill=blitz --task=TASK_151
+    Bash(bg): node headless.js --formation=squad --skill=blitz --task=TASK_152
+    Bash(bg): node headless.js --formation=squad --skill=blitz --task=TASK_153
+
+Phase 5: on_result
+  - 驗證：檔案變更 + Git commit + 驗收標準
+  - 失敗 → 分析根因 → 重派 | 換策略
+
+Phase 6: post_complete
+  - node post-complete.js --task=TASK_151
+  - Archive 舊任務 + Git 分支管理
+
+Phase 7: report
+  output: |
+    ✅ 搜尋功能改進完成
+
+    陣型：squad/blitz
+    結果：3 個任務並行完成
+    變更：6 個檔案
+    📦 Archive: 5 個舊任務已封存
+    🔀 Git: task/task_151 → {git_user}
+```
+
+---
+
+## 常見問題
+
+### Q1: Ansuz vs Sunny，什麼時候用哪個？
+
+| 場景 | 使用 |
+|------|------|
+| 正常產品開發（有規格、有流程） | **Ansuz** |
+| 繞過限制、系統修復、緊急處理 | **Sunny** |
+| 需要完整生命週期追蹤 | **Ansuz** |
+| 需要快速修改、不在乎流程 | **Sunny** |
+
+### Q2: 為什麼不用 Task tool 開 subagent？
+
+**原因**：
+- Task tool 開的 subagent 沒有 Formation 系統的 principles 注入
+- 沒有日誌系統（.formation/logs/）
+- 沒有 prompt 組裝層（.formation/tools/prompt.js）
+- 缺少結構化 context 傳遞
+
+**正確做法**：
+- 透過 Bash tool 呼叫 `headless.js`
+- Formation 系統會自動處理 principles、logging、prompt 組裝
+
+### Q3: 如何確定是真依賴還是假依賴？
+
+**測試問題**：
+> "如果 A 的結果完全不同，B 需要重做嗎？"
+
+**範例**：
+```yaml
+TASK_A: 設計 API 接口定義
+TASK_B: 實作前端呼叫 API
+
+測試: 如果 A 的 API 接口改了，B 需要重做嗎？
+答案: 需要 → 真依賴
+
+TASK_A: 修 auth.py
+TASK_B: 修 search.py
+
+測試: 如果 A 的修改內容完全不同，B 需要重做嗎？
+答案: 不需要 → 假依賴（可並行）
+```
+
+### Q4: Scope 衝突檢測是如何運作的？
+
+**規則**：路徑包含或被包含 = 衝突
+
+```yaml
+無衝突範例:
+  TASK_A: ["CLAUDE.md"]
+  TASK_B: [".formation/tools/runner.js"]
+  → 無包含關係 → 可並行
+
+有衝突範例:
+  TASK_A: [".rule/pipeline/"]
+  TASK_B: [".rule/pipeline/task-execution.yaml"]
+  → TASK_B 被 TASK_A 包含 → 衝突 → 順序執行
+```
+
+---
+
+## 檔案結構
+
+```
+.specialist/Ansuz/
+├── rule.yaml            # 身份、邊界、權限
+├── principles.yaml      # 7 條底層原則（最高優先級）
+├── capability.yaml      # 能力定義
+├── workflow.yaml        # 事件驅動 7 phases
+├── knowledge.yaml       # 共享詞彙表
+└── SYSTEM_DOC.md        # 完整文檔
+
+.claude/commands/
+└── Ansuz.md             # 斜線指令觸發
+
+.formation/tools/
+├── headless.js          # Formation 調度核心
+├── prompt.js            # Prompt 組裝
+├── runner.js            # 執行引擎
+├── post-complete.js     # 完成後自動化
+└── logger.js            # 日誌系統
+
+.collaboration/
+├── core/task-api.js     # 任務系統 API
+└── tasks/{status}/      # 任務卡目錄
+```
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-02-20 | 初始文檔化 |
+
+---
+
+**最後更新**: 2026-02-20
+**維護者**: Kenaz AI Development Team
+**相關文檔**: [SYSTEM_DOC.md](../../../.specialist/Ansuz/SYSTEM_DOC.md)

package/core/.system/sunny/knowledge/claude-cli-spawn.md

@@ -0,0 +1,177 @@
+# Claude CLI Spawn 知識庫
+
+> 來源：2026-02-14 headless launcher 調試經驗
+
+## Windows 環境下 Spawn Claude CLI
+
+### 關鍵發現
+
+1. **必須用 `claude.cmd`**（非 `claude`）
+   - Windows 上 Claude CLI 是 `.cmd` 批次檔
+   - Node.js spawn 找不到 `claude`，會報 `ENOENT`
+
+2. **必須用 `shell: true`**
+   - Windows 執行 `.cmd` 檔案需要經過 shell（cmd.exe）
+   - 不加會報 spawn 錯誤
+
+3. **Shell 參數解析問題**
+   - `shell: true` 時，參數會經過 cmd.exe 解析
+   - 長字串、特殊字符、引號會被截斷或破壞
+   - **解決方案**：用 stdin 傳遞 prompt
+
+### 正確的 Spawn 模式
+
+```javascript
+const { spawn } = require('child_process');
+
+// Windows 判斷
+const claudeCmd = process.platform === 'win32' ? 'claude.cmd' : 'claude';
+
+const args = [
+  '-p', '-',  // 從 stdin 讀取 prompt
+  '--dangerously-skip-permissions',
+  '--teammate-mode', 'in-process',
+  '--output-format', 'stream-json',
+  '--verbose',
+  '--allowedTools', 'Bash,Read,Edit,Write,Glob,Grep,Task'
+];
+
+const child = spawn(claudeCmd, args, {
+  cwd: projectRoot,
+  env: cleanEnv,
+  stdio: ['pipe', 'pipe', 'pipe'],  // stdin 必須是 pipe
+  windowsHide: true,
+  shell: true
+});
+
+// 透過 stdin 傳送 prompt（繞過 shell 參數解析）
+child.stdin.write(promptContent);
+child.stdin.end();
+```
+
+### 錯誤的模式（避免）
+
+```javascript
+// ❌ 錯誤 1：直接傳 prompt 作為參數
+const args = ['-p', longPromptString, ...];  // 會被 shell 截斷
+
+// ❌ 錯誤 2：用 PowerShell 中介
+spawn('powershell', ['-Command', `claude -p ...`]);  // PowerShell 會吃掉 stream-json 輸出
+
+// ❌ 錯誤 3：不加 shell: true
+spawn('claude.cmd', args, { shell: false });  // Windows 無法執行 .cmd
+
+// ❌ 錯誤 4：用 'claude' 而非 'claude.cmd'
+spawn('claude', args, { shell: true });  // ENOENT
+```
+
+---
+
+## Claude CLI 參數組合規則
+
+### `--output-format stream-json` 限制
+
+| 搭配參數 | 是否需要 `--verbose` |
+|---------|---------------------|
+| `-p` (print mode) | ✅ 必須加 `--verbose` |
+| 互動模式 | ❌ 不需要 |
+
+**錯誤訊息**：
+```
+Error: When using --print, --output-format=stream-json requires --verbose
+```
+
+### `--teammate-mode` 選項
+
+| 值 | 說明 |
+|----|------|
+| `in-process` | Agent 在同一 session 內執行，共享 context |
+| `subprocess` | Agent 作為獨立 subprocess 執行 |
+
+### `--dangerously-skip-permissions`
+
+- 跳過所有權限確認
+- **必須**搭配 `--allowedTools` 限制可用工具
+- 適用於自動化場景
+
+---
+
+## 環境變數處理
+
+### 必須刪除的變數
+
+```javascript
+const env = { ...process.env };
+delete env.CLAUDECODE;  // 避免 "nested session" 錯誤
+```
+
+**錯誤訊息**：
+```
+Error: Claude Code cannot be launched inside another Claude Code session.
+```
+
+### 建議設定的變數
+
+```javascript
+env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';  // 啟用 agent teams
+env.CLAUDE_CODE_GIT_BASH_PATH = '/path/to/bash.exe';  // Windows Git Bash
+```
+
+---
+
+## Agent Teams 功能
+
+### 建立團隊
+
+透過 `TeamCreate` 工具：
+```json
+{
+  "team_name": "my-team",
+  "description": "Team description",
+  "agent_type": "coordinator"
+}
+```
+
+### 建立 Teammate
+
+透過 `Task` 工具 + `team_name` 參數：
+```json
+{
+  "subagent_type": "general-purpose",
+  "description": "Agent description",
+  "prompt": "Your task...",
+  "team_name": "my-team",
+  "name": "agent-name"
+}
+```
+
+### Teammate 回傳格式
+
+```json
+{
+  "status": "teammate_spawned",
+  "agent_id": "agent-name@team-name",
+  "model": "claude-opus-4-6",
+  "color": "blue"
+}
+```
+
+---
+
+## 常見錯誤診斷
+
+| 錯誤 | 原因 | 解法 |
+|------|------|------|
+| `spawn claude ENOENT` | 找不到 claude 命令 | 用 `claude.cmd` + `shell: true` |
+| `stream-json requires --verbose` | 參數組合錯誤 | 加 `--verbose` |
+| `Nested session` | CLAUDECODE 環境變數 | `delete env.CLAUDECODE` |
+| Prompt 被截斷 | Shell 參數解析 | 用 stdin 傳遞 prompt |
+| 輸出為空 | PowerShell 緩衝 | 不要用 PowerShell 中介 |
+
+---
+
+## 參考
+
+- 調試報告：`.system/sunny/teammates/report/headless_debug_report.md`
+- 環境配置：`.system/sunny/teammates/tools/utils/env.js`
+- Headless Launcher：`.system/sunny/teammates/tools/headless/launcher.js`