dflow-sdd-ddd 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -6,6 +6,74 @@
 
 ---
 
+## 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 命名 + 各工具叫用現實對齊）
+
+**變更**：
+
+- **修正 opt-in command adapter 命名 bug**（PROPOSAL-036）：0.5.0 的
+  `dflow configure-agents --command-adapters` 在 Claude 產生
+  `.claude/commands/dflow/dflow-<id>.md`；因 Claude Code 把子目錄 `dflow/`
+  當 namespace、再加上檔名的 `dflow-` 前綴，註冊出的指令名變成重複的
+  `/dflow:dflow-<id>`。改為產生 `.claude/commands/dflow/<id>.md`，指令名
+  回正為 `/dflow:<id>`。
+- **各工具叫用方式對齊實測現實**：command adapter wrapper 與
+  `configure-agents` next-steps 文字改為說明三工具實際叫用名 —— Claude Code
+  `/dflow:<id>`、GitHub Copilot 選單 `/dflow-<id>`（或 canonical `/dflow:<id>`
+  純文字）、Codex CLI 不帶斜線的純文字（如 `dflow:status`）。Codex AGENTS.md
+  command-adapters snippet 補上「CLI 攔截斜線指令時改送不帶斜線文字」的指引。
+  `README` / `docs/using-with-*` / `docs/evaluating-dflow` / `tutorial`
+  同步更新。
+
+**⚠️ Breaking change / 遷移**：
+
+- 生成路徑重新命名。**從 0.5.0 升級、且曾跑過 `configure-agents
+  --command-adapters` 的專案**，須手動刪除舊的
+  `.claude/commands/dflow/dflow-*.md`，否則 Claude Code 會同時顯示新舊兩組
+  指令名。未使用 command adapters 的專案不受影響。
+
+---
+
 ## 0.5.0 — 2026-05-20 — Guide control commands、opt-in command adapters、移除 Gemini
 
 **Proposals**：PROPOSAL-032（AI-AGENT-GUIDE 補 status/next/cancel 行為語義 +

package/README.en.md

@@ -47,8 +47,14 @@ tool, run:
 dflow configure-agents
 ```
 
-This command only configures AI instruction files. It does not rerun project
-initialization or touch existing specs.
+If you also want tool-native command / prompt wrappers, use the opt-in mode:
+
+```bash
+dflow configure-agents --command-adapters
+```
+
+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
 
@@ -94,7 +100,19 @@ After init, start work through the Dflow workflow in your AI coding agent:
 /dflow:pr-review
 ```
 
-If your tool does not support custom slash commands, use the same command names as plain instructions in chat. Dflow is Markdown-based workflow material plus a scaffolding CLI, so it can be used with AI coding agents that can read project instructions and repository context.
+`/dflow:*` is Dflow's canonical shared vocabulary; each AI tool's `/` parser
+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 |
+| 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
+a plain instruction in chat. Dflow is Markdown-based workflow material plus a
+scaffolding CLI, so it can be used with AI coding agents that can read project
+instructions and repository context.
 
 For the first adoption pass, use a branch or disposable sample project so your
 team can inspect the generated `dflow/specs/` workspace before bringing the
@@ -216,7 +234,38 @@ 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.
+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

package/README.md

@@ -41,7 +41,13 @@ init 流程會詢問是 greenfield 或 brownfield，接著預覽即將建立的
 dflow configure-agents
 ```
 
-此指令只設定 AI 指示檔，不會重跑專案初始化，也不會動到既有 specs。
+若想同時建立工具原生的命令 / prompt wrapper，使用 opt-in 模式：
+
+```bash
+dflow configure-agents --command-adapters
+```
+
+此指令只設定 AI 指示檔與選配 command adapters，不會重跑專案初始化，也不會動到既有 specs。
 
 ### 替代路徑：不安裝直接試用
 
@@ -79,7 +85,15 @@ dflow doctor
 /dflow:pr-review
 ```
 
-若你的工具不支援自訂 slash command，把同名指令當成普通對話訊息輸入即可。Dflow 是 Markdown-based 的 workflow 材料加一個 scaffolding CLI，能與任何可讀專案指示與 repo 上下文的 AI 程式設計助理一起運作。
+`/dflow:*` 是 Dflow 的 canonical 共同詞彙；各 AI 工具的 `/` parser 行為不同。實際輸入方式如下：
+
+| 工具 | 建議叫法 |
+|---|---|
+| Claude Code（安裝 `--command-adapters` 後） | `/dflow:<id>`，例如 `/dflow:new-feature` |
+| GitHub Copilot | chat 文字可用 `/dflow:<id>`；VS Code prompt 選單使用 `/dflow-<id>` |
+| Codex CLI | 不帶斜線的純文字 `dflow:<id>`，例如 `dflow:new-feature` |
+
+若你的工具不支援自訂 slash command，把 workflow 名稱當成普通對話訊息輸入即可。Dflow 是 Markdown-based 的 workflow 材料加一個 scaffolding CLI，能與任何可讀專案指示與 repo 上下文的 AI 程式設計助理一起運作。
 
 第一次採用建議用 branch 或一次性試用專案，讓團隊先檢視產生的 `dflow/specs/` 工作區，再把流程引入正式程式碼。
 
@@ -188,7 +202,21 @@ Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指
 
 若這些檔案已存在，Dflow 不會覆蓋，改寫 merge snippet 到 `dflow/specs/shared/`。專案指南保持單一 source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow 規則。
 
-之後團隊採用新 AI 程式設計助理時，可隨時跑 `dflow configure-agents` 新增 shim。
+之後團隊採用新 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 指南：
 

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

@@ -64,13 +64,17 @@ Each shim points back to the canonical
 
 - Multiple tools can be active in the same project without diverging
   workflow rules.
-- Switching or adding tools later does not require re-running `init`; use
-  run `dflow configure-agents` to add another shim.
+- Switching or adding tools later does not require re-running `init`; run
+  `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.
 
-If your tool does not support custom slash commands, use the same command
-names (e.g., `/dflow:new-feature`) as plain instructions in chat. Dflow is
+`/dflow:*` is the canonical shared vocabulary, but each tool's `/` parser
+behaves differently: Claude Code command adapters use `/dflow:<id>`, the
+GitHub Copilot prompt menu uses `/dflow-<id>` (chat text can still name
+`/dflow:<id>`), and Codex CLI uses no-slash text `dflow:<id>`. Dflow is
 Markdown-based workflow material; it works with any AI agent that can read
 project instructions and repository context.
 
@@ -144,8 +148,10 @@ real codebase.
    - Brownfield: [`tutorial/02-brownfield/`](../tutorial/02-brownfield/walkthrough-00-setup.md)
 
 5. **Optional: try one workflow command**. Open the sample project in your
-   AI tool and ask it to run `/dflow:new-feature` (or paste the equivalent
-   instruction in chat). Inspect what it writes to `dflow/specs/`.
+   AI tool and ask it to run the new-feature workflow using that tool's
+   invocation form (`/dflow:new-feature` in Claude Code with adapters,
+   `/dflow-<id>` from the Copilot prompt menu, or `dflow:new-feature` in
+   Codex CLI). Inspect what it writes to `dflow/specs/`.
 
 6. **Decide and clean up**. If Dflow does not fit, delete the sample
    directory. There is no global state to clean; nothing was installed

package/docs/evaluating-dflow.md

@@ -48,10 +48,14 @@ Dflow 支援多種 AI 程式設計助理。跑完 `init` 後，你選取一個
 每個 shim 都指向 canonical 的 `dflow/specs/shared/AI-AGENT-GUIDE.md`。實際意義：
 
 - 同一個專案可以同時啟用多個工具，而不會有 workflow 規則分歧。
-- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim。
+- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim，或用 `dflow configure-agents --command-adapters` opt in 工具原生命令入口。
 - 專案指南始終保持為 Dflow workflow 行為的單一 source of truth。
 
-若你的工具不支援自訂 slash command，把同名指令（例如 `/dflow:new-feature`）當成普通對話訊息輸入即可。Dflow 是 Markdown-based 的 workflow 材料，能與任何可讀專案指示與 repo 上下文的 AI 助理一起運作。
+`/dflow:*` 是 canonical 共同詞彙，但各工具的 `/` parser 行為不同：Claude Code
+command adapters 使用 `/dflow:<id>`，GitHub Copilot prompt 選單使用
+`/dflow-<id>`（chat 文字仍可說 `/dflow:<id>`），Codex CLI 使用不帶斜線的
+`dflow:<id>`。Dflow 是 Markdown-based 的 workflow 材料，能與任何可讀專案指示與
+repo 上下文的 AI 助理一起運作。
 
 關於特定工具的 `init` 寫入內容與 slash command 在對話中的呈現方式，見各工具指南：
 
@@ -111,7 +115,7 @@ Dflow 支援多種 AI 程式設計助理。跑完 `init` 後，你選取一個
    - Greenfield：[`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)
    - Brownfield：[`tutorial/02-brownfield/`](../tutorial/02-brownfield/walkthrough-00-setup.md)
 
-5. **選用：試跑一個 workflow 指令**。在你的 AI 工具中開啟範例專案，叫它執行 `/dflow:new-feature`（或在對話中貼上同等指令）。檢查它寫入 `dflow/specs/` 的內容。
+5. **選用：試跑一個 workflow 指令**。在你的 AI 工具中開啟範例專案，依工具叫法執行 new-feature workflow（Claude Code adapters 用 `/dflow:new-feature`、Copilot prompt 選單用 `/dflow-<id>`、Codex CLI 用 `dflow:new-feature`）。檢查它寫入 `dflow/specs/` 的內容。
 
 6. **決定並清理**。若 Dflow 不適合，直接刪除範例目錄。沒有全域狀態需要清除；除了一次性的 `npx` 快取，什麼也沒有安裝。
 

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

@@ -81,17 +81,19 @@ custom project instructions you already had.
 
 ## Using Dflow Slash Commands in Claude Code
 
-By default, Dflow's canonical `/dflow:*` slash commands are workflow names
-recognized by the AI through the workflow table in `AI-AGENT-GUIDE.md`, not
-Claude Code's built-in slash command system. You type them as plain chat:
+Dflow's canonical `/dflow:*` names are the shared workflow vocabulary across
+tools. Each tool has different `/` parser behavior, and Claude Code accepts
+`/dflow:<id>` only when that slash command has been registered. Install the
+command adapters below, then invoke the Claude Code registered name:
 
 ```text
 /dflow:new-feature
 ```
 
-Claude Code treats this as input. Because it has the workflow table loaded
-via `CLAUDE.md` import, it recognizes the prefix and enters the matching
-workflow. A typical conversation looks like:
+After adapters are installed, Claude Code registers
+`.claude/commands/dflow/<id>.md` as `/dflow:<id>`. The wrapper points back to
+the canonical workflow in `AI-AGENT-GUIDE.md`. A typical conversation looks
+like:
 
 ```text
 You: /dflow:new-feature
@@ -131,6 +133,11 @@ If you forget a command name, ask Claude Code "what dflow workflows are
 available?" — the answer comes from the workflow table it already has
 loaded.
 
+If command adapters are not installed yet, or if Claude Code treats a
+slash-prefixed input as an unknown command, resend it as plain text, for
+example `dflow:new-feature` or `Run the Dflow /dflow:new-feature workflow.`,
+so the model can follow the canonical guide.
+
 ### Optional Command Adapters
 
 If you want Claude Code to expose tool-native command entries, run this in an
@@ -143,14 +150,115 @@ dflow configure-agents --command-adapters
 After you select Claude Code, Dflow projects thin wrappers from the command
 registry inside the canonical guide:
 
-- `.claude/commands/dflow/dflow-<id>.md`
+- `.claude/commands/dflow/<id>.md`
+
+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, 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:
 
-These wrappers use adapter-native 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.
-Dflow v1 does not promise that Claude Code's menu will expose the exact
-colon form `/dflow:new-feature`. The canonical name remains in the guide and
-wrapper body.
+- `.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
 
@@ -178,10 +286,10 @@ spec locations, or SDD constraints to `CLAUDE.md`, those belong in
 `dflow/specs/shared/AI-AGENT-GUIDE.md` instead. The shim stays small so
 that other tools' shims don't drift away from it.
 
-**Default `/dflow:*` is not a Claude Code Skill installation.** `init` does
-not install anything into Claude Code's skill system. The slash commands are
-plain text patterns the AI recognizes from the workflow table. If you later
-run `dflow configure-agents --command-adapters`, the added files are thin
+**`/dflow:*` is not a Claude Code Skill installation.** `init` does not
+install anything into Claude Code's skill system. Without command adapters,
+Dflow names are text triggers the AI recognizes from the workflow table. After
+you run `dflow configure-agents --command-adapters`, the added files are thin
 command wrappers, not a second workflow definition.
 
 **Choose either legacy Claude skills or the installed adapter.** If the