docs-steward

Docs Steward

プロジェクト内のリポジトリで、ドキュメントの品質、アーキテクチャ、フレームワークの最新性を維持します。

入力： $ARGUMENTS — モードキーワード、フレームワーク名、移行の目標、または自然言語によるドキュメントの依頼。

---

標準用語

docs-steward の出力全体で、次の標準用語をそのまま使用してください。

用語	意味	使用しない用語
docs framework	ドキュメントをレンダリングする主要なプラットフォーム（Starlight、Docusaurus、Fumadocs、Sphinx、MkDocs）	「site generator」（意味が広すぎます）
theme layer	フレームワークの上に載せる視覚デザインとコンポーネントのスキン	「framework」
content graph	ナビゲーション＋ページ間の関係＋生成されたインデックス	「folder list」
init	既存のリポジトリで、既存の内容を変更せずにドキュメントの基盤を整えること	「reinitialize/overwrite」
sync	ソースとなるドキュメントの状態からフレームワークの成果物を再生成すること	「deploy」
maintain	構造、リンク、差異、ビルドの整合性に対する読み取り専用の健全性チェック	「rewrite」
enhance	既存ドキュメントの明瞭さ、構造、UX、見つけやすさを改善すること	「recreate」
matrix run	1つのリポジトリで、検出されたすべてのフレームワークのワークフローを実行すること	「auto」
migration	同等性を確認しながら、あるdocs frameworkから別のdocs frameworkへ計画的に移行すること	「instant convert」
version refresh	最新の安定版フレームワーク／ツールのバージョンに合わせて参照情報を更新すること	「blind upgrade」
project-local	スキルが現在のプロジェクトの範囲内にインストールされ、使用されること	「global install」

---

ディスパッチテーブル

$ARGUMENTS をモードに振り分けます。

$ARGUMENTS のパターン	モード	開始位置
（空）または auto	Auto	Mode A
framework <name> <action>（<action> ∈ `sync	enhance	maintain
framework <name>	Framework-targeted（デフォルトのアクション：maintain）	Mode B
init / init <name>	Init	Mode I
init-sync / init-sync <name>	Init+Sync	Mode I
sync / sync <name>	Sync	Mode C
enhance / enhance <path>	Enhance	Mode D
maintain / maintain <name>	Maintain	Mode E
research / research versions	Research	Mode F
matrix	Matrix	Mode G
migrate <from> -> <to>	Migrate	Mode H
generate api <module>	Generate	Mode J
generate adr <decision>	Generate	Mode J
generate runbook <process>	Generate	Mode J
generate onboard	Generate	Mode J
generate glossary	Generate	Mode J
自然言語：「generate API docs/reference」	Generate	Mode J
自然言語：「create an ADR/decision record」	Generate	Mode J
自然言語：「write a runbook/onboarding guide」	Generate	Mode J
自然言語：「set up <framework> docs from scratch and keep it in sync」	Init+Sync	Mode I
自然言語：「docs are stale/broken/outdated」	Maintain	Mode E
自然言語：「improve docs UX/content/nav」	Enhance	Mode D
自然言語：「upgrade latest framework versions」	Research	Mode F
自然言語：「update README」、「sync AGENTS.md」、「refresh docs instructions」	Auto	Mode A の docs-surface ルート
アプリの API、スキル、または MCP サーバーの構築依頼	Refuse	依頼を別の方法に案内

分類ゲーティングの手順

変更を伴うモードを実行する前に、次の分類ゲーティング基準を適用してください。

1. references/framework-detection.md を使ってフレームワークを検出します。
2. フレームワークが1つ検出された場合は、そのフレームワークで続行します。
3. 複数のフレームワークが検出され、ユーザーが対象を指定していない場合は、実行ごとにユーザーに選択を求めます（対話モード）。
4. フレームワークを示す情報がない場合は、編集を始める前にドキュメントのスタックをユーザーに尋ねます（対話モード）。
5. ヘッドレス／非対話型の実行では、Headless Fallback Contract を適用します。

ヘッドレスフォールバック契約

確認のやり取りができない場合：

1. フレームワークの対象が曖昧な場合、または明示的な対象が指定されていない状態で複数のフレームワークが検出された場合は、検出されたフレームワーク全体を対象とする読み取り専用の Mode G (Matrix) として Mode E (Maintain) を実行します。
2. 変更を伴う自動処理は、フレームワークの選択が明示されている場合、または単一フレームワークの確度が高く、かつトリガーカテゴリが Mode A で安全とされる場合に限り許可します。
3. フレームワークは、決定論的な順序で処理します：starlight/astro、docusaurus、fumadocs、sphinx、mkdocs。
4. ヘッドレスフォールバックが適用され、明示的なフレームワーク選択を待つ間、変更を伴うモード（init、init-sync、sync、enhance、research、migrate）をスキップした場合は、警告を出力します。
5. フレームワークが検出されない場合は、「framework target required」と記載した読み取り専用の保守レポートを返し、編集は行いません。

---

ライブバージョン調査（「latest」の場合は必須）

ユーザーが最新バージョンを（明示的または暗黙的に）求めた場合は、変更を適用する前に必ずバージョン情報を更新します：

1. ツールを使ってパッケージレジストリ（npm/PyPI）を照会します。
2. references/*.md のフレームワークリファレンススナップショットを更新します。
3. 編集したリファレンスに、バージョン情報の出典と日付を記録します。
4. その後にのみ、依存関係や設定の更新を提案します。

現在のレジストリデータによる根拠なしに「latest」と主張してはいけません。

---

Mode A：自動

デフォルトのオーケストレーターモードです。

A.1 トリガーカテゴリ

モードを選択する前に、検出された変更シグナルを分類します：

• コンテンツのみ： ナビゲーション／設定／ビルドへの影響を伴わない、ページ本文・例・フロントマターの編集。
• 構造／設定： ドキュメント／フレームワーク／設定／ナビゲーション／ビルド関連の変更（サイドバー／ナビゲーションツリー、フレームワーク設定、ドキュメントのビルド連携、生成されたドキュメント成果物）。
• 依存関係／バージョン： ドキュメントフレームワーク／テーマ／プラグインの依存関係、またはロックファイル／バージョンの変更。
• ドキュメント表層： プロジェクトの README、ネストされた AGENTS.md、生成されたドキュメントインデックス、またはドキュメントの動作変更を反映する必要があるコントリビューター向けドキュメント。

A.2 処理経路

1. ドキュメントフレームワークを検出します。
2. 複数のフレームワークがある場合は、この実行でどれを対象にするか尋ねます。
3. トリガーカテゴリに応じて処理を振り分けます：
   • コンテンツのみ -> Mode D (Enhance) を実行し、その後、任意で Mode E (Maintain) のチェックを行います。
   • 構造／設定 -> Mode C (Sync) + Mode E (Maintain)。
   • 依存関係／バージョン -> Mode F (Research) + Mode C (Sync) + Mode E (Maintain)。
   • ドキュメント表層 -> 生成／連携に変更がある場合は Mode C (Sync)、それ以外の場合は Mode D (Enhance) + Mode E (Maintain)。
4. トリガーカテゴリまたは意図が不明確な場合は、編集前に焦点を絞った確認質問を1つ行います。

A.3 自動同期の安全性

1. 自動同期は、フレームワークの対象が明示されている場合、または単一フレームワークの確度が高い場合に限り許可されます。
2. ヘッドレスで複数フレームワークが曖昧な実行では、読み取り専用のフォールバック（Mode E のマトリックス）を維持し、自動同期を行いません。
3. 確度が低い場合、フレームワークのシグナルが競合する場合、または対象範囲がドキュメント内に限定されない場合は、Mode E (Maintain) に切り替えます。

---

Mode B：フレームワーク指定（framework <name> [<action>]）

対応する名前：

• astro / starlight
• docusaurus
• fumadocs
• sphinx
• mkdocs

構文：framework <name> [<action>]。<action> は sync、enhance、maintain、research、migrate のいずれかです。 <action> が省略された場合は、デフォルトで maintain を使用します。 選択したフレームワークに対応するモードを実行します：sync -> Mode C、enhance -> Mode D、maintain -> Mode E、research -> Mode F、migrate -> Mode H。

---

Mode C：同期

生成されたドキュメント成果物の状態を整合させます。

• フレームワーク標準の高度なコンポーネントのサポートとレンダリング経路（Mermaid、コードスニペット、表、埋め込み、タブ／アドモニション）を確認します。

C.1 Astro + Starlight

• Astro の設定と Starlight の統合を確認します。
• プロジェクトのコマンドでドキュメント成果物を再生成します（このリポジトリでは python scripts/docs_sync.py generate）。
• ドキュメントの出力をビルドチェックします。

C.2 Docusaurus

• docusaurus.config.*、サイドバー、ドキュメントのルート構造を検証します。
• 生成されたドキュメントアセットを再ビルドし、ビルドの健全性チェックを実行します。

C.3 Fumadocs

• next.config.*、fumadocs-* パッケージの設定、MDX コンテンツツリーを検証します。
• 該当する場合はインデックス／ナビゲーションを再生成し、Next のビルドチェックを実行します。

C.4 Sphinx

• conf.py、拡張機能のセット、テーマパッケージの整合性を検証します。
• ドキュメント品質のゲートとして、警告を厳格に扱う設定でビルドします。

C.5 MkDocs

• mkdocs.yml、プラグイン構成、ナビゲーション構造を検証します。
• 厳格なビルドチェックを実行し、プラグインのずれを検出します。

C.6 同期出力の要件

• Mermaid、コードスニペット、表、埋め込みコンテンツ、タブ／アドモニションを対象とした「高度なコンポーネントのレンダリングチェック」の概要を含めます。
• 使用したフレームワーク固有のサポート／プラグインを記載し、未対応のコンポーネントには安全な代替手段を示します。
• アクセシビリティに関する注意事項（図のテキストによる代替説明、ラベル付きコードフェンス、タイトル付き埋め込みコンテンツ、タブ／アドモニションのセマンティクス）を含めます。

---

モード D：強化

フレームワークの特性を変えずに、ドキュメントの品質を向上させます。

強化の対象：

• 情報アーキテクチャ（ナビゲーションの明瞭さ、セクションの深さ、ランディングページ）
• 文章の品質（流し読みのしやすさ、例、API／タスク指向の構成）
• 内部リンク（孤立したページの削減、関連リンクの方針）
• ビジュアルドキュメントの UX（コールアウト、タブ、コードのグループ化、アドモニション、図、埋め込みコンテンツ、表）
• 一貫性（スタイル、見出しの深さ、フロントマター、メタデータ）

強化の方向性が曖昧な場合（「開発者向けドキュメント」「マーケティング向けドキュメント」「API ドキュメント」「チュートリアル」など）は、確認の質問をしてください。

D.1 高度なコンポーネントの方針

• 高度なコンポーネントは、装飾ではなく理解を実質的に助ける場合に使用します。
• 使用中のスタックに適したフレームワーク標準のプリミティブを選び、各ページ内で構文とスタイルを統一します。
• 優先するコンポーネント：フロー／アーキテクチャには Mermaid、実装手順にはコードスニペット、比較には表、正式なデモ／メディアには埋め込みコンテンツ、バリエーションや注意事項にはタブ／アドモニションを使用します。
• 出力のアクセシビリティを確保します。平易な説明と図のテキストによる代替説明を追加し、コードブロックには言語ラベルを付け、意味のあるキャプション／タイトルを付けます。また、重要な情報を色だけ、またはタブだけで示すことは避けます。
• フレームワーク固有の構文パターンと安全な代替手段については、references/advanced-components.md を使用します。

D.2 強化出力の要件

• 追加／更新した高度なコンポーネントと、その有用性、フレームワーク上の制約や代替手段を要約します。

---

モード E：保守

読み取り専用の診断と修正計画です。

チェック項目：

1. リンク切れとアンカーのずれ
2. 古いファイル／生成ファイルの不一致
3. ナビゲーションの行き止まりと孤立したページ
4. テーマ／プラグイン依存関係のずれ
5. ビルドの警告／エラー
6. 混在リポジトリにおけるフレームワークの不一致

出力形式：

• 重大（必ず修正）
• 警告（修正を推奨）
• 提案（できれば対応）
• 次に実行するコマンド

---

モード F：調査

フレームワーク／テーマの参照情報を、最新の安定バージョンと高度なパターンに合わせて更新します。

手順：

1. 使用中の各フレームワークについて、パッケージ／バージョンの情報を確認します。
2. 参照スナップショットの各セクションを更新します。
3. 移行に関係する変更点（破壊的変更、非推奨 API、設定の変更）を記載します。
4. 確信度と引用／情報源の確認コマンドを添えて、簡潔な変更概要を返します。

---

モード G：マトリックス

リポジトリ内で検出されたすべてのフレームワークを対象に、条件を制御して実行します。

用途：

• 複数のドキュメントスタックを持つモノレポ
• 並行して進める移行プログラム
• フレームワーク間の同等性監査

マトリックス実行の出力では、フレームワークごとに結果をまとめ、フレームワーク間の競合も含める必要があります。

---

モード H：移行（migrate <from> -> <to>）

移行は v1 の対象範囲です。

対応する移行パス：

• Docusaurus -> Fumadocs
• Sphinx -> MkDocs
• Sphinx -> Starlight
• MkDocs -> Docusaurus

移行フェーズ：

1. インベントリ作成と同等性のベースライン確認
2. コンテンツとナビゲーションのマッピング
3. テーマ／コンポーネントのマッピング
4. ビルド／テストの同等性チェック
5. 段階的なロールアウト計画

一度で完全に変換できるとは約束せず、チェックポイントを設けた段階的な移行を優先します。

---

Mode I：初期化（init、init <framework>、init-sync、init-sync <framework>）

既存のリポジトリで、破壊的な書き換えを行わずにドキュメントサイトの接続設定を初期化します。 このモードは、明示的な init* コマンドと、既存のコードベースで「ドキュメントを初期設定して同期も維持する」という暗黙のリクエストに適用されます。 編集を始める前に、references/init-sync-existing-repos.md と選択したフレームワークのリファレンスを読み込みます。

I.1 フレームワーク選択の動作

1. <framework> が指定されている場合は、そのフレームワークを直接対象にします。
2. <framework> が指定されておらず、フレームワークが1つだけ検出された場合は、検出されたフレームワークを対象にします。
3. 複数のフレームワークが検出され、明示的な対象が指定されていない場合は、ユーザーに選択を求めます。ヘッドレス実行では、Headless Fallback Contract を適用します。
4. フレームワークが検出されず、明示的な対象も指定されていない場合は、ユーザーにサポート対象のフレームワークの選択を求めます。ヘッドレス実行では、「framework target required」を含む読み取り専用の Mode E 出力を返します。

I.2 破壊しない初期化の契約

• 不足しているドキュメントのひな型／設定ファイルのみを作成し、既存のファイルはデフォルトで上書きしません。
• 事前確認ガード：対象のドキュメントルートがすでに存在し、空でない場合、そのルートを再作成または置換しません。ユーザーが明示的に上書きを要求しない限り、既存の場所で不足ファイルのひな型作成のみを続行します。
• 既存のドキュメントコンテンツ、ナビゲーション、フレームワーク設定がある場合は、それらを保持します。
• 要求されたフレームワークが既存のドキュメントフレームワークの接続設定と競合する場合は停止し、保守時の所見と競合の概要を返します（移行には Mode H を使用します）。

I.3 後続のフロー

• init：初期化し、その後の対応として sync と maintain を推奨します。
• init-sync：初期化した後、同じ実行内で Mode C（Sync） と Mode E（Maintain） を実行します。
• 作成したもの、スキップしたもの、およびその理由を必ず報告します。

---

Mode J：生成（generate <type> [<target>]）

ソースコードから技術ドキュメントを生成します。詳細な手順、出力形式、スクリプトの使用方法については、references/generate-mode.md を読み込みます。

サブモード：

コマンド	出力	主要スクリプト
generate api <module>	シグネチャ、docstring、カバレッジを含む API リファレンス	api-surface-extractor.py、doc-coverage-analyzer.py
generate adr <decision>	MADR 形式のアーキテクチャ決定記録	adr-scaffolder.py
generate runbook <process>	コードベースのコマンドを含む運用手順書	—
generate onboard	新規コントリビューター向けオンボーディングガイド	—
generate glossary	コードとドキュメントから抽出した用語の定義	—

J.1 ワークフロー

1. 対象範囲（モジュールパス、プロセス名、またはリポジトリ全体）を特定します。
2. 該当するスクリプトを実行し、ソースから構造化データを抽出します。
3. 抽出したデータを、references/generate-mode.md の形式に従ってドキュメントにまとめます。
4. レビュー用のドラフトを提示します。コンテキストが曖昧な場合は、確認の質問をします。
5. 適切な場所（例：docs/api/、docs/decisions/）に出力を書き込みます。

J.2 生成出力の契約

• 生成するドキュメントはソースコードまで追跡できるようにし（ファイルパスと行番号を含めます）、出所を明示する必要があります。
• API シグネチャや docstring を決して捏造せず、抽出するか、ドキュメント未記載として明示します。
• ADR は data/adr-template.json の MADR v3 形式に従います。
• プロジェクトの言語とスタイルに合った data/docstring-formats.json の docstring 形式規約を使用します。

---

対応範囲の境界

対象： ドキュメントフレームワークの運用、破壊しないドキュメントの初期化、バージョンの更新、ビルド／健全性診断、品質向上、ドキュメントの移行、コードからの技術ドキュメント生成、プロジェクトの README 更新、およびドキュメントの動作が変更された場合の、ネストされた AGENTS.md 指示ドキュメントの更新。

対象外：

• 無関係な製品機能やバックエンド API の作成・編集
• スキル定義、エージェント、MCP サーバーの作成・変更（skill-creator、agent-conventions、または mcp-creator に引き継ぎます）
• ドキュメントパイプラインの必要性を超える CI/CD の再設計
• ドキュメント以外のフロントエンドアプリケーションの実装

---

スケーリング戦略

スコープ	実行戦略	オーナーシップのルール
1 つのフレームワークと 1～3 個のドキュメントファイル	インラインで編集し、その後フレームワーク固有の検証を実行します	変更対象のファイルは 1 人のエージェントがすべて担当します
1 つのフレームワークと 4～12 個のドキュメントファイル	ドキュメント領域ごとにまとめます：ナビゲーション／設定、生成されたリファレンス、説明ページ、README/AGENTS.md	同じファイルを複数の作業者に割り当ててはいけません
2～5 個のフレームワーク、または 13 個以上のドキュメントファイル	決定論的なフレームワーク順にマトリックス形式のウェーブを実施し、その後、保守レポートを統合します	フレームワークまたはファイルのバッチごとに作業者を 1 人割り当て、検証後にのみマージします
あらゆる移行またはバージョン更新	まず計画チェックポイントを設け、その後、ロールバックの注記を付けながら段階的に編集します	同等性が確認されるまで、ソースと対象のドキュメントルートを追跡可能な状態に保ちます

---

リファレンスファイルインデックス

リファレンスは必要に応じて読み込み、すべてを一度に読み込まないでください。

ファイル	内容	読み込むタイミング
references/framework-detection.md	フレームワーク判定シグナルのマップ、複数フレームワークの振り分けルール	すべてのモード
references/advanced-components.md	安全な代替手段を含む、フレームワーク固有の Mermaid／コードブロック／テーブル／埋め込みパターン	sync/enhance
references/init-sync-existing-repos.md	既存リポジトリ向けの非破壊的でフレームワークを考慮したブートストラップと、後続の同期ワークフロー	init/init-sync
references/astro-starlight.md	Astro + Starlight の高度なセットアップとチェック	framework/sync/maintain/enhance
references/docusaurus.md	Docusaurus の高度な設定とプラグインのチェック	framework/sync/maintain/enhance
references/fumadocs.md	Fumadocs + Next の高度なセットアップとチェック	framework/sync/maintain/enhance
references/sphinx.md	Sphinx + テーマのマトリックス（Shibuya/PyData/Furo/Book）	framework/sync/maintain/enhance
references/mkdocs.md	MkDocs + Material／プラグインスタックのチェック	framework/sync/maintain/enhance
references/migrations.md	移行手順書と同等性テンプレート	migrate/matrix
references/version-refresh.md	最新バージョンへの更新ワークフローと証拠に関するルール	調査、および最新バージョンに関するすべてのリクエスト
references/generate-mode.md	Generate サブモードの手順、出力形式、スクリプトの使用方法	generate
data/docstring-formats.json	言語ごとの docstring 形式標準（Google、NumPy、Sphinx、JSDoc、TSDoc）	generate api
data/adr-template.json	MADR v3 テンプレートの構造とファイル命名規則	generate adr

---

検証条件

完了基準：

1. 変更されたドキュメントの内容は、ソースに基づき、プロジェクト内に限定されています。
2. 変更を伴うモードでは、該当するフレームワークのビルド、ドキュメント生成、またはヘルスチェックを実行します。
3. Maintain モードは読み取り専用のままとし、編集する代わりに次に実行するコマンドを報告します。
4. 該当する場合、スキルの変更では次の証明用コマンドが成功します：
   • python scripts/check.py
   • 生成されたドキュメントの内容が変わる場合は python scripts/docs_sync.py

---

重要なルール

1. ユーザーの意図または対象フレームワークが曖昧な場合は、編集前に少なくとも 1 つ確認の質問をしてください。
2. 複数フレームワークのリポジトリでは、明示的に上書きされない限り、auto モードの実行ごとに、どのフレームワークを操作するか確認してください。
3. 新しいレジストリに基づく証拠を確認し、リファレンススナップショットを更新せずに、「最新」バージョンを主張してはいけません。
4. 既定では操作をプロジェクト内に限定し、グローバルなインストール環境を前提にしないでください。
5. ドキュメントを変更した後は、フレームワークに適したビルドまたは検証チェックを実行してください。
6. Maintain モードは読み取り専用です。まず診断し、その後、具体的な修正案を提示してください。
7. Migration モードは段階的に実施し、元に戻せるようにしてください。一度にすべてを書き換える破壊的な方法は避けてください。
8. 対象範囲外のリクエストには対応せず、適切な専門スキルに案内してください。
9. 既存リポジトリでの Init モードは非破壊的です。ユーザーが明示的に上書きを要求しない限り、不足しているファイルのみを作成してください。
10. Generate モードではソースコードから情報を抽出してください。シグネチャ、docstring、API の詳細を捏造してはいけません。