dflow-sdd-ddd 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,45 @@
 
 ---
 
+## 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/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

@@ -156,10 +156,109 @@ 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 only points to the canonical
+`dflow/specs/shared/AI-AGENT-GUIDE.md`, which carries the real workflow content.
+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

@@ -143,9 +143,87 @@ 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`，由 guide 承載真正的 workflow 內容。
+它的行為：
+
+- **自動觸發於** 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:

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

@@ -90,6 +90,32 @@ workflow 與 `dflow/specs/shared/AI-AGENT-GUIDE.md`，不複製 workflow 步驟
 Copilot 的 `/` parser 行為與 Claude / Codex 不同：選單入口是 `/dflow-<id>`，
 但在 chat 文字中也可以直接說 canonical `/dflow:<id>`。
 
+### 產生物的版控政策與升級
+
+`.github/prompts/dflow-<id>.prompt.md` 是從 canonical guide 投影出來的**衍生物**。Dflow 的
+**建議預設**是不版控、由 clone 後重跑 `dflow configure-agents --command-adapters` 重生成；團隊若
+想 clone 後立即有原生 prompt 選單，也可改為**版控**。請對同專案的所有工具採一致策略（政策總覽見
+[README「Init 產生的檔案」](../README.md#init-產生的檔案)）。
+
+採 gitignore 預設時，在專案 `.gitignore` 加入（**注意 glob 副作用**）：
+
+```gitignore
+.github/prompts/dflow-*.prompt.md
+```
+
+此 glob 會一併 ignore 你自己以 `dflow-` 開頭命名的 prompt 檔。若你有同前綴的自訂 prompt，請改用
+更精確的規則或替自訂檔改名。若這些 prompt **已被版控**，新增 ignore 不會自動移出版控，需先：
+
+```bash
+git rm --cached .github/prompts/dflow-*.prompt.md
+```
+
+（`--cached` 只移出版控、保留工作目錄檔案。）
+
+升級 dflow 後重跑 `dflow configure-agents --command-adapters`，prompt adapter 會用**新版 registry**
+重投影；但既有 `dflow/specs/shared/AI-AGENT-GUIDE.md` **不會**被覆寫——「重投影 adapter」不等於
+「升級 canonical guide」。請以**相同的 dflow CLI 版本**重投影。
+
 ### 對話範例
 
 典型的 Copilot Chat workflow 如下：

package/lib/init.js

@@ -10,6 +10,8 @@ const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, 'templates');
 const COMMAND_REGISTRY_START = '<!-- dflow-command-registry:start -->';
 const COMMAND_REGISTRY_END = '<!-- dflow-command-registry:end -->';
+const COMMAND_ADAPTER_GENERATED_MARKER = '<!-- dflow-generated: command-adapter -->';
+const SKILL_ADAPTER_GENERATED_MARKER = '<!-- dflow-generated: skill-adapter -->';
 const EXPECTED_COMMAND_IDS = [
   'new-feature',
   'modify-existing',
@@ -23,6 +25,28 @@ const EXPECTED_COMMAND_IDS = [
   'next',
   'cancel'
 ];
+const LEGACY_COMMAND_ADAPTERS = [
+  {
+    version: '0.5.0',
+    agent: 'claude',
+    source: 'generated:legacy-claude-command-adapter-v0.5.0',
+    pathPattern: '.claude/commands/dflow/dflow-<id>.md',
+    fingerprint: 'v0.5.0 buildThinCommandWrapper',
+    commands: [
+      { id: 'new-feature', label: '/dflow:new-feature', argHint: 'feature request' },
+      { id: 'modify-existing', label: '/dflow:modify-existing', argHint: 'change request' },
+      { id: 'bug-fix', label: '/dflow:bug-fix', argHint: 'expected vs actual' },
+      { id: 'new-phase', label: '/dflow:new-phase', argHint: 'feature id or phase goal' },
+      { id: 'finish-feature', label: '/dflow:finish-feature', argHint: 'feature id' },
+      { id: 'verify', label: '/dflow:verify', argHint: 'area or feature id' },
+      { id: 'pr-review', label: '/dflow:pr-review', argHint: 'change or branch' },
+      { id: 'report-dflow-feedback', label: '/dflow:report-dflow-feedback', argHint: 'issue or improvement' },
+      { id: 'status', label: '/dflow:status', argHint: '-' },
+      { id: 'next', label: '/dflow:next', argHint: '-' },
+      { id: 'cancel', label: '/dflow:cancel', argHint: '-' }
+    ]
+  }
+];
 
 const PROSE_LANGUAGE_PATTERN =
   /^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?(?:-(?:[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*$/;
@@ -262,10 +286,12 @@ async function runConfigureAgents(options = {}) {
     const plan = await buildConfigureAgentsPlan(cwd, {
       ...projectContext,
       aiAgents,
-      commandAdapters: Boolean(options.commandAdapters)
+      commandAdapters: Boolean(options.commandAdapters),
+      skills: Boolean(options.skills)
     });
 
-    renderPreview(stdout, plan, []);
+    const warnings = plan.warnings || [];
+    renderPreview(stdout, plan, warnings);
     const confirmed = await askConfirmation(rl, 'Create these files? (y/N) ');
 
     if (!confirmed) {
@@ -276,6 +302,7 @@ async function runConfigureAgents(options = {}) {
     rl = undefined;
 
     const result = await writeFilePlan(cwd, plan);
+    result.warnings.unshift(...warnings);
     result.warnings.push(...collectUnresolvedPlaceholderWarnings(plan, result.created));
 
     printResultReport(stdout, result, plan.deferred);
@@ -1000,6 +1027,7 @@ async function buildConfigureAgentsPlan(cwd, answers) {
     optionalFiles: answers.optionalFiles || []
   });
   const items = [];
+  const warnings = [];
 
   let content = await readPackagedTemplate(answers.edition, 'scaffolding/AI-AGENT-GUIDE.md');
   content = substitutePlaceholders(content, substitution);
@@ -1022,9 +1050,16 @@ async function buildConfigureAgentsPlan(cwd, answers) {
 
   await finalizePlanItems(cwd, items);
 
+  if (answers.commandAdapters) {
+    await addLegacyCommandAdapterCleanupItems(cwd, items, answers.aiAgents, warnings);
+  }
+
+  await addSkillAdapterItems(cwd, items, answers.aiAgents, answers.skills, warnings);
+
   return {
     items,
     deferred: [],
+    warnings,
     unresolvedInitPlaceholders: Array.from(substitution.entries())
       .filter(([placeholder, value]) => placeholder === value)
       .map(([placeholder]) => placeholder)
@@ -1156,6 +1191,158 @@ function addCommandAdapterItems(items, aiAgents, commandRegistry) {
   }
 }
 
+async function addLegacyCommandAdapterCleanupItems(cwd, items, aiAgents, warnings) {
+  for (const legacy of LEGACY_COMMAND_ADAPTERS) {
+    if (!aiAgents.includes(legacy.agent)) {
+      continue;
+    }
+
+    for (const command of legacy.commands) {
+      const relativePath = legacy.pathPattern.replace('<id>', command.id);
+      const targetPath = path.join(cwd, relativePath);
+      let stats;
+
+      try {
+        stats = await fs.stat(targetPath);
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          continue;
+        }
+        throw error;
+      }
+
+      if (!stats.isFile()) {
+        warnings.push(`Found legacy Dflow command adapter path but it is not a file; not removed: ${relativePath}`);
+        continue;
+      }
+
+      const content = await fs.readFile(targetPath, 'utf8');
+      const expectedContent = buildLegacyCommandAdapterFingerprint(legacy, command);
+      if (normalizeCommandAdapterFingerprint(content) !== normalizeCommandAdapterFingerprint(expectedContent)) {
+        warnings.push(`Found legacy Dflow command adapter with non-generated content; not removed: ${relativePath}. Inspect it manually before deleting.`);
+        continue;
+      }
+
+      items.push({
+        relativePath,
+        source: legacy.source,
+        notes: `stale dflow adapter generated by Dflow ${legacy.version}`,
+        action: 'remove',
+        size: Buffer.byteLength(content, 'utf8'),
+        expectedContent
+      });
+    }
+  }
+}
+
+function buildDflowSkillAdapter() {
+  return `---
+name: dflow
+description: >
+  Dflow SDD/DDD workflow guardian for this project. PRIMARY: the canonical
+  /dflow:* commands (/dflow:new-feature, /dflow:modify-existing, /dflow:bug-fix,
+  /dflow:new-phase, /dflow:finish-feature, /dflow:pr-review, /dflow:verify,
+  /dflow:report-dflow-feedback, /dflow:status, /dflow:next, /dflow:cancel).
+  SECONDARY (auto-trigger safety net) — engage ONLY for: adding or changing
+  product/domain behavior, new requirements, a feature or bug-fix workflow, or
+  spec-impacting architecture/domain-model decisions. Do NOT engage for pure
+  refactors, infrastructure chores, formatting, or general code questions.
+  When engaged by natural language, DO NOT auto-enter a workflow: judge the
+  intent, suggest the matching /dflow: command, and wait for confirmation.
+---
+
+${SKILL_ADAPTER_GENERATED_MARKER}
+
+# Dflow SDD/DDD Workflow Guardian
+
+This project uses Dflow for spec-first AI-assisted development. The canonical
+workflow contract, command registry, spec locations, and SDD/DDD rules live in:
+
+- \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+
+When this skill engages, read that guide and follow the matching \`/dflow:\`
+workflow or control command defined there. Do not duplicate or invent workflow
+steps here — the guide is the single source of truth.
+
+If engaged by natural language (not an explicit \`/dflow:\` command): identify
+which \`/dflow:\` command fits, suggest it, and wait for the developer to confirm
+before entering any workflow.
+`;
+}
+
+async function addSkillAdapterItems(cwd, items, aiAgents, skills, warnings) {
+  if (!skills) {
+    return;
+  }
+
+  if (!aiAgents.includes('claude')) {
+    warnings.push(
+      'The --skills flag currently supports Claude Code only; no skill adapter was generated because Claude Code was not a selected target.'
+    );
+    return;
+  }
+
+  const relativePath = '.claude/skills/dflow/SKILL.md';
+  const targetPath = path.join(cwd, relativePath);
+
+  // The thin skill is edition-neutral (it only points to the per-edition guide),
+  // so there is nothing edition-specific to go stale — re-running just rewrites
+  // the same marker-guarded file (idempotent). No LEGACY skill set exists yet
+  // (skills are new in PROPOSAL-038); future skill cleanup would extend the same
+  // LEGACY_* / addLegacyCommandAdapterCleanupItems marker-fingerprint pattern.
+  let existingContent;
+  try {
+    existingContent = await fs.readFile(targetPath, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+    existingContent = undefined;
+  }
+
+  if (existingContent !== undefined && !existingContent.includes(SKILL_ADAPTER_GENERATED_MARKER)) {
+    warnings.push(
+      'Existing .claude/skills/dflow/SKILL.md is not a Dflow-generated skill; left unchanged. Remove or rename it to let Dflow manage this skill.'
+    );
+    return;
+  }
+
+  items.push({
+    relativePath,
+    source: 'generated:claude-skill-adapter',
+    notes: 'skill adapter, thin skill pointing to AI-AGENT-GUIDE.md',
+    content: buildDflowSkillAdapter(),
+    overwrite: true
+  });
+}
+
+function buildLegacyCommandAdapterFingerprint(legacy, command) {
+  if (legacy.version === '0.5.0' && legacy.fingerprint === 'v0.5.0 buildThinCommandWrapper') {
+    return buildLegacyV050ThinCommandWrapper(command);
+  }
+
+  throw new InitError(`Internal error: unsupported legacy command adapter fingerprint: ${legacy.version}`);
+}
+
+function buildLegacyV050ThinCommandWrapper(command) {
+  const argHint = command.argHint === '-'
+    ? 'Argument hint: none.'
+    : `Argument hint: ${command.argHint}.`;
+
+  return `# /dflow-${command.id}
+
+Execute the canonical \`${command.label}\` Dflow workflow or control command.
+
+Definition: \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+
+${argHint}
+`;
+}
+
+function normalizeCommandAdapterFingerprint(content) {
+  return String(content).replace(/\r\n/g, '\n');
+}
+
 function buildCodexCommandTriggerSection(commandRegistry) {
   const triggers = commandRegistry
     .map((command) => {
@@ -1190,6 +1377,8 @@ function buildThinCommandWrapper(command, displayName = command.label) {
 
   return `# ${displayName}
 
+${COMMAND_ADAPTER_GENERATED_MARKER}
+
 Execute the canonical \`${command.label}\` Dflow workflow or control command.
 
 Definition: \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
@@ -1651,6 +1840,7 @@ async function writeFilePlan(cwd, plan) {
   const result = {
     created: [],
     updated: [],
+    removed: [],
     skipped: [],
     warnings: []
   };
@@ -1659,6 +1849,37 @@ async function writeFilePlan(cwd, plan) {
     const targetPath = path.join(cwd, item.relativePath);
 
     try {
+      if (item.action === 'remove') {
+        let stats;
+        try {
+          stats = await fs.stat(targetPath);
+        } catch (error) {
+          if (error.code === 'ENOENT') {
+            result.skipped.push(item.relativePath);
+            result.warnings.push(`Skipped missing stale adapter: ${item.relativePath}`);
+            continue;
+          }
+          throw error;
+        }
+
+        if (!stats.isFile()) {
+          result.skipped.push(item.relativePath);
+          result.warnings.push(`Skipped stale adapter removal because target is not a file: ${item.relativePath}`);
+          continue;
+        }
+
+        const currentContent = await fs.readFile(targetPath, 'utf8');
+        if (normalizeCommandAdapterFingerprint(currentContent) !== normalizeCommandAdapterFingerprint(item.expectedContent || '')) {
+          result.skipped.push(item.relativePath);
+          result.warnings.push(`Skipped stale adapter removal because content changed after preview: ${item.relativePath}`);
+          continue;
+        }
+
+        await fs.unlink(targetPath);
+        result.removed.push(item.relativePath);
+        continue;
+      }
+
       if (await pathExists(targetPath)) {
         if (item.overwrite) {
           await fs.mkdir(path.dirname(targetPath), { recursive: true });
@@ -1710,9 +1931,11 @@ async function writeFilePlan(cwd, plan) {
         );
       }
 
-      const message = error.code === 'ENOTDIR' || error.code === 'EEXIST'
-        ? `Cannot create parent directory for ${item.relativePath}: a parent path is a file.`
-        : `Write failed while creating ${item.relativePath}: ${error.message}`;
+      const message = item.action === 'remove'
+        ? `Write failed while removing ${item.relativePath}: ${error.message}`
+        : error.code === 'ENOTDIR' || error.code === 'EEXIST'
+          ? `Cannot create parent directory for ${item.relativePath}: a parent path is a file.`
+          : `Write failed while creating ${item.relativePath}: ${error.message}`;
       throw new WritePhaseError(message, result);
     }
   }
@@ -1756,6 +1979,9 @@ function printResultReport(stdout, result, deferred) {
   stdout.write('\nUpdated:\n');
   printList(stdout, result.updated);
 
+  stdout.write('\nRemoved:\n');
+  printList(stdout, result.removed);
+
   stdout.write('\nSkipped:\n');
   printList(stdout, result.skipped);
 
@@ -1782,7 +2008,7 @@ Recommended next steps:
 
 function printConfigureAgentsNextSteps(stdout, commandAdapters = false) {
   const commandAdapterStep = commandAdapters
-    ? '- Command adapters use tool-specific invocation names: Claude Code `/dflow:<id>`; GitHub Copilot prompt menu `/dflow-<id>` or canonical `/dflow:<id>` as text; Codex CLI plain text without a slash, such as `dflow:status`. Canonical `/dflow:*` names remain defined in dflow/specs/shared/AI-AGENT-GUIDE.md. If upgrading from Dflow 0.5.0, manually remove stale `.claude/commands/dflow/dflow-*.md` files so Claude Code does not show both old and new command names.\n'
+    ? '- Command adapters use tool-specific invocation names: Claude Code `/dflow:<id>`; GitHub Copilot prompt menu `/dflow-<id>` or canonical `/dflow:<id>` as text; Codex CLI plain text without a slash, such as `dflow:status`. Canonical `/dflow:*` names remain defined in dflow/specs/shared/AI-AGENT-GUIDE.md. If upgrading from Dflow 0.5.0, stale `.claude/commands/dflow/dflow-*.md` files generated by 0.5.0 are detected and listed for removal in the confirmation preview, so Claude Code does not show both old and new command names; edited or non-Dflow files are kept with a warning.\n'
     : '';
 
   stdout.write(`

package/package.json

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