dflow-sdd-ddd 0.1.1 → 0.3.0

package/README.md

@@ -1,48 +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 |
-|---|---|
-| **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. |
+目標不是流程本身，而是讓軟體變更可重複、語意更清楚、規則更不散落、行為更不依賴 prompt。
 
-## Get Started
+## 主要特點
 
-Run Dflow from the root of the project you want to adopt it in:
+| 特點 | 對工程團隊的幫助 |
+|---|---|
+| **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 規則。 |
 
-```bash
-npx dflow-sdd-ddd init
-```
+## 開始使用
 
-The init flow asks whether the project is greenfield or brownfield, then previews the files it will create. Existing files are not overwritten.
+前置需求：已安裝 Node.js / npm，且全域 npm bin 目錄已加入 `PATH`。
 
-For a fixed global CLI:
+於要採用 Dflow 的專案根目錄執行：
 
 ```bash
 npm install -g dflow-sdd-ddd
 dflow init
 ```
 
-If the project is already initialized and you later add another AI coding
-tool, run:
+init 流程會詢問是 greenfield 或 brownfield，接著預覽即將建立的檔案。既有檔案不會被覆寫。Init 只建立 workflow 文件與 AI 指示檔，**不會**檢查、重構、或遷移你的應用程式碼。
+
+若專案已初始化、之後又要加入另一個 AI 程式設計工具，執行：
 
 ```bash
 dflow configure-agents
 ```
 
-This command only configures AI instruction files. It does not rerun project
-initialization or touch existing specs.
+此指令只設定 AI 指示檔，不會重跑專案初始化，也不會動到既有 specs。
+
+### 替代路徑：不安裝直接試用
+
+若無法或不想全域安裝（沒有管理員權限、暫時性環境、或只想試一次），Dflow 每個 CLI 指令都可透過 `npx` 執行：
+
+```bash
+npx dflow-sdd-ddd init
+npx dflow-sdd-ddd doctor
+npx dflow-sdd-ddd configure-agents
+```
+
+走這條路徑時，同一個 session 內所有指令都要用完整的 `npx dflow-sdd-ddd <subcommand>` 形式；裸 `dflow` 別名只有全域安裝後才能用。
+
+### 檢查 legacy artifacts（選用）
 
-After init, start work through the Dflow workflow in your AI coding agent:
+要檢查專案內是否仍有 legacy 或 pre-V1 artifacts（如根目錄的 `specs/` 或舊版的 `_共用/`），執行：
+
+```bash
+dflow doctor
+```
+
+`doctor` 是唯讀健康檢查；不會修改任何檔案，只報告找到的問題並指向 migration guide。剛 init 的新專案不會有 legacy artifacts、可跳過此步驟。
+
+### 開始使用 Dflow workflow
+
+完成 init 之後，透過 AI 程式設計助理走 Dflow workflow：
 
 ```text
 /dflow:new-feature
@@ -54,132 +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 程式設計助理一起運作。
 
-## Project Tracks
+第一次採用建議用 branch 或一次性試用專案，讓團隊先檢視產生的 `dflow/specs/` 工作區，再把流程引入正式程式碼。
 
-| Track | Use it when | Main outcome |
+完整評估流程（init 產生哪些檔案、AI 工具支援、track 選擇、30 分鐘試用 playbook）見 [評估 Dflow](docs/evaluating-dflow.md)。Greenfield 與 Brownfield 端到端劇情走完與規格範例見 [`tutorial/`](tutorial/README.md) 索引。
+
+## 專案 Track
+
+| Track | 何時用 | 主要產出 |
 |---|---|---|
-| **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 增加或修改行為，業務規則可能已散落各處 | 漸進的領域抽出、更安全的變更規劃、可遷移的領域知識 |
+
+兩條 track 描述的是採用風格，不是 framework 品牌。Dflow 本質是給「希望 AI 協助、又不願放棄領域清晰度」的軟體團隊使用的 workflow 系統。
+
+### Track 選擇與遷移
 
-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.
+> 以下「rewrite 到 ASP.NET Core」是目前 Dflow 模板的預設遷移路徑（出於主要使用者背景），但設計本身與語言 / framework 無關 — workflow、ceremony tier、文件模型都可套用其他 stack。
 
-## Workflow Model
+Track 在 `dflow init` 時選定、之後**不能 in-place 切換**（沒有 `/dflow:switch-to-greenfield` 之類的指令）。Brownfield 設計上是 Greenfield 的前置準備：抽出到 `src/Domain/` 的純 C# 程式碼與 `dflow/specs/domain/` 內的領域文件（術語、規則、模型、事件）都是 migration-ready 資產，未來 rewrite 時（建新 ASP.NET Core 專案 + 新 `dflow init` 選 Greenfield）可以直接搬過去。`dflow/specs/migration/tech-debt.md` 是 brownfield 專用的遷移債紀錄。
 
-Dflow uses a hybrid design:
+也支援「逐 BC（Bounded Context）遷移」— 某個 BC 已純化到 `src/Domain/`、Code-Behind 已純為 UI 綁定後，這個 BC 就已是 Clean Architecture 狀態，不必整個 system 一次性切。brownfield 的 `/dflow:modify-existing` 內「assess Code-Behind」步驟對該 BC 自然會變 no-op。
 
-| Layer | Purpose |
+## 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 控制變更需要多少規格、實作計畫與驗證。
 
-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.
+## 文件模型
 
-## Files Created by Init
+實際開發中，一個 feature branch 通常會經歷多次「提案 → 實作 → 完成」循環才整個 finish — 多個 milestone、多次迭代、多筆 commit。Dflow 三層文件模型對應這個節奏：
 
-A typical initialized project receives a `dflow/` workspace:
+| 層 | 檔案 | 用途 | 對應的 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 是常態，少了中間層就會遇到三個痛點：
+
+- 翻所有 phase-spec 才能知道「這個 feature 目前累積到哪」
+- 新對話接手時要重建 context，不知道上次做到哪
+- 歸檔顆粒度太細或太粗 — 要嘛一份份歸檔失去 feature 全貌，要嘛全部塞進 system 層失去 phase 軌跡
+
+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/`。
+
+## 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)
 
-You can run `dflow configure-agents` later to add more tool shims as the team
-adopts additional AI coding agents.
+Init 不會把 `tutorial/` 目錄複製進你的專案。[`tutorial/`](tutorial/README.md) 目錄存放在本 source repository，作為理解 Dflow 如何在 Greenfield / Brownfield 劇情中運作的評估材料。
 
-## Main Flows
+## 主要 Flow
 
-| Flow | When to use it | Typical outputs |
+Dflow 指令依角色分四類。「我要做的事」對應到指令的速查表附在最後。
+
+### 入口指令（從這裡開始一個 workflow）
+
+啟動一次 workflow run；可在沒有任何既有 feature 的狀態下使用。三者彼此獨立、不互為前置。
+
+| 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: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）
 
-## Why DDD Matters More with AI
+只在已啟動的 active feature 內可用。指向 `completed/` 的 feature 會被拒絕。
 
-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.
+| 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） |
+
+### 流程控制（管理進行中的 workflow run）
 
-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.
+| Flow | 何時用 |
+|---|---|
+| `/dflow:status` | 看現在在哪個 workflow / Step / 進度 |
+| `/dflow:next` | 確認過 Step Gate（等同自然語言「OK」/「繼續」） |
+| `/dflow:cancel` | 放棄目前 workflow run、回到自由對話。已建立的 artifacts 保留 |
 
-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:
+### 獨立工具（任何時候可呼叫，不綁定 feature 或 workflow）
+
+| Flow | 何時用 | 典型產出 |
+|---|---|---|
+| `/dflow:verify` | 需要確認文件、程式、測試、債務紀錄是否一致 | 跨規格、領域文件、實作、測試、債務的 drift report |
+| `/dflow:pr-review` | 變更已準備接受審查 | SDD/DDD 合規 review 清單，含風險、缺口、後續項目 |
+| `/dflow:report-dflow-feedback` | 你或 AI 在使用中發現 Dflow 本身的問題 | sanitized 的本地 feedback 草稿；不自動送出 |
+
+### 該選哪個指令（rule of thumb）
+
+| 我要做的事 | 直接下指令 |
+|---|---|
+| 完全新功能（與現有 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` |
+
+### completed feature 是凍結歷史
+
+當 `/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. |
+| `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`，涵蓋：
 
-## Status
+- 專案初始化（`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）
 
-Dflow is currently published as `dflow-sdd-ddd` on npm. Version `0.1.0` focuses on project initialization, workflow documentation, and AI-agent-readable SDD/DDD guidance. Additional packaging for specific AI tools can be layered on top without changing the core workflow model.
+GitHub 上的 source 可能包含 `0.2.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
 
-## License
+## 授權
 
-MIT License. See [LICENSE](LICENSE).
+MIT License，見 [LICENSE](LICENSE)。

package/TEMPLATE-COVERAGE.md

@@ -0,0 +1,46 @@
+<!-- Maintenance contract for Dflow. See archive/proposals/PROPOSAL-013-system-document-template-coverage.md §4 for origin. -->
+
+# Template Coverage Matrix
+
+This file is a maintenance contract for Dflow, not the runtime brain. `SKILL.md` should point to this matrix for review and maintenance work instead of duplicating the full table.
+
+The matrix lists Brownfield / Greenfield logical template parity so reviewers can check which templates should remain aligned and which differences are intentional.
+
+## Matrix
+
+| Logical document | Generated / maintained path | Brownfield template | Greenfield template | Parity requirement | Allowed differences | Section anchors |
+|---|---|---|---|---|---|---|
+| Feature dashboard | `dflow/specs/features/{active\|completed}/{SPEC-ID}-{slug}/_index.md` | `templates/_index.md` | `templates/_index.md` | Required sections same | Greenfield may mention Aggregate / Domain Events | `current-br-snapshot`, `lightweight-changes` |
+| Phase spec | `dflow/specs/features/active/{SPEC-ID}-{slug}/phase-spec-YYYY-MM-DD-{slug}.md` | `templates/phase-spec.md` | `templates/phase-spec.md` | Lifecycle sections same | Greenfield has layer-by-layer plan + Domain Events | `implementation-tasks`, `behavior-scenarios`, `open-questions` |
+| Lightweight spec | `dflow/specs/features/active/{SPEC-ID}-{slug}/lightweight-YYYY-MM-DD-{slug}.md` or `BUG-{NUMBER}-{slug}.md` | `templates/lightweight-spec.md` | `templates/lightweight-spec.md` | T2 structure and task checklist intent same | Layer tags differ | `implementation-tasks` |
+| Glossary | `dflow/specs/domain/glossary.md` | `templates/glossary.md` | `templates/glossary.md` | Same columns | none | - |
+| Bounded Context definition | `dflow/specs/domain/{context}/context-definition.md` | `templates/context-definition.md` | `templates/context-definition.md` | Same purpose / structural sections | Greenfield may reference Aggregate / Domain Service / Repository Interface | - |
+| Rules index | `dflow/specs/domain/{context}/rules.md` | `templates/rules.md` | `templates/rules.md` | BR-ID / anchor / status format same | Greenfield may include Aggregate column | `business-rules` |
+| Models catalog | `dflow/specs/domain/{context}/models.md` | `templates/models.md` | `templates/models.md` | Same purpose | Greenfield has Aggregate / Specification depth | - |
+| Aggregate worksheet | `dflow/specs/domain/{context}/aggregates/{name}.md` (per Aggregate, on demand) | n/a | `templates/aggregate-design.md` | Greenfield only | Brownfield does not use the Aggregate worksheet | - |
+| Behavior snapshot | `dflow/specs/domain/{context}/behavior.md` | `templates/behavior.md` | `templates/behavior.md` | BR anchor and drift-verification structure same | Greenfield may reference Domain Events | `behavior-scenarios` |
+| Events catalog | `dflow/specs/domain/{context}/events.md` | n/a | `templates/events.md` | Greenfield only | Brownfield does not require event catalog | - |
+| Context map | `dflow/specs/domain/context-map.md` | `templates/context-map.md` optional | `templates/context-map.md` mandatory | Similar concept | Brownfield optional / emergent | - |
+| Tech debt | Brownfield: `dflow/specs/migration/tech-debt.md`; Greenfield: `dflow/specs/architecture/tech-debt.md` | `templates/tech-debt.md` | `templates/tech-debt.md` | Same backlog intent | Brownfield migration focus; Greenfield architecture focus | - |
+| ADR guide | `dflow/specs/architecture/decisions/README.md` | n/a | `scaffolding/architecture-decisions-README.md` | Greenfield only | Brownfield not applicable | - |
+| Project AI guide | `dflow/specs/shared/AI-AGENT-GUIDE.md` when at least one AI agent is selected during init | `scaffolding/AI-AGENT-GUIDE.md` | `scaffolding/AI-AGENT-GUIDE.md` | Same canonical tool-neutral workflow guide and source-of-truth pointers | Track-specific seeded values and available source-of-truth paths may differ | - |
+| AI tool shims | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, or merge snippets under `dflow/specs/shared/` | generated by CLI | generated by CLI | Thin files must point back to `dflow/specs/shared/AI-AGENT-GUIDE.md`; existing files are not overwritten | Tool-specific import hints differ | - |
+| Legacy Claude guide template | `<project root>/CLAUDE.md` | `templates/CLAUDE.md` | `templates/CLAUDE.md` | H2 navigation and H3 structural headings aligned (canonical English, per F-01 Path A) | Greenfield includes Aggregate / Architecture Decisions and other Greenfield-specific H3 sections | - |
+
+## Reference Flow Parity
+
+Common reference flows under `sdd-ddd-brownfield-skill/references/` and
+`sdd-ddd-greenfield-skill/references/` must stay synchronized unless a
+track-specific difference is explicit. This includes
+`dflow-feedback-flow.md`; it is a governance/support flow and should not grow
+GitHub CLI submission behavior without a separate proposal.
+
+## Section Anchors
+
+The `Section anchors` column is the single maintenance location for template section anchor coverage. Do not create a separate `SECTION-ANCHORS.md`.
+
+When adding a new anchor:
+
+1. Add the anchor definition to `archive/proposals/PROPOSAL-013-system-document-template-coverage.md` §1 "Important Dflow-updated sections" (historical reference) or its successor governance document.
+2. Add the anchor id to the matching row in this matrix.
+3. Follow the anchor naming / namespacing / versioning rules defined in `archive/proposals/PROPOSAL-013-system-document-template-coverage.md` §1.

package/TEMPLATE-LANGUAGE-GLOSSARY.md

@@ -0,0 +1,52 @@
+<!-- Maintenance contract for Dflow. See archive/proposals/PROPOSAL-013-system-document-template-coverage.md §1.1 for origin. -->
+
+# Template Language Glossary
+
+This file is a human reading aid and review reference for Dflow template terminology. It is not a second template set.
+
+Template headings, field labels, anchors, and placeholder names use canonical English. Free prose inside those sections follows the project `Prose Language` convention.
+
+## Inclusion Criteria
+
+A term is included in this glossary when it meets **any** of these:
+
+1. **Cross-file structural term** — appears as a heading / column / inline label in two or more templates (e.g. `Implementation Tasks`, `Business Rules`).
+2. **Translation-sensitive concept** — direct Chinese translation may lose precision or differ from common usage (e.g. `Behavior Delta` vs 「行為變更」, `Resume Pointer` vs 「接續入口」).
+3. **Workflow-critical inline label** — bold inline labels that AI / tooling reads as fixed fields within a section (e.g. `**Before** / **After** / **Reason**`).
+4. **Commit message convention label** — labels used in Integration Commit Message Conventions (e.g. `Feature Goal`, `Change Scope`, `Phase Count`).
+
+A term is **NOT** included when:
+
+- The English heading is self-explanatory and its Chinese translation is unambiguous (e.g. `Open Questions`, `Edge Cases`, `Test Strategy`, `Implementation Notes`, `Goals & Scope`, `Phase Specs`, `Problem`, `Root Cause`, `Fix Approach`, `Tech Debt Discovered`).
+- It only appears once in a single template as a section heading without cross-file reference.
+- It is a placeholder example (e.g. `{one-line summary}`) rather than a structural term.
+
+The "使用位置" column refers to file paths where the term appears structurally (as heading / column / label), not necessarily a specific section. For example, `Domain Models` appears as the H1 of `models.md`, representing the file's central concept; `Implementation Tasks` appears as an H2 in two different templates.
+
+## Glossary
+
+| English term | 繁體中文對照 | 使用位置 | 說明 |
+|---|---|---|---|
+| Implementation Tasks | 實作任務 | `phase-spec.md`, `lightweight-spec.md` | AI 產生與追蹤 task checklist 的段落 |
+| Behavior Scenarios | 行為情境 | `phase-spec.md`, `behavior.md` | Given/When/Then 行為規格 |
+| Business Rules | 業務規則 | `rules.md`, `_index.md` | BR-ID declarative rules |
+| Current BR Snapshot | 目前業務規則快照 | `_index.md` | feature-level rules snapshot |
+| Domain Models | 領域模型 | `models.md` | Entities / Value Objects / Services 等模型索引 |
+| Change Scope | 變動範圍 | `Git-principles-*.md`, spec templates | 描述本次變更涵蓋的功能 / 文件 / 程式碼範圍 |
+| Feature Goal | 功能目標 | `Git-principles-*.md`, `finish-feature-flow.md` | Integration Summary 與整合 commit message 的主目標段落 |
+| Related BR-IDs | 關聯 BR-ID 清單 | `Git-principles-*.md`, `finish-feature-flow.md` | 統整本次變更涉及的 ADDED / MODIFIED / REMOVED BR-ID |
+| Phase Count | Phase 數 | `Git-principles-*.md`, `finish-feature-flow.md` | 整合摘要中描述本次 feature 涵蓋的 phase-spec 數量 |
+| Lightweight Change | 輕量修改 | `_index.md`, `lightweight-spec.md`, Git principles | T2 / small change 類型的固定術語 |
+| Lightweight Changes | 輕量修改紀錄 | `_index.md` | `_index.md` 中登記 T2 外連 + T3 inline 的 section heading |
+| Resume Pointer | 接續入口 | `_index.md` | `_index.md` 末段「目前進展 + 下一動作」的 section heading |
+| Behavior Delta | 行為變更 | `lightweight-spec.md` | lightweight-spec 中 BR delta 段的 section heading |
+| Current Progress | 目前進展 | `_index.md` | Resume Pointer 段內描述當下狀態的 inline bold label（per F-04 / DD-A Path A）|
+| Next Action | 下一個動作 | `_index.md` | Resume Pointer 段內描述下一動作的 inline bold label（per F-04 / DD-A Path A）|
+| Before | 原本 | `lightweight-spec.md`, `phase-spec.md`, `references/modify-existing-flow.md` | Behavior Delta MODIFIED 段內描述變更前狀態的 inline bold label（per F-08 / DD-A Path A）|
+| After | 改為 | `lightweight-spec.md`, `phase-spec.md`, `references/modify-existing-flow.md` | Behavior Delta MODIFIED 段內描述變更後狀態的 inline bold label（per F-08 / DD-A Path A）|
+| Reason | 原因 | `lightweight-spec.md`, `phase-spec.md`, `references/modify-existing-flow.md` | Behavior Delta 段內描述變更原因的 inline bold label（per F-08 / DD-A Path A）|
+| Prose Language | prose 語言 / 自由文字語言 | `dflow/specs/shared/_conventions.md`, init flow, prose-generating references | 專案層級設定，規範 AI 生成自由 prose 時使用的 explicit BCP-47 language tag，例如 `zh-TW` 或 `en` |
+| Free prose | 自由 prose / 自由文字 | Templates, generated specs, workflow references | 由使用者或 AI 撰寫的段落內容，例如 task 描述、Root Cause、Fix Approach、Open Questions；遵循專案 `Prose Language` |
+| Structural language | 結構性語言 | Templates, generated specs, `TEMPLATE-COVERAGE.md` | 固定文件結構語言，例如 headings、table headers、labels、placeholders、IDs、anchors；Dflow 保持 canonical English |
+| Canonical English | 標準英文結構 | Templates, scaffolding, generated specs | Dflow 固定使用的英文結構詞彙，用於穩定 AI 導航、anchor 定位與跨檔維護 |
+| Code-facing terms | 面向程式碼的術語 | Templates, generated specs, `_conventions.md` | 不應只為符合 prose 語言而翻譯的內容，例如 code identifiers、DDD pattern names、BR IDs、SPEC IDs、file paths、branch names、anchors、inline code |

package/bin/dflow.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { runConfigureAgents, runInit } = require('../lib/init');
+const { runConfigureAgents, runDoctor, runInit } = require('../lib/init');
 const pkg = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -11,6 +11,7 @@ function printHelp() {
 Usage:
   dflow init              Initialize Dflow specs in the current project
   dflow configure-agents  Add or update AI agent instruction shims
+  dflow doctor            Read-only health check for legacy / pre-V1 artifacts
   dflow --help            Show this help
   dflow --version         Show the CLI version
 `);
@@ -37,6 +38,23 @@ dflow/specs/shared/AI-AGENT-GUIDE.md file.
 `);
 }
 
+function printDoctorHelp() {
+  process.stdout.write(`Usage:
+  dflow doctor
+
+Read-only health check for the current project. Reports legacy
+or pre-V1 artifacts that may need manual migration:
+
+  - root specs/ directory containing Dflow content
+  - _共用/ directory under specs/ or dflow/specs/
+  - dflow/specs/shared/_conventions.md missing the Dflow Version
+    front-matter line
+
+Doctor never modifies files. See docs/migrating-to-dflow-v1.md
+for the manual migration checklist.
+`);
+}
+
 async function main() {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     printHelp();
@@ -86,6 +104,24 @@ async function main() {
     });
   }
 
+  if (args[0] === 'doctor') {
+    if (args.length > 1 && (args[1] === '--help' || args[1] === '-h')) {
+      printDoctorHelp();
+      return 0;
+    }
+
+    if (args.length > 1) {
+      process.stderr.write(`Unsupported doctor option: ${args.slice(1).join(' ')}\n`);
+      return 1;
+    }
+
+    return await runDoctor({
+      cwd: process.cwd(),
+      stdout: process.stdout,
+      stderr: process.stderr
+    });
+  }
+
   process.stderr.write(`Unsupported subcommand: ${args[0]}\n\n`);
   printHelp();
   return 1;