miles990 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 任務時：
- 解析 context: 載入相關設計文檔
- 解析 acceptance: 設定驗收標準
- 執行 PDCA: 帶著完整上下文執行
- 更新狀態:
- [ ]→- [x] - 記錄實作: 呼叫
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 # 查看執行最佳實踐