dflow-sdd-ddd 0.1.1 → 0.3.0

package/docs/evaluating-dflow.en.md

@@ -0,0 +1,238 @@
+# Evaluating Dflow
+
+> [繁體中文](evaluating-dflow.md) | **English**
+
+A short guide for first-time evaluators deciding whether Dflow fits a project.
+About 10 minutes to read, optional 30 minutes to try in a sample project.
+
+## Who This Guide Is For
+
+You are deciding whether to introduce Dflow into a codebase. You may be a
+tech lead evaluating workflow changes for an AI-assisted team, a solo
+developer comparing AI coding workflows, or a team member asked to assess
+Dflow before broader adoption.
+
+This guide answers the most common evaluation questions in one place. It does
+not replace [`README.md`](../README.en.md) (overview) or [`tutorial/`](../tutorial/)
+(deep walk-throughs); it is a focused decision aid.
+
+## What Is Dflow
+
+Dflow is a workflow kit for AI-assisted development. It gives an AI coding
+agent a concrete process for turning change requests into structured specs,
+domain language, and reviewable code, instead of jumping from prompt straight
+to code.
+
+Dflow is Markdown-based workflow material plus a scaffolding CLI. It does not
+require a runtime, server, or framework. Once `init` runs, Dflow lives entirely
+in your project's `dflow/specs/` directory and AI instruction files.
+
+## What `init` Creates and Does Not Do
+
+`dflow init` (or `npx dflow-sdd-ddd init` on the no-install path) creates:
+
+- A `dflow/specs/` workspace (overview, conventions, domain glossary, context
+  map, architecture/tech-debt, features active/completed). See
+  [`README.md` "Files Created by Init"](../README.en.md#files-created-by-init)
+  for the full tree.
+- A canonical project guide at `dflow/specs/shared/AI-AGENT-GUIDE.md`.
+- Mergeable AI agent instruction files for the tools you select (e.g.,
+  `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
+  `.github/copilot-instructions.md`). Each is a thin pointer to the
+  canonical guide.
+
+`init` does **not**:
+
+- Inspect, refactor, or migrate your application code.
+- Overwrite existing AI agent instruction files; if one exists, Dflow writes
+  a merge snippet under `dflow/specs/shared/` instead.
+- Modify your build system, package manager, or dependencies.
+- Send any data anywhere; it is a local scaffolding command.
+
+## How Dflow Works With Different AI Tools
+
+Dflow targets multiple AI coding agents. After running `init`, you select one
+or more tools and Dflow writes the corresponding shim:
+
+| Tool | Generated file |
+|---|---|
+| Codex / Copilot coding agent | `AGENTS.md` |
+| Claude Code | `CLAUDE.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+Each shim points back to the canonical
+`dflow/specs/shared/AI-AGENT-GUIDE.md`. Practical implications:
+
+- Multiple tools can be active in the same project without diverging
+  workflow rules.
+- Switching or adding tools later does not require re-running `init`; use
+  run `dflow configure-agents` to add another shim.
+- The project guide stays the single source of truth for Dflow workflow
+  behavior.
+
+If your tool does not support custom slash commands, use the same command
+names (e.g., `/dflow:new-feature`) as plain instructions in chat. Dflow is
+Markdown-based workflow material; it works with any AI agent that can read
+project instructions and repository context.
+
+For a tool-specific walk-through of what `init` writes and how the slash
+commands appear in conversation, see the per-tool guides:
+
+- [Using Dflow with Claude Code](using-with-claude-code.en.md)
+- [Using Dflow with Codex CLI](using-with-codex.en.md)
+- [Using Dflow with Gemini CLI](using-with-gemini-cli.en.md)
+- [Using Dflow with GitHub Copilot](using-with-github-copilot.en.md)
+
+## Greenfield or Brownfield: Choosing a Track
+
+Pick **Greenfield** if:
+
+- You are starting a new system or a new bounded module.
+- You have room to shape architecture before legacy constraints accumulate.
+- You want explicit domain models from feature 1.
+
+Pick **Brownfield** if:
+
+- You are extending or modifying an existing codebase.
+- Business rules are scattered across handlers, stored procedures, UI code,
+  or scripts.
+- You want to introduce specs and domain extraction incrementally without
+  refactoring everything first.
+
+Mixed cases:
+
+- New module inside an existing app: usually Greenfield, scoped to the new
+  bounded context.
+- Existing app with clean architecture and active development: either track
+  works; Brownfield is safer if rules are not yet documented.
+
+## A 30-Minute Evaluation Playbook
+
+This walk-through lets you see what Dflow does without committing it to a
+real codebase.
+
+1. **Create a sample project** (Greenfield):
+
+   ```bash
+   mkdir dflow-sample && cd dflow-sample
+   git init
+   ```
+
+2. **Install and run init**:
+
+   ```bash
+   npm install -g dflow-sdd-ddd
+   dflow init
+   ```
+
+   If you prefer not to install globally, use `npx dflow-sdd-ddd init`
+   instead. When prompted, choose Greenfield. Pick one AI tool to generate
+   the shim for.
+
+3. **Inspect what was created**:
+
+   ```bash
+   ls -la
+   find dflow -type f
+   ```
+
+   Open `dflow/specs/shared/_overview.md`,
+   `dflow/specs/shared/_conventions.md`, and
+   `dflow/specs/shared/AI-AGENT-GUIDE.md` to see the shape.
+
+4. **Read one tutorial walk-through** to see what a real feature flow looks
+   like end to end:
+   - Greenfield: [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)
+   - Brownfield: [`tutorial/02-brownfield/`](../tutorial/02-brownfield/walkthrough-00-setup.md)
+
+5. **Optional: try one workflow command**. Open the sample project in your
+   AI tool and ask it to run `/dflow:new-feature` (or paste the equivalent
+   instruction in chat). Inspect what it writes to `dflow/specs/`.
+
+6. **Decide and clean up**. If Dflow does not fit, delete the sample
+   directory. There is no global state to clean; nothing was installed
+   beyond the one-shot `npx` cache.
+
+If you want a deeper read instead of running anything, the tutorial
+walk-throughs cover the same flow with worked outputs you can compare
+against.
+
+## What If You Stop Using Dflow
+
+Dflow is designed for low cost to try and low cost to leave:
+
+- Nothing depends on the `dflow-sdd-ddd` CLI being installed after `init`.
+- The generated files are plain Markdown; remove Dflow from a project with
+  `rm -rf dflow/` plus deleting the AI agent shim files you no longer want.
+- Existing project instruction files (e.g., a pre-existing `CLAUDE.md`) are
+  not modified by Dflow, so reverting is straightforward.
+
+This means an evaluation pass leaves no permanent footprint if you decide
+not to adopt.
+
+## Cost Per Feature: A Rough Estimate
+
+Dflow scales ceremony to change risk through three tiers (see
+[`README.md` "Workflow Model"](../README.en.md#workflow-model) for full
+detail):
+
+- **T1 Heavy** — new features, new phases, new Aggregates or Bounded
+  Contexts, architecture changes, new business rules. A full phase-spec
+  with domain modeling, behavior examples, an implementation plan, and
+  verification + finish checks. The cost is real but proportional to
+  the risk being managed.
+- **T2 Light** — bug fixes (logic errors), UI verification adjustments,
+  small changes with a business-rule delta. A lightweight spec, focused
+  verification, and confirmation that the fix lands in the correct
+  architectural layer.
+- **T3 Trivial** — button colors, copy typos, pure formatting — **no
+  business-rule, Domain, or data-structure changes**. One line in
+  `_index.md`; no separate spec file.
+
+Tier choice is not always manual: `/dflow:new-feature` and
+`/dflow:new-phase` default to T1; `/dflow:modify-existing` and
+`/dflow:bug-fix` let the AI judge T1/T2/T3 based on what is actually
+changing. Pure typo / formatting commits (e.g., `prettier`,
+`dotnet format`) can skip Dflow entirely and just `git commit` — Dflow
+is for changes with business semantics or structural impact.
+
+## Project Language Compatibility
+
+Dflow templates use **canonical English** structure (headings, field labels)
+so AI agents can locate sections reliably across projects. The free-form
+content you write inside templates can be in any team language — English,
+Traditional Chinese, Simplified Chinese, or others. The init flow asks for
+the project's prose language and stores it in
+`dflow/specs/shared/_conventions.md`.
+
+Practical effect:
+
+- AI tools see stable English structure across projects.
+- Humans read and write specs in the team's chosen language.
+- No need to translate templates or maintain parallel localized copies.
+
+## Where to Go Next
+
+If you decided Dflow fits:
+
+- Run `init` in your real project (consider a branch first).
+- Read [`tutorial/`](../tutorial/) for end-to-end walk-throughs and worked
+  outputs.
+- See [`CONTRIBUTING.md`](../CONTRIBUTING.md) before opening issues or
+  pull requests.
+
+If you are still deciding:
+
+- Read [`docs/why-ddd-for-ai.en.md`](why-ddd-for-ai.en.md) for the design
+  rationale behind spec-first plus DDD.
+- Compare a tutorial scenario step-by-step with its `outputs/` tree to see
+  what production-shape Dflow specs look like.
+
+If Dflow does not fit your project today:
+
+- The structured-spec idea is portable; you can adopt parts of it without
+  the CLI.
+- Open a docs feedback issue (see
+  [`CONTRIBUTING.md`](../CONTRIBUTING.md)) if a specific gap blocked you.
+  That feedback helps future evaluators.

package/docs/evaluating-dflow.md

@@ -0,0 +1,169 @@
+# 評估 Dflow
+
+> **繁體中文** | [English](evaluating-dflow.en.md)
+
+首次評估 Dflow 是否適合專案的簡明指引。
+閱讀約需 10 分鐘；可選擇再花 30 分鐘在範例專案中實際試用。
+
+## 本指引的適用對象
+
+你正在評估是否要在一個 codebase 中引入 Dflow。你可能是正在評估 AI 輔助團隊 workflow 變更的技術主管、比較各種 AI 開發 workflow 的獨立開發者，或是在更廣泛採用前受指派評估 Dflow 的團隊成員。
+
+本指引把最常見的評估問題彙整在一處。它不取代
+[`README.md`](../README.md)（概覽）或 [`tutorial/`](../tutorial/)
+（深度 walk-through）；它是一份聚焦的決策輔助文件。
+
+## Dflow 是什麼
+
+Dflow 是一套 AI 輔助開發的 workflow 工具集。它為 AI 程式設計助理提供具體流程，把變更需求轉成結構化規格、領域語言、與可審查的程式碼，而不是從 prompt 直接跳到程式碼。
+
+Dflow 是 Markdown-based 的 workflow 材料加上一個 scaffolding CLI。它不需要任何 runtime、server 或 framework。`init` 跑完之後，Dflow 完全存在於你的專案的 `dflow/specs/` 目錄與 AI 指示檔中。
+
+## `init` 產生什麼、不做什麼
+
+`dflow init`（或免安裝路徑的 `npx dflow-sdd-ddd init`）會建立：
+
+- `dflow/specs/` workspace（概覽、慣例、領域詞彙表、context map、架構 / 技術債、功能 active/completed）。完整目錄樹見
+  [`README.md` "Init 產生的檔案"](../README.md#init-產生的檔案)。
+- 位於 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的 canonical 專案指南。
+- 你所選工具的可合併 AI 指示檔（例如 `CLAUDE.md`、`AGENTS.md`、`GEMINI.md`、`.github/copilot-instructions.md`）。每個都是指向 canonical 指南的薄 shim。
+
+`init` **不會**：
+
+- 檢查、重構、或遷移你的應用程式碼。
+- 覆寫既有的 AI 指示檔；若檔案已存在，Dflow 改在 `dflow/specs/shared/` 下寫入 merge snippet。
+- 修改你的建構系統、套件管理工具、或相依套件。
+- 傳送任何資料到外部；它是本機的 scaffolding 指令。
+
+## Dflow 如何與不同 AI 工具協作
+
+Dflow 支援多種 AI 程式設計助理。跑完 `init` 後，你選取一個或多個工具，Dflow 就會寫入對應的 shim：
+
+| 工具 | 產生的檔案 |
+|---|---|
+| Codex / Copilot coding agent | `AGENTS.md` |
+| Claude Code | `CLAUDE.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+每個 shim 都指向 canonical 的 `dflow/specs/shared/AI-AGENT-GUIDE.md`。實際意義：
+
+- 同一個專案可以同時啟用多個工具，而不會有 workflow 規則分歧。
+- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim。
+- 專案指南始終保持為 Dflow workflow 行為的單一 source of truth。
+
+若你的工具不支援自訂 slash command，把同名指令（例如 `/dflow:new-feature`）當成普通對話訊息輸入即可。Dflow 是 Markdown-based 的 workflow 材料，能與任何可讀專案指示與 repo 上下文的 AI 助理一起運作。
+
+關於特定工具的 `init` 寫入內容與 slash command 在對話中的呈現方式，見各工具指南：
+
+- [在 Claude Code 中使用 Dflow](using-with-claude-code.md)
+- [在 Codex CLI 中使用 Dflow](using-with-codex.md)
+- [在 Gemini CLI 中使用 Dflow](using-with-gemini-cli.md)
+- [在 GitHub Copilot 中使用 Dflow](using-with-github-copilot.md)
+
+## Greenfield 或 Brownfield：選擇 Track
+
+選 **Greenfield** 若：
+
+- 你正在啟動一個新系統或新的 bounded module。
+- 你有空間在 legacy 限制累積前先塑形架構。
+- 你想從 feature 1 就建立明確的領域模型。
+
+選 **Brownfield** 若：
+
+- 你正在擴充或修改一個既有的 codebase。
+- 業務規則散落在 handler、stored procedure、UI 程式碼或腳本中。
+- 你想漸進引入規格與領域抽出，而不必先做全面重構。
+
+混合情境：
+
+- 在既有 app 內加入新 module：通常選 Greenfield，scope 限定在新的 bounded context。
+- 既有 app 具有乾淨架構且持續開發中：兩種 track 都可行；業務規則尚未文件化時 Brownfield 較安全。
+
+## 30 分鐘評估 Playbook
+
+這份 walk-through 讓你在不動到真實 codebase 的情況下看清楚 Dflow 的實際效果。
+
+1. **建立範例專案**（Greenfield）：
+
+   ```bash
+   mkdir dflow-sample && cd dflow-sample
+   git init
+   ```
+
+2. **安裝並執行 init**：
+
+   ```bash
+   npm install -g dflow-sdd-ddd
+   dflow init
+   ```
+
+   若不想全域安裝，改用 `npx dflow-sdd-ddd init`。提示時選擇 Greenfield，並選取一個 AI 工具產生 shim。
+
+3. **檢視產生的內容**：
+
+   ```bash
+   ls -la
+   find dflow -type f
+   ```
+
+   開啟 `dflow/specs/shared/_overview.md`、`dflow/specs/shared/_conventions.md`、以及 `dflow/specs/shared/AI-AGENT-GUIDE.md` 看看整體架構。
+
+4. **閱讀一份 tutorial walk-through** 以了解完整的 feature flow：
+   - Greenfield：[`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)
+   - Brownfield：[`tutorial/02-brownfield/`](../tutorial/02-brownfield/walkthrough-00-setup.md)
+
+5. **選用：試跑一個 workflow 指令**。在你的 AI 工具中開啟範例專案，叫它執行 `/dflow:new-feature`（或在對話中貼上同等指令）。檢查它寫入 `dflow/specs/` 的內容。
+
+6. **決定並清理**。若 Dflow 不適合，直接刪除範例目錄。沒有全域狀態需要清除；除了一次性的 `npx` 快取，什麼也沒有安裝。
+
+若你偏好不執行任何指令、只做深度閱讀，tutorial walk-through 也涵蓋同樣的 flow，並附有可供對比的預期產出。
+
+## 若你停用 Dflow
+
+Dflow 的設計讓試用成本低、退出成本也低：
+
+- `init` 完成後，你的專案不依賴已安裝的 `dflow-sdd-ddd` CLI。
+- 產生的檔案都是純 Markdown；用 `rm -rf dflow/` 加上刪除你不再需要的 AI 指示 shim 檔案，即可從專案中移除 Dflow。
+- 既有的專案指示檔（例如原本就存在的 `CLAUDE.md`）不會被 Dflow 修改，因此復原很直接。
+
+這表示評估一輪後，若你決定不採用，不會留下任何永久痕跡。
+
+## 每個 Feature 的成本：概略估算
+
+Dflow 依改動深淺將流程份量調整為三個 tier（完整說明見
+[`README.md` "Workflow 模型"](../README.md#workflow-模型)）：
+
+- **T1 Heavy** — 新 feature、新 phase、新 Aggregate 或 Bounded Context、架構變更、新業務規則。需要完整的 phase-spec，包含領域建模、行為例子、實作計畫、以及驗證與收尾檢查。成本確實存在，但與所管理的風險成正比。
+- **T2 Light** — bug fix（邏輯錯誤）、UI 驗證調整、有業務規則 delta 的小幅修改。需要 lightweight spec、聚焦驗證、以及確認修復落在正確的架構層。
+- **T3 Trivial** — 按鈕顏色、文案 typo、純 formatting — **不動業務規則、不動 Domain 概念、不動資料結構**。只需在 `_index.md` 寫一行，不另開 spec 檔。
+
+Tier 不是每次都由 user 手動決定：`/dflow:new-feature` 與 `/dflow:new-phase` 預設一律 T1；`/dflow:modify-existing` 與 `/dflow:bug-fix` 則由 AI 依實際改動內容判斷 T1 / T2 / T3。純 typo / formatting commit（例如 `prettier`、`dotnet format`）可以完全跳過 Dflow 直接 `git commit` — Dflow 是給有業務語意或結構影響的變更使用的。
+
+## 專案語言相容性
+
+Dflow 模板使用**英文 canonical 結構**（標題、欄位標籤），讓 AI 助理能可靠地在不同專案間定位各段落。你在模板內容中自由撰寫的文字可以使用任何團隊語言 — 英文、繁體中文、簡體中文或其他。init 流程會詢問專案的文章語言，並存入 `dflow/specs/shared/_conventions.md`。
+
+實際效果：
+
+- AI 工具在不同專案間看到一致的英文結構。
+- 人員以團隊選定的語言讀寫規格。
+- 不需要翻譯模板或維護平行的在地化副本。
+
+## 下一步
+
+若你決定 Dflow 適合：
+
+- 在你的真實專案執行 `init`（建議先用 branch）。
+- 閱讀 [`tutorial/`](../tutorial/) 取得端到端 walk-through 與預期產出。
+- 開 issue 或 pull request 前，先看 [`CONTRIBUTING.md`](../CONTRIBUTING.md)。
+
+若你還在評估中：
+
+- 閱讀 [為什麼 AI 時代 DDD 更重要](why-ddd-for-ai.md)，了解 spec-first 加上 DDD 背後的設計理由。
+- 把 tutorial 劇情逐步與它的 `outputs/` 目錄對比，看看 Dflow 規格在接近正式的狀態下是什麼樣子。
+
+若 Dflow 目前不適合你的專案：
+
+- structured-spec 的概念是可移植的；你可以採用其中一部分而不需要 CLI。
+- 若某個具體缺口阻礙了你，開一個 docs feedback issue（見 [`CONTRIBUTING.md`](../CONTRIBUTING.md)）。這類回饋對未來的評估者很有幫助。

package/docs/migrating-to-dflow-v1.md

@@ -0,0 +1,230 @@
+# Migrating to Dflow V1
+
+> **Audience**: maintainers of an existing project that adopted an early
+> Dflow form (pre-`dflow-sdd-ddd@0.1.0`) and want to align it with the
+> V1 baseline that ships from npm.
+>
+> **Stance**: V1 took a clean cut. Dflow does not perform automatic
+> migration. This guide is a manual checklist. The CLI only warns when
+> it detects legacy paths; it does not modify existing files.
+
+> **Audience reality (2026-05-15)**: To date, the only known user of
+> this guide has been the **OBTS** migration (a single, completed
+> one-off). Dflow has not had broad pre-V1 adoption; this guide is
+> maintained as a contingency endpoint for `dflow doctor` and
+> `dflow init` warning messages, not as documentation of an active
+> migration program. If you reach this page via those tool outputs
+> and your case isn't covered below, please open a docs feedback issue
+> so the guide can be extended.
+
+## When You Need This Guide
+
+Skip this guide if you started using Dflow at `dflow-sdd-ddd@0.1.0`
+or later. Your project is already on the V1 baseline.
+
+Read this guide if any of the following are true:
+
+- Your project has a top-level `specs/` directory that holds Dflow
+  spec material (not the V1 `dflow/specs/`).
+- Your project has `specs/_共用/` instead of `dflow/specs/shared/`.
+- Your spec headings are in Traditional Chinese rather than the
+  canonical English vocabulary documented in
+  `TEMPLATE-LANGUAGE-GLOSSARY.md`.
+- Your AI instructions point teammates to `/dflow:init-project`
+  instead of the Dflow CLI init command (`dflow init`, or
+  `npx dflow-sdd-ddd init` on the no-install path).
+- Your `CLAUDE.md` (or equivalent root instruction file) was generated
+  by an early Dflow variant that wrote a full Claude-only file rather
+  than the V1 multi-AI thin shim that points to
+  `dflow/specs/shared/AI-AGENT-GUIDE.md`.
+
+You may need only some of these steps; the five sections below are
+independent.
+
+## Before You Start
+
+- Work on a dedicated branch or a disposable copy. None of the steps
+  are destructive, but move-and-rename mistakes are easier to recover
+  from a clean branch.
+- Make sure the working tree is clean (`git status`).
+- Note your current Dflow version if you can identify it. Older
+  internal Dflow forms may not have been versioned at all.
+- Open these V1 reference files for cross-checking:
+  - `TEMPLATE-LANGUAGE-GLOSSARY.md` — canonical English headings.
+  - `TEMPLATE-COVERAGE.md` — V1 file layout and parity matrix.
+  - `docs/evaluating-dflow.en.md` — what a fresh V1 `init` produces, if
+    you want to spin up a sample project to compare against.
+- For an on-demand read-only summary of legacy artifacts in your
+  project, run `dflow doctor` (or `npx dflow-sdd-ddd doctor` on the
+  no-install path). The command lists detected legacy paths and missing
+  V1 fields; it never modifies files.
+
+## Migration Steps
+
+### 1. Move root `specs/` to `dflow/specs/`
+
+V1 puts every Dflow-managed spec under `dflow/specs/`, so the `dflow/`
+directory becomes a single Dflow namespace separate from any
+unrelated `specs/` directory another tool may own (PROPOSAL-014).
+
+If your project has top-level `specs/` containing Dflow content:
+
+```bash
+mkdir -p dflow
+git mv specs dflow/specs
+git status
+```
+
+Commit the rename in a single commit. Avoid mixing the rename with
+content edits in the same commit so reviewers can read the diff
+cleanly.
+
+If you also have an unrelated `specs/` directory used by another
+tool, move only the Dflow material into `dflow/specs/`. The CLI will
+warn when it sees a non-Dflow `specs/` directory but will not modify
+it.
+
+### 2. Rename `_共用/` to `shared/`
+
+V1 uses canonical English directory names (PROPOSAL-012). If your
+project has `dflow/specs/_共用/`:
+
+```bash
+git mv dflow/specs/_共用 dflow/specs/shared
+git status
+```
+
+Update any cross-references in spec files or AI instructions. A
+project-wide grep after the rename catches leftover references:
+
+```bash
+grep -rn "_共用" .
+```
+
+### 3. Translate Chinese headings to canonical English
+
+V1 templates use canonical English structure for section headings,
+field labels, anchors, and placeholders (PROPOSAL-013). Free prose
+inside those sections may stay in your team language.
+
+This is the most labor-intensive step. Recommended approach:
+
+1. Open `TEMPLATE-LANGUAGE-GLOSSARY.md` for the heading-by-heading
+   mapping.
+2. For each generated spec file, replace Chinese H2 / H3 headings,
+   table column labels, and bold inline labels with their canonical
+   English form.
+3. Leave free prose (descriptions, decision rationale, task text) in
+   the team language. The Prose Language convention recorded in
+   `dflow/specs/shared/_conventions.md` applies here — see also
+   step 6 below.
+
+An AI assistant can walk through each spec file heading-by-heading
+faster than a global search-and-replace, because earlier Dflow
+adoption may have used slightly different wording per team. After
+translation, run a project-wide search for the most common Chinese
+headings to catch missed files. Adjust the search list to match the
+templates your team actually used:
+
+```bash
+grep -rn "## 業務規則\|## 行為情境\|## 領域模型" dflow/specs/
+```
+
+### 4. Switch the init entry point
+
+Pre-V1 documentation may have instructed teammates to start a Dflow
+project by running `/dflow:init-project` from inside an AI agent. V1
+removed that runtime slash command (PROPOSAL-014). The init flow now
+runs as a shell command. Install Dflow globally and run:
+
+```bash
+npm install -g dflow-sdd-ddd
+dflow init
+```
+
+If you cannot or do not want to install globally, use the no-install path:
+
+```bash
+npx dflow-sdd-ddd init
+```
+
+If you already have an initialized project, you do not need to re-run
+`init`. The other `/dflow:*` workflow commands (`/dflow:new-feature`,
+`/dflow:modify-existing`, `/dflow:bug-fix`, `/dflow:new-phase`,
+`/dflow:finish-feature`, `/dflow:verify`, `/dflow:pr-review`) are
+unchanged and continue to work.
+
+Update any team documentation, runbooks, or onboarding notes that
+still reference `/dflow:init-project` so new project setups use the
+shell command instead.
+
+### 5. Adopt multi-AI thin shims
+
+V1 separates the canonical project guide from each per-tool
+instruction file (PROPOSAL-020). The canonical guide lives at
+`dflow/specs/shared/AI-AGENT-GUIDE.md`. Per-tool files (`AGENTS.md`,
+`CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`) are thin
+shims pointing at the canonical guide.
+
+If your project's `CLAUDE.md` (or equivalent) was generated by an
+early Dflow form that wrote a full file rather than a thin shim:
+
+```bash
+dflow configure-agents
+```
+
+This command adds shims for any AI tools you select. `dflow configure-agents`
+does not overwrite an existing `CLAUDE.md`; instead, it writes a
+`dflow/specs/shared/<tool>-md-snippet.md` that you can merge into the
+existing file at your own pace.
+
+If you prefer a fully clean V1 layout, archive the existing root
+instruction file under another name first, then run
+`dflow configure-agents` so it can write the new shim from scratch.
+
+## After Migration
+
+Verify the migrated project:
+
+- Ask the AI agent to run `/dflow:status` and confirm it can locate
+  Dflow flow material and report the project's current state.
+- Open `dflow/specs/shared/_conventions.md` and confirm a `## Prose
+  Language` section exists. If your project predates the
+  prose-language convention (PROPOSAL-015), add the section manually
+  with the correct BCP-47 language tag, for example `zh-TW` or `en`.
+- Run a final grep to confirm no legacy paths or terms remain inside
+  `dflow/specs/`. Adjust the term list to match your earlier Dflow
+  adoption:
+
+```bash
+grep -rn "_共用\|/dflow:init-project" dflow/specs/
+```
+
+## Out of Scope
+
+This guide stays manual on purpose. The items below are not part of
+V1 and may or may not arrive in a later release; do not rely on them
+when planning a migration today.
+
+- Automatic migration of legacy paths or headings.
+- A `dflow doctor` health check command.
+- A `dflow migrate` subcommand that edits files.
+- Automated translation of free prose between languages.
+
+If any of these would help your team, open a docs feedback issue so
+the request is recorded. The maintainer position is not to refuse
+them, only to keep V1 a clean cut.
+
+## Where To Go Next
+
+- `docs/evaluating-dflow.en.md` for what a fresh V1 `init` produces, in
+  case you want to compare against your migrated project.
+- Per-tool walkthroughs under `docs/` for the AI tool you use:
+  - `docs/using-with-claude-code.en.md`
+  - `docs/using-with-codex.en.md`
+- `TEMPLATE-COVERAGE.md` for the V1 logical / generated file parity
+  between Greenfield and Brownfield tracks.
+
+If something in this guide does not match your project's actual
+pre-V1 state, open a docs feedback issue. The guide can be extended
+as new edge cases come in.