unified-planning

name	unified-planning
version	1.0.0
description	Unified Planning Layer - 智能整合 spec-workflow 與 evolve PDCA
triggers	["plan","規劃","計畫","專案","project","feature","功能"]
dependencies	{"skills":["evolve"],"mcp":["spec-workflow"]}

Unified Planning Layer v1.0

單一入口，智能路由到最適合的規劃/執行機制

觸發方式

/plan [目標描述]
/plan [目標] --formal    # 強制使用 spec-workflow
/plan [目標] --quick     # 強制使用 evolve PDCA
/plan --from-spec [name] # 從已有 spec 執行任務
/plan --status           # 查看當前規劃狀態

核心架構

┌─────────────────────────────────────────────────────────────────┐
│                    Unified Planning Layer                        │
│                                                                  │
│  /plan [goal]                                                    │
│       │                                                          │
│       ▼                                                          │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                   Planning Router                           │ │
│  │                                                             │ │
│  │  分析目標複雜度：                                           │ │
│  │  • 大型功能/系統/架構 → spec-workflow (正式)               │ │
│  │  • 修復/改進/小功能 → evolve PDCA (快速)                   │ │
│  │  • 用戶指定 --formal/--quick 優先                          │ │
│  └────────────────────────────────────────────────────────────┘ │
│       │                                                          │
│       ├─── Quick Path ─────────────────────────────────┐        │
│       │                                                 │        │
│       │    evolve PDCA                                  │        │
│       │    Plan → Do → Check → Act → Memory            │        │
│       │                                                 │        │
│       └─── Formal Path ────────────────────────────────┘        │
│                                                                  │
│            spec-workflow                                         │
│            Requirements → Design → Tasks → Approval              │
│                              │                                   │
│                              ▼                                   │
│            Task Executor (evolve instances)                      │
│            For each task: /evolve [task] --from-spec            │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                  Shared Memory Layer                        │ │
│  │  .claude/memory/ ← 兩者共用，知識互通                       │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

路由邏輯

自動判斷 (預設)

條件	路由
包含「feature」「system」「architecture」「重構」「系統」	spec-workflow
預估影響 >10 個檔案	spec-workflow
預估時間 >4 小時	spec-workflow
包含「fix」「improve」「add」「修復」「改進」	evolve
單一明確任務	evolve

手動覆蓋

--formal    # 強制 spec-workflow，即使是小任務
--quick     # 強制 evolve PDCA，即使是大功能

執行流程

Path A: Quick (evolve PDCA)

/plan fix the login button
       │
       ▼
┌─────────────────────────────────────────┐
│  Router: 小任務 → evolve PDCA           │
└─────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  evolve PDCA 執行                        │
│                                         │
│  1. 搜尋 Memory 相關經驗                 │
│  2. Plan: 規劃修復步驟                   │
│  3. Do: 執行修復                         │
│  4. Check: 驗證結果                      │
│  5. Act: 記錄經驗到 Memory               │
└─────────────────────────────────────────┘
       │
       ▼
✅ 完成，經驗已儲存

Path B: Formal (spec-workflow)

/plan implement user authentication with OAuth
       │
       ▼
┌─────────────────────────────────────────┐
│  Router: 大功能 → spec-workflow          │
└─────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  spec-workflow 規劃                      │
│                                         │
│  1. 建立 specs/.specs/auth-system/       │
│  2. 撰寫 requirements.md                 │
│  3. 撰寫 design.md                       │
│  4. 產生 tasks.md (任務清單)             │
│  5. 請求審批 (Dashboard)                 │
└─────────────────────────────────────────┘
       │
       ▼ (審批通過後)
┌─────────────────────────────────────────┐
│  Task Executor                           │
│                                         │
│  For each task in tasks.md:             │
│    /evolve [task] --from-spec auth      │
│    - 執行單個任務                        │
│    - 更新 tasks.md 狀態                  │
│    - log-implementation 記錄            │
└─────────────────────────────────────────┘
       │
       ▼
✅ 所有任務完成，spec 標記為 DONE

Path C: From Spec (繼續執行)

/plan --from-spec auth-system
       │
       ▼
┌─────────────────────────────────────────┐
│  讀取 specs/.specs/auth-system/tasks.md  │
│                                         │
│  找到未完成的任務：                      │
│  - [ ] Task 3: Implement token refresh  │
│  - [ ] Task 4: Add logout endpoint      │
└─────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  依序執行剩餘任務                        │
│  /evolve "Implement token refresh"      │
│  /evolve "Add logout endpoint"          │
└─────────────────────────────────────────┘

任務銜接協議

tasks.md 格式 (spec-workflow 輸出)

## Tasks

- [x] 1. Setup project structure
      context: Basic Express setup
      acceptance: Server starts on port 3000

- [-] 2. Implement login endpoint
      context: |
        Use JWT for tokens
        See design.md#auth-flow
      acceptance: |
        - POST /api/login accepts email/password
        - Returns valid JWT on success
        - Returns 401 on failure

- [ ] 3. Implement token refresh
      context: Refresh token rotation
      acceptance: POST /api/refresh returns new tokens

evolve 讀取並執行

當 evolve 執行 --from-spec 任務時：

1. 解析 context: 載入相關設計文檔
2. 解析 acceptance: 設定驗收標準
3. 執行 PDCA: 帶著完整上下文執行
4. 更新狀態: - [ ] → - [x]
5. 記錄實作: 呼叫 log-implementation

共享 Memory

兩個機制共用同一個 Memory 系統：

.claude/memory/
├── learnings/      ← evolve 寫入成功經驗
├── failures/       ← evolve 寫入失敗教訓
├── decisions/      ← spec-workflow ADRs
├── patterns/       ← evolve 推理模式
├── strategies/     ← evolve 策略池
└── specs/          ← spec-workflow specs 連結 (NEW)
    └── README.md   # 指向 specs/.specs/

Memory 互通範例

1. spec-workflow 建立 auth-system 規格
   → 寫入 .claude/memory/decisions/003-auth-design.md

2. evolve 執行 Task 1
   → 搜尋 Memory 找到 003-auth-design.md
   → 應用設計決策
   → 完成後寫入 learnings/

3. evolve 執行 Task 2
   → 搜尋 Memory 找到 Task 1 的 learnings
   → 累積知識，避免重複踩坑

狀態查詢

/plan --status

┌─────────────────────────────────────────┐
│  📊 Planning Status                      │
│                                         │
│  Active Specs:                          │
│  ├─ auth-system (3/5 tasks done)        │
│  └─ api-redesign (pending approval)     │
│                                         │
│  Recent evolve sessions:                │
│  ├─ fix-login-button ✅ (2h ago)        │
│  └─ improve-perf ✅ (yesterday)         │
│                                         │
│  Memory stats:                          │
│  ├─ Learnings: 25 entries               │
│  ├─ Failures: 4 entries                 │
│  └─ Last updated: 10 min ago            │
└─────────────────────────────────────────┘

使用範例

範例 1: 快速修復

User: /plan fix the TypeScript compilation error in auth module

Agent:
🔀 路由分析：小型修復任務 → evolve PDCA

📋 開始執行...
[evolve PDCA 流程]
...
✅ 完成！錯誤已修復，經驗已記錄。

範例 2: 大型功能

User: /plan implement a complete user management system with RBAC

Agent:
🔀 路由分析：大型系統功能 → spec-workflow

📝 建立規格文檔...
- specs/.specs/user-management/requirements.md
- specs/.specs/user-management/design.md
- specs/.specs/user-management/tasks.md (12 tasks)

⏳ 等待審批...
請在 Dashboard 審核並批准規格。

[審批通過後]

🚀 開始執行任務...
Task 1/12: Setup user model ✅
Task 2/12: Implement CRUD endpoints ✅
...

範例 3: 強制模式

User: /plan add a simple button --formal

Agent:
🔀 用戶指定 --formal → spec-workflow

📝 建立規格文檔...
（即使是簡單任務也會完整走 spec-workflow 流程）

範例 4: 繼續執行

User: /plan --from-spec user-management

Agent:
📖 讀取 specs/.specs/user-management/tasks.md

剩餘任務：
- [ ] Task 8: Implement role assignment
- [ ] Task 9: Add permission checking middleware
- [ ] Task 10: Create admin dashboard

🚀 繼續執行...

最佳實踐

DO

• 讓 Router 自動判斷，大多數情況它是對的
• 大型功能使用 spec-workflow，獲得完整文檔
• 快速迭代使用 evolve，保持敏捷
• 定期檢查 --status 了解進度

DON'T

• 不要對小任務強制 --formal（過度設計）
• 不要對大功能強制 --quick（缺乏規劃）
• 不要忽略審批流程（spec-workflow 的價值）
• 不要跳過 Memory 搜尋（重複踩坑）

與其他工具整合

CLI

npx claude-starter-kit plan [goal] [options]

MCP Tools

• spec-workflow: 規格管理
• skillpkg: 技能習得
• evolve: PDCA 執行

Workflows

搭配 workflow 指令使用：

npx claude-starter-kit workflow plan    # 查看規劃最佳實踐
npx claude-starter-kit workflow execute # 查看執行最佳實踐