dflow-sdd-ddd 0.2.0 → 0.3.0

package/docs/using-with-github-copilot.md

@@ -0,0 +1,177 @@
+# 在 GitHub Copilot 中使用 Dflow
+
+> **繁體中文** | [English](using-with-github-copilot.en.md)
+
+當你的 AI 程式設計助理是 GitHub Copilot（IDE chat + inline completions）時，Dflow 的使用體驗 walk-through。閱讀約需 10 分鐘。
+
+本指南專注於 GitHub Copilot 的具體使用體驗。工具中立的評估流程請見
+[`docs/evaluating-dflow.md`](evaluating-dflow.md)。完整的 Get Started
+與功能列表請見 [`README.md`](../README.md)。
+
+## 本指南的適用對象
+
+你正在使用或評估以 GitHub Copilot 作為 AI 程式設計助理的 Dflow。
+本指南說明 `init` 之後 Copilot 看到了什麼、repository shim 的位置、
+如何從 IDE 呼叫 Dflow workflow，以及幾個值得了解的 Copilot 專屬使用模式
+與 permission 行為。
+
+## 前置條件
+
+- 在你的 IDE（VS Code、JetBrains 或 GitHub.dev）中已啟用 GitHub Copilot。
+- 已具備 Node.js / npm 環境（Dflow 透過 npm 發佈）。以
+  `npm install -g dflow-sdd-ddd` 全域安裝，或用 `npx dflow-sdd-ddd init`
+  走免安裝路徑，確保 repository shim 存在。
+- 已具備 Dflow canonical 指南的基本認識：`dflow/specs/shared/AI-AGENT-GUIDE.md`。
+
+## `init` 之後 GitHub Copilot 看到了什麼
+
+`init` 為 Copilot 在以下路徑寫入一個小型的工具專屬薄 shim：
+
+- `.github/copilot-instructions.md`（注意：位於 `.github/` 目錄內，非專案根目錄）
+
+生成的 shim 範例：
+
+```markdown
+# GitHub Copilot Repository Instructions
+
+This project uses Dflow for spec-first AI-assisted development.
+
+Before planning or editing code, read and follow:
+
+- `dflow/specs/shared/AI-AGENT-GUIDE.md`
+```
+
+重點說明：
+
+- Copilot shim 位於 `.github/copilot-instructions.md`（見 `lib/init.js` mapping）。
+- Copilot shim 不含 Markdown `@` import。它只透過路徑指向 canonical 指南，讀取
+  `dflow/specs/shared/AI-AGENT-GUIDE.md` 時需明確開啟該檔案。
+
+## 在 GitHub Copilot 中使用 Dflow Workflow 指令
+
+Copilot 是 IDE 優先的助理（chat panel + inline completions），不是 CLI 工具。
+請把 Dflow workflow 名稱當成普通的對話指示，而非 CLI slash command：
+
+- 在 Copilot Chat 中：「Run the Dflow /dflow:new-feature workflow」—— Copilot
+  應讀取 canonical 指南並繼續執行。
+- 在程式碼 comment 或 editor chat 中，以普通文字描述 workflow：
+  `Run the Dflow /dflow:new-feature workflow.`
+
+可用的 workflow 入口：
+
+| 指令 | 適用情境 |
+|---|---|
+| `/dflow:new-feature` | 需要新增一個使用者可見的功能或業務行為。 |
+| `/dflow:modify-existing` | 需要修改現有行為。 |
+| `/dflow:bug-fix` | 可以用預期行為 vs 實際行為描述的缺陷。 |
+| `/dflow:new-phase` | 進行中的 feature 需要另一個實作 slice。 |
+| `/dflow:finish-feature` | 實作完成後需要進行漂移（drift）收尾。 |
+| `/dflow:verify` | 需要對 spec、領域文件、實作與測試進行一致性檢查。 |
+| `/dflow:pr-review` | 變更已準備好進行 SDD/DDD review。 |
+| `/dflow:report-dflow-feedback` | 你發現了 Dflow 的問題或改進點，想要一份清理過的上游回饋草稿。 |
+
+### 對話範例
+
+典型的 Copilot Chat workflow 如下：
+
+```text
+You: I'd like to use the /dflow:new-feature workflow. We need to add the
+     ability for users to export their data as CSV.
+
+Copilot: I'll help you structure this as a new feature. Let me start by
+         reviewing the AI-AGENT-GUIDE to understand the spec format.
+
+         Before drafting the feature spec, I need to understand the scope:
+
+         1. Should the CSV include all user data fields or a selected subset?
+         2. Which user roles should be able to trigger the export?
+         3. Are there any compliance or performance constraints I should know?
+
+You: All fields, only admin users, and exports should complete within 30 seconds
+     for datasets up to 1 million rows.
+
+Copilot: Got it. I'll create the feature spec at dflow/specs/features/active/
+         with these constraints. Let me also outline the implementation phases...
+```
+
+### 既有的 Repository 指示
+
+如果你的專案中已有 `.github/copilot-instructions.md`，`init` 不會覆蓋它。
+它改為在 `dflow/specs/shared/` 下寫入 merge snippet，讓你手動審閱後貼入
+既有檔案。這樣可以避免破壞你已有的自訂 Copilot 指示。
+
+到 `dflow/specs/shared/COPILOT-INSTRUCTIONS-MERGE-SNIPPET.md` 找到 merge
+snippet，再把相關段落貼入你現有的 `.github/copilot-instructions.md`。
+
+### Slash Command Passthrough 說明
+
+Copilot 是否會直通（passthrough）原始的 `/dflow:*` slash command，取決於
+IDE 整合方式與 Copilot 版本。若 Copilot 無法識別以 slash 為前綴的 workflow
+名稱，以普通文字重新送出請求：
+
+```text
+You: Instead of /dflow:new-feature, try: "Please help me start a new Dflow
+     feature workflow. Read dflow/specs/shared/AI-AGENT-GUIDE.md first."
+```
+
+## 與其他 AI 工具的差異
+
+canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間是相同的。
+只有根目錄層的 shim 有所不同：
+
+| 工具 | 產生的 shim | 載入 canonical 指南的方式 |
+|---|---|---|
+| GitHub Copilot | `.github/copilot-instructions.md` | 直接讀取 repository 指示 |
+| Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| Gemini CLI | `GEMINI.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| Codex / Copilot coding agent | `AGENTS.md` | 啟動時直接讀取檔案內容 |
+
+- Shim 路徑：Copilot 使用 `.github/copilot-instructions.md`（不是 `AGENTS.md`
+  或 `CLAUDE.md`）。
+- Markdown import：Copilot shim 不含 `@dflow/specs/shared/AI-AGENT-GUIDE.md`
+  import。這點與 Claude Code / Gemini CLI 的 shim 透過 `@` import inline 嵌入不同。
+- 工具模型：Copilot 是 IDE-based（chat panel + inline completions）；
+  Codex / Claude Code 是 CLI-based agent。Copilot 透過編輯器 UI 互動，而非
+  command-line session。
+- Workflow 呼叫：使用 CLI agent 時可對 agent process 輸入 `/dflow:*`；使用
+  Copilot 時，建議在 Copilot Chat 或 editor comment 中使用普通文字描述。
+- Permission 模型：Copilot 依賴 IDE 的 permission 與 extension sandbox。它可能
+  受 editor-level approvals 管理；CLI 工具通常有明確的 sandbox flags 與獨立的
+  permission gates。
+
+## 常見模式與注意事項
+
+- 保持 `.github/copilot-instructions.md` 精簡。Canonical Dflow 指南
+  （`dflow/specs/shared/AI-AGENT-GUIDE.md`）才是 source of truth。
+- 若 Copilot 看起來只從 shim 文字工作，請明確要求它開啟或讀取
+  `dflow/specs/shared/AI-AGENT-GUIDE.md` 後再繼續。
+- Copilot 的 inline completions 可能在未走 Dflow workflow 的情況下直接建議程式碼；
+  需要 spec-driven 輸出時，請明確要求執行 workflow。
+- Copilot Chat context 不一定會在所有 IDE 版本中自動包含 `.github/` 目錄下的
+  repository 指示檔；行為因 Copilot / IDE 版本而異（見頁尾說明）。
+- 當 slash-prefixed forms 被 IDE 拒絕時，改用普通文字描述 workflow 名稱。
+
+## 下一步
+
+如果你還沒有執行 `init`：
+
+- 執行 `dflow init`（安裝後）或 `npx dflow-sdd-ddd init`，選擇 Copilot 目標
+  以建立 `.github/copilot-instructions.md`。參考
+  [評估者指南 Playbook](evaluating-dflow.md#30-分鐘評估-playbook) 在可拋棄的
+  範例專案中試用。
+
+如果你已執行 `init` 且想查看端到端的 workflow 範例：
+
+- 閱讀 [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../sdd-ddd-greenfield-skill/scaffolding/AI-AGENT-GUIDE.md)
+  （或 brownfield 等效版本）後再開始 workflow。
+- 閱讀 [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)，
+  其中有展示 Copilot chat flow 的對話範例。
+
+如果你想了解設計理念：
+
+- 閱讀[為什麼 AI 時代 DDD 更重要](why-ddd-for-ai.md)。
+
+---
+
+IDE 行為說明：Slash command passthrough 與 `.github/` 指示檔的自動包含行為，
+會因 Copilot / IDE 版本而異。依賴確切語意前請向 maintainer 確認。

package/docs/why-ddd-for-ai.en.md

@@ -0,0 +1,37 @@
+# Why DDD Matters More with AI
+
+> [繁體中文](why-ddd-for-ai.md) | **English**
+
+AI-assisted development changes the failure mode of software design. The team can produce more code faster, but unclear domain meaning is also amplified faster.
+
+When a project lacks shared language and explicit boundaries, small inconsistencies spread:
+
+- the same concept appears as `Order`, `Booking`, and `Transaction`
+- APIs encode different meanings for similar actions
+- business rules live in handlers, UI code, scripts, and tests
+- nobody can confidently say which behavior is authoritative
+
+An AI coding agent does not know the business domain by default. When the prompt is incomplete, it fills the missing parts with plausible logic. That logic may compile, pass superficial tests, and still be wrong. The most dangerous AI mistakes are often not syntax errors; they are reasonable-looking domain mistakes.
+
+DDD gives the spec a semantic backbone:
+
+| DDD idea | AI-era value |
+|---|---|
+| **Ubiquitous Language** | Keeps names and meanings stable across prompts, specs, code, and reviews. |
+| **Bounded Context** | Defines where a term or rule is valid, and prevents accidental meaning leaks. |
+| **Domain Model** | Gives behavior a clear owner instead of scattering rules across technical layers. |
+| **Domain Rules** | States what is correct, allowed, forbidden, and exceptional before code generation. |
+
+The important shift is where design lives. In older workflows, much of the real design could remain implicit in code. With AI, that is too late. The model needs constraints before it generates code.
+
+```text
+Without DDD:
+Prompt -> AI fills gaps -> Code -> Hidden domain drift
+
+With DDD:
+Domain meaning -> Structured spec -> AI implementation -> Reviewable code
+```
+
+Code still matters, but it is no longer the first place where meaning should be discovered. For AI collaboration, specs become the pre-generation contract, and DDD supplies the language, boundaries, and rules that make the contract precise.
+
+Dflow is built around that idea: spec first, domain meaning explicit, AI constrained before implementation, and drift checked before the work is considered done.

package/docs/why-ddd-for-ai.md

@@ -1,26 +1,28 @@
-# Why DDD Matters More with AI
+# 為什麼 AI 時代 DDD 更重要
 
-AI-assisted development changes the failure mode of software design. The team can produce more code faster, but unclear domain meaning is also amplified faster.
+> **繁體中文** | [English](why-ddd-for-ai.en.md)
 
-When a project lacks shared language and explicit boundaries, small inconsistencies spread:
+AI 輔助開發改變了軟體設計的失敗模式。團隊能更快產出更多程式碼，但不清晰的領域語義也會以同樣的速度擴散。
 
-- the same concept appears as `Order`, `Booking`, and `Transaction`
-- APIs encode different meanings for similar actions
-- business rules live in handlers, UI code, scripts, and tests
-- nobody can confidently say which behavior is authoritative
+當專案缺乏共同語言與明確邊界時，細小的不一致便會蔓延：
 
-An AI coding agent does not know the business domain by default. When the prompt is incomplete, it fills the missing parts with plausible logic. That logic may compile, pass superficial tests, and still be wrong. The most dangerous AI mistakes are often not syntax errors; they are reasonable-looking domain mistakes.
+- 同一個概念以 `Order`、`Booking`、`Transaction` 三種名稱出現
+- API 對相似動作賦予不同語義
+- 業務規則分散在 handler、UI 程式碼、腳本與測試之中
+- 沒有人能確定哪一個行為才是權威的
 
-DDD gives the spec a semantic backbone:
+AI 程式碼代理預設不了解業務領域。當 prompt 資訊不完整時，它會以看似合理的邏輯填補缺漏。這些邏輯可能通過編譯、通過表面測試，卻依然是錯的。AI 最危險的錯誤往往不是語法錯誤，而是外觀合理的領域錯誤。
 
-| DDD idea | AI-era value |
+DDD 為規格提供語義骨幹：
+
+| DDD 概念 | AI 時代的價值 |
 |---|---|
-| **Ubiquitous Language** | Keeps names and meanings stable across prompts, specs, code, and reviews. |
-| **Bounded Context** | Defines where a term or rule is valid, and prevents accidental meaning leaks. |
-| **Domain Model** | Gives behavior a clear owner instead of scattering rules across technical layers. |
-| **Domain Rules** | States what is correct, allowed, forbidden, and exceptional before code generation. |
+| **Ubiquitous Language（通用語言）** | 讓名稱與語義在 prompt、規格、程式碼與 review 之間保持穩定。 |
+| **Bounded Context** | 定義術語或規則的有效範圍，防止語義意外洩漏。 |
+| **領域模型（Domain Model）** | 讓行為有明確的所有者，而不是將規則分散在技術層之間。 |
+| **領域規則（Domain Rules）** | 在程式碼生成之前，先明確指出什麼是正確的、允許的、禁止的，以及例外情況。 |
 
-The important shift is where design lives. In older workflows, much of the real design could remain implicit in code. With AI, that is too late. The model needs constraints before it generates code.
+關鍵的轉變在於設計的位置。舊有的工作流程中，大量真正的設計可以隱含在程式碼裡。引入 AI 之後，這樣做已經太遲。模型需要在生成程式碼之前就取得約束條件。
 
 ```text
 Without DDD:
@@ -30,6 +32,6 @@ With DDD:
 Domain meaning -> Structured spec -> AI implementation -> Reviewable code
 ```
 
-Code still matters, but it is no longer the first place where meaning should be discovered. For AI collaboration, specs become the pre-generation contract, and DDD supplies the language, boundaries, and rules that make the contract precise.
+程式碼仍然重要，但不再是發現語義的第一現場。在 AI 協作模式下，規格成為生成前的契約，DDD 提供語言、邊界與規則，使契約具備精確性。
 
-Dflow is built around that idea: spec first, domain meaning explicit, AI constrained before implementation, and drift checked before the work is considered done.
+Dflow 正是圍繞這個理念建構：規格優先、領域語義顯式化、在實作前約束 AI，並在工作完成前驗證漂移（drift）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {

package/templates/brownfield/scaffolding/AI-AGENT-GUIDE.md

@@ -70,7 +70,8 @@ Signals:
   canonical English; compare against `TEMPLATE-LANGUAGE-GLOSSARY.md` if
   available.
 - References to a runtime `/dflow:init-project` slash command (V1
-  replaced it with the shell command `npx dflow-sdd-ddd init`).
+  replaced it with the Dflow CLI init command (`dflow init`, or
+  `npx dflow-sdd-ddd init` when using the no-install path)).
 - A root `CLAUDE.md`, `AGENTS.md`, or equivalent that holds the full
   Dflow workflow text instead of being a thin shim pointing to this
   file.

package/templates/brownfield/scaffolding/CLAUDE-md-snippet.md

@@ -5,9 +5,9 @@
 > This file is a **snippet**, not a standalone `CLAUDE.md`. Its purpose
 > is to be merged into your project's root `CLAUDE.md`:
 >
-> - New `npx dflow-sdd-ddd init` output uses
->   `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical guide and
->   creates a thin `CLAUDE.md` shim that points back to it.
+> - New Dflow CLI init output (`dflow init`, or `npx dflow-sdd-ddd init` when
+>   using the no-install path) uses `dflow/specs/shared/AI-AGENT-GUIDE.md` as
+>   the canonical guide and creates a thin `CLAUDE.md` shim that points back to it.
 > - Use this legacy snippet only if you intentionally want the older
 >   Claude-specific two-H2 layout in your project's root `CLAUDE.md`.
 
@@ -45,7 +45,7 @@ ASP.NET Core 做準備。
 
 ```
 dflow/specs/
-├── shared/                   # 專案級治理文件（由 npx dflow-sdd-ddd init 寫入）
+├── shared/                   # 專案級治理文件（由 Dflow CLI init 寫入）
 │   ├── _overview.md          # 系統現況與遷移策略
 │   ├── _conventions.md       # 規格撰寫慣例
 │   └── Git-principles-*.md   # Git 規範（gitflow 或 trunk 版）
@@ -97,7 +97,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 當你作為 AI assistant 被呼叫時，若偵測到使用者需要 SDD/DDD 工作流
 引導，請參考 Dflow entry points：
 
-- `npx dflow-sdd-ddd init` — 專案初始化（建立 `dflow/specs/` 結構）
+- Dflow CLI init command (`dflow init`, or `npx dflow-sdd-ddd init` when using the no-install path) — 專案初始化（建立 `dflow/specs/` 結構）
 - `/dflow:new-feature` — 新功能開發
 - `/dflow:new-phase` — 在 active feature 內新增階段
 - `/dflow:modify-existing` — 修改既有功能
@@ -162,5 +162,5 @@ When merging this snippet into an existing `CLAUDE.md`:
    duplicate it.
 
 If you are starting from scratch (no existing `CLAUDE.md`), the
-`npx dflow-sdd-ddd init` flow will install this snippet as-is and you
-can refine from there.
+the Dflow CLI init flow (`dflow init`, or `npx dflow-sdd-ddd init` when using
+the no-install path) will install this snippet as-is and you can refine from there.

package/templates/brownfield/templates/CLAUDE.md

@@ -17,7 +17,7 @@
 
 ```
 dflow/specs/
-├── shared/                   # 專案級治理文件（由 npx dflow-sdd-ddd init 寫入）
+├── shared/                   # 專案級治理文件（由 dflow init 寫入）
 │   ├── _overview.md          # 系統現況與遷移策略
 │   └── _conventions.md       # 規格撰寫慣例與模板
 ├── domain/                   # 領域知識

package/templates/brownfield/templates/phase-spec.md

@@ -19,30 +19,33 @@ Template note (for AI):
   `phase-spec-YYYY-MM-DD-{slug}.md` placed at
   `dflow/specs/features/active/{SPEC-ID}-{slug}/`.
 
-  Each section below carries an HTML comment indicating its fill-in phase (Phase 1-4).
-  These phase markers let /dflow:status and the completion checklist track progress.
-  Phases correspond to SKILL.md § Guiding Questions by Phase:
-    Phase 1 - Understanding (What & Why)
-    Phase 2 - Domain Analysis (Where does it live?)
-    Phase 3 - Spec Writing (Behavior + Rules + Edge Cases)
-    Phase 4 - Implementation Planning
-  The "Implementation Tasks" section at the end is generated by AI after Phase 4 planning is done
+  Each section below carries an HTML comment indicating its fill-in activity (Activity 1-4).
+  These activity markers let /dflow:status and the completion checklist track progress.
+  Activities correspond to SKILL.md § Guiding Questions by Activity:
+    Activity 1: Understanding (What & Why)
+    Activity 2: Domain Analysis (Where does it live?)
+    Activity 3: Spec Writing (Behavior + Rules + Edge Cases)
+    Activity 4: Implementation Planning
+  The "Implementation Tasks" section at the end is generated by AI after Activity 4 (Implementation Planning) is done
   (see new-feature-flow.md Step 5 end / new-phase-flow.md Step 4 end /
    modify-existing-flow.md Step 4 end).
 
+  Note: "phase 2+ specs" / "Phase 2+" in the BR and Delta sections below refers to
+  the N-th phase-spec of this feature (i.e. iteration unit), NOT an activity number.
+
   For phase 2+ specs in the same feature: only list BRs that are NEW or
   MODIFIED in this phase under "Business Rules"; do not re-copy unchanged BRs from
   prior phases. The cumulative state lives in the feature's `_index.md`
   Current BR Snapshot table.
 -->
 
-## Problem Description <!-- Fill timing: Phase 1 -->
+## Problem Description <!-- Fill timing: Activity 1: Understanding -->
 
 這個功能要解決什麼問題？誰需要它？
 
 > 用使用者的角度描述，避免技術用語。
 
-## Domain Concepts <!-- Fill timing: Phase 2 -->
+## Domain Concepts <!-- Fill timing: Activity 2: Domain Analysis -->
 
 涉及的 Domain 概念（引用 `dflow/specs/domain/{context}/models.md`）：
 
@@ -55,7 +58,7 @@ Template note (for AI):
 - [ ] `dflow/specs/domain/{context}/models.md` — 新增模型定義
 
 <!-- dflow:section behavior-scenarios -->
-## Behavior Scenarios <!-- Fill timing: Phase 3 -->
+## Behavior Scenarios <!-- Fill timing: Activity 3: Spec Writing -->
 
 ### Main Success Scenario
 
@@ -75,7 +78,7 @@ Scenario: {替代情境}
   Then {不同的預期結果}
 ```
 
-## Business Rules <!-- Fill timing: Phase 3 -->
+## Business Rules <!-- Fill timing: Activity 3: Spec Writing -->
 
 > Phase 2+ 注意：本段僅列**本 phase 新增 / 修改到的 BR**；未變動的 BR 不重抄
 > （它們的當前狀態見 feature 的 `_index.md` Current BR Snapshot 表）。
@@ -85,7 +88,7 @@ Scenario: {替代情境}
 | BR-01 | {規則描述} | |
 | BR-02 | {規則描述} | |
 
-## Delta from prior phases <!-- Fill timing: Phase 3; skip for the first phase -->
+## Delta from prior phases <!-- Fill timing: Activity 3: Spec Writing; skip for the first phase -->
 
 > 本段僅記**本 phase 相對前一 phase 的變化**，不累積歷史。歷史由 feature 目錄下
 > 各 phase-spec 的本段串接閱讀；feature 層的當前累積狀態見 `_index.md` 的
@@ -119,14 +122,14 @@ Then {新的預期結果}
 - BR-003 金額上限
 - BR-005 提交後不可修改
 
-## Edge Cases <!-- Fill timing: Phase 3 -->
+## Edge Cases <!-- Fill timing: Activity 3: Spec Writing -->
 
 | ID | Case | Expected Handling |
 |---|---|---|
 | EC-01 | {邊界描述} | {處理方式} |
 | EC-02 | {邊界描述} | {處理方式} |
 
-## Implementation Notes <!-- Fill timing: Phase 4 -->
+## Implementation Notes <!-- Fill timing: Activity 4: Implementation Planning -->
 
 ### Current WebForms Implementation
 
@@ -148,7 +151,7 @@ Then {新的預期結果}
 
 > 遷移時需要注意的事項，或者現在的設計如何幫助未來遷移。
 
-## Data Structure Changes <!-- Fill timing: Phase 4 -->
+## Data Structure Changes <!-- Fill timing: Activity 4: Implementation Planning -->
 
 > 涉及的資料表與欄位變更（如有）
 
@@ -156,7 +159,7 @@ Then {新的預期結果}
 |---|---|---|---|
 | {Table} | {Column} | 新增/修改/刪除 | |
 
-## Test Strategy <!-- Fill timing: Phase 4 -->
+## Test Strategy <!-- Fill timing: Activity 4: Implementation Planning -->
 
 > Domain 層的單元測試應驗證哪些行為？
 
@@ -164,14 +167,14 @@ Then {新的預期結果}
 - [ ] {測試案例 2}
 
 <!-- dflow:section open-questions -->
-## Open Questions <!-- Fill timing: Phase 1-4 -->
+## Open Questions <!-- Fill timing: Activity 1-4; any time during planning -->
 
 - {尚未釐清的需求、規則、資料或實作問題}
 
 <!-- dflow:section implementation-tasks -->
-## Implementation Tasks <!-- Fill timing: generated by AI after Phase 4; all items should be checked at completion -->
+## Implementation Tasks <!-- Fill timing: generated by AI after Activity 4: Implementation Planning; all items should be checked at completion -->
 
-> AI 在 Phase 4 實作規劃完成後，根據「Implementation Notes」產生的具體任務清單。
+> AI 在 Activity 4 (Implementation Planning) 完成後，根據「Implementation Notes」產生的具體任務清單。
 > 格式：`[LAYER]-[NUMBER]: 任務描述`
 > 分類標籤（Brownfield track）：
 >   - `DOMAIN`  — Domain 層類別、VO、Service、Interface

package/templates/greenfield/scaffolding/AI-AGENT-GUIDE.md

@@ -70,7 +70,8 @@ Signals:
   canonical English; compare against `TEMPLATE-LANGUAGE-GLOSSARY.md` if
   available.
 - References to a runtime `/dflow:init-project` slash command (V1
-  replaced it with the shell command `npx dflow-sdd-ddd init`).
+  replaced it with the Dflow CLI init command (`dflow init`, or
+  `npx dflow-sdd-ddd init` when using the no-install path)).
 - A root `CLAUDE.md`, `AGENTS.md`, or equivalent that holds the full
   Dflow workflow text instead of being a thin shim pointing to this
   file.

package/templates/greenfield/scaffolding/CLAUDE-md-snippet.md

@@ -14,9 +14,9 @@
 
 ## How to use this snippet
 
-- New `npx dflow-sdd-ddd init` output uses
-  `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical guide and creates
-  a thin `CLAUDE.md` shim that points back to it.
+- New Dflow CLI init output (`dflow init`, or `npx dflow-sdd-ddd init` when
+  using the no-install path) uses `dflow/specs/shared/AI-AGENT-GUIDE.md` as
+  the canonical guide and creates a thin `CLAUDE.md` shim that points back to it.
 - Use this legacy snippet only if you intentionally want the older
   Claude-specific two-H2 layout in your project's root `CLAUDE.md`.
 
@@ -66,7 +66,7 @@ Presentation → Application → Domain ← Infrastructure
 ### Project Structure
 
 完整 specs 目錄結構見 Dflow skill `SKILL.md` § "Project Structure"。
-以下只列本專案當前狀態（`npx dflow-sdd-ddd init` 建立後可能還未全填）：
+以下只列本專案當前狀態（Dflow CLI init 建立後可能還未全填）：
 
 ```
 dflow/specs/
@@ -101,7 +101,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - `sdd-ddd-greenfield-skill/references/` 內各 flow 文件
 
 本專案採用的 Dflow entry points：
-- `npx dflow-sdd-ddd init` — 專案初始化（一次性，已執行過）
+- Dflow CLI init command (`dflow init`, or `npx dflow-sdd-ddd init` when using the no-install path) — 專案初始化（一次性，已執行過）
 - `/dflow:new-feature` — 新功能
 - `/dflow:new-phase` — 既有 active feature 加新 phase
 - `/dflow:modify-existing` — 修改既有行為
@@ -165,5 +165,6 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - The snippet does NOT re-copy the Dflow decision tree, Ceremony
   Scaling criteria, or per-flow step details — those live in the
   skill and change when the skill evolves
-- Re-run `npx dflow-sdd-ddd init` will NOT overwrite an existing
-  `CLAUDE.md`; if you want to re-sync, merge manually
+- Re-running the Dflow CLI init command (`dflow init`, or `npx dflow-sdd-ddd init`
+  when using the no-install path) will NOT overwrite an existing `CLAUDE.md`;
+  if you want to re-sync, merge manually

package/templates/greenfield/scaffolding/_conventions.md

@@ -101,7 +101,7 @@ Project-specific guidance when filling these templates:
   descriptions (Mermaid state diagram or Given / When / Then + "And
   the Aggregate is in state X").
 - **CQRS split**: commands (write) vs queries (read) should be
-  identified during Phase 4 (Implementation Planning). Commands
+  identified during Activity 4 (Implementation Planning). Commands
   generally map 1:1 to an Aggregate method; queries bypass the
   Domain layer and read projections.
 

package/templates/greenfield/templates/CLAUDE.md

@@ -34,7 +34,7 @@ Presentation → Application → Domain ← Infrastructure
 
 ```
 dflow/specs/
-├── shared/                   # 專案級治理文件（由 npx dflow-sdd-ddd init 寫入）
+├── shared/                   # 專案級治理文件（由 dflow init 寫入）
 │   ├── _overview.md          # 系統現況與遷移策略
 │   └── _conventions.md       # 規格撰寫慣例
 ├── domain/