kenaz 0.0.0-stage → 0.3.2

package/core/k-cli/README.md

@@ -0,0 +1,423 @@
+# k-cli
+
+KenazAI 的獨立 CLI 工具 — 無需 Dashboard，直接操作 Specialist、Task、Dispatch、Project 等核心功能。
+
+## 快速開始
+
+```bash
+cd k-cli && npm install && npm run build
+
+# 1. 確認 CLI 可用
+k-cli ping
+
+# 2. 查看專案狀態
+k-cli project status
+
+# 3. 若尚未初始化（status 顯示 mode: unknown）→ 初始化（core-path 自動偵測）
+k-cli project initialize
+
+# 4. 查看使用指南（初始化時自動產生）
+cat k-cli.md
+```
+
+**建議流程**：`ping` → `status` → （未初始化則 `initialize`）→ 正常使用
+
+## 定位
+
+| 比較 | Dashboard MCP (Rust) | mcp-server (Node，已於 TASK_2027 移除) | **k-cli** |
+|------|---------------------|-------------------|-------------|
+| 運行方式 | HTTP server（需 Dashboard） | stdio MCP server | **獨立 CLI** |
+| 依賴 | Tauri app 運行中 | MCP client 呼叫 | **無依賴，直接執行** |
+| 用途 | Claude Code 透過 `.mcp.json` 使用 | 已移除（TASK_2027） | **人類 + 腳本直接操作** |
+
+## 核心價值
+
+- **零依賴**：不需要 Dashboard 運行，直接呼叫底層工具
+- **spawnClaude 架構**：寫入操作透過 `spawnClaude` 直接啟動 Claude CLI，無需 headless.js 中間層
+- **dry-run 支援**：所有寫入命令支援 `--dry-run`，驗證但不執行
+- **可腳本化**：所有輸出支援 `--json` 格式，方便 pipe 和自動化
+- **明確偵測**：不猜測、不 fallback、不向上找目錄，偵測失敗就是失敗
+
+## 設計原則
+
+```
+讀取操作 → 直接呼叫底層工具（快速、無副作用）
+寫入操作 → spawnClaude 啟動 Claude CLI（Specialist 執行 / Ansuz 決策）
+```
+
+| 操作類型 | 命令 | 執行方式 |
+|---------|------|---------|
+| 讀取 | specialist list, task list, task get, project status... | 直接呼叫 |
+| 寫入（任務） | task create | → spawnClaude + Ansuz（分析需求 → Amelia 審查 role → 建立） |
+| 刪除 | task delete | → 直接 rm 檔案 |
+| 調度 | dispatch run TASK_XXX | → spawnClaude + Ansuz（讀 role → 判斷陣型 → headless.js） |
+| 調度 | dispatch run --auto | → spawnClaude + Ansuz（掃描 backlog → 逐個 dispatch） |
+| 執行 | specialist run | → spawnClaude + 指定 Specialist |
+
+## 命令一覽
+
+```
+k-cli <command> [subcommand] [options]
+```
+
+### Specialist 命令
+
+| 命令 | 說明 | 執行方式 |
+|------|------|---------|
+| `k-cli specialist list` | 列出所有 Specialist（名稱 + prompt） | 直接讀取 |
+| `k-cli specialist run` | 啟動 Specialist 執行任務 | spawnClaude |
+
+```bash
+# 列出所有 Specialist 和 prompt
+k-cli specialist list
+
+# 啟動 Ansuz（positional args 作為 user prompt）
+k-cli specialist run --agent Ansuz 幫我檢查 git 狀態
+
+# 啟動 Amelia 協調多 Agent
+k-cli specialist run --agent Amelia 執行 TASK_340
+
+# dry-run：顯示會做什麼，不實際啟動
+k-cli specialist run --agent Ansuz 分析需求 --dry-run
+```
+
+### Task 命令
+
+| 命令 | 說明 | 執行方式 |
+|------|------|---------|
+| `k-cli task list` | 列出任務 | 直接讀取 |
+| `k-cli task get <id>` | 取得任務詳情 | 直接讀取 |
+| `k-cli task create <描述>` | 建立新任務（自然語言，人類用） | → spawnClaude + Ansuz + Amelia |
+| `k-cli task submit --title ... ` | 建立新任務（結構化欄位，process/script 用，TASK_2147） | 直接呼叫 task-api.js，無 Claude 依賴 |
+| `k-cli task delete <id>` | 刪除任務 | → 直接 rm 檔案 |
+
+```bash
+# 讀取（直接）
+k-cli task list --status backlog
+k-cli task get TASK_340
+
+# 建立任務（語意描述 → Ansuz 分析 → Amelia 審查 role → 建立高品質任務）
+k-cli task create 幫我創建 hello_world.js 輸出 Hello World
+k-cli task create 實作登入 API 支援 OAuth2 --dry-run
+
+# 刪除（直接 rm 檔案，不限狀態）
+k-cli task delete TASK_340
+k-cli task delete TASK_340 --dry-run
+```
+
+#### task submit（TASK_2147：子專案 process 用，無 Claude 依賴）
+
+`task create` 的輕量版：不分析自然語言、不呼叫 Ansuz/Amelia，直接把旗標轉成
+`task-api.js create` 呼叫。給已經知道自己要建什麼卡的 process/script 用（例如子專案裡的
+in-app agent 把一個改良提案變成任務）。core 解析沿用 `resolveProject()`（讀
+`.kenaz/project.yaml`），呼叫端不需要設定 `KENAZ_SOURCE_DIR`。
+
+```bash
+k-cli task submit \
+  --title "標題" --description "描述" --priority P3 --role developer \
+  --requirements "r1" --requirements "r2" --requirements "r3" \
+  --acceptance-criteria "a1" --acceptance-criteria "a2" --acceptance-criteria "a3" \
+  --technical-notes "n1" --technical-notes "n2" \
+  --origin "my-sub-project-agent" \
+  --project-path /path/to/subproject --json
+```
+
+- 任務一律落在 `backlog/`（正常 triage），**不會 auto-dispatch**。
+- `--origin`（= `--source`）未指定時，預設為子專案名稱；用來標記任務來源方便追溯。
+- 品質門檻（requirements/acceptance_criteria ≥ 3、technical_notes ≥ 2）與 `task create` 相同，不放寬。
+- `--json` 會在建立後自動 `task get` 回完整任務 JSON（含 `id`/`source`/`status`），方便腳本直接讀回結果。
+- `--dry-run` 顯示會執行的 task-api.js 指令，不實際建立。
+
+#### task create 流程
+
+```
+k-cli task create "描述"
+  │
+  ├─ k-cli 預先組裝 Ansuz + Amelia prompts（並行）
+  │
+  └→ spawnClaude(Ansuz) [allowedTools 含 Agent]
+       ├─ Step 1: 分析需求（理解目標、搜尋相關代碼）
+       ├─ Step 2: 整理任務草稿（結構化所有欄位）
+       ├─ Step 3: Agent tool → Amelia subagent 審查 + 判斷 role
+       ├─ Step 4: 採納建議 → task-api.js create（含正確 role）
+       └─ Step 5: 輸出結果摘要
+```
+
+> Amelia 審查透過 Claude 原生 Agent tool（subagent）執行，避免 nested CLI spawn。
+
+### Dispatch 命令
+
+| 命令 | 說明 | 執行方式 |
+|------|------|---------|
+| `k-cli dispatch run <taskId>` | Dispatch 指定任務 | → spawnClaude + Ansuz + headless.js |
+| `k-cli dispatch run --auto` | 自動掃描 backlog 並 dispatch | → spawnClaude + Ansuz + headless.js |
+| `k-cli dispatch status <taskId>` | 查看 dispatch 狀態 | 直接讀取 |
+
+```bash
+# 指定任務 dispatch（Ansuz 讀 role → 判斷陣型 → headless.js 執行）
+k-cli dispatch run TASK_340
+k-cli dispatch run TASK_340 --dry-run
+
+# 自動掃描（Ansuz 掃 backlog → 按優先級逐個 dispatch）
+k-cli dispatch run --auto
+k-cli dispatch run --auto --project-path /path/to/project
+
+# 查看狀態（自動搜尋 .kenaz/logs/ 或 .formation/logs/）
+k-cli dispatch status TASK_340 --tail 50
+```
+
+#### dispatch run 流程
+
+```
+k-cli dispatch run TASK_XXX
+  │
+  └→ spawnClaude(Ansuz)
+       ├─ Step 1: task-api get → 讀取任務 role
+       ├─ Step 2: role → --skill, 判斷陣型（unit > solo > squad > legion）
+       └─ Step 3: node headless.js --skill={role} --task=TASK_XXX
+                    │
+                    headless.js 自動處理：
+                    ├─ auto-claim（backlog → active）
+                    ├─ 依賴預檢
+                    ├─ spawnClaude(agent) 執行任務
+                    ├─ ensureTaskComplete
+                    └─ postComplete（archive + git branch + merge）
+```
+
+#### Formation Role → Skill 對應
+
+| role | --skill | 說明 |
+|------|---------|------|
+| frontend | frontend | React/TypeScript UI、client-side |
+| backend | backend | API、DB、server-side |
+| designer | designer | 設計規範產出 |
+| qa | qa | 測試、Bug 驗證 |
+| sre | sre | 基礎設施、部署 |
+| developer | developer | 通才兜底 |
+
+Skill 定義檔：`.formation/legacy/{role}.yaml`
+
+#### 陣型判斷
+
+原則：能 unit 不 solo，能 solo 不 squad，能 squad 不 legion。
+
+| 陣型 | 條件 | headless.js 參數 |
+|------|------|-----------------|
+| unit（預設） | 目標明確、單一 scope | `--skill={role} --task=TASK_XXX` |
+| solo | 需多角度分析 | `--formation=solo --skill=strategy --task=TASK_XXX` |
+| squad | 多個獨立子任務可並行 | `--formation=squad --skill=blitz --task=TASK_XXX` |
+| legion | 有順序依賴或即時協調 | `--formation=legion --skill=forge --task=TASK_XXX` |
+
+### Project 命令
+
+| 命令 | 說明 | 執行方式 |
+|------|------|---------|
+| `k-cli project status` | 專案總覽 | 直接讀取 |
+| `k-cli project initialize` | 初始化子專案 `.kenaz/` 結構 | 直接執行 |
+| `k-cli project install <target>` | 安裝/更新模板檔案 | 直接執行 |
+
+```bash
+# 專案總覽
+k-cli project status
+
+# 初始化新子專案（core-path 自動從 CLI 位置推導）
+k-cli project initialize --project-path /path/to/new-project
+
+# 手動指定 core-path（覆蓋自動偵測）
+k-cli project initialize --project-path /path/to/new-project --core-path /other/KenazAI
+
+# 初始化但不 git init
+k-cli project initialize --project-path /path/to/project --no-git
+
+# dry-run：顯示會建立什麼
+k-cli project initialize --project-path /path/to/project --dry-run
+```
+
+`project status` 輸出內容：
+
+| 區塊 | 來源 | 資料 |
+|------|------|------|
+| 專案設定 | `.kenaz/project.yaml` | project_name、schema_version、core_path、tasks dir、logs dir |
+| Git 狀態 | `git` | branch、最後 commit、dirty files 數量 |
+| 任務統計 | `task-api.js stats` | backlog / active / done / blocked 數量、P0/P1 高亮 |
+
+`project initialize` 建立內容：
+
+| 項目 | 說明 |
+|------|------|
+| `.kenaz/project.yaml` | 專案配置（schema_version、project_name、core_path、路徑正規化為 `/`） |
+| `.kenaz/tasks/{backlog,active,done,blocked,cancel}/` | 任務目錄 |
+| `.kenaz/logs/{unit,solo,squad,legion,misc,legacy}/` | Formation log 目錄 |
+| `.gitignore` | 標準 gitignore（預設啟用，`--no-git` 跳過） |
+| `.gitattributes` | 行尾正規化（預設啟用，`--no-git` 跳過） |
+| `k-cli.md` | 使用指南（可用 `project install k-cli` 更新） |
+| `git init --initial-branch=main` | Git 初始化 + aliases + initial commit |
+
+```bash
+# 安裝/更新模板到現有專案
+k-cli project install k-cli
+
+# dry-run
+k-cli project install k-cli --dry-run
+```
+
+### 通用命令
+
+| 命令 | 說明 |
+|------|------|
+| `k-cli ping` | 健康檢查（顯示專案名稱、模式、core_path） |
+
+## 全域選項
+
+| Flag | 說明 |
+|------|------|
+| `--dry-run` | 驗證但不執行（適用所有寫入 / 調度命令） |
+| `--json` | 輸出 JSON 格式 |
+| `--project-path <path>` | 指定子專案路徑（使用 `.kenaz/project.yaml` 中的 `project_path` 值） |
+| `--auto` | 自動掃描模式（僅 `dispatch run`） |
+| `--force` | 跳過品質檢查（僅 `task create`） |
+| `--no-git` | 初始化時跳過 Git（僅 `project initialize`） |
+| `--core-path <path>` | 覆蓋自動偵測的 core 路徑（僅 `project initialize`） |
+| `--help`, `-h` | 顯示幫助 |
+
+## 架構
+
+```
+k-cli/
+├── README.md              # 本文件
+├── package.json           # 依賴管理（deps: yaml）
+├── tsconfig.json          # TypeScript 配置
+├── src/                   # TypeScript 原始碼
+│   ├── index.ts           # 入口 + 命令路由 + flag 解析
+│   ├── core/              # 共用基礎設施
+│   │   ├── types.ts       # ProjectInfo、CliFlags 型別定義
+│   │   ├── project.ts     # 專案偵測（core / sub-project / unknown）
+│   │   ├── process.ts     # nodeProcess — 統一 process spawner
+│   │   ├── spawn.ts       # spawnClaude — Claude CLI 直接啟動器
+│   │   └── output.ts      # 輸出格式化（table / JSON）
+│   ├── specialist/        # Specialist 功能
+│   │   ├── list.ts        # 列出 Specialist + prompt（直接）
+│   │   └── run.ts         # 啟動 Specialist（spawnClaude）
+│   ├── task/              # 任務管理功能
+│   │   ├── list.ts        # task list（直接 task-api.js）
+│   │   ├── get.ts         # task get（直接 task-api.js）
+│   │   ├── create.ts      # task create（spawnClaude + Ansuz + Amelia）
+│   │   ├── submit.ts      # task submit（直接 task-api.js，無 Claude 依賴，TASK_2147）
+│   │   ├── update.ts      # task update（直接 task-api.js）
+│   │   └── delete.ts      # task delete（直接 task-api.js）
+│   ├── dispatch/          # Formation 調度功能
+│   │   ├── run.ts         # dispatch run（spawnClaude + Ansuz + headless.js）
+│   │   └── status.ts      # dispatch status（直接讀 log）
+│   └── project/           # 專案管理功能
+│       ├── status.ts      # project status（含 project.yaml 詳情）
+│       ├── initialize.ts  # project initialize（建立 .kenaz/ + Git）
+│       └── install.ts     # project install（安裝/更新模板）
+├── templates/             # 可安裝的模板檔案
+│   └── k-cli.md           # k-cli 使用指南
+└── dist/                  # 編譯輸出（npm run build）
+```
+
+### 內部呼叫關係
+
+```
+k-cli
+  │
+  ├─ 直接呼叫（讀取）
+  │   ├─ specialist/list   → fs.readdir(.specialist/) + session.js
+  │   ├─ task/list, get    → .collaboration/core/task-api.js
+  │   ├─ task/delete       → 直接 rm YAML 檔案（不限狀態）
+  │   ├─ dispatch/status   → .kenaz/logs/ 或 .formation/logs/ + log-reader.js
+  │   └─ project/status    → .kenaz/project.yaml + task-api.js stats + git commands
+  │
+  ├─ spawnClaude（Ansuz 決策）
+  │   ├─ task/create       → Ansuz 分析需求
+  │   │                       → Agent tool subagent（Amelia 審查 + role）
+  │   │                       → task-api.js create（最終建立）
+  │   ├─ dispatch/run      → Ansuz 讀 role + 判斷陣型
+  │   │   TASK_XXX            → headless.js --skill={role} --task=TASK_XXX
+  │   └─ dispatch/run      → Ansuz 掃 backlog + 逐個 dispatch
+  │       --auto              → headless.js × N
+  │
+  └─ spawnClaude（Specialist 直接執行）
+      └─ specialist/run    → session.js（組裝 prompt）+ spawnClaude
+```
+
+### spawnClaude 架構
+
+`core/spawn.ts` 是 k-cli 的核心，直接啟動 Claude CLI 子進程：
+
+```
+spawnClaude(opts)
+  ├─ detectClaudeCmd()      → 偵測 claude CLI 路徑（Windows: .cmd / .exe）
+  ├─ getClaudeEnv()         → 清理環境變數（刪除 CLAUDECODE 避免嵌套檢測）
+  │   └─ detectGitBash()    → Windows: 偵測 git-bash 路徑
+  └─ spawn(claude, args)    → stdin pipe prompt, stream-json 輸出
+```
+
+### Git 流程（自動觸發鏈）
+
+```
+k-cli dispatch run TASK_XXX
+  └→ Ansuz → headless.js
+       ├─ auto-claim（backlog → active）
+       ├─ 依賴預檢
+       ├─ 保存當前分支 → .formation/.dispatch-branch
+       ├─ spawnClaude(agent) 執行任務
+       └─ agent exit 0 → 自動觸發：
+            ├─ ensureTaskComplete → task-api complete
+            └─ postComplete()
+                 ├─ archive（done/ 超過 10 個 → archived/）
+                 └─ gitBranchAndMerge()
+                      ├─ stash 未提交變更
+                      ├─ checkout -b task/task_xxx
+                      ├─ unstash + git add + commit
+                      ├─ checkout {userBranch}
+                      ├─ merge task/task_xxx --no-ff
+                      └─ 提示: merge to main when ready
+```
+
+| 階段 | 誰處理 | 自動/手動 |
+|------|--------|----------|
+| claim | headless.js | 自動 |
+| agent 執行 | headless.js → spawnClaude | 自動 |
+| task complete | headless.js ensureTaskComplete() | 自動 |
+| archive | post-complete.js | 自動 |
+| task branch + commit | post-complete.js gitBranchAndMerge() | 自動 |
+| merge 到 user branch | post-complete.js | 自動 |
+| merge 到 main | **用戶** | **手動** |
+
+## Dry-Run 行為
+
+`--dry-run` 適用於所有有副作用的命令：
+
+| 命令 | dry-run 行為 |
+|------|-------------|
+| `specialist run` | 組裝 prompt → 顯示 agent + prompt 長度 → **不 spawn Claude** |
+| `dispatch run` | 組裝 Ansuz prompt → 顯示模式 + 資訊 → **不 spawn Ansuz** |
+| `task create` | 組裝 Ansuz prompt → 顯示將建立的任務資訊 → **不啟動 Ansuz** |
+| `task update` | 組裝 task-api args → 顯示將更新的內容 → **不呼叫 task-api** |
+| `task delete` | 組裝 task-api args → 顯示將刪除的任務 → **不呼叫 task-api** |
+
+## 專案偵測邏輯
+
+`resolveProject` 使用明確偵測，不猜測、不 fallback、不向上搜尋目錄：
+
+| 偵測條件 | 模式 | core_path |
+|---------|------|-----------|
+| 有 `.collaboration/tasks/` | `core` | 當前目錄 |
+| 有 `.kenaz/project.yaml`（無 `.collaboration/tasks/`） | `sub-project` | yaml 中的 `core_path` 欄位 |
+| 以上都沒有 | `unknown` | 當前目錄 |
+
+## 安裝 & 執行
+
+```bash
+# 編譯
+cd k-cli && npm install && npm run build
+
+# 執行
+node dist/index.js ping
+node dist/index.js project status
+
+# 建議建立 alias
+alias k-cli="node /path/to/KenazAI/k-cli/dist/index.js"
+```

package/core/k-cli/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "k-cli",
+  "version": "0.1.0",
+  "description": "KenazAI CLI tool — Specialist, Task, Dispatch operations",
+  "main": "dist/index.js",
+  "bin": {
+    "k-cli": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "bash test/run.sh"
+  },
+  "dependencies": {
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/core/k-cli/templates/k-cli.md

@@ -0,0 +1,91 @@
+# k-cli 使用指南
+
+本專案由 KenazAI k-cli 初始化管理。
+
+## 常用命令
+
+```bash
+# 健康檢查
+k-cli ping
+
+# 專案狀態
+k-cli project status
+
+# 任務管理（讀取）
+k-cli task list
+k-cli task list --status backlog
+k-cli task get TASK_XXX
+
+# 建立任務（Ansuz 分析 → Amelia subagent 審查 role → 建立）
+k-cli task create 幫我創建 hello_world.js 輸出 Hello World
+k-cli task create 實作登入 API 支援 OAuth2
+
+# 刪除任務（直接 rm，不限狀態）
+k-cli task delete TASK_XXX
+
+# Specialist（positional args 作為 user prompt）
+k-cli specialist list
+k-cli specialist run --agent Ansuz 幫我檢查 git 狀態
+k-cli specialist run --agent Amelia 執行 TASK_XXX
+
+# Dispatch — 指定任務（讀 role → 判斷陣型 → headless.js 執行）
+k-cli dispatch run TASK_XXX
+
+# Dispatch — 自動掃描（掃 backlog → 按優先級逐個 dispatch）
+k-cli dispatch run --auto
+
+# 查看 dispatch 狀態
+k-cli dispatch status TASK_XXX --tail 50
+
+# 專案初始化（新子專案）
+k-cli project initialize
+k-cli project initialize --project-path /path/to/project --no-git
+
+# 安裝/更新模板
+k-cli project install k-cli
+```
+
+## Dispatch 流程
+
+```
+k-cli dispatch run TASK_XXX
+  └→ Ansuz 讀 role → 判斷陣型 → headless.js
+       headless.js 自動處理：
+       ├─ auto-claim（backlog → active）
+       ├─ 依賴預檢
+       ├─ agent 執行任務
+       ├─ task complete
+       └─ post-complete（archive + git branch + merge to user branch）
+```
+
+Git merge 到 main 需要用戶手動操作。
+
+## Task Create 流程
+
+```
+k-cli task create "描述"
+  ├─ k-cli 預先組裝 Ansuz + Amelia prompts
+  └→ spawnClaude(Ansuz)
+       ├─ 分析需求 + 整理任務草稿
+       ├─ Agent tool → Amelia subagent 審查 + 判斷 role
+       └─ task-api.js create（建立任務）
+```
+
+Amelia 審查透過 Claude 原生 Agent tool（subagent）執行，無需嵌套 CLI。
+
+## 全域選項
+
+| Flag | 說明 |
+|------|------|
+| `--json` | JSON 輸出 |
+| `--dry-run` | 驗證但不執行 |
+| `--auto` | 自動掃描模式（僅 dispatch run） |
+| `--force` | 跳過品質檢查（僅 task create） |
+| `--project-path <path>` | 指定專案路徑（使用 `.kenaz/project.yaml` 中的 `project_path` 值） |
+| `--help` | 顯示幫助 |
+
+## 更新此文件
+
+```bash
+k-cli project install k-cli
+```

package/core/k-cli/test/TEST_SPEC.md

@@ -0,0 +1,134 @@
+# k-cli Test Specification
+
+## 概述
+
+Build 後在 `test/sandbox/` 建立真實專案環境，跑完所有 k-cli 功能。
+每次 `npm test` 自動：清空 sandbox → 初始化 → 逐項測試 → 報告結果。
+
+## 執行方式
+
+```bash
+cd k-cli
+npm run build && npm test
+```
+
+## 前置條件
+
+- Claude CLI 可用（`task create` 和 `dispatch run` 會 spawnClaude）
+- `npm run build` 必須先執行
+
+## 測試環境
+
+- **Sandbox**: `test/sandbox/`（每次測試前清空重建）
+- **Core Path**: KenazAI 本體（`k-cli/../`）
+- **路徑參數**: 使用 `.kenaz/project.yaml` 中的 `project_path`（絕對路徑）
+
+## 11 個測試
+
+### Test 1: project initialize → verify → delete k-cli.md → verify → install
+- `k-cli project initialize --project-path test/sandbox/ --no-git`
+- 驗證：`.kenaz/project.yaml` 存在、`tasks/` 5 個狀態目錄存在、`logs/` 6 個陣型目錄存在、`k-cli.md` 存在
+- 刪除 `test/sandbox/k-cli.md`
+- 驗證：`k-cli.md` 不存在
+- `k-cli project install k-cli --project-path test/sandbox/`
+- 驗證：`k-cli.md` 重新出現、內容含 `k-cli`
+
+### Test 2: ping
+- `k-cli ping --project-path test/sandbox/`
+- 驗證：輸出含 `k-cli` 且含 `sub-project`
+
+### Test 3: project status
+- `k-cli project status --project-path test/sandbox/ --json`
+- 驗證：JSON 解析成功、含 `sub-project`
+
+### Test 4: specialist list
+- `k-cli specialist list --project-path test/sandbox/`
+- 驗證：輸出含 `Ansuz` 且含 `Amelia`
+
+### Test 5: task create × 3 → list → get
+建立 3 個簡單任務，驗證 Ansuz + Amelia subagent 流程：
+
+1. `k-cli task create "寫一個 Node.js 程式，console.log 輸出 Hello World" --project-path test/sandbox/`
+   - 驗證：輸出含 TASK_ID（記為 TASK_A）
+2. `k-cli task create "寫一個 Node.js 程式，計算 10+10 並輸出結果" --project-path test/sandbox/`
+   - 驗證：輸出含 TASK_ID（記為 TASK_B）
+3. `k-cli task create "寫一個 Node.js 程式，讀取當前目錄的檔案列表並印出" --project-path test/sandbox/`
+   - 驗證：輸出含 TASK_ID（記為 TASK_C）
+
+流程驗證（每個 create 都會經過）：
+- spawnClaude(Ansuz) → 分析需求 → Agent tool subagent(Amelia) 審查 + 判斷 role → task-api.js create
+
+建立後驗證：
+- `k-cli task list --project-path test/sandbox/`
+- 驗證：輸出含 TASK_A、TASK_B、TASK_C，總數 ≥ 3
+- `k-cli task get TASK_A --project-path test/sandbox/`
+- 驗證：輸出含 TASK_A 詳細資訊
+
+### Test 6: dispatch run（指定任務）
+- 使用 Test 5 的 TASK_A
+- `k-cli dispatch run TASK_A --project-path test/sandbox/`
+- 驗證：Ansuz 讀 role → 判斷陣型 → headless.js 執行，輸出含 TASK_A
+
+### Test 7: dispatch status（等待任務完成）
+- `k-cli dispatch status TASK_A --project-path test/sandbox/`
+- 輪詢直到任務完成（或 timeout）
+- 驗證：輸出含 TASK_A 相關資訊，最終狀態為 done
+
+### Test 8: dispatch run --auto（自動掃描）
+- `k-cli dispatch run --auto --project-path test/sandbox/`
+- 驗證：自動掃描 backlog，dispatch TASK_B 和 TASK_C（或剩餘待處理任務）
+- 驗證：輸出含掃描結果
+
+### Test 9: task delete → verify
+- 使用 Test 5 的 TASK_A
+- `k-cli task get TASK_A` → 驗證任務存在
+- `k-cli task delete TASK_A --project-path test/sandbox/`（直接 rm，不限狀態）
+- `k-cli task list --project-path test/sandbox/`
+- 驗證：TASK_A 不在列表中
+
+### Test 10: specialist run Amelia（簡單任務）
+- `k-cli specialist run --agent Amelia 列出 sandbox 專案的任務狀態 --project-path test/sandbox/`
+- 驗證：spawnClaude(Amelia) 執行成功，輸出含任務相關資訊
+
+### Test 11: --dry-run（全指令驗證）
+不實際執行，僅驗證 dry-run 輸出正確：
+
+1. `k-cli project initialize --project-path test/sandbox/ --dry-run`
+   - 驗證：輸出含 `dry-run`
+2. `k-cli task create "測試 dry-run" --project-path test/sandbox/ --dry-run`
+   - 驗證：輸出含 `dry-run`，不呼叫 spawnClaude
+3. `k-cli task delete TASK_B --project-path test/sandbox/ --dry-run`
+   - 驗證：輸出含 `dry-run`，任務仍存在
+4. `k-cli dispatch run TASK_B --project-path test/sandbox/ --dry-run`
+   - 驗證：輸出含 `dry-run`，不呼叫 spawnClaude
+5. `k-cli specialist run --agent Amelia 測試 --project-path test/sandbox/ --dry-run`
+   - 驗證：輸出含 `dry-run`，不呼叫 spawnClaude
+6. `k-cli project install k-cli --project-path test/sandbox/ --dry-run`
+   - 驗證：輸出含 `dry-run`
+
+## 結果格式
+
+```
+k-cli Test Suite
+════════════════════════════════
+[ 1/11] project init+install   ✅ PASS
+[ 2/11] ping                  ✅ PASS
+[ 3/11] project status        ✅ PASS
+[ 4/11] specialist list       ✅ PASS
+[ 5/11] task create × 3       ✅ PASS
+[ 6/11] dispatch run           ✅ PASS
+[ 7/11] dispatch status        ✅ PASS
+[ 8/11] dispatch run --auto    ✅ PASS
+[ 9/11] task delete             ✅ PASS
+[10/11] specialist run Amelia  ✅ PASS
+[11/11] --dry-run              ✅ PASS
+
+Result: 11/11 passed
+```
+
+失敗時顯示：
+```
+[ 5/11] task create × 3       ❌ FAIL
+  Expected output to contain "TASK_"
+  Got: "Error: ..."
+```