unified-planning

Unified Planning Layer v1.0

Single entry point, intelligently routes to the most suitable planning/execution mechanism

Trigger Method

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

Core Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    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/ ← 兩者共用，知識互通                       │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Routing Logic

Automatic Decision (Default)

Condition	Route
Contains "feature", "system", "architecture", "refactor", "system"	spec-workflow
Estimated impact >10 files	spec-workflow
Estimated time >4 hours	spec-workflow
Contains "fix", "improve", "add", "repair", "improve"	evolve
Single well-defined task	evolve

Manual Override

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

Execution Flow

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 (Continue Execution)

/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"          │
└─────────────────────────────────────────┘

Task Handoff Protocol

tasks.md Format (spec-workflow output)

## 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 reads and executes

When evolve executes --from-spec task:

Parse context: Load related design documents
Parse acceptance: Set acceptance criteria
Execute PDCA: Execute with full context
Update status: - [ ] → - [x]
Record implementation: Call log-implementation

Shared Memory

Both mechanisms share the same Memory system:

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

Memory Interoperability Example

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
   → 累積知識，避免重複踩坑

Status Query

/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            │
└─────────────────────────────────────────┘

Usage Examples

Example 1: Quick Fix

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

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

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

Example 2: Large Feature

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 ✅
...

Example 3: Forced Mode

User: /plan add a simple button --formal

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

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

Example 4: Continue Execution

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

🚀 繼續執行...

Best Practices

DO

Let Router decide automatically; it's right most of the time
Use spec-workflow for large features to get complete documentation
Use evolve for rapid iteration to stay agile
Regularly check --status for progress

DON'T

Don't force --formal for small tasks (over-engineering)
Don't force --quick for large features (lack of planning)
Don't skip the approval process (the value of spec-workflow)
Don't skip Memory search (repeating mistakes)

Integration with Other Tools

CLI

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

MCP Tools

spec-workflow: Spec management
skillpkg: Skill acquisition
evolve: PDCA execution

Workflows

Use together with the workflow command:

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

About this skill

Trigger Method

Core Architecture

Routing Logic

Automatic Decision (Default)

Manual Override

Execution Flow

Path A: Quick (evolve PDCA)

Path B: Formal (spec-workflow)

Path C: From Spec (Continue Execution)

Task Handoff Protocol

tasks.md Format (spec-workflow output)

evolve reads and executes

Shared Memory

Memory Interoperability Example

Status Query

Usage Examples

Example 1: Quick Fix

Example 2: Large Feature

Example 3: Forced Mode

Example 4: Continue Execution

Best Practices

DO

DON'T

Integration with Other Tools

CLI

MCP Tools

Workflows