| name | sdd-openspec |
| description | OpenSpec SDD 操作指引精靈。當使用者意圖使用 OpenSpec、提及 SDD 開發並選擇 OpenSpec、 或要求以規格驅動開發方式建立提案時觸發。 以選單方式呈現所有步驟，引導使用者完成從初始化到歸檔的完整流程， 並將每步操作記錄保存為 log 檔案。 |
| version | 1.0.5 |
| author | lazyjerry |
OpenSpec 操作指引精靈
引導使用者完成 OpenSpec SDD 工作流程：從安裝、初始化到提案、實作、歸檔。
啟動流程
1. 環境檢查
執行以下終端指令確認 OpenSpec 是否已安裝：
openspec --version
檢測並更新套件（建議每次啟動先執行）：
npm install -g @fission-ai/openspec@latest
openspec --version
若專案已初始化過 OpenSpec，更新套件後建議同步整合指令檔：
cd <專案目錄>
openspec update
- 已安裝 → 顯示版本號，進入步驟選單
- 未安裝 → 顯示安裝指引後停止：
⚠️ 尚未偵測到 OpenSpec CLI。請先安裝：
npm install -g @fission-ai/openspec@latest
需要 Node.js 20.19.0 以上版本。
安裝完成後請重新啟動此精靈。
2. 詢問工作目錄
確認使用者的目標專案目錄：
請問要在哪個專案目錄執行 OpenSpec？
（輸入路徑，或按 Enter 使用目前工作區）
3. 顯示步驟選單
請讀取 references/menu.md 並原樣顯示，作為互動選單。
4. 執行步驟
依使用者選擇按需讀取對應小檔：
- Step 0:
references/steps/step-0-init.md
- Step 1:
references/steps/step-1-project.md
- Step 2:
references/steps/step-2-propose.md
- Step 3:
references/steps/step-3-spec-format.md
- Step 4:
references/steps/step-4-validate.md
- Step 5:
references/steps/step-5-apply.md
- Step 6:
references/steps/step-6-archive.md
- A:
references/steps/step-a-advanced.md
- C:
references/commands.md
取得選定步驟的完整指引後，依照該步驟：
- 顯示步驟說明：該步驟的目的與注意事項
- 提供提示詞模板：可直接使用的指令或提示
- 引導使用者輸入：收集必要資訊（如提案描述、變更名稱等）
- 協助執行：根據步驟類型，執行 CLI 指令或提供 AI 提示詞
- 記錄到 log：將使用者輸入與執行結果寫入 log 檔案
5. 步驟完成後
Log 機制
Log 檔案位置與命名
<專案根目錄>/sdd-logs/openspec-<YYYY-MM-DD>-<提案名稱>.md
- 首次啟動時建立
sdd-logs/ 目錄（如不存在）
- 提案名稱在 Step 2 建立提案時確定；Step 0～1 使用
init 作為暫時名稱
- 同一提案的所有步驟記錄在同一檔案中
Log 檔案初始化模板
首次建立時，請使用 references/log-format.md 的「Log 檔案初始化模板」。
每步驟追加格式
每完成一個步驟，請使用 references/log-format.md 的「每步驟追加格式」。
關鍵規則
| # | 規則 | 說明 |
|---|
| 1 | 先讀再做 | 每次執行步驟前，先讀取對應的小檔（references/menu.md、references/log-format.md、references/steps/step-*.md、references/commands.md） |
| 2 | 忠實記錄 | 使用者的每次輸入都必須記錄到 log |
| 3 | 不跳步驟 | 選單讓使用者自由選擇，但提醒建議順序 |
| 4 | 範圍控制 | 實作階段提醒使用者「請專注在 tasks.md 列出的項目」 |
| 5 | 使用新版指令 | slash command 使用 /opsx:* 格式 |
| 6 | 錯誤處理 | CLI 指令失敗時，顯示錯誤訊息並提供修正建議 |
