dflow-sdd-ddd 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,61 @@
 
 ---
 
+## 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 行為語義 +
+scaffolding 單一來源化）、PROPOSAL-033（npm 版 installed 入口 + opt-in command
+adapters）、PROPOSAL-034（移除 Gemini 支援）
+
+**變更**：
+
+- **`/dflow:status` / `/dflow:next` / `/dflow:cancel` 行為語義進入 canonical guide**
+  （PROPOSAL-032）：四份 scaffolding `AI-AGENT-GUIDE.md`（brownfield / greenfield，
+  發佈用 templates 與 skill 副本）的 workflow 表補上這三個控制指令及其行為語義
+  （status 回報格式、next 確認語義、cancel 中止語義）。先前這些定義只存在於不被
+  npm 發佈的 `SKILL.md`，npm-installed 專案的 host AI 拿不到，導致 `/dflow:status`
+  形同失效。
+- **`dflow configure-agents --command-adapters`**（PROPOSAL-033）：新增 opt-in
+  選項，除 thin shim 外額外產生各工具原生的薄 command adapter（Claude
+  `.claude/commands/dflow/dflow-*.md`、Copilot `.github/prompts/dflow-*.prompt.md`，
+  Codex 取得 AGENTS.md command-adapters snippet），讓 `/dflow-*` 指令出現在工具
+  選單。預設不產生；canonical `/dflow:*` 名稱仍以 `AI-AGENT-GUIDE.md` 為準。
+  `docs/using-with-*` 同步更新。
+- **移除 Gemini 支援**（PROPOSAL-034）：`dflow init` / `dflow configure-agents`
+  不再提供 `GEMINI.md` 選項，並刪除 Gemini CLI per-tool docs 與 tutorial shim
+  fixture。
+
+---
+
 ## 0.4.0 — 2026-05-19 — Language-agnostic templates and skill source
 
 **Proposals**：PROPOSAL-030（language-agnostic templates and skill source；

package/README.en.md

@@ -20,7 +20,7 @@ The goal is not the process itself, but repeatable software change with clearer
 | **Three-layer documentation model** | Matches how feature branches actually evolve: phase (one propose-implement-archive cycle) / feature (the whole branch's running state and resume pointer) / system (cross-feature long-term knowledge). Many spec tools only ship phase + system, which breaks down when a feature branch spans multiple phases. Detailed below. |
 | **Change-depth-based tiers (T1/T2/T3)** | AI scales specification and verification by change depth: color/typo gets one inline row in `_index.md`; bug fixes get a lightweight spec plus focused verification; new features or bounded-context-level changes go through a full phase-spec plus layer-by-layer implementation planning / verification. Small changes don't get dragged down by the process. |
 | **Drift verification** | `/dflow:verify` cross-checks specs, domain documents, implementation, tests, and tech-debt records to surface the "documentation still describes the old behavior" drift that PR review by eye usually misses. |
-| **Multi-AI-tool rule sharing** | A canonical project guide plus thin tool-specific shims (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / Copilot instructions) — teams switching between Claude, Codex, Gemini, and Copilot don't have to maintain multiple copies of workflow rules. |
+| **Multi-AI-tool rule sharing** | A canonical project guide plus thin tool-specific shims (`CLAUDE.md` / `AGENTS.md` / Copilot instructions) — teams switching between Claude, Codex, and Copilot don't have to maintain multiple copies of workflow rules. |
 
 ## Get Started
 
@@ -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
@@ -208,7 +226,6 @@ files whose only job is to redirect the tool to the canonical guide):
 |---|---|
 | Codex / Copilot coding agent | `AGENTS.md` |
 | Claude Code | `CLAUDE.md` |
-| Gemini CLI | `GEMINI.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
 If one of those files already exists, Dflow leaves it unchanged and writes a
@@ -217,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
@@ -225,7 +243,6 @@ workflow commands appear in a given AI tool, see the per-tool guides under
 
 - [Using Dflow with Claude Code](docs/using-with-claude-code.en.md)
 - [Using Dflow with Codex CLI](docs/using-with-codex.en.md)
-- [Using Dflow with Gemini CLI](docs/using-with-gemini-cli.en.md)
 - [Using Dflow with GitHub Copilot](docs/using-with-github-copilot.en.md)
 
 Init does not copy the `tutorial/` directory into your project. The
@@ -330,7 +347,7 @@ npm package is `0.2.0`, covering:
 
 - Project initialization (`dflow init`)
 - Workflow documentation (the `/dflow:*` flows)
-- Multi-AI agent setup (CLAUDE.md / AGENTS.md / GEMINI.md / Copilot instructions shims)
+- Multi-AI agent setup (CLAUDE.md / AGENTS.md / Copilot instructions shims)
 - AI-agent-readable SDD/DDD guidance
 - Public migration tooling: manual migration guide plus `dflow doctor` read-only health check
 - Public onboarding: evaluator guide and per-tool walkthroughs for Claude Code and Codex CLI

package/README.md

@@ -20,7 +20,7 @@ Dflow 是一套 spec-first 的工作流程工具集，專為 AI 輔助軟體開
 | **三層文件模型** | 對應 feature branch 的實際節奏：phase（單次提案-實作循環）/ feature（整條 branch 的累積狀態與接續指引）/ system（跨 feature 的長期知識）。許多 spec 工具只有 phase + system 兩層，多次迭代的 feature branch 跨多個 phase 時就會失真。下方有完整說明。 |
 | **依改動深淺的 Tier 制（T1/T2/T3）** | AI 依改動深淺自動決定規格與驗證量級：改顏色 / typo 只需 `_index.md` 一行；bug fix 用 lightweight spec + 聚焦驗證；新 feature 或動到 bounded context 才走完整 phase-spec + 分層實作計畫 / 驗證。小修改不會被流程拖累。 |
 | **漂移驗證** | `/dflow:verify` 把規格、領域文件、實作、測試、技術債紀錄做交叉比對，找出 PR review 人眼看不出來的「文件還在描述舊行為」漂移。 |
-| **多 AI 工具共用一份規則** | Canonical 專案指南 + 各工具薄 shim（`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / Copilot instructions），團隊在 Claude / Codex / Gemini / Copilot 之間切換時不必維護多份 workflow 規則。 |
+| **多 AI 工具共用一份規則** | Canonical 專案指南 + 各工具薄 shim（`CLAUDE.md` / `AGENTS.md` / Copilot instructions），團隊在 Claude / Codex / Copilot 之間切換時不必維護多份 workflow 規則。 |
 
 ## 開始使用
 
@@ -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/` 工作區，再把流程引入正式程式碼。
 
@@ -184,18 +198,16 @@ Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指
 |---|---|
 | Codex / Copilot coding agent | `AGENTS.md` |
 | Claude Code | `CLAUDE.md` |
-| Gemini CLI | `GEMINI.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
 若這些檔案已存在，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 指南：
 
 - [在 Claude Code 中使用 Dflow](docs/using-with-claude-code.md)
 - [在 Codex CLI 中使用 Dflow](docs/using-with-codex.md)
-- [在 Gemini CLI 中使用 Dflow](docs/using-with-gemini-cli.md)
 - [在 GitHub Copilot 中使用 Dflow](docs/using-with-github-copilot.md)
 
 Init 不會把 `tutorial/` 目錄複製進你的專案。[`tutorial/`](tutorial/README.md) 目錄存放在本 source repository，作為理解 Dflow 如何在 Greenfield / Brownfield 劇情中運作的評估材料。
@@ -292,7 +304,7 @@ Dflow 目前以 `dflow-sdd-ddd` 名稱發佈於 npm。最新發佈版本為 `0.2
 
 - 專案初始化（`dflow init`）
 - Workflow 文件（`/dflow:*` 流程）
-- 多 AI agent 設定（CLAUDE.md / AGENTS.md / GEMINI.md / Copilot instructions shim）
+- 多 AI agent 設定（CLAUDE.md / AGENTS.md / Copilot instructions shim）
 - AI agent 可讀的 SDD/DDD 指引
 - 公開 migration tooling：手動 migration guide 與 `dflow doctor` 唯讀健康檢查
 - 公開 onboarding：evaluator 指南、Claude Code / Codex CLI 的 per-tool walkthrough

package/TEMPLATE-COVERAGE.md

@@ -24,7 +24,7 @@ The matrix lists Brownfield / Greenfield logical template parity so reviewers ca
 | Tech debt | Brownfield: `dflow/specs/migration/tech-debt.md`; Greenfield: `dflow/specs/architecture/tech-debt.md` | `templates/tech-debt.md` | `templates/tech-debt.md` | Same backlog intent | Brownfield migration focus; Greenfield architecture focus | - |
 | ADR guide | `dflow/specs/architecture/decisions/README.md` | n/a | `scaffolding/architecture-decisions-README.md` | Greenfield only | Brownfield not applicable | - |
 | Project AI guide | `dflow/specs/shared/AI-AGENT-GUIDE.md` when at least one AI agent is selected during init | `scaffolding/AI-AGENT-GUIDE.md` | `scaffolding/AI-AGENT-GUIDE.md` | Same canonical tool-neutral workflow guide and source-of-truth pointers | Track-specific seeded values and available source-of-truth paths may differ | - |
-| AI tool shims | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, or merge snippets under `dflow/specs/shared/` | generated by CLI | generated by CLI | Thin files must point back to `dflow/specs/shared/AI-AGENT-GUIDE.md`; existing files are not overwritten | Tool-specific import hints differ | - |
+| AI tool shims | `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, or merge snippets under `dflow/specs/shared/` | generated by CLI | generated by CLI | Thin files must point back to `dflow/specs/shared/AI-AGENT-GUIDE.md`; existing files are not overwritten | Tool-specific import hints differ | - |
 | Legacy Claude guide template | `<project root>/CLAUDE.md` | `templates/CLAUDE.md` | `templates/CLAUDE.md` | H2 navigation and H3 structural headings aligned (canonical English, per F-01 Path A) | Greenfield includes Aggregate / Architecture Decisions and other Greenfield-specific H3 sections | - |
 
 ## Reference Flow Parity

package/bin/dflow.js

@@ -29,12 +29,15 @@ optional starter files, and AI coding agents before showing a full file preview.
 
 function printConfigureAgentsHelp() {
   process.stdout.write(`Usage:
-  dflow configure-agents
+  dflow configure-agents [--command-adapters]
 
 Adds AI agent instruction files to an existing Dflow project.
-The command can create AGENTS.md, CLAUDE.md, GEMINI.md, and
+The command can create AGENTS.md, CLAUDE.md, and
 .github/copilot-instructions.md shims that point to the canonical
 dflow/specs/shared/AI-AGENT-GUIDE.md file.
+
+Options:
+  --command-adapters  Also generate tool-native thin wrappers for supported tools.
 `);
 }
 
@@ -91,8 +94,10 @@ async function main() {
       return 0;
     }
 
-    if (args.length > 1) {
-      process.stderr.write(`Unsupported configure-agents option: ${args.slice(1).join(' ')}\n`);
+    const configureOptions = args.slice(1);
+    const unsupportedConfigureOptions = configureOptions.filter((arg) => arg !== '--command-adapters');
+    if (unsupportedConfigureOptions.length > 0) {
+      process.stderr.write(`Unsupported configure-agents option: ${unsupportedConfigureOptions.join(' ')}\n`);
       return 1;
     }
 
@@ -100,7 +105,8 @@ async function main() {
       cwd: process.cwd(),
       stdin: process.stdin,
       stdout: process.stdout,
-      stderr: process.stderr
+      stderr: process.stderr,
+      commandAdapters: configureOptions.includes('--command-adapters')
     });
   }
 

package/docs/evaluating-dflow.en.md

@@ -37,9 +37,8 @@ in your project's `dflow/specs/` directory and AI instruction files.
   for the full tree.
 - A canonical project guide at `dflow/specs/shared/AI-AGENT-GUIDE.md`.
 - Mergeable AI agent instruction files for the tools you select (e.g.,
-  `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
-  `.github/copilot-instructions.md`). Each is a thin pointer to the
-  canonical guide.
+  `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`). Each is a
+  thin pointer to the canonical guide.
 
 `init` does **not**:
 
@@ -58,7 +57,6 @@ or more tools and Dflow writes the corresponding shim:
 |---|---|
 | Codex / Copilot coding agent | `AGENTS.md` |
 | Claude Code | `CLAUDE.md` |
-| Gemini CLI | `GEMINI.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
 Each shim points back to the canonical
@@ -66,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.
 
@@ -81,7 +83,6 @@ commands appear in conversation, see the per-tool guides:
 
 - [Using Dflow with Claude Code](using-with-claude-code.en.md)
 - [Using Dflow with Codex CLI](using-with-codex.en.md)
-- [Using Dflow with Gemini CLI](using-with-gemini-cli.en.md)
 - [Using Dflow with GitHub Copilot](using-with-github-copilot.en.md)
 
 ## Greenfield or Brownfield: Choosing a Track
@@ -147,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

@@ -26,7 +26,7 @@ Dflow 是 Markdown-based 的 workflow 材料加上一個 scaffolding CLI。它
 - `dflow/specs/` workspace（概覽、慣例、領域詞彙表、context map、架構 / 技術債、功能 active/completed）。完整目錄樹見
   [`README.md` "Init 產生的檔案"](../README.md#init-產生的檔案)。
 - 位於 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的 canonical 專案指南。
-- 你所選工具的可合併 AI 指示檔（例如 `CLAUDE.md`、`AGENTS.md`、`GEMINI.md`、`.github/copilot-instructions.md`）。每個都是指向 canonical 指南的薄 shim。
+- 你所選工具的可合併 AI 指示檔（例如 `CLAUDE.md`、`AGENTS.md`、`.github/copilot-instructions.md`）。每個都是指向 canonical 指南的薄 shim。
 
 `init` **不會**：
 
@@ -43,22 +43,24 @@ Dflow 支援多種 AI 程式設計助理。跑完 `init` 後，你選取一個
 |---|---|
 | Codex / Copilot coding agent | `AGENTS.md` |
 | Claude Code | `CLAUDE.md` |
-| Gemini CLI | `GEMINI.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
 每個 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 在對話中的呈現方式，見各工具指南：
 
 - [在 Claude Code 中使用 Dflow](using-with-claude-code.md)
 - [在 Codex CLI 中使用 Dflow](using-with-codex.md)
-- [在 Gemini CLI 中使用 Dflow](using-with-gemini-cli.md)
 - [在 GitHub Copilot 中使用 Dflow](using-with-github-copilot.md)
 
 ## Greenfield 或 Brownfield：選擇 Track
@@ -113,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/migrating-to-dflow-v1.md

@@ -163,7 +163,7 @@ shell command instead.
 V1 separates the canonical project guide from each per-tool
 instruction file (PROPOSAL-020). The canonical guide lives at
 `dflow/specs/shared/AI-AGENT-GUIDE.md`. Per-tool files (`AGENTS.md`,
-`CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`) are thin
+`CLAUDE.md`, `.github/copilot-instructions.md`) are thin
 shims pointing at the canonical guide.
 
 If your project's `CLAUDE.md` (or equivalent) was generated by an

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
 
-Dflow's `/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,34 @@ 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
+initialized project:
+
+```bash
+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/<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. 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
 
 The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is identical
@@ -140,7 +170,6 @@ across tools. Only the root-level shim differs:
 |---|---|---|
 | Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
 | Codex / Copilot coding agent | `AGENTS.md` | Reads file content directly when starting |
-| Gemini CLI | `GEMINI.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
 | GitHub Copilot | `.github/copilot-instructions.md` | Reads file content directly |
 
 You can run `dflow configure-agents` later to add another tool's shim without
@@ -159,9 +188,19 @@ spec locations, or SDD constraints to `CLAUDE.md`, those belong in
 that other tools' shims don't drift away from it.
 
 **`/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. You can use
-them immediately after `init` without any Claude Code configuration.
+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
+project still has legacy `.claude/skills/sdd-ddd-*` skills, choose either
+those skills or `--command-adapters`. If they must temporarily coexist, use
+Claude Code skill override / `disable-model-invocation` settings to prevent
+the legacy skill from auto-triggering. Otherwise the same `/dflow:*` intent
+may trigger both the legacy skill and the installed adapter. Installed
+adapter wrappers must stay thin pointers and should not copy workflow
+semantics.
 
 **Permission gates and Dflow workflow gates are separate.** Claude Code may
 ask permission to run a tool (e.g., write a file). Dflow's workflows have

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 的 `/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,31 @@ 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 看到工具原生的命令入口，可在已初始化的專案中執行：
+
+```bash
+dflow configure-agents --command-adapters
+```
+
+選擇 Claude Code 後，Dflow 會從 canonical guide 內的 command registry
+投影產生薄 wrapper：
+
+- `.claude/commands/dflow/<id>.md`
+
+這些 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 工具的差異
 
 canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間是相同的。
@@ -129,7 +156,6 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 |---|---|---|
 | Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
 | Codex / Copilot coding agent | `AGENTS.md` | 啟動時直接讀取檔案內容 |
-| Gemini CLI | `GEMINI.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
 | GitHub Copilot | `.github/copilot-instructions.md` | 直接讀取檔案內容 |
 
 你可以之後執行 `dflow configure-agents` 來新增另一個工具的 shim，而不需要重跑
@@ -146,9 +172,17 @@ 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 表識別的純文字模式。
-你在 `init` 之後就可以立即使用它們，不需要任何 Claude Code 設定。
+**`/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`
+之間擇一使用。若必須暫時共存，請用 Claude Code 的 skill override /
+`disable-model-invocation` 設定避免 legacy skill 自動觸發，否則同一個
+`/dflow:*` 意圖可能同時觸發 legacy skill 與 installed adapter。Installed
+adapter wrapper 必須保持薄指標，不應複製 workflow 語義。
 
 **Permission gates 與 Dflow workflow gates 是分開的。** Claude Code 可能會詢問
 執行某個工具的權限（例如寫入檔案）。Dflow 的 workflow 有自己的審核關卡（例如