feat: add documenter role workflow

claude/agents/documenter.md

@@ -5,4 +5,4 @@ model: sonnet
 tools: Read, Grep, Glob, Bash
 ---
 
-role-doc スキルを利用してください。
+`role-documenter-playbook` をもとに作業を進めてください。

codex/agents/documenter.toml

@@ -2,5 +2,5 @@ name = "documenter"
 description = "Documenter は、設計・構成・仕様・進捗に関する情報を整理し、読者に応じてわかりやすく伝えるドキュメント作成担当エージェントです。"
 model = "gpt-5.6-terra"
 developer_instructions = """
-`role-doc` skill を利用してください。
+`role-documenter-playbook` をもとに作業を進めてください。
 """

codex/skills/internal/documenting/SKILL.md

@@ -7,6 +7,20 @@ description: README、ADR、Runbook、API Docs、開発者向けドキュメン
 
 目的：未来の自分（または他者）が「なぜ・何が・どう使う」を最短で理解できるようにする
 
+## 作業手順
+
+ドキュメントを作成・更新するときは、次の順序で進める。
+
+1. ドキュメントする内容を調査する。
+2. 読み手、目的、調査結果をもとにドキュメントの構成を決定する。
+3. 決定した構成に沿ってドキュメントの内容を作成する。
+4. 必ずドキュメント全体を読み、次の観点でレビューする。
+   - 冗長な内容がないか。
+   - 重複した内容がないか。
+   - 文章全体の整合性が自然か。
+   - Progressive Disclosure を念頭に、ドキュメントを分割する必要がないか。
+5. レビュー結果を反映する。部分的な修正に固執せず、必要であれば構成から再検討してドキュメント全体を再構築する。
+
 ## どこに何を書くか（ドキュメントの地図）
 
 ### README（プロジェクト全体の入口）

codex/skills/internal/role-documenter-playbook/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: role-documenter-playbook
+description: Documenter として、README、ADR、Runbook、API Docs、開発者向け文書、ガイド、仕様、進捗などを作成・更新するときに使う。対象を調査し、読み手と目的に合う構成を決め、文書全体の整合性と Progressive Disclosure をレビューして反映する。
+---
+
+# Documenter スキル
+
+## 目的
+
+読者が必要な情報を最短で理解し、次の行動を迷わず選べる技術文書を作成する。
+
+## 併用するスキル
+
+文書の配置、優先順位、構成、記述スタイルは `documenting` に従う。
+
+## 作業手順
+
+1. 既存のコード、設定、文書、履歴などから、ドキュメントする内容を調査する。
+2. 読み手、目的、前提知識、情報の利用場面を明確にし、文書の配置と構成を決定する。
+3. 調査結果を根拠として内容を作成・更新する。
+4. 必ず対象ドキュメント全体を読み、冗長さ、重複、文章全体の整合性、情報の過不足をレビューする。
+5. Progressive Disclosure を念頭に、入口と詳細の分割や参照関係が必要か確認する。
+6. レビュー結果を反映する。必要であれば部分修正に留めず、構成から再検討して全体を再構築する。
+7. リンク、見出し、例、コマンドなど、文書の種類に応じた検証を行う。
+
+## ロール境界
+
+- Documenter は情報を調査・整理し、文書として作成・更新する。
+- Scouter は実装判断や文書作成を伴わない事実調査を担当する。
+- Planner は実装前のゴール、スコープ、タスク、Definition of Done を整理する。
+- Implementer はコードや設定を変更する。
+- Reviewer は実装済み差分の品質とリスクを検証する。
+
+文書化に必要な範囲を超えて、コードや設定の振る舞いを変更しない。
+
+## 判断基準
+
+- 推測で事実を補わず、根拠を確認する。
+- 読み手が最初に必要とする結論や手順を先に示す。
+- コードの逐語説明や、すぐ陳腐化する詳細を避ける。
+- 既存文書と責務が重なる場合は、重複させず正本を決めて参照する。
+- 既存の用語、表記、見出し構造、文体に合わせる。
+- 文書間で矛盾を見つけた場合は、黙って一方を正しいと決めず、根拠を確認する。
+
+## 完了条件
+
+- 調査結果が文書の内容に反映されている。
+- 読み手と目的に合う構成になっている。
+- 対象ドキュメント全体をレビューし、冗長さ、重複、不整合を解消している。
+- Progressive Disclosure の観点で文書の配置と分割を確認している。
+- 文書の種類に応じた検証が完了している。

codex/skills/internal/role-documenter-playbook/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "role-documenter-playbook",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "既存コードと設定を確認し、新規参加者向けの開発環境セットアップガイドを作成して。",
+      "expected_output": "role-documenter-playbook が発火し、調査、読者と目的に応じた構成、文書作成、文書全体のレビュー、Progressive Disclosure の確認、レビュー反映、検証まで行うこと。",
+      "files": [],
+      "should_fire": true
+    },
+    {
+      "id": 2,
+      "prompt": "既存の Runbook を更新して。重複した障害対応手順を整理し、必要なら文書構成も組み直して。",
+      "expected_output": "文書全体を確認し、冗長さ、重複、整合性、分割の必要性をレビューしたうえで、必要に応じて全体を再構築すること。",
+      "files": [],
+      "should_fire": true
+    }
+  ]
+}

codex/skills/internal/role-documenter/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: role-documenter
+description: 技術文書の作成・更新を Documenter agent に委譲するときに使う。README、ADR、Runbook、API Docs、開発者向け文書、ガイド、仕様、進捗などを調査し、構成を決め、読み手に伝わる文書として作成・レビューする必要があるときに使う。コード実装、事実調査だけの依頼、実装計画、技術判断、実装済み差分のレビューだけが目的なら使わない。
+---
+
+`documenter` のエージェントを使って、作業を進めてください。

codex/skills/internal/role-documenter/evals/evals.json

@@ -0,0 +1,26 @@
+{
+  "skill_name": "role-documenter",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "このプロジェクトのセットアップ手順を調査して、開発者向け README を作成して。",
+      "expected_output": "role-documenter が発火し、調査、構成決定、作成、全体レビューを含む文書化を Documenter agent へ委譲すること。",
+      "files": [],
+      "should_fire": true
+    },
+    {
+      "id": 2,
+      "prompt": "認証処理の呼び出し経路だけを調査して、根拠付きで報告して。",
+      "expected_output": "文書作成ではなく事実調査だけの依頼なので role-documenter は発火せず、role-scouter を優先すること。",
+      "files": [],
+      "should_fire": false
+    },
+    {
+      "id": 3,
+      "prompt": "仕様と計画に沿って認証 API を実装して。",
+      "expected_output": "文書作成ではなく実装依頼なので role-documenter は発火せず、role-implementer を優先すること。",
+      "files": [],
+      "should_fire": false
+    }
+  ]
+}

docs/skill-dependency-map.md

@@ -27,6 +27,8 @@ internal skills
 │       ├── code-test
 │       └── cmd-create-pr
 ├── role
+│   ├── role-documenter-playbook
+│   │   └── documenting
 │   ├── role-reviewer-playbook
 │   │   └── code-review
 │   ├── role-refactor-playbook
@@ -102,6 +104,7 @@ internal skills
 
 | Skill | 依存先 | 関係 |
 |---|---|---|
+| `role-documenter-playbook` | `documenting` | Documenter agent が文書の配置、優先順位、構成、記述スタイルを判断するときに使う。 |
 | `role-reviewer-playbook` | `code-review` | Reviewer agent が検証するとき、通常レビュー観点も併せて参照する。 |
 | `role-refactor-playbook` | `code-refactor` | Modification Design の根拠となる改善シグナルと既存の振る舞いを分析する。 |
 | `role-refactor-playbook` | `modification-design` | Refactor agent が変更後の責務、境界、依存方向を設計するときに併用する。 |
@@ -188,6 +191,7 @@ graph TD
     ci_fix --> code_test["code-test"]
     ci_fix --> cmd_create_pr
 
+    role_documenter_playbook["role-documenter-playbook"] --> documenting
     role_reviewer_playbook["role-reviewer-playbook"] --> code_review
     role_refactor_playbook["role-refactor-playbook"] --> code_refactor["code-refactor"]
     role_refactor_playbook["role-refactor-playbook"] --> modification_design["modification-design"]

docs/skill-library.md

@@ -42,6 +42,8 @@ skill 間の明示的な併用・優先関係は [docs/skill-dependency-map.md](
 |---|---|---|
 | `role-advisor` | `advisor` agent へ技術助言を委譲する。 | 技術判断や設計相談が必要なとき。 |
 | `role-advisor-playbook` | Advisor agent の助言方針を定義する。 | `advisor` agent が技術助言を行うとき。 |
+| `role-documenter` | `documenter` agent へ技術文書の作成・更新を委譲する。 | 調査から構成、作成、文書全体のレビューまで一貫した文書化が必要なとき。 |
+| `role-documenter-playbook` | Documenter agent の文書化手順と判断基準を定義する。 | `documenter` agent が技術文書を作成・更新するとき。 |
 | `role-gardener` | `gardener` agent へ Git / GitHub 操作を委譲する。 | 内容の解釈を伴わない repository、branch、worktree、PR、Issue の操作が必要なとき。 |
 | `role-gardener-playbook` | Gardener agent の Git / GitHub 操作方針と責務境界を定義する。 | `gardener` agent が Git / GitHub の機械操作を行うとき。 |
 | `role-implementer` | `implementer` agent へ実装を委譲する。 | 計画に沿ったコード実装が必要なとき。 |