dflow-sdd-ddd 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,32 @@
 
 ---
 
+## 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
 
@@ -208,7 +208,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
@@ -225,7 +224,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 +328,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 規則。 |
 
 ## 開始使用
 
@@ -184,7 +184,6 @@ 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 規則。
@@ -195,7 +194,6 @@ Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指
 
 - [在 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 +290,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
@@ -81,7 +79,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

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,7 +43,6 @@ 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`。實際意義：
@@ -58,7 +57,6 @@ Dflow 支援多種 AI 程式設計助理。跑完 `init` 後，你選取一個
 
 - [在 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

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,9 +81,9 @@ 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:
+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:
 
 ```text
 /dflow:new-feature
@@ -131,6 +131,27 @@ 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.
 
+### 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/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.
+
 ## Differences vs Other AI Tools
 
 The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is identical
@@ -140,7 +161,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
@@ -158,10 +178,20 @@ 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.
 
-**`/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.
+**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
+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,9 +73,9 @@ 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:*` slash commands 是 AI 透過
+`AI-AGENT-GUIDE.md` 中的 workflow 表識別的 workflow 名稱，不是 Claude Code
+內建的 slash command 系統。你以普通對話方式輸入它們：
 
 ```text
 /dflow:new-feature
@@ -120,6 +120,25 @@ skill 檔案來執行它們。
 如果你忘了指令名稱，問 Claude Code「what dflow workflows are available?」
 即可 —— 答案會從它已載入的 workflow 表中給出。
 
+### 選配 Command Adapters
+
+如果想讓 Claude Code 看到工具原生的命令入口，可在已初始化的專案中執行：
+
+```bash
+dflow configure-agents --command-adapters
+```
+
+選擇 Claude Code 後，Dflow 會從 canonical guide 內的 command registry
+投影產生薄 wrapper：
+
+- `.claude/commands/dflow/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 中。
+
 ## 與其他 AI 工具的差異
 
 canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間是相同的。
@@ -129,7 +148,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 +164,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 系統中安裝任何東西。Slash commands 是 AI 從 workflow 表識別的純文字模式。
+若你之後執行 `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 有自己的審核關卡（例如

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

@@ -62,7 +62,7 @@ Two things matter when Codex starts in this project:
 1. Codex CLI reads `AGENTS.md` as project instructions. This is Codex's
    standard repository-instruction mechanism.
 2. The Dflow shim does not include a Markdown import line. Unlike the
-   Claude Code and Gemini shims, generated `AGENTS.md` does not contain
+   Claude Code shim, generated `AGENTS.md` does not contain
    `@dflow/specs/shared/AI-AGENT-GUIDE.md`.
 
 That means Codex sees the pointer immediately, but the canonical Dflow guide
@@ -76,7 +76,7 @@ The canonical guide is where the real workflow rules live: project context
 (track, tech stack, prose language), the Dflow workflow table,
 source-of-truth file paths, and core SDD/DDD rules. The `AGENTS.md` shim
 stays small so the same canonical guide can serve Codex CLI, Claude Code,
-Gemini CLI, GitHub Copilot, and other tools.
+GitHub Copilot, and other tools.
 
 If an `AGENTS.md` already existed in the project, `init` does not overwrite
 it. If the existing file does not already point to
@@ -152,6 +152,26 @@ If you forget a workflow name, ask Codex to read
 `dflow/specs/shared/AI-AGENT-GUIDE.md` and list the available Dflow
 workflows.
 
+### Codex Behavior With Optional Command Adapters
+
+For Codex, `dflow configure-agents --command-adapters` strengthens text
+triggers only. It does not create Codex command files and it does not add
+`.agents/skills/dflow/SKILL.md`. Codex v1 has no Dflow command-file adapter
+equivalent to Claude `.claude/commands` or Copilot `.github/prompts`.
+
+When you select `AGENTS.md - Codex / Copilot coding agent` in
+`--command-adapters` mode and Dflow can create a new `AGENTS.md` shim, the
+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.
+```
+
+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.
+
 ## Differences vs Other AI Tools
 
 The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is identical
@@ -161,12 +181,13 @@ 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` | Project instructions load the shim; Codex must follow the pointer and read the guide |
-| Gemini CLI | `GEMINI.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
 | GitHub Copilot | `.github/copilot-instructions.md` | Reads repository instructions directly |
 
 You can run `dflow configure-agents` later to add another tool's shim
-without re-running `init`. Multiple tools can be active in the same project
-and stay synchronized via the canonical guide.
+without re-running `init`. If you need tool-native wrappers for Claude or
+Copilot, opt in with `dflow configure-agents --command-adapters`. Codex
+remains text-trigger-only in that mode. Multiple tools can be active in the
+same project and stay synchronized via the canonical guide.
 
 Codex also has its own project-instruction layering. It can read global
 instructions from Codex home and project instructions from `AGENTS.md` files
@@ -196,6 +217,11 @@ 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.
 
+**Codex does not generate command files.** Even with `--command-adapters`,
+Codex only strengthens text-trigger guidance in `AGENTS.md` / merge
+snippets. Do not expect Codex-specific files under `.claude/commands`,
+`.github/prompts`, or `.agents/skills/dflow/SKILL.md`.
+
 **Do not confuse Codex `/init` with Dflow `init`.** Codex `/init` creates a
 generic `AGENTS.md` scaffold for Codex. Dflow setup is `dflow init` (or
 `npx dflow-sdd-ddd init` on the no-install path), and adding later tool shims

package/docs/using-with-codex.md

@@ -56,8 +56,8 @@ Codex 在這個專案中啟動時，有兩件事值得注意：
 
 1. Codex CLI 將 `AGENTS.md` 作為專案指示讀取。這是 Codex 的
    標準 repository 指示機制。
-2. Dflow shim 不含 Markdown import 那一行。與 Claude Code 和 Gemini 的
-   shim 不同，產生的 `AGENTS.md` 不含 `@dflow/specs/shared/AI-AGENT-GUIDE.md`。
+2. Dflow shim 不含 Markdown import 那一行。與 Claude Code 的 shim 不同，
+   產生的 `AGENTS.md` 不含 `@dflow/specs/shared/AI-AGENT-GUIDE.md`。
 
 這意味著 Codex 能立即看到指標，但 canonical Dflow 指南不會由 shim 自動 inline 嵌入。
 在規劃或編輯之前，Codex 應跟著指標讀取 `dflow/specs/shared/AI-AGENT-GUIDE.md`。
@@ -67,7 +67,7 @@ read and follow `dflow/specs/shared/AI-AGENT-GUIDE.md`.」
 canonical 指南是實際 workflow 規則的所在：專案上下文（track、技術棧、
 文章語言）、Dflow workflow 表、source-of-truth 檔案路徑，以及核心 SDD/DDD 規則。
 `AGENTS.md` shim 刻意保持精簡，這樣 canonical 指南就能同時服務 Codex CLI、
-Claude Code、Gemini CLI、GitHub Copilot 與其他工具。
+Claude Code、GitHub Copilot 與其他工具。
 
 如果專案中已有 `AGENTS.md`，`init` 不會覆蓋它。若既有檔案尚未指向
 `dflow/specs/shared/AI-AGENT-GUIDE.md`，`init` 會在
@@ -139,6 +139,24 @@ finish-feature 漂移（drift）檢查。確切的流程取決於你進入的是
 如果你忘了 workflow 名稱，請 Codex 讀取 `dflow/specs/shared/AI-AGENT-GUIDE.md`
 並列出可用的 Dflow workflow 即可。
 
+### 選配 Command Adapters 的 Codex 行為
+
+`dflow configure-agents --command-adapters` 對 Codex 採文字 trigger 強化，不會建立
+Codex 命令檔，也不會新增 `.agents/skills/dflow/SKILL.md`。Codex v1 沒有與
+Claude `.claude/commands` 或 Copilot `.github/prompts` 對等的 Dflow command-file
+adapter。
+
+當你在 `--command-adapters` 模式下選擇 `AGENTS.md - Codex / Copilot coding agent`
+且 Dflow 可以建立新的 `AGENTS.md` shim 時，shim 會加入從 canonical command
+registry 產生的 trigger 清單。這些 trigger 仍是文字提示，例如：
+
+```text
+Run the Dflow /dflow:new-feature workflow.
+```
+
+如果專案已有自訂 `AGENTS.md`，Dflow 仍會保留既有檔案；請依產生的 merge snippet
+或文件指引手動合併 Dflow 指標。
+
 ## 與其他 AI 工具的差異
 
 canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間是相同的。
@@ -148,11 +166,12 @@ 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` | 專案指示載入 shim；Codex 須跟著指標讀取指南 |
-| Gemini CLI | `GEMINI.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
 | GitHub Copilot | `.github/copilot-instructions.md` | 直接讀取 repository 指示 |
 
 你可以之後執行 `dflow configure-agents` 來新增另一個工具的 shim，而不需要重跑
-`init`。同一個專案可以同時啟用多個工具，並透過 canonical 指南保持同步。
+`init`。若需要 Claude / Copilot 的工具原生命令 wrapper，可 opt in
+`dflow configure-agents --command-adapters`。Codex 在此模式下仍是文字 trigger
+only。同一個專案可以同時啟用多個工具，並透過 canonical 指南保持同步。
 
 Codex 也有自己的專案指示分層機制。它可以從 Codex home 讀取全域指示、
 從專案根目錄到當前工作目錄之間的 `AGENTS.md` 檔案讀取專案指示。
@@ -179,6 +198,10 @@ SDD 約束加入 `AGENTS.md`，這些內容應該放到
 輸入 Dflow workflow 名稱。`/dflow:*` 的直通行為需依所用的 Codex 版本向
 maintainer 確認。
 
+**Codex 不產生命令檔。** 即使使用 `--command-adapters`，Codex 也只強化
+`AGENTS.md` / merge snippet 中的文字 trigger 說明。不要期待 `.claude/commands`、
+`.github/prompts` 或 `.agents/skills/dflow/SKILL.md` 形式的 Codex 專屬命令檔。
+
 **不要混淆 Codex `/init` 與 Dflow `init`。** Codex `/init` 為 Codex 建立
 通用的 `AGENTS.md` scaffold。Dflow 的設定是 `dflow init`（或免安裝路徑的
 `npx dflow-sdd-ddd init`），之後新增工具 shim 則是 `dflow configure-agents`。

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

@@ -42,7 +42,9 @@ Key points:
 
 ## Using Dflow Workflow Commands with GitHub Copilot
 
-Copilot is an IDE-first assistant (chat panel + inline completions), not a CLI tool. Treat Dflow workflow names as plain chat instructions rather than CLI slash commands:
+By default, Copilot is an IDE-first assistant (chat panel + inline
+completions), not a CLI tool. Treat Dflow workflow names as plain chat
+instructions rather than CLI slash commands:
 
 - In the Copilot Chat: "Run the Dflow /dflow:new-feature workflow" — Copilot should read the canonical guide and proceed.
 - In code comments or editor chat, describe the workflow as plain text: `Run the Dflow /dflow:new-feature workflow.`
@@ -60,6 +62,28 @@ Available workflow entry points:
 | `/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. |
 
+### Optional Prompt Adapters
+
+If you want tool-native entries in a Copilot / VS Code environment that
+supports prompt files, run this in an initialized project:
+
+```bash
+dflow configure-agents --command-adapters
+```
+
+After you select GitHub Copilot, Dflow projects thin prompt wrappers from the
+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.
+
 ### Sample Conversation Flow
 
 A typical Copilot Chat workflow looks like this:
@@ -107,13 +131,12 @@ The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the same across
 |---|---|---|
 | GitHub Copilot | `.github/copilot-instructions.md` | Reads repository instructions directly |
 | Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
-| Gemini CLI | `GEMINI.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
 | Codex / Copilot coding agent | `AGENTS.md` | Reads file content directly when starting |
 
 - 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 Claude/Gemini CLI shims which inline via `@` imports.
+- 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.
+- 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`.
 - 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
@@ -123,6 +146,7 @@ The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the same across
 - 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.
+- 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
 
@@ -133,4 +157,4 @@ The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the same across
 
 ---
 
-Note on IDE behavior: Slash-command passthrough and automatic inclusion of `.github/` instruction files vary by Copilot / IDE version. Confirm with a maintainer before relying on exact semantics.
+Note on IDE behavior: Slash-command passthrough and automatic inclusion of `.github/` instruction files vary by Copilot / IDE version. Confirm with a maintainer before relying on exact semantics.

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

@@ -49,8 +49,8 @@ Before planning or editing code, read and follow:
 
 ## 在 GitHub Copilot 中使用 Dflow Workflow 指令
 
-Copilot 是 IDE 優先的助理（chat panel + inline completions），不是 CLI 工具。
-請把 Dflow workflow 名稱當成普通的對話指示，而非 CLI slash command：
+預設情況下，Copilot 是 IDE 優先的助理（chat panel + inline completions），不是
+CLI 工具。請把 Dflow workflow 名稱當成普通的對話指示，而非 CLI slash command：
 
 - 在 Copilot Chat 中：「Run the Dflow /dflow:new-feature workflow」—— Copilot
   應讀取 canonical 指南並繼續執行。
@@ -70,6 +70,26 @@ Copilot 是 IDE 優先的助理（chat panel + inline completions），不是 CL
 | `/dflow:pr-review` | 變更已準備好進行 SDD/DDD review。 |
 | `/dflow:report-dflow-feedback` | 你發現了 Dflow 的問題或改進點，想要一份清理過的上游回饋草稿。 |
 
+### 選配 Prompt Adapters
+
+如果想在支援 prompt files 的 Copilot / VS Code 環境中使用工具原生入口，可在
+已初始化的專案中執行：
+
+```bash
+dflow configure-agents --command-adapters
+```
+
+選擇 GitHub Copilot 後，Dflow 會從 canonical guide 內的 command registry
+投影產生薄 prompt wrapper：
+
+- `.github/prompts/dflow-<id>.prompt.md`
+
+這些 prompt 使用 adapter-native 命名，例如 `/dflow-new-feature` 或 IDE 的
+Quick Pick prompt 名稱。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 Chat workflow 如下：
@@ -123,18 +143,19 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 |---|---|---|
 | GitHub Copilot | `.github/copilot-instructions.md` | 直接讀取 repository 指示 |
 | Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
-| Gemini CLI | `GEMINI.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
 | Codex / Copilot coding agent | `AGENTS.md` | 啟動時直接讀取檔案內容 |
 
 - Shim 路徑：Copilot 使用 `.github/copilot-instructions.md`（不是 `AGENTS.md`
   或 `CLAUDE.md`）。
 - Markdown import：Copilot shim 不含 `@dflow/specs/shared/AI-AGENT-GUIDE.md`
-  import。這點與 Claude Code / Gemini CLI 的 shim 透過 `@` import inline 嵌入不同。
+  import。這點與 Claude Code 的 shim 透過 `@` import inline 嵌入不同。
 - 工具模型：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 中使用普通文字描述。
+  Copilot 時，預設建議在 Copilot Chat 或 editor comment 中使用普通文字描述。
+  若已 opt in `--command-adapters`，則使用 adapter-native prompt 名稱，例如
+  `/dflow-new-feature`。
 - Permission 模型：Copilot 依賴 IDE 的 permission 與 extension sandbox。它可能
   受 editor-level approvals 管理；CLI 工具通常有明確的 sandbox flags 與獨立的
   permission gates。
@@ -150,6 +171,8 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 - Copilot Chat context 不一定會在所有 IDE 版本中自動包含 `.github/` 目錄下的
   repository 指示檔；行為因 Copilot / IDE 版本而異（見頁尾說明）。
 - 當 slash-prefixed forms 被 IDE 拒絕時，改用普通文字描述 workflow 名稱。
+- Prompt adapter 是從 canonical command registry 產生的薄 wrapper；不要在
+  `.github/prompts/` 中手寫或複製 Dflow workflow 步驟。
 
 ## 下一步