docs: add standards adoption playbook

README.md

@@ -9,6 +9,7 @@ It combines shared config packages, repository templates, and a CLI so teams can
 Product documentation lives in `docs/` and is published as a VitePress site in English and Japanese.
 
 - overview: `docs/index.md`
+- adoption playbook: `docs/adoption-playbook.md`
 - concepts and safety model: `docs/concepts.md`
 - CLI usage: `docs/cli.md`
 - base preset details: `docs/templates/base.md`

docs/.vitepress/config.mts

@@ -7,6 +7,7 @@ const base =
 const englishNav = [
   { text: "Overview", link: "/" },
   { text: "Concepts", link: "/concepts" },
+  { text: "Adoption", link: "/adoption-playbook" },
   { text: "CLI", link: "/cli" },
   { text: "Base Template", link: "/templates/base" },
 ];
@@ -17,6 +18,7 @@ const englishSidebar = [
     items: [
       { text: "Overview", link: "/" },
       { text: "Concepts", link: "/concepts" },
+      { text: "Adoption Playbook", link: "/adoption-playbook" },
       { text: "CLI", link: "/cli" },
       { text: "Base Template", link: "/templates/base" },
     ],
@@ -26,6 +28,7 @@ const englishSidebar = [
 const japaneseNav = [
   { text: "概要", link: "/ja/" },
   { text: "基本概念", link: "/ja/concepts" },
+  { text: "導入", link: "/ja/adoption-playbook" },
   { text: "CLI", link: "/ja/cli" },
   { text: "Base Template", link: "/ja/templates/base" },
 ];
@@ -36,6 +39,7 @@ const japaneseSidebar = [
     items: [
       { text: "概要", link: "/ja/" },
       { text: "基本概念", link: "/ja/concepts" },
+      { text: "導入プレイブック", link: "/ja/adoption-playbook" },
       { text: "CLI", link: "/ja/cli" },
       { text: "Base Template", link: "/ja/templates/base" },
     ],

docs/adoption-playbook.md

@@ -0,0 +1,98 @@
+# Adoption Playbook
+
+This page explains how to roll out shared repository standards into real repositories without creating a large, risky migration.
+
+## Why standards rollouts usually fail
+
+Many standards projects fail for one of these reasons:
+
+- they try to replace too many files at once
+- they assume all target repositories are greenfield
+- they hide the real diff behind generators
+- they require teams to trust a tool before they can review the change
+
+Those problems get worse in AI-assisted repositories, where multiple tools, prompts, and local conventions evolve quickly.
+
+## The design goal
+
+`project-standards` is intentionally shaped around a small, reviewable adoption path:
+
+- preview the exact diff first
+- keep writes explicit
+- avoid clobbering repository-specific files
+- separate shared config from in-repo templates
+- make future upgrades possible without forcing full replacement
+
+## The rollout strategy
+
+### 1. Start with `diff`
+
+The first step for an existing repository should always be a read-only preview:
+
+```sh
+node packages/cli/dist/index.js diff ../target-repository
+```
+
+This keeps the review conversation grounded in the actual change instead of an abstract promise.
+
+### 2. Prefer `--dry-run` before real writes
+
+If the diff looks reasonable, the next step is still a non-destructive dry run:
+
+```sh
+node packages/cli/dist/index.js apply ../target-repository --include quality --dry-run
+```
+
+That extra step matters when the target repository is active and has local conventions that the base preset should not silently overwrite.
+
+### 3. Use file strategies that respect reality
+
+The current MVP intentionally keeps the strategy surface small:
+
+- `create_if_missing`
+- `replace_if_managed`
+
+This avoids pretending that partial ownership is easy. A repository either opts into a managed file or keeps its local version.
+
+### 4. Keep shared config and templates separate
+
+Two kinds of standards should not be treated the same:
+
+- shared config packages are better referenced than copied
+- repository-local files still need templates and explicit ownership rules
+
+That separation makes it easier to update behavior later without hiding the source of truth.
+
+## Why this works well for AI-assisted repositories
+
+AI-assisted development increases the number of generated docs, prompts, rules, and local workflow files. That makes accidental drift more likely.
+
+A useful standards tool in that environment should:
+
+- show the diff before writing
+- keep managed boundaries obvious
+- avoid destructive upgrades by default
+- make quality-related adoption small enough for normal review
+
+`project-standards` is designed around those constraints instead of treating them as edge cases.
+
+## A practical rollout order
+
+For an existing repository, a safe sequence usually looks like this:
+
+1. inspect the current repository and decide what should remain local
+2. run `diff`
+3. apply only the quality-related subset with `--dry-run`
+4. review the result with the team
+5. run the real apply once the managed boundaries are accepted
+6. leave stack-specific follow-ups for separate PRs
+
+## What this page should signal
+
+This repository is not just a config dump. It is an attempt to make repository standards adoptable in the messy conditions where teams actually work:
+
+- existing repositories
+- multiple tools
+- AI-assisted workflows
+- partial ownership
+- review-first engineering culture

docs/index.md

@@ -21,6 +21,7 @@ It combines shared config packages, repository templates, and a CLI so teams can
 ## Read next
 
 - [Concepts](./concepts.md)
+- [Adoption Playbook](./adoption-playbook.md)
 - [CLI](./cli.md)
 - [Base Template](./templates/base.md)
 

docs/ja/adoption-playbook.md

@@ -0,0 +1,92 @@
+# 導入プレイブック
+
+このページでは、共有リポジトリ標準を大きくて危険な migration にせず、既存リポジトリへ小さく導入する考え方を整理します。
+
+## なぜ標準導入は失敗しやすいのか
+
+標準導入がうまくいかない理由は、だいたい次のどれかです。
+
+- 一度に置き換えるファイルが多すぎる
+- 対象リポジトリが greenfield だと暗黙に仮定している
+- generator の裏に実際の差分が隠れている
+- review より先にツールへの信頼を要求してしまう
+
+この問題は、AI 支援開発の repo でさらに大きくなります。prompt、rule、agent guide、local workflow が増えるほど、repo ごとの差異や drift は起きやすくなるからです。
+
+## 設計目標
+
+`project-standards` は、既存 repo にも導入できるよう、次の方針で設計しています。
+
+- まず実差分を `diff` で見る
+- write を明示的にする
+- repo 固有ファイルをむやみに上書きしない
+- shared config と template の責務を分ける
+- 将来の upgrade を見据えつつ、最初の導入は小さく保つ
+
+## 導入戦略
+
+### 1. 既存 repo では `diff` から始める
+
+最初の一手は常に read-only preview です。
+
+```sh
+node packages/cli/dist/index.js diff ../target-repository
+```
+
+まず実差分を見せることで、「何が変わるのか分からないまま apply する」状態を避けます。
+
+### 2. 実 apply の前に `--dry-run` を挟む
+
+差分が妥当でも、次の一手はまだ non-destructive であるべきです。
+
+```sh
+node packages/cli/dist/index.js apply ../target-repository --include quality --dry-run
+```
+
+対象 repo が既に運用中で、局所的な慣習や管理境界を持っているときほど、この一段が効きます。
+
+### 3. 現実に合わせた file strategy を使う
+
+MVP では strategy をあえて絞っています。
+
+- `create_if_missing`
+- `replace_if_managed`
+
+partial ownership を簡単に扱えるふりをせず、「そのファイルを managed として引き受けるか、ローカル管理のままにするか」をはっきりさせるためです。
+
+### 4. shared config と template を分ける
+
+repo 標準には、同じように見えて性質が違うものが混ざります。
+
+- shared config package として参照したいもの
+- repo 内に実ファイルとして存在してほしい template
+
+この 2 つを分けることで、後から挙動を更新しやすくしつつ、正本の位置も分かりやすくできます。
+
+## AI 支援開発の repo で効く理由
+
+AI 支援開発では、doc、prompt、rule、command、local workflow file が増えやすく、repo drift が起きやすくなります。
+
+その環境で役に立つ標準導入ツールは、少なくとも次を満たす必要があります。
+
+- write 前に実差分を見せる
+- managed boundary を明確にする
+- destructive upgrade を default にしない
+- quality 系の導入を通常の review で見切れる大きさに保つ
+
+`project-standards` は、これらを後付けの例外ではなく、最初から前提条件として扱っています。
+
+## 実際の導入順
+
+既存 repo に入れるときの安全な順番は、だいたい次のとおりです。
+
+1. 現在の repo を見て、ローカルに残すものを決める
+2. `diff` を取る
+3. quality 系だけ `--dry-run` で当てる
+4. team で review する
+5. managed boundary に合意できたら real apply を実行する
+6. stack 固有の follow-up は別 PR に分ける
+
+## このページで伝えたいこと
+
+この repo は単なる設定配布ではありません。既存 repo、複数ツール、AI 支援開発、partial ownership という現実の条件下で、標準導入を review-first に成立させるための platform として設計しています。

docs/ja/index.md

@@ -21,6 +21,7 @@ shared config package、repository template、CLI を 1 か所にまとめるこ
 ## 次に読む
 
 - [基本概念](./concepts.md)
+- [導入プレイブック](./adoption-playbook.md)
 - [CLI](./cli.md)
 - [Base Template](./templates/base.md)