@k2works/claude-code-booster 4.17.0 → 5.1.0

package/lib/assets/.claude/skills/closing-iteration/SKILL.md

@@ -112,6 +112,20 @@ KPT（Keep / Problem / Try）で振り返り、`docs/development/retrospective-N
 - `mkdocs.yml`: ふりかえり・完了報告書・新規レビュー・新規 ADR・マニュアルの新規章をナビゲーションに追加
 - 追加行のインデントが既存ナビと一致しているか確認する
 
+### ステップ 7.5: OKF 適用（`apply-okf`）
+
+`docs/` が OKF バンドルなら、クローズで生まれた・更新された文書に規約を適用する。クローズは 1 イテレーションで最も多くの文書が動く局面（計画の実績更新・ふりかえり・報告書・レビューレポート・ADR・マニュアル）なので、`--changed` でまとめて掛ける。
+
+```bash
+python .claude/skills/apply-okf/scripts/okf_apply.py apply docs --changed --by <agent>
+gulp okf:check
+```
+
+- `retrospective-N.md`・`iteration_report-N.md`・レビューレポートは新規 → `draft` で登録。ユーザーが報告書を承認したら `verify --by human:<id>`
+- `iteration_plan-N.md` は実績で本文が変わるので `generated` が更新される。計画自体は `stable` のまま残す（後継は報告書であり、計画は廃止ではない）
+- 置き換えた ADR や旧手順があれば `deprecate --replaced-by` で後継に繋ぐ
+- `gulp okf:check` が ERROR 0 であることを確認してからコミットする
+
 ### （任意）ステップ 8: ジャーナル（`creating-journal`）
 
 長いセッションや区切りとして、判断・詰まり・学びを `docs/journal/YYYYMMDD.md` に残すと、コミットログに載らない意思決定の経緯を追跡できる。
@@ -130,6 +144,7 @@ KPT（Keep / Problem / Try）で振り返り、`docs/development/retrospective-N
 - [ ] GitHub Issue クローズ・Project Status 更新
 - [ ] **ユーザーマニュアルが実装と一致**（UI 変更ありなら本文・キャプチャを更新／変更なしならその旨を報告書に記録）
 - [ ] `docs/index.md` / `docs/development/index.md` / `mkdocs.yml` 同期
+- [ ] OKF バンドルなら `apply-okf` を変更分に適用・報告書承認後に `verify`・`gulp okf:check` ERROR 0
 - [ ] 各ステップの成果を意味のある単位でコミット（`git-commit`）
 
 ## コミットの区切り
@@ -156,5 +171,6 @@ KPT（Keep / Problem / Try）で振り返り、`docs/development/retrospective-N
 - `syncing-github-project` — GitHub 同期（ステップ 6）
 - `creating-manual` — ユーザーマニュアルの更新・画面キャプチャ再生成（ステップ 6.5）
 - `operating-docs` — ドキュメントインデックス更新・Lint（ステップ 7）
+- `apply-okf` — クローズで動いた文書への OKF 規約適用（ステップ 7.5）
 - `creating-journal` — セッション記録（任意ステップ 8）
 - `git-commit` — 各ステップ成果のコミット

package/lib/assets/.claude/skills/creating-adr/SKILL.md

@@ -79,12 +79,14 @@ ADR の価値は「決定そのもの」ではなく「なぜその決定に至
 1. `docs/adr/` ディレクトリ内の既存 ADR の最大番号を確認する
 2. 次の連番でテンプレートに基づいて ADR を作成する
 3. `docs/index.md` と `mkdocs.yml` を更新する
+4. `apply-okf` スキルで OKF バンドルに登録する（`docs/` が OKF バンドルの場合）。ADR 本文を自分が書いたので `--by` はエージェント、`status` は未レビューの `draft` になる。置換した旧 ADR があれば `deprecate --replaced-by adr/NNN-new.md` で `deprecated` にする
 
 ### 既存設計からの ADR 抽出
 
 1. アーキテクチャ設計ドキュメントを読み込む
 2. 主要な技術的意思決定を識別する
 3. 各決定を ADR として記録する
+4. 記録した ADR をまとめて `apply-okf` に掛ける（`apply docs --changed --by <agent>`）
 
 ## 途中から再開・更新
 
@@ -105,9 +107,11 @@ ADR の価値は「決定そのもの」ではなく「なぜその決定に至
 - 配置場所は必ず `docs/adr/`。新規作成時は `docs/index.md` と `mkdocs.yml` も更新する
 - ユーザーの指示があるまでコミットしない
 - コンテキストの明確化・代替案の記録・影響の両面記載・コンプライアンス項目を必ず含める
+- ADR 本文の「ステータス」と OKF の `status` は別物。本文のステータス（提案中 / 承認済み / 廃止 / 置換）は意思決定の状態、フロントマターの `status`（draft / stable / deprecated）は文書の消費可否。承認されたら `apply-okf` の `verify --by human:<id>` で `stable` に昇格させ、置換・廃止されたら `deprecate` で `deprecated` にする
 
 ## 関連スキル
 
 - `analyzing-architecture` — アーキテクチャ設計（ADR の主な発生源）
 - `analyzing-tech-stack` — 技術スタック選定（ADR として記録すべき決定）
+- `apply-okf` — 作成・承認・置換した ADR を OKF バンドルに反映
 - `git-commit` — ADR 作成後のコミット

package/lib/assets/.claude/skills/creating-journal/SKILL.md

@@ -82,7 +82,17 @@ description: その日の Skill 実行と意思決定を物語形式で `docs/jo
 
 このセッション中のコミットを `git log --oneline` で抽出し、テーブル化する。フェーズ別に分けるとさらに読みやすい。
 
-### 6. コミット
+### 6. OKF バンドルに登録
+
+`docs/` が OKF バンドル（ルート `index.md` に `okf_version` がある）なら、`apply-okf` スキルでジャーナルにフロントマターを付ける。
+
+```bash
+python .claude/skills/apply-okf/scripts/okf_apply.py apply docs docs/journal/<today>.md --by <agent>
+```
+
+ジャーナルは本文をエージェントが書くので `--by` は `claude-code/<model>` のようなエージェント形式。`type` は `journal/` から `Journal` と推定される。追記の場合も本文が変わるので `generated.at` が更新される（これが「最後に書いた日時」を正しく表す）。`journal/index.md` へのエントリ追加と `log.md` への記録はスクリプトが行う。
+
+### 7. コミット
 
 ```text
 docs(journal): YYYY-MM-DD のセッション記録を追加
@@ -126,4 +136,5 @@ docs(journal): YYYY-MM-DD のジャーナルに <セクション名> を追記
 - `creating-iteration-report` — イテレーション完了時のフォーマル報告書 (ジャーナルとは別)
 - `creating-release-report` — リリース完了時のフォーマル報告書
 - `tracking-progress` — 進捗の定量分析
+- `apply-okf` — ジャーナルへの OKF フロントマター付与と `journal/index.md`・`log.md` 更新
 - `operating-docs` — ジャーナル追加後のインデックス更新 (`--update` で `docs/index.md` 同期)

package/lib/assets/.claude/skills/migrating-okf/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: migrating-okf
+description: プロジェクトドキュメント（docs/ 配下の要件定義・設計・運用手順・ADR など）を Open Knowledge Format（OKF）の知識バンドルに移行し、OKF 仕様のバージョンアップ（v0.1→v0.2 など）にも追従させる。移行は `docs/reference/OKF導入ガイド_V0.2.md` に準拠する。「ドキュメントを OKF に移行したい」「知識バンドルを作りたい」「Markdown にフロントマターを付けてエージェントが読める形にしたい」「OKF のバージョンを上げたい」「timestamp を generated に置き換えたい」「OKF に適合しているか検証したい」「index.md / log.md を整備したい」「エージェント向けのナレッジベースを整備したい」といった場面で必ず発動する。既存ドキュメントに来歴（sources）・信頼（generated/verified）・ライフサイクル（status/stale_after）を付与する作業や、エージェントが生成した知識の検証状態を管理したい場面でも積極的に使うこと。
+---
+
+# OKF 移行
+
+プロジェクトの Markdown ドキュメントを OKF（Open Knowledge Format）の**知識バンドル**に移行し、仕様バージョンアップに追従させる。
+
+仕様の日本語リファレンスは `docs/reference/OKF導入ガイド_V0.2.md`。**作業前に必ず読む**。特に §4（コンセプト文書）・§5（来歴・信頼・ライフサイクル）・§11（適合性）・§13（バージョン間の変更点）・§14（導入手順）が本スキルの根拠になる。ガイドと本スキルが食い違う場合はガイドを正とする。
+
+同じディレクトリに `PROJECT.md` があれば必ず読む。バンドルの置き場所・対象ディレクトリ・既定の `generated.by`・除外パターンなど、プロジェクト固有の値はそこにある。
+
+## なぜ OKF に移行するのか
+
+エージェントが繰り返し参照し、書き換えもする知識には「どこから来たか（来歴）」「誰が確認したか（信頼）」「まだ有効か（鮮度）」が要る。素の Markdown にはそれを置く場所がない。OKF は YAML フロントマターを持つ Markdown のディレクトリというだけの最小規約で、この 3 つを第一級にする。移行の本質はフォーマット変換ではなく、**各文書に「信頼してよい根拠」を持たせること**である。
+
+## モード
+
+| モード | 用途 |
+| :--- | :--- |
+| `--plan` | 対象文書を棚卸しし、バンドル構造と `type` 割り当て案を提示する。ファイルは変更しない |
+| `--migrate` | 文書に OKF フロントマターを付与し、`index.md`・`log.md` を整備する（既定） |
+| `--upgrade <version>` | 既存バンドルを指定バージョンの仕様に追従させる（例: `--upgrade 0.2`） |
+| `--check` | バンドルの適合性を検証し、違反と警告を報告する |
+
+指定がなければ、バンドルが未作成なら `--plan` → 確認 → `--migrate`、作成済みなら `--check` から始める。
+
+## 進め方
+
+### 1. 棚卸し（`--plan`）
+
+1. 対象ディレクトリ（既定 `docs/`。`PROJECT.md` で上書き可）の `.md` を列挙する
+2. 各文書を読み、次を判断する
+   - **コンセプトにするか除外するか**。`index.md`・`log.md` は予約名なのでコンセプトにできない。テンプレート（`docs/template/`）や一時的なジャーナルは通常除外する
+   - **`type`**。既存ディレクトリから素直に導く（例: `docs/adr/` → `ADR`、`docs/design/` → `Design`、`docs/operation/` → `Playbook`、`docs/reference/` → `Reference`）。中央登録はないので、説明的で一貫した値を選ぶことだけが要件
+   - **`resource` の有無**。テーブル・API・ダッシュボードなど実在の資産を説明する文書だけに付ける
+3. バンドル構造案を提示する。**既存ディレクトリ構造を尊重する**（移動はリンク切れと git 履歴の断絶を招く）。ガイド §14.2 の骨格はあくまで新規作成時の例
+4. 提案を表にまとめ、ユーザーの確認を得てから `--migrate` に進む
+
+### 2. 移行（`--migrate`）
+
+各コンセプト文書に対して：
+
+1. **フロントマターを付与する**。既存の見出し・本文はそのまま残す
+   - `type`（必須）、`title`（既存の `# 見出し` から）、`description`（本文冒頭から 1 文に要約。無ければ書く）、`tags`
+   - `generated: { by, at }`。`generated` は「**今の本文を誰がいつ書いたか**」を表す。フロントマターを付けただけで本文を変えていないなら、書いた人は変わっていないので、git log の著者から `human:<id>`、`at` は本文を最後に変えたコミットの日時にする。本文を書き換えた（要約を書き足した、構造化のため再構成した）なら本作業のエージェント（例: `claude-code/claude-fable-5`）と現在時刻。著者が git から辿れない（履歴が浅い、インポートされた文書）なら `generated` を省略し、レポートの要確認に載せる。移行しただけの文書にエージェントを著者として書くと、来歴が嘘になる
+   - 既存のフロントマター（Wiki.js の `dateCreated`/`editor`/`published`、Jekyll の `layout` など）があれば**併合**する。意味が対応するキーは OKF に写し（`dateCreated` → `generated.at`）、ツール固有で意味を失うキーは削除し、削除したことをレポートに書く。判断がつかないキーは残す（未知キーは仕様上有効）
+   - `status`。レビュー済みの安定文書は `stable`（省略可）、WIP は `draft`、置き換え済みは `deprecated`
+   - `sources`。文書が根拠にしている外部資料・上流文書（要件定義→設計など）があれば登録し、`id` を付ける。本文中で根拠を示す箇所は `[^id]` 脚注に変える
+   - `stale_after` は「定期的に見直すべき」文書（環境手順・技術スタック）にだけ付ける。全文書に一律付けると陳腐化警告がノイズになる
+2. **リンクをバンドル相対（`/` 始まり）に揃える**。既存の相対リンクが壊れていなければ無理に変えなくてよい（相対も仕様上有効）
+3. **本文を構造化する**。慣習見出し（`# Schema`・`# Examples`）が適用できる箇所だけ合わせる。文章を書き換えて意味を変えない。本文に NBSP（U+00A0）や全角スペースが混じっていることがあるので、文字列一致で編集する前に該当行を実際に読む
+4. 各ディレクトリの `index.md` を生成・更新する。エントリにはフロントマターの `description` を反映する。バンドルルートの `index.md` のみ `okf_version: "0.2"` を持つフロントマターを置く
+5. バンドルルートの `log.md` に移行エントリを追記する（`## YYYY-MM-DD` 見出し、新しい日付が上）
+6. `scripts/okf_check.py --check` を実行し、違反ゼロを確認する
+
+フロントマター付与の例：
+
+**Input**（`docs/design/data-model.md` 冒頭）
+
+```markdown
+# データモデル設計
+
+本ドキュメントは受注管理システムのデータモデルを定義する。要件定義書のユースケース一覧を基に...
+```
+
+**Output**
+
+```markdown
+---
+type: Design
+title: データモデル設計
+description: 受注管理システムの概念・論理データモデルとテーブル定義。
+tags: [design, data-model]
+status: stable
+generated: { by: human:k2works, at: 2026-06-10T09:12:00Z }   # 本文未変更なので git 著者と最終更新コミット
+sources:
+  - id: requirements
+    resource: /requirements/requirements_definition.md
+    title: 要件定義書
+---
+
+# データモデル設計
+
+本ドキュメントは受注管理システムのデータモデルを定義する。要件定義書のユースケース一覧を基に...[^requirements]
+
+[^requirements]: 要件定義書
+```
+
+### 3. バージョンアップ（`--upgrade <version>`）
+
+仕様が改訂されたとき、既存バンドルを新バージョンに追従させる。
+
+1. バンドルルート `index.md` の `okf_version` で現在バージョンを確認する（無ければ v0.1 相当とみなす）
+2. ガイドの「vX.Y からの変更点」節（v0.2 なら §13）を読み、**破壊的変更**と**追加的変更**を分けて把握する
+3. 破壊的変更を機械的に適用する。v0.1→v0.2 は `scripts/okf_check.py --upgrade 0.2` が対応している
+   - `timestamp` → `generated: { by, at }`（`by` は git log の著者から推定。人なら `human:<id>`。推定できなければ `unknown/legacy` とし、レポートに列挙する）
+   - 本文 `# Citations` リスト → フロントマター `sources`
+4. 追加的変更は「付けられるところだけ」付ける。無いことも仕様上有効なので、根拠の無いフィールドを埋めるためにでっち上げない
+5. `okf_version` を更新し、`log.md` に **Upgrade** エントリを追記する
+6. `--check` で違反ゼロを確認する
+
+将来のバージョン（v0.3 以降）でスクリプトが未対応なら、ガイドの変更点節を読んで変換規則を洗い出し、スクリプトに変換を追加してから適用する。手作業で全文書を直さない。
+
+### 4. 検証（`--check`）
+
+```bash
+python .claude/skills/migrating-okf/scripts/okf_check.py --check <バンドルルート>
+```
+
+運用手順書に登録済みの Gulp タスク `gulp okf:check`（同じスクリプトを呼ぶ）でもよい。`gulp okf:help` に `okf:upgrade`・`okf:viz`（上流ツールでグラフ可視化）などの一覧がある。
+
+検証内容はガイド §11 に対応する。
+
+| レベル | 内容 |
+| :--- | :--- |
+| ERROR | 予約名以外の `.md` にフロントマターが無い / `type` が空 / `index.md`（ルート以外）にフロントマターがある / `log.md` の日付見出しが `YYYY-MM-DD` でない |
+| WARN | `generated` が無い / `generated.by` の形式がアクター規約に合わない / 脚注ラベルに対応する `sources[].id` が無い / タイムスタンプに UTC オフセットが無い / バンドル内リンク切れ / `stale_after` を過ぎている |
+
+検査はコードフェンスとインラインコードの中を無視する（仕様例のリンクや脚注を誤検知しないため）。ERROR は移行完了前に必ず解消する。WARN は仕様上は適合なので、内容を確認して意図的なら残してよい。リンク切れは「まだ書かれていない知識」でも有効だが、移行直後のリンク切れはたいてい単なるパス間違いなので直す。
+
+## 判断に迷いやすい点
+
+- **`verified` を付けてよいのは、実際に人またはプロセスが内容を確認したときだけ。** 移行作業でエージェントが読んだだけでは `verified` にしない。信頼ティアの意味が壊れる
+- **`description` は検索スニペットと `index.md` に使われる。** 「〜について記述したドキュメント」のような自己言及ではなく、中身を 1 文で言う
+- **`type` の数は絞る。** ディレクトリごとに 1 つが目安。文書ごとに新しい型を発明すると消費側のルーティングが効かない
+- **本文の意味を変えない。** 移行は構造の付与であって推敲ではない。内容の誤りに気づいたらレポートに書き、別作業にする
+- **mkdocs との共存。** フロントマターは MkDocs でもメタデータとして無害に扱われる。`docs/index.md` は MkDocs のトップページでもあるので、OKF の `okf_version` フロントマターを追加しても既存本文は残す
+
+## 完了報告
+
+`--migrate` / `--upgrade` の最後に次を報告する。
+
+```markdown
+## OKF 移行結果
+
+- バンドル: <パス>（okf_version: <版>）
+- コンセプト: <N> 件（type 別内訳）
+- 除外: <N> 件（理由）
+- 検証: ERROR 0 / WARN <N>
+- 要確認: <generated.by を推定できなかった文書、リンク切れ、内容の疑義 など>
+```
+
+## 関連スキル
+
+- `operating-docs` — `docs/index.md`・`mkdocs.yml` の更新と Markdown Lint
+- `creating-adr` — ADR は `type: ADR` のコンセプトとして移行する
+- `git-commit` — 移行後のコミット（ユーザーの指示があるまでコミットしない）

package/lib/assets/.claude/skills/migrating-okf/evals/evals.json

@@ -0,0 +1,23 @@
+{
+  "skill_name": "migrating-okf",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "docs/ 配下の設計ドキュメントと ADR を OKF の知識バンドルに移行して。docs/reference/OKF導入ガイド_V0.2.md に沿ってやってほしい。まず案を見せてから実行して。",
+      "expected_output": "棚卸し表（type 割り当て）を提示後、各 .md に type/title/description/generated 等のフロントマターを付与し、index.md に okf_version、log.md に移行エントリを追加し、検証で ERROR 0 を報告する",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "knowledge/ にある OKF バンドルが古い v0.1 形式（timestamp と # Citations を使っている）なので v0.2 に上げて。",
+      "expected_output": "timestamp を generated.at に、# Citations を sources に変換し、okf_version を 0.2 に更新、log.md に Upgrade エントリを追記、検証結果を報告する",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "knowledge/ の OKF バンドルが仕様に適合しているかチェックして、問題があれば直して。",
+      "expected_output": "okf_check.py --check を実行し、ERROR を修正、WARN は内容を判断して報告する",
+      "files": []
+    }
+  ]
+}