dflow-sdd-ddd 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -6,6 +6,102 @@
 
 ---
 
+## 0.11.0 — 2026-06-27 — DDD 指引深化 + pre-V1 退役 + docs 刷新
+
+**Proposals**：PROPOSAL-059（modeling-guide 盲區補強）、PROPOSAL-060（Subdomain 分類）、PROPOSAL-061（Brownfield aggregate 萌芽判準）、PROPOSAL-062（戰術補遺）、PROPOSAL-064（Brownfield modeling-guide reachability）、PROPOSAL-065（檢查機械化）、PROPOSAL-066（context-map 語彙補完）、PROPOSAL-063（退役 pre-V1 migration story）
+
+本版主線 = DDD 引導指引一輪深化,貫穿主軸：補 AI 自行建模會漏的盲區、擋 AI 過度套用 DDD、讓 Brownfield 也搆得到完整建模指引、把 review / verify 檢查收成可機械執行的判準；另含 pre-V1 migration story 全退役與 README / docs 刷新。
+
+### 新功能 / 行為改善（DDD 建模指引）
+
+- **DDD modeling guide 盲區補強**（PROPOSAL-059）：補不變式三層分類（local / aggregate-boundary / set-based）、聚合子集合無界成長判準、event payload thin/fat 準則、跨 aggregate 事件鏈失敗路徑 BR 化、Event Sourcing 防呆句。
+- **Subdomain-Aware Modeling Depth（防過度工程）**（PROPOSAL-060）：兩軌 `context-map.md` 加 Subdomain Type 欄（core / supporting / generic）；guide 加「依 subdomain 調建模深度」小節（優先序 cap + 三防誤讀邊界：BR 不豁免 / Tier 正交 / criticality 不降級）。方向是省成本而非加流程。
+- **Brownfield aggregate 萌芽判準**（PROPOSAL-061）：modify-existing / new-feature / new-phase 三流加「一概念累積多條狀態轉移 / 原子跨欄位不變式 → Aggregate 正在成形」偵測,建議升 T1 deliberately 建模。
+- **Brownfield 也搆得到 DDD modeling guide**（PROPOSAL-064）：guide 升為 `templates/common/` canonical bundle reference,`dflow init` / `configure-agents` 投影到 Brownfield 專案（先前 greenfield-only）；guide 內 greenfield-coupled artifact 參照 edition-neutral 化（頂部 Edition note 對映 Brownfield 記錄面）。
+- **modeling guide 戰術補遺**（PROPOSAL-062）：Factory（含 reconstitution ≠ creation）、強型別 ID + domain primitives 判準、Read Model 查詢側（列表 / 報表不走 aggregate）。
+- **context-map 語彙補完**（PROPOSAL-066）：guide BC-Relationships 加 Separate Ways（反過度整合）+ Big Ball of Mud（+ ACL,包 legacy 泥球）判準 / 階梯 + Open Host Service 一句；兩軌 `context-map.md` Relationship Type 語彙同步。
+
+### 維護者 / 檢查機械化
+
+- **DDD 檢查機械化**（PROPOSAL-065）：`pr-review` checklist 的 UL 檢查收成「diff domain-facing 命名 ↔ glossary `Code Mapping` 對照 + 同義詞偵測」（兩軌對齊）；`/dflow:verify` reframe 為「rules↔behavior 核心 + optional domain-doc hygiene」,加 events.md 反向檢查（greenfield,收窄 local + business-significant）與 models.md Code-Mapping 資訊檢查（兩軌）；`check-repo-consistency.sh` 加 Edition-note 載重面 guard（dev-only,不影響套件使用者）。
+
+### 文件 / Tutorial
+
+- **README 刷新 + Why Dflow 頁**：README 更新至現況;新增 `docs/why-dflow.md`（+ 英文 parity）。
+- **tutorial 進階觀念**：`tutorial/DDD_MINDSET_SHIFT.md` 加 3 則進階 mindset（Factory / 強型別 ID / Read Model,對齊 PROPOSAL-062）。
+
+### 移除 / 退役
+
+- **退役 pre-V1 migration story**（PROPOSAL-063）：移除 pre-V1 → V1 migration guide、`dflow doctor` / `dflow init` 的 pre-V1 偵測、`AI-AGENT-GUIDE.md` 偵測段。Dflow 任何已發布 npm 版本皆無 pre-V1 採用者 → 該偵測 / 指引已無對象。**對既有專案：無影響。**
+
+### 修正
+
+- **`--skills` help 修正**：`dflow configure-agents --skills` 的 help 文字補列全三家工具（Claude / Codex / Copilot）。
+
+### 升級提醒
+
+- **Brownfield 取得 DDD modeling guide**（PROPOSAL-064）：既有 Brownfield 專案重跑 `dflow configure-agents` 後,`dflow/specs/shared/dflow-workflows/references/` 下新增 `ddd-modeling-guide.md`（先前僅 greenfield 投影）。
+
+### 驗證
+
+- 每個 DDD phase 全程 proposal-stage + implementation-stage cross-model review 收斂；3b（core-invariant,動 `lib/init.js`）另過 fresh cold-eye gate（r1 抓到破包重投影靜默刪已裝 guide 的 data-loss must-fix）。
+- `npm test` + `scripts/check-repo-consistency.sh`（含 `check-cross-refs.mjs` + source↔mirror diff + `npm pack --dry-run`）全綠。
+
+---
+
+## 0.10.0 — 2026-06-06 — agentskills 標準三家觸發 parity、既有 agent 檔自動注入、投影內容保全與清理
+
+**Proposals**：PROPOSAL-049（feature-slice 使用面語意體檢）、PROPOSAL-050（還原 041 雙軌合一丟失的 skill 內容進 AI-AGENT-GUIDE）、PROPOSAL-051（退役 `templates/CLAUDE.md`）、PROPOSAL-052（bundle stale-removal 推廣到同-edition）、PROPOSAL-054（既有 agent 檔 Dflow 墊片 auto-inject）、PROPOSAL-056（Codex 專案層 skill `--skills` parity）、PROPOSAL-057（以 agentskills.io 標準為三家共同自動觸發層；Phase 2）
+
+本版兩條主線：
+
+1. **入口層標準化 + 降低採用摩擦**（054 / 056 / 057 + Copilot 指南）—— 三家（Claude / Codex / Copilot）以 agentskills.io 開放標準取得 project-level skill 投影 parity（自然語言觸發；Copilot CLI 仍需 `/dflow` 喚起）、既有 agent 檔零手動合併即接上、Claude shim 瘦身、Copilot 跨介面用法講清楚。
+2. **投影內容保全與清理**（049 / 050 / 051 / 052）—— 一輪 feature-by-feature 語意體檢補回 041 雙軌合一時孤兒化的 canonical 內容、退役 legacy 範本、把 bundle 退役檔清除推廣到最常見的同-edition 升級。
+
+### 新功能 / 行為改善
+
+- **`dflow configure-agents --skills` 三家專案層 skill parity（Codex 補自動觸發、Copilot 補原生 skill）**（PROPOSAL-056 + #4 un-defer）：`--skills` 從「只投 Claude、寫死單一路徑」一般化為「把同一份工具中立 thin skill（`templates/common/skill/SKILL.md`）投影到每個被選工具各自的 project-level skill 路徑」。Claude 維持 `.claude/skills/dflow/SKILL.md`；**Codex 新增 `.agents/skills/dflow/SKILL.md`**，找回 Codex 的自然語言自動觸發（先前只有手動命令 / 文字 trigger）；**GitHub Copilot 新增 `.github/skills/dflow/SKILL.md`**（#4 un-defer：spike 確認 Copilot 從自己原生 `.github/skills/` 探索成立、即使移除 `.claude`/`.agents` 跨讀路徑也成立——**VS Code Chat 自然語言自動觸發、Copilot CLI 仍需 `/dflow` 手動喚起**）。Copilot 也會跨讀 `.claude`/`.agents`；Dflow 產生的各份逐字相同，但若該路徑已有非 Dflow 的同名 skill，Dflow 會保留不覆寫、可能內容不同（移除或改名即可避免同名重複）。依據：Claude / Codex / Copilot 已收斂於 agentskills.io 開放標準（皆以 `SKILL.md` 為入口、`name`/`description` frontmatter、project-level 探索、description 驅動自動觸發）。
+
+- **既有 agent 檔的 Dflow 墊片 auto-inject（三工具統一）**（PROPOSAL-054）：當使用者已有自己的根 agent 檔（Claude `CLAUDE.md`、Codex `AGENTS.md`、Copilot `.github/copilot-instructions.md`）且尚未引用 guide，`init` / `configure-agents` 不再預設「丟一個 snippet 檔、Notes 一行請你手動合併」，改為**附加一塊帶 `<!-- dflow-generated: agent-shim START/END -->` 標記的 Dflow 區塊**（呈現為確認預覽裡的一般項目），重跑時**原地抽換**該區塊（idempotent）。snippet + 警告降為 fallback，只在標記殘缺 / 重複 / 顛倒等無法安全注入時才用；並補上先前缺的對稱警告（最常見路徑反而 signpost 最弱的洞）。指令只能以文字寫進 `AGENTS.md` 的 Codex 受惠最大。
+
+- **bundle 退役檔在同-edition 升級也自動清除**（PROPOSAL-052）：`configure-agents` 的 bundle stale-removal 原本只在 **edition 改變**時觸發；現在推廣為「依 manifest diff 清除『舊 manifest 有、當前 bundle 已無』的退役檔」，涵蓋最常見的**同-edition 重跑升級**。一併補三道 projection-cleanup 硬化：current-bundle 非空 guard（防 bundle 掃出空集合時誤刪整包、砍掉 `/dflow:*` 可達性）、壞 manifest 區分 ENOENT vs parse/IO error（後者至少 warn，不再靜默跳過）、待刪檔措辭從硬編「stale adapter / edition changed」修正為通用。**直接受惠**：051 退役 `templates/CLAUDE.md` 後既有同-edition 專案殘留的 vendored copy，重跑 `dflow configure-agents` 即被清掉。
+
+- **Claude shim 瘦身為薄指標**（PROPOSAL-057 Phase 2）：`init` 生成的根 `CLAUDE.md` 墊片不再用 `@import` 把整份 `AI-AGENT-GUIDE.md`（~5k tokens）每個 session 強制載入，改為路徑無關的薄 awareness，並把「讀 guide」scoping 到 spec-impacting work（對齊 progressive disclosure；workflow 步驟本就按需載入）。
+
+- **skill 自動觸發 recall 強化**（PROPOSAL-057 Phase 2）：`templates/common/skill/SKILL.md` 的 `description` 補上間接觸發語（不點命令名的自然語句也能觸發），修掉先前「最間接語句 recall 較弱」的弱點；同時收斂在 **Codex 的 1024 字元上限**內（986 chars），並加 `test/registry-parity.mjs` 護欄斷言 folded description ≤ 1024 防回歸。觸發契約維持 suggest-and-wait（建議命令、等確認，不自動跑完整個 workflow）。
+
+### 文件
+
+- **GitHub Copilot 指南分介面重寫**（copilot-cmd-surface，2026-06-05 實測）：`docs/using-with-github-copilot.md` + `.en.md` 把 Copilot 用法分為 **VS Code Copilot Chat** 與 **GitHub Copilot CLI** 兩節，各自講自動觸發有無、命令能不能用、正確語法 —— VS Code Chat 自然語言自動觸發 + `/dflow-<id>`（連字號，需 `--command-adapters`）；Copilot CLI 無自動觸發、先打 `/dflow` 手動喚起 skill、無 per-id 命令（`.github/prompts/` CLI 不讀取）。冒號形式 `/dflow:<id>` 釐清為 canonical / Claude·Codex 命令語法，在 Copilot 只能當文字稱呼。移除舊的「chat 文字可直接說 canonical `/dflow:<id>`」易誤導措辭。雙語 parity。
+
+### 投影內容保全（PROPOSAL-049 / 050）
+
+- **feature-slice 使用面語意體檢**（PROPOSAL-049）：對「使用 Dflow 時實際會碰到的範圍」（CLI runtime + init 投影的 bundle / adapter + 雙軌 skill source）做一輪 feature-by-feature 人讀語意體檢，補 047（首次 implementation-stage cross-model review）之前 ship、未過該層 review 的盲區。修掉的 drift 含：`modify-existing-flow` 等殘留「the developer commits」的 pre-047 行為者口吻、Greenfield context-definition 路徑兩軌 parity、`/dflow:verify` scope over-claim、`last-updated` 權威歸 `rules.md` 等。純語意 / 結構修正，grep 擋不住。
+
+- **還原 041 合一丟失的 canonical 內容**（PROPOSAL-050）：041 把兩份 per-edition `SKILL.md` 合一成 35 行薄殼時，數個被各 flow 以 `see SKILL.md § …` 指向的 workflow-protocol 段變成**懸空 ref**。本版把這些段（Workflow Transparency〔Auto-Trigger Safety Net / Three-Tier Transparency / Confirmation Signals NL↔Command / Completion Checklist〕、Ceremony Scaling 完整 T1/T2/T3 表、Guiding Questions by Activity、Project Structure）還原進**兩軌 `AI-AGENT-GUIDE.md`**（runtime 面），並 repoint ~15 處 ref；另還原 conservation audit 抓到的 silent-drop（Brownfield 不適用排除條款、三項可攜資產立論、非指令 decision routing、完成清單 skip-detection guard）。使用者專案的 canonical 指南因此恢復完整、ref 不再撲空。
+
+### Migration / 升級提醒
+
+- **`templates/CLAUDE.md` 退役（移除一個 vendored generated 檔）**（PROPOSAL-051）：刪除 Greenfield / Brownfield 各一份 source + mirror 共 4 檔（legacy full-layout 範例）。它**不是** `init` 來源（根 `CLAUDE.md` 由 `lib/init.js` 程式化生成薄殼），canonical 內容（decision routing / Ceremony 表 / per-flow steps）已於 050 全數移進 `AI-AGENT-GUIDE.md` + bundle。**對既有專案的影響**：先前以同-edition 跑過的專案，其 vendored copy `dflow/specs/shared/dflow-workflows/templates/CLAUDE.md` 會留為**無害殘檔**（帶 generated marker、不被任何 flow 消費）；**重跑 `dflow configure-agents` 即自動清除**（PROPOSAL-052 的同-edition stale-removal）。npm tarball 因此縮減一個 generated file。
+
+- **Claude shim 形狀改變**（PROPOSAL-057）：既有專案的根 `CLAUDE.md` 仍可用；若要拿到瘦身後的薄指標版，重跑 `dflow init` / `dflow configure-agents` 即原地刷新該 Dflow 區塊。
+
+### 維護者工具 / 測試（不影響套件使用者）
+
+- **cross-ref resolver guard**（PROPOSAL-055，dev-only）：新增 `scripts/check-cross-refs.mjs`（納入 `check-repo-consistency.sh`），把「文件 `§` / 檔名 / 路徑 ref 解不解得開」從一次性人工 grep 固化為常駐檢查；namespace-aware（限 public source + governance 範圍、跳過 history 與 `{token}` 佔位、§/anchor longest-prefix）。`scripts/` 不投影 dist、不進 tarball。
+- **registry-parity 測試**（PROPOSAL-053，dev-only）：新增 `test/registry-parity.mjs`，斷言 11 個 `/dflow:*` 指令表跨 surface / 雙軌一致（F-02 安全網）；後並加 057 的 folded description ≤ 1024 斷言。
+- **`test/agent-inject.mjs`**（PROPOSAL-054）：新增既有 agent 檔 auto-inject 的注入 / idempotent 抽換 / fallback 矩陣覆蓋。
+- `test/smoke.mjs`：擴充 054 auto-inject、056 `--skills` 各家路徑、052 同-edition stale-removal 等斷言。
+
+### 驗證
+
+- `npm test`（`smoke.mjs` + `registry-parity.mjs` + `agent-inject.mjs` 全綠）
+- `scripts/check-repo-consistency.sh`（含 `check-cross-refs.mjs` + registry parity + source↔mirror diff + `npm pack --dry-run` + `git diff --check`）pass、0 error
+- `scripts/export-dist.sh --dry-run`：dev / dist 已同步、無 drift
+- 049–057 各 proposal 實作均經 implementation-stage cross-model review 收斂 approve（見各 closeout 紀錄）
+
+---
+
 ## 0.9.0 — 2026-05-28 — 執行當下對齊：feedback 逐欄產出、Codex trigger 注入、commit checkpoints + branch gate（含 breaking changes）
 
 **Proposals**：PROPOSAL-048（feedback 輸出對齊目標 issue 表單）、PROPOSAL-046（Codex command-trigger 注入既有 AGENTS.md shim）、PROPOSAL-047（commit checkpoints、branch lifecycle 強制、AI commit 政策翻轉、init Git policy 升必選）

package/README.en.md

@@ -4,8 +4,12 @@
 
 > **AI collaboration without DDD = accelerated chaos; with DDD = AI constrained inside the domain model upfront.**
 > A Rich Domain Model (business rules encoded into domain objects themselves, not scattered across services or prompts) puts invariants, business rules, and Aggregate boundaries inside the objects — every line of code the AI writes must pass through that contract. Dflow treats DDD as the semantic backbone of SDD.
+>
+> **Dflow doesn't teach AI what DDD is — it's a scaffold:** it forces the AI to keep a full record of the trade-offs behind each design decision and fills in the blind spots the AI tends to miss while filling in details on its own and that review can't easily catch.
+>
+> In other words: not whether the AI can do DDD, but whether you can trust it when it does.
 
-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.
+Concretely, it 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.
 
 The goal is not the process itself, but repeatable software change with clearer meaning, fewer scattered rules, and less prompt-dependent behavior.
 
@@ -20,7 +24,7 @@ The goal is not the process itself, but repeatable software change with clearer
 | **Three-layer documentation model** | Matches how feature branches actually evolve: phase (one propose-implement-archive cycle) / feature (the whole branch's running state and resume pointer) / system (cross-feature long-term knowledge). Many spec tools only ship phase + system, which breaks down when a feature branch spans multiple phases. Detailed below. |
 | **Change-depth-based tiers (T1/T2/T3)** | AI scales specification and verification by change depth: color/typo gets one inline row in `_index.md`; bug fixes get a lightweight spec plus focused verification; new features or bounded-context-level changes go through a full phase-spec plus layer-by-layer implementation planning / verification. Small changes don't get dragged down by the process. |
 | **Drift verification** | `/dflow:verify` cross-checks specs, domain documents, implementation, tests, and tech-debt records to surface the "documentation still describes the old behavior" drift that PR review by eye usually misses. |
-| **Multi-AI-tool rule sharing** | A canonical project guide plus thin tool-specific shims (`CLAUDE.md` / `AGENTS.md` / Copilot instructions) — teams switching between Claude, Codex, and Copilot don't have to maintain multiple copies of workflow rules. |
+| **Multi-AI-tool rule sharing** | A canonical project guide plus thin tool-specific shims (`CLAUDE.md` / `AGENTS.md` / Copilot instructions) — teams switching between Claude, Codex, and Copilot don't have to maintain multiple copies of workflow rules. All three also share one project-level skill built on the agentskills.io open standard, so natural language auto-triggers the matching workflow (Copilot CLI summons it via `/dflow`). |
 
 ## Get Started
 
@@ -48,44 +52,27 @@ tool, run:
 dflow configure-agents
 ```
 
-If you also want tool-native command / prompt wrappers, use the opt-in mode:
+Adding `--skills` projects a project-level skill for all three tools (Claude,
+Codex, and GitHub Copilot), restoring natural-language auto-trigger (you say "I
+want to add a feature" and the AI suggests the matching workflow; Copilot CLI
+still summons it via `/dflow`). All three support it now, so treat it as the
+recommended standard install:
 
 ```bash
-dflow configure-agents --command-adapters
+dflow configure-agents --skills
 ```
 
-This command only configures AI instruction files and optional command
-adapters. It does not rerun project initialization or touch existing specs.
-
-### Alternative: try without installing
-
-If you cannot or do not want to do a global install (no admin rights,
-ephemeral environment, or one-shot evaluation), every Dflow CLI command is
-also available through `npx`:
-
-```bash
-npx dflow-sdd-ddd init
-npx dflow-sdd-ddd doctor
-npx dflow-sdd-ddd configure-agents
-```
-
-When using this path, all commands in the same session must also use the full
-`npx dflow-sdd-ddd <subcommand>` form. The bare `dflow` alias is only
-available after a global install.
-
-### Check legacy artifacts (optional)
-
-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:
+If you also want tool-native `/` command / prompt menus, add `--command-adapters`
+(it composes with `--skills`):
 
 ```bash
-dflow doctor
+dflow configure-agents --command-adapters --skills
 ```
 
-`doctor` is a read-only health check. It never modifies files; it only
-reports findings and points at the migration guide. Freshly initialized
-projects won't have legacy artifacts and can skip this step.
+These commands (re)configure AI instruction files and refresh the
+project-vendored workflow bundle, plus optional command adapters / skills; they
+do not rerun init's interactive prompts and do not overwrite specs you authored
+yourself.
 
 ### Start using the Dflow workflow
 
@@ -107,7 +94,8 @@ behaves differently. Use these practical invocation forms:
 | Tool | Recommended invocation |
 |---|---|
 | Claude Code after `--command-adapters` | `/dflow:<id>`, for example `/dflow:new-feature` |
-| GitHub Copilot | `/dflow:<id>` as chat text; `/dflow-<id>` in the VS Code prompt menu |
+| GitHub Copilot (VS Code Chat) | Command entry is `/dflow-<id>` (hyphen, needs `--command-adapters`); natural language also auto-triggers. `/dflow:<id>` (colon) is only a text reference, not a command |
+| GitHub Copilot CLI | No per-id command; type `/dflow` to summon the skill, then describe the workflow in natural language |
 | Codex CLI | no-slash plain text `dflow:<id>`, for example `dflow:new-feature` |
 
 If your tool does not support custom slash commands, use the workflow name as
@@ -216,7 +204,9 @@ dflow/
         └── 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 also creates or updates a project instruction file for your AI coding
+agent. The exact file depends on the target tool and existing project setup;
+Dflow avoids overwriting custom content in existing project instructions.
 
 When you select AI agent setup during init, Dflow writes
 `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical project guide, then
@@ -229,14 +219,22 @@ files whose only job is to redirect the tool to the canonical guide):
 | Claude Code | `CLAUDE.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.
+If one of those files already exists, Dflow preserves custom content. A
+Dflow-generated shim is refreshed in place; another file that already points to
+`dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped. If the file does not yet
+point to the guide, Dflow shows the change in the confirmation preview and
+appends a marked `<!-- dflow-generated: agent-shim START/END -->` block at the
+end of the file; re-running refreshes that same block in place without
+duplicating it. A fallback merge snippet under `dflow/specs/shared/` is written
+only when the file contains conflicting or malformed Dflow markers. The project
+guide stays the single source of truth, so teams can use multiple AI tools
+without maintaining multiple copies of the workflow rules.
 
 You can run `dflow configure-agents` later to add more tool shims as the team
 adopts additional AI coding agents. If you need Claude / Copilot tool-native
-command entries, use `dflow configure-agents --command-adapters`.
+command entries, use `dflow configure-agents --command-adapters`. For
+natural-language auto-trigger (a project-level skill for Claude Code, Codex, and
+GitHub Copilot), use `dflow configure-agents --skills`.
 
 ### Version-Control Policy for Generated Artifacts (recommended default)
 
@@ -247,9 +245,10 @@ version-control the source, not the generated artifacts.
 
 | File | Role | Recommended default |
 |---|---|---|
-| `dflow/` (canonical guide, specs, merge snippet) | source | **version-control** |
-| Thin shims (`CLAUDE.md` / `AGENTS.md` / `.github/copilot-instructions.md`) | source | **version-control** |
+| `dflow/` (canonical guide, specs, fallback merge snippets) | source | **version-control** |
+| Thin shims or marked Dflow blocks in existing root agent files (`CLAUDE.md` / `AGENTS.md` / `.github/copilot-instructions.md`) | source | **version-control** |
 | `.claude/commands/dflow/`, `.github/prompts/dflow-*.prompt.md` | generated | **recommended: do not version-control (gitignore)**; regenerate after clone with `configure-agents --command-adapters` |
+| `.claude/skills/dflow/`, `.agents/skills/dflow/`, `.github/skills/dflow/` | generated | **recommended: do not version-control (gitignore)**; regenerate after clone with `configure-agents --skills` |
 
 This is a **recommendation**, not the only valid policy. If your team wants a
 native `/` menu immediately after clone, or your CI / dev environment does not
@@ -268,6 +267,20 @@ to avoid a registry / guide version mismatch. Per-tool `.gitignore` snippets,
 glob side effects, the `git rm --cached` switch-over step, and upgrade details
 are covered in the per-tool guides.
 
+**Caveat when upgrading an existing project**: `configure-agents` only
+re-projects the layers Dflow itself owns (the workflow bundle, command / skill
+adapters, and the marked block inside existing agent files). It does **not**
+refresh the canonical guide (`AI-AGENT-GUIDE.md`) or the other user-owned layers
+(such as `_conventions.md` or the prose outside a shim's markers) — those become
+project-owned right after init and are deliberately left untouched. The trade-off:
+when a new release adds content into the canonical guide, an existing project does
+not pick it up automatically and can silently drift from that release's canonical
+shape. After upgrading an existing project, reconcile manually and use a fresh
+comparison baseline — run a **brand-new `dflow init` with the same edition and the
+same answers** elsewhere, then diff it file-by-file against your project: every
+difference should classify as either "your user content" or "known
+outside-the-markers", otherwise it is a missed update.
+
 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/`:
@@ -352,6 +365,16 @@ Domain meaning -> Structured spec -> AI implementation -> Code as output
 
 For a longer explanation, see [Why DDD Matters More with AI](docs/why-ddd-for-ai.en.md).
 
+## Why Dflow (Even When AI Already Knows DDD)
+
+A common objection: "AI already understands DDD — tell it to *build a feature using DDD* and it will, so adding a process layer is over-engineering." That is half right — the AI can indeed state the correct DDD answer. But stating the right answer and letting you see how it got there — and check what it missed — at review are two different things. So the comparison is not "AI tool vs process" but **AI alone vs AI + scaffold**: the difference is not a smarter AI, it is a **more reviewable AI**.
+
+And Dflow's guidance is fed back from real blind spots — and once it is added, the model actually reuses it. One example: modeling on its own, the same model guarded a "only one active at a time" uniqueness rule with just an in-memory check inside the aggregate — textbook-correct, but under concurrency two requests each pass the check and break the invariant (modeling-correct, production-broken); after that blind spot was encoded as a section of Dflow guidance, re-run on a different domain, the same model proactively cited it and added DB-level protection (a unique index + a concurrency token + a 409). That is the value: Dflow turns "the blind spots AI misses on its own" into reusable guidance it actually follows.
+
+For audit-sensitive domains (medical, finance, compliance, anything where a production failure is expensive), the difference is a deal-breaker. The cost has two sides. *Producing* the DDD documents is no longer the pre-AI era of DDD by hand — the AI generates the specs, the decision record, and the domain model for you, so the marginal cost is mainly a few more tokens and running the workflow; and just being constrained by the domain model during generation already makes the output steadier (as in the concurrency blind spot above), which you get even if you never read the record closely. But cashing in the further "reviewable" value still takes a person actually reviewing that record — that is the cost in human attention and discipline. So the trade-off stands: when stakes are high, an audit is needed, or a team maintains it long-term, the investment clearly pays off; when you won't review it, the cost of failure is low, and iteration is fast, AI alone may still be the more practical choice.
+
+For the full loop (how a blind spot becomes guidance, and why the flip points to the guidance content rather than the domain or framing change), a few more "Dflow forces it on the record, AI tends to miss it on its own" observations, and the steps to verify it yourself, see [Why Dflow](docs/why-dflow.en.md).
+
 ## Repository Layout
 
 | Path | Purpose |
@@ -374,17 +397,19 @@ 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:
+npm package is `0.10.0`, covering:
 
-- Project initialization (`dflow init`)
-- Workflow documentation (the `/dflow:*` flows)
-- Multi-AI agent setup (CLAUDE.md / AGENTS.md / Copilot instructions shims)
+- Project initialization (`dflow init`) and idempotent upgrade re-projection (`dflow configure-agents`)
+- Workflow documentation (the `/dflow:*` flows) plus a workflow bundle vendored into each project
+- Multi-AI agent setup: a canonical guide plus thin per-tool shims (CLAUDE.md / AGENTS.md / Copilot instructions), with existing agent files auto-injected as a marked block (no manual merge)
+- Native project-level skills for all three tools (Claude / Codex / GitHub Copilot), sharing the agentskills.io open standard with natural-language auto-trigger (Copilot CLI still summons via `/dflow`)
+- Optional tool-native command entries (`--command-adapters`) and an auto-trigger skill (`--skills`)
 - AI-agent-readable SDD/DDD guidance
-- Public migration tooling: manual migration guide plus `dflow doctor` read-only health check
-- Public onboarding: evaluator guide and per-tool walkthroughs for Claude Code and Codex CLI
+- `dflow doctor` read-only project health check
+- Public onboarding: evaluator guide and per-tool walkthroughs for Claude Code, Codex CLI, and GitHub Copilot
 - A verification-only CI workflow (it does not execute publish)
 
-The GitHub source may include post-`0.2.0` repository changes before the
+The GitHub source may include post-`0.10.0` repository changes before the
 next npm release is published. See [CHANGELOG.md](CHANGELOG.md) for full
 release history.
 

package/README.md

@@ -4,8 +4,12 @@
 
 > **AI 協作沒 DDD = 加速混亂；有 DDD = 把 AI 事先約束在領域模型內。**
 > Rich Domain Model（業務規則寫在領域物件本身、而非散在 service 或 prompt 裡）把不變條件、業務規則、Aggregate 邊界編碼進物件 — AI 寫的程式碼必須穿過這個契約。Dflow 把 DDD 當成 SDD 的語意骨幹。
+>
+> **Dflow 不是教 AI 什麼是 DDD——它是一層 scaffold（鷹架）：** 強迫 AI 把每個設計決策的取捨完整留檔，並補上「AI 自己補細節時容易漏、而 review 又難一眼看出」的盲區。
+>
+> 換句話說，不是「AI 會不會 DDD」，而是「AI 做 DDD 時，你能不能信他」。
 
-Dflow 是一套 spec-first 的工作流程工具集，專為 AI 輔助軟體開發設計。它為你的 AI 程式設計助理提供具體流程，把變更需求轉成結構化規格、領域語言、實作計畫、漂移檢查、與可審查的程式碼，而不是從 prompt 直接跳到程式碼。
+具體來說，它是一套 spec-first 的工作流程工具集，專為 AI 輔助軟體開發設計。它為你的 AI 程式設計助理提供具體流程，把變更需求轉成結構化規格、領域語言、實作計畫、漂移檢查、與可審查的程式碼，而不是從 prompt 直接跳到程式碼。
 
 目標不是流程本身，而是讓軟體變更可重複、語意更清楚、規則更不散落、行為更不依賴 prompt。
 
@@ -20,7 +24,7 @@ Dflow 是一套 spec-first 的工作流程工具集，專為 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` / Copilot instructions），團隊在 Claude / Codex / Copilot 之間切換時不必維護多份 workflow 規則。 |
+| **多 AI 工具共用一份規則** | Canonical 專案指南 + 各工具薄 shim（`CLAUDE.md` / `AGENTS.md` / Copilot instructions），團隊在 Claude / Codex / Copilot 之間切換時不必維護多份 workflow 規則。三家還共用一份依 agentskills.io 開放標準的 project-level skill，可用自然語言自動觸發對應 workflow（Copilot CLI 需先打 `/dflow` 喚起）。 |
 
 ## 開始使用
 
@@ -41,35 +45,19 @@ init 流程會詢問是 greenfield 或 brownfield、團隊採用的 Git policy
 dflow configure-agents
 ```
 
-若想同時建立工具原生的命令 / prompt wrapper，使用 opt-in 模式：
+加上 `--skills` 會為 Claude / Codex / GitHub Copilot 三家投影 project-level skill，找回自然語言自動觸發（你描述「我要加一個功能」，AI 就主動建議對應 workflow；Copilot CLI 仍需先打 `/dflow` 喚起）。三家現在都支援，建議當成標準安裝：
 
 ```bash
-dflow configure-agents --command-adapters
+dflow configure-agents --skills
 ```
 
-此指令只設定 AI 指示檔與選配 command adapters，不會重跑專案初始化，也不會動到既有 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（選用）
-
-要檢查專案內是否仍有 legacy 或 pre-V1 artifacts（如根目錄的 `specs/` 或舊版的 `_共用/`），執行：
+若還想要工具原生的 `/` 命令 / prompt 選單，再加 `--command-adapters`（可與 `--skills` 並用）：
 
 ```bash
-dflow doctor
+dflow configure-agents --command-adapters --skills
 ```
 
-`doctor` 是唯讀健康檢查；不會修改任何檔案，只報告找到的問題並指向 migration guide。剛 init 的新專案不會有 legacy artifacts、可跳過此步驟。
+這些指令會（重新）設定 AI 指示檔、刷新隨專案 vendored 的 workflow bundle，並選配 command adapters / skills；它們不會重跑 init 的互動問答，也不會覆寫你自己撰寫的 specs。
 
 ### 開始使用 Dflow workflow
 
@@ -90,7 +78,8 @@ dflow doctor
 | 工具 | 建議叫法 |
 |---|---|
 | Claude Code（安裝 `--command-adapters` 後） | `/dflow:<id>`，例如 `/dflow:new-feature` |
-| GitHub Copilot | chat 文字可用 `/dflow:<id>`；VS Code prompt 選單使用 `/dflow-<id>` |
+| GitHub Copilot（VS Code Chat） | 命令入口用 `/dflow-<id>`（連字號，需 `--command-adapters`）；也可自然語言自動觸發。`/dflow:<id>`（冒號）僅當文字稱呼、非命令 |
+| GitHub Copilot CLI | 沒有 per-id 命令；先打 `/dflow` 喚起 skill，再用自然語言描述 workflow |
 | Codex CLI | 不帶斜線的純文字 `dflow:<id>`，例如 `dflow:new-feature` |
 
 若你的工具不支援自訂 slash command，把 workflow 名稱當成普通對話訊息輸入即可。Dflow 是 Markdown-based 的 workflow 材料加一個 scaffolding CLI，能與任何可讀專案指示與 repo 上下文的 AI 程式設計助理一起運作。
@@ -190,7 +179,7 @@ dflow/
         └── completed/
 ```
 
-Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指示檔；確切檔名取決於目標工具與既有專案設定。Dflow 不覆寫既有專案指示。
+Dflow 也會為你的 AI 程式設計助理建立或更新專案指示檔；確切檔名取決於目標工具與既有專案設定。Dflow 不覆寫既有專案指示中的自訂內容。
 
 選擇 AI agent 設定時，Dflow 把 `dflow/specs/shared/AI-AGENT-GUIDE.md` 作為 canonical 專案指南，並為每個 AI 工具建立**小型的指向檔**（俗稱 shim，內容很短，只是把該工具引導去讀 canonical 指南）：
 
@@ -200,9 +189,15 @@ Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指
 | Claude Code | `CLAUDE.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
-若這些檔案已存在，Dflow 不會覆蓋，改寫 merge snippet 到 `dflow/specs/shared/`。專案指南保持單一 source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow 規則。
+若這些檔案已存在，Dflow 不會覆蓋自訂內容；已是 Dflow-generated shim 的檔案
+會原地刷新，其他已指向 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會略過。
+若檔案尚未指向 guide，預設會在確認 preview 顯示並於檔案末尾附加帶有
+`<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block，重跑會
+原地更新同一段且不重複。只有檔案內有衝突或 malformed Dflow markers 時，
+才會改寫 fallback merge snippet 到 `dflow/specs/shared/`。專案指南保持單一
+source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow 規則。
 
-之後團隊採用新 AI 程式設計助理時，可隨時跑 `dflow configure-agents` 新增 shim；若需要 Claude / Copilot 的工具原生命令入口，改用 `dflow configure-agents --command-adapters`。
+之後團隊採用新 AI 程式設計助理時，可隨時跑 `dflow configure-agents` 新增 shim；若需要 Claude / Copilot 的工具原生命令入口，改用 `dflow configure-agents --command-adapters`；若要自然語言自動觸發（為 Claude Code、Codex 與 GitHub Copilot 投影專案層 skill），改用 `dflow configure-agents --skills`。
 
 ### 產生物的版控政策（建議預設）
 
@@ -210,14 +205,17 @@ Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指
 
 | 檔案 | 角色 | 建議預設 |
 |---|---|---|
-| `dflow/`（canonical guide、規格、merge snippet） | source | **版控** |
-| 薄 shim（`CLAUDE.md` / `AGENTS.md` / `.github/copilot-instructions.md`） | source | **版控** |
+| `dflow/`（canonical guide、規格、fallback merge snippet） | source | **版控** |
+| 薄 shim 或既有 root agent 檔案中的 marked Dflow block（`CLAUDE.md` / `AGENTS.md` / `.github/copilot-instructions.md`） | source | **版控** |
 | `.claude/commands/dflow/`、`.github/prompts/dflow-*.prompt.md` | 衍生物 | **建議不版控（gitignore）**，clone 後重跑 `configure-agents --command-adapters` 重生成 |
+| `.claude/skills/dflow/`、`.agents/skills/dflow/`、`.github/skills/dflow/` | 衍生物 | **建議不版控（gitignore）**，clone 後重跑 `configure-agents --skills` 重生成 |
 
 這是**建議**，不是唯一正解。若團隊希望 clone 後立即有原生 `/` 選單、或 CI / 開發環境不裝 npm，**版控 adapter** 也是合理選擇——代價是升級若改了命名，要重投影並 commit 刪除舊檔。關鍵原則：**同一專案對所有工具採一致策略**，別像常見的踩雷一樣一邊 ignore、一邊版控。
 
 升級 dflow 後重跑 `dflow configure-agents --command-adapters`，adapter 會用**新版的 command registry** 重投影；但**不會**覆寫已存在的 `dflow/specs/shared/AI-AGENT-GUIDE.md`（canonical guide 已存在則保留）。「重投影 adapter」與「升級 canonical guide」是兩件事；升級時請用**相同的 dflow CLI 版本**重投影，避免 registry 與 guide 版本錯位。各工具的 `.gitignore` 片段、glob 副作用、`git rm --cached` 切換步驟與升級細節見 per-tool 指南。
 
+**升級既有專案的 caveat**：`configure-agents` 只重投影 Dflow 自己擁有的自動層（workflow bundle、command / skill adapters，以及既有 agent 檔內帶 marker 的區塊）。它**不會**刷新 canonical 指南（`AI-AGENT-GUIDE.md`）與其他 user-owned 層（如 `_conventions.md`、shim marker 以外的文字）——這些檔在 init 後即歸專案所有、刻意不被覆寫。代價是：當新版把內容加進 canonical 指南時，既有專案不會自動拿到，可能與該版的 canonical 形狀 silent drift。升級既有專案後，建議手動 reconcile，並以「在別處跑一個**同 edition、同答案的全新 `dflow init`**、再與你的專案逐檔 diff」當驗證基準：每個差異都應能歸類為「你的 user content」或「已知 marker 以外」，否則就是漏修。
+
 特定工具的 init 寫入內容與 Dflow workflow 命令呈現方式，見 `docs/` 內的 per-tool 指南：
 
 - [在 Claude Code 中使用 Dflow](docs/using-with-claude-code.md)
@@ -297,6 +295,16 @@ Dflow 把 DDD 當成規格背後的語意結構：ubiquitous language 讓命名
 
 更詳細的說明見 [為什麼 AI 時代 DDD 更重要](docs/why-ddd-for-ai.md)。
 
+## 為什麼用 Dflow（即使 AI 已經會 DDD）
+
+常見的質疑是：「現在的 AI 已經懂 DDD，叫它『用 DDD 建一個 feature』它就會做，再加一層 process 是過度工程。」這句話對了一半——AI 確實能說出對的 DDD 答案。但「能說出對的答案」和「在 review 時看得到它怎麼想、查得出它有沒有漏」是兩回事。所以該比的不是「AI 工具 vs process」，而是 **AI alone vs AI + scaffold**：差別不是更聰明的 AI，是**更可審查的 AI**。
+
+而且 Dflow 的引導是從真實盲區回灌的、補上後模型真的會沿用。一個實例：模型自己建模時，把「同時只能有一筆 active」這類唯一性規則只用 aggregate 內的 in-memory check 保護——教科書上對、但並發下兩個請求會各自通過檢查、破壞不變式（modeling-correct、production-broken）；把這個盲區寫成一段引導補進 Dflow 後，換一個 domain 重跑，同一個模型就主動引用它、補上 DB 層保護（unique index + concurrency token + 409）。Dflow 的價值就在這：把「AI 自己會漏的盲區」固化成可重用、會被遵循的引導。
+
+對需要 audit 的領域（醫療、金融、合規、任何「上線出包代價高」的場景），這個差異是 deal-breaker。成本要分兩塊看：**產出** DDD 文件已經不是徒手做 DDD 的年代——AI 幫你生規格、決策紀錄與領域模型，邊際成本主要是多花一些 token 與走一遍流程；而且光是「生成時被領域模型約束」就已讓產出更穩（如前面那個並發盲區），這部分就算你沒深讀紀錄也拿得到。但要再兌現「可審查」這份價值，得有人實際去 review 那份紀錄——那才是人力與紀律的成本。所以取捨仍在：高風險、需 audit、要長期維護時，這筆投資明顯划算；你不會去 review、失敗成本低、迭代又快時，AI alone 仍可能更實際。
+
+完整的迴路（盲區怎麼變成引導、為什麼這歸到引導內容而非 domain / framing 的差異）、其他幾個「Dflow 強制留檔、AI 自己容易漏」的觀察，以及自己動手驗證的步驟，見 [為什麼用 Dflow](docs/why-dflow.md)。
+
 ## Repo 結構
 
 | 路徑 | 用途 |
@@ -314,17 +322,19 @@ issue 與 pull request 指引見 [CONTRIBUTING.md](CONTRIBUTING.md)。Pull reque
 
 ## 狀態
 
-Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.2.0`，涵蓋：
+Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.10.0`，涵蓋：
 
-- 專案初始化（`dflow init`）
-- Workflow 文件（`/dflow:*` 流程）
-- 多 AI agent 設定（CLAUDE.md / AGENTS.md / Copilot instructions shim）
+- 專案初始化（`dflow init`）與 idempotent 升級重投影（`dflow configure-agents`）
+- Workflow 文件（`/dflow:*` 流程）＋隨專案 vendored 的 workflow bundle
+- 多 AI agent 設定：canonical 指南 + 各工具薄 shim（CLAUDE.md / AGENTS.md / Copilot instructions）；既有 agent 檔以帶 marker 的區塊自動注入、零手動合併
+- 三家原生 project-level skill（Claude / Codex / GitHub Copilot），共用 agentskills.io 開放標準、支援自然語言自動觸發（Copilot CLI 仍需先打 `/dflow` 喚起）
+- 選配工具原生命令入口（`--command-adapters`）與自動觸發 skill（`--skills`）
 - AI agent 可讀的 SDD/DDD 指引
-- 公開 migration tooling：手動 migration guide 與 `dflow doctor` 唯讀健康檢查
-- 公開 onboarding：evaluator 指南、Claude Code / Codex CLI 的 per-tool walkthrough
+- `dflow doctor` 唯讀專案健康檢查
+- 公開 onboarding：evaluator 指南，Claude Code / Codex CLI / GitHub Copilot 的 per-tool walkthrough
 - 僅驗證的 CI workflow（不執行 publish）
 
-GitHub 上的 source 可能包含 `0.2.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
+GitHub 上的 source 可能包含 `0.10.0` 之後尚未發佈的 repo 變更。完整 release history 見 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 授權
 

package/TEMPLATE-COVERAGE.md

@@ -25,7 +25,6 @@ The matrix lists Brownfield / Greenfield logical template parity so reviewers ca
 | 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`, `.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
 

package/TEMPLATE-LANGUAGE-GLOSSARY.md

@@ -32,6 +32,7 @@ The "使用位置" column refers to file paths where the term appears structural
 | 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 等模型索引 |
+| Subdomain Type | 子領域類型 | `context-map.md` | 標記 BC 為 core / supporting / generic,決定建模深度（Subdomain-Aware Modeling Depth）；不降低 BR / Tier / 安全測試要求 |
 | 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 |

package/bin/dflow.js

@@ -11,7 +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 doctor            Read-only project health check
   dflow --help            Show this help
   dflow --version         Show the CLI version
 `);
@@ -22,9 +22,9 @@ function printInitHelp() {
   dflow init
 
 Initializes Dflow project specs under dflow/specs/.
-The command prompts for project type, tech stack, prose language, Git policy,
-AI commit marker, optional starter files, and AI coding agents before showing a
-full file preview.
+The command prompts for project type, tech stack, migration context, prose
+language, Git policy, AI commit marker, optional starter files, and AI coding
+agents before showing a full file preview.
 `);
 }
 
@@ -39,7 +39,7 @@ dflow/specs/shared/AI-AGENT-GUIDE.md file.
 
 Options:
   --command-adapters  Also generate tool-native thin wrappers for supported tools.
-  --skills            Also generate a supported tool's skill adapter (currently Claude Code project skill, restores natural-language auto-trigger).
+  --skills            Also generate project-level skill adapters for supported tools (Claude Code, Codex, and GitHub Copilot), restoring natural-language auto-trigger.
 `);
 }
 
@@ -47,16 +47,12 @@ 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:
+Read-only health check for the current project. Reports findings such as:
 
-  - 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.
+Doctor never modifies files.
 `);
 }
 

package/docs/evaluating-dflow.en.md

@@ -42,15 +42,18 @@ in your project's `dflow/specs/` directory and AI instruction files.
   completion checklists, templates). This bundle is projected from the npm
   package at init time so workflows are reachable from any clone without
   needing the Dflow source or package installed locally.
-- Mergeable AI agent instruction files for the tools you select (e.g.,
-  `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`). Each is a
-  thin pointer to the canonical guide and workflow bundle.
+- AI agent instruction files, or marked Dflow blocks inside existing files, for
+  the tools you select (e.g., `CLAUDE.md`, `AGENTS.md`,
+  `.github/copilot-instructions.md`). Each points the tool to the canonical
+  guide and workflow bundle.
 
 `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.
+- Overwrite custom content in existing AI agent instruction files; if one
+  exists, Dflow refreshes Dflow-generated shims, leaves a file that already
+  points to the guide as-is, shows and appends a marked Dflow block by default
+  otherwise, and writes a fallback merge snippet only on marker conflicts.
 - Modify your build system, package manager, or dependencies.
 - Send any data anywhere; it is a local scaffolding command.
 
@@ -177,8 +180,9 @@ 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.
+- If an existing project instruction file (e.g., a pre-existing `CLAUDE.md`)
+  received a marked Dflow block, remove that block to revert it; later
+  `init` / `configure-agents` runs will append it again.
 
 This means an evaluation pass leaves no permanent footprint if you decide
 not to adopt.