dflow-sdd-ddd 0.9.0 → 0.11.0

package/docs/using-with-codex.md

@@ -43,12 +43,17 @@ canonical Dflow 指南的，以及幾個值得了解的 Codex 專屬指令與權
 
 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.
 
-Keep tool-specific instruction files small. The Dflow guide above is the
-single source of truth for project workflow rules, slash-command behavior,
+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.
 ```
 
@@ -56,11 +61,11 @@ Codex 在這個專案中啟動時，有兩件事值得注意：
 
 1. Codex CLI 將 `AGENTS.md` 作為專案指示讀取。這是 Codex 的
    標準 repository 指示機制。
-2. Dflow shim 不含 Markdown import 那一行。與 Claude Code 的 shim 不同，
-   產生的 `AGENTS.md` 不含 `@dflow/specs/shared/AI-AGENT-GUIDE.md`。
+2. Dflow shim 是薄指標，不把指南 inline 進來。產生的 `AGENTS.md` 只以
+   普通 Markdown bullet 指向 `dflow/specs/shared/AI-AGENT-GUIDE.md`。
 
 這意味著 Codex 能立即看到指標，但 canonical Dflow 指南不會由 shim 自動 inline 嵌入。
-在規劃或編輯之前，Codex 應跟著指標讀取 `dflow/specs/shared/AI-AGENT-GUIDE.md`。
+做 spec-impacting 工作（新功能、行為變更、bug fix）時，Codex 應跟著指標讀取 `dflow/specs/shared/AI-AGENT-GUIDE.md`。
 若 Codex 在回應 Dflow 請求時沒有提到該檔案，請明確引導它：「Before continuing,
 read and follow `dflow/specs/shared/AI-AGENT-GUIDE.md`.」
 
@@ -69,13 +74,19 @@ canonical 指南是實際 workflow 規則的所在：專案上下文（track、
 `AGENTS.md` shim 刻意保持精簡，這樣 canonical 指南就能同時服務 Codex CLI、
 Claude Code、GitHub Copilot 與其他工具。
 
-如果專案中已有 `AGENTS.md`，`init` 不會覆蓋它。若既有檔案尚未指向
-`dflow/specs/shared/AI-AGENT-GUIDE.md`，`init` 會在
-`dflow/specs/shared/AGENTS-md-snippet.md` 下寫入 merge snippet，
-讓你手動合併。這樣可以避免破壞你已有的自訂專案指示。
+如果專案中已有 `AGENTS.md`，`init` 不會覆蓋自訂內容。已是 Dflow-generated shim
+的檔案會原地刷新；其他已指向 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會
+略過，不會新增第二個指標。否則 Dflow 會在確認 preview 顯示並於檔案末尾附加帶有
+`<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block，重跑會
+原地更新同一段。只有遇到衝突或 malformed Dflow markers 時，才會改寫
+`dflow/specs/shared/AGENTS-md-snippet.md` fallback merge snippet 讓你手動合併。
 
-若是 `dflow configure-agents --command-adapters` 情境，對應檔名為
-`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`。
+若改用 `dflow configure-agents --command-adapters`，marker conflict 的 fallback 小抄會依
+「壞掉的是哪一段 marker」分成兩個檔：只有 trigger markers 壞掉、而檔案仍指向 canonical
+指南時，用 trigger-only 的 `dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`；
+其他任何 marker conflict（agent-shim markers 壞掉，或兩段 marked block 交疊／跨界）則用
+完整 shim 的 `dflow/specs/shared/AGENTS-md-snippet.md`。兩者
+都只在 marker conflict 時出現，詳見下方〈選配 Command Adapters 的 Codex 行為〉。
 
 ## 在 Codex CLI 中使用 Dflow Workflow 指令
 
@@ -144,9 +155,11 @@ guide 中記為 `/dflow:*`）。
 ### 選配 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。
+Codex 命令檔。Codex v1 沒有與 Claude `.claude/commands` 或 Copilot `.github/prompts`
+對等的 Dflow command-file adapter。
+
+**自動觸發 skill 走的是 `--skills`（非 `--command-adapters`）。** 見下方
+〈選配 Skill 的 Codex 行為〉。
 
 當你在 `--command-adapters` 模式下選擇 `AGENTS.md - Codex / Copilot coding agent`
 時，Dflow 會把從 canonical command registry 產生的 trigger 清單寫進 `AGENTS.md`。
@@ -160,19 +173,60 @@ dflow:new-feature
 --command-adapters` 流程就是如此），Dflow 會把帶 marker 的 trigger 段**直接注入**
 `AGENTS.md`，零手動合併；重複執行會就地重投影同一段、不會重複附加。
 
-如果 `AGENTS.md` 在 Dflow 產生後被改過、或本來就是你自訂的檔案，Dflow 會保留既有
-檔案不動，改把 trigger 段寫到 merge snippet 供你手動合併。此情況下 Codex 目標的
-merge snippet 檔名是 `dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`。
+如果 `AGENTS.md` 在 Dflow 產生後被改過、或本來就是你自訂的檔案，Dflow 仍會保留既有
+內容，並透過同一套機制把 trigger 段作為相鄰的 marked block 附加（或就地更新）到
+`AGENTS.md`，確認 preview 會先顯示這段。只有當既有的 Dflow markers 壞到無法安全就地
+改寫時，Dflow 才會改成「不動你的檔、另寫一份手動合併小抄」；而且依「壞掉的是哪一段
+marker」分成兩種小抄：
+
+- **只有 trigger markers 壞掉，agent-shim 段與其 region 仍完好（沒有交疊／跨界），且檔案
+  已指向 canonical 指南**：指南指標已就位，小抄只需補 trigger 段，檔名是
+  `dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`。
+- **其他任何 marker conflict**——例如 agent-shim markers 本身壞掉，或 agent-shim 與
+  trigger 兩段 marked block 交疊／跨界——小抄需要完整 shim（標題、指南指標，以及在
+  `--command-adapters` 下的 trigger 段），檔名是 `dflow/specs/shared/AGENTS-md-snippet.md`。
+
+兩種小抄都只在 marker conflict 時出現。乾淨、沒有 marker 衝突的自訂 `AGENTS.md` 不會
+產生任何小抄——Dflow 會直接把相鄰 marked block append 進去。
+
+### 選配 Skill 的 Codex 行為（自動觸發）
+
+`dflow configure-agents --skills` 會把一份精簡、工具中立的 skill 投影到
+`.agents/skills/dflow/SKILL.md`——Codex 的專案層 skill 路徑。這讓 Codex 取得與
+Claude Code **對等的自然語言自動觸發**：你用「help me start a new feature」這類描述
+時，Codex 可依該 skill 的 `description` 自動判斷是否相關，建議對應的 `dflow:<id>`
+workflow，而不必每次都記得手打命令。
+
+skill body 與 frontmatter（`name` / `description`）都是純文字，只指向 canonical 指南
+（`dflow/specs/shared/AI-AGENT-GUIDE.md`）與 vendored workflow bundle，與 Claude 投影
+的是**同一份 source**（`templates/common/skill/SKILL.md`），沒有 per-tool 內容分岔。
+被自動觸發時，skill 的約定是：先判斷意圖、建議對應 `dflow:<id>`、等你確認後才進入
+workflow，而不會自行直接執行。
+
+重跑 `--skills` 會就地重寫帶 marker 的同一份 skill（idempotent）；若該路徑已存在一份
+**非** Dflow 產生的檔案（沒有 `<!-- dflow-generated: skill-adapter -->` marker），Dflow
+不會覆寫，只會 warn 並保留你的檔。
+
+> GitHub Copilot 也支援：`--skills` 模式下選擇 Copilot 會投影
+> `.github/skills/dflow/SKILL.md`（同一份 thin skill）。Copilot 也會跨讀
+> `.claude`/`.agents`；Dflow 產生的各份逐字相同，但若該路徑已有你自己的非 Dflow
+> `dflow` skill，Dflow 會保留不覆寫、內容可能不同（移除或改名以免同名重複）。
 
 ### 產生物的版控政策（Codex）
 
-Codex 不產生 command 檔，所以**沒有需要 gitignore 的衍生 adapter**。Codex 端要版控的是
-`AGENTS.md` shim 與 `dflow/`（canonical guide + 規格）；其中
-`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md` 這個 merge helper 屬 `dflow/` 的一部分，
-**隨 `dflow/` 一起版控**。`--command-adapters` 對 Codex 只強化 `AGENTS.md` 的文字 trigger，
-不新增任何 `.claude/`、`.github/`、`.agents/` 命令檔，因此 Claude / Copilot 那套「衍生 adapter
-要不要版控」的取捨在 Codex 端不適用。其他工具的 adapter 版控政策見
-[README「Init 產生的檔案」](../README.md#init-產生的檔案) 與各 per-tool 指南。
+Codex 不產生 command 檔，所以 `--command-adapters` 端**沒有需要 gitignore 的衍生 adapter**。
+Codex 端要版控的是 `AGENTS.md` shim / marked blocks 與 `dflow/`（canonical guide +
+規格）；其中兩種 fallback merge helper（`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`
+或 `dflow/specs/shared/AGENTS-md-snippet.md`）只在 marker conflict 時產生，若出現也屬
+`dflow/` 的一部分，**隨 `dflow/` 一起版控**。
+`--command-adapters` 對 Codex 只強化 `AGENTS.md` 的文字 trigger，不新增任何
+`.claude/`、`.github/`、`.agents/` 命令檔。
+
+唯一的 Codex 衍生物來自 `--skills`：`.agents/skills/dflow/SKILL.md`。它與 Claude 的
+`.claude/skills/dflow/SKILL.md` 一樣，是可從 canonical 指南重生成的衍生物，沿用相同的
+**建議預設**（不版控、clone 後重跑 `configure-agents --skills` 重生成；若你的團隊偏好 clone
+即有自動觸發，版控它也是合理選擇，原則是同專案對各工具採一致策略）。其他工具的 adapter /
+skill 版控政策見 [README「Init 產生的檔案」](../README.md#init-產生的檔案) 與各 per-tool 指南。
 
 ## 與其他 AI 工具的差異
 
@@ -181,7 +235,7 @@ canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間
 
 | 工具 | 產生的 shim | 載入 canonical 指南的方式 |
 |---|---|---|
-| Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| Claude Code | `CLAUDE.md` | 專案指示載入 shim；循指標讀取指南 |
 | Codex / Copilot coding agent | `AGENTS.md` | 專案指示載入 shim；Codex 須跟著指標讀取指南 |
 | GitHub Copilot | `.github/copilot-instructions.md` | 直接讀取 repository 指示 |
 
@@ -197,7 +251,7 @@ Codex 也有自己的專案指示分層機制。它可以從 Codex home 讀取
 
 如果你的團隊在同一個專案中同時使用 Claude Code 和 Codex CLI，
 不需要額外的 Dflow 協調。兩個工具都讀取相同的 canonical 指南；
-只有 shim 檔案與載入機制不同。
+只有 shim 檔案不同。
 
 ## 常見模式與注意事項
 
@@ -207,7 +261,7 @@ SDD 約束加入 `AGENTS.md`，這些內容應該放到
 與它產生漂移（drift）。
 
 **Codex 不會從 `AGENTS.md` inline 嵌入 Dflow 指南。** 產生的 Codex shim
-是以普通的 Markdown bullet 指向 canonical 指南，而非 `@...` import。
+是以普通的 Markdown bullet 指向 canonical 指南。
 若 Codex 看起來只從 shim 工作，請要求它讀取 `AI-AGENT-GUIDE.md`。
 
 **`/dflow:*` 不是 Codex CLI 的內建 slash command。** Codex slash command 控制
@@ -216,8 +270,10 @@ SDD 約束加入 `AGENTS.md`，這些內容應該放到
 canonical `/dflow:<id>` workflow。
 
 **Codex 不產生命令檔。** 即使使用 `--command-adapters`，Codex 也只強化
-`AGENTS.md` / merge snippet 中的文字 trigger 說明。不要期待 `.claude/commands`、
-`.github/prompts` 或 `.agents/skills/dflow/SKILL.md` 形式的 Codex 專屬命令檔。
+`AGENTS.md` 中 marked block 的文字 trigger 說明；只有 marker conflict 才會產生
+fallback merge snippet。不要期待 `.claude/commands` 或 `.github/prompts` 形式的
+Codex 專屬**命令**檔。（自動觸發 **skill** 是另一回事，由 `--skills` 投影到
+`.agents/skills/dflow/SKILL.md`，見上方〈選配 Skill 的 Codex 行為〉。）
 
 **不要混淆 Codex `/init` 與 Dflow `init`。** Codex `/init` 為 Codex 建立
 通用的 `AGENTS.md` scaffold。Dflow 的設定是 `dflow init`（或免安裝路徑的
@@ -233,9 +289,12 @@ session 中同時出現；這是預期行為。
 在這個模式下，Codex 可在專案內工作，並在超出 sandbox 範圍（例如 workspace
 外寫入或存取網路）前先詢問。
 
-**既有的 `AGENTS.md` 會被保留。** 若 Dflow 因檔案已存在而無法安全寫入
-根目錄 shim，請到 `dflow/specs/shared/` 下找 merge snippet，
-手動將 Dflow 指標合併進你現有的專案指示。
+**既有的 `AGENTS.md` 會被保留。** Dflow 不會覆蓋你現有的自訂專案指示；base pointer
+若是 Dflow-generated shim 會原地刷新，其他已指向 `AI-AGENT-GUIDE.md` 的檔案會
+略過，否則會在確認 preview 顯示並附加 marked Dflow block，重跑原地更新。
+`--command-adapters` 仍可加入 / 更新相鄰的 trigger block；刪除 block 後再跑
+`init` / `configure-agents` 會再附加。只有 marker conflict 時，才需要到
+`dflow/specs/shared/` 找 fallback merge snippet 手動處理。
 
 **巢狀 `AGENTS.md` 可能改變 Codex 看到的內容。** Codex 沿著到當前工作目錄
 的路徑分層讀取專案指示。若某個子目錄有自己的 `AGENTS.md` 或

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.