dflow-sdd-ddd 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,35 @@
 
 ---
 
+## 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,8 @@ 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`.
 
 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,7 @@ 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`。
 
 特定工具的 init 寫入內容與 Dflow workflow 命令呈現方式，見 `docs/` 內的 per-tool 指南：
 

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/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,16 @@ 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 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.
+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.
 
 ## Differences vs Other AI Tools
 
@@ -178,10 +187,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

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

@@ -73,16 +73,18 @@ source-of-truth 檔案路徑，以及核心 SDD/DDD 規則。`CLAUDE.md` shim
 
 ## 在 Claude Code 中使用 Dflow Slash Commands
 
-預設情況下，Dflow 的 canonical `/dflow:*` slash commands 是 AI 透過
-`AI-AGENT-GUIDE.md` 中的 workflow 表識別的 workflow 名稱，不是 Claude Code
-內建的 slash command 系統。你以普通對話方式輸入它們：
+Dflow 的 canonical `/dflow:*` 名稱是跨工具共用的 workflow 詞彙；各工具的
+`/` parser 行為不同，Claude Code 需要註冊過的 slash command 才能接受
+`/dflow:<id>` 形式。建議先安裝下方的 command adapters，然後以 Claude Code
+實際註冊的名稱輸入：
 
 ```text
 /dflow:new-feature
 ```
 
-Claude Code 將此視為輸入。由於它已透過 `CLAUDE.md` import 載入了 workflow 表，
-它會識別這個前綴並進入對應的 workflow。一次典型的對話如下：
+安裝 adapter 後，Claude Code 會把 `.claude/commands/dflow/<id>.md` 註冊成
+`/dflow:<id>`。Wrapper 會指回 `AI-AGENT-GUIDE.md` 中的 canonical workflow。
+一次典型的對話如下：
 
 ```text
 You: /dflow:new-feature
@@ -120,6 +122,10 @@ skill 檔案來執行它們。
 如果你忘了指令名稱，問 Claude Code「what dflow workflows are available?」
 即可 —— 答案會從它已載入的 workflow 表中給出。
 
+若尚未安裝 command adapters，或 Claude Code 將 slash-prefixed 輸入判定為
+Unknown command，請改用普通文字，例如 `dflow:new-feature` 或
+`Run the Dflow /dflow:new-feature workflow.`，讓模型依 canonical guide 執行。
+
 ### 選配 Command Adapters
 
 如果想讓 Claude Code 看到工具原生的命令入口，可在已初始化的專案中執行：
@@ -131,13 +137,15 @@ dflow configure-agents --command-adapters
 選擇 Claude Code 後，Dflow 會從 canonical guide 內的 command registry
 投影產生薄 wrapper：
 
-- `.claude/commands/dflow/dflow-<id>.md`
+- `.claude/commands/dflow/<id>.md`
 
-這些 wrapper 使用 adapter-native 命名，例如 `/dflow-new-feature`。Wrapper
-內容只指向 canonical `/dflow:new-feature` workflow 與
-`dflow/specs/shared/AI-AGENT-GUIDE.md`，不複製 workflow 步驟。Dflow v1 不承諾
-Claude Code 選單中一定會出現 exact `/dflow:new-feature` colon 形式；canonical
-名稱仍保留在 guide 與 wrapper body 中。
+這些 wrapper 使用 Claude Code 的目錄 namespace 命名，例如
+`/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>`。
 
 ## 與其他 AI 工具的差異
 
@@ -164,10 +172,10 @@ SDD 約束加入 `CLAUDE.md`，這些內容應該放到
 `dflow/specs/shared/AI-AGENT-GUIDE.md`。shim 保持精簡，其他工具的 shim 才不會
 與它產生漂移（drift）。
 
-**預設 `/dflow:*` 不是安裝 Claude Code Skill。** `init` 不會在 Claude Code 的
-skill 系統中安裝任何東西。Slash commands 是 AI 從 workflow 表識別的純文字模式。
-若你之後執行 `dflow configure-agents --command-adapters`，新增的是薄 command
-wrapper，不是 workflow 的第二份定義。
+**`/dflow:*` 不是安裝 Claude Code Skill。** `init` 不會在 Claude Code 的
+skill 系統中安裝任何東西。未安裝 command adapters 時，Dflow 名稱只是 AI 從
+workflow 表識別的文字 trigger；安裝 `dflow configure-agents --command-adapters`
+後，新增的是薄 command wrapper，不是 workflow 的第二份定義。
 
 **legacy Claude skill 與 installed adapter 擇一。** 如果專案仍保留舊的
 `.claude/skills/sdd-ddd-*` skill，請在 legacy skill 與 `--command-adapters`

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

@@ -84,40 +84,41 @@ it. If the existing file does not already point to
 `dflow/specs/shared/AGENTS-md-snippet.md` that you can merge manually. This
 avoids destroying custom project instructions you already had.
 
+In the `dflow configure-agents --command-adapters` case, the corresponding
+snippet path is `dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`.
+
 ## Using Dflow Workflow Commands in Codex CLI
 
 Codex CLI has its own built-in slash command layer for controlling the CLI
 session. Commands such as `/permissions`, `/model`, `/status`, `/diff`,
 `/review`, and `/init` are Codex CLI controls, not Dflow workflows.
 
-Dflow's `/dflow:*` entries are workflow names recognized by the AI through
-`AI-AGENT-GUIDE.md`, not registered Codex CLI commands. Raw
-`/dflow:new-feature` passthrough behavior in Codex CLI should be verified
-with the maintainer for the supported Codex version. The reliable form is to
-name the workflow as a plain chat instruction:
+Dflow's canonical `/dflow:*` entries are workflow names recognized by the AI
+through `AI-AGENT-GUIDE.md`, not registered Codex CLI commands. Codex handles
+the leading `/` first, so the reliable form is to remove the leading slash and
+send the same name as plain text:
 
 ```text
-Run the Dflow /dflow:new-feature workflow.
+dflow:new-feature
 ```
 
-If your Codex CLI version passes unknown slash-prefixed input through to the
-model, this shorter form may also work (verify with maintainer):
+Or use a plain chat instruction:
 
 ```text
-/dflow:new-feature
+Run the Dflow dflow:new-feature workflow.
 ```
 
-If Codex reports an unknown slash command, re-send the request in prose:
+If Codex reports an unknown slash command, re-send it without the slash:
 
 ```text
-Treat /dflow:new-feature as a Dflow workflow name, not as a Codex CLI
-command. Read dflow/specs/shared/AI-AGENT-GUIDE.md and start that workflow.
+Treat dflow:new-feature as the canonical /dflow:new-feature Dflow workflow
+name. Read dflow/specs/shared/AI-AGENT-GUIDE.md and start that workflow.
 ```
 
 A typical conversation looks like:
 
 ```text
-You: Run the Dflow /dflow:new-feature workflow.
+You: dflow:new-feature
 
 Codex CLI: I'll read dflow/specs/shared/AI-AGENT-GUIDE.md first, then use the
 new-feature workflow. Please describe the user-visible capability or business
@@ -132,21 +133,22 @@ dflow/specs/features/active/. Before I do, I have a few clarifying questions.
 
 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.).
+sequence depends on which workflow you entered (`dflow:new-feature`,
+`dflow:modify-existing`, `dflow:bug-fix`, etc.; the canonical guide records
+these as `/dflow:*`).
 
 Available workflow entry points:
 
-| Workflow | Use when |
+| Codex input | Use when |
 |---|---|
-| `/dflow:new-feature` | A new user-visible capability or business behavior is requested. |
-| `/dflow:modify-existing` | Existing behavior needs to change. |
-| `/dflow:bug-fix` | A defect can be described with expected vs actual behavior. |
-| `/dflow:new-phase` | An active feature needs another implementation slice. |
-| `/dflow:finish-feature` | Implementation is complete and needs drift closure. |
-| `/dflow:verify` | Specs, domain docs, implementation, and tests need consistency checks. |
-| `/dflow:pr-review` | A change is ready for SDD/DDD review. |
-| `/dflow:report-dflow-feedback` | You found a Dflow issue or improvement and want a sanitized upstream feedback draft. |
+| `dflow:new-feature` | A new user-visible capability or business behavior is requested. |
+| `dflow:modify-existing` | Existing behavior needs to change. |
+| `dflow:bug-fix` | A defect can be described with expected vs actual behavior. |
+| `dflow:new-phase` | An active feature needs another implementation slice. |
+| `dflow:finish-feature` | Implementation is complete and needs drift closure. |
+| `dflow:verify` | Specs, domain docs, implementation, and tests need consistency checks. |
+| `dflow:pr-review` | A change is ready for SDD/DDD review. |
+| `dflow:report-dflow-feedback` | You found a Dflow issue or improvement and want a sanitized upstream feedback draft. |
 
 If you forget a workflow name, ask Codex to read
 `dflow/specs/shared/AI-AGENT-GUIDE.md` and list the available Dflow
@@ -165,13 +167,16 @@ shim includes a trigger list generated from the canonical command registry.
 Those triggers are still plain text prompts, for example:
 
 ```text
-Run the Dflow /dflow:new-feature workflow.
+dflow:new-feature
 ```
 
 If the project already has a custom `AGENTS.md`, Dflow still preserves that
 file; merge the Dflow pointer manually from the generated snippet or the
 documentation guidance.
 
+In this mode, the Codex-target merge snippet filename is
+`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`.
+
 ## Differences vs Other AI Tools
 
 The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is identical
@@ -211,11 +216,11 @@ Codex shim has a normal Markdown bullet pointing to the canonical guide, not
 an `@...` import. Ask Codex to read `AI-AGENT-GUIDE.md` if it appears to be
 working from the shim alone.
 
-**`/dflow:*` is not a Codex CLI built-in slash command.** Codex slash
-commands control the Codex session itself. Use Dflow workflow names as plain
-chat instructions when raw slash input is intercepted or rejected. Raw
-`/dflow:*` passthrough behavior should be verified with the maintainer for
-the supported Codex version.
+**`/dflow:*` is not a Codex CLI built-in slash command.** Codex slash commands
+control the Codex session itself. When raw slash input is intercepted or
+rejected, use the no-slash text form `dflow:<id>`, for example
+`dflow:status`. The model should treat it as the canonical `/dflow:<id>`
+workflow by reading `AI-AGENT-GUIDE.md`.
 
 **Codex does not generate command files.** Even with `--command-adapters`,
 Codex only strengthens text-trigger guidance in `AGENTS.md` / merge

package/docs/using-with-codex.md

@@ -74,39 +74,40 @@ Claude Code、GitHub Copilot 與其他工具。
 `dflow/specs/shared/AGENTS-md-snippet.md` 下寫入 merge snippet，
 讓你手動合併。這樣可以避免破壞你已有的自訂專案指示。
 
+若是 `dflow configure-agents --command-adapters` 情境，對應檔名為
+`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`。
+
 ## 在 Codex CLI 中使用 Dflow Workflow 指令
 
 Codex CLI 有自己的內建 slash command 層，用來控制 CLI session。
 `/permissions`、`/model`、`/status`、`/diff`、`/review`、`/init` 等指令
 都是 Codex CLI 控制項，不是 Dflow workflow。
 
-Dflow 的 `/dflow:*` 項目是 AI 透過 `AI-AGENT-GUIDE.md` 識別的 workflow
-名稱，不是已註冊的 Codex CLI 指令。`/dflow:new-feature` 在 Codex CLI 中
-能否直接傳遞到模型，需依所用的 Codex 版本向 maintainer 確認。
-最可靠的方式是以普通對話指示輸入 workflow 名稱：
+Dflow 的 canonical `/dflow:*` 項目是 AI 透過 `AI-AGENT-GUIDE.md` 識別的
+workflow 名稱，不是已註冊的 Codex CLI 指令。Codex 會先處理 `/` 前綴，因此
+最可靠的方式是移除開頭斜線，把同一個名稱當普通文字輸入：
 
 ```text
-Run the Dflow /dflow:new-feature workflow.
+dflow:new-feature
 ```
 
-若你的 Codex CLI 版本會將未知的 slash 前綴輸入傳遞到模型，也可嘗試以下
-較短形式（請先向 maintainer 確認）：
+或用一句普通對話指示：
 
 ```text
-/dflow:new-feature
+Run the Dflow dflow:new-feature workflow.
 ```
 
-若 Codex 回報未知 slash command，改以純文字重新送出：
+若 Codex 回報未知 slash command，改以不帶斜線的純文字重新送出：
 
 ```text
-Treat /dflow:new-feature as a Dflow workflow name, not as a Codex CLI
-command. Read dflow/specs/shared/AI-AGENT-GUIDE.md and start that workflow.
+Treat dflow:new-feature as the canonical /dflow:new-feature Dflow workflow
+name. Read dflow/specs/shared/AI-AGENT-GUIDE.md and start that workflow.
 ```
 
 典型的對話如下：
 
 ```text
-You: Run the Dflow /dflow:new-feature workflow.
+You: dflow:new-feature
 
 Codex CLI: I'll read dflow/specs/shared/AI-AGENT-GUIDE.md first, then use the
 new-feature workflow. Please describe the user-visible capability or business
@@ -121,20 +122,21 @@ dflow/specs/features/active/. Before I do, I have a few clarifying questions.
 
 接著這個 workflow 會引導你完成 spec 起草、行為範例、實作計畫，以及
 finish-feature 漂移（drift）檢查。確切的流程取決於你進入的是哪個 workflow
-（`/dflow:new-feature`、`/dflow:modify-existing`、`/dflow:bug-fix` 等）。
+（`dflow:new-feature`、`dflow:modify-existing`、`dflow:bug-fix` 等；canonical
+guide 中記為 `/dflow:*`）。
 
 可用的 workflow 入口：
 
-| 指令 | 適用情境 |
+| Codex 輸入 | 適用情境 |
 |---|---|
-| `/dflow:new-feature` | 需要新增一個使用者可見的功能或業務行為。 |
-| `/dflow:modify-existing` | 需要修改現有行為。 |
-| `/dflow:bug-fix` | 可以用預期行為 vs 實際行為描述的缺陷。 |
-| `/dflow:new-phase` | 進行中的 feature 需要另一個實作 slice。 |
-| `/dflow:finish-feature` | 實作完成後需要進行漂移（drift）收尾。 |
-| `/dflow:verify` | 需要對 spec、領域文件、實作與測試進行一致性檢查。 |
-| `/dflow:pr-review` | 變更已準備好進行 SDD/DDD review。 |
-| `/dflow:report-dflow-feedback` | 你發現了 Dflow 的問題或改進點，想要一份清理過的上游回饋草稿。 |
+| `dflow:new-feature` | 需要新增一個使用者可見的功能或業務行為。 |
+| `dflow:modify-existing` | 需要修改現有行為。 |
+| `dflow:bug-fix` | 可以用預期行為 vs 實際行為描述的缺陷。 |
+| `dflow:new-phase` | 進行中的 feature 需要另一個實作 slice。 |
+| `dflow:finish-feature` | 實作完成後需要進行漂移（drift）收尾。 |
+| `dflow:verify` | 需要對 spec、領域文件、實作與測試進行一致性檢查。 |
+| `dflow:pr-review` | 變更已準備好進行 SDD/DDD review。 |
+| `dflow:report-dflow-feedback` | 你發現了 Dflow 的問題或改進點，想要一份清理過的上游回饋草稿。 |
 
 如果你忘了 workflow 名稱，請 Codex 讀取 `dflow/specs/shared/AI-AGENT-GUIDE.md`
 並列出可用的 Dflow workflow 即可。
@@ -151,12 +153,15 @@ adapter。
 registry 產生的 trigger 清單。這些 trigger 仍是文字提示，例如：
 
 ```text
-Run the Dflow /dflow:new-feature workflow.
+dflow:new-feature
 ```
 
 如果專案已有自訂 `AGENTS.md`，Dflow 仍會保留既有檔案；請依產生的 merge snippet
 或文件指引手動合併 Dflow 指標。
 
+在這個模式下，Codex 目標的 merge snippet 檔名是
+`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`。
+
 ## 與其他 AI 工具的差異
 
 canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間是相同的。
@@ -194,9 +199,9 @@ SDD 約束加入 `AGENTS.md`，這些內容應該放到
 若 Codex 看起來只從 shim 工作，請要求它讀取 `AI-AGENT-GUIDE.md`。
 
 **`/dflow:*` 不是 Codex CLI 的內建 slash command。** Codex slash command 控制
-的是 Codex session 本身。當 slash 輸入被攔截或拒絕時，改用普通對話指示
-輸入 Dflow workflow 名稱。`/dflow:*` 的直通行為需依所用的 Codex 版本向
-maintainer 確認。
+的是 Codex session 本身。當 slash 輸入被攔截或拒絕時，改用不帶斜線的普通文字
+`dflow:<id>`，例如 `dflow:status`。模型會依 `AI-AGENT-GUIDE.md` 把它視為
+canonical `/dflow:<id>` workflow。
 
 **Codex 不產生命令檔。** 即使使用 `--command-adapters`，Codex 也只強化
 `AGENTS.md` / merge snippet 中的文字 trigger 說明。不要期待 `.claude/commands`、

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

@@ -76,13 +76,12 @@ command registry inside the canonical guide:
 
 - `.github/prompts/dflow-<id>.prompt.md`
 
-These prompts use adapter-native names, for example `/dflow-new-feature` or
-the matching IDE Quick Pick prompt name. 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 Copilot chat supports the exact colon form
-`/dflow:new-feature`. The canonical name remains in the guide and prompt
-body.
+These prompts use `/dflow-<id>` in the Copilot / VS Code prompt menu, 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. 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.
 
 ### Sample Conversation Flow
 
@@ -136,7 +135,7 @@ The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the same across
 - Shim path: Copilot uses `.github/copilot-instructions.md` (not `AGENTS.md` or `CLAUDE.md`).
 - Markdown import: Copilot shim has NO `@dflow/specs/shared/AI-AGENT-GUIDE.md` import. This contrasts with the Claude Code shim, which inlines via an `@` import.
 - Tool model: Copilot is IDE-based (chat panel + inline completions); Codex/Claude Code are CLI-based agents. Copilot interacts through the editor UI rather than a command-line session.
-- Workflow invocation: With CLI agents you may type `/dflow:*` to the agent process; with Copilot prefer plain-chat phrasing in the Copilot Chat or editor comments by default. If you opt in to `--command-adapters`, use adapter-native prompt names such as `/dflow-new-feature`.
+- Workflow invocation: canonical `/dflow:*` is shared vocabulary, but each tool's `/` parser behaves differently. In Copilot chat text, name `/dflow:<id>`; if you opt in to `--command-adapters`, the VS Code prompt menu name is `/dflow-<id>`, such as `/dflow-new-feature`.
 - Permission model: Copilot relies on the IDE's permission and extension sandbox. It may prompt for or be governed by editor-level approvals; CLI tools often have explicit sandbox flags and separate permission gates.
 
 ## Common Patterns and Gotchas
@@ -145,7 +144,7 @@ The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the same across
 - If Copilot appears to be working only from the shim text, ask it to open or read `dflow/specs/shared/AI-AGENT-GUIDE.md` before continuing.
 - Copilot's inline completions may suggest code without following Dflow workflows; explicitly request the workflow when you need spec-driven output.
 - Copilot chat context may not automatically include repository instruction files from `.github/` in all IDE versions; behavior varies by Copilot / IDE version (see footer note).
-- Use plain prose to name workflows when slash-prefixed forms are rejected by the IDE.
+- Use plain prose to name the canonical `/dflow:<id>` workflow when slash-prefixed forms are rejected by the IDE.
 - Prompt adapters are thin wrappers generated from the canonical command registry; do not hand-write or copy Dflow workflow steps under `.github/prompts/`.
 
 ## Where to Go Next

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

@@ -84,11 +84,11 @@ dflow configure-agents --command-adapters
 
 - `.github/prompts/dflow-<id>.prompt.md`
 
-這些 prompt 使用 adapter-native 命名，例如 `/dflow-new-feature` 或 IDE 的
-Quick Pick prompt 名稱。Prompt 內容只指向 canonical `/dflow:new-feature`
+這些 prompt 在 Copilot / VS Code prompt 選單中使用 `/dflow-<id>` 形式，例如
+`/dflow-new-feature`。Prompt 內容只指向 canonical `/dflow:new-feature`
 workflow 與 `dflow/specs/shared/AI-AGENT-GUIDE.md`，不複製 workflow 步驟。
-Dflow v1 不承諾 Copilot chat 一定支援 exact `/dflow:new-feature` colon 形式；
-canonical 名稱仍保留在 guide 與 prompt body 中。
+Copilot 的 `/` parser 行為與 Claude / Codex 不同：選單入口是 `/dflow-<id>`，
+但在 chat 文字中也可以直接說 canonical `/dflow:<id>`。
 
 ### 對話範例
 
@@ -152,9 +152,9 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 - 工具模型：Copilot 是 IDE-based（chat panel + inline completions）；
   Codex / Claude Code 是 CLI-based agent。Copilot 透過編輯器 UI 互動，而非
   command-line session。
-- Workflow 呼叫：使用 CLI agent 時可對 agent process 輸入 `/dflow:*`；使用
-  Copilot 時，預設建議在 Copilot Chat 或 editor comment 中使用普通文字描述。
-  若已 opt in `--command-adapters`，則使用 adapter-native prompt 名稱，例如
+- Workflow 呼叫：canonical `/dflow:*` 是共同詞彙，但各工具 `/` parser 行為不同。
+  Copilot 可在 chat 文字中使用 `/dflow:<id>`，若已 opt in
+  `--command-adapters`，VS Code prompt 選單名則是 `/dflow-<id>`，例如
   `/dflow-new-feature`。
 - Permission 模型：Copilot 依賴 IDE 的 permission 與 extension sandbox。它可能
   受 editor-level approvals 管理；CLI 工具通常有明確的 sandbox flags 與獨立的
@@ -170,7 +170,8 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
   需要 spec-driven 輸出時，請明確要求執行 workflow。
 - Copilot Chat context 不一定會在所有 IDE 版本中自動包含 `.github/` 目錄下的
   repository 指示檔；行為因 Copilot / IDE 版本而異（見頁尾說明）。
-- 當 slash-prefixed forms 被 IDE 拒絕時，改用普通文字描述 workflow 名稱。
+- 當 slash-prefixed forms 被 IDE 拒絕時，改用普通文字描述 canonical
+  `/dflow:<id>` workflow 名稱。
 - Prompt adapter 是從 canonical command registry 產生的薄 wrapper；不要在
   `.github/prompts/` 中手寫或複製 Dflow workflow 步驟。
 

package/lib/init.js

@@ -1134,10 +1134,10 @@ function addCommandAdapterItems(items, aiAgents, commandRegistry) {
   if (aiAgents.includes('claude')) {
     for (const command of commandRegistry) {
       items.push({
-        relativePath: `.claude/commands/dflow/dflow-${command.id}.md`,
+        relativePath: `.claude/commands/dflow/${command.id}.md`,
         source: 'generated:claude-command-adapter',
         notes: 'command adapter, derived from dflow command registry',
-        content: buildThinCommandWrapper(command),
+        content: buildThinCommandWrapper(command, `/dflow:${command.id}`),
         overwrite: true
       });
     }
@@ -1149,7 +1149,7 @@ function addCommandAdapterItems(items, aiAgents, commandRegistry) {
         relativePath: `.github/prompts/dflow-${command.id}.prompt.md`,
         source: 'generated:copilot-command-adapter',
         notes: 'command adapter, derived from dflow command registry',
-        content: buildThinCommandWrapper(command),
+        content: buildThinCommandWrapper(command, `/dflow-${command.id}`),
         overwrite: true
       });
     }
@@ -1172,18 +1172,23 @@ Codex does not install Dflow command files. When the developer asks for a
 canonical Dflow command, treat it as a text trigger, read the canonical guide,
 and execute the matching workflow or control command.
 
+If the CLI intercepts a slash-prefixed Dflow name such as \`/dflow:status\` as
+an unknown command, the developer may resend it without the slash, for example
+\`dflow:status\`. Treat that as the same Dflow text trigger, read the guide,
+and execute it.
+
 Recognized canonical triggers:
 
 ${triggers}
 `;
 }
 
-function buildThinCommandWrapper(command) {
+function buildThinCommandWrapper(command, displayName = command.label) {
   const argHint = command.argHint === '-'
     ? 'Argument hint: none.'
     : `Argument hint: ${command.argHint}.`;
 
-  return `# /dflow-${command.id}
+  return `# ${displayName}
 
 Execute the canonical \`${command.label}\` Dflow workflow or control command.
 
@@ -1777,7 +1782,7 @@ Recommended next steps:
 
 function printConfigureAgentsNextSteps(stdout, commandAdapters = false) {
   const commandAdapterStep = commandAdapters
-    ? '- Command adapters use adapter-native names such as `/dflow-new-feature`; canonical `/dflow:*` names remain defined in dflow/specs/shared/AI-AGENT-GUIDE.md.\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, manually remove stale `.claude/commands/dflow/dflow-*.md` files so Claude Code does not show both old and new command names.\n'
     : '';
 
   stdout.write(`

package/package.json

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