dflow-sdd-ddd 0.4.0 → 0.6.0

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
@@ -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,26 +133,50 @@ 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
 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
+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
@@ -161,12 +186,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
@@ -190,11 +216,16 @@ 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
+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

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,46 +67,47 @@ 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` 會在
 `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,24 +122,46 @@ 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 即可。
 
+### 選配 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
+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`）在各工具之間是相同的。
@@ -148,11 +171,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` 檔案讀取專案指示。
@@ -175,9 +199,13 @@ 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`、
+`.github/prompts` 或 `.agents/skills/dflow/SKILL.md` 形式的 Codex 專屬命令檔。
 
 **不要混淆 Codex `/init` 與 Dflow `init`。** Codex `/init` 為 Codex 建立
 通用的 `AGENTS.md` scaffold。Dflow 的設定是 `dflow init`（或免安裝路徑的

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,27 @@ 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 `/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
 
 A typical Copilot Chat workflow looks like this:
@@ -107,13 +130,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: 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
@@ -122,7 +144,8 @@ 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
 
@@ -133,4 +156,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 在 Copilot / VS Code prompt 選單中使用 `/dflow-<id>` 形式，例如
+`/dflow-new-feature`。Prompt 內容只指向 canonical `/dflow:new-feature`
+workflow 與 `dflow/specs/shared/AI-AGENT-GUIDE.md`，不複製 workflow 步驟。
+Copilot 的 `/` parser 行為與 Claude / Codex 不同：選單入口是 `/dflow-<id>`，
+但在 chat 文字中也可以直接說 canonical `/dflow:<id>`。
+
 ### 對話範例
 
 典型的 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 中使用普通文字描述。
+- 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 與獨立的
   permission gates。
@@ -149,7 +170,10 @@ 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 步驟。
 
 ## 下一步