AmanVarshney01/tcut

提出一個新變更 – 在一個步驟內建立變更並產生所有文件。

我將建立一個包含以下文件的變更：

• proposal.md（什麼與為什麼）
• design.md（如何做）
• tasks.md（實施步驟）

準備實施時，執行 /opsx:apply

---

儲存庫選擇： 如果使用者指定了一個儲存庫（store，一個在這台機器上註冊的獨立 OpenSpec 儲存庫），或者工作屬於某個儲存庫，請執行 openspec store list --json 來發現已註冊的儲存庫 ID，然後在讀取或寫入規格和變更的指令（new change、status、instructions、list、show、validate、archive、doctor、context）中傳遞 --store <id>。其他指令不接受此旗標。指令輸出的提示訊息已自動加上該旗標；請在後續對話中保留它。如果沒有指定儲存庫，指令將作用於最近的本地 openspec/ 根目錄。

輸入： 使用者的請求應包含一個變更名稱（kebab-case）或他們想要建置內容的描述。

步驟

1. 如果未提供明確輸入，詢問他們想要建置什麼

   使用 AskUserQuestion 工具（開放式提問，無預設選項）詢問：

   「你想進行什麼變更？請描述你想建置或修復的內容。」

   根據描述，推導出一個 kebab-case 名稱（例如：「add user authentication」→ add-user-auth）。

   重要： 在了解使用者想要建置什麼之前，不要繼續進行。

2. 建立變更目錄

   openspec new change "<name>"
   

   這會在 CLI 解析出的規劃主目錄（包含 .openspec.yaml）中建立一個結構化的變更。

3. 取得文件建置順序

   openspec status --change "<name>" --json
   

   解析 JSON 以取得：

   • applyRequires：實施前需要的文件 ID 陣列（例如 ["tasks"]）
   • artifacts：所有文件及其狀態與相依性的清單
   • planningHome、changeRoot、artifactPaths 和 actionContext：路徑與範圍上下文。使用這些值，不要假設儲存庫本機路徑。

4. 依序建立文件直到可實施狀態

   使用 TodoWrite 工具 追蹤文件的進度。

   按照文件依賴順序循環處理（先處理沒有未完成依賴的文件）：

   a. 對於每個狀態為 ready（滿足所有依賴）的文件：

   • 取得指令：

     openspec instructions <artifact-id> --change "<name>" --json
     

   • 指令 JSON 包含：
     • context：專案背景（對你的限制 – 不要包含在輸出中）
     • rules：文件專屬規則（對你的限制 – 不要包含在輸出中）
     • template：輸出檔案要使用的結構
     • instruction：此文件類型的結構描述專屬指引
     • resolvedOutputPath：寫入文件的已解析路徑或模式
     • dependencies：已完成的文件，供上下文參考
   • 閱讀任何已完成的依賴檔案以取得上下文
   • 使用 template 作為結構，將文件寫入 resolvedOutputPath
   • 將 context 和 rules 作為限制條件 – 但不要將它們複製到檔案中
   • 顯示簡短進度：「已建立 」

   b. 持續直到所有 applyRequires 文件完成

   • 建立每個文件後，重新執行 openspec status --change "<name>" --json
   • 檢查 applyRequires 中的每個文件 ID，確認其在文件陣列中的 status 為 "done"
   • 當所有 applyRequires 文件都完成時停止

   c. 如果文件需要使用者輸入（上下文不明確）：

   • 使用 AskUserQuestion 工具 釐清
   • 然後繼續建立

5. 顯示最終狀態

   openspec status --change "<name>"
   

輸出

完成所有文件後，總結：

• 變更名稱與位置
• 已建立的文件清單及簡短說明
• 準備就緒：「所有文件已建立！準備開始實施。」
• 提示：「執行 /opsx:apply 或要求我實施，即可開始處理任務。」

文件建立指南

• 根據 openspec instructions 中的 instruction 欄位來處理每種文件類型
• 結構描述定義了每個文件應包含的內容 – 請遵循它
• 在建立新文件之前，先閱讀依賴文件以取得上下文
• 使用 template 作為輸出檔案的結構 – 填入其章節
• 重要：context 和 rules 是對你的限制，而非檔案的內容
  • 不要將 <context>、<rules>、<project_context> 區塊複製到文件內
  • 這些內容引導你撰寫，但永遠不應出現在輸出中

護欄

• 建立所有實施所需文件（由結構描述的 apply.requires 定義）
• 在建立新文件之前，務必先閱讀依賴文件
• 如果上下文極不明確，詢問使用者 – 但更傾向於做出合理的決定以保持進度
• 如果相同名稱的變更已存在，詢問使用者是要繼續還是建立新的
• 在繼續下一個文件之前，驗證每個文件檔案確實存在