formal-you/agent-skills-suite

變更（既有系統）

在現有的規格和程式碼庫中，新增一個受範圍限制、可審查的變更，而無需撰寫新的 產品需求文件（PRD）。一次變更會產生一個提案加上恰好一個四文件任務套件；品質驗證（QA） 通過後，經過確認的變更差異會被寫回規格文件中，提案則會被封存。此技能 以提示（prompt）優先：每個步驟都有手動備援方案，且打包的腳本是可選的輔助工具。

管線位置：spec-generator -> change -> task-decomposition -> plan-linter（閘門 1）-> review（閘門 2）-> dev -> qa -> converge -> 封存。

existing spec + bounded change
  -> .specs/change-context/standards.md        （standards_extract.py；隱含約束）
  -> .specs/changes/<change-id>/proposal.md    （生命週期：proposed -> applied -> archived）
  -> tasks/<change-id>/01..04                  （一個合約，一個套件）
  -> 閘門 1 plan-linter -> 閘門 2 review -> dev <-> qa -> converge -> 已封存提案

使用時機

• 現有的規格或已上線的程式碼庫需要進行增量變更：錯誤修正、小型功能、 行為調整、受範圍內的非功能需求（NFR）調整。
• 此變更可以重複使用現有的 #sec-* 錨點，並符合微型（micro）/標準（standard）差異預算。
• 您希望遵循提案 -> 實施 -> 封存循環，同時保留此儲存庫的 4 文件任務 協定和一人一檔案的角色規則。

不應使用時機

• 工作是全新開發，或尚無上游規格存在：請使用 prd-generator，接著 spec-generator，然後 task-decomposition。
• 變更需要新的架構決策、新的元件邊界、新的跨領域不變性約束，或全新的規格章節（新的 #sec-* 錨點）：請升級至 spec-generator 而非將其偷渡至變更中。
• 您只需要將已核准的規格分割成任務：請使用 task-decomposition。
• 您只需要稽核現有的任務套件或提案：請使用 plan-linter。
• 任務已規劃完成，正在等待實施/驗證：請使用 dev / qa。

輸入

• 基礎規格文件：預設為 .specs/02-tech-spec.md（及其模組化部分）。
• 由需求提出者以白話文撰寫的受範圍變更需求。
• 步驟 1 中產生的儲存庫慣例報告。
• 可選：此變更所接續的現有任務套件，以及相關的架構決策記錄（ADR）。

輸出

成品	建立後的擁有者	用途
.specs/change-context/standards.md	工具	決定性的儲存庫標準與隱含約束（自動產生，絕不手動編輯）。
.specs/changes/<change-id>/proposal.md	規劃者	受範圍變更提案：動機、增量差異、影響範圍、不變性約束/NFR、回滾機制、驗證方式。
.specs/changes/<change-id>/convergence.md	收斂工具	品質驗證（QA）通過後撰寫；記錄哪些內容被折返寫回規格文件。
tasks/<change-id>/01-contract.md ... 04-process.md	規劃者 / 開發者 / 品質驗證 / 工具	恰好一個四文件套件，重複使用任務分解（task-decomposition）模板。

提案不是一份產品需求文件（PRD），也不是一份替代規格文件。它是一個差異檔，指明它 會更改哪些現有的錨點。完整的生命週期與規模規則：references/brownfield-protocol.md。

工作流程

1. 提取儲存庫標準（每次配置變更執行一次）：

   python .agents/skills/change/scripts/standards_extract.py --repo-root . --json
   python .agents/skills/change/scripts/standards_extract.py --repo-root . --check
   

   在規劃前先閱讀 .specs/change-context/standards.md。其「隱含約束」 章節具有約束力：僅使用它所驗證的命令，尊重宣告的測試佈局、 執行環境底線和現有的錨點。--check 返回退出碼 1 表示報告已 過時；請在規劃前重新產生。切勿手動編輯該報告。

2. 建立提案和一個任務套件的骨架（唯一會寫入檔案的步驟）：

   python .agents/skills/change/scripts/scaffold_change.py \
     --change-id CHG-001-rate-limit \
     --title "限制登入嘗試次數" \
     --anchor "#sec-auth-tokens" \
     --kind modify \
     --size-class micro --estimated-lines 40 \
     --touch-files "modify:src/auth/rate_limit.py" \
     --repo-root .
   

   骨架產生器會根據基礎規格文件驗證錨點，計算 base_spec_sha256， 並委託給 task-decomposition （scaffold_task.py）或在其不存在時發出最小的內聯 套件。使用 --dry-run 預覽，使用 --force 覆蓋可拋棄的執行。

3. 規劃者填寫提案和合約。 替換提案中的指南（motivation、 [CHG-<n>] 差異塊、路徑、不變性約束/NFR、回滾、驗證）以及合約中的佔位符 （module、adherence_adrs、dod、邊界案例、不變性約束描述）。請勿發明路徑或錨點。 保持 02/03 為空白角色表單；保持提案 status: proposed。

4. 閘門 1，接著閘門 2。 運行決定性的閘門 1，然後進行獨立的語意審查：

   # 從儲存庫根目錄執行。閘門 1 輔助工具需要安裝 plan-linter 技能。
   python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --repo-root . --spec .specs/02-tech-spec.md --changes-dir .specs/changes
   python .agents/skills/change/scripts/lint_change.py --change-id CHG-001-rate-limit --repo-root .
   

   閘門 1 必須在實施前通過；閘門 2 不得報告 BLOCKED 或 REQUEST CHANGES。

5. 實施與驗證。 運行 dev（僅對宣告的 touch_files 進行操作，填寫 02，移交）和 qa（在 tests/acceptance/ 下進行獨立測試，填寫 03，給出一個裁決）。提案 在實施和驗證通過後移至 applied 狀態。

6. 收斂與封存。 在 QA_PASSED 之後，運行 converge 將已確認的偏差 附加到 .specs/02-tech-spec.md，撰寫 convergence.md，將套件移至 tasks/archive/，並設定 提案 status: archived。若無 converge，請手動執行相同的附加寫回操作。

手動備援（無 Python）

1. 手動建立標準列表：儲存庫根目錄配置、測試/原始碼樹、執行環境、#sec-* 錨點。
2. 將 assets/templates/proposal.template.md 複製到 .specs/changes/<change-id>/proposal.md，填寫每個標記（{{...}}），並計算 base_spec_sha256。
3. 使用 task-decomposition 模板或 references/brownfield-protocol.md 中的備援方案，建立 tasks/<change-id>/ 四文件套件。
4. 手動執行閘門 1 / 閘門 2 檢查清單；將證據記錄在套件中。
5. 使用相同的成品遵循工作流程步驟 5–6。

品質閘門檢查清單

• 標準報告已產生且為最新（standards_extract.py --check 退出碼為 0）。
• 提案前端資料完整，status: proposed，kind 正確， base_spec_sha256 為最新。
• 每個 [CHG-<n>] 區塊都命名了一個存在於基礎規格文件中的真實 #sec-* 錨點。
• 恰好存在一個任務套件；change_id 等於提案 id 並且 origin_spec_anchor 是提案的 impact_anchors 之一。
• 差異預算已遵守：微型（micro）為 1 個觸及檔案（預設 10-49 行）；標準（standard）為 1-3 個檔案（預設 50-250 行）。數字可在 plan-linter 配置中設定。
• 閘門 1 在填寫完成的合約上通過，且提案為開放狀態（proposed/applied）。
• 閘門 2 審查沒有阻擋性的發現；審查者為獨立且唯讀。
• 開發者僅實施了 touch_files；品質驗證（QA）給出了恰好一個附有證據的裁決。
• 收斂（Converge）將差異附加到規格文件，且提案已archived。

反幻覺規則

• 絕不發明檔案路徑。 每個 touch_files 條目必須是一個要 modify 的現有檔案， 或是一個要 create 的存在目錄中的新檔案（相對於儲存庫，使用正斜線）。
• 每個差異區塊都命名一個真實的錨點。 重複使用現有的 #sec-* 錨點； 骨架產生器和 linter 會拒絕缺失或飄移的錨點。
• 不要發明命令或慣例。 只有被宣告的配置（標準報告）所驗證的命令才能出現在合約的完成定義（DoD）中。
• 結構性變更需要升級。 如果變更需要新的規格章節/錨點、 新的元件、新的架構決策記錄（ADR）或不變性約束的變更，請停止並使用 spec-generator。
• 不要誇大閘門的作用。 閘門 1 是確定性的帳務檢查，閘門 2 是 基於提示的審查；git 和 CI 才是權威。

輔助腳本

• scripts/standards_extract.py — 決定性標準提取器；寫入 .specs/change-context/standards.md（支援 --json、--check、--dry-run、--version）。
• scripts/scaffold_change.py — 建立一個提案和一個任務套件的骨架 （支援 --dry-run、--force、--json、--version）。
• scripts/lint_change.py — 提案/套件一致性與基礎規格飄移檢查 （支援 --json、--version）。

所有輔助工具僅使用標準函式庫，會自行解析其目錄，並以退出碼 0（成功）、1（閘門失敗）、2（使用錯誤）、3（非預期錯誤）結束。

失敗處理

• 缺少基礎規格文件：停止。既有系統變更需要一份基礎規格文件；骨架產生器會以退出碼 2 退出。
• 未知的錨點：停止並重複使用現有的錨點，或升級至 spec-generator。
• 過時的報告或規格飄移（退出碼 1）：重新產生報告，重新設定提案基準，重新執行閘門 1；絕不手動編輯 base_spec_sha256。
• 變更目錄已存在：僅在可拋棄的情況下使用 --force 重新執行；否則編輯現有的提案。
• 腳本不可用：遵循手動備援方案；工作流程以提示為優先。

誠實的限制

• 標準報告描述的是已宣告的配置，而非必然實踐的慣例；它是給規劃者的提示，而非合規證明。
• base_spec_sha256 偵測基礎規格文件的任何位元組變更；收斂後，已封存的提案不受飄移檢查的約束。
• 可選腳本是可以繞過的；CI 加上儲存庫權限仍然是權威。