dflow-sdd-ddd 0.9.0 → 0.10.0

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

@@ -2,13 +2,13 @@
 
 > [繁體中文](using-with-github-copilot.md) | **English**
 
-A walk-through of what Dflow looks like when your AI coding agent is GitHub Copilot (IDE chat + inline completions). About 10 minutes to read.
+A walk-through of what Dflow looks like when your AI coding agent is GitHub Copilot. GitHub Copilot has two surfaces — **VS Code Copilot Chat** (the in-IDE chat panel + inline completions) and **GitHub Copilot CLI** (the terminal) — and they trigger Dflow and invoke commands differently, so this guide covers them separately. About 10 minutes to read.
 
 This guide focuses on the Copilot experience specifically. For the tool-neutral evaluation flow, see [`docs/evaluating-dflow.en.md`](evaluating-dflow.en.md). For the full Get Started and feature list, see [`README.md`](../README.en.md).
 
 ## Who This Guide Is For
 
-You are using or evaluating Dflow with GitHub Copilot in an IDE (e.g., VS Code). This guide covers what Copilot sees after `init`, the repository shim location, how to invoke Dflow workflows from the IDE, and Copilot-specific UX and permission patterns worth knowing.
+You are using or evaluating Dflow with GitHub Copilot, in either VS Code Copilot Chat or the GitHub Copilot CLI. This guide covers what Copilot sees after `init`, the repository shim location, how to invoke Dflow workflows on each surface, and Copilot-specific UX and permission patterns worth knowing.
 
 ## Prerequisites
 
@@ -30,26 +30,39 @@ Example generated shim:
 
 This project uses Dflow for spec-first AI-assisted development.
 
-Before planning or editing code, read and follow:
+For spec-impacting work — a new feature, a change to product, user-facing, or
+domain behavior, a new requirement, or a bug-fix workflow — read and follow:
 
-- `dflow/specs/shared/AI-AGENT-GUIDE.md`
+- `dflow/specs/shared/AI-AGENT-GUIDE.md` — command registry, routing rules, and project context.
+- `dflow/specs/shared/dflow-workflows/` — vendored workflow bundle with executable step definitions.
+
+For routine work (refactors, renames, chores, formatting, dependency bumps, or
+general code questions), proceed normally; you need not read the guide first.
+
+Keep tool-specific instruction files small. The guide and workflow bundle are
+the authoritative sources for Dflow workflow rules, slash-command behavior,
+spec locations, and SDD/DDD constraints.
 ```
 
 Key points:
 
 - The Copilot shim is located at `.github/copilot-instructions.md` (see `lib/init.js` mapping).
-- The Copilot shim does NOT include a Markdown `@` import. It points to the canonical guide by path only. Readers must open `dflow/specs/shared/AI-AGENT-GUIDE.md` explicitly.
+- The Copilot shim is a thin pointer to the canonical guide by path. Readers must open `dflow/specs/shared/AI-AGENT-GUIDE.md` explicitly.
 
 ## Using Dflow Workflow Commands with GitHub Copilot
 
-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:
+GitHub Copilot has two surfaces, and Dflow triggering and command behavior
+differ between them — sort out which one you are on first:
 
-- 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.`
+- **VS Code Copilot Chat** (the in-IDE chat panel): natural language **does
+  auto-trigger** Dflow's skill; if you opt in to prompt adapters, the
+  tool-native command `/dflow-<id>` (hyphen) is also available.
+- **GitHub Copilot CLI** (the terminal): there is **no** natural-language
+  auto-trigger; you first type `/dflow` to **manually engage** the skill and let
+  it guide you; the per-id `/dflow-<id>` command is **not available** in the CLI.
 
-Available workflow entry points:
+Both surfaces share the same set of workflow entry points (same vocabulary;
+only how you invoke them differs):
 
 | Command | Use when |
 |---|---|
@@ -62,10 +75,54 @@ 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. |
 
+> **Syntax note**: in the table, `/dflow:<id>` (**colon**) is Dflow's canonical
+> vocabulary and the **actual command** syntax for Claude / Codex. Copilot's
+> prompt-adapter command uses `/dflow-<id>` (**hyphen**) instead, and only in VS
+> Code; do not type the colon form literally as a command in Copilot (the
+> Copilot CLI parses `/dflow:new-feature` down to `/dflow`). The two
+> sub-sections below cover how to invoke on each surface.
+
+### Surface A: VS Code Copilot Chat
+
+- **Auto-trigger**: yes. Describe what you want in plain natural language in chat
+  (e.g., "I want to add CSV export for users") and Dflow's skill engages on its
+  own, picks the matching workflow, and starts in **suggest-and-wait** mode (it
+  proposes a command and waits for your confirmation) rather than running the
+  whole workflow unprompted.
+- **Command**: `/dflow-<id>` (**hyphen**) works, but first run
+  `dflow configure-agents --command-adapters` in the project to project
+  `.github/prompts/dflow-<id>.prompt.md` (see the next section); then pick
+  `/dflow-new-feature` from the prompt menu.
+- **Plain text also works**: you can also describe the workflow in plain chat
+  text (e.g., `Run the Dflow /dflow:new-feature workflow.`) — here
+  `/dflow:new-feature` is just a **text reference**, not something parsed as a
+  command.
+
+### Surface B: GitHub Copilot CLI
+
+- **Auto-trigger**: **none**. Sending plain natural language does **not** engage
+  Dflow's skill.
+- **How to engage**: type `/dflow` (no id suffix) to **manually engage** the
+  skill; once engaged it lists the available workflows / asks what you want to
+  do, and you then continue with a **natural-language description** (e.g., "I
+  want to add CSV export") or by replying to the options it lists. It also runs
+  in suggest-and-wait mode.
+- **Command**: the per-id `/dflow-<id>` is **not available** in the CLI —
+  `.github/prompts/dflow-<id>.prompt.md` is VS Code Chat-specific and the **CLI
+  does not read it**, so `/dflow-new-feature` returns Unknown; the colon form
+  `/dflow:new-feature` is parsed down to `/dflow`. The CLI has no per-id command
+  entry; use the "`/dflow` to engage → describe in conversation" path instead.
+- **What about the command the skill suggests**: once engaged, the skill may
+  suggest a `/dflow:<id>` (that is the canonical form written for Claude /
+  Codex). In Copilot you do **not** need to type that command string literally —
+  in the CLI the skill is already engaged, so just describe the workflow you want
+  in conversation or confirm; in VS Code, use the `/dflow-<id>` (hyphen)
+  prompt-menu entry instead.
+
 ### 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:
+If you want tool-native **command** entries in a VS Code Copilot environment
+that supports prompt files, run this in an initialized project:
 
 ```bash
 dflow configure-agents --command-adapters
@@ -76,12 +133,32 @@ 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.
+These prompts work **only in the VS Code Copilot Chat prompt menu** (as
+`/dflow-<id>`, for example `/dflow-new-feature`); the **Copilot CLI does not
+read** `.github/prompts/`, so this command path is unavailable in the CLI (see
+"Surface B" above). 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. Note the command syntax uses the **hyphen** `/dflow-<id>`, not the
+canonical **colon** `/dflow:<id>` — the colon form is Claude / Codex's command
+syntax and in Copilot can only be a text reference, never typed as a command.
+
+### The `--skills` Flag and Skill Triggering on Copilot
+
+`dflow configure-agents --skills` projects the same tool-neutral thin skill for
+**Claude Code, Codex, and GitHub Copilot**, each at its own project-level skill
+path; Copilot's is `.github/skills/dflow/SKILL.md`. Testing (2026-06-05) confirmed
+Copilot discovers and runs the skill from its own native `.github/skills/` path
+(it still works with the cross-read `.claude`/`.agents` paths removed); the
+trigger differs by surface — **VS Code Chat auto-triggers on natural language**,
+while the **Copilot CLI needs a `/dflow` to manually engage** it (details in
+Surfaces A / B above).
+
+> Note: Copilot also cross-reads `.claude/skills` and `.agents/skills`; if you
+> select Copilot alongside Claude / Codex in the same project, the same `dflow`
+> skill may surface from more than one path. The copies Dflow *generates* are
+> byte-identical (same `name`), so they behave the same; but a pre-existing
+> non-Dflow `dflow` skill at one of those paths is left untouched and could
+> differ — remove or rename it to avoid a divergent same-name duplicate.
 
 ### Version Control and Upgrades for Generated Adapters
 
@@ -145,17 +222,40 @@ Copilot: Got it. I'll create the feature spec at dflow/specs/features/active/
 
 ### Pre-Existing Repository Instructions
 
-If a `.github/copilot-instructions.md` file already exists in your project, `init` does not overwrite it. Instead, it writes a merge snippet under `dflow/specs/shared/` that you can review and paste into your existing file manually. This avoids destroying custom Copilot instructions you already had.
-
-Look for a file named `dflow/specs/shared/COPILOT-INSTRUCTIONS-MERGE-SNIPPET.md` and paste the relevant sections into your existing `.github/copilot-instructions.md`.
-
-### Notes on Slash-Command Passthrough
-
-Copilot may or may not passthrough raw `/dflow:*` slash commands depending on the IDE integration and Copilot version. If Copilot does not recognize a slash-prefixed workflow name, re-send the request as plain prose:
+If a `.github/copilot-instructions.md` file already exists in your project,
+`init` does not overwrite custom content. A Dflow-generated shim is refreshed
+in place; another file that already points to
+`dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped. If the file does not yet
+point to the guide, Dflow shows the change in the confirmation preview and
+appends a marked `<!-- dflow-generated: agent-shim START/END -->` block at the
+end of the file; re-running refreshes that same block in place without
+duplicating it. This avoids destroying custom Copilot instructions you already
+had. If you delete the block, the next `init` / `configure-agents` run appends
+it again.
+
+Look for the fallback merge snippet
+`dflow/specs/shared/copilot-instructions-snippet.md` only when Dflow reports
+conflicting or malformed markers, then resolve it manually in your existing
+`.github/copilot-instructions.md`.
+
+### Can You Type `/dflow:<id>` (the Colon Form) Directly?
+
+The canonical `/dflow:<id>` (colon) is Claude / Codex's command syntax. In
+Copilot, **do not type it literally as a command on either surface**:
+
+- **VS Code Chat**: as a text reference it is fine (Copilot understands which
+  workflow you mean); for a command entry, use the prompt-adapter `/dflow-<id>`
+  (hyphen).
+- **Copilot CLI**: typing `/dflow:new-feature` is parsed down to `/dflow` (it
+  only engages the skill, without the id). Type `/dflow` to engage, then describe
+  the workflow you want.
+
+On any surface, whenever a slash form is not recognized, re-send the request as
+plain prose:
 
 ```text
-You: Instead of /dflow:new-feature, try: "Please help me start a new Dflow
-     feature workflow. Read dflow/specs/shared/AI-AGENT-GUIDE.md first."
+You: Please help me start a new Dflow feature workflow. Read
+     dflow/specs/shared/AI-AGENT-GUIDE.md first.
 ```
 
 ## Differences vs Other AI Tools
@@ -165,13 +265,13 @@ The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the same across
 | Tool | Generated shim | Loads canonical guide via |
 |---|---|---|
 | GitHub Copilot | `.github/copilot-instructions.md` | Reads repository instructions directly |
-| Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| Claude Code | `CLAUDE.md` | Reads file content directly when starting |
 | 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 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: 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`.
+- Loading: the Copilot shim is a thin pointer that does not inline the guide (same as the other tools now); the canonical guide is loaded on demand.
+- Tool model: Copilot has two surfaces — VS Code Chat (chat panel + inline completions) and the Copilot CLI (terminal); Codex/Claude Code are CLI-based agents. The two Copilot surfaces interact with Dflow differently (see Surfaces A / B above).
+- Workflow invocation: canonical `/dflow:*` is shared vocabulary, but each tool's `/` parser behaves differently. Claude / Codex take `/dflow:<id>` (colon) directly as a command; Copilot does **not** — in VS Code the command entry is the prompt-adapter `/dflow-<id>` (hyphen, requires `--command-adapters`), while the Copilot CLI has no per-id command and instead uses `/dflow` to engage the skill (see Surfaces A / B above).
 - 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
@@ -180,7 +280,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 the canonical `/dflow:<id>` workflow when slash-prefixed forms are rejected by the IDE.
+- Sort out the surface first: VS Code Chat auto-triggers on natural language and uses `/dflow-<id>` for commands; the Copilot CLI has no auto-trigger, engage with `/dflow` first, and has no per-id command (see Surfaces A / B above).
+- When a slash form is not recognized (occasional in VS Code Chat, or `/dflow-<id>` returning Unknown in the Copilot CLI), describe the workflow in plain prose, or in the CLI type `/dflow` to engage the skill first.
 - 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
@@ -192,4 +293,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 behavior: the surface differences described here (VS Code Chat auto-triggers on natural language, the Copilot CLI engages manually via `/dflow`, prompt adapters are VS Code-only) reflect 2026-06-05 testing; automatic inclusion of `.github/` instruction files and each surface's `/` command parsing may still vary by Copilot / IDE version. Confirm with a maintainer before relying on exact semantics.

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

@@ -2,7 +2,10 @@
 
 > **繁體中文** | [English](using-with-github-copilot.en.md)
 
-當你的 AI 程式設計助理是 GitHub Copilot（IDE chat + inline completions）時，Dflow 的使用體驗 walk-through。閱讀約需 10 分鐘。
+當你的 AI 程式設計助理是 GitHub Copilot 時，Dflow 的使用體驗 walk-through。GitHub
+Copilot 有兩個介面——**VS Code Copilot Chat**（IDE 內的 chat panel + inline
+completions）與 **GitHub Copilot CLI**（終端機）——兩者觸發 Dflow 與調用命令的方式
+不同，本指南會分開說明。閱讀約需 10 分鐘。
 
 本指南專注於 GitHub Copilot 的具體使用體驗。工具中立的評估流程請見
 [`docs/evaluating-dflow.md`](evaluating-dflow.md)。完整的 Get Started
@@ -12,8 +15,8 @@
 
 你正在使用或評估以 GitHub Copilot 作為 AI 程式設計助理的 Dflow。
 本指南說明 `init` 之後 Copilot 看到了什麼、repository shim 的位置、
-如何從 IDE 呼叫 Dflow workflow，以及幾個值得了解的 Copilot 專屬使用模式
-與 permission 行為。
+如何在 VS Code Copilot Chat 與 Copilot CLI 兩個介面呼叫 Dflow workflow，
+以及幾個值得了解的 Copilot 專屬使用模式與 permission 行為。
 
 ## 前置條件
 
@@ -36,28 +39,36 @@
 
 This project uses Dflow for spec-first AI-assisted development.
 
-Before planning or editing code, read and follow:
+For spec-impacting work — a new feature, a change to product, user-facing, or
+domain behavior, a new requirement, or a bug-fix workflow — read and follow:
 
-- `dflow/specs/shared/AI-AGENT-GUIDE.md`
+- `dflow/specs/shared/AI-AGENT-GUIDE.md` — command registry, routing rules, and project context.
+- `dflow/specs/shared/dflow-workflows/` — vendored workflow bundle with executable step definitions.
+
+For routine work (refactors, renames, chores, formatting, dependency bumps, or
+general code questions), proceed normally; you need not read the guide first.
+
+Keep tool-specific instruction files small. The guide and workflow bundle are
+the authoritative sources for Dflow workflow rules, slash-command behavior,
+spec locations, and SDD/DDD constraints.
 ```
 
 重點說明：
 
 - Copilot shim 位於 `.github/copilot-instructions.md`（見 `lib/init.js` mapping）。
-- Copilot shim 不含 Markdown `@` import。它只透過路徑指向 canonical 指南，讀取
+- Copilot shim 是薄指標，只透過路徑指向 canonical 指南；讀取
   `dflow/specs/shared/AI-AGENT-GUIDE.md` 時需明確開啟該檔案。
 
 ## 在 GitHub Copilot 中使用 Dflow Workflow 指令
 
-預設情況下，Copilot 是 IDE 優先的助理（chat panel + inline completions），不是
-CLI 工具。請把 Dflow workflow 名稱當成普通的對話指示，而非 CLI slash command：
+GitHub Copilot 有兩個介面，Dflow 在兩者的觸發與命令行為不同，先分清楚再用：
 
-- 在 Copilot Chat 中：「Run the Dflow /dflow:new-feature workflow」—— Copilot
-  應讀取 canonical 指南並繼續執行。
-- 在程式碼 comment 或 editor chat 中，以普通文字描述 workflow：
-  `Run the Dflow /dflow:new-feature workflow.`
+- **VS Code Copilot Chat**（IDE 內的 chat panel）：自然語言**會自動觸發** Dflow
+  的 skill；若你 opt in prompt adapters，工具原生命令 `/dflow-<id>`（連字號）也可用。
+- **GitHub Copilot CLI**（終端機）：**沒有**自然語言自動觸發；要先打 `/dflow`
+  **手動喚起** skill 再由它引導；per-id 的 `/dflow-<id>` 命令在 CLI **不可用**。
 
-可用的 workflow 入口：
+兩介面共用同一組 workflow 入口（詞彙相同，差別只在怎麼喚起）：
 
 | 指令 | 適用情境 |
 |---|---|
@@ -70,9 +81,43 @@ CLI 工具。請把 Dflow workflow 名稱當成普通的對話指示，而非 CL
 | `/dflow:pr-review` | 變更已準備好進行 SDD/DDD review。 |
 | `/dflow:report-dflow-feedback` | 你發現了 Dflow 的問題或改進點，想要一份清理過的上游回饋草稿。 |
 
+> **語法提醒**：表中 `/dflow:<id>`（**冒號**）是 Dflow 的 canonical 詞彙，也是
+> Claude / Codex 的**實際命令**語法。Copilot 的 prompt-adapter 命令改用
+> `/dflow-<id>`（**連字號**），且只在 VS Code 活；在 Copilot 裡不要照字面把冒號
+> 形式當命令輸入（Copilot CLI 會把 `/dflow:new-feature` 斷成 `/dflow`）。下面分介面
+> 說明各自怎麼呼叫。
+
+### 介面 A：VS Code Copilot Chat
+
+- **自動觸發**：有。在 chat 直接用自然語言描述要做的事（例：「I want to add CSV
+  export for users」），Dflow 的 skill 會自動 engage、判斷對應 workflow，並以
+  **suggest-and-wait**（建議命令、等你確認）開始，不會擅自跑完整個 workflow。
+- **命令**：`/dflow-<id>`（**連字號**）可用，但需先在專案跑
+  `dflow configure-agents --command-adapters` 投影
+  `.github/prompts/dflow-<id>.prompt.md`（見下節），之後在 prompt 選單選
+  `/dflow-new-feature` 即可。
+- **純文字也行**：你也可以在 chat 用普通文字描述 workflow（例：`Run the Dflow
+  /dflow:new-feature workflow.`）——此時 `/dflow:new-feature` 只是被當成**文字
+  稱呼**，不是被當命令解析。
+
+### 介面 B：GitHub Copilot CLI
+
+- **自動觸發**：**無**。直接送自然語言**不會** engage Dflow 的 skill。
+- **喚起方式**：先打 `/dflow`（無 id 後綴）**手動喚起** skill；skill engage 後會
+  列出可用的 workflow / 問你要做什麼，接著你用**自然語言描述**（例：「I want to
+  add CSV export」）或回覆它列的選項即可繼續。它一樣以 suggest-and-wait 運作。
+- **命令**：per-id 的 `/dflow-<id>` 在 CLI **不可用**——
+  `.github/prompts/dflow-<id>.prompt.md` 是 VS Code Chat 專屬、**CLI 不讀取**，
+  輸入 `/dflow-new-feature` 會得到 Unknown；冒號形式 `/dflow:new-feature` 則被
+  CLI 斷成 `/dflow`。CLI 沒有 per-id 命令入口，統一走「`/dflow` 喚起 → 會話描述」。
+- **skill 建議的命令怎麼辦**：skill engage 後可能會建議你用某個 `/dflow:<id>`
+  （這是給 Claude / Codex 的 canonical 寫法）。在 Copilot **不必照字面輸入那串
+  命令**——CLI 裡 skill 已經 engage，直接在會話用文字描述要的 workflow、或回覆
+  確認即可；VS Code 裡則改用 prompt 選單的 `/dflow-<id>`（連字號）。
+
 ### 選配 Prompt Adapters
 
-如果想在支援 prompt files 的 Copilot / VS Code 環境中使用工具原生入口，可在
+如果想在支援 prompt files 的 VS Code Copilot 環境中使用工具原生**命令**入口，可在
 已初始化的專案中執行：
 
 ```bash
@@ -84,11 +129,28 @@ dflow configure-agents --command-adapters
 
 - `.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>`。
+這些 prompt **只在 VS Code Copilot Chat 的 prompt 選單**生效（形式為
+`/dflow-<id>`，例如 `/dflow-new-feature`）；**Copilot CLI 不讀取**
+`.github/prompts/`，所以這條命令路徑在 CLI 不可用（見上方「介面 B」）。Prompt
+內容只指向 canonical `/dflow:new-feature` workflow 與
+`dflow/specs/shared/AI-AGENT-GUIDE.md`，不複製 workflow 步驟。注意命令語法用
+**連字號** `/dflow-<id>`，不是 canonical 的**冒號** `/dflow:<id>`——後者是
+Claude / Codex 的命令寫法，在 Copilot 只能當文字稱呼、不能當命令輸入。
+
+### `--skills` flag 與 Copilot 的 skill 觸發
+
+`dflow configure-agents --skills` 會為 **Claude Code、Codex 與 GitHub Copilot**
+各自投影同一份工具中立的 thin skill 到它們的 project-level skill 路徑；Copilot 的是
+`.github/skills/dflow/SKILL.md`。實測（2026-06-05）確認 Copilot 會從**自己原生的
+`.github/skills/`** 探索並運作（即使移除 `.claude`/`.agents` 的跨讀路徑也成立），
+觸發方式依介面而異——**VS Code Chat 自然語言自動觸發**、**Copilot CLI 需打 `/dflow`
+手動喚起**（細節見上方介面 A / B）。
+
+> 註：Copilot 也會跨讀 `.claude/skills` 與 `.agents/skills`；若你同一專案同時選了
+> Copilot 與 Claude / Codex，同一份 `dflow` skill 可能從多條路徑被看到。Dflow **產生**
+> 的各份內容逐字相同（同 `name`），所以正常情況一致；但若你在某條路徑已有自己的
+> （非 Dflow）`dflow` skill，Dflow 會原地保留、不覆寫——它可能與原生那份內容不同，
+> 建議移除或改名以免同名重複。
 
 ### 產生物的版控政策與升級
 
@@ -142,22 +204,33 @@ Copilot: Got it. I'll create the feature spec at dflow/specs/features/active/
 
 ### 既有的 Repository 指示
 
-如果你的專案中已有 `.github/copilot-instructions.md`，`init` 不會覆蓋它。
-它改為在 `dflow/specs/shared/` 下寫入 merge snippet，讓你手動審閱後貼入
-既有檔案。這樣可以避免破壞你已有的自訂 Copilot 指示。
+如果你的專案中已有 `.github/copilot-instructions.md`，`init` 不會覆蓋自訂內容。
+已是 Dflow-generated shim 的檔案會原地刷新；其他已指向
+`dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會略過。若既有檔案尚未指向 guide，
+Dflow 會在確認 preview 顯示並於檔案末尾附加帶有
+`<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block；重跑會
+原地更新同一段，不會重複。這樣可以避免破壞你已有的自訂 Copilot 指示。若你刪除
+該 block，下一次 `init` / `configure-agents` 會再附加它。
+
+只有遇到衝突或 malformed Dflow markers 時，才到
+`dflow/specs/shared/copilot-instructions-snippet.md` 找 fallback merge snippet，
+再手動處理你現有的 `.github/copilot-instructions.md`。
+
+### `/dflow:<id>`（冒號形式）能不能直接輸入？
 
-到 `dflow/specs/shared/COPILOT-INSTRUCTIONS-MERGE-SNIPPET.md` 找到 merge
-snippet，再把相關段落貼入你現有的 `.github/copilot-instructions.md`。
+canonical 的 `/dflow:<id>`（冒號）是給 Claude / Codex 的命令寫法。在 Copilot
+**兩個介面都不要把它當命令字面輸入**：
 
-### Slash Command Passthrough 說明
+- **VS Code Chat**：當文字稱呼可以（Copilot 會理解你指的 workflow）；要命令入口
+  請用 prompt-adapter 的 `/dflow-<id>`（連字號）。
+- **Copilot CLI**：輸入 `/dflow:new-feature` 會被斷成 `/dflow`（只喚起 skill、不帶
+  id）。直接打 `/dflow` 喚起後，用文字描述要的 workflow 即可。
 
-Copilot 是否會直通（passthrough）原始的 `/dflow:*` slash command，取決於
-IDE 整合方式與 Copilot 版本。若 Copilot 無法識別以 slash 為前綴的 workflow
-名稱，以普通文字重新送出請求：
+任何介面只要 slash 形式沒被識別，就改用普通文字重新送出請求：
 
 ```text
-You: Instead of /dflow:new-feature, try: "Please help me start a new Dflow
-     feature workflow. Read dflow/specs/shared/AI-AGENT-GUIDE.md first."
+You: Please help me start a new Dflow feature workflow. Read
+     dflow/specs/shared/AI-AGENT-GUIDE.md first.
 ```
 
 ## 與其他 AI 工具的差異
@@ -168,20 +241,20 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 | 工具 | 產生的 shim | 載入 canonical 指南的方式 |
 |---|---|---|
 | GitHub Copilot | `.github/copilot-instructions.md` | 直接讀取 repository 指示 |
-| Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| Claude Code | `CLAUDE.md` | 啟動時直接讀取檔案內容 |
 | 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 的 shim 透過 `@` import inline 嵌入不同。
-- 工具模型：Copilot 是 IDE-based（chat panel + inline completions）；
-  Codex / Claude Code 是 CLI-based agent。Copilot 透過編輯器 UI 互動，而非
-  command-line session。
+- 載入方式：Copilot shim 是薄指標、不 inline 指南（與其他工具一致）；
+  canonical 指南按需載入。
+- 工具模型：Copilot 有兩個介面——VS Code Chat（chat panel + inline completions）
+  與 Copilot CLI（終端機）；Codex / Claude Code 是 CLI-based agent。兩個 Copilot
+  介面與 Dflow 的互動方式不同（見上方介面 A / B）。
 - Workflow 呼叫：canonical `/dflow:*` 是共同詞彙，但各工具 `/` parser 行為不同。
-  Copilot 可在 chat 文字中使用 `/dflow:<id>`，若已 opt in
-  `--command-adapters`，VS Code prompt 選單名則是 `/dflow-<id>`，例如
-  `/dflow-new-feature`。
+  Claude / Codex 直接吃 `/dflow:<id>`（冒號）當命令；Copilot **不行**——VS Code
+  的命令入口是 prompt-adapter 的 `/dflow-<id>`（連字號，需 `--command-adapters`），
+  Copilot CLI 則沒有 per-id 命令、改打 `/dflow` 喚起 skill（見上方介面 A / B）。
 - Permission 模型：Copilot 依賴 IDE 的 permission 與 extension sandbox。它可能
   受 editor-level approvals 管理；CLI 工具通常有明確的 sandbox flags 與獨立的
   permission gates。
@@ -196,8 +269,10 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
   需要 spec-driven 輸出時，請明確要求執行 workflow。
 - Copilot Chat context 不一定會在所有 IDE 版本中自動包含 `.github/` 目錄下的
   repository 指示檔；行為因 Copilot / IDE 版本而異（見頁尾說明）。
-- 當 slash-prefixed forms 被 IDE 拒絕時，改用普通文字描述 canonical
-  `/dflow:<id>` workflow 名稱。
+- 先分清楚介面：VS Code Chat 自然語言自動觸發、命令用 `/dflow-<id>`；Copilot CLI
+  無自動觸發、先打 `/dflow` 喚起、沒有 per-id 命令（見上方介面 A / B）。
+- 當 slash 形式沒被識別（VS Code Chat 偶發、或 Copilot CLI 的 `/dflow-<id>`
+  Unknown）時，改用普通文字描述 workflow，或在 CLI 先打 `/dflow` 喚起 skill。
 - Prompt adapter 是從 canonical command registry 產生的薄 wrapper；不要在
   `.github/prompts/` 中手寫或複製 Dflow workflow 步驟。
 
@@ -223,5 +298,7 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 
 ---
 
-IDE 行為說明：Slash command passthrough 與 `.github/` 指示檔的自動包含行為，
-會因 Copilot / IDE 版本而異。依賴確切語意前請向 maintainer 確認。
+行為說明：本指南描述的介面差異（VS Code Chat 自然語言自動觸發、Copilot CLI 以
+`/dflow` 手動喚起、prompt adapters 僅 VS Code）依 2026-06-05 實測；`.github/`
+指示檔的自動包含與各介面的 `/` 命令解析仍可能因 Copilot / IDE 版本而異，依賴確切
+語意前請向 maintainer 確認。