sdd-openspec

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

取得選定步驟的完整指引後，依照該步驟：

1. 顯示步驟說明：該步驟的目的與注意事項
2. 提供提示詞模板：可直接使用的指令或提示
3. 引導使用者輸入：收集必要資訊（如提案描述、變更名稱等）
4. 協助執行：根據步驟類型，執行 CLI 指令或提供 AI 提示詞
5. 記錄到 log：將使用者輸入與執行結果寫入 log 檔案

5. 步驟完成後

• 更新 log 檔案
• 顯示下一步建議
• 回到步驟選單

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 指令失敗時，顯示錯誤訊息並提供修正建議