dev-plan

name	dev-plan
description	Generate a development plan with task breakdown and section 10 tracking tables
allowed-tools	Read, Write, Glob, Grep, Bash

開發計畫書產生器

G0 通過後，由 L1 產出標準化開發計畫書。

使用方式

/dev-plan <sprint-number> <project-name>

參數

• $0: Sprint 編號
• $1: 專案名稱

執行步驟

1. 讀取對應的提案書： !cat proposal/sprint$0-proposal.md 2>/dev/null || echo "找不到 Sprint $0 提案書"

2. 讀取開發計畫書範本： !cat .knowledge/templates/dev-plan.md.template 2>/dev/null || echo "範本未找到"

3. 建立規範文件（若不存在則建立，已存在則跳過）：

   ⚠️ 規範文件是 Code Review「對規範」的比對對象，缺少 = Review 品質打折。 必須在 dev-plan 產出時一併建立，不得延後。

   mkdir -p .knowledge/specs
   

   建立以下三個檔案（內容從提案書 + 技術方案提取）：

   檔案	內容	來源
   .knowledge/specs/api-design.md	API 端點清單、請求/回應格式、錯誤碼	提案書需求 + 技術方案
   .knowledge/specs/data-model.md	資料表定義、欄位型別、關聯、索引	技術方案 DB 設計
   .knowledge/specs/feature-spec.md	功能規格、用戶流程、邊界條件、驗收標準	提案書功能清單

   每個檔案格式：

   # {標題}
   
   > 版本: v1.0 | Sprint {N} | 最後更新: {YYYY-MM-DD}
   
   ## 概述
   {簡述}
   
   ## 詳細規格
   {具體內容}
   

4. 建立 Sprint Branch：

   BASE=$(git rev-parse --abbrev-ref HEAD)   # 記錄當前 base branch（main / master / 其他）
   git checkout -b sprint-$0
   

   若 sprint-$0 branch 已存在，輸出警告並跳過（冪等）。 $BASE 將寫入 dev-plan metadata，供 /sprint-close 使用。

5. 產出 proposal/sprint$0-dev-plan.md，包含：

   • 需求摘要（來自提案書）
   • 技術方案
   • 檔案變更清單
   • 介面設計（如需要）
   • 第 5 節：規範文件索引（指向 .knowledge/specs/ 下的三個檔案）
   • 第 6 節：任務拆解表（含依賴圖）
   • 驗收標準
   • 異常處理
   • 時程預估
   • 第 10 節：預建空表格（任務完成紀錄 / Review 紀錄 / Gate 紀錄）

第 10 節格式（強制）

⚠️ 此區域的表頭名稱與欄位順序被系統 parser (parseDevPlanSection10) 嚴格依賴。 不得更改表頭名稱、欄位順序、或子標題名稱。

## 10. 任務與審核紀錄（備查）

> 每個任務完成後記錄結果，每次 Review/Gate 通過後記錄決策。本區作為 Sprint 完整稽核軌跡。

### 任務完成紀錄

| 任務 | 完成日期 | 結果 | 備註 |
|------|---------|------|------|
| T1 | | | |
| T2 | | | |
（依第 6 節任務清單預建所有任務行）

### Review 紀錄

| Review 步驟 | 日期 | 結果 | Review 文件連結 |
|------------|------|------|---------------|
| UI 圖稿 Review | | | |
| 實作 Review | | | |
| 測試 Review | | | |
（依確認流程中的步驟預建行）

### Gate 紀錄

| Gate | 日期 | 決策 | 審核意見 |
|------|------|------|---------|
| G0 | | | |
| G1 | | | |
（依確認流程中的 Gate 預建行，空行 = 未審核）

欄位值規範（供後續 skill 填寫時遵守）

任務結果欄位（normalizeStatus 解析）：

值	系統狀態
✅ 完成	done
🔧 需修正	in_review
🔄 進行中	in_progress

Gate 決策欄位（decisionToStatus 解析）：

值	系統狀態
✅ 通過	approved
❌ 駁回	rejected
⚠️ 附條件通過	approved

Review 結果欄位：通過 / 不通過（目前僅存字串，不做狀態轉換）

日期格式：YYYY-MM-DD

Dev-plan Metadata（標題區）

dev-plan 標題區必須包含以下欄位（供其他 Skill 讀取）：

> **Base Branch**: {master / main / 其他}
> **Sprint Branch**: sprint-{N}