ops-wiki-agent-kit 0.1.0 → 0.1.2

package/.github/agents/source-code-to-spec-documenter.agent.md

@@ -1,5 +1,6 @@
 ---
 name: source-code-to-spec-documenter
+tools: [execute, read, edit, search, todo]
 description: 從 docs-target-queue target queue 選取一筆目標，依 entrypoint 追 source evidence，產生 source-code-backed SPEC docs；缺少 runtime metadata 時產出 partial SPEC 與可審查 coverage gaps，並交接 review handoff。
 handoffs:
   - label: Review Target SPEC

package/.github/agents/source-code-to-system-ops-overview.agent.md

@@ -1,5 +1,6 @@
 ---
 name: source-code-to-system-ops-overview
+tools: [execute, read, edit, search, todo]
 description: 根據 source code、SQL、設定檔、部署線索、依賴檔、Log keyword、錯誤訊息或既有文件，產生或更新跨系統型態、跨技術棧的系統層級維運總覽文件。
 ---
 

package/.github/prompts/00-discover-target-baseline.prompt.md

@@ -0,0 +1,37 @@
+---
+agent: source-code-to-spec-documenter
+tools: [execute, read, edit, search, todo]
+description: 為 docs-target-queue 的單一 target row 建立或刷新 shared discovery handoff baseline，不產生 target-facing SPEC 文件。
+---
+
+# Discover Target Baseline
+
+此 prompt 只設定 `baseline` scope invocation。Prompt role、execution order、handoff baseline、source tracing、guideline loading、queue update 與 final response contract 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 擁有。
+
+不要在 task start 時一次完整載入所有 skills、全部 references 或 reviewer workflow；依 `generation-workflow.md` 的 progressive loading 順序執行。
+
+## Scope
+
+`generation_scope = baseline`
+
+`doc_profile = <selected row doc_profile | user specified | standard>`
+
+本 scope 只建立或刷新 shared `handoff.json` baseline；不得產生或更新 target-facing SPEC 文件，也不得將任何 doc status 設為 `generated`。
+
+## Critical Guardrails
+
+- 開始前必須載入 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md`，不要只依本 prompt 推論 baseline behavior。
+- Baseline 是 search priority / evidence ledger，不是 completion proof；不得把未追蹤的 behavior 寫成 `N/A` 或已確認不適用。
+- 必須保留 visible subfunctions、relation candidates、unmapped behaviors、coverage gaps 與 `not_checked`，避免後續 `01` / `02` / `03` 遺失追蹤線索。
+- 不得寫入任何 target-facing `docs/**/*.md` 檔案；只允許寫入 durable handoff `.github/artifacts/source-code-to-spec/<target_id>/handoff.json`，並以同一路徑更新 queue `last_handoff`。
+- Handoff patch 的 root `generation_scope` 與 `current_run.scope` 必須等於本 prompt 的 `generation_scope`；不得重用其他 scope 的 patch JSON。
+- 不得直接編輯 durable `handoff.json` 取代 `handoff_update.py` helper merge。
+- `handoff_update.py` 成功後，必須依 `$source-code-to-spec-documenter` Queue Helper 與 `target-queue-contract.md` 立刻執行 `spec_queue.py update`，並 reselect selected row 驗證 `docs/docs-target-queue.md` 已更新。
+
+## Orchestration
+
+依 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 執行；prompt 不另行改寫 workflow contract。
+
+## Final Response
+
+依 `$source-code-to-spec-documenter` 的 baseline Final Response contract 回報，並額外標示 durable handoff path、confirmed evidence、not checked 與後續建議執行的 `01` / `02` / `03` prompt。

package/.github/prompts/01-generate-target-foundation-spec.prompt.md

@@ -1,12 +1,12 @@
 ---
 agent: source-code-to-spec-documenter
 tools: [execute, read, edit, search, todo]
-description: 為 docs-target-queue 的單一 target row 建立 discovery baseline，並產生第 1 份 foundation/business source-code-backed ops SPEC 文件。
+description: 為 docs-target-queue 的單一 target row 復用或更新 discovery baseline，並產生第 1 份 foundation/business source-code-backed ops SPEC 文件。
 ---
 
 # Generate Target Foundation SPEC
 
-此 prompt 只設定 `foundation` scope invocation。Prompt role、execution order、handoff baseline、source tracing、guideline loading、queue update 與 final response contract 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 擁有。
+此 prompt 只設定 `foundation` scope invocation。Prompt role、execution order、handoff baseline reuse / update、source tracing、guideline loading、queue update 與 final response contract 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 擁有。
 
 不要在 task start 時一次完整載入所有 skills、全部 references 或 reviewer workflow；依 `generation-workflow.md` 的 progressive loading 順序執行。
 
@@ -16,15 +16,19 @@ description: 為 docs-target-queue 的單一 target row 建立 discovery baselin
 
 `doc_profile = <selected row doc_profile | user specified | standard>`
 
-本 scope 產生或更新第 1 份 target SPEC；selected output file、reference routing、coverage handling 與 handoff policy 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 與 `$source-code-to-ops-spec-guidelines` 的 `SKILL.md` 決定。
+本 scope 產生或更新第 1 份 target SPEC；優先復用 `00-discover-target-baseline.prompt.md` 建立的 shared handoff。selected output file、reference routing、coverage handling 與 handoff policy 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 與 `$source-code-to-ops-spec-guidelines` 的 `SKILL.md` 決定。
 
-## Generation Detail
+## Critical Guardrails
 
-本次 invocation 必須要求 `$source-code-to-ops-spec-guidelines` 使用最詳細 source-backed SPEC style；single-scope 只限制 selected output file，不降低內容深度。
-
-本文件必須依 foundation/business guideline 產出完整正式章節、完整 table contracts、source-backed SQL（適用時）、Step / branch / mapping detail（適用時），以及每張 diagram 後的結構化圖表文字說明。
-
-不得只產出摘要、維運摘要卡或 cross-reference 代替正式章節。若來源不足，以 `N/A`、`無法由目前來源確認` 或 `Unresolved` 標示並寫入 handoff，不可用摘要取代缺漏章節。
+- 開始前必須載入 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md`，不要只依本 prompt 推論 generation behavior。
+- 不得用 summary、handoff summary、Final Response 或 reviewer note 取代 selected output file 內的正式章節內容。
+- 若 resolved `doc_profile=full`，必須依 `generation-workflow.md` 的 Full-Depth Gate 檢查 selected output file。
+- 若 baseline 不存在，只能建立最小 discovery baseline；不得把未追蹤的 downstream、DAO、SQL、error / ops evidence 寫成已確認不存在。
+- 不得寫入 `doc_file_plan.selected_output_files` 以外的 target-facing `docs/**/*.md` 檔案。
+- Handoff patch 的 root `generation_scope` 與 `current_run.scope` 必須等於本 prompt 的 `generation_scope`；不得重用其他 scope 的 patch JSON。
+- 不得直接編輯 durable `handoff.json` 取代 `handoff_update.py` helper merge。
+- 若發現同一 target 有尚未合併的 patch JSON，先依該 patch 自身 scope 完成 helper merge 與 queue sync，再繼續本 prompt。
+- `handoff_update.py` 成功後，必須依 `$source-code-to-spec-documenter` Queue Helper 與 `target-queue-contract.md` 立刻執行 `spec_queue.py update`，並 reselect selected row 驗證 `docs/docs-target-queue.md` 已更新。
 
 ## Orchestration
 

package/.github/prompts/02-generate-target-architecture-spec.prompt.md

@@ -18,13 +18,17 @@ description: 為 docs-target-queue 的單一 target row 復用或更新 handoff
 
 本 scope 產生或更新第 2 份 target SPEC；selected output file、reference routing、coverage handling 與 handoff policy 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 與 `$source-code-to-ops-spec-guidelines` 的 `SKILL.md` 決定。
 
-## Generation Detail
-
-本次 invocation 必須要求 `$source-code-to-ops-spec-guidelines` 使用最詳細 source-backed SPEC style；single-scope 只限制 selected output file，不降低內容深度。
-
-本文件必須依 architecture/flow/data/logic guideline 產出完整正式章節、完整 table contracts、source-backed SQL、Step / branch / mapping detail，以及每張 diagram 後的結構化圖表文字說明。
-
-不得只產出摘要、維運摘要卡或 cross-reference 代替正式章節。若來源不足，以 `N/A`、`無法由目前來源確認` 或 `Unresolved` 標示並寫入 handoff，不可用摘要取代缺漏章節。
+## Critical Guardrails
+
+- 開始前必須載入 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md`，不要只依本 prompt 推論 generation behavior。
+- 不得用 summary、handoff summary、Final Response 或 reviewer note 取代 selected output file 內的正式章節內容。
+- 必須把既有 baseline / foundation handoff 的 `not_checked`、`coverage_gaps`、`relation_candidates` 與 `unmapped_behaviors_found` 視為 architecture tracing 的 follow-up input；不得因 foundation 未展開就推定 behavior 不存在。
+- 若 resolved `doc_profile=full`，必須依 `generation-workflow.md` 的 Full-Depth Gate 檢查 selected output file。
+- 不得寫入 `doc_file_plan.selected_output_files` 以外的 target-facing `docs/**/*.md` 檔案。
+- Handoff patch 的 root `generation_scope` 與 `current_run.scope` 必須等於本 prompt 的 `generation_scope`；不得重用其他 scope 的 patch JSON。
+- 不得直接編輯 durable `handoff.json` 取代 `handoff_update.py` helper merge。
+- 若發現同一 target 有尚未合併的 patch JSON，先依該 patch 自身 scope 完成 helper merge 與 queue sync，再繼續本 prompt。
+- `handoff_update.py` 成功後，必須依 `$source-code-to-spec-documenter` Queue Helper 與 `target-queue-contract.md` 立刻執行 `spec_queue.py update`，並 reselect selected row 驗證 `docs/docs-target-queue.md` 已更新。
 
 ## Orchestration
 

package/.github/prompts/03-generate-target-ops-spec.prompt.md

@@ -18,13 +18,17 @@ description: 為 docs-target-queue 的單一 target row 復用或更新 handoff
 
 本 scope 產生或更新第 3 份 target SPEC；selected output file、reference routing、coverage handling 與 handoff policy 由 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md` 與 `$source-code-to-ops-spec-guidelines` 的 `SKILL.md` 決定。
 
-## Generation Detail
-
-本次 invocation 必須要求 `$source-code-to-ops-spec-guidelines` 使用最詳細 source-backed SPEC style；single-scope 只限制 selected output file，不降低內容深度。
-
-本文件必須依 error/ops/scenario coverage guideline 產出完整正式章節、完整 table contracts、source-backed SQL（適用時）、Step / branch / mapping detail（適用時），以及每張 diagram 後的結構化圖表文字說明。
-
-不得只產出摘要、維運摘要卡或 cross-reference 代替正式章節。若來源不足，以 `N/A`、`無法由目前來源確認` 或 `Unresolved` 標示並寫入 handoff，不可用摘要取代缺漏章節。
+## Critical Guardrails
+
+- 開始前必須載入 `$source-code-to-spec-documenter` 的 `references/generation-workflow.md`，不要只依本 prompt 推論 generation behavior。
+- 不得用 summary、handoff summary、Final Response 或 reviewer note 取代 selected output file 內的正式章節內容。
+- 必須把既有 baseline / foundation / architecture handoff 的 `not_checked`、`coverage_gaps`、`relation_candidates` 與 `unmapped_behaviors_found` 視為 ops tracing 的 follow-up input；不得因前序 scope 未展開就推定 behavior 不存在。
+- 若 resolved `doc_profile=full`，必須依 `generation-workflow.md` 的 Full-Depth Gate 檢查 selected output file。
+- 不得寫入 `doc_file_plan.selected_output_files` 以外的 target-facing `docs/**/*.md` 檔案。
+- Handoff patch 的 root `generation_scope` 與 `current_run.scope` 必須等於本 prompt 的 `generation_scope`；不得重用其他 scope 的 patch JSON。
+- 不得直接編輯 durable `handoff.json` 取代 `handoff_update.py` helper merge。
+- 若發現同一 target 有尚未合併的 patch JSON，先依該 patch 自身 scope 完成 helper merge 與 queue sync，再繼續本 prompt。
+- `handoff_update.py` 成功後，必須依 `$source-code-to-spec-documenter` Queue Helper 與 `target-queue-contract.md` 立刻執行 `spec_queue.py update`，並 reselect selected row 驗證 `docs/docs-target-queue.md` 已更新。
 
 ## Orchestration
 

package/.github/prompts/generate-system-ops-overview.prompt.md

@@ -15,8 +15,9 @@ description: 從 source code、SQL、設定檔、部署線索、依賴檔、Log
 3. System classification gate：依 evidence 判定一種或多種系統型態，例如 web/API、mobile app、desktop application、DB SQL/database program、ERP、batch、CLI、integration service。不得把 web、Java、Spring、REST 或 server deployment 當作預設前提。
 4. Evidence boundary gate：整理 module、function group、runtime/config、external integration、error/log clue、triage direction 與 coverage gap。每個重要結論都標示 source location；不要輸出額外判斷欄位。
 5. Reconciliation gate：若 output file 已存在，先比對既有內容與現行 source evidence，保留仍正確的段落，修正過期、無 evidence、過度功能層化或敏感資訊風險的內容。
-6. Write gate：產生或更新 `S01 系統維運總覽文件`。文件使用繁體中文 narrative；technical identifiers、source paths、config keys、API paths、SQL/database object、class/method names、CLI commands 與 protocol names 保留英文或原始語法。不要輸出 secret value、production 操作指令、完整功能流程或正式 SOP。
-7. Quality gate：依 `$source-code-to-system-ops-overview` 的 quality gate 檢查章節邊界、來源標示、跨技術棧適用性、敏感資訊與功能層內容外溢。若可用，執行 `git diff --check` 或等效 Markdown whitespace 檢查。
+6. Contract gate：寫入前依 `references/system-operations-overview-guideline.md` 檢查必填章節與表格欄位。不得把 guideline 要求使用 Markdown Table 的章節降級成純 narrative；若某欄不適用，填 `N/A`、`Unknown` 或「無法由目前來源確認」。
+7. Write gate：產生或更新 `S01 系統維運總覽文件`。文件使用繁體中文 narrative；technical identifiers、source paths、config keys、API paths、SQL/database object、class/method names、CLI commands 與 protocol names 保留英文或原始語法。不要輸出 secret value、production 操作指令、完整功能流程或正式 SOP。
+8. Quality gate：依 `$source-code-to-system-ops-overview` 的 quality gate 檢查章節邊界、表格 contract、來源標示、跨技術棧適用性、敏感資訊與功能層內容外溢。若可用，執行 `git diff --check` 或等效 Markdown whitespace 檢查。
 
 ## Task
 

package/.github/skills/source-code-to-ops-spec-guidelines/SKILL.md

@@ -52,25 +52,10 @@ description: 在產生、維護、重構或審查 source-code-backed ops SPEC gu
 
 若任務只維護某一份主要 guideline 且不涉及共用文件基礎，可先載入該 owner guideline；涉及 target-facing SPEC generation、Metadata、Obsidian Links、章節適用或圖表格式時，必須載入 `references/supporting-output-format-diagram-and-example-reference.md`。
 
-`doc_file_plan` 用來記錄 generation scope、selected output files、章節 `N/A` / `Unresolved` 原因、coverage gaps 與 handoff impact；reference 檔案選擇以本 skill 的 Reference Routing 為準。
-
-Target-facing SPEC 的內容優先順序是完整、準確、source-backed，其次才是篇幅壓縮或版面簡潔。摘要、維運摘要卡、圖表文字說明、handoff summary 或 cross-reference 只能協助導覽，不可取代正式詳細章節；若來源可確認 handler、service、DAO / Repository / Mapper、SQL、table、status transition、config、job、file I/O 或 external integration 行為，應在對應 scope 的章節保留可審查細節。
-
-Target-facing SPEC 以業務行為、處理流程、資料規則、錯誤處理與維運判斷方式為主。Source path、line、symbol 與 `EvidenceRef[]` 由 `source-code-to-spec-documenter` 的 `handoff.json` 保存；文件本身只在內容需要時保留必要識別資料，例如 API path、SQL ID、table、status column、job name、config key、file name、log keyword 或 trace id，且應整合到對應章節的操作、資料、狀態或錯誤欄位中。
-
-`doc_profile=full` 代表 selected scope 內採完整深度，不是把 source-backed detail 壓成摘要。Full profile 至少應保留：
-
-- 可從 source 讀取的完整 SQL excerpt；若 SQL 是動態組合，保留 source-backed pseudo SQL、組合條件、參數來源與限制。
-- DAO / Repository / Mapper method 與 SQL、table、status column、DB object、stored routine 或 external resource 的 mapping。
-- Handler / controller / job / service 到 DAO method 的可追蹤流程，以及與維運判斷有關的 branch、transaction、rollback、retry、rerun、log、error message 與 status transition。
-- 欄位 mapping、狀態 mapping、request / response mapping、file column mapping 或 external payload mapping 的來源欄位、目標欄位、轉換規則與限制。
-
-不要因為流程、SQL、圖表或資料 mapping 較大就刪減 source-backed detail；必要時拆成多個表格、子章節或多張圖表，並讓每一段都可追溯到 source evidence。
+`doc_file_plan`、full-depth completion gate、source tracing、status transition、handoff 欄位與 write / update behavior 由 `source-code-to-spec-documenter/references/generation-workflow.md`、`source-code-to-spec-documenter/references/source-tracing-rules.md`、`source-code-to-spec-documenter/references/generation-handoff-contract.md` 與 `source-code-to-spec-documenter/references/target-queue-contract.md` 擁有；本 skill 只維護 reference routing 與 target-facing chapter guideline ownership。
 
 Target-facing SPEC 的每一個正式章節都應保留章節標題。若該章節沒有來源資料、已確認不適用，或目前來源不足以填寫，不要硬湊表格、圖表或推測內容；在章節下方輸出一行 `N/A: <簡短原因>`、`無法由目前來源確認: <缺少的 evidence>` 或 `Unresolved: <阻塞原因>` 即可，並將 completion-impacting gap 寫入 handoff。
 
-Target-facing SPEC 的 generation / update 執行流程、source tracing、idempotent update、handoff 欄位與 queue 狀態不由本 skill 維護；請使用 `source-code-to-spec-documenter/references/generation-workflow.md`、`source-code-to-spec-documenter/references/source-tracing-rules.md`、`source-code-to-spec-documenter/references/generation-handoff-contract.md` 與 `source-code-to-spec-documenter/references/target-queue-contract.md`。
-
 ## Ownership Boundary
 
 維護 guideline contract 時，先找 owner，再改 owner。避免同一條規則散落在多份文件中。
@@ -98,16 +83,9 @@ Target-facing SPEC 的 generation / update 執行流程、source tracing、idemp
 7. 若來源不足，guideline 應要求標示 `N/A`、`無法由目前來源確認`、`unknown` 或 `Unresolved`，不得鼓勵 AI 補完不存在的行為。
 8. 不要把歷史範例中的示意 table、狀態值、API、Job 或 DB object 當成真實 source evidence；只能作為格式與顆粒度範例。
 
-## Diagram and Metadata Rules
-
-圖表與 Metadata 的補充規則放在 `references/supporting-output-format-diagram-and-example-reference.md`。維護任一 guideline 時，至少要遵守以下共通規則：
+## Shared Format Rules
 
-- 每張 Mermaid、ASCII Art、ERD、UML、flowchart、sequenceDiagram、classDiagram 或其他圖表後面，必須立即附上 `> 📝 **圖表文字說明**` blockquote。
-- 圖表文字說明必須可獨立閱讀；即使 diagram 無法 render，讀者仍能理解架構、流程、資料關聯、分支結果與維運線索。
-- 圖表負責視覺化，圖表文字說明負責補足完整脈絡；兩者共同構成必填內容。
-- Mermaid `sequenceDiagram` 失敗或例外訊息優先使用 `-x`，避免使用不穩定的 `A--xB` 寫法。
-- Mermaid `erDiagram` 的 PK/FK 標示必須使用雙引號，例如 `string PRODUCT_ID "PK"`。
-- Metadata 與 `## Obsidian Links` 規則以 `references/supporting-output-format-diagram-and-example-reference.md` 為主；若任務明確要求「系統功能規格書」格式，使用同一 supporting reference 的 Metadata variant。
+圖表、Metadata、`## Obsidian Links`、Mermaid / ASCII Art 語法、圖表文字說明與 Metadata variant 的完整規則，統一由 `references/supporting-output-format-diagram-and-example-reference.md` 維護；本 `SKILL.md` 只保留 routing、owner boundary 與 quality gate。
 
 ## Quality Gate
 

package/.github/skills/source-code-to-ops-spec-guidelines/references/01-system-overview-and-business-scenarios-guideline.md

@@ -16,8 +16,6 @@
 
 本文件本身不是交付給維運人員閱讀的最終文件，而是提供 AI 產生最終維運文件時使用的參考規則與章節範本。
 
-跨 `01`、`02`、`03` 都適用的文件定位、系統單元型態、章節適用判斷、Metadata、`## Obsidian Links` 與章節編號原則，統一由 `supporting-output-format-diagram-and-example-reference.md` 維護，本文件不重複定義。
-
 本文件負責讓第一份維運文件優先回答以下問題：
 
 - 使用者從哪裡進入或觸發這個功能？
@@ -42,12 +40,6 @@
 
 即使在正式編號章節底下，`撰寫目標`、`撰寫要求`、`內容規範`、欄位契約與填寫規則等文字也屬於 guideline 說明；AI 產出最終文件時，應使用這些規則生成實際內容，不應原樣複製規則文字。
 
-## 共用文件基礎規則
-
-跨三份 target SPEC 的文件定位、系統單元型態、章節適用判斷、Metadata、`## Obsidian Links`、reader-facing `Name` / lookup `ID` 規則與產出文件章節編號原則，請依 `supporting-output-format-diagram-and-example-reference.md` 的「跨三份 SPEC 的文件基礎規則」撰寫。
-
-本文件只保留第一份輸出文件的正式章節契約。若需要調整共用文件基礎規則，請修改 supporting reference，不要在本文件新增重複規則。
-
 ---
 
 # 產出文件章節範本