adr-init

name	adr-init
description	ADR (Architecture Decision Record) の置き場を Sphinx プロジェクトに用意する。「ADR 管理を始めたい」「ADR を初期化」と依頼された場面で発火する。既存 Sphinx プロジェクトがあればその配下に ADR セクションを追加し、無ければ ADR 専用の Sphinx プロジェクトを新規生成する。
license	MIT
allowed-tools	Bash, Read, Write, Edit, Glob

ステップ 1: モード判定

Glob で対象リポジトリ内の conf.py を検索する。

**/conf.py

• conf.py が見つかった場合 → セクション追加モードへ進む。
• conf.py が見つからない場合 → スタンドアロンモードへ進む。

conf.py が複数マッチした場合（monorepo 等）は、リポジトリルートに最も近い（パス階層が最も浅い）conf.py を既定の <sphinx-root> とする。それでも判断がつかない場合（同階層に複数ある等）は、どの Sphinx プロジェクトに ADR セクションを追加するかをユーザーに確認する。

---

セクション追加モード（既存 Sphinx プロジェクトを検出した場合）

ステップ 2-A: ADR セクションディレクトリを作成する

検出した conf.py が置かれているディレクトリを <sphinx-root> とする。 <sphinx-root>/adr/ ディレクトリと <sphinx-root>/adr/_templates/ ディレクトリを作成する。

ステップ 2-B: テンプレートファイルを配置する

このスキルディレクトリ（skills/adr-init/）の templates/ から以下をコピーする。

コピー元（スキルの templates/）	コピー先
templates/index.md	<sphinx-root>/adr/index.md
templates/_templates/adr_template.md	<sphinx-root>/adr/_templates/adr_template.md

index.md は glob toctree（[0-9][0-9][0-9][0-9]-*）を含んでいるため、ADR ファイル追加後に index.md を編集する必要はない。

ステップ 2-C: 親プロジェクトの index.md に ADR セクションを組み込む

<sphinx-root>/index.md（または index.rst）の {toctree} ブロックに adr/index を追加する。

• toctree エントリは拡張子なしで記述する（adr/index であって adr/index.md ではない）。

• 既に adr/index が含まれていれば何もしない。

• ファイルが RST 形式の場合は .. toctree:: ディレクティブに追記する。例:

  .. toctree::
  
     adr/index
  

ステップ 2-D: conf.py の exclude_patterns を更新する

<sphinx-root>/conf.py の exclude_patterns に 'adr/_templates' を追加する。

• 既に含まれていれば何もしない。
• adr_template.md が Sphinx のビルド対象に含まれないようにするための設定。

例（既存リストへの追記）:

exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "adr/_templates"]

ステップ 2-E: myst_parser の確認

<sphinx-root>/conf.py の extensions に myst_parser が含まれていない場合、sphinx-config スキルを使って追加することを提案する（強制ではない）。sphinx-config スキルが使えない場合は親 conf.py の extensions を直接編集してもよい。

---

スタンドアロンモード（既存 Sphinx プロジェクトが無い場合）

ステップ 3-A: 配置先ディレクトリを決める

既定の配置先は docs/adr/。ユーザーが別のパスを指定していればそちらを使う。

ステップ 3-B: テンプレートツリーをコピーする

このスキルディレクトリの templates/ ツリー全体を配置先へコピーする。

コピー元（スキルの templates/）	コピー先
templates/conf.py	<配置先>/conf.py
templates/index.md	<配置先>/index.md
templates/Makefile	<配置先>/Makefile
templates/make.bat	<配置先>/make.bat
templates/_static/.gitkeep	<配置先>/_static/.gitkeep
templates/_templates/adr_template.md	<配置先>/_templates/adr_template.md

ステップ 3-C: conf.py のプレースホルダを置換する

コピーした <配置先>/conf.py の以下のプレースホルダを実値で置換する。

プレースホルダ	置換値
{{PROJECT}}	プロジェクト名（ユーザー指定、または推定できる場合はリポジトリ名）
{{AUTHOR}}	著者名（ユーザー指定）
{{YEAR}}	現在の年（4 桁）

プロジェクト名・著者名が不明な場合はユーザーに確認してから置換する。

---

共通事項（両モード）

• ADR ファイル本体（NNNN-<slug>.md）と index.md の構造は両モードで共通。adr-author スキルはこの共通構造に対して動作する。
• 完了後、adr-author スキルで最初の ADR を起票できる旨をユーザーに案内する。
• Sphinx のビルド・テーマ運用には sphinx-skills（drillan/sphinx-skills）が利用可能である旨を案内する（ハード依存ではなく参考案内）。
• ADR が 1 件も無い状態で sphinx-build -W（警告をエラー化）を実行すると、adr/index.md の glob toctree（[0-9][0-9][0-9][0-9]-*）が空マッチ警告を出しビルドが失敗する。これは初期化直後の想定内の挙動であり、adr-author で最初の ADR を起票すれば解消する。最初の ADR を起票するまでは -W なしでビルドする。