ops-wiki-agent-kit 0.1.0

package/.github/skills/source-code-to-system-ops-overview/references/system-operations-overview-guideline.md

@@ -0,0 +1,332 @@
+# 系統層級維運總覽 Reference Guideline
+
+- **文件版本**: 0.1.0
+- **最後更新**: 2026-06-01
+- **文件目的**: 本指南用於協助 AI 從 Source Code、設定檔、部署線索、依賴檔、錯誤訊息、Log keyword、既有文件與可確認的系統結構中，產生系統層級維運總覽文件。
+- **文件性質**: Reference guideline，不是最終維運文件；本檔用於定義系統層級文件的內容邊界、章節結構、表格欄位與證據紀律。
+- **適用對象**: 作為 `$source-code-to-system-ops-overview` skill 的 reference guideline，主要供 AI 產生、更新或審查系統層級維運總覽時參考。
+- **最終文件讀者**: 維運工程師、L1/L2 Support、系統負責人、交接人員、QA、PM，以及需要先判斷問題應往哪個模組或功能層文件查找的人員。
+- **使用方式**: 產生 `S01 系統維運總覽文件` 時使用本指南；若需要單一功能的流程、SQL、錯誤處理、重跑或 rollback 細節，應改由功能層文件或其他 guideline 負責。
+
+---
+
+## 本文件定位
+
+本 guideline 只負責系統層級維運總覽，不負責單一功能、API、Batch、File I/O、DB routine 或外部整合流程的詳細說明。
+
+系統層級文件的用途是讓維運人員快速掌握整個系統的邊界、模組、執行環境、設定類型、外部整合點、錯誤與 Log 線索，以及問題發生時應先往哪一類資料或哪一份功能層文件查找。
+
+本文件產生的最終內容應優先回答以下問題：
+
+- 這個系統主要負責什麼？哪些範圍可由 Source Code 確認？
+- 系統有哪些主要 module、function group、job group、interface group 或 deployment component？
+- 系統使用哪些 runtime、framework、config file、entrypoint 與 dependency？
+- 哪些設定 key 會影響 DB、外部服務、timeout、retry、pool、file path 或 feature flag？
+- 系統有哪些外部整合點？方向、觸發方式與可追蹤線索是什麼？
+- 維運遇到錯誤訊息、exception 或 Log keyword 時，應先往哪個模組、設定或功能層文件查？
+- 哪些資訊只能由 Source Code 確認，哪些屬於推論，哪些必須人工補充？
+
+---
+
+## 跨系統類型與跨技術棧適用原則
+
+本 guideline 必須適用於不同系統型態與程式語言，不得預設所有目標都是 Java Web、Spring、REST API 或 server-side application。若某章節或欄位不適用目前系統，應標示 `N/A`、`Unknown` 或「無法由目前來源確認」，不要硬套 web / API / Java 術語。
+
+### 系統型態正規化
+
+產生系統層級文件時，先將目前專案歸類為一種或多種系統型態，再選擇適合的 source evidence 與章節顆粒度。
+
+| 系統型態 | 常見來源線索 | 系統層可寫重點 | 不應強制套用 |
+|---|---|---|---|
+| Web / API service | route、controller、middleware、service、dependency、web config、OpenAPI | API group、runtime、config key、external service、error/log clue | 不要把 request / response mapping 寫進系統總覽 |
+| Mobile app / Desktop application | screen、view、view model、event handler、manifest、installer config、local storage | screen/module inventory、local config、backend integration、client log clue | 不要假設 server deployment topology |
+| DB SQL / Database program | schema、table、view、stored procedure、function、trigger、job、SQL script | DB object inventory、routine group、scheduler、interface table、error message | 不要要求 class、method、HTTP path |
+| ERP / Packaged system | module、customization、report、interface program、batch job、table extension、exported metadata | package/module boundary、custom object、interface、job/report、manual configuration gap | 不要把 vendor runtime 或 formal owner 自行補完 |
+| Batch / CLI / Scheduled job | scheduler config、job class/script、command entrypoint、file path、log keyword | job group、trigger、input/output path、retry/config clue、first triage direction | 不要直接提供 production rerun 指令 |
+| Integration / Middleware | queue、topic、webhook、file exchange、ETL mapping、adapter config、endpoint key | inbound/outbound direction、trigger、destination key、observable clue | 不要展開完整 field mapping |
+
+同一個系統可能同時包含多種型態，例如 web + batch + DB routine + ERP interface。系統總覽應呈現組合式 inventory，而不是把所有內容轉成單一技術模型。
+
+### 語言與技術中立規則
+
+Source evidence 的判讀必須保留原始技術語意。Java、C#、JavaScript/TypeScript、Python、SQL、PL/SQL、T-SQL、shell script、ERP metadata 或其他語言都可作為系統層總覽來源。
+
+| Evidence category | Java example | C# / .NET example | JS / TS example | SQL / DB example | ERP / packaged example |
+|---|---|---|---|---|---|
+| Entry point | `main class`、`web.xml`、`@Controller`、`@Scheduled` | `Program.cs`、`Controller`、`Worker Service` | `server.ts`、`route handler`、`Electron main` | `procedure`、`function`、`trigger`、`job` | `custom report`、`interface program`、`batch definition` |
+| Config | `.properties`、`.yml`、Spring XML | `appsettings.json`、`.config` | `.env`、`package.json`、framework config | SQL script parameter、schema config | customizing table、exported setting |
+| Dependency | `pom.xml`、`build.gradle` | `.csproj`、`packages.config` | `package.json`、lock file | extension、DB package dependency | add-on package、vendor module metadata |
+| Observability | logger call、exception class | logging provider、exception type | logger module、browser/client log | `RAISE`、error code、audit table | application log、job log、message class |
+
+技術識別碼、config key、API path、SQL keyword、class name、method name、package name、table name、job name、queue/topic name 與 CLI command 必須保留英文或原文，不得為了中文化而破壞可執行或可查找內容。
+
+---
+
+## 系統層與功能層邊界
+
+### 系統層級文件允許內容
+
+系統層級文件應產出 source-backed overview、inventory、navigation、分流與證據範圍。若單一功能細節可由 source evidence 確認，系統總覽應保留足以分流的入口、模組、可觀測線索與功能層文件連結；完整流程、SQL、mapping、狀態與錯誤處理由功能層文件承接。
+
+| 類型 | 可寫內容 | 寫作深度 |
+|---|---|---|
+| 系統用途 | 系統主要用途、可確認範圍、不可確認業務背景 | 以 source-backed 概述加邊界清單呈現 |
+| 模組清單 | module name、用途摘要、主要程式位置、可觀測線索 | 列出可分流的 inventory；內部流程交給功能層文件 |
+| 功能清單 | function name、所屬模組、入口線索、主要程式位置、是否需要功能層文件 | 作為 navigation 與 coverage map；功能處理步驟交給對應功能層文件 |
+| 技術環境 | language、framework、runtime、dependency、entrypoint、config file | 列來源可確認項目，不做架構設計推論 |
+| 系統設定 | config key、用途類型、來源檔、是否敏感、影響範圍 | 只列 key 與意義，不列 secret value |
+| 外部整合 | interface name、direction、protocol、trigger、endpoint key、related module | 保留系統層整合線索；request / response mapping 交給功能層文件 |
+| 錯誤與 Log | error code、exception type、Log keyword、可能模組、第一查找方向 | 保留系統層線索與分流方向；正式 SOP 只在有來源時引用 |
+| 維運分流 | 問題現象、優先查找資訊、可能分類、下一份文件 | 初步 triage，不給 production 操作指令 |
+| 來源與缺口 | source location、coverage gap、人工補充項目 | 明確標示可回查來源與不可確認事項 |
+
+### 功能層級內容禁止混入
+
+以下內容不應出現在系統層級維運總覽中；若需要，應導向功能層文件、API 文件、Batch 文件、DB routine 文件或正式 SOP。
+
+| 禁止內容 | 原因 | 正確處理方式 |
+|---|---|---|
+| 單一功能完整處理流程 | 會把系統總覽變成功能規格 | 保留功能名稱、入口、可觀測線索與文件連結 |
+| request / response 欄位 mapping | 屬於 API 或外部整合功能層細節 | 在功能層 API / external integration 文件撰寫 |
+| SQL 詳細查詢條件 | 屬於功能層資料邏輯或排查細節 | 系統層保留主要 DB object、SQL ID 或查找線索，並導向功能層文件 |
+| 狀態轉移細節 | 屬於功能流程與資料生命週期 | 系統層保留主要 status field、相關模組與文件導覽 |
+| error handling flow | 屬於單一功能錯誤處理 | 系統層保留 error / exception / Log keyword 與分流方向 |
+| rerun / rollback SOP | 可能影響 production 安全 | 標示「需功能層文件或正式 SOP」，並保留可確認的 job / script / console 線索 |
+| production 操作指令 | Source Code 通常無法確認正式操作權限 | 列為人工補充項目 |
+| SLA、正式 owner、escalation window | 通常不在 Source Code 中 | 列為人工補充項目 |
+| 監控閾值推論 | 容易產生假告警標準 | 只有來源可確認時列出，否則標示無法確認 |
+
+---
+
+## 來源與缺口規則
+
+系統層級文件只保留可回查來源位置與必要缺口，不輸出額外判斷欄位。不得因為系統名稱、package name、class name 或 config key 命名看似明確，就自行補完業務背景、正式 SOP、負責窗口或 production 運作規則。
+
+若資訊無法確認，應使用「無法由目前來源確認」或列入人工補充項目。若只是命名推測且不影響維運查找，應省略，不要為了整理判斷而增加欄位。
+
+---
+
+# 產出文件章節範本
+
+以下正式編號章節代表 `S01 系統維運總覽文件` 可採用的章節架構。章節下方的撰寫要求、欄位契約與限制規則只供 AI 參考，不應逐字輸出到最終文件。
+
+## 1. 系統用途與邊界
+
+**撰寫目標**:
+說明整個系統主要處理什麼、Source Code 可確認的系統範圍，以及 Source Code 無法確認但維運可能需要人工補充的業務背景。
+
+### 1.1 系統用途摘要
+
+以一段話描述系統主要用途。內容應來自 repo 結構、README、module naming、entrypoint、route、job、config、DB object 或既有文件，不得自行補出企業背景或組織任務。
+
+### 1.2 Source Code 可確認的系統範圍
+
+使用條列式列出可確認範圍，例如 UI module、API service、batch job、file exchange、database program、external integration 或 shared library。
+
+每一點應附上可追蹤線索，例如 package path、module path、config file、job name、API base path 或 DB object。
+
+### 1.3 無法從 Source Code 確認的業務背景
+
+只列真正會影響維運判斷、交接或支援分流的缺口，例如正式系統 owner、SLA、正式告警窗口、production 操作權限、業務流程上下游責任界線。
+
+不得把一般「可能需要補充文件」當成固定段落填滿版面。若沒有實質缺口，可標示 `N/A` 並說明目前來源已足以支援系統層總覽。
+
+## 2. 系統主要模組與功能清單
+
+**撰寫目標**:
+建立系統層 navigation inventory，讓維運人員知道問題應先往哪個 module、function group、job group 或 interface group 查找。
+
+### 2.1 系統主要模組
+
+使用 Markdown Table 呈現，至少包含以下欄位：
+
+| 欄位 | 說明 |
+|---|---|
+| 模組名稱 | 使用來源可確認的 module、package、service、job group 或 component name |
+| 模組用途摘要 | 一句話說明模組負責的系統層職責 |
+| 主要程式位置 | path、package、project module 或 deployment component |
+| 主要入口線索 | API base path、menu group、job prefix、file path key、queue name 或 config key |
+| 維運查找方向 | 遇到問題時應先查設定、Log、DB、外部介面或功能層文件 |
+
+模組用途摘要應停在系統層職責與分流線索；若 source evidence 已確認單一功能流程或完整 call chain，應在本欄提供功能層文件導覽或 coverage gap，不在系統總覽內改寫成完整功能規格。
+
+### 2.2 系統功能清單摘要
+
+功能清單作為系統層索引與 coverage map，不取代功能層文件。若來源無法完整列出所有功能，應標示 coverage gap。
+
+建議欄位如下：
+
+| 功能名稱 | 功能用途摘要 | 所屬模組 | 主要入口線索 | 主要程式位置 | 是否需要功能層文件 |
+|---|---|---|---|---|---|
+| `{function name}` | `{one-line purpose}` | `{module}` | `{menu / API / job / file / event}` | `{path}` | `Yes / No / Unknown` |
+
+功能用途摘要應作為 navigation 用途，保留功能名稱、入口與可觀測線索。validation rule、SQL、request / response mapping、狀態轉移、錯誤流程或 rerun 規則若有 source evidence，應交由功能層文件承接；系統總覽需標示對應文件或待補 coverage gap。
+
+## 3. 技術與執行環境線索
+
+**撰寫目標**:
+整理系統可由來源確認的技術組成與執行線索，協助維運或交接人員快速辨識 runtime、framework、啟動入口與設定來源。
+
+使用 Markdown Table 呈現，至少包含以下類型：
+
+| 類型 | 應列內容 | 可接受來源 | 不應加入 |
+|---|---|---|---|
+| Language / Runtime | Java、Node.js、Python、JDK version、runtime container | build file、Dockerfile、CI config | 未確認版本 |
+| Framework | Spring、Spring Boot、Struts、Quartz、MyBatis、JPA | dependency、annotation、config | framework 設計教學 |
+| 主要設定檔 | application config、Spring XML、log config、scheduler config | repo file path | secret value |
+| 主要啟動入口 | main class、web.xml、controller root、job launcher、script | source、deployment file | production 啟動指令推論 |
+| 主要依賴 | DB driver、MQ client、HTTP client、scheduler、logging library | dependency file、import | 完整 dependency tree |
+| Client / UI application | mobile manifest、desktop app entrypoint、view/screen file、event handler | source、package metadata、installer config | server-only deployment assumption |
+| Database program | procedure、function、trigger、view、scheduled DB job、SQL script | DDL、migration、DB package、SQL source | object-level SQL flow detail |
+| ERP / packaged component | custom module、report、interface program、custom table、batch definition | exported metadata、custom code、configuration extract | vendor behavior without evidence |
+
+若 runtime version 或 deployment topology 無法確認，應標示「無法由目前來源確認」。
+
+## 4. 系統設定與環境參數
+
+**撰寫目標**:
+整理會影響系統維運判斷的設定 key 類型，但不得揭露敏感值。
+
+設定表至少包含以下欄位：
+
+| Config Key / Pattern | 類型 | 用途摘要 | 來源檔案 | 影響範圍 | 是否敏感 | 維運注意事項 |
+|---|---|---|---|---|---|---|
+
+設定類型應優先涵蓋：
+
+- DB 連線設定 key，例如 JDBC URL、schema、datasource name、pool key。
+- 外部服務 URL key，例如 API host、SFTP path、MQ broker、service endpoint。
+- timeout / retry / pool 設定，例如 connection timeout、read timeout、retry count、thread pool size。
+- 檔案路徑設定，例如 input directory、output directory、temporary path、archive path。
+- feature flag 或開關，例如 enable flag、mode key、scheduler enable key。
+- logging / tracing 設定，例如 log level、correlation id、trace setting。
+- client / desktop 設定，例如 local config path、installer setting、app manifest、offline storage key。
+- DB SQL / database program 參數，例如 schema name、DB link name、procedure parameter default、job enable key。
+- ERP / packaged system 設定，例如 customizing key、interface profile、report variant、batch definition、table extension flag。
+
+敏感資訊處理規則：
+
+- 不得輸出 password、token、private key、secret value、certificate content。
+- 若來源檔案含敏感資訊，只能寫「設定檔含敏感連線資訊，需確認是否由 secret manager 或部署環境管理」。
+- 若只看到 placeholder，例如 `${DB_PASSWORD}`，可列 key name，但不得推測實際值。
+
+## 5. 外部介面與整合點摘要
+
+**撰寫目標**:
+列出系統層級可確認的外部整合點，協助維運判斷問題可能來自外部 API、檔案交換、MQ、queue、topic、socket、webhook、DB link 或 interface table。
+
+整合點摘要表至少包含：
+
+| 整合點名稱 | 類型 | Direction | Trigger | Endpoint / Destination Key | Related Module | 可觀測線索 | 細節文件 |
+|---|---|---|---|---|---|---|---|
+
+欄位說明：
+
+- `Direction` 使用 `Inbound`、`Outbound`、`Bidirectional` 或 `Unknown`。
+- `Trigger` 可填 API call、scheduler、file arrival、manual run、queue message、DB polling 或 event。
+- `Endpoint / Destination Key` 優先填 config key、queue name、topic name、SFTP path key、DB link name 或 interface table name，不填 secret。
+- `細節文件` 可填功能層文件路徑、待產出、或「無法由目前來源確認」。
+
+本章不得用無來源的 request / response mapping、欄位轉換、retry flow 或外部錯誤處理細節補齊版面。若這些細節可由 source evidence 確認，系統總覽應保留 endpoint、destination key、related module、可觀測線索與功能層文件導覽，完整 mapping 與流程放在功能層文件。
+
+## 6. 錯誤訊息、Exception 與 Log 線索摘要
+
+**撰寫目標**:
+整理系統層級可查找的錯誤與 Log 線索，協助維運人員先判斷問題可能屬於設定、外部介面、資料、權限、批次、檔案或程式錯誤。
+
+### 6.1 重要錯誤與 Exception 摘要
+
+使用 Markdown Table 呈現：
+
+| Error / Exception / Message | 類型 | 可能模組 | 可能問題分類 | 第一查找方向 | 來源位置 |
+|---|---|---|---|---|---|
+
+此表保留系統層可分流的錯誤 / exception / message 線索，不補寫無來源的完整處理策略。若錯誤只屬某單一功能，應在「第一查找方向」指向功能層文件或待補功能層文件。
+
+### 6.2 Log Keyword 摘要
+
+使用 Markdown Table 呈現：
+
+| Log Keyword / Pattern | 可能階段 | Related Module | 必要識別資訊 | 可能位置 | 維運用途 |
+|---|---|---|---|---|---|
+
+不得自行創造看似正式的 Log pattern。若無法確認正式 log path，應寫「無法由目前來源確認」，不要假設 `/var/log`、`logs/` 或平台路徑。
+
+### 6.3 SOP 人工補充提醒
+
+若錯誤訊息、Log keyword 或 exception 足以判斷問題類型，但不足以確認正式處理方式，應列入人工補充表：
+
+| 線索 | 已可確認 | 不可確認 | 需要人工補充原因 |
+|---|---|---|---|
+
+本節不得自行補出正式 SOP。
+
+## 7. 維運初步分流判斷
+
+**撰寫目標**:
+提供系統層級 triage map，協助 L1/L2 Support 根據使用者回報、Log、設定、外部介面或資料現象，決定第一步應查什麼。
+
+使用 Markdown Table 呈現：
+
+| 問題現象 | 優先檢查類型 | 第一查找資訊 | 可能分類 | 下一步文件或模組 | 升級條件 |
+|---|---|---|---|---|---|
+
+建議分流分類：
+
+- 設定問題：config key 缺漏、環境值錯誤、feature flag、timeout、pool。
+- 外部介面問題：API timeout、SFTP 失敗、MQ backlog、queue message failed、DB link error。
+- 資料問題：狀態異常、查無資料、重複資料、interface table 未處理。
+- 權限問題：role、permission、scope、資料範圍。
+- 檔案問題：檔案不存在、格式錯誤、路徑錯誤、解析失敗。
+- 批次問題：scheduler 未執行、job failed、重複執行、卡在處理中。
+- 程式問題：exception、null handling、mapping error、framework startup failure。
+
+分流表只能提供初步方向，不得指示直接修改 DB、重跑 production job、刪除檔案、清 queue 或變更正式設定。
+
+## 8. Source Code 證據範圍與人工補充項目
+
+**撰寫目標**:
+明確分離可確認項目與需人工補充項目，避免系統層文件混入無來源的業務背景或正式維運規則。
+
+### 8.1 可確認項目
+
+使用條列式或表格列出可直接由來源確認的項目，例如 module inventory、entrypoint、config key、dependency、external endpoint key、Log keyword、error message、DB object。
+
+### 8.2 需人工補充項目
+
+只列會影響維運交接、支援分流、正式處理、安全操作或 escalation 的缺口：
+
+| 補充項目 | 為何 Source Code 無法確認 | 對維運的影響 | 建議補充來源 |
+|---|---|---|---|
+
+常見人工補充項目包含 owner、SLA、正式 escalation path、production runbook、正式監控閾值、正式資料修復流程、正式重跑權限與正式 rollback 流程。
+
+---
+
+## 品質檢查
+
+產生或審查系統層級維運總覽時，應檢查以下事項：
+
+- 文件是否只描述系統層級資訊，沒有混入單一功能的完整流程。
+- 功能內容是否只以功能清單、模組索引或文件導覽方式出現。
+- 是否列出 config key 類型與來源，但沒有揭露 secret value。
+- 外部介面是否保留系統層 source-backed 線索，並將 request / response mapping 導向功能層文件。
+- 錯誤與 Log 是否保留系統層 source-backed 分流線索，且沒有編造正式 SOP。
+- 維運分流是否只提供初步查找方向，沒有指示 production 操作。
+- 每一個重要資訊是否具備來源位置；無法確認事項是否集中列入人工補充項目。
+- 無法確認事項是否明確標示「無法由目前來源確認」或列入人工補充項目。
+- 技術識別碼、config key、API path、SQL keyword、class name、method name 與 CLI command 是否保留英文原文。
+- 文件是否沒有把 web、Java、Spring、REST、server deployment 或 HTTP endpoint 當成所有系統的預設前提。
+- DB SQL、desktop application、mobile app、ERP、batch 或 integration system 不適用的欄位是否以 `N/A`、`Unknown` 或「無法由目前來源確認」處理，而不是硬填猜測內容。
+
+## 與功能層文件的銜接
+
+系統層文件可以引用功能層文件，但不得取代功能層文件。
+
+建議在系統層文件中使用以下導覽欄位：
+
+| 系統層項目 | 對應功能層文件 | 文件狀態 | 備註 |
+|---|---|---|---|
+| `{module or function group}` | `{feature doc path or TBD}` | `Exists / Missing / Not Required / Unknown` | `{reason}` |
+
+若功能層文件尚未存在，系統層文件只能標示 `Missing` 或 `TBD`，不得直接把功能細節補進 S01。

package/README.md

@@ -0,0 +1,116 @@
+# ops-wiki-agent-kit
+
+`ops-wiki-agent-kit` 是用來把 Ops Wiki agent toolkit 初始化到既有專案的 npm CLI package。
+
+安裝後會建立或更新目標專案的 `.github` toolkit 內容：
+
+- `.github/agents`
+- `.github/prompts`
+- `.github/skills`
+
+此 package 不會散佈 `.github/copilot-instructions.md`。
+
+## 使用方式
+
+在目標專案根目錄執行：
+
+```bash
+npx ops-wiki-agent-kit init
+```
+
+預設行為：
+
+- 將 toolkit 複製到目前目錄的 `.github`
+- 已存在的檔案不會被覆蓋
+- 已存在的檔案會顯示為 `skip`
+
+指定目標專案：
+
+```bash
+npx ops-wiki-agent-kit init --target ./my-project
+```
+
+預覽將寫入的檔案：
+
+```bash
+npx ops-wiki-agent-kit init --dry-run
+```
+
+允許覆蓋既有檔案：
+
+```bash
+npx ops-wiki-agent-kit init --force
+```
+
+## 發佈流程
+
+第一次發佈前需要登入 npm：
+
+```bash
+npm login
+```
+
+登入後確認目前帳號：
+
+```bash
+npm whoami
+```
+
+發佈前先檢查會被打包的內容：
+
+```bash
+npm run pack:dry-run
+```
+
+確認 package 內只包含 npm 必要檔案與 `.github/agents`、`.github/prompts`、`.github/skills` 後，再發佈：
+
+```bash
+npm publish
+```
+
+發佈後，其他專案即可使用：
+
+```bash
+npx ops-wiki-agent-kit init
+```
+
+## 套件命名
+
+建議 package name：
+
+```text
+ops-wiki-agent-kit
+```
+
+原因：
+
+- 保留 `ops-wiki` 專案語意
+- 表示內容是 agent、prompt、skill toolkit
+- `npx ops-wiki-agent-kit init` 可讀性足夠
+- 名稱長度適中
+
+如果未來要放到 npm organization scope，也可以改成：
+
+```text
+@acer/ops-wiki-agent-kit
+```
+
+scope package 第一次發佈通常要指定 access：
+
+```bash
+npm publish --access public
+```
+
+## 開發檢查
+
+顯示 CLI help：
+
+```bash
+npm run check
+```
+
+檢查 npm package 內容：
+
+```bash
+npm run pack:dry-run
+```

package/ops-wiki-agent-kit.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageJson = require("./package.json");
+
+const packageGithubDir = path.resolve(__dirname, ".github");
+const toolkitRoots = ["agents", "prompts", "skills"];
+
+function printHelp() {
+  console.log(`ops-wiki-agent-kit
+
+Usage:
+  npx ops-wiki-agent-kit init [options]
+
+Options:
+  --target <path>   Install into the target project directory. Default: current directory.
+  --force           Overwrite existing files.
+  --dry-run         Show planned changes without writing files.
+  --help            Show this help.
+  --version         Show package version.
+`);
+}
+
+function parseArgs(argv) {
+  const options = {
+    command: null,
+    target: process.cwd(),
+    force: false,
+    dryRun: false
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--version" || arg === "-v") {
+      options.version = true;
+    } else if (arg === "--force") {
+      options.force = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--target") {
+      const target = argv[index + 1];
+      if (!target || target.startsWith("--")) {
+        throw new Error("--target requires a path.");
+      }
+      options.target = path.resolve(process.cwd(), target);
+      index += 1;
+    } else if (!options.command) {
+      options.command = arg;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function walkFiles(rootDir) {
+  const results = [];
+  const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const entryPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkFiles(entryPath));
+    } else if (entry.isFile()) {
+      results.push(entryPath);
+    }
+  }
+
+  return results;
+}
+
+function getToolkitFiles() {
+  const files = [];
+
+  for (const toolkitRoot of toolkitRoots) {
+    const sourceDir = path.join(packageGithubDir, toolkitRoot);
+    if (!fs.existsSync(sourceDir)) {
+      throw new Error(`Toolkit directory not found: ${sourceDir}`);
+    }
+
+    for (const sourceFile of walkFiles(sourceDir)) {
+      files.push({
+        sourceFile,
+        relativePath: path.join(toolkitRoot, path.relative(sourceDir, sourceFile))
+      });
+    }
+  }
+
+  return files;
+}
+
+function copyToolkit(options) {
+  const targetRoot = path.resolve(options.target);
+  const targetGithubDir = path.join(targetRoot, ".github");
+  const toolkitFiles = getToolkitFiles();
+  const actions = {
+    created: 0,
+    overwritten: 0,
+    skipped: 0
+  };
+
+  for (const { sourceFile, relativePath } of toolkitFiles) {
+    const targetFile = path.join(targetGithubDir, relativePath);
+    const displayPath = `.github/${relativePath.replaceAll(path.sep, "/")}`;
+    const targetExists = fs.existsSync(targetFile);
+
+    if (targetExists && !options.force) {
+      actions.skipped += 1;
+      console.log(`skip      ${displayPath}`);
+      continue;
+    }
+
+    if (options.dryRun) {
+      console.log(`${targetExists ? "overwrite" : "create   "} ${displayPath}`);
+      if (targetExists) {
+        actions.overwritten += 1;
+      } else {
+        actions.created += 1;
+      }
+      continue;
+    }
+
+    fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+    fs.copyFileSync(sourceFile, targetFile);
+
+    if (targetExists) {
+      actions.overwritten += 1;
+      console.log(`overwrite ${displayPath}`);
+    } else {
+      actions.created += 1;
+      console.log(`create    ${displayPath}`);
+    }
+  }
+
+  return actions;
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (options.version) {
+    console.log(packageJson.version);
+    return;
+  }
+
+  if (options.command !== "init") {
+    printHelp();
+    process.exitCode = 1;
+    return;
+  }
+
+  const actions = copyToolkit(options);
+  const mode = options.dryRun ? "Dry run complete" : "Install complete";
+  console.log(`${mode}: ${actions.created} created, ${actions.overwritten} overwritten, ${actions.skipped} skipped.`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ops-wiki-agent-kit",
+  "version": "0.1.0",
+  "description": "Install Ops Wiki agent, prompt, and skill toolkits into a project.",
+  "license": "UNLICENSED",
+  "bin": {
+    "ops-wiki-agent-kit": "./ops-wiki-agent-kit.js"
+  },
+  "files": [
+    ".github/agents/",
+    ".github/prompts/",
+    ".github/skills/",
+    "ops-wiki-agent-kit.js"
+  ],
+  "scripts": {
+    "check": "node ops-wiki-agent-kit.js --help",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}