vibe-sdlc-spec

name	vibe-sdlc-spec
description	Vibe-SDLC Phase 1：定義規格文件與計畫，協助撰寫與審查 PRD、SRD、SDD、API Spec、Dev Plan。 使用時機：專案啟動需要建立規格文件與計畫，或需要審查既有規格的完整性與一致性。
user_invocable	true

Phase 1：定義規格文件與計畫

目的

建立專案的完整真相來源（Single Source of Truth）。此階段應充分與開發者討論，生成高品質規格文件與計畫，所有後續工作皆以此為依據。

你的角色

你是 AI 助手（執行者）。在此階段你的職責是：

• 協助開發者撰寫與完善規格文件
• 交叉比對四份規格文件，找出不一致或遺漏
• 產出完整性審查報告

你不應該：在需求定義階段自行決定商業需求或技術選型，這些應該在需求完成後與開發者討論後進行決策。

前置條件

• 工作目錄已確立（可為空目錄；若本地 git 倉庫、CLAUDE.md、/docs 目錄皆不存在，skill 會自動進入「空專案初始化」流程）
• GitHub 倉庫可選（若缺，會在初始化面板中提示由使用者手動建立）

交付物

文件	檔名	存放路徑	類型	說明
文件入口與導航	00-Docs_Index.md	/docs/00-Docs_Index.md	必要	規格文件導航索引，列出所有文件清單、建立/更新時機、依賴關係
產品需求文件 (PRD)	01-1-PRD.md	/docs/01-1-PRD.md	必要	偏重產品面或客戶的需求及要求，可能衍生 UI/UX 需求
系統需求文件 (SRD)	01-2-SRD.md	/docs/01-2-SRD.md	必要	非功能性需求（NFR）、部署要求、約束與安全合規
系統設計文件 (SDD)	01-3-SDD.md	/docs/01-3-SDD.md	必要	系統架構、元件設計、數據模型、技術決策記錄（ADR）
遊戲設計文件 (GDD)	01-4-GDD.md	/docs/01-4-GDD.md	領域選用	遊戲專案專用：核心機制、數值設計、關卡設計。僅遊戲類專案需要
API 介面規格	01-5-API_Spec.md	/docs/01-5-API_Spec.md	必要	API 規格說明
API 介面合約	API_Spec.yaml	/docs/API_Spec.yaml	必要	OpenAPI 規格
UI/UX 設計文件	01-6-UI_UX_Design.md	/docs/01-6-UI_UX_Design.md	選用	UI/UX 設計規格（視覺風格、互動流程、Design Tokens），若 PRD 衍生 UI/UX 需求時建立。撰寫前 必須 先讀 references/UI_UX_Writing_Guidelines.md
UI Wireframe	ui/{page}.html	/docs/ui/*.html	選用	每個頁面一檔的 HTML + Tailwind CDN 視覺參考，由 01-6-UI_UX_Design.md 以 link 引用（規則詳見 UI_UX_Writing_Guidelines.md §9）
開發執行計畫	02-Dev_Plan.md	/docs/02-Dev_Plan.md	必要	里程碑、任務拆解、依賴關係
規格審查報告	03-Docs_Review_Report.md	/docs/03-Docs_Review_Report.md	必要	交叉比對結果、不一致與遺漏項目
CI/CD 規格文件	04-CI_CD_Spec.md	/docs/04-CI_CD_Spec.md	選用	CI Workflow 定義、品質閘門、Docker 部署配置（複雜專案建議獨立，Dev Plan 以連結引用）

重要：

• 每項規格都應賦予規格編號以利後續追蹤與討論。
• 每個任務都應賦予任務編號以利後續追蹤與討論。

UI/UX 設計文件撰寫準則

若需建立 01-6-UI_UX_Design.md，AI 助手必須先讀取 references/UI_UX_Writing_Guidelines.md 並遵循該指引的 9 條準則撰寫。指引重點：

1. 結構、狀態、欄位、呈現邏輯、元件庫指名：以 markdown 表格結構化描述（準則 1–8）
2. 流程圖：頁面跳轉、對話流、狀態機一律使用 Mermaid flowchart，不使用 ASCII 箭頭或圖片（準則 2）
3. 視覺空間感：使用 HTML + Tailwind CDN 獨立檔案，放置於 /docs/ui/，由 markdown 規格書以 relative link 引用（準則 9）
4. 每條準則均附自檢方法，AI 產出後必須對照指引末段 checklist 自檢

UI/UX 產出物結構：

• /docs/01-6-UI_UX_Design.md — 規格權威（markdown，AI 實作時以此為準）
• /docs/ui/{page}.html — 視覺參考（每個 §3.x 頁面對應一檔，低保真 wireframe 使用灰階 palette）

核心原則：markdown 規格書是實作權威，HTML wireframe 是視覺輔助。兩者衝突時以 markdown 為準。

版本修訂記錄格式規範

所有 /docs 規格文件皆須包含版本管理資訊，格式如下：

文件開頭（必要）

> **版本**：v{major}.{minor}
> **最後更新**：{YYYY-MM-DD}

文件結尾 — 版本修訂說明表格（必要）

---

## 版本修訂說明

| 版本 | 日期 | 修訂內容 |
|------|------|---------|
| v1.0 | 2026-03-16 | 初版定稿 |
| v1.1 | 2026-03-21 | {修訂摘要，列出新增/修改的章節與內容} |

版本號規則

變更類型	版本遞進	範例
新增功能需求（如新增 PRD-F-XXX）	minor +1	v1.0 → v1.1
修正錯誤、補充遺漏、格式調整	minor +1	v1.1 → v1.2
重大架構變更、破壞性修改	major +1	v1.2 → v2.0

修改規格文件時的必要動作

每次修改 /docs 下的規格文件時，必須同步更新以下三處：

1. 文件開頭的 版本號（遞進）
2. 文件開頭的 最後更新日期（改為當天）
3. 文件結尾的 版本修訂說明表格（新增一行，摘要說明本次修訂內容）

注意：OpenAPI YAML 檔（如 API_Spec.yaml）的版本號寫在 info.version 欄位，修訂說明寫在 info.description 欄位中。

參考範例

請參考 examples/docs/ 目錄下的文件。

操作步驟

步驟	執行者	操作	產出
0	開發者	建立文件入口：初始化 Docs Index，登錄預計建立的文件清單	00-Docs_Index.md
1	開發者	撰寫 PRD：定義功能清單、使用者故事、資料欄位，並與開發者討論並優化 PRD	01-1-PRD.md
2	開發者	撰寫 SRD：當 PRD 定義完成後，定義非功能性需求（NFR）、部署要求、約束與安全合規	01-2-SRD.md
3	開發者	撰寫 SDD：當 SRD 定義完成後，定義系統架構、技術棧選型、數據模型、設計決策記錄（ADR）	01-3-SDD.md
4	開發者	定義 API Spec：以 OpenAPI 格式定義所有端點、請求/回應結構	01-5-API_Spec.md, API_Spec.yaml
5	開發者	撰寫 Dev Plan：當 PRD、SRD、SDD、API Spec 定義完成後，拆解里程碑、任務清單、任務間依賴關係	02-Dev_Plan.md
6	開發者	確認以上文件均已提交至 /docs 目錄並推送至倉庫	Git commit & push to Github (or Gitlab)
7	AI 助手	交叉比對 /docs 下規格文件，產出完整性審查報告	審查報告
8	開發者	審閱報告，修正規格缺漏後重新提交	最終版規格

SRD 與 SDD 的分工：SRD 定義「系統應該達到的需求與約束」（如性能目標、安全要求），SDD 負責描述「如何設計系統來滿足這些需求」（如架構選型、元件設計）。

領域專用文件：遊戲類專案應在步驟 1 之後額外建立 01-4-GDD.md（遊戲設計文件），定義核心機制、數值設計與關卡設計。其他領域專用文件（如資料設計文件）可視需求於適當步驟加入。

Dev Plan 格式規範

可依需求規格相關文件(包含PRD、SRD、API Spec、...等)生成 Dev Plan(開發計畫)，然後與開發者討論並優化。

範例文件：02-Dev_Plan.md

核心設計原則

1. 面向 AI Agentic Coding：計畫以 Main Agent + Sub Agents (子代理) 為執行單位，非傳統人類團隊。
2. API First 契約驅動：前後端透過 API_Spec.yaml 解耦，Sub Agents 可高度並行開發。
3. Human Gate 機制：每個 Milestone 設有人類驗收門，由人類導演決定是否進入下一階段。

文件結構 (必須包含以下章節)

1. 角色定義 (Role Registry)：全文唯一角色定義來源（含 GitHub 帳號與認證配置）
2. 項目概況與時間表：里程碑 Gantt 圖 (Mermaid)、工作量估算
3. 里程碑定義：每個 Milestone 的目標、AI 執行策略、交付物、人類決策點
4. 任務清單：任務總覽表格 + 任務詳細描述 + 並行群組視覺化 (Mermaid)
5. 技術實施方案：前後端技術棧、數據庫與部署配置
6. 風險識別與應對：AI 開發視角的風險 (如 Regression、上下文不同步、除錯迴圈)
7. 質量保證計畫 (Vibe Check)：CI/CD 閘口、Human-in-the-Loop 審查
8. 溝通與協作：狀態同步中心、文件存取約定 (Single Source of Truth)

角色定義格式

必須在文件最開頭以表格定義所有角色，包含：角色代號、角色名稱、類別 (🧑 人類 / 🤖 AI)、GitHub 帳號、Git Author、說明。後續全文引用角色時必須使用此處定義的代號，禁止前後不一致。

建議角色配置：

類別	建議角色	GitHub 帳號	說明
🧑 人類	H-Director (導演)	@owner	最高決策、規格審查、Milestone 驗收、PR 合併
🧑 人類	H-Reviewer (審查員)	(同 Director 或獨立帳號)	特定領域審查（安全/合規性），可由 Director 兼任
🧑 人類	H-UxReviewer (UX 審查員)	(同 Director 或獨立帳號)	UX 相關審查，可由 Director 兼任或由 AI Agent 代理
🤖 AI	A-Main (主代理)	(同 Director 或獨立帳號)	統籌拆解 Issue、協調 Sub Agents、整合驗證
🤖 AI	A-Backend (後端子代理)	@ext-dev 或 @owner	專注後端 API、DB、ORM
🤖 AI	A-Frontend (前端子代理)	@ext-dev 或 @owner	專注 UI 組件、頁面、狀態管理
🤖 AI	A-QA (測試子代理)	(同 Director 或獨立帳號)	E2E 測試、覆蓋率
🤖 AI	A-DevOps (部署子代理)	(同 Director 或獨立帳號)	CI/CD、Docker、監控

多帳號協作：多個角色可共用同一 GitHub 帳號（單人專案），也可每個角色使用獨立帳號（多人或外部成員協作）。角色表中需填寫 GitHub 帳號 與 Git Author，並在 §1.5 中配置認證方式與 Repo 權限。詳細配置步驟請參考 帳號配置指南。

任務總覽表格格式

| ID | 任務名稱 | 優先級 | 負責角色 | 前置任務 | PR 策略 | 預估耗時 |
|----|---------|-------|---------|---------|--------|----------|
| T-101 | [任務名稱] | P0 | A-Backend | — | 與 T-102 合併 | ~N AI Sessions |
| T-102 | [任務名稱] | P0 | A-Backend | — | 與 T-101 合併 | ~N AI Sessions |
| T-103 | [任務名稱] | P0 | A-Frontend | — | 獨立 PR | ~N AI Sessions |
| T-104 | [任務名稱] | P0 | A-DevOps | T-102, T-103 | 獨立 PR | ~N AI Sessions |
| ⛳ M1 | M1 驗收門 | P0 | H-Director | T-103, T-104 | — | ~N HRH |

• 前置任務：直接在總覽表中列出依賴關係，使依賴鏈一目了然，無需翻閱詳細描述。若無前置任務填 —。
• PR 策略：標記任務的 PR 提交方式。同一 Agent 的多個無依賴任務應合併為一個 PR（如「與 T-102 合併」），其餘填「獨立 PR」。驗收門填 —。
• 預估耗時：AI 角色用 AI Sessions (一次完整 Agent 對話執行)；人類角色用 HRH (Human Review Hours)。
• 優先級：P0 為關鍵路徑必須完成、P1 為重要但非阻塞、P2可選任務但建議完成(時間允許時應該完成此任務)、P3可選任務(可做可不做，但若完成對專案可能有加分效果)。

任務詳細描述格式

每個任務以下列結構描述：

**T-{ID}：{任務名稱}**
- **任務描述**：概述該任務的目標
- **主要步驟**：
  1. 步驟一：具體操作描述
  2. 步驟二：具體操作描述
  3. ...
- **前置任務**：前置任務 ID，若無填 `（無）`
- **輸入**：依賴或參考的文件，若無填 `（無）`
- **產出**：此任務的輸出/產出文件或源碼，若無填 `（無）`
- **驗證**：
  - ✅ 自動：可在 CI 中自動執行的驗證（單元測試、lint、type check、build）
  - 👁️ 手動：需人工操作的驗證（視覺效果、裝置測試、外部 API 整合）
- **優先級**：任務的優先等級

主要步驟：以 numbered list 條列該任務的具體執行步驟，便於 Sub Agent 逐步對照執行。步驟應具體到可操作的程度（如「安裝依賴 X」、「實作 Y 端點」），而非抽象描述。

驗證分類：每個驗證條件必須標記為 ✅ 自動 或 👁️ 手動，明確區分 CI 可執行與需人工操作的項目。

並行與依賴規則

• 使用「並行群組 (G)」標記可同時執行的任務
• 同一群組內的任務可由不同 Sub Agents 同時開發
• 群組之間依序進行，以 ⛳ 驗收門 (Human Gate) 作為分界
• 使用 Mermaid flowchart 的 fork/join 語法視覺化並行關係

同 Agent 並行任務處理

• 當同一並行群組內有多個任務分配給同一 Agent（如 T-101、T-102 都是 A-Backend），這些任務在該 Agent 內部為依序執行（單一 Worktree 限制），但與其他 Agent 的任務仍為跨 Agent 並行。
• 同一 Agent 的多個無依賴任務，應合併為一個 PR 提交，避免同目錄多次 PR 造成合併衝突。
• Mermaid 並行圖中，應使用 subgraph 標示同 Agent 的依序執行關係，與跨 Agent 並行區分。

Dev Plan 常見錯誤防範

CI/CD 時序原則

• CI Workflow 必須在 M1 建立，不可延遲到最後的 Milestone。CI 是所有 PR 品質閘門的基礎，若 CI 只在最後才建立，前面所有 Milestone 的 PR 都沒有自動檢查保護，與「每次 PR 觸發 CI Gate」的品質保證計畫自相矛盾。
• CI 任務依賴前後端骨架（需要 package.json 和 npm scripts），但所有功能開發任務必須依賴 CI 就緒，確保功能 PR 提交時已有自動品質閘門。
• 正確的依賴鏈：骨架任務 → CI 任務 → 功能開發任務。
• 任務編號應反映此順序：CI 任務排在骨架之後、功能開發之前（例如骨架為 T-101~T-103、CI 為 T-104、功能開發為 T-105 起）。
• 當 CI/CD 配置較複雜（多 Job、E2E、Service Container 等），應獨立為 04-CI_CD_Spec.md，Dev Plan 以連結引用，避免 Dev Plan 過於冗長。

驗證條件設計原則

• 每個任務的驗證條件必須區分 ✅ 自動（CI 可執行）與 👁️ 手動（需人工操作），不可混為一談。
• 禁止將以下項目列為自動驗證條件：
  • 依賴外部 API Key 的測試（LLM、第三方服務）→ 單元測試必須使用 Mock Provider
  • 視覺效果驗證（動畫、顏色漸變、佈局）→ 自動驗證僅確認 CSS class 正確套用，視覺效果標記為手動驗證
  • 裝置特定功能（手機安裝 PWA、語音辨識、特定瀏覽器行為）→ 標記為手動驗證
  • 外部 API 回應時間（不可控因素）→ 改為驗證已配置 timeout 與重試機制，實際延遲在 staging 環境手動觀測

任務拆分原則

• 功能性質不同的工作不應合併為同一任務。例如「CI/CD + Docker + PWA」包含三種不同性質的工作，應拆為獨立任務並放到合理的 Milestone。
• 判斷標準：若一個任務的子項目屬於不同 Milestone 的時間點，則應拆分。

Bootstrap 階段 PR 規則

• M1 中 CI 任務（如 T-104）就緒前的初始化任務，其 PR 無法通過 CI 閘門。Dev Plan 應明確標注這些任務為「Bootstrap PR」，由 H-Director 直接審查合併，不經過 A-Main 初審與 CI 檢查。
• CI 就緒的分界點（通常是 CI 任務合併之後）必須在 Dev Plan 的 M1 里程碑說明中明確標示。

同 Agent 多任務合併原則

• 當同一並行群組中有多個任務分配給同一 Agent（如 T-101 + T-102 都是 A-Backend），由於單一 Agent 只有一個 Worktree，這些任務實際上為依序執行。
• 應在任務總覽表的「PR 策略」欄位中標注「與 T-XXX 合併為一個 PR」，並在 Mermaid 並行圖中使用 subgraph 標示 Agent 內部的依序關係。

手動驗證任務原則

• 當任務的驗證條件中包含 👁️ 手動 項目時，每個手動驗證項應建立獨立的 Issue，指派給對應的人類審查角色。
• 手動驗證 Issue 的前置任務為其對應的功能開發 Issue（功能完成後才能驗證）。
• 手動驗證 Issue 必須在 ⛳ 驗收門之前完成。

指派原則：

驗證類型	指派角色	範例
視覺效果、互動體驗、UI 佈局、動畫、裝置相容性	H-UxReviewer	預算血條顏色漸變、PWA 安裝體驗、語音按鈕手動測試
安全性、合規性、API 整合、資料正確性	H-Reviewer	LLM 引擎整合測試（需真實 API Key）、權限驗證
端到端業務流程、功能驗收	H-Director	完整記帳流程操作驗證

命名規範：手動驗證 Issue 標題格式為 [驗證] T-{ID} {驗證項目簡述}，例如：

• [驗證] T-201 Gemini/OpenAI 引擎整合測試
• [驗證] T-203 語音辨識瀏覽器相容性測試
• [驗證] T-302 預算血條視覺效果驗收

繪圖規範

文件中所有流程圖、時間表、依賴關係圖，一律使用 Mermaid 語法，禁止使用 ASCII Art。建議圖表：

• 里程碑時間表：gantt
• 任務分發流程：flowchart LR
• 並行群組視覺化：flowchart TB (fork/join 模式)

Git 協作策略 (Multi Sub Agent)

當多個 Sub Agents 並行開發時，Dev Plan 應包含以下 Git 協作規範：

Worktree 使用

• 每個 Sub Agent 應使用獨立的 Git Worktree 在各自的分支上開發，避免 checkout 切換衝突。
• Worktree 建立命令：git worktree add ../worktree-<agent> <branch>
• 主 Worktree 保留給 A-Main 執行整合工作。

分支命名規範

⛔ 嚴格禁止直接 push 至 main，所有變更一律透過分支 + PR 流程。main 為唯讀基準分支，dev/main-agent 為 A-Main 的快照分支（不承接任何工作 commit）。

條件	分支命名	生命週期	說明
有 Issue	feat/<agent>/issue-N-簡述	短期	所有 Issue-based 開發，PR 合併後刪除
無 Issue（小修）	chore/main-agent/<YYYYMMDD>-<簡述>	短期	typo、文案、聯調連續小修；從 origin/main 建出，PR 合併後刪除
A-Main 快照	dev/main-agent	永久（允許 force-update）	由 /vibe-sdlc-status 管理，僅承載 STATUS / dashboard 快照 commit。嚴禁承接工作 commit 或從其分出新分支

Per-issue 分支範例：

• feat/backend/issue-12-auth-api
• feat/frontend/issue-15-login-ui
• feat/devops/issue-20-docker-setup

Chore 分支範例：

• chore/main-agent/20260410-typo-readme
• chore/main-agent/20260410-integration-fixes

dev/main-agent 快照分支生命週期：

• 首次建立：git checkout -b dev/main-agent origin/main && git push -u origin dev/main-agent
• 後續維護：由 /vibe-sdlc-status 在彙整 STATUS 時 git reset --hard origin/main + 重新 commit + git push --force-with-lease
• 永遠不刪除，但不保證歷史線性（這是設計上的合約）
• 詳細規則見 /vibe-sdlc-status 的「A-Main 快照分支」章節與 /vibe-sdlc-dev 的「分支策略」

Bootstrap 階段（CI 建立前的 PR 處理）

M1 中，CI Pipeline 本身就是開發任務之一（如 T-104），在 CI 就緒前提交的初始化 PR 無法經過 CI 閘門檢查：

• Bootstrap PR（CI 建立前的任務）直接由 H-Director 審查合併，不經過 CI 閘門與 A-Main 初審。
• Sub Agent 建立 PR 時直接指定 reviewer：gh pr create --reviewer <H-Director-username>
• CI 就緒後（如 T-104 合併後），所有後續 PR 必須通過 CI 檢查，恢復標準雙層審查流程。

H-Director 通知機制

場景	通知方式
Bootstrap 階段	gh pr create --reviewer <H-Director-username>，GitHub 自動發送 Review Request 通知
標準流程	A-Main 初審通過後執行 gh pr edit --add-reviewer <H-Director-username>，GitHub 自動通知
Milestone 驗收	A-Main 在 GitHub Issue 中 @H-Director 並附上驗收檢查清單

PR 審查流程（標準流程，CI 就緒後適用）

flowchart LR
    SUB["Sub Agent<br/>gh pr create"] --> CI["GitHub Actions<br/>CI 檢查"]
    CI -->|通過| MAIN["A-Main 初審"]
    CI -->|失敗| SUB
    MAIN -->|通過| REQ["A-Main 執行<br/>gh pr edit<br/>--add-reviewer H-Director"]
    REQ --> DIR["H-Director<br/>收到 GitHub 通知<br/>終審 & Merge"]
    MAIN -->|駁回| SUB

1. Sub Agent 完成開發後提交 PR，目標分支為 main（或指定的整合分支）。
2. A-Main 進行初審：確認 PR 範圍僅限該 Agent 負責的目錄、CI 通過、無型別錯誤。
3. A-Main 初審通過後，執行 gh pr edit --add-reviewer <H-Director-username> 通知 H-Director。
4. H-Director 進行終審：Code Review 後決定 Merge 或要求修改。

合併順序與衝突處理

• 同一並行群組內的 PR，無依賴關係者 可依完成先後合併。
• 若合併後產生衝突，由 A-Main 負責 rebase 並解決衝突。
• 禁止 Sub Agent 直接修改其他 Agent 負責範圍內的檔案。

PR 範圍限制

Sub Agent 角色	允許修改的路徑
A-Backend	/backend/**
A-Frontend	/frontend/**
A-QA	/tests/**
A-DevOps	.github/**, docker/**, Dockerfile, docker-compose.yml
A-Main	全專案 (整合與修復用)

審查報告格式

當執行步驟「交叉比對規格文件」時，按以下格式產出報告至 /docs/03-Docs_Review_Report.md：

# 規格完整性審查報告

## 審查範圍
- 比對文件：00-Docs_Index.md, 01-1-PRD.md, 01-2-SRD.md, 01-3-SDD.md, 01-5-API_Spec.md, 02-Dev_Plan.md, ...

## 不一致項目
| 編號 | 文件   | 不一致描述 | 建議修正 |
|------|------|------------|----------|

> 註： 「文件」可以列出多個文件，若包含多個文件之間存在不一致，請將所有不一致項目列於此表格中。

## 遺漏項目
| 編號 | 文件 | 遺漏描述 | 應補充至 |
|------|------|----------|----------|

## 結論
- 不一致項目：N 項
- 遺漏項目：N 項
- 建議：[通過 / 需修正後重新審查]

完成條件

• /docs/00-Docs_Index.md 已建立，且所有文件皆已登錄
• 所有「必要」類型規格文件皆已提交至 /docs
• SRD 與 SDD 職責分離：SRD 僅含需求與約束，SDD 含架構設計與技術決策
• 所有規格文件皆包含版本修訂記錄（版本號 + 最後更新日期 + 修訂說明表格）
• AI 審查報告無未解決的遺漏項目
• 開發者確認規格定稿
• 開發計畫合理可行

空專案初始化（Bootstrap）

當使用者呼叫此 skill 時，必須先偵測專案是否為空，依下列層次判定並引導：

偵測層次

層次	偵測指令	缺什麼
L1	test -d .git	本地 git 倉庫
L2	git remote -v 輸出為空	GitHub / GitLab 遠端
L3	test -f README.md && test -f .gitignore	專案基礎檔
L3.5	test -f CLAUDE.md（且檔案非空）	Claude Code 專案指引
L4	test -d docs	/docs 目錄
L5	test -f docs/00-Docs_Index.md	Docs Index 與規格文件

觸發條件

僅在 L4 與 L5 皆缺失（即 /docs 目錄不存在或完全沒有規格文件）時觸發初始化面板。若使用者已有 /docs 內容，直接進入「行為指引」既有流程，不打擾。

初始化面板

偵測到空專案時，輸出下列面板並等待使用者選擇，禁止自動執行：

🌱 偵測到這是新專案，Vibe-SDLC 可協助初始化以下項目：
──────────────────────────────────────────────────
  {✅/❌} L1  git init（本地倉庫）
  {✅/❌} L2  GitHub remote 設定
  {✅/❌} L3  .gitignore / README.md
  {✅/❌} L3.5 CLAUDE.md（專案指引）
  {✅/❌} L4  /docs 目錄
  {✅/❌} L5  /docs/00-Docs_Index.md 骨架
  {✅/❌} A-Main 快照分支 dev/main-agent

請選擇：
  1️⃣  全部執行（推薦，新專案一鍵 bootstrap）
  2️⃣  只建立 /docs 骨架 + Docs Index（已有 git 時）
  3️⃣  我想逐項確認
  4️⃣  跳過初始化，直接進入規格撰寫流程

請選擇（1/2/3/4）：

{✅/❌} 依實際偵測結果填入（已存在為 ✅，缺失為 ❌）。

各選項行為

選項 1 — 全部執行：依下列順序執行，每一步執行前以一句話備註用途，執行失敗則停下報告：

1. L1 git init：若 .git/ 不存在，執行 git init 並建立初始 commit 佔位（空 commit 或含 README）
2. L3 基礎檔：若缺 .gitignore 或 README.md，建立最小骨架：
   • .gitignore：至少包含 .env, .env.*, node_modules/, dist/, build/, *.log, .DS_Store, docs/status/（若採用 STATUS 模式 B/C）
   • README.md：含專案名稱 + 一句話描述 + Vibe-SDLC 連結
3. L3.5 CLAUDE.md：呼叫下方「CLAUDE.md 初始化」流程
4. L4/L5 docs 骨架：建立 /docs/ 目錄，並從 examples/docs/00-Docs_Index.md 複製一份作為 /docs/00-Docs_Index.md，將「專案名稱」與文件清單改為占位符待使用者填寫
5. 快照分支：git checkout -b dev/main-agent（A-Main 快照分支，從 main 分出；若尚無 commit，先完成 step 1 的初始 commit）。建立後不立即在其上做任何 commit；後續由 /vibe-sdlc-status 管理
6. L2 GitHub remote：呼叫下方「GitHub Remote 建立流程」，讓使用者選擇由 AI 代為建立或自行手動

完成後輸出下一步建議：「初始化完成，接下來會協助你撰寫 PRD，請先告訴我專案要解決什麼問題。」

選項 2 — 只建 docs 骨架：只執行上方步驟 3、4（CLAUDE.md + docs 骨架），跳過 git 與基礎檔相關動作。適合已有 git repo 但剛從別的 SDLC 切換過來的專案。

選項 3 — 逐項確認：依序對每個 ❌ 項目詢問「是否執行？(y/N)」，使用者答 y 才執行該項。

選項 4 — 跳過：不做任何初始化動作，直接進入既有的「行為指引」流程（由使用者自行決定從哪份規格開始）。

CLAUDE.md 初始化流程

本 skill 提供骨架模板：templates/CLAUDE.md.template（含 {PROJECT_NAME}、{PROJECT_DESCRIPTION}、{BACKEND_STACK} 等占位符）。

情境 A：CLAUDE.md 不存在

1. 互動詢問三個最小必要資訊（其餘占位符保留，由使用者後續自行補）：
   • 「這個專案叫什麼名字？」→ 填入 {PROJECT_NAME}
   • 「一句話描述專案做什麼？」→ 填入 {PROJECT_DESCRIPTION}
   • （技術棧、STATUS 模式為選填，若使用者當下想好就填，否則保留占位符）
2. 從 templates/CLAUDE.md.template 讀取內容，置換占位符
3. 寫入 <project_root>/CLAUDE.md
4. 提示使用者「技術棧與 STATUS 版控策略的占位符請後續補上」

情境 B：CLAUDE.md 已存在但缺少 Vibe-SDLC 區塊

偵測方式：grep CLAUDE.md 是否包含 /vibe-sdlc 字串。若不包含：

1. 提示：「偵測到 CLAUDE.md 未引用 Vibe-SDLC 流程，是否要 append 相關區塊？(y/N)」
2. 使用者同意後，從 templates/CLAUDE.md.template 擷取「## Vibe-SDLC 流程」整段（包含核心原則），以 append 方式寫入既有 CLAUDE.md 末尾
3. 不覆蓋既有內容，只附加

情境 C：CLAUDE.md 已存在且已含 Vibe-SDLC 區塊

跳過，不動它。

GitHub Remote 建立流程

前置檢查：先執行 git remote -v，若已有 origin 指向有效遠端（非占位），則直接跳過整段流程。

若本地 git 有 commit 但無 remote，輸出下列選擇面板並等待使用者選擇：

🔗 GitHub Remote 尚未設定
──────────────────────────
選擇建立方式：
  A 由 AI 代為建立（執行 gh repo create，需要 gh 已登入）
  B 我要自己手動建立
  C 先跳過，稍後再設定

請選擇（A/B/C）：

選項 A — AI 代為建立：

1. 先檢查 gh 是否可用：
   • gh auth status 若失敗，提示使用者先執行 gh auth login，然後改選 B 或 C
   • 若 gh 未安裝，直接改選 B
2. 互動確認四個資訊：
   • Repo 名稱（預設為 basename $(pwd)，可覆寫）
   • Owner：帳號 or organization（預設為 gh api user --jq .login 取得的當前使用者，可覆寫）
   • 可見性：private / public / internal（預設 private）
   • 是否立即推送 main 與 dev/main-agent（預設 y）
3. 顯示即將執行的指令並請使用者最終確認，例如：

   即將執行：
     gh repo create <owner>/<name> --private --source=. --remote=origin --push
     git push -u origin dev/main-agent
   
   執行？(y/N)：
   

4. 使用者答 y 後執行；答 N 則改走選項 B（輸出手動指令）
5. 執行失敗（名稱衝突、權限不足等）時停下報告錯誤，並提供修正建議（改名稱 / 換 owner / 檢查 gh 權限）

選項 B — 使用者手動建立：

輸出完整指令清單供使用者複製：

請依序執行以下指令（可依需求調整參數）：

# 1. 建立 GitHub repo（擇一）
#   方式 A：使用 gh CLI
gh repo create <name> --private --source=. --remote=origin --push

#   方式 B：在 GitHub 網頁建立空 repo 後手動加 remote
git remote add origin [e-mail]:<owner>/<name>.git
git branch -M main
git push -u origin main

# 2. 將常駐分支推上遠端
git push -u origin dev/main-agent

設定完成後告訴我一聲，我會繼續後續流程。

輸出後暫停流程等待使用者回報，不進入後續 PRD 撰寫。

選項 C — 先跳過：

記錄「稍後再設定 remote」，繼續後續流程（進入 PRD 撰寫）。提醒使用者：「Phase 2 建立 Issues 時必須要有 remote，請在那之前完成 remote 設定。」

行為指引

初始化完成後（或偵測到非空專案時），依下列流程協助使用者：

1. 先檢查 /docs 目錄是否存在，以及已有哪些規格文件
2. 若 /docs/00-Docs_Index.md 不存在：建議先建立文件入口，作為後續文件的導航索引
3. 若規格文件尚未建立：詢問開發者想從哪份文件開始，協助撰寫
4. 若規格文件已存在：詢問開發者是要修改規格還是進行交叉比對審查
5. 修改既有規格文件時，必須同步更新該文件的版本號、最後更新日期與版本修訂說明表格（詳見「版本修訂記錄格式規範」）
6. 執行審查時，逐一讀取所有規格文件，系統性比對後產出報告
7. 檢查規格文件間的交互參考是否完整：
   • Docs Index 是否已登錄所有已建立的文件
   • PRD 各功能需求是否標注對應的 UI/UX 設計章節參考（如有 UI/UX 設計文件）
   • SRD 與 SDD 是否職責分離（SRD 僅含需求，SDD 含設計）
   • SDD 的架構設計是否與 API Spec 的端點定義一致
   • UI/UX 設計文件是否反向參考 PRD、SRD、API Spec
   • UI/UX 設計文件是否遵循 references/UI_UX_Writing_Guidelines.md 的 9 條準則（逐條列出符合/違反，違反項必須寫入審查報告）：
     • §1 結構分層正確（設計原則 → 頁面清單 → 單頁佈局）
     • §2 頁面跳轉／對話流／狀態機使用 Mermaid flowchart（無 ASCII 箭頭藝術或圖片）
     • §3 元件描述使用語意，無純方位詞（左上角／右側／下方等）
     • §4 互動元件列出完整狀態（default / hover / disabled / loading / error 等）
     • §5 表單欄位使用結構化表格（名稱 / 類型 / 必填 / 驗證規則 / 錯誤訊息 / 說明）
     • §6 呈現（樣式）與顯示邏輯（條件渲染）分開描述
     • §7 文件自足，無「如圖所示」類外部依賴描述
     • §8 已指名使用的 UI 元件庫與元件名稱（若專案使用元件庫）
     • §9 每個 §3.x 頁面有對應 /docs/ui/*.html wireframe 且 markdown 已 link 引用
     • §9.6 每個視覺型 §3.x.y 子元件章節有對應 ui/{page}.html#{anchor} link；HTML 對應 <section> 有 id 屬性
   • /docs/ui/*.html wireframe 是否包含 <meta name="fidelity"> 與 <meta name="spec-ref"> 標籤
   • UI/UX 規格書與 HTML wireframe 是否保持一致（Design Tokens、欄位、狀態描述無衝突）
8. 若為遊戲類專案，提醒開發者是否需要建立 GDD（01-4-GDD.md）
9. 審查完成且無遺漏後，提示開發者可進入 Phase 2（/vibe-sdlc-issues）