dflow-sdd-ddd 0.1.1 → 0.3.0

package/docs/using-with-gemini-cli.md

@@ -0,0 +1,184 @@
+# 在 Gemini CLI 中使用 Dflow
+
+> **繁體中文** | [English](using-with-gemini-cli.en.md)
+
+當你的 AI 程式設計助理是 [Gemini CLI](https://github.com/google/gemini-cli) 時，Dflow 的使用體驗 walk-through。閱讀約需 10 分鐘。
+
+本指南專注於 Gemini CLI 的具體使用體驗。工具中立的評估流程請見
+[`docs/evaluating-dflow.md`](evaluating-dflow.md)。完整的 Get Started
+與功能列表請見 [`README.md`](../README.md)。
+
+## 本指南的適用對象
+
+你正在使用或評估以 Gemini CLI 作為 AI 程式設計助理的 Dflow。
+本指南說明 `init` 之後 Gemini CLI 看到了什麼、Dflow 的 slash
+commands 是如何被識別的，以及幾個值得了解的 Gemini CLI 專屬使用模式。
+
+你不需要在執行 `init` 之前先讀本指南。它最適合在你執行過一次 `init` 之後、
+想了解 Gemini CLI 實際載入什麼內容時閱讀。
+
+## 前置條件
+
+- 已安裝 Gemini CLI（見 [github.com/google/gemini-cli](https://github.com/google/gemini-cli)）。
+- 已具備 Node.js / npm 環境（Dflow 透過 npm 發佈）。以
+  `npm install -g dflow-sdd-ddd` 全域安裝，或用 `npx dflow-sdd-ddd` 走免安裝路徑。
+- 有一個你願意在其中執行 init 的專案目錄。首次嘗試建議先用 branch 或
+  可拋棄的範例專案；見
+  [評估者指南 Playbook](evaluating-dflow.md#30-分鐘評估-playbook)。
+
+你不需要獨立的 Dflow 服務或 API 金鑰。這些 workflow 是文字形式，使用
+Gemini CLI 本身既有的功能。
+
+## `init` 之後 Gemini CLI 看到了什麼
+
+執行 `dflow init`（或免安裝路徑的 `npx dflow-sdd-ddd init`）並選擇 Gemini CLI
+作為目標工具後，會在專案根目錄建立一個薄 shim：
+
+```markdown
+# GEMINI.md - Dflow Project Instructions
+
+This project uses Dflow for spec-first AI-assisted development.
+
+Before planning or editing code, read and follow:
+
+- `dflow/specs/shared/AI-AGENT-GUIDE.md`
+
+Keep tool-specific instruction files small. The Dflow guide above is the
+single source of truth for project workflow rules, slash-command behavior,
+spec locations, and SDD/DDD constraints.
+
+If your tool supports Markdown imports, the canonical guide is imported below:
+
+@dflow/specs/shared/AI-AGENT-GUIDE.md
+```
+
+Gemini CLI 在這個專案中啟動時，會發生兩件事：
+
+1. Gemini CLI 自動從專案根目錄載入 `GEMINI.md` 到它的 context 中。
+   這是 Gemini CLI 的標準專案指示機制。
+2. 末尾的 `@dflow/specs/shared/AI-AGENT-GUIDE.md` 這行使用 Gemini
+   CLI 的 Markdown import 語法，將 canonical Dflow 指南 inline 嵌入。因此 Gemini CLI
+   等效於把兩個檔案當成一組指示來讀取。
+
+canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）是實際 workflow
+規則的所在：專案上下文（track、技術棧、文章語言）、`/dflow:*` workflow 表、
+source-of-truth 檔案路徑，以及核心 SDD/DDD 規則。`GEMINI.md` shim 刻意保持精簡，
+這樣 canonical 指南就能在不需要 Gemini CLI 專屬修改的情況下持續演進。
+
+如果專案中已有 `GEMINI.md`，`init` 不會覆蓋它。它改為在
+`dflow/specs/shared/` 下寫入 merge snippet，讓你手動貼入現有的 `GEMINI.md`。
+
+## 在 Gemini CLI 中使用 Dflow Workflow 指令
+
+Dflow 的 `/dflow:*` slash commands 是 AI 透過 `AI-AGENT-GUIDE.md` 中的
+workflow 表識別的 workflow 名稱，不是 Gemini CLI 的內建工具指令。
+你以普通對話方式輸入它們：
+
+```text
+/dflow:new-feature
+```
+
+Gemini CLI 將此視為輸入。由於它已透過 `GEMINI.md` import 載入了 workflow 表，
+它會識別這個前綴並進入對應的 workflow。一次典型的對話如下：
+
+```text
+User: /dflow:new-feature
+
+Gemini CLI: Entering new-feature workflow. Please describe the user-facing
+capability or business behavior you want to add.
+
+User: Allow expense submitters to attach a receipt image when filing an
+expense.
+
+Gemini CLI: I'll start by drafting a feature spec under
+dflow/specs/features/active/. Before I do, I need a short answer on:
+[clarifying questions about scope, owner, priority]
+```
+
+接著這個 workflow 會引導你完成 spec 起草、行為範例、實作計畫，以及
+finish-feature 漂移（drift）檢查。確切的流程取決於你進入的是哪個 workflow
+（`/dflow:new-feature`、`/dflow:modify-existing`、`/dflow:bug-fix` 等）。
+所有 workflow 定義都存放在 Dflow skill source 中；Gemini CLI 在需要時讀取
+skill 檔案來執行它們。
+
+可用的 workflow 入口：
+
+| 指令 | 適用情境 |
+|---|---|
+| `/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 的問題或改進點，想要一份清理過的上游回饋草稿。 |
+
+如果你忘了指令名稱，問 Gemini CLI「what dflow workflows are available?」
+即可 —— 答案會從它已載入的 workflow 表中給出。
+
+## 與其他 AI 工具的差異
+
+canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間是相同的。
+只有根目錄層的 shim 有所不同：
+
+| 工具 | 產生的 shim | 載入 canonical 指南的方式 |
+|---|---|---|
+| Gemini CLI | `GEMINI.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| Codex / Copilot coding agent | `AGENTS.md` | 啟動時直接讀取檔案內容 |
+| GitHub Copilot | `.github/copilot-instructions.md` | 直接讀取檔案內容 |
+
+你可以之後執行 `dflow configure-agents` 來新增另一個工具的 shim，而不需要重跑
+`init`。同一個專案可以同時啟用多個工具，並透過 canonical 指南保持同步。
+
+## 常見模式與注意事項
+
+**保持 `GEMINI.md` 精簡。** 如果你發現自己在把 workflow 規則、spec 路徑或
+SDD 約束加入 `GEMINI.md`，這些內容應該放到
+`dflow/specs/shared/AI-AGENT-GUIDE.md`。shim 保持精簡，其他工具的 shim 才不會
+與它產生漂移（drift）。
+
+**`/dflow:*` 不是 Gemini CLI 的工具指令。** Slash commands 是 AI 從 workflow
+表識別的純文字模式。你在 `init` 之後就可以立即使用它們，不需要任何 Gemini CLI
+設定。
+
+**Permission gates 與 Dflow workflow gates 是分開的。** Gemini CLI 可能會在執行
+shell 指令或修改檔案前要求確認。Dflow 的 workflow 有自己的審核關卡（例如「我已起草
+spec —— 你要我繼續進入實作嗎？」）。兩者可能在同一個動作上同時觸發；這是預期行為，
+不代表設定有誤。
+
+**`@` import 不是遞迴的。** `GEMINI.md` import 了 `AI-AGENT-GUIDE.md`，但如果
+`AI-AGENT-GUIDE.md` 引用了其他檔案（例如 feature spec），那些檔案不會被自動
+載入 —— Gemini CLI 會在進入對應 workflow 時按需讀取它們。這樣可以讓 context
+用量與正在進行的工作保持比例。
+
+**既有的 `GEMINI.md` 會被保留。** `init` 不會覆蓋你現有的專案指示。請到
+`dflow/specs/shared/` 下找 `init` 寫入的 merge snippet，並手動將相關段落貼入
+你現有的 `GEMINI.md`。
+
+**跨機器專案可正常運作。** `dflow/specs/` 是純 Markdown，已 check in 到你的
+repo。任何人 clone 該 repo 並在其中使用 Gemini CLI，都會透過已 commit 的
+`GEMINI.md` shim 與 canonical 指南自動看到相同的 Dflow 設定。
+
+## 下一步
+
+如果你還沒有執行 `init`：
+
+- 按照[評估者指南 Playbook](evaluating-dflow.md#30-分鐘評估-playbook)
+  在可拋棄的範例專案中試用。
+
+如果你已執行 `init` 且想查看端到端的 workflow 範例：
+
+- 閱讀 [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md) 或
+  [`tutorial/02-brownfield/`](../tutorial/02-brownfield/walkthrough-00-setup.md)。
+  tutorial walk-through 展示了對話流程與產生的 `dflow/specs/` 輸出。
+
+如果你想了解設計理念：
+
+- 閱讀[為什麼 AI 時代 DDD 更重要](why-ddd-for-ai.md)。
+
+如果有任何行為與描述不符：
+
+- 開一個 docs feedback issue（見 [`CONTRIBUTING.md`](../CONTRIBUTING.md)）。
+  Per-tool 文件是新內容，有關 Gemini CLI 行為的具體回饋非常有價值。

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

@@ -0,0 +1,136 @@
+# Using Dflow with GitHub Copilot
+
+> [繁體中文](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.
+
+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.
+
+## Prerequisites
+
+- GitHub Copilot enabled in your IDE (VS Code, JetBrains, or GitHub.dev).
+- A project initialized with `dflow init` (or `npx dflow-sdd-ddd init` on the
+  no-install path) so the repository shim exists.
+- Basic familiarity with the Dflow canonical guide: `dflow/specs/shared/AI-AGENT-GUIDE.md`.
+
+## What GitHub Copilot Sees After `init`
+
+`init` writes a small tool-specific shim for Copilot at:
+
+- `.github/copilot-instructions.md` (note: this is inside `.github/`, not the project root)
+
+Example generated shim:
+
+```markdown
+# GitHub Copilot Repository Instructions
+
+This project uses Dflow for spec-first AI-assisted development.
+
+Before planning or editing code, read and follow:
+
+- `dflow/specs/shared/AI-AGENT-GUIDE.md`
+```
+
+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.
+
+## 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:
+
+- 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.`
+
+Available workflow entry points:
+
+| Command | 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. |
+
+### Sample Conversation Flow
+
+A typical Copilot Chat workflow looks like this:
+
+```text
+You: I'd like to use the /dflow:new-feature workflow. We need to add the
+     ability for users to export their data as CSV.
+
+Copilot: I'll help you structure this as a new feature. Let me start by
+         reviewing the AI-AGENT-GUIDE to understand the spec format.
+
+         Before drafting the feature spec, I need to understand the scope:
+
+         1. Should the CSV include all user data fields or a selected subset?
+         2. Which user roles should be able to trigger the export?
+         3. Are there any compliance or performance constraints I should know?
+
+You: All fields, only admin users, and exports should complete within 30 seconds
+     for datasets up to 1 million rows.
+
+Copilot: Got it. I'll create the feature spec at dflow/specs/features/active/
+         with these constraints. Let me also outline the implementation phases...
+```
+
+### 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:
+
+```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."
+```
+
+## Differences vs Other AI Tools
+
+The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the same across tools. Only the root-level shim differs:
+
+| 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 |
+| 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.
+- 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.
+- 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
+
+- Keep `.github/copilot-instructions.md` thin. The canonical Dflow guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the source of truth.
+- 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.
+
+## Where to Go Next
+
+- If you have not run `init`: run `dflow init` (after `npm install -g dflow-sdd-ddd`) or `npx dflow-sdd-ddd init` and choose the Copilot target to create `.github/copilot-instructions.md`.
+- Read [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../sdd-ddd-greenfield-skill/scaffolding/AI-AGENT-GUIDE.md) (or the brownfield equivalent) before starting a workflow.
+- See [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md) for conversation examples that demonstrate Copilot chat flows.
+- Read [`docs/why-ddd-for-ai.en.md`](why-ddd-for-ai.en.md) for the design rationale behind spec-first plus DDD.
+
+---
+
+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

@@ -0,0 +1,177 @@
+# 在 GitHub Copilot 中使用 Dflow
+
+> **繁體中文** | [English](using-with-github-copilot.en.md)
+
+當你的 AI 程式設計助理是 GitHub Copilot（IDE chat + inline completions）時，Dflow 的使用體驗 walk-through。閱讀約需 10 分鐘。
+
+本指南專注於 GitHub Copilot 的具體使用體驗。工具中立的評估流程請見
+[`docs/evaluating-dflow.md`](evaluating-dflow.md)。完整的 Get Started
+與功能列表請見 [`README.md`](../README.md)。
+
+## 本指南的適用對象
+
+你正在使用或評估以 GitHub Copilot 作為 AI 程式設計助理的 Dflow。
+本指南說明 `init` 之後 Copilot 看到了什麼、repository shim 的位置、
+如何從 IDE 呼叫 Dflow workflow，以及幾個值得了解的 Copilot 專屬使用模式
+與 permission 行為。
+
+## 前置條件
+
+- 在你的 IDE（VS Code、JetBrains 或 GitHub.dev）中已啟用 GitHub Copilot。
+- 已具備 Node.js / npm 環境（Dflow 透過 npm 發佈）。以
+  `npm install -g dflow-sdd-ddd` 全域安裝，或用 `npx dflow-sdd-ddd init`
+  走免安裝路徑，確保 repository shim 存在。
+- 已具備 Dflow canonical 指南的基本認識：`dflow/specs/shared/AI-AGENT-GUIDE.md`。
+
+## `init` 之後 GitHub Copilot 看到了什麼
+
+`init` 為 Copilot 在以下路徑寫入一個小型的工具專屬薄 shim：
+
+- `.github/copilot-instructions.md`（注意：位於 `.github/` 目錄內，非專案根目錄）
+
+生成的 shim 範例：
+
+```markdown
+# GitHub Copilot Repository Instructions
+
+This project uses Dflow for spec-first AI-assisted development.
+
+Before planning or editing code, read and follow:
+
+- `dflow/specs/shared/AI-AGENT-GUIDE.md`
+```
+
+重點說明：
+
+- Copilot shim 位於 `.github/copilot-instructions.md`（見 `lib/init.js` mapping）。
+- Copilot shim 不含 Markdown `@` import。它只透過路徑指向 canonical 指南，讀取
+  `dflow/specs/shared/AI-AGENT-GUIDE.md` 時需明確開啟該檔案。
+
+## 在 GitHub Copilot 中使用 Dflow Workflow 指令
+
+Copilot 是 IDE 優先的助理（chat panel + inline completions），不是 CLI 工具。
+請把 Dflow workflow 名稱當成普通的對話指示，而非 CLI slash command：
+
+- 在 Copilot Chat 中：「Run the Dflow /dflow:new-feature workflow」—— Copilot
+  應讀取 canonical 指南並繼續執行。
+- 在程式碼 comment 或 editor chat 中，以普通文字描述 workflow：
+  `Run the Dflow /dflow:new-feature workflow.`
+
+可用的 workflow 入口：
+
+| 指令 | 適用情境 |
+|---|---|
+| `/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 的問題或改進點，想要一份清理過的上游回饋草稿。 |
+
+### 對話範例
+
+典型的 Copilot Chat workflow 如下：
+
+```text
+You: I'd like to use the /dflow:new-feature workflow. We need to add the
+     ability for users to export their data as CSV.
+
+Copilot: I'll help you structure this as a new feature. Let me start by
+         reviewing the AI-AGENT-GUIDE to understand the spec format.
+
+         Before drafting the feature spec, I need to understand the scope:
+
+         1. Should the CSV include all user data fields or a selected subset?
+         2. Which user roles should be able to trigger the export?
+         3. Are there any compliance or performance constraints I should know?
+
+You: All fields, only admin users, and exports should complete within 30 seconds
+     for datasets up to 1 million rows.
+
+Copilot: Got it. I'll create the feature spec at dflow/specs/features/active/
+         with these constraints. Let me also outline the implementation phases...
+```
+
+### 既有的 Repository 指示
+
+如果你的專案中已有 `.github/copilot-instructions.md`，`init` 不會覆蓋它。
+它改為在 `dflow/specs/shared/` 下寫入 merge snippet，讓你手動審閱後貼入
+既有檔案。這樣可以避免破壞你已有的自訂 Copilot 指示。
+
+到 `dflow/specs/shared/COPILOT-INSTRUCTIONS-MERGE-SNIPPET.md` 找到 merge
+snippet，再把相關段落貼入你現有的 `.github/copilot-instructions.md`。
+
+### Slash Command Passthrough 說明
+
+Copilot 是否會直通（passthrough）原始的 `/dflow:*` slash command，取決於
+IDE 整合方式與 Copilot 版本。若 Copilot 無法識別以 slash 為前綴的 workflow
+名稱，以普通文字重新送出請求：
+
+```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."
+```
+
+## 與其他 AI 工具的差異
+
+canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）在各工具之間是相同的。
+只有根目錄層的 shim 有所不同：
+
+| 工具 | 產生的 shim | 載入 canonical 指南的方式 |
+|---|---|---|
+| 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 嵌入不同。
+- 工具模型：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 中使用普通文字描述。
+- Permission 模型：Copilot 依賴 IDE 的 permission 與 extension sandbox。它可能
+  受 editor-level approvals 管理；CLI 工具通常有明確的 sandbox flags 與獨立的
+  permission gates。
+
+## 常見模式與注意事項
+
+- 保持 `.github/copilot-instructions.md` 精簡。Canonical Dflow 指南
+  （`dflow/specs/shared/AI-AGENT-GUIDE.md`）才是 source of truth。
+- 若 Copilot 看起來只從 shim 文字工作，請明確要求它開啟或讀取
+  `dflow/specs/shared/AI-AGENT-GUIDE.md` 後再繼續。
+- Copilot 的 inline completions 可能在未走 Dflow workflow 的情況下直接建議程式碼；
+  需要 spec-driven 輸出時，請明確要求執行 workflow。
+- Copilot Chat context 不一定會在所有 IDE 版本中自動包含 `.github/` 目錄下的
+  repository 指示檔；行為因 Copilot / IDE 版本而異（見頁尾說明）。
+- 當 slash-prefixed forms 被 IDE 拒絕時，改用普通文字描述 workflow 名稱。
+
+## 下一步
+
+如果你還沒有執行 `init`：
+
+- 執行 `dflow init`（安裝後）或 `npx dflow-sdd-ddd init`，選擇 Copilot 目標
+  以建立 `.github/copilot-instructions.md`。參考
+  [評估者指南 Playbook](evaluating-dflow.md#30-分鐘評估-playbook) 在可拋棄的
+  範例專案中試用。
+
+如果你已執行 `init` 且想查看端到端的 workflow 範例：
+
+- 閱讀 [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../sdd-ddd-greenfield-skill/scaffolding/AI-AGENT-GUIDE.md)
+  （或 brownfield 等效版本）後再開始 workflow。
+- 閱讀 [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)，
+  其中有展示 Copilot chat flow 的對話範例。
+
+如果你想了解設計理念：
+
+- 閱讀[為什麼 AI 時代 DDD 更重要](why-ddd-for-ai.md)。
+
+---
+
+IDE 行為說明：Slash command passthrough 與 `.github/` 指示檔的自動包含行為，
+會因 Copilot / IDE 版本而異。依賴確切語意前請向 maintainer 確認。

package/docs/why-ddd-for-ai.en.md

@@ -0,0 +1,37 @@
+# Why DDD Matters More with AI
+
+> [繁體中文](why-ddd-for-ai.md) | **English**
+
+AI-assisted development changes the failure mode of software design. The team can produce more code faster, but unclear domain meaning is also amplified faster.
+
+When a project lacks shared language and explicit boundaries, small inconsistencies spread:
+
+- the same concept appears as `Order`, `Booking`, and `Transaction`
+- APIs encode different meanings for similar actions
+- business rules live in handlers, UI code, scripts, and tests
+- nobody can confidently say which behavior is authoritative
+
+An AI coding agent does not know the business domain by default. When the prompt is incomplete, it fills the missing parts with plausible logic. That logic may compile, pass superficial tests, and still be wrong. The most dangerous AI mistakes are often not syntax errors; they are reasonable-looking domain mistakes.
+
+DDD gives the spec a semantic backbone:
+
+| DDD idea | AI-era value |
+|---|---|
+| **Ubiquitous Language** | Keeps names and meanings stable across prompts, specs, code, and reviews. |
+| **Bounded Context** | Defines where a term or rule is valid, and prevents accidental meaning leaks. |
+| **Domain Model** | Gives behavior a clear owner instead of scattering rules across technical layers. |
+| **Domain Rules** | States what is correct, allowed, forbidden, and exceptional before code generation. |
+
+The important shift is where design lives. In older workflows, much of the real design could remain implicit in code. With AI, that is too late. The model needs constraints before it generates code.
+
+```text
+Without DDD:
+Prompt -> AI fills gaps -> Code -> Hidden domain drift
+
+With DDD:
+Domain meaning -> Structured spec -> AI implementation -> Reviewable code
+```
+
+Code still matters, but it is no longer the first place where meaning should be discovered. For AI collaboration, specs become the pre-generation contract, and DDD supplies the language, boundaries, and rules that make the contract precise.
+
+Dflow is built around that idea: spec first, domain meaning explicit, AI constrained before implementation, and drift checked before the work is considered done.

package/docs/why-ddd-for-ai.md

@@ -1,26 +1,28 @@
-# Why DDD Matters More with AI
+# 為什麼 AI 時代 DDD 更重要
 
-AI-assisted development changes the failure mode of software design. The team can produce more code faster, but unclear domain meaning is also amplified faster.
+> **繁體中文** | [English](why-ddd-for-ai.en.md)
 
-When a project lacks shared language and explicit boundaries, small inconsistencies spread:
+AI 輔助開發改變了軟體設計的失敗模式。團隊能更快產出更多程式碼，但不清晰的領域語義也會以同樣的速度擴散。
 
-- the same concept appears as `Order`, `Booking`, and `Transaction`
-- APIs encode different meanings for similar actions
-- business rules live in handlers, UI code, scripts, and tests
-- nobody can confidently say which behavior is authoritative
+當專案缺乏共同語言與明確邊界時，細小的不一致便會蔓延：
 
-An AI coding agent does not know the business domain by default. When the prompt is incomplete, it fills the missing parts with plausible logic. That logic may compile, pass superficial tests, and still be wrong. The most dangerous AI mistakes are often not syntax errors; they are reasonable-looking domain mistakes.
+- 同一個概念以 `Order`、`Booking`、`Transaction` 三種名稱出現
+- API 對相似動作賦予不同語義
+- 業務規則分散在 handler、UI 程式碼、腳本與測試之中
+- 沒有人能確定哪一個行為才是權威的
 
-DDD gives the spec a semantic backbone:
+AI 程式碼代理預設不了解業務領域。當 prompt 資訊不完整時，它會以看似合理的邏輯填補缺漏。這些邏輯可能通過編譯、通過表面測試，卻依然是錯的。AI 最危險的錯誤往往不是語法錯誤，而是外觀合理的領域錯誤。
 
-| DDD idea | AI-era value |
+DDD 為規格提供語義骨幹：
+
+| DDD 概念 | AI 時代的價值 |
 |---|---|
-| **Ubiquitous Language** | Keeps names and meanings stable across prompts, specs, code, and reviews. |
-| **Bounded Context** | Defines where a term or rule is valid, and prevents accidental meaning leaks. |
-| **Domain Model** | Gives behavior a clear owner instead of scattering rules across technical layers. |
-| **Domain Rules** | States what is correct, allowed, forbidden, and exceptional before code generation. |
+| **Ubiquitous Language（通用語言）** | 讓名稱與語義在 prompt、規格、程式碼與 review 之間保持穩定。 |
+| **Bounded Context** | 定義術語或規則的有效範圍，防止語義意外洩漏。 |
+| **領域模型（Domain Model）** | 讓行為有明確的所有者，而不是將規則分散在技術層之間。 |
+| **領域規則（Domain Rules）** | 在程式碼生成之前，先明確指出什麼是正確的、允許的、禁止的，以及例外情況。 |
 
-The important shift is where design lives. In older workflows, much of the real design could remain implicit in code. With AI, that is too late. The model needs constraints before it generates code.
+關鍵的轉變在於設計的位置。舊有的工作流程中，大量真正的設計可以隱含在程式碼裡。引入 AI 之後，這樣做已經太遲。模型需要在生成程式碼之前就取得約束條件。
 
 ```text
 Without DDD:
@@ -30,6 +32,6 @@ With DDD:
 Domain meaning -> Structured spec -> AI implementation -> Reviewable code
 ```
 
-Code still matters, but it is no longer the first place where meaning should be discovered. For AI collaboration, specs become the pre-generation contract, and DDD supplies the language, boundaries, and rules that make the contract precise.
+程式碼仍然重要，但不再是發現語義的第一現場。在 AI 協作模式下，規格成為生成前的契約，DDD 提供語言、邊界與規則，使契約具備精確性。
 
-Dflow is built around that idea: spec first, domain meaning explicit, AI constrained before implementation, and drift checked before the work is considered done.
+Dflow 正是圍繞這個理念建構：規格優先、領域語義顯式化、在實作前約束 AI，並在工作完成前驗證漂移（drift）。