robsonprod/portfolio

從 OpenSpec 變更請求中實作任務

商店選取： 如果使用者指定了一個商店（商店是這台機器上註冊的獨立 OpenSpec 儲存庫）或者工作位於其中，請執行 openspec store list --json 來探索已註冊的商店 ID，然後在讀取或寫入規格與變更的命令（new change、status、instructions、list、show、validate、archive、doctor、context、schemas、view）中加上 --store <id>。一旦選定，請將 --store <id> 視為整個工作流程的固定設定。以下所有未指定範圍的範例都是簡寫：執行前請加上該旗標。例如，請執行 openspec status --change "<name>" --json --store "<id>"，而非下方顯示的無範圍形式。其他命令不支援此旗標。命令輸出的提示已包含此旗標；請在後續操作中保留它。若無商店，則命令針對最近的本地 openspec/ 根目錄運作。

專案檢查： 這些步驟預期專案已使用 OpenSpec。在執行第一個會寫入任何內容的步驟（new change、archive、sync specs 或撰寫 artifact 檔案）之前，請確認專案有根目錄：執行 openspec list --json（選取商店時加上 --store <id>，因為此時商店就是根目錄）並讀取 root。若有 root 物件，表示專案已設定完成。"root": null 則表示未設定——此處沒有 openspec/ 目錄，而 openspec new change 這類寫入操作可能會將其建立為副作用。此命令也會以非零值退出，這表示答案，而非 CLI 故障，因此請讀取 JSON，不要重試或繞過它。

有一種 "root": null 與設定無關：當 status 錯誤訊息以 Declared in 或 Invalid store declaration in 開頭，且指向此專案的 openspec/config.yaml（或 config.yml）時，表示該專案是透過其宣告的商店來使用 OpenSpec，但此機器無法解析該商店（商店未註冊，或 store: 行格式錯誤）。請勿將其視為未初始化而跳過以下分支：應在寫入前停止，並向使用者顯示該錯誤的 message 和 fix。

否則，若無根目錄，接下來發生的事情取決於如何進入此工作流程：

• 自動選取：您自己選擇了此工作流程，而使用者未提及 OpenSpec、未指定此技能，也未執行其斜線命令。請停止使用 OpenSpec，並像未安裝 OpenSpec 一樣正常回覆請求。請不要要求使用者設定任何東西，也不要提及 OpenSpec 設定。
• 明確的 OpenSpec 請求：使用者提及了 OpenSpec、指定了此技能，或執行了其斜線命令。請在寫入前停止，並詢問如何進行：設定此專案（openspec init）、指定他們已有的某個商店（--store <id>），或針對此請求不使用 OpenSpec 繼續進行。等待他們回答。

在兩個分支中，都不要將根目錄建立為副作用：切勿執行 openspec init，除非使用者要求；切勿手動建立 openspec/ 檔案；也不要讓任何命令建立它。

輸入： 可選，指定變更名稱（例如 /opsx:apply add-auth）。若省略，請檢查是否能從對話上下文推斷。若模糊或不明確，您必須提示可用的變更。

步驟

1. 選取變更

   若有提供名稱，則使用它。否則：

   • 若使用者提到某個變更，從對話上下文推斷
   • 若只有一個啟用中的變更，則自動選取
   • 若不明確，執行 openspec list --json 取得可用變更，並要求使用者選取一個

   務必宣告：「正在使用變更：<名稱>」以及如何覆蓋（例如 /opsx:apply <其他>）。

2. 檢查狀態以了解架構

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

   解析 JSON 以了解：

   • schemaName：正在使用的工作流程（例如 "spec-driven"）
   • planningHome、changeRoot 和 actionContext：規劃範圍和編輯限制
   • 哪個 artifact 包含任務（例如 spec-driven 的 "tasks"，其他請檢查 status）

3. 取得 apply 指示

   openspec instructions apply --change "<name>" --json
   

   這會回傳：

   • contextFiles：artifact ID 到具體檔案路徑的陣列（依架構而異——可能是 proposal/specs/design/tasks 或 spec/tests/implementation/docs）
   • 進度（總數、已完成、剩餘）
   • 任務清單，包含狀態、來源路徑和來源行號
   • 基於目前狀態的動態指示
   • 可選的 context：目前所選根目錄所需的專案指示輸入
   • 可選的 operationGuidance：目前 apply 的建議性指導方針
   • missingArtifacts（存在時）：缺少輸出的必要 artifact ID

   處理狀態：

   • 若 state: "blocked"：顯示訊息並暫停實作。
     • 若 missingArtifacts 不為空：建議完成缺少的 artifact。執行 openspec status --change "<name>" --json，選取下一個 ready 的 artifact（非 skipped 或 blocked），並使用 openspec instructions "<artifact-id>" --change "<name>" --json 取得其規則和範本。兩個命令都保留選取的 --store <id>。
     • 否則，遵循 CLI 指示，從現有的規劃 artifact 建立或修復架構配置的追蹤檔案。不要假設另一個 artifact 已準備就緒或在阻塞狀態下開始實作。
   • 若 state: "all_done"：回報所有追蹤的任務已完成，並建議在歸檔前進行適當的審查或驗證
   • 否則：繼續進行實作

   將 context 視為必要的提示層級輸入。閱讀並考慮它，並在實作時套用相關的專案事實、慣例和限制。 將 operationGuidance 視為可選的附加建議。閱讀並考慮每個條目，並遵循適用且與內建工作流程相容的條目。

   將這兩個欄位與 CLI 回傳的狀態、缺少的 artifact、任務、進度、contextFiles 和內建的 instruction 分開。它們不是任務完成的證據，不會取代內建指示，也不允許繞過阻塞狀態。若 context 與內建指示、明確的使用者選擇或 CLI 控制的值衝突，請回報衝突並保留控制值。若 guidance 不適用或與那些控制輸入衝突，請不要遵循它，並解釋原因。這些是提示層級的行為合約，而非可強制執行的檢查。

4. 讀取背景檔案

   讀取 apply 指示輸出中 contextFiles 下列出的每個檔案路徑。 檔案取決於所使用的架構：

   • spec-driven：proposal, specs, design, tasks
   • 其他架構：遵循 CLI 輸出的 contextFiles

   請勿將 context 或 operationGuidance 逐字複製到實作檔案或規劃 artifact 中，除非使用者另外要求。

5. 顯示目前進度

   顯示：

   • 正在使用的架構
   • 進度：「已完成 N/M 個任務」
   • 剩餘任務概覽
   • CLI 的動態指示

6. 實作任務（循環直到完成或受阻）

   對於每個待處理任務：

   • 顯示正在處理的任務
   • 進行所需的程式碼變更
   • 保持變更最小化且聚焦
   • 在編輯前，確認回傳的 sourcePath 和 line 處的核取方塊仍與任務描述相符；若不相符，請重新執行 apply 指示並使用重新整理後的位置
   • 在回傳的 sourcePath 和 line 處將任務標記為完成：- [ ] → - [x]
   • 重新執行 apply 指示並確認該任務現在已完成且進度已變更
   • 繼續下一個任務

   暫停，若：

   • 任務不清楚 → 要求澄清
   • 實作過程中發現設計問題 → 建議更新 artifact
   • 某個任務所需的工作超出規格和任務所描述的範圍，或者您想要丟棄、縮小、延後或接受指定行為的例外以使其符合 → 提出增加的範圍並詢問；不要默默地吸收
   • 遇到錯誤或阻礙 → 回報並等待指示
   • 使用者中斷

7. 完成或暫停時，顯示狀態

   顯示：

   • 本次工作階段完成的任務
   • 整體進度：「已完成 N/M 個任務」
   • 若全部完成：回報追蹤的任務已完成，並建議在歸檔前進行適當的審查或驗證
   • 若暫停：解釋原因並等待指示

實作期間的輸出

## 正在實作：<change-name>（架構：<schema-name>）

正在處理任務 3/7：<task description>
[...實作中...]
✓ 任務完成

正在處理任務 4/7：<task description>
[...實作中...]
✓ 任務完成

完成時的輸出

## 實作完成

**變更：** <change-name>
**架構：** <schema-name>
**進度：** 7/7 個任務已完成 ✓

### 本次工作階段已完成
- [x] 任務 1
- [x] 任務 2
...

所有追蹤的任務已完成。請在歸檔前根據需要審查或驗證變更。
您可以使用 `/opsx:archive` 來歸檔此變更。

暫停時的輸出（遇到問題）

## 實作已暫停

**變更：** <change-name>
**架構：** <schema-name>
**進度：** 已完成 4/7 個任務

### 遇到的問題
<問題描述>

**選項：**
1. <選項 1>
2. <選項 2>
3. 其他方法

您想要怎麼做？

護欄

• 持續處理任務直到完成或受阻
• 在開始前務必先讀取背景檔案（來自 apply 指示的輸出）
• 若任務不明確，請在實作前暫停並詢問
• 若實作過程中發現問題，請暫停並建議更新 artifact
• 保持程式碼變更最小化，且範圍僅限於每個任務
• 完成每個任務後立即更新任務核取方塊
• 遇到錯誤、阻礙或不明確的需求時暫停——不要猜測
• 當任務所需的工作超出規格描述時，提出增加的範圍並暫停——絕不默默地縮小、延後或簡化掉指定的行為
• 僅在指定行為完全實作完畢後，才將任務標記為 - [x]，而非部分完成或延後時
• 使用 CLI 輸出的 contextFiles，不要假設特定的檔案名稱
• 使用每個任務的 sourcePath 和 line 來更新其確切的核取方塊
• 請勿將 context 或 operation guidance 用作任務完成的證據
• 套用相關的專案背景；向控制工作流程的輸入回報衝突
• 考慮每個 guidance 條目；解釋任何不適用或有衝突的建議
• 請勿將執行階段的 context 或 operation guidance 複製到實作檔案或規劃 artifact 中
• 保留 CLI 控制的 blocked/ready/all-done 行為和完成標準

流暢工作流程整合

此技能支援「對變更執行動作」模型：

• 可隨時呼叫：在所有 artifact 完成之前（若任務存在）、在部分實作之後、與其他動作交錯進行
• 允許 artifact 更新：若實作過程中發現設計問題，建議更新 artifact——不受階段限制，可流暢運作