dflow-sdd-ddd 0.2.0 → 0.4.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

@@ -1,226 +1,169 @@
-# Evaluating Dflow
+# 評估 Dflow
 
-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.
+> **繁體中文** | [English](evaluating-dflow.en.md)
 
-## Who This Guide Is For
+首次評估 Dflow 是否適合專案的簡明指引。
+閱讀約需 10 分鐘；可選擇再花 30 分鐘在範例專案中實際試用。
 
-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.md) (overview) or [`tutorial/`](../tutorial/)
-(deep walk-throughs); it is a focused decision aid.
+你正在評估是否要在一個 codebase 中引入 Dflow。你可能是正在評估 AI 輔助團隊 workflow 變更的技術主管、比較各種 AI 開發 workflow 的獨立開發者，或是在更廣泛採用前受指派評估 Dflow 的團隊成員。
 
-## What Is Dflow
+本指引把最常見的評估問題彙整在一處。它不取代
+[`README.md`](../README.md)（概覽）或 [`tutorial/`](../tutorial/)
+（深度 walk-through）；它是一份聚焦的決策輔助文件。
 
-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 是什麼
 
-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.
+Dflow 是一套 AI 輔助開發的 workflow 工具集。它為 AI 程式設計助理提供具體流程，把變更需求轉成結構化規格、領域語言、與可審查的程式碼，而不是從 prompt 直接跳到程式碼。
 
-## What `init` Creates and Does Not Do
+Dflow 是 Markdown-based 的 workflow 材料加上一個 scaffolding CLI。它不需要任何 runtime、server 或 framework。`init` 跑完之後，Dflow 完全存在於你的專案的 `dflow/specs/` 目錄與 AI 指示檔中。
 
-`npx dflow-sdd-ddd init` creates:
+## `init` 產生什麼、不做什麼
 
-- A `dflow/specs/` workspace (overview, conventions, domain glossary, context
-  map, architecture/tech-debt, features active/completed). See
-  [`README.md` "Files Created by Init"](../README.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.
+`dflow init`（或免安裝路徑的 `npx dflow-sdd-ddd init`）會建立：
 
-`init` does **not**:
+- `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。
 
-- 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.
+`init` **不會**：
 
-## How Dflow Works With Different AI Tools
+- 檢查、重構、或遷移你的應用程式碼。
+- 覆寫既有的 AI 指示檔；若檔案已存在，Dflow 改在 `dflow/specs/shared/` 下寫入 merge snippet。
+- 修改你的建構系統、套件管理工具、或相依套件。
+- 傳送任何資料到外部；它是本機的 scaffolding 指令。
 
-Dflow targets multiple AI coding agents. After running `init`, you select one
-or more tools and Dflow writes the corresponding shim:
+## Dflow 如何與不同 AI 工具協作
 
-| Tool | Generated file |
+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` |
 
-Each shim points back to the canonical
-`dflow/specs/shared/AI-AGENT-GUIDE.md`. Practical implications:
+每個 shim 都指向 canonical 的 `dflow/specs/shared/AI-AGENT-GUIDE.md`。實際意義：
 
-- 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
-  `dflow configure-agents` to add another shim.
-- The project guide stays the single source of truth for Dflow workflow
-  behavior.
+- 同一個專案可以同時啟用多個工具，而不會有 workflow 規則分歧。
+- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim。
+- 專案指南始終保持為 Dflow workflow 行為的單一 source of truth。
 
-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.
+若你的工具不支援自訂 slash command，把同名指令（例如 `/dflow:new-feature`）當成普通對話訊息輸入即可。Dflow 是 Markdown-based 的 workflow 材料，能與任何可讀專案指示與 repo 上下文的 AI 助理一起運作。
 
-For a tool-specific walk-through of what `init` writes and how the slash
-commands appear in conversation, see the per-tool guides:
+關於特定工具的 `init` 寫入內容與 slash command 在對話中的呈現方式，見各工具指南：
 
-- [Using Dflow with Claude Code](using-with-claude-code.md)
-- [Using Dflow with Codex CLI](using-with-codex.md)
-- (Guides for Gemini and GitHub Copilot may follow as maintainer experience
-  with each tool stabilizes.)
+- [在 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 or Brownfield: Choosing a Track
+## Greenfield 或 Brownfield：選擇 Track
 
-Pick **Greenfield** if:
+選 **Greenfield** 若：
 
-- 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.
+- 你正在啟動一個新系統或新的 bounded module。
+- 你有空間在 legacy 限制累積前先塑形架構。
+- 你想從 feature 1 就建立明確的領域模型。
 
-Pick **Brownfield** if:
+選 **Brownfield** 若：
 
-- 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.
+- 你正在擴充或修改一個既有的 codebase。
+- 業務規則散落在 handler、stored procedure、UI 程式碼或腳本中。
+- 你想漸進引入規格與領域抽出，而不必先做全面重構。
 
-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.
+- 在既有 app 內加入新 module：通常選 Greenfield，scope 限定在新的 bounded context。
+- 既有 app 具有乾淨架構且持續開發中：兩種 track 都可行；業務規則尚未文件化時 Brownfield 較安全。
 
-## A 30-Minute Evaluation Playbook
+## 30 分鐘評估 Playbook
 
-This walk-through lets you see what Dflow does without committing it to a
-real codebase.
+這份 walk-through 讓你在不動到真實 codebase 的情況下看清楚 Dflow 的實際效果。
 
-1. **Create a sample project** (Greenfield):
+1. **建立範例專案**（Greenfield）：
 
    ```bash
    mkdir dflow-sample && cd dflow-sample
    git init
    ```
 
-2. **Run init**:
+2. **安裝並執行 init**：
 
    ```bash
-   npx dflow-sdd-ddd init
+   npm install -g dflow-sdd-ddd
+   dflow init
    ```
 
-   When prompted, choose Greenfield. Pick one AI tool to generate the shim
-   for.
+   若不想全域安裝，改用 `npx dflow-sdd-ddd init`。提示時選擇 Greenfield，並選取一個 AI 工具產生 shim。
 
-3. **Inspect what was created**:
+3. **檢視產生的內容**：
 
    ```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.
+   開啟 `dflow/specs/shared/_overview.md`、`dflow/specs/shared/_conventions.md`、以及 `dflow/specs/shared/AI-AGENT-GUIDE.md` 看看整體架構。
 
-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/00-setup.md)
-   - Brownfield: [`tutorial/02-brownfield/`](../tutorial/02-brownfield/00-setup.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. **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/`.
+5. **選用：試跑一個 workflow 指令**。在你的 AI 工具中開啟範例專案，叫它執行 `/dflow:new-feature`（或在對話中貼上同等指令）。檢查它寫入 `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.
+6. **決定並清理**。若 Dflow 不適合，直接刪除範例目錄。沒有全域狀態需要清除；除了一次性的 `npx` 快取，什麼也沒有安裝。
 
-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.
+若你偏好不執行任何指令、只做深度閱讀，tutorial walk-through 也涵蓋同樣的 flow，並附有可供對比的預期產出。
 
-## What If You Stop Using Dflow
+## 若你停用 Dflow
 
-Dflow is designed for low cost to try and low cost to leave:
+Dflow 的設計讓試用成本低、退出成本也低：
 
-- 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.
+- `init` 完成後，你的專案不依賴已安裝的 `dflow-sdd-ddd` CLI。
+- 產生的檔案都是純 Markdown；用 `rm -rf dflow/` 加上刪除你不再需要的 AI 指示 shim 檔案，即可從專案中移除 Dflow。
+- 既有的專案指示檔（例如原本就存在的 `CLAUDE.md`）不會被 Dflow 修改，因此復原很直接。
 
-This means an evaluation pass leaves no permanent footprint if you decide
-not to adopt.
+這表示評估一輪後，若你決定不採用，不會留下任何永久痕跡。
 
-## Cost Per Feature: A Rough Estimate
+## 每個 Feature 的成本：概略估算
 
-Dflow scales ceremony to change risk through three tiers (see
-[`README.md` "Workflow Model"](../README.md#workflow-model) for full
-detail):
+Dflow 依改動深淺將流程份量調整為三個 tier（完整說明見
+[`README.md` "Workflow 模型"](../README.md#workflow-模型)）：
 
-- **T1 Lightweight** — small bug fixes, narrow edits. Roughly the same
-  speed as ad-hoc AI coding, with a short spec and verification on top.
-- **T2 Standard** — normal feature work. Adds a feature spec, behavior
-  examples, and finish checks. Expect modest upfront overhead in exchange
-  for a reusable spec, fewer review cycles, and lower drift risk.
-- **T3 Full** — cross-cutting changes, new bounded contexts, risky
-  architecture work. Adds full domain modeling and broader verification.
-  The cost is real but proportional to the risk being managed.
+- **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 choice is intentional, not automatic. You are not forced into T3
-ceremony for a one-line fix.
+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 是給有業務語意或結構影響的變更使用的。
 
-## 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`.
+Dflow 模板使用**英文 canonical 結構**（標題、欄位標籤），讓 AI 助理能可靠地在不同專案間定位各段落。你在模板內容中自由撰寫的文字可以使用任何團隊語言 — 英文、繁體中文、簡體中文或其他。init 流程會詢問專案的文章語言，並存入 `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.
+- AI 工具在不同專案間看到一致的英文結構。
+- 人員以團隊選定的語言讀寫規格。
+- 不需要翻譯模板或維護平行的在地化副本。
 
-## Where to Go Next
+## 下一步
 
-If you decided Dflow fits:
+若你決定 Dflow 適合：
 
-- 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.
+- 在你的真實專案執行 `init`（建議先用 branch）。
+- 閱讀 [`tutorial/`](../tutorial/) 取得端到端 walk-through 與預期產出。
+- 開 issue 或 pull request 前，先看 [`CONTRIBUTING.md`](../CONTRIBUTING.md)。
 
-If you are still deciding:
+若你還在評估中：
 
-- Read [`docs/why-ddd-for-ai.md`](why-ddd-for-ai.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.
+- 閱讀 [為什麼 AI 時代 DDD 更重要](why-ddd-for-ai.md)，了解 spec-first 加上 DDD 背後的設計理由。
+- 把 tutorial 劇情逐步與它的 `outputs/` 目錄對比，看看 Dflow 規格在接近正式的狀態下是什麼樣子。
 
-If Dflow does not fit your project today:
+若 Dflow 目前不適合你的專案：
 
-- 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.
+- structured-spec 的概念是可移植的；你可以採用其中一部分而不需要 CLI。
+- 若某個具體缺口阻礙了你，開一個 docs feedback issue（見 [`CONTRIBUTING.md`](../CONTRIBUTING.md)）。這類回饋對未來的評估者很有幫助。