dflow-sdd-ddd 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,71 @@
 
 ---
 
+## 0.8.0 — 2026-05-24 — DDD set-based invariant 引導擴充、雙軌 skill 殼合一、user-projected bundle 內容 polish
+
+**Proposals**：PROPOSAL-040（CLI papercuts + 文件補洞）、PROPOSAL-041（C0+C1：configure-agents idempotent bundle re-projection + 雙軌 skill 殼合一）、PROPOSAL-042（ddd-modeling-guide 補 set-based invariants 與 Phase-1 event dispatch 段）、PROPOSAL-044（user-projected bundle 內 maintainer-source path 清除）、PROPOSAL-045（user-projected bundle 內 maintainer-only provenance refs 清除）
+
+**新功能 / 新引導內容**：
+
+- **ddd-modeling-guide 補「Set-Based / Uniqueness Invariants」段**（PROPOSAL-042）：明確說明 set-based invariants（「同 X 只能一筆 active」「email 跨 User 唯一」這類）**無論選哪種 aggregate 邊界**，in-memory check 在並發下都不夠保護，需 DB unique / partial index 或 optimistic concurrency token 配合。涵蓋兩種常見 aggregate 切法（拆獨立 + folded 為 child entity）的對策；指出 child entity 寫入需 bump root version；建議將並發衝突 translate 為業務語意 conflict（HTTP 409）。同 update 補 Common Mistakes #6 與 Phase-1 event dispatch lifecycle 段落。
+
+**行為改善**：
+
+- **`configure-agents` 自動補回 bundle**（PROPOSAL-041 C0）：對 pre-039 既有專案再次跑 `configure-agents` 時，自動 re-project 缺失的 `dflow/specs/shared/dflow-workflows/` bundle（idempotent；第二次跑為 no-op）。順手關閉 PROPOSAL-039 follow-up (i)。
+- **雙軌 skill 殼合一**（PROPOSAL-041 C1）：兩份 `sdd-ddd-{green,brown}field-skill/SKILL.md` 統一為 `templates/common/skill/SKILL.md` thin shell；`lib/init.js` 從該檔讀。對 npm 使用者只是裝起來行為一致，無破壞性變更；對 maintainer 是 source-of-truth 收斂。
+- **CLI papercuts 批次修**（PROPOSAL-040 group A）：`init` / `configure-agents` 數個 CLI 摩擦點修補（issues #2/#11/#12）。
+- **`init` 後續 step 文件補洞**（PROPOSAL-040 group B）：slug 命名加 CI 相容性 caveat、`behavior.md` skeleton 註解明確（避免 user 以為 finish-feature 前就該填）、`configure-agents` 自動偵測既有 agent 配置（#13/#7）、`aggregate-design.md` 在 feature 目錄內的存放位置明文釘住。
+
+**文件 / user-facing 內容 polish**：
+
+- **user-projected bundle 內 `sdd-ddd-*-skill/` maintainer-source path 清除**（PROPOSAL-044）：原本 `npm install` 後 user project 內的 flow / template 文件含 `sdd-ddd-greenfield-skill/scaffolding/...` 這類在 user 端不存在的路徑引用——user 讀到會誤判「我裝錯了？」。本 release 把該類引用全部清為 user 端可解析路徑或自足語句。涵蓋 12 個 source + 12 個 mirror。
+- **user-projected bundle 內 maintainer-only provenance refs 清除**（PROPOSAL-045）：原本 user 端會看到的 `<!-- ... PROPOSAL-013 ... -->` HTML 註解、`init-project-flow.md` 末段 `archive/reviews/...` 引用、references body 內 bare `PROPOSAL-NNN` 引用、brownfield `CLAUDE-md-snippet.md` 內 `(established in PROPOSAL-007c)` 標註等——這些是 maintainer-only 歷史佔位、user 看到只會困惑。本 release 全部清除或改寫為自足語句；HTML 註解保留為 `<!-- Seeded by Dflow. -->`（語意精準：user 取到檔後可自行客製化、dflow 並不持續維護該副本）。涵蓋 66 個 unique files。
+
+**維護者工具**（不影響套件使用者）：
+
+- **`scripts/check-repo-consistency.sh` 新增 045 guard**：scoped git grep 對 `sdd-ddd-*-skill/{templates,scaffolding,references}/*.md` + `templates/{green,brown}field/**/*.md` 偵測 `(archive/|planning/|reviews/|proposals/|PROPOSAL-[0-9]{3})` 任一命中即 fail——防未來再引入 maintainer-only provenance refs。Pre-commit hook 不加。
+
+---
+
+## 0.7.0 — 2026-05-22 — Opt-in Claude skill adapter、自動清理舊 command adapter、發布前 lifecycle 機檢
+
+**Proposals**：PROPOSAL-037（generated adapter commit 政策與升級流程）、PROPOSAL-038（選配 skill adapter）、PROPOSAL-035（lifecycle drift forcing-functions）
+
+**新功能**：
+
+- **`dflow configure-agents --skills`**（PROPOSAL-038）：在已初始化的專案投影一個
+  edition-neutral 的「thin」skill 到 `.claude/skills/dflow/SKILL.md`，指向專案內既有
+  guide（不打包 SKILL.md 模板）。auto-trigger 描述刻意收窄，採 suggest-and-wait
+  契約；wrapper 帶 `<!-- dflow-generated: skill-adapter -->` 供覆寫保護。`--skills`
+  在未鎖定 Claude 時 warn 並 no-op。Claude skill 與 command adapter（`dflow:<id>`）
+  名稱不衝突，可共存（已於 real Claude Code 實測）。Codex 維持 AGENTS.md 文字觸發，
+  不提供 user-level skill。
+
+**行為改善**：
+
+- **`init` 自動移除前一版 stale command adapter**（PROPOSAL-037 Segment B）：透過既有
+  plan / preview / confirm pipeline，依明確的 `LEGACY_COMMAND_ADAPTERS` 表（目前僅
+  v0.5.0）與 CRLF-normalized 精確指紋比對，apply 時再次 re-check；對使用者改過或
+  非 Dflow 產生的檔案 warn-but-keep，絕不使用 glob。**這把 0.6.0 需手動刪除舊
+  `.claude/commands/dflow/dflow-*.md` 的遷移步驟自動化了**。新生成的 wrapper 帶
+  `<!-- dflow-generated: command-adapter -->`。
+
+**文件**：
+
+- **generated adapter 的版控政策**（PROPOSAL-037 Segment A）：README（zh + en）與各工具
+  guide 補上建議預設（gitignore + 重新生成）與「追蹤 adapter」的替代做法、條件式
+  `.gitignore` 片段與 glob 注意事項、`git rm --cached` 指引，並區分 adapter-refresh
+  與 canonical-guide-migration、加入 CLI 版本 pinning 說明。
+
+**維護者工具**（不影響套件使用者）：
+
+- **lifecycle drift 機檢**（PROPOSAL-035）：新增 `scripts/check-lifecycle.mjs`（dev-only，
+  不隨套件發布），硬斷言「`proposals/` 內無 terminal-status proposal」與「`archive/proposals/`
+  內皆為 terminal status」，並對引用已歸檔 proposal 的 active handoff 發出 warning；
+  接入 CI 與 npm 發布前 checklist。
+
+---
+
 ## 0.6.0 — 2026-05-21 — Command-adapter 命名修正
 
 **Proposals**：PROPOSAL-036（修正 command-adapter 命名 + 各工具叫用現實對齊）

package/README.en.md

@@ -237,6 +237,36 @@ 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`.
 
+### Version-Control Policy for Generated Artifacts (recommended default)
+
+The command / prompt wrappers produced by `dflow configure-agents
+--command-adapters` are **generated artifacts** projected from the canonical
+guide. Dflow's **recommended default** is to treat them as regenerable output:
+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** |
+| `.claude/commands/dflow/`, `.github/prompts/dflow-*.prompt.md` | generated | **recommended: do not version-control (gitignore)**; regenerate after clone with `configure-agents --command-adapters` |
+
+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
+install npm, **version-controlling the adapters** is a reasonable choice — the
+trade-off is that when an upgrade renames commands you must re-project and
+commit the removal of the old files. The key rule: **use one consistent policy
+across all tools in a project**, rather than ignoring adapters for one tool and
+tracking them for another.
+
+After upgrading Dflow, re-running `dflow configure-agents --command-adapters`
+re-projects adapters from the **new command registry**, but it does **not**
+overwrite an existing `dflow/specs/shared/AI-AGENT-GUIDE.md` (an existing
+canonical guide is kept). "Re-projecting adapters" and "migrating the canonical
+guide" are two different things; re-project with the **same dflow CLI version**
+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.
+
 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/`:

package/README.md

@@ -204,6 +204,20 @@ Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指
 
 之後團隊採用新 AI 程式設計助理時，可隨時跑 `dflow configure-agents` 新增 shim；若需要 Claude / Copilot 的工具原生命令入口，改用 `dflow configure-agents --command-adapters`。
 
+### 產生物的版控政策（建議預設）
+
+`dflow configure-agents --command-adapters` 產生的命令 / prompt wrapper 是從 canonical guide 投影出來的**衍生物（generated artifact）**。Dflow 的**建議預設**是把它們當成可重生成的產物：版控 source、不版控衍生物。
+
+| 檔案 | 角色 | 建議預設 |
+|---|---|---|
+| `dflow/`（canonical guide、規格、merge snippet） | source | **版控** |
+| 薄 shim（`CLAUDE.md` / `AGENTS.md` / `.github/copilot-instructions.md`） | source | **版控** |
+| `.claude/commands/dflow/`、`.github/prompts/dflow-*.prompt.md` | 衍生物 | **建議不版控（gitignore）**，clone 後重跑 `configure-agents --command-adapters` 重生成 |
+
+這是**建議**，不是唯一正解。若團隊希望 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 指南。
+
 特定工具的 init 寫入內容與 Dflow workflow 命令呈現方式，見 `docs/` 內的 per-tool 指南：
 
 - [在 Claude Code 中使用 Dflow](docs/using-with-claude-code.md)

package/bin/dflow.js

@@ -29,7 +29,7 @@ optional starter files, and AI coding agents before showing a full file preview.
 
 function printConfigureAgentsHelp() {
   process.stdout.write(`Usage:
-  dflow configure-agents [--command-adapters]
+  dflow configure-agents [--command-adapters] [--skills]
 
 Adds AI agent instruction files to an existing Dflow project.
 The command can create AGENTS.md, CLAUDE.md, and
@@ -38,6 +38,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).
 `);
 }
 
@@ -95,7 +96,9 @@ async function main() {
     }
 
     const configureOptions = args.slice(1);
-    const unsupportedConfigureOptions = configureOptions.filter((arg) => arg !== '--command-adapters');
+    const unsupportedConfigureOptions = configureOptions.filter(
+      (arg) => arg !== '--command-adapters' && arg !== '--skills'
+    );
     if (unsupportedConfigureOptions.length > 0) {
       process.stderr.write(`Unsupported configure-agents option: ${unsupportedConfigureOptions.join(' ')}\n`);
       return 1;
@@ -106,7 +109,8 @@ async function main() {
       stdin: process.stdin,
       stdout: process.stdout,
       stderr: process.stderr,
-      commandAdapters: configureOptions.includes('--command-adapters')
+      commandAdapters: configureOptions.includes('--command-adapters'),
+      skills: configureOptions.includes('--skills')
     });
   }
 

package/docs/evaluating-dflow.en.md

@@ -35,10 +35,16 @@ in your project's `dflow/specs/` directory and AI instruction files.
   map, architecture/tech-debt, features active/completed). See
   [`README.md` "Files Created by Init"](../README.en.md#files-created-by-init)
   for the full tree.
-- A canonical project guide at `dflow/specs/shared/AI-AGENT-GUIDE.md`.
+- A canonical project guide at `dflow/specs/shared/AI-AGENT-GUIDE.md` —
+  the command registry, routing rules, and project context.
+- A vendored workflow bundle at `dflow/specs/shared/dflow-workflows/` —
+  the executable step definitions for each `/dflow:*` workflow (step gates,
+  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.
+  thin pointer to the canonical guide and workflow bundle.
 
 `init` does **not**:
 
@@ -60,7 +66,9 @@ or more tools and Dflow writes the corresponding shim:
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
 Each shim points back to the canonical
-`dflow/specs/shared/AI-AGENT-GUIDE.md`. Practical implications:
+`dflow/specs/shared/AI-AGENT-GUIDE.md`. The guide acts as the command registry
+and router; executable workflow steps live in the vendored bundle at
+`dflow/specs/shared/dflow-workflows/`. Practical implications:
 
 - Multiple tools can be active in the same project without diverging
   workflow rules.
@@ -68,8 +76,9 @@ Each shim points back to the canonical
   `dflow configure-agents` to add another shim, or
   `dflow configure-agents --command-adapters` to opt in to tool-native command
   entries.
-- The project guide stays the single source of truth for Dflow workflow
-  behavior.
+- The guide and workflow bundle together are the authoritative sources for
+  Dflow workflow behavior; both are plain Markdown committed in your repo and
+  accessible to any clone.
 
 `/dflow:*` is the canonical shared vocabulary, but each tool's `/` parser
 behaves differently: Claude Code command adapters use `/dflow:<id>`, the

package/docs/evaluating-dflow.md

@@ -25,8 +25,14 @@ Dflow 是 Markdown-based 的 workflow 材料加上一個 scaffolding CLI。它
 
 - `dflow/specs/` workspace（概覽、慣例、領域詞彙表、context map、架構 / 技術債、功能 active/completed）。完整目錄樹見
   [`README.md` "Init 產生的檔案"](../README.md#init-產生的檔案)。
-- 位於 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的 canonical 專案指南。
-- 你所選工具的可合併 AI 指示檔（例如 `CLAUDE.md`、`AGENTS.md`、`.github/copilot-instructions.md`）。每個都是指向 canonical 指南的薄 shim。
+- 位於 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的 canonical 專案指南 ——
+  命令登錄表、路由規則與專案上下文。
+- 位於 `dflow/specs/shared/dflow-workflows/` 的 vendored workflow bundle ——
+  各 `/dflow:*` workflow 的可執行步驟定義（step gates、completion checklists、模板）。
+  這個 bundle 在 init 時從 npm 套件投影進專案，因此 workflow 步驟是 self-contained
+  且可達的，任何 clone 都不需要 Dflow source 或 package 在本機安裝。
+- 你所選工具的可合併 AI 指示檔（例如 `CLAUDE.md`、`AGENTS.md`、`.github/copilot-instructions.md`）。
+  每個都是指向 canonical 指南與 workflow bundle 的薄 shim。
 
 `init` **不會**：
 
@@ -45,11 +51,14 @@ Dflow 支援多種 AI 程式設計助理。跑完 `init` 後，你選取一個
 | Claude Code | `CLAUDE.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
-每個 shim 都指向 canonical 的 `dflow/specs/shared/AI-AGENT-GUIDE.md`。實際意義：
+每個 shim 都指向 canonical 的 `dflow/specs/shared/AI-AGENT-GUIDE.md`（命令登錄表）
+與 `dflow/specs/shared/dflow-workflows/`（可執行步驟定義）。實際意義：
 
 - 同一個專案可以同時啟用多個工具，而不會有 workflow 規則分歧。
-- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim，或用 `dflow configure-agents --command-adapters` opt in 工具原生命令入口。
-- 專案指南始終保持為 Dflow workflow 行為的單一 source of truth。
+- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim，
+  或用 `dflow configure-agents --command-adapters` opt in 工具原生命令入口。
+- 指南與 workflow bundle 共同成為 Dflow workflow 行為的權威來源；兩者都是純 Markdown
+  已 commit 進 repo，任何 clone 均可直接讀取。
 
 `/dflow:*` 是 canonical 共同詞彙，但各工具的 `/` parser 行為不同：Claude Code
 command adapters 使用 `/dflow:<id>`，GitHub Copilot prompt 選單使用

package/docs/npm-publish-checklist.md

@@ -13,6 +13,14 @@ Replace `<version>` with the version being published, for example `0.1.2`.
 - [ ] Confirm `README.md` installation instructions match the release.
 - [ ] Confirm Greenfield and Brownfield common flow changes are synchronized.
 - [ ] Confirm generated templates match skill source where applicable.
+- [ ] Run the lifecycle check in the development repo and confirm it is green,
+      so every proposal this release covers is terminal (`implemented` /
+      `rejected` / `superseded`) and already archived:
+
+```bash
+node scripts/check-lifecycle.mjs
+```
+
 - [ ] Run:
 
 ```bash

package/docs/using-with-claude-code.en.md

@@ -68,11 +68,15 @@ Two things happen when Claude Code starts in this project:
    Code's Markdown import syntax to inline the canonical Dflow guide. So
    Claude Code effectively reads both files as one set of instructions.
 
-The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is where the
-real workflow rules live: project context (track, tech stack, prose
+The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the
+**command registry and router**: project context (track, tech stack, prose
 language), the `/dflow:*` workflow table, source-of-truth file paths, and
-core SDD/DDD rules. The `CLAUDE.md` shim stays small precisely so the
-canonical guide can evolve without Claude-Code-specific edits.
+core SDD/DDD rules. The executable workflow steps (Step 1→N, step gates,
+completion checklists) live in the **vendored workflow bundle** that `init`
+projects into `dflow/specs/shared/dflow-workflows/`. Both are plain Markdown
+checked into your repo, so they travel with the project when cloned. The
+`CLAUDE.md` shim stays small precisely so the canonical guide can evolve
+without Claude-Code-specific edits.
 
 If a `CLAUDE.md` already existed in the project, `init` does not overwrite
 it. Instead it writes a merge snippet under `dflow/specs/shared/` that you
@@ -112,9 +116,11 @@ dflow/specs/features/active/. Before I do, I need a short answer on:
 The workflow then walks you through spec drafting, behavior examples,
 implementation planning, and finish-feature drift checks. The exact
 sequence depends on which workflow you entered (`/dflow:new-feature`,
-`/dflow:modify-existing`, `/dflow:bug-fix`, etc.). All workflow definitions
-live under the Dflow skill source; Claude Code follows them by reading the
-skill files when needed.
+`/dflow:modify-existing`, `/dflow:bug-fix`, etc.). The executable step
+definitions (Step 1→N, step gates, completion checklists) are in the
+vendored workflow bundle at `dflow/specs/shared/dflow-workflows/`; `init`
+projects this bundle into every initialized project so the workflow steps
+are self-contained and reachable without any external source dependency.
 
 Available workflow entry points:
 
@@ -156,10 +162,111 @@ These wrappers use Claude Code's directory namespace names, for example
 `/dflow:new-feature`. Their body only points to the canonical
 `/dflow:new-feature` workflow and `dflow/specs/shared/AI-AGENT-GUIDE.md`; it
 does not copy workflow steps. Projects upgraded from Dflow 0.5.0 may still
-have old `.claude/commands/dflow/dflow-*.md` files. Dflow does not delete user
-files automatically; remove those old wrappers manually so Claude Code does
-not show both the old `/dflow:dflow-<id>` names and the new `/dflow:<id>`
-names.
+have old `.claude/commands/dflow/dflow-*.md` files, which make Claude Code show
+both the old `/dflow:dflow-<id>` names and the new `/dflow:<id>` names. When you
+re-run `dflow configure-agents --command-adapters`, Dflow **automatically
+detects and removes** these 0.5.0-generated stale wrappers: the files to remove
+are listed in the confirmation preview (marked `remove`) and deleted only after
+you confirm. Dflow removes only files whose content **exactly matches** the
+0.5.0 generated output; if you have edited the file, or it is one you placed in
+the same namespace yourself, Dflow leaves it in place and prints a warning so
+you can review it manually.
+
+### Version Control and Upgrades for Generated Adapters
+
+`.claude/commands/dflow/<id>.md` is a **generated artifact** projected from the
+canonical guide. Dflow's **recommended default** is to not version-control it
+and regenerate it after clone with `dflow configure-agents --command-adapters`;
+teams that want a native command menu immediately after clone may instead
+**version-control** it. Use one consistent policy across all tools in a project
+(see the policy overview and ignore-vs-track trade-off in
+[README "Files Created by Init"](../README.en.md#files-created-by-init)).
+
+When using the gitignore default, add this to the project `.gitignore` (**only
+if you reserve the `.claude/commands/dflow/` namespace for Dflow**):
+
+```gitignore
+.claude/commands/dflow/
+```
+
+Note: this rule also ignores any custom commands you place in the same
+directory. If the directory is **already version-controlled**, adding the
+ignore rule does not remove it from version control automatically; first run:
+
+```bash
+git rm --cached -r .claude/commands/dflow/
+```
+
+(`--cached` removes it from version control while keeping the working-tree
+files.)
+
+After upgrading Dflow, re-running `dflow configure-agents --command-adapters`
+re-projects adapters from the **new registry**, but an existing
+`dflow/specs/shared/AI-AGENT-GUIDE.md` is **not** overwritten — "re-projecting
+adapters" is not the same as "migrating the canonical guide." Re-project with
+the **same dflow CLI version** to avoid a registry / guide version mismatch.
+
+### Optional Skill Adapter (Restore Natural-Language Auto-Trigger)
+
+Command adapters give you a `/` menu entry, but they **do not auto-trigger** —
+you have to invoke the command yourself. If you want to restore the "say 'I want
+to add a feature' and it shows up automatically" experience, run this in an
+initialized project:
+
+```bash
+dflow configure-agents --skills
+```
+
+After you select Claude Code, Dflow generates a thin skill:
+
+- `.claude/skills/dflow/SKILL.md`
+
+This skill does not copy workflow steps; its body points to the canonical
+`dflow/specs/shared/AI-AGENT-GUIDE.md` (command registry and routing rules) and
+`dflow/specs/shared/dflow-workflows/` (vendored bundle with executable step
+definitions).
+Its behavior:
+
+- **Auto-triggers on** feature / bug-fix workflows, product/domain behavior
+  changes, new requirements, and spec-impacting architecture / domain-model
+  decisions.
+- **Does not trigger on** pure refactors, infrastructure chores, formatting, or
+  general code questions.
+- When engaged by natural language it **does not enter a workflow directly**: it
+  judges the intent, **suggests the matching `/dflow:` command, and waits for
+  your confirmation** before proceeding.
+
+**The four combinations** (command adapters and the skill are each independently
+opt-in):
+
+| Installed | Entry behavior |
+|---|---|
+| Neither | Root shim only (CLAUDE.md points to the guide); no `/` menu, no auto-trigger |
+| Command adapters only | `/dflow:*` appears in the `/` menu; no natural-language auto-trigger |
+| Skill only | Natural-language auto-trigger (suggest-and-wait); no `/` menu |
+| Both | `/` menu + natural-language safety net **may coexist** |
+
+**Both may coexist with no mutex needed** (validated in a real Claude Code
+environment): the skill name `dflow` does not collide with the command adapters'
+`dflow:<id>` names, explicit commands load their own adapter precisely with no
+double-fire; the skill acts as a natural-language safety net while command
+adapters provide the `/` menu.
+
+After installing, verify with `/skills` or by asking "What skills are
+available?". Note: adding a new top-level skills directory may require
+**restarting Claude Code** before it is watched. Also, a personal / enterprise
+skill at `~/.claude/skills/dflow` can **override** the project skill (per the
+Claude docs); use `/skills` to check which one is active.
+
+**Version-control policy**: `.claude/skills/dflow/SKILL.md` is a **generated
+artifact**, just like the command adapters, and follows the same default — do
+not version-control it and regenerate it after clone with
+`dflow configure-agents --skills` (`.claude/skills/dflow/` is already in the
+recommended gitignore set); clone-ready teams may version-control it instead.
+Re-running `--skills` is idempotent: an existing marker-stamped skill is
+rewritten cleanly. If `.claude/skills/dflow/SKILL.md` is **not** Dflow-generated
+(no `<!-- dflow-generated: skill-adapter -->` marker), Dflow leaves it unchanged
+and prints a warning asking you to remove or rename it.
 
 ## Differences vs Other AI Tools
 

package/docs/using-with-claude-code.md

@@ -62,10 +62,14 @@ Claude Code 在這個專案中啟動時，會發生兩件事：
    Markdown import 語法，將 canonical Dflow 指南 inline 嵌入。因此 Claude Code
    等效於把兩個檔案當成一組指示來讀取。
 
-canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）是實際 workflow
-規則的所在：專案上下文（track、技術棧、文章語言）、`/dflow:*` workflow 表、
-source-of-truth 檔案路徑，以及核心 SDD/DDD 規則。`CLAUDE.md` shim 刻意保持精簡，
-這樣 canonical 指南就能在不需要 Claude Code 專屬修改的情況下持續演進。
+canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）是**命令登錄表與路由器**：
+專案上下文（track、技術棧、文章語言）、`/dflow:*` workflow 表、source-of-truth
+檔案路徑，以及核心 SDD/DDD 規則。可執行的 workflow 步驟（Step 1→N、step gates、
+completion checklists）則放在 `init` 投影進專案的 **vendored workflow bundle**
+（`dflow/specs/shared/dflow-workflows/`）。兩者都是純 Markdown，隨 repo
+一起 commit，任何 clone 都能直接讀取，不需要 Dflow source 或 package 在本機安裝。
+`CLAUDE.md` shim 刻意保持精簡，這樣 canonical 指南就能在不需要 Claude Code
+專屬修改的情況下持續演進。
 
 如果專案中已有 `CLAUDE.md`，`init` 不會覆蓋它。它改為在
 `dflow/specs/shared/` 下寫入 merge snippet，讓你手動貼入現有的 `CLAUDE.md`。
@@ -103,8 +107,10 @@ dflow/specs/features/active/. Before I do, I need a short answer on:
 接著這個 workflow 會引導你完成 spec 起草、行為範例、實作計畫，以及
 finish-feature 漂移（drift）檢查。確切的流程取決於你進入的是哪個 workflow
 （`/dflow:new-feature`、`/dflow:modify-existing`、`/dflow:bug-fix` 等）。
-所有 workflow 定義都存放在 Dflow skill source 中；Claude Code 在需要時讀取
-skill 檔案來執行它們。
+可執行的步驟定義（Step 1→N、step gates、completion checklists）存放在
+`dflow/specs/shared/dflow-workflows/` 的 vendored bundle 中；`init` 會把這個
+bundle 投影進每個初始化的專案，因此 workflow 步驟是 self-contained 且可達的，
+不需要任何外部 source dependency。
 
 可用的 workflow 入口：
 
@@ -143,9 +149,88 @@ dflow configure-agents --command-adapters
 `/dflow:new-feature`。Wrapper 內容只指向 canonical `/dflow:new-feature`
 workflow 與 `dflow/specs/shared/AI-AGENT-GUIDE.md`，不複製 workflow 步驟。
 從 Dflow 0.5.0 升級的專案可能仍保留舊檔
-`.claude/commands/dflow/dflow-*.md`；Dflow 不會擅自刪除 user 檔，請手動刪除
-這些舊 wrapper，避免 Claude Code 同時顯示舊的 `/dflow:dflow-<id>` 與新的
-`/dflow:<id>`。
+`.claude/commands/dflow/dflow-*.md`，會讓 Claude Code 同時顯示舊的
+`/dflow:dflow-<id>` 與新的 `/dflow:<id>`。重跑
+`dflow configure-agents --command-adapters` 時，Dflow 會**自動偵測並清除**這些
+0.5.0 產生的 stale wrapper：待刪檔會列在確認 preview 中（標為 `remove`），由你
+確認後才刪除。Dflow 只會刪除**內容與 0.5.0 產生物完全相符**的檔；若該檔被你改過、
+或是你自己放在同 namespace 的檔，Dflow 不會刪除，只會印出 warning 提示你自行確認。
+
+### 產生物的版控政策與升級
+
+`.claude/commands/dflow/<id>.md` 是從 canonical guide 投影出來的**衍生物**。Dflow 的
+**建議預設**是不版控、由 clone 後重跑 `dflow configure-agents --command-adapters` 重生成；
+團隊若想 clone 後立即有原生命令選單，也可改為**版控**。重點是同一專案對所有工具採一致策略
+（政策總覽與 ignore-vs-track 取捨見 [README「Init 產生的檔案」](../README.md#init-產生的檔案)）。
+
+採 gitignore 預設時，在專案 `.gitignore` 加入（**僅在你保留 `.claude/commands/dflow/`
+namespace 給 Dflow 時**）：
+
+```gitignore
+.claude/commands/dflow/
+```
+
+注意：此規則會一併 ignore 你放在同一目錄下的自訂 command。若該目錄**已被版控**，新增 ignore
+規則不會自動把它移出版控，需先：
+
+```bash
+git rm --cached -r .claude/commands/dflow/
+```
+
+（`--cached` 只移出版控、保留工作目錄檔案。）
+
+升級 dflow 後重跑 `dflow configure-agents --command-adapters`，adapter 會用**新版 registry**
+重投影；但既有 `dflow/specs/shared/AI-AGENT-GUIDE.md` **不會**被覆寫——「重投影 adapter」不等於
+「升級 canonical guide」。請以**相同的 dflow CLI 版本**重投影，避免 registry 與 guide 版本錯位。
+
+### 選配 Skill Adapter（找回自然語言自動觸發）
+
+Command adapter 提供 `/` 選單入口，但**不會自動觸發**——你得主動打命令。若想找回
+「講『我要加一個功能』就自動現身」的體驗，可在已初始化的專案中執行：
+
+```bash
+dflow configure-agents --skills
+```
+
+選擇 Claude Code 後，Dflow 會產生一份薄 skill：
+
+- `.claude/skills/dflow/SKILL.md`
+
+這份 skill 不複製 workflow 步驟，body 指向 canonical
+`dflow/specs/shared/AI-AGENT-GUIDE.md`（命令登錄表與路由規則）以及
+`dflow/specs/shared/dflow-workflows/`（含可執行步驟定義的 vendored bundle）。
+它的行為：
+
+- **自動觸發於** feature / bug-fix workflow、product/domain behavior 變更、新需求、
+  spec-impacting 的 architecture / domain-model 決策。
+- **不會觸發於** 純 refactor、infra chore、formatting、一般 code 問題。
+- 由自然語言觸發時，**不會直接進 workflow**：它會判斷意圖、**建議對應的 `/dflow:`
+  命令並等待你確認**，再進入流程。
+
+**四種組合**（command adapter 與 skill 各自獨立 opt-in）：
+
+| 安裝組合 | 入口行為 |
+|---|---|
+| 都不裝 | 只有根目錄 shim（CLAUDE.md 指向 guide）；無 `/` 選單、無自動觸發 |
+| 只裝 command adapters | `/dflow:*` 出現在 `/` 選單；無自然語言自動觸發 |
+| 只裝 skill | 自然語言自動觸發（suggest-and-wait）；無 `/` 選單 |
+| 兩者都裝 | `/` 選單 + 自然語言 safety net **可共存** |
+
+**兩者可共存、無需互斥**（已在真實 Claude Code 環境驗證）：skill 名稱 `dflow` 與
+command adapter 的 `dflow:<id>` 不撞名，明確命令各自精準載入、不會雙觸發；skill 當
+自然語言 safety net，command adapters 當 `/` 選單。
+
+安裝後用 `/skills` 或詢問「What skills are available?」確認 skill 已被探索到。注意：
+新增頂層 skills 目錄可能需**重啟 Claude Code** 才會被 watch 到。另外，位於
+`~/.claude/skills/dflow` 的 personal / enterprise skill 可能會 **override** 專案層級
+skill（依 Claude 官方文件），用 `/skills` 可檢查目前生效的是哪一份。
+
+**版控政策**：`.claude/skills/dflow/SKILL.md` 與 command adapter 一樣是**衍生物**，
+沿用相同預設——不版控、由 clone 後重跑 `dflow configure-agents --skills` 重生成
+（`.claude/skills/dflow/` 已列入建議的 gitignore 集合）；clone-ready 團隊也可選擇版控。
+重跑 `--skills` 是 idempotent 的：帶 marker 的既有 skill 會被乾淨重寫；若 `.claude/skills/dflow/SKILL.md`
+**不是** Dflow 產生的（無 `<!-- dflow-generated: skill-adapter -->` marker），Dflow 不會覆蓋它，
+只會印出 warning 提示你移除或改名。
 
 ## 與其他 AI 工具的差異
 

package/docs/using-with-codex.en.md

@@ -177,6 +177,20 @@ documentation guidance.
 In this mode, the Codex-target merge snippet filename is
 `dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`.
 
+### Version-Control Policy for Generated Artifacts (Codex)
+
+Codex does not generate command files, so there is **no derived adapter to
+gitignore**. On the Codex side, what you version-control is the `AGENTS.md`
+shim and `dflow/` (the canonical guide and specs); the merge helper
+`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md` is part of `dflow/`
+and is **version-controlled along with `dflow/`**. `--command-adapters` only
+strengthens the text triggers in `AGENTS.md` for Codex; it adds no `.claude/`,
+`.github/`, or `.agents/` command files, so the Claude / Copilot
+"version-control the generated adapter or not" trade-off does not apply on the
+Codex side. The adapter version-control policy for other tools is covered in
+[README "Files Created by Init"](../README.en.md#files-created-by-init) and the
+per-tool guides.
+
 ## Differences vs Other AI Tools
 
 The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is identical

package/docs/using-with-codex.md

@@ -162,6 +162,16 @@ dflow:new-feature
 在這個模式下，Codex 目標的 merge snippet 檔名是
 `dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`。
 
+### 產生物的版控政策（Codex）
+
+Codex 不產生 command 檔，所以**沒有需要 gitignore 的衍生 adapter**。Codex 端要版控的是
+`AGENTS.md` shim 與 `dflow/`（canonical guide + 規格）；其中
+`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md` 這個 merge helper 屬 `dflow/` 的一部分，
+**隨 `dflow/` 一起版控**。`--command-adapters` 對 Codex 只強化 `AGENTS.md` 的文字 trigger，
+不新增任何 `.claude/`、`.github/`、`.agents/` 命令檔，因此 Claude / Copilot 那套「衍生 adapter
+要不要版控」的取捨在 Codex 端不適用。其他工具的 adapter 版控政策見
+[README「Init 產生的檔案」](../README.md#init-產生的檔案) 與各 per-tool 指南。
+
 ## 與其他 AI 工具的差異
 
 canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間是相同的。

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

@@ -83,6 +83,42 @@ does not copy workflow steps. Copilot's `/` parser behavior differs from
 Claude and Codex: the prompt menu entry is `/dflow-<id>`, while chat text may
 still name the canonical `/dflow:<id>` workflow.
 
+### Version Control and Upgrades for Generated Adapters
+
+`.github/prompts/dflow-<id>.prompt.md` is a **generated artifact** projected
+from the canonical guide. Dflow's **recommended default** is to not
+version-control it and regenerate it after clone with `dflow configure-agents
+--command-adapters`; teams that want a native prompt menu immediately after
+clone may instead **version-control** it. Use one consistent policy across all
+tools in a project (policy overview in
+[README "Files Created by Init"](../README.en.md#files-created-by-init)).
+
+When using the gitignore default, add this to the project `.gitignore` (**mind
+the glob side effect**):
+
+```gitignore
+.github/prompts/dflow-*.prompt.md
+```
+
+This glob also ignores any of your own prompt files named with a `dflow-`
+prefix. If you have custom prompts with the same prefix, use a more specific
+rule or rename your custom files. If these prompts are **already
+version-controlled**, adding the ignore rule does not remove them
+automatically; first run:
+
+```bash
+git rm --cached .github/prompts/dflow-*.prompt.md
+```
+
+(`--cached` removes them from version control while keeping the working-tree
+files.)
+
+After upgrading Dflow, re-running `dflow configure-agents --command-adapters`
+re-projects prompt adapters from the **new registry**, but an existing
+`dflow/specs/shared/AI-AGENT-GUIDE.md` is **not** overwritten — "re-projecting
+adapters" is not the same as "migrating the canonical guide." Re-project with
+the **same dflow CLI version**.
+
 ### Sample Conversation Flow
 
 A typical Copilot Chat workflow looks like this: