kenaz 0.3.18 → 0.3.20

package/core/.system/README.md

@@ -1,555 +1,14 @@
-# .system - 系統核心文檔總索引
+# .system - subsystem docs
 
-> **用途**: Kenaz AI 系統核心組件文檔中心
-> **建立日期**: 2026-02-13 | **更新**: 2026-02-19
-> **文檔版本**: v3.1
+Reference docs for the subsystems that are still live. Rules in `.rule/INDEX.yaml`, failure patterns in `.failure/INDEX.yaml`, commands in `.claude/commands/` and skills in `.claude/skills/` are self-describing; read them directly.
 
----
+| Doc | Subsystem |
+|---|---|
+| [collaboration/README.md](./collaboration/README.md) | Task system: `.kenaz/tasks/{status}/` YAML cards, `.collaboration/core/task-api.js` |
+| [specialist/README.md](./specialist/README.md) | Specialist system (`.specialist/`: Ansuz, Amelia) |
+| [assessment/README.md](./assessment/README.md) | Feature assessment reports (`.assessment/`) |
+| [githooks/README.md](./githooks/README.md) | Git hooks (`.githooks/`) |
+| [external-skills/README.md](./external-skills/README.md) | External skills (`.agents/skills/`) |
+| [archive/README.md](./archive/README.md) | Long-term archive (`.archive/`) |
 
-## 📋 系統架構總覽
-
-Kenaz AI 採用**模組化系統架構**，各子系統獨立運作且相互協作：
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│                      Kenaz AI 系統                            │
-│                                                               │
-│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │
-│  │  規則系統   │  │ Agent系統  │  │  記憶系統  │            │
-│  │   .rule/   │  │  .claude/  │  │  .memory/  │            │
-│  └────────────┘  └────────────┘  └────────────┘            │
-│                                                               │
-│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │
-│  │  任務系統   │  │ Formation  │  │  失敗學習  │            │
-│  │.collaboration/│ .formation/│  │  .failure/ │            │
-│  └────────────┘  └────────────┘  └────────────┘            │
-│                                                               │
-│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │
-│  │  Dashboard │  │ CLI Tools  │  │ Git Hooks  │            │
-│  │ dashboard/ │  │dev/scripts/│  │ .githooks/ │            │
-│  └────────────┘  └────────────┘  └────────────┘            │
-└──────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 🗂️ 子系統快速導航
-
-| 子系統 | 路徑 | 說明 | 狀態 |
-|--------|------|------|------|
-| [規則系統](#rule---規則系統) | `.rule/` | 最高優先級規則庫 | ✅ Active |
-| [Agent 系統](#agent-skills--commands---agent-定義與指令系統) | `.claude/` | Agent 定義與斜線指令 | ✅ Active |
-| [Sunny 系統](#sunny---內部系統開發-agent) | `.system/sunny/` | 內部系統開發特權 Agent | ✅ Active |
-| [失敗學習](#failure---失敗學習系統) | `.failure/` | 失敗經驗記錄與預防 | ✅ Active |
-| [記憶系統](#memory---記憶系統) | `.memory/` | 智能記憶與知識管理 | ✅ Active |
-| [Kenaz 主記憶](#kenaz---主記憶與文檔工具) | `.kenaz/` | 跨專案共享知識庫 | ✅ Active |
-| [Collaboration](#collaboration---新任務系統) | `.collaboration/` | 第二代任務管理系統 | ✅ Active (v3.x) |
-| [Pipeline](#pipeline---舊任務系統-legacy) | `dev/pipeline/` | 第一代任務系統 | ⚠️ Legacy |
-| [Formation](#formation---多陣型調度系統) | `.formation/` | 多陣型 Agent 調度 | ✅ Active |
-| [Dashboard](#dashboard---tauri-後端架構) | `dashboard/src-tauri/` | 桌面應用後端 | ✅ Active |
-| [CLI Tools](#cli-tools---開發工具集) | `dev/scripts/` | 開發與維護腳本 | ✅ Active |
-| [Git Hooks](#git-hooks---自動化系統) | `.githooks/` | Git 生命週期自動化 | ✅ Active |
-
----
-
-## Rule - 規則系統
-
-`.rule/` 是專案的**最高優先級規則庫**，定義所有 AI Agent 和人類開發者必須遵守的核心約束與標準。
-
-### 規則優先級
-
-當規則發生衝突時，按以下優先級順序執行：
-
-```
-1. .rule/*           ← 最高優先級（所有人必須遵守）
-2. CLAUDE.md         ← 專案級指令與工作流程
-3. .claude/skills/   ← Agent 行為定義
-4. .agents/skills/   ← 外部安裝的最佳實踐
-```
-
-### 目錄結構
-
-| 分類 | 說明 |
-|------|------|
-| `general/` | 通用規則（所有 Agent 適用） |
-| `pipeline/` | Pipeline 專用規則（任務執行、封存、自動更新） |
-| `code/` | 代碼規範（命名、結構、複用性、可維護性） |
-| `design/` | 設計規範（UI、UX、色彩系統） |
-| `architecture/` | 架構決策記錄（未來擴展） |
-| `business/` | 業務邏輯約束（未來擴展） |
-
-### 嚴重程度
-
-| 級別 | 說明 | 圖標 |
-|------|------|------|
-| **MUST** | 必須遵守，違反將導致拒絕合併 | 🔴 |
-| **SHOULD** | 應該遵守，除非有合理理由 | 🟡 |
-| **MAY** | 建議遵守，可依情況調整 | 🟢 |
-
-### 重要規則速查
-
-| 規則 ID | 標題 | 嚴重程度 | 說明 |
-|---------|------|---------|------|
-| **GEN-007** | 專案自包含原則 | 🔴 | 所有操作必須在專案目錄內 |
-| **AGT-001** | 記憶點優先 | 🔴 | 任務開始前檢查 .memory/ |
-| **AGT-005** | 失敗經驗查閱 | 🔴 | 失敗時必須查閱 .failure/ |
-| **PPL-107** | 工作啟動前展示計劃 | 🔴 | 必須向用戶展示計劃並等待確認 |
-| **PPL-111** | scope_paths 衝突檢測 | 🔴 | 並行任務不可有路徑衝突 |
-
-### 使用方式
-
-```bash
-# 讀取規則索引
-cat .rule/INDEX.yaml
-
-# 檢查相關規則
-cat .rule/general/agent-workflow.yaml  # 所有 Agent 必讀
-cat .rule/pipeline/task-execution.yaml  # Pipeline 任務必讀
-```
-
-**詳細文檔**：請參閱 [`rule/README.md`](./rule/README.md)
-
----
-
-## Agent Skills & Commands - Agent 定義與指令系統
-
-`.claude/` 是 Kenaz AI 專案的 **Agent 定義與指令系統**，提供完整的 AI Agent 管理框架。
-
-### 核心組件
-
-| 組件 | 說明 |
-|------|------|
-| `skills/` | Agent 角色定義（職責、能力、工作流程） |
-| `commands/` | 斜線指令觸發機制（如 `/Ansuz`, `/產品`） |
-| `hooks/` | Session 生命週期鉤子（自動初始化） |
-| `settings.json` | 權限管理與配置 |
-| `mcp.json` | MCP 整合（Cortex RAG 引擎） |
-
-### 現有 Agent
-
-| Agent | 指令 | 職責 |
-|-------|------|------|
-| Formation Lead | `/lead` | 需求分析、陣型調度、結果追蹤 |
-| Product Manager | `/產品` | 需求分析、PRD 撰寫、任務規劃 |
-| Designer | `/設計` | UI/UX 設計、設計規範 |
-| Developer | - | 前端開發（React/TypeScript） |
-| Backend Engineer | `/後端` | 後端開發（Python/FastAPI） |
-| Sunny | `/sunny` | 內部系統開發（特權模式） |
-
-### Lead vs Worker 模式
-
-- **Lead Agent（溝通者）**：理解需求、調度執行、匯報結果（不直接寫代碼）
-- **Worker Agent（執行者）**：接收明確任務、執行技術工作、返回結果
-- **混合 Agent**：既可協調也可執行（如 Dev Agent）
-
-### 使用方式
-
-```bash
-# 在 Claude Code 中輸入斜線指令觸發 Agent
-/產品  # 啟動 Product Manager
-/dev   # 啟動 Dev Agent
-
-# 新增 Agent
-1. 建立 .claude/skills/<agent_name>/SKILL.md
-2. 建立 .claude/commands/<指令名>.md
-3. 更新 CLAUDE.md 註冊 Agent
-```
-
-**詳細文檔**：請參閱 [`agent-skills/README.md`](./agent-skills/README.md)
-
----
-
-## Sunny - 內部系統開發 Agent
-
-Sunny 是專門處理 Kenaz AI **內部系統開發**的特權 Agent。
-
-### 為什麼需要 Sunny？
-
-正常開發流程（PM → Design → Dev → QA）適用於產品功能開發，但當需要修改**系統本身**（如 `.collaboration/`、`.rule/`、`.formation/`）時，流程規則會產生矛盾。Sunny 解決這個 bootstrapping 問題。
-
-### 規則優先級
-
-```
-1. .rule/*          ← 絕對遵守（GEN-007, SEC-*, DATA-*）
-2. .system/sunny/*  ← Sunny 專屬規則
-3. CLAUDE.md        ← 可選擇性忽略
-```
-
-### 能力範圍
-
-| 允許 | 禁止 |
-|------|------|
-| 直接修改系統目錄 | 違反 `.rule/` 規則 |
-| 使用 Task 工具（跳過 TEAM-003） | 在專案目錄外輸出（GEN-007） |
-| 跳過展示計劃、用戶確認 | 違反安全/資料完整性規則 |
-| 不遵循標準開發流程 | |
-
-### 子系統
-
-| 路徑 | 說明 |
-|------|------|
-| `sunny/README.md` | 完整系統文檔與運作機制 |
-| `sunny/RULES.json` | 規則定義 |
-| `sunny/tools.json` | 工具註冊表 |
-| `sunny/knowledge/` | Claude Code 官方功能知識庫 |
-| `sunny/teammates/` | Agent Teams 啟動器（實驗性） |
-
-### 使用方式
-
-在 Claude Code 中輸入 `/sunny` 啟動，說「退出」結束。
-
-**詳細文檔**：請參閱 [`sunny/README.md`](./sunny/README.md)
-
----
-
-## Failure - 失敗學習系統
-
-`.failure/` 是專案的**失敗經驗學習系統**，記錄開發過程中的失敗模式並提供預防措施。
-
-### 核心理念
-
-**從失敗中學習，將錯誤轉化為規則**：
-```
-失敗 → 記錄到 .failure/ → 分析根因 → 如重複發生（>2 次）→ 提升為 .rule/
-```
-
-### 失敗分類
-
-| 分類 | 圖標 | 說明 |
-|------|------|------|
-| `agent-execution/` | 🤖 | Agent 執行失敗（空跑、無輸出、錯誤邏輯） |
-| `code-quality/` | 💻 | 代碼品質問題（bug、性能、可讀性） |
-| `architecture/` | 🏗️ | 架構決策失敗（設計缺陷、技術選型錯誤） |
-| `pipeline/` | ⚙️ | Pipeline 系統失敗（任務管理、佇列污染） |
-| `data-integrity/` | 📊 | 數據完整性問題（JSON 損壞、編碼錯誤） |
-
-### 核心規則
-
-**AGT-005**：失敗時必須查閱失敗經驗（定義於 `.rule/general/agent-workflow.yaml`）
-
-### 可用工具
-
-| 工具 | 用途 |
-|------|------|
-| `check_failures.ps1` | 任務開始前檢查相關失敗模式 |
-| `log_failure.ps1` | 任務失敗後記錄失敗經驗 |
-| `validate_json.js` | 驗證 JSON 文件完整性 |
-| `fix_json.js` | 一鍵修復 JSON（移除 BOM + 驗證 + 格式化） |
-
-### 使用方式
-
-```powershell
-# 任務開始前：檢查失敗模式
-.\.failure\tools\check_failures.ps1 -TaskID "TASK_XXX"
-
-# 任務執行中：驗證 JSON
-node .failure/tools/fix_json.js dev/pipeline/TASK_QUEUE.json
-
-# 任務失敗後：記錄經驗
-.\.failure\tools\log_failure.ps1 -Interactive
-```
-
-**詳細文檔**：請參閱 [`failure/README.md`](./failure/README.md)
-
----
-
-## Memory - 記憶系統
-
-`.memory/` 是 Kenaz AI 的**智能記憶系統**，模擬人腦記憶機制，提供持久化知識儲存與檢索。
-
-### 核心理念
-
-**自動化記憶、語義檢索、雙層架構**：
-```
-Agent 工作流程
-    ↓
-1. 任務開始前 → 查詢相關記憶（避免重複踩坑）
-2. 任務執行中 → 實時存取知識（模式、解決方案）
-3. 任務完成後 → 自動評估是否需要記憶
-```
-
-### 雙層架構
-
-| 層級 | 位置 | 性質 | 內容 |
-|------|------|------|------|
-| **主記憶** | `.kenaz/main-memory/` | 唯讀、全局 | Kenaz 系統知識、通用最佳實踐 |
-| **專案記憶** | `.memory/` | 讀寫、專案專屬 | 決策、失敗經驗、模式、洞察 |
-
-### 記憶類型
-
-| 類型 | 說明 |
-|------|------|
-| **decision** | 決策記錄（架構選型、技術決策） |
-| **failure** | 失敗經驗（Bug、錯誤、踩坑） |
-| **pattern** | 可複用模式（程式碼片段、流程範本） |
-| **insight** | 洞察理解（對系統的新認識） |
-| **context** | 狀態快照（專案當前進度） |
-| **reference** | 外部資源（文檔連結、API 參考） |
-
-### 使用方式
-
-```bash
-# 搜尋相關記憶
-node .memory/tools/memory-tools.js search "團隊調用"
-
-# 新增記憶
-node .memory/tools/memory-tools.js add \
-  --type decision \
-  --title "選擇 React 框架" \
-  --summary "因為生態系成熟、團隊熟悉度高"
-
-# 列出所有記憶
-node .memory/tools/memory-tools.js list
-```
-
-**詳細文檔**：請參閱 [`memory/README.md`](./memory/README.md)
-
----
-
-## Kenaz - 主記憶與文檔工具
-
-`.kenaz/` 是 Kenaz AI 的**系統級核心配置目錄**，提供跨專案共享的知識庫與文檔管理工具。
-
-### 核心組件
-
-| 組件 | 說明 |
-|------|------|
-| `main-memory/` | 跨專案共享的主記憶系統（唯讀） |
-| `docs/` | 系統文檔與索引工具 |
-| `cortex.yaml` | Kenaz Cortex RAG 引擎配置 |
-
-### 主記憶特性
-
-- **跨專案共享**：所有 Kenaz 專案共用的知識庫
-- **唯讀繼承**：專案可讀取但不可修改（由開發者維護）
-- **優先級繼承**：專案記憶 > 主記憶 > 系統預設
-
-### 文檔工具
-
-| 工具 | 用途 |
-|------|------|
-| `docs/build-index.js` | 自動生成系統文檔索引 |
-| `docs/update-all.ps1` | 批量更新所有文檔 |
-
-**詳細文檔**：請參閱 [`kenaz/README.md`](./kenaz/README.md)
-
----
-
-## Collaboration - 新任務系統
-
-`.collaboration/` 是 Kenaz AI 的**第二代任務管理系統**（v3.x），採用「目錄即狀態」架構。
-
-### 核心設計
-
-**設計理念**：
-- **目錄即狀態**：任務狀態由檔案所在目錄決定
-- **YAML 格式**：人類可讀，支援多行文字
-- **雙層 API**：task-api.js（完整功能）+ task-api-json.js（JSON 輸出）
-- **向後相容**：與舊 TASK_QUEUE.json 格式相容
-
-### 目錄結構
-
-```
-.collaboration/
-├── core/                    # 核心 API
-│   ├── task-api.js          # 主 API（CLI）
-│   └── task-api-json.js     # JSON 輸出（Dashboard 用）
-├── tasks/                   # 任務儲存
-│   ├── active/              # 進行中
-│   ├── done/                # 已完成
-│   ├── blocked/             # 已阻塞
-│   └── archived/            # 已封存
-└── config/                  # 配置與模板
-```
-
-### 使用方式
-
-```bash
-# 建立任務
-node .collaboration/core/task-api.js create \
-  --title "實作功能 X" \
-  --priority P1 \
-  --role developer
-
-# 查詢任務
-node .collaboration/core/task-api.js get TASK_XXX
-
-# 更新狀態
-node .collaboration/core/task-api.js update TASK_XXX --status done
-```
-
-**詳細文檔**：請參閱 [`collaboration/README.md`](./collaboration/README.md)
-
----
-
-## Pipeline - 舊任務系統 ⚠️ LEGACY
-
-`dev/pipeline/` 是 Kenaz AI 的**第一代任務管理系統**，採用 JSON + YAML 雙格式設計。
-
-### ⚠️ 系統狀態
-
-| 狀態 | 說明 |
-|------|------|
-| **Legacy** | 傳統系統，保留供排程器使用 |
-| **相容支援** | 目前仍可使用，但功能凍結 |
-| **逐步淘汰** | 未來將全面遷移到 `.collaboration/` |
-
-### 關鍵差異（vs 新系統）
-
-| 特性 | 新系統 | 舊系統 |
-|------|--------|--------|
-| **格式** | YAML + 目錄 | JSON + YAML |
-| **路徑鎖定** | ❌ 無 | ✅ lock_manager.py |
-| **依賴解析** | ⚠️ 基礎 | ✅ 完整（拓撲排序） |
-| **並行衝突檢測** | ❌ 無 | ✅ 自動 |
-
-### 適用場景
-
-- Multi-Agent 並行開發（需路徑鎖定）
-- 排程器自動化（需依賴解析）
-
-**詳細文檔**：請參閱 [`pipeline/README.md`](./pipeline/README.md)
-
----
-
-## Formation - 多陣型調度系統
-
-`.formation/` 是 Kenaz AI 的 **Agent 部署陣型系統**，根據任務規模動態選擇最佳調度策略。
-
-### 核心理念
-
-**「合適的陣型 = 最佳的效率與成本平衡」**
-
-### 5 種陣型
-
-| 陣型 | 說明 | 適用場景 | Agent 數量 |
-|------|------|----------|-----------|
-| **unit** | 單人執行 | 簡單任務、不需協作 | 1 |
-| **solo** | 分段執行（輪次制）| 中等任務、多步驟 | 1-3（輪流） |
-| **squad** | 輕量團隊（委派制）| 複雜任務、低耦合 | 2-5 |
-| **legion** | 重火力團隊（即時協作）| 高耦合、需即時溝通 | 2-10 |
-| **legacy** | 排程器模式（舊系統）| Pipeline 自動化 | N（排程器調度） |
-
-### Formation Lead
-
-透過 `/lead` 指令啟動 Formation Lead Agent：
-- 自動分析任務規模
-- 選擇最佳陣型
-- 調度 Agent 執行
-- 追蹤結果與回報
-
-**詳細文檔**：請參閱 [`formation/README.md`](./formation/README.md)
-
----
-
-## Dashboard - Tauri 後端架構
-
-`dashboard/src-tauri/` 是 **Kenaz AI Desktop Application** 的核心服務層。
-
-### 技術棧
-
-- **Rust + Tauri**：桌面應用框架
-- **Axum**：HTTP Server（Web 模式）
-- **Portable-Pty**：終端會話管理
-- **State Management**：Tauri State + Axum Shared State
-
-### 核心功能
-
-| 功能 | 說明 |
-|------|------|
-| **Tauri Commands** | 桌面應用 IPC（前端呼叫 Rust） |
-| **HTTP Server** | Web 模式 API |
-| **PTY Server** | 終端會話管理 |
-| **Scheduler 協調** | Multi-Agent 排程器管理 |
-| **自動更新** | 應用版本檢查與安裝 |
-
-### Feature Modules
-
-| 模組 | 路徑 | 職責 |
-|------|------|------|
-| **Script Manager** | `features/script/` | Tauri Commands |
-| **HTTP Server** | `features/http/` | Axum Web API |
-| **PTY Server** | `features/pty/` | 終端管理 |
-| **Scheduler** | `features/scheduler/` | 排程器協調 |
-
-**詳細文檔**：請參閱 [`dashboard/README.md`](./dashboard/README.md)
-
----
-
-## CLI Tools - 開發工具集
-
-`dev/scripts/` 是 Kenaz AI 的**開發與維護工具集**，提供初始化、排程、維護三大類工具。
-
-### 工具分類
-
-| 類別 | 工具 | 說明 |
-|------|------|------|
-| **初始化** | `INIT_PROJECT.bat` | 初始化新專案（清理 Pipeline） |
-|  | `INIT_GIT.bat` | 初始化 Git 倉庫與配置 |
-|  | `SETUP_RAG.bat` | 設置 RAG 引擎（kenaz-cortex） |
-|  | `SETUP_MCP.bat` | 設置 MCP Server（Claude Code 整合） |
-|  | `SETUP_GIT_HOOKS.bat` | 設置 Git Hooks |
-| **排程** | `START_DEV_AGENT.bat` | 單 Agent 開發（自我增強模式） |
-|  | `START_MULTI_AGENT.bat` | 多 Agent 並行開發 |
-|  | `RUN_ONCE.bat` | 單次執行（不含自我增強） |
-| **維護** | `check_queue.ps1` | 檢查任務佇列狀態 |
-|  | `clean_logs.ps1` | 清理執行日誌 |
-
-### 使用方式
-
-```powershell
-# 初始化新專案（首次執行）
-.\dev\scripts\INIT_PROJECT.bat
-
-# 啟動單 Agent 開發
-.\dev\scripts\START_DEV_AGENT.bat
-
-# 啟動多 Agent 並行開發
-.\dev\scripts\START_MULTI_AGENT.bat
-```
-
-**詳細文檔**：請參閱 [`cli-tools/README.md`](./cli-tools/README.md)
-
----
-
-## Git Hooks - 自動化系統
-
-`.githooks/` 是 Kenaz AI 的 **Git Hooks 自動化系統**，透過 Git 生命週期鉤子自動執行任務。
-
-### 核心功能
-
-| Hook | 觸發時機 | 功能 |
-|------|----------|------|
-| **post-commit** | commit 後 | RAG 引擎增量索引 |
-| **pre-commit** | commit 前 | 路徑鎖定檢查、代碼品質檢查 |
-| **post-merge** | merge 後 | RAG 索引重建 |
-
-### 雙平台支援
-
-| 平台 | 語言 | 路徑 |
-|------|------|------|
-| **Windows** | PowerShell | `.githooks/hooks-ps1/*.ps1` |
-| **Unix/Linux** | Bash | `.githooks/hooks-sh/*.sh` |
-
-### 使用方式
-
-```powershell
-# 設置 Git Hooks（自動偵測平台）
-.\dev\scripts\SETUP_GIT_HOOKS.bat
-
-# 或手動設置
-git config core.hooksPath .githooks/hooks-ps1  # Windows
-git config core.hooksPath .githooks/hooks-sh   # Unix/Linux
-```
-
-### RAG 引擎整合
-
-- **增量索引**：只索引變更的檔案（節省時間）
-- **自動重建**：merge 後自動重建索引（確保一致性）
-- **背景執行**：不阻塞 commit 流程
-
-**詳細文檔**：請參閱 [`githooks/README.md`](./githooks/README.md)
-
----
-
-*建立日期: 2026-02-13 | 更新: 2026-02-19 | 文檔版本: v3.1*
+Retired and removed (2026-10): memory system (Synapse/Hippocampus/Cortex/Alaya), Formation unit/squad/legion dispatch (subagent dispatch only: `node .formation/tools/dispatch.js`), desktop Dashboard and Next.js frontend, `dev/pipeline/TASK_QUEUE.json` pipeline, Sunny.