nextaltair OKF Bundle Maintenance
Markdown ファイルのディレクトリを Open Knowledge Format (OKF)
バンドルとして保守する汎用スキル。frontmatter を唯一の正準ソース (SSoT) とし、
index.md や人間向けテーブルは frontmatter から生成する派生物として扱う。
プロジェクト非依存・stdlib only。--bundle-root で対象ディレクトリを受け取るので、
ADR・知識ベース・用語集など任意の OKF バンドルに使える。
OKF の必須ルール (SPEC v0.1)
- frontmatter の必須キーは
typeのみ。title/description/tags/timestampは任意。 - スカラー値メタデータ (status / timestamp 等) は frontmatter に置く。本文の散文に書かない。
index.md/log.mdは予約ファイル名。概念ドキュメントには使わない。log.mdの日付は ISO 8601。index.md/ 生成テーブルは生成物。手編集しない。
スクリプト (scripts/)
すべて python3 単体 (依存なし) で動く。
| スクリプト | 役割 |
|---|---|
okf_validate.py --bundle-root DIR |
frontmatter 検証 (必須 type / ISO timestamp / --require・--exclude・--skip-missing 可) |
okf_index.py --bundle-root DIR --index |
OKF index.md (箇条書き) を生成 |
okf_index.py --bundle-root DIR --table --columns ... --link-column ... |
列を frontmatter キーで指定する Markdown テーブルを生成 |
okf_index.py の --check は書き込まず「生成物が最新か」だけ検証する (drift 検出)。
--table-output 先に <!-- OKF-TABLE:START --> / <!-- OKF-TABLE:END --> マーカーがあれば、
その間だけ置換するのでテーブル前後の散文を保持できる。
okf_validate.py --skip-missing は frontmatter が無いファイルを違反にせず除外する
(段階的移行 / lazy migration 用)。frontmatter 未付与の既存ドキュメントを許容しつつ、
付与済みのものだけ type 必須 / ISO timestamp を強制したいバンドルで使う。
全件 frontmatter 必須のバンドル (例: ADR) には付けない。
Workflow (Agent が判断で起動)
概念ドキュメントを追加・編集・改番したら:
- 検証:
python3 <skill>/scripts/okf_validate.py --bundle-root <DIR> [--exclude README.md]— frontmatter 欠落や必須キー漏れを補う。 - 再生成:
python3 <skill>/scripts/okf_index.py --bundle-root <DIR> --index ...(必要なら--table ...も) で派生ビューを更新する。 - コミット: 生成物を含めてコミットする (docs chore は main 直 push 可なプロジェクトもある)。
CI 自走に頼らず Agent の判断で回す。許容するのは「実行漏れ (索引が一時的に古い)」だけで、 生成は決定論なので内容ドリフトは発生しない。索引やテーブルを手で書き起こさない (書式ブレ・転記ミスの温床)。
プロジェクト固有の責務 (スキル外)
「その概念を参照しているコードが概念より新しい」式の drift 検出 (REFERENCE-DRIFT) は 各プロジェクトの enactment surface に依存するため、本スキルには含めない。プロジェクト側の 専用ツール (例: ADR とソースの整合を見る drift チェッカー) が担う。
使用例
# ADR バンドル検証 (全件 frontmatter 必須)
python3 <skill-dir>/scripts/okf_validate.py --bundle-root docs/decisions --exclude README.md
# index.md + README テーブルを再生成
make adr-index # 内部で okf_index.py を呼ぶ (Makefile target がある場合)
# 通常ドキュメント検証 (lazy migration: 未付与は skip、付与済みのみ検証)
python3 <skill-dir>/scripts/okf_validate.py --bundle-root docs --skip-missing