dflow-sdd-ddd 0.2.0 → 0.4.0

package/README.md

@@ -1,64 +1,73 @@
 # Dflow
 
-Dflow is a spec-first workflow kit for AI-assisted software development. It gives your AI coding agent a concrete process for turning change requests into structured specs, domain language, implementation plans, drift checks, and reviewable code instead of jumping straight from prompt to code.
+**繁體中文** | [English](README.en.md)
 
-AI makes delivery faster, but it also makes ambiguous domain knowledge more dangerous. Dflow uses DDD ideas such as ubiquitous language, bounded contexts, domain rules, and model ownership as the semantic backbone of SDD, so the AI has constraints before it generates code. The goal is not ceremony for its own sake; the goal is repeatable software change with clearer meaning, fewer scattered rules, and less prompt-dependent behavior.
+> **AI 協作沒 DDD = 加速混亂；有 DDD = 把 AI 事先約束在領域模型內。**
+> Rich Domain Model（業務規則寫在領域物件本身、而非散在 service 或 prompt 裡）把不變條件、業務規則、Aggregate 邊界編碼進物件 — AI 寫的程式碼必須穿過這個契約。Dflow 把 DDD 當成 SDD 的語意骨幹。
 
-## Key Features
+Dflow 是一套 spec-first 的工作流程工具集，專為 AI 輔助軟體開發設計。它為你的 AI 程式設計助理提供具體流程，把變更需求轉成結構化規格、領域語言、實作計畫、漂移檢查、與可審查的程式碼，而不是從 prompt 直接跳到程式碼。
 
-| Feature | What it gives engineering teams |
+目標不是流程本身，而是讓軟體變更可重複、語意更清楚、規則更不散落、行為更不依賴 prompt。
+
+## 主要特點
+
+| 特點 | 對工程團隊的幫助 |
 |---|---|
-| **Spec-first development** | Every meaningful change starts from an explicit spec, acceptance behavior, and implementation plan before code changes begin. |
-| **Greenfield and Brownfield tracks** | Start clean in a new project, or introduce Dflow into an existing codebase through progressive domain extraction and safer incremental change. |
-| **Hybrid workflow control** | Command-first entry points for intentional work, auto-trigger checks as a safety net, and transparent phase gates so developers stay in control. |
-| **DDD semantic backbone** | Captures domain language, context boundaries, business rules, and model decisions so AI output is constrained by project meaning. |
-| **Three-layer documentation model** | Keeps short-lived phase deltas, feature snapshots, and system-level state separate, so specs stay useful instead of becoming one large document dump. |
-| **Drift verification** | Checks whether specs, domain documents, implementation, tests, and technical debt records still describe the same system. |
+| **Spec-first 開發** | 把對齊推到實作之前，避免 AI 從模糊 prompt 直接生程式碼後才發現方向錯、回頭重做。 |
+| **Greenfield 與 Brownfield 雙軌** | 不只服務新專案；既有 codebase 不必先做大規模重構，可邊改邊把散落各處的領域規則抽出來。 |
+| **混合式工作流程控制** | 不是 autopilot 也不是純手動 — 明確命令進入、AI 在你忘記啟動時建議切入、重要決策點停下確認。三層共存讓 AI 不會一路跑偏，也不會把每一步都變成繁瑣流程。 |
+| **DDD 語意骨幹** | AI 最容易憑直覺發明業務規則（折扣何時有效、帳號權限邊界），這種錯誤 review 時人眼很難察覺。先把領域語言、邊界、業務規則寫下來，AI 補細節時受專案約束、而不是憑感覺。 |
+| **三層文件模型** | 對應 feature branch 的實際節奏：phase（單次提案-實作循環）/ feature（整條 branch 的累積狀態與接續指引）/ system（跨 feature 的長期知識）。許多 spec 工具只有 phase + system 兩層，多次迭代的 feature branch 跨多個 phase 時就會失真。下方有完整說明。 |
+| **依改動深淺的 Tier 制（T1/T2/T3）** | AI 依改動深淺自動決定規格與驗證量級：改顏色 / typo 只需 `_index.md` 一行；bug fix 用 lightweight spec + 聚焦驗證；新 feature 或動到 bounded context 才走完整 phase-spec + 分層實作計畫 / 驗證。小修改不會被流程拖累。 |
+| **漂移驗證** | `/dflow:verify` 把規格、領域文件、實作、測試、技術債紀錄做交叉比對，找出 PR review 人眼看不出來的「文件還在描述舊行為」漂移。 |
+| **多 AI 工具共用一份規則** | Canonical 專案指南 + 各工具薄 shim（`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / Copilot instructions），團隊在 Claude / Codex / Gemini / Copilot 之間切換時不必維護多份 workflow 規則。 |
 
-## Get Started
+## 開始使用
 
-Prerequisite: a local Node.js / npm environment that can run `npx`.
+前置需求：已安裝 Node.js / npm，且全域 npm bin 目錄已加入 `PATH`。
 
-Run Dflow from the root of the project you want to adopt it in:
+於要採用 Dflow 的專案根目錄執行：
 
 ```bash
-npx dflow-sdd-ddd init
+npm install -g dflow-sdd-ddd
+dflow init
 ```
 
-The init flow asks whether the project is greenfield or brownfield, then
-previews the files it will create. Existing files are not overwritten. Init
-creates workflow documentation and AI instruction files; it does not inspect,
-refactor, or migrate your application code.
+init 流程會詢問是 greenfield 或 brownfield，接著預覽即將建立的檔案。既有檔案不會被覆寫。Init 只建立 workflow 文件與 AI 指示檔，**不會**檢查、重構、或遷移你的應用程式碼。
 
-For a fixed global CLI:
+若專案已初始化、之後又要加入另一個 AI 程式設計工具，執行：
 
 ```bash
-npm install -g dflow-sdd-ddd
-dflow init
+dflow configure-agents
 ```
 
-If the project is already initialized and you later add another AI coding
-tool, run:
+此指令只設定 AI 指示檔，不會重跑專案初始化，也不會動到既有 specs。
+
+### 替代路徑：不安裝直接試用
+
+若無法或不想全域安裝（沒有管理員權限、暫時性環境、或只想試一次），Dflow 每個 CLI 指令都可透過 `npx` 執行：
 
 ```bash
-dflow configure-agents
+npx dflow-sdd-ddd init
+npx dflow-sdd-ddd doctor
+npx dflow-sdd-ddd configure-agents
 ```
 
-This command only configures AI instruction files. It does not rerun project
-initialization or touch existing specs.
+走這條路徑時，同一個 session 內所有指令都要用完整的 `npx dflow-sdd-ddd <subcommand>` 形式；裸 `dflow` 別名只有全域安裝後才能用。
+
+### 檢查 legacy artifacts（選用）
 
-To check whether the project still has legacy or pre-V1 artifacts (such as
-a top-level `specs/` directory or a `_共用/` directory left over from older
-Dflow forms), run:
+要檢查專案內是否仍有 legacy 或 pre-V1 artifacts（如根目錄的 `specs/` 或舊版的 `_共用/`），執行：
 
 ```bash
 dflow doctor
 ```
 
-`doctor` is a read-only health check. It never modifies files; it only
-reports findings and points at the migration guide.
+`doctor` 是唯讀健康檢查；不會修改任何檔案，只報告找到的問題並指向 migration guide。剛 init 的新專案不會有 legacy artifacts、可跳過此步驟。
+
+### 開始使用 Dflow workflow
 
-After init, start work through the Dflow workflow in your AI coding agent:
+完成 init 之後，透過 AI 程式設計助理走 Dflow workflow：
 
 ```text
 /dflow:new-feature
@@ -70,182 +79,227 @@ After init, start work through the Dflow workflow in your AI coding agent:
 /dflow:pr-review
 ```
 
-If your tool does not support custom slash commands, use the same command names as plain instructions in chat. Dflow is Markdown-based workflow material plus a scaffolding CLI, so it can be used with AI coding agents that can read project instructions and repository context.
+若你的工具不支援自訂 slash command，把同名指令當成普通對話訊息輸入即可。Dflow 是 Markdown-based 的 workflow 材料加一個 scaffolding CLI，能與任何可讀專案指示與 repo 上下文的 AI 程式設計助理一起運作。
 
-For the first adoption pass, use a branch or disposable sample project so your
-team can inspect the generated `dflow/specs/` workspace before bringing the
-workflow into an active codebase.
+第一次採用建議用 branch 或一次性試用專案，讓團隊先檢視產生的 `dflow/specs/` 工作區，再把流程引入正式程式碼。
 
-For a guided evaluation walk-through — what `init` creates, AI tool support,
-track choice, and a 30-minute sample-project playbook — see [Evaluating
-Dflow](docs/evaluating-dflow.md). For end-to-end scenario walk-throughs of
-Greenfield and Brownfield workflows with worked spec outputs, see the
-[`tutorial/`](tutorial/README.md) index (top of file has an English reading
-guide).
+完整評估流程（init 產生哪些檔案、AI 工具支援、模式選擇、30 分鐘試用 playbook）見 [評估 Dflow](docs/evaluating-dflow.md)。Greenfield 與 Brownfield 端到端劇情走完與規格範例見 [`tutorial/`](tutorial/README.md) 索引。
 
-## Project Tracks
+## 專案模式
 
-| Track | Use it when | Main outcome |
+| 模式 | 何時用 | 主要產出 |
 |---|---|---|
-| **Greenfield** | You are starting a new system or a new bounded area with room to shape architecture and domain model early. | Clean spec baseline, domain model ownership, feature-by-feature implementation through SDD. |
-| **Brownfield** | You are adding or changing behavior in an existing codebase where business rules may already be scattered. | Progressive domain extraction, safer change planning, and migration-ready domain knowledge. |
+| **Greenfield** | 新系統或新 bounded area，有空間早期塑形架構與領域模型 | 乾淨的規格 baseline、領域模型歸屬、feature-by-feature SDD 實作 |
+| **Brownfield** | 在既有 codebase 增加或修改行為，業務規則可能已散落各處 | 漸進的領域抽出、更安全的變更規劃、可遷移的領域知識 |
 
-These tracks describe adoption style, not framework branding. Dflow should be read as a workflow system for software teams that want AI assistance without giving up domain clarity.
+兩種模式區分的是專案起始狀態（新建 vs 既有 codebase），不是 framework 品牌；Dflow 對語言與 stack 不做假設，workflow、tier 制與文件模型可套用任何技術組合。本質是給「希望 AI 協助、又不願放棄領域清晰度」的軟體團隊使用的 workflow 系統。
 
-## Workflow Model
+各 stack（.NET / Java-Spring / Node-TS / Python / Go / PHP-Laravel）的填好範例見 [`docs/examples-by-stack.md`](./docs/examples-by-stack.md)。
 
-Dflow uses a hybrid design:
+### 模式選擇與遷移
 
-| Layer | Purpose |
+模式在 `dflow init` 時選定、之後**不能 in-place 切換**（沒有 `/dflow:switch-to-greenfield` 之類的指令）。Brownfield 設計上是 Greenfield 的前置準備：抽出到專案 domain 層（例如 `src/Domain/`）的領域程式碼，與 `dflow/specs/domain/` 內的領域文件（術語、規則、模型、事件），都是 migration-ready 資產 — 未來要 rewrite 時（建新專案 + 新 `dflow init` 選 Greenfield），可以直接搬過去。`dflow/specs/migration/tech-debt.md` 是 brownfield 專用的遷移債紀錄。
+
+也支援「逐 BC（Bounded Context）遷移」— 某個 BC 的業務邏輯已純化到 domain 層、表現層只剩 UI 綁定後，這個 BC 就已是 Clean Architecture 狀態，不必整個 system 一次性切。Brownfield 的 `/dflow:modify-existing` 內「評估表現層業務邏輯」步驟對該 BC 自然會變 no-op。
+
+## Workflow 模型
+
+Dflow 採用混合設計，user 跟 AI 互動有三個層面：
+
+| 層 | 用途 |
 |---|---|
-| **Command-first entry** | Developers intentionally start work with commands such as `/dflow:new-feature` or `/dflow:modify-existing`. |
-| **Auto-trigger safety net** | When the conversation clearly implies a feature, phase, bug fix, verification, or review, the AI should suggest the matching Dflow flow. |
-| **Transparency gates** | The AI announces flow entry, phase transitions, and important internal steps so the developer can approve direction before work expands. |
+| **命令進入** | 開發者主動以 `/dflow:new-feature`、`/dflow:modify-existing` 等命令開始工作。 |
+| **自動偵測安全網** | 當對話明顯指向某個 feature、phase、bug fix、verification、review 時，AI 應主動建議對應的 Dflow flow。 |
+| **透明的決策檢查點** | AI 在工作的關鍵節點（flow 進入、Step Gate、重要內部步驟）會停下來告知並等開發者確認方向，避免一路自動跑下去。 |
 
-Dflow also scales ceremony by change risk:
+### Workflow 內部結構
 
-| Tier | Typical use | Expected weight |
-|---|---|---|
-| **T1 Lightweight** | Small bug fixes or narrow edits. | Minimal spec, focused verification. |
-| **T2 Standard** | Normal feature work. | Feature spec, behavior examples, implementation plan, finish checks. |
-| **T3 Full** | Cross-cutting changes, new bounded contexts, risky architecture work. | Full domain modeling, phase planning, broader drift verification, stronger review gates. |
+每次 user 下一個 `/dflow:xxx` 指令，就是啟動一個 **Workflow run**。Workflow 內部由編號的 **Step** 組成（例如 `/dflow:new-feature` 共 8 個 Step），Step 之間有兩種邊界：
+
+- **Step Gate** — AI 必須停下宣告即將進入下一個 Step、等 user 確認方向。確認方式：`/dflow:next` 指令、或自然語言「OK / 繼續」、或直接提供下一個 Step 需要的資料（implicit confirmation）
+- **Step-internal transition** — AI 只宣告「Step N 完成，進入 Step N+1」、不等待
 
-The transparency gates and T1/T2/T3 tiers are related but separate: transparency controls how the AI communicates the workflow; tiers control how much specification and verification the change needs.
+Step Gate 不是每個 Step 之間都有。以 `/dflow:new-feature` 為例，8 個 Step 中只有 4 個 Step Gate，其他 Step 之間直接推進。
 
-## Documentation Model
+### 依改動深淺調整規格、實作計畫與驗證（Tier 制）
 
-Dflow separates documents by lifecycle:
+Dflow 依改動深淺自動決定規格、實作計畫與驗證的量級（T1 / T2 / T3 三層）：
 
-| Layer | Shape | Purpose |
+| Tier | 典型用途 | 預期份量 |
 |---|---|---|
-| **Phase Delta** | Short-lived phase spec. | Captures what this phase changes, why, and how it will be verified. |
-| **Feature Snapshot** | Feature-level summary and behavior. | Preserves the accepted behavior and implementation decisions after phases complete. |
-| **System State** | Shared domain and architecture documents. | Maintains durable knowledge such as glossary, context map, rules, models, conventions, and technical debt. |
+| **T1 Heavy** | 新 feature、新 phase、新 Aggregate / Bounded Context、架構變更、新業務規則 | 完整 phase-spec、領域建模、行為例子、實作計畫、驗證與收尾檢查 |
+| **T2 Light** | Bug fix（邏輯錯誤）、UI 驗證調整、有 BR（business rule）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。
+
+**不是每個變更都走 Dflow**：純 typo、純 formatting commit（例如 `prettier` / `dotnet format` 自動跑）連 T3 inline 紀錄都不需要，直接 `git commit` 即可。Dflow 是給有業務語意或結構變動的修改用的。
+
+透明的決策檢查點與 Tier 制有關但獨立：檢查點控制 AI 如何溝通 workflow；Tier 控制變更需要多少規格、實作計畫與驗證。
+
+## 文件模型
+
+實際開發中，一個 feature branch 通常會經歷多次「提案 → 實作 → 完成」循環才整個 finish — 多個 milestone、多次迭代、多筆 commit。Dflow 三層文件模型對應這個節奏：
+
+| 層 | 檔案 | 用途 | 對應的 git 概念 |
+|---|---|---|---|
+| **Phase Delta** | `phase-spec-{date}-{slug}.md`（或 lightweight spec） | 紀錄此次循環改了什麼、為什麼、怎麼實作與驗證 | feature branch 內的一次 milestone 區間 |
+| **Feature Snapshot** | `_index.md`（每個 feature 目錄內） | feature 級 dashboard：phase 列表、cumulative BR Snapshot、Resume Pointer | feature branch 自己的「目前進度」 |
+| **System State** | `rules.md` / `behavior.md` / `glossary.md` / `context-map.md` | 跨 feature 的長期知識：術語、業務規則、模型、慣例、技術債 | main / trunk 累積下來的「系統現在實際是什麼」 |
+
+`_index.md` 是關鍵的中間層。很多 spec 工具只有 phase + system 兩層，但 feature branch 跨多次 phase 是常態，少了中間層就會遇到三個痛點：
 
-This keeps AI collaboration grounded. The phase layer gives the agent immediate execution context, the feature layer records what was delivered, and the system layer becomes the long-term source of truth for future prompts and reviews.
+- 翻所有 phase-spec 才能知道「這個 feature 目前累積到哪」
+- 新對話接手時要重建 context，不知道上次做到哪
+- 歸檔顆粒度太細或太粗 — 要嘛一份份歸檔失去 feature 全貌，要嘛全部塞進 system 層失去 phase 軌跡
 
-## Files Created by Init
+Dflow 用 `_index.md` 解決這三點：Current BR Snapshot 每完成一個 phase 就 regenerate、Resume Pointer 寫接續指引、整個 feature 目錄是自然的歸檔單位。`/dflow:finish-feature` 收尾時，把 `_index.md` 的 BR Snapshot reconcile 到 `rules.md` / `behavior.md`（feature 層晉升到 system 層），然後 `git mv` 整個 feature 目錄到 `completed/`。
 
-A typical initialized project receives a `dflow/` workspace:
+## Init 產生的檔案
+
+典型初始化專案會建立 `dflow/` workspace：
 
 ```text
 dflow/
-  specs/
-    shared/
-      _overview.md
-      _conventions.md
-      Git-principles-*.md
-    domain/
-      glossary.md
-      context-map.md
-    architecture/
-      tech-debt.md
-    features/
-      active/
-      completed/
+└── specs/
+    ├── shared/
+    │   ├── _overview.md
+    │   ├── _conventions.md
+    │   └── Git-principles-*.md
+    ├── domain/
+    │   ├── glossary.md
+    │   └── context-map.md
+    ├── architecture/
+    │   └── tech-debt.md
+    └── features/
+        ├── active/
+        └── completed/
 ```
 
-Dflow also creates or provides a mergeable project instruction file for your AI coding agent. The exact file depends on the target tool and existing project setup; Dflow avoids overwriting existing project instructions.
+Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指示檔；確切檔名取決於目標工具與既有專案設定。Dflow 不覆寫既有專案指示。
 
-When you select AI agent setup during init, Dflow writes
-`dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical project guide, then
-creates small tool-specific shims that point back to it:
+選擇 AI agent 設定時，Dflow 把 `dflow/specs/shared/AI-AGENT-GUIDE.md` 作為 canonical 專案指南，並為每個 AI 工具建立**小型的指向檔**（俗稱 shim，內容很短，只是把該工具引導去讀 canonical 指南）：
 
-| Tool target | Generated file |
+| 目標工具 | 產生檔案 |
 |---|---|
 | Codex / Copilot coding agent | `AGENTS.md` |
 | Claude Code | `CLAUDE.md` |
 | Gemini CLI | `GEMINI.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
-If one of those files already exists, Dflow leaves it unchanged and writes a
-merge snippet under `dflow/specs/shared/` instead. The project guide stays the
-single source of truth, so teams can use multiple AI tools without maintaining
-multiple copies of the workflow rules.
+若這些檔案已存在，Dflow 不會覆蓋，改寫 merge snippet 到 `dflow/specs/shared/`。專案指南保持單一 source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow 規則。
+
+之後團隊採用新 AI 程式設計助理時，可隨時跑 `dflow configure-agents` 新增 shim。
+
+特定工具的 init 寫入內容與 Dflow workflow 命令呈現方式，見 `docs/` 內的 per-tool 指南：
+
+- [在 Claude Code 中使用 Dflow](docs/using-with-claude-code.md)
+- [在 Codex CLI 中使用 Dflow](docs/using-with-codex.md)
+- [在 Gemini CLI 中使用 Dflow](docs/using-with-gemini-cli.md)
+- [在 GitHub Copilot 中使用 Dflow](docs/using-with-github-copilot.md)
+
+Init 不會把 `tutorial/` 目錄複製進你的專案。[`tutorial/`](tutorial/README.md) 目錄存放在本 source repository，作為理解 Dflow 如何在 Greenfield / Brownfield 劇情中運作的評估材料。
+
+## 主要 Flow
+
+Dflow 指令依角色分四類。「我要做的事」對應到指令的速查表附在最後。
 
-You can run `dflow configure-agents` later to add more tool shims as the team
-adopts additional AI coding agents.
+### 入口指令（從這裡開始一個 workflow）
 
-For tool-specific walk-throughs of what `init` writes and how Dflow's
-workflow commands appear in a given AI tool, see the per-tool guides under
-`docs/`:
+啟動一次 workflow run；可在沒有任何既有 feature 的狀態下使用。三者彼此獨立、不互為前置。
 
-- [Using Dflow with Claude Code](docs/using-with-claude-code.md)
-- [Using Dflow with Codex CLI](docs/using-with-codex.md)
+| Flow | 何時用 | 典型產出 |
+|---|---|---|
+| `/dflow:new-feature` | 完全新功能、新增一條系統要實現的業務規則 | feature 目錄 + `_index.md` + 第 1 份 phase-spec（一律 T1） |
+| `/dflow:modify-existing` | 改既有行為 — **不確定改動屬於哪類**時用，AI 內部會分流 | T1 → 升 new-phase / new-feature；T2 → lightweight-spec；T3 → `_index.md` inline 一行 |
+| `/dflow:bug-fix` | 可清楚陳述預期行為的 defect | AI 判 tier（多為 T2 lightweight-spec）。Orphan bug 會自建最小 feature 目錄 |
+
+### Feature 內指令（限 active feature）
 
-Guides for Gemini CLI and GitHub Copilot may follow as maintainer
-experience with each tool stabilizes.
+只在已啟動的 active feature 內可用。指向 `completed/` 的 feature 會被拒絕。
 
-Init does not copy the `tutorial/` directory into your project. The
-[`tutorial/`](tutorial/README.md) directory lives in this source repository
-as evaluation material for understanding how Dflow works on Greenfield and
-Brownfield scenarios; the tutorial index opens with an English reading guide
-for non-Chinese readers.
+| Flow | 何時用 | 典型產出 |
+|---|---|---|
+| `/dflow:new-phase` | active feature 需要再一個實作切片 | 新一份 `phase-spec-{date}-{slug}.md` + Implementation Tasks + 程式實作 / 驗證 + phase 標記完成（一律 T1） |
+| `/dflow:finish-feature` | feature 全部 phase 完成、要收尾 | `git mv` 整個 feature dir 到 `completed/`、sync BR Snapshot 到 BC 層、Integration Summary（不 auto-merge） |
 
-## Main Flows
+### 流程控制（管理進行中的 workflow run）
 
-| Flow | When to use it | Typical outputs |
+| Flow | 何時用 |
+|---|---|
+| `/dflow:status` | 看現在在哪個 workflow / Step / 進度 |
+| `/dflow:next` | 確認過 Step Gate（等同自然語言「OK」/「繼續」） |
+| `/dflow:cancel` | 放棄目前 workflow run、回到自由對話。已建立的 artifacts 保留 |
+
+### 獨立工具（任何時候可呼叫，不綁定 feature 或 workflow）
+
+| Flow | 何時用 | 典型產出 |
 |---|---|---|
-| `/dflow:new-feature` | A new user-visible capability or business behavior. | Feature spec, behavior examples, phase plan, domain updates. |
-| `/dflow:modify-existing` | A change to behavior already present in the system. | Impact analysis, updated specs, adjusted domain rules, migration notes when needed. |
-| `/dflow:bug-fix` | A defect where expected behavior can be stated narrowly. | Lightweight spec, reproduction, fix plan, regression check. |
-| `/dflow:new-phase` | A feature needs another implementation slice. | Phase delta, acceptance checks, focused implementation plan. |
-| `/dflow:finish-feature` | The implementation is done and needs closure. | Drift verification, feature snapshot, technical debt update, review checklist. |
-| `/dflow:verify` | You need confidence that docs and code still match. | Drift report across spec, domain docs, implementation, tests, and debt records. |
-| `/dflow:pr-review` | A change is ready for review. | SDD/DDD compliance review with risks, gaps, and follow-up items. |
-| `/dflow:report-dflow-feedback` | You or the AI found a Dflow issue or improvement while using the workflow. | Sanitized local feedback draft for a GitHub issue or future PR; nothing is submitted automatically. |
+| `/dflow:verify` | 需要確認文件、程式、測試、債務紀錄是否一致 | 跨規格、領域文件、實作、測試、債務的 drift report |
+| `/dflow:pr-review` | 變更已準備接受審查 | SDD/DDD 合規 review 清單，含風險、缺口、後續項目 |
+| `/dflow:report-dflow-feedback` | 你或 AI 在使用中發現 Dflow 本身的問題 | sanitized 的本地 feedback 草稿；不自動送出 |
 
-## Why DDD Matters More with AI
+### 該選哪個指令（rule of thumb）
 
-AI agents are strong at filling gaps. That is useful when the missing detail is mechanical, but risky when the missing detail is business meaning. If a prompt does not define the language, boundaries, and allowed behavior, the model may invent plausible rules that are hard to notice in review.
+| 我要做的事 | 直接下指令 |
+|---|---|
+| 完全新功能（與現有 feature 無關） | `/dflow:new-feature` |
+| 為 active feature 加規劃中的下一個 phase | `/dflow:new-phase` |
+| 修一個明確的 bug | `/dflow:bug-fix` |
+| **不確定**怎麼分類、反正是改既有的 | `/dflow:modify-existing` |
+| feature 全部 phase 都完成、要收尾 | `/dflow:finish-feature` |
+| 跑變更 review | `/dflow:pr-review` |
+| 檢查文件與程式碼 drift | `/dflow:verify` |
 
-Dflow treats DDD as the semantic structure behind the spec. Ubiquitous language keeps names consistent. Bounded contexts keep meanings from leaking across areas. Domain rules define what is correct, allowed, or forbidden before implementation starts.
+### completed feature 是凍結歷史
 
-In a code-first workflow, design often appears after the fact in classes, handlers, and tests. In an AI-assisted workflow, the spec must become the precondition for generation. The practical flow becomes:
+當 `/dflow:finish-feature` 把 feature 目錄 `git mv` 到 `completed/` 後，**該 feature 不接受任何直接寫入**，無論是新 phase-spec、lightweight-spec、還是 `_index.md` inline 一行。如果之後要再改它，必須建一個 follow-up feature：新 feature 目錄、新 SPEC-ID、`_index.md` 用 `follow-up-of: {原 SPEC-ID}` metadata 連回原 feature。
+
+理由：「completed = 凍結歷史」是 Dflow 的核心保證；若接受 post-completion 修改，feature lifecycle 就失去明確終點、`_index.md` BR Snapshot 也無法可信。`/dflow:modify-existing` 偵測到目標是 completed feature 時會主動詢問 user 三個選項：A 走 follow-up、B 改用 `/dflow:new-feature` 當獨立新需求、C（被拒絕，重新引導至 A）。
+
+## 為什麼 DDD 在 AI 時代更重要
+
+AI 助理擅長把缺少的細節補起來。如果缺少的是「靠規則或慣例就能推出來」的東西（例如命名、樣板語法），這是優點；但如果缺少的是**業務語意**（什麼樣的折扣才算有效、帳號不能做什麼），模型可能會發明一個看起來合理、實際錯誤的規則，而且這種錯誤在 review 時很難一眼察覺。
+
+Dflow 把 DDD 當成規格背後的語意結構：ubiquitous language 讓命名一致、bounded context 防止語意跨領域漏氣、領域規則在實作開始之前先定義什麼是正確、允許、禁止。
+
+在 code-first workflow 裡，設計常常在類別、handler、測試完成後才浮現。在 AI-assisted workflow 裡，規格必須成為產生程式碼的前置條件。實務流程變成：
 
 ```text
-Domain meaning -> Structured spec -> AI implementation -> Code as output
+領域意義 → 結構化規格 → AI 實作 → 程式碼即產出
 ```
 
-For a longer explanation, see [Why DDD Matters More with AI](docs/why-ddd-for-ai.md).
+更詳細的說明見 [為什麼 AI 時代 DDD 更重要](docs/why-ddd-for-ai.md)。
 
-## Repository Layout
+## Repo 結構
 
-| Path | Purpose |
+| 路徑 | 用途 |
 |---|---|
-| `bin/` | CLI entrypoint. |
-| `lib/` | Init runtime implementation. |
-| `templates/` | Files copied by the init command. |
-| `test/` | Smoke tests for generated output. |
-| `tutorial/` | Guided learning scenarios and expected outputs. |
-| `sdd-ddd-*-skill/` | Source workflow material consumed by AI coding agents. |
-
-## Contributing and Releases
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for issue and pull request guidance.
-Pull requests run an automated verification workflow on GitHub before review.
-Maintainer-facing release rules are documented in [Release and Versioning
-Policy](docs/release-versioning-policy.md), with the manual npm flow in [npm
-Publish Checklist](docs/npm-publish-checklist.md).
-
-## Status
-
-Dflow is currently published as `dflow-sdd-ddd` on npm. The latest published
-npm package is `0.2.0`, covering project initialization, workflow
-documentation, multi-AI agent setup, AI-agent-readable SDD/DDD guidance,
-public migration tooling (manual migration guide and `dflow doctor`
-read-only health check), public onboarding (evaluator guide and per-tool
-walkthroughs for Claude Code and Codex CLI), and a verification-only CI
-workflow.
-
-The GitHub source may include post-`0.2.0` repository changes before the
-next npm release is published. See [CHANGELOG.md](CHANGELOG.md) for full
-release history.
-
-If you maintain a project that adopted an early Dflow form before
-`0.1.0` was published, see [Migrating to Dflow
-V1](docs/migrating-to-dflow-v1.md) for the manual migration checklist.
-
-## License
-
-MIT License. See [LICENSE](LICENSE).
+| `bin/` | CLI 進入點 |
+| `lib/` | Init runtime 實作 |
+| `templates/` | init 指令複製的檔案 |
+| `test/` | 產出物的 smoke test |
+| `tutorial/` | 引導式學習劇情與預期產出 |
+| `sdd-ddd-*-skill/` | AI 程式設計助理消化的 workflow 來源材料 |
+
+## 貢獻與發布
+
+issue 與 pull request 指引見 [CONTRIBUTING.md](CONTRIBUTING.md)。Pull request 會在 review 前跑 GitHub 上自動 verification workflow。Maintainer-facing 的 release 規則見 [Release and Versioning Policy](docs/release-versioning-policy.md)；手動 npm flow 見 [npm Publish Checklist](docs/npm-publish-checklist.md)。
+
+## 狀態
+
+Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.2.0`，涵蓋：
+
+- 專案初始化（`dflow init`）
+- Workflow 文件（`/dflow:*` 流程）
+- 多 AI agent 設定（CLAUDE.md / AGENTS.md / GEMINI.md / Copilot instructions shim）
+- AI agent 可讀的 SDD/DDD 指引
+- 公開 migration tooling：手動 migration guide 與 `dflow doctor` 唯讀健康檢查
+- 公開 onboarding：evaluator 指南、Claude Code / Codex CLI 的 per-tool walkthrough
+- 僅驗證的 CI workflow（不執行 publish）
+
+GitHub 上的 source 可能包含 `0.2.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
+
+## 授權
+
+MIT License，見 [LICENSE](LICENSE)。