dflow-sdd-ddd 0.8.0 → 0.10.0

package/README.en.md

@@ -35,8 +35,9 @@ npm install -g dflow-sdd-ddd
 dflow init
 ```
 
-The init flow asks whether the project is greenfield or brownfield, then
-previews the files it will create. Existing files are not overwritten. Init
+The init flow asks whether the project is greenfield or brownfield, which Git
+policy the team follows (GitFlow / Trunk), and how AI-made commits should be
+marked, then previews the files it will create. Existing files are not overwritten. Init
 creates workflow documentation and AI instruction files; it does not inspect,
 refactor, or migrate your application code.
 
@@ -215,7 +216,9 @@ dflow/
         └── completed/
 ```
 
-Dflow also creates or provides a mergeable project instruction file for your AI coding agent. The exact file depends on the target tool and existing project setup; Dflow avoids overwriting existing project instructions.
+Dflow also creates or updates a project instruction file for your AI coding
+agent. The exact file depends on the target tool and existing project setup;
+Dflow avoids overwriting custom content in existing project instructions.
 
 When you select AI agent setup during init, Dflow writes
 `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical project guide, then
@@ -228,14 +231,22 @@ files whose only job is to redirect the tool to the canonical guide):
 | Claude Code | `CLAUDE.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
-If one of those files already exists, Dflow leaves it unchanged and writes a
-merge snippet under `dflow/specs/shared/` instead. The project guide stays the
-single source of truth, so teams can use multiple AI tools without maintaining
-multiple copies of the workflow rules.
+If one of those files already exists, Dflow preserves 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. A fallback merge snippet under `dflow/specs/shared/` is written
+only when the file contains conflicting or malformed Dflow markers. The project
+guide stays the single source of truth, so teams can use multiple AI tools
+without maintaining multiple copies of the workflow rules.
 
 You can run `dflow configure-agents` later to add more tool shims as the team
 adopts additional AI coding agents. If you need Claude / Copilot tool-native
-command entries, use `dflow configure-agents --command-adapters`.
+command entries, use `dflow configure-agents --command-adapters`. For
+natural-language auto-trigger (a project-level skill for Claude Code and Codex),
+use `dflow configure-agents --skills`.
 
 ### Version-Control Policy for Generated Artifacts (recommended default)
 
@@ -246,9 +257,10 @@ version-control the source, not the generated artifacts.
 
 | File | Role | Recommended default |
 |---|---|---|
-| `dflow/` (canonical guide, specs, merge snippet) | source | **version-control** |
-| Thin shims (`CLAUDE.md` / `AGENTS.md` / `.github/copilot-instructions.md`) | source | **version-control** |
+| `dflow/` (canonical guide, specs, fallback merge snippets) | source | **version-control** |
+| Thin shims or marked Dflow blocks in existing root agent files (`CLAUDE.md` / `AGENTS.md` / `.github/copilot-instructions.md`) | source | **version-control** |
 | `.claude/commands/dflow/`, `.github/prompts/dflow-*.prompt.md` | generated | **recommended: do not version-control (gitignore)**; regenerate after clone with `configure-agents --command-adapters` |
+| `.claude/skills/dflow/`, `.agents/skills/dflow/` | generated | **recommended: do not version-control (gitignore)**; regenerate after clone with `configure-agents --skills` |
 
 This is a **recommendation**, not the only valid policy. If your team wants a
 native `/` menu immediately after clone, or your CI / dev environment does not
@@ -317,7 +329,7 @@ Usable only inside an already-started active feature. Targets pointing at `compl
 |---|---|---|
 | `/dflow:verify` | Need to confirm docs, code, tests, and tech-debt records are still in sync | Drift report across spec, domain docs, implementation, tests, and debt records |
 | `/dflow:pr-review` | A change is ready for review | SDD/DDD compliance review checklist with risks, gaps, and follow-up items |
-| `/dflow:report-dflow-feedback` | You or the AI found a Dflow issue or improvement while using it | Sanitized local feedback draft; nothing is submitted automatically |
+| `/dflow:report-dflow-feedback` | You or the AI found a Dflow issue or improvement while using it | Sanitized local draft rendered field-by-field for the upstream issue form, ready to paste; nothing is submitted automatically |
 
 ### What should I run? (rule of thumb)
 
@@ -389,4 +401,4 @@ release history.
 
 ## License
 
-MIT License. See [LICENSE](LICENSE).
+GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See [LICENSE](LICENSE).

package/README.md

@@ -33,7 +33,7 @@ npm install -g dflow-sdd-ddd
 dflow init
 ```
 
-init 流程會詢問是 greenfield 或 brownfield，接著預覽即將建立的檔案。既有檔案不會被覆寫。Init 只建立 workflow 文件與 AI 指示檔，**不會**檢查、重構、或遷移你的應用程式碼。
+init 流程會詢問是 greenfield 或 brownfield、團隊採用的 Git policy（GitFlow / Trunk）、以及 AI commit 的標記方式，接著預覽即將建立的檔案。既有檔案不會被覆寫。Init 只建立 workflow 文件與 AI 指示檔，**不會**檢查、重構、或遷移你的應用程式碼。
 
 若專案已初始化、之後又要加入另一個 AI 程式設計工具，執行：
 
@@ -190,7 +190,7 @@ dflow/
         └── completed/
 ```
 
-Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指示檔；確切檔名取決於目標工具與既有專案設定。Dflow 不覆寫既有專案指示。
+Dflow 也會為你的 AI 程式設計助理建立或更新專案指示檔；確切檔名取決於目標工具與既有專案設定。Dflow 不覆寫既有專案指示中的自訂內容。
 
 選擇 AI agent 設定時，Dflow 把 `dflow/specs/shared/AI-AGENT-GUIDE.md` 作為 canonical 專案指南，並為每個 AI 工具建立**小型的指向檔**（俗稱 shim，內容很短，只是把該工具引導去讀 canonical 指南）：
 
@@ -200,9 +200,15 @@ Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指
 | Claude Code | `CLAUDE.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
-若這些檔案已存在，Dflow 不會覆蓋，改寫 merge snippet 到 `dflow/specs/shared/`。專案指南保持單一 source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow 規則。
+若這些檔案已存在，Dflow 不會覆蓋自訂內容；已是 Dflow-generated shim 的檔案
+會原地刷新，其他已指向 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會略過。
+若檔案尚未指向 guide，預設會在確認 preview 顯示並於檔案末尾附加帶有
+`<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block，重跑會
+原地更新同一段且不重複。只有檔案內有衝突或 malformed Dflow markers 時，
+才會改寫 fallback merge snippet 到 `dflow/specs/shared/`。專案指南保持單一
+source of truth，團隊就能用多個 AI 工具而不必維護多份 workflow 規則。
 
-之後團隊採用新 AI 程式設計助理時，可隨時跑 `dflow configure-agents` 新增 shim；若需要 Claude / Copilot 的工具原生命令入口，改用 `dflow configure-agents --command-adapters`。
+之後團隊採用新 AI 程式設計助理時，可隨時跑 `dflow configure-agents` 新增 shim；若需要 Claude / Copilot 的工具原生命令入口，改用 `dflow configure-agents --command-adapters`；若要自然語言自動觸發（為 Claude Code 與 Codex 投影專案層 skill），改用 `dflow configure-agents --skills`。
 
 ### 產生物的版控政策（建議預設）
 
@@ -210,9 +216,10 @@ Dflow 也會為你的 AI 程式設計助理建立或提供可合併的專案指
 
 | 檔案 | 角色 | 建議預設 |
 |---|---|---|
-| `dflow/`（canonical guide、規格、merge snippet） | source | **版控** |
-| 薄 shim（`CLAUDE.md` / `AGENTS.md` / `.github/copilot-instructions.md`） | source | **版控** |
+| `dflow/`（canonical guide、規格、fallback merge snippet） | source | **版控** |
+| 薄 shim 或既有 root agent 檔案中的 marked Dflow block（`CLAUDE.md` / `AGENTS.md` / `.github/copilot-instructions.md`） | source | **版控** |
 | `.claude/commands/dflow/`、`.github/prompts/dflow-*.prompt.md` | 衍生物 | **建議不版控（gitignore）**，clone 後重跑 `configure-agents --command-adapters` 重生成 |
+| `.claude/skills/dflow/`、`.agents/skills/dflow/` | 衍生物 | **建議不版控（gitignore）**，clone 後重跑 `configure-agents --skills` 重生成 |
 
 這是**建議**，不是唯一正解。若團隊希望 clone 後立即有原生 `/` 選單、或 CI / 開發環境不裝 npm，**版控 adapter** 也是合理選擇——代價是升級若改了命名，要重投影並 commit 刪除舊檔。關鍵原則：**同一專案對所有工具採一致策略**，別像常見的踩雷一樣一邊 ignore、一邊版控。
 
@@ -263,7 +270,7 @@ Dflow 指令依角色分四類。「我要做的事」對應到指令的速查
 |---|---|---|
 | `/dflow:verify` | 需要確認文件、程式、測試、債務紀錄是否一致 | 跨規格、領域文件、實作、測試、債務的 drift report |
 | `/dflow:pr-review` | 變更已準備接受審查 | SDD/DDD 合規 review 清單，含風險、缺口、後續項目 |
-| `/dflow:report-dflow-feedback` | 你或 AI 在使用中發現 Dflow 本身的問題 | sanitized 的本地 feedback 草稿；不自動送出 |
+| `/dflow:report-dflow-feedback` | 你或 AI 在使用中發現 Dflow 本身的問題 | sanitized 的本地草稿，逐欄對齊上游 issue 表單可直接貼上；不自動送出 |
 
 ### 該選哪個指令（rule of thumb）
 
@@ -328,4 +335,4 @@ GitHub 上的 source 可能包含 `0.2.0` 之後尚未發佈的 repo 變更。
 
 ## 授權
 
-MIT License，見 [LICENSE](LICENSE)。
+GNU Affero General Public License v3.0 或更新版本（AGPL-3.0-or-later），見 [LICENSE](LICENSE)。

package/TEMPLATE-COVERAGE.md

@@ -25,7 +25,6 @@ The matrix lists Brownfield / Greenfield logical template parity so reviewers ca
 | ADR guide | `dflow/specs/architecture/decisions/README.md` | n/a | `scaffolding/architecture-decisions-README.md` | Greenfield only | Brownfield not applicable | - |
 | Project AI guide | `dflow/specs/shared/AI-AGENT-GUIDE.md` when at least one AI agent is selected during init | `scaffolding/AI-AGENT-GUIDE.md` | `scaffolding/AI-AGENT-GUIDE.md` | Same canonical tool-neutral workflow guide and source-of-truth pointers | Track-specific seeded values and available source-of-truth paths may differ | - |
 | AI tool shims | `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, or merge snippets under `dflow/specs/shared/` | generated by CLI | generated by CLI | Thin files must point back to `dflow/specs/shared/AI-AGENT-GUIDE.md`; existing files are not overwritten | Tool-specific import hints differ | - |
-| Legacy Claude guide template | `<project root>/CLAUDE.md` | `templates/CLAUDE.md` | `templates/CLAUDE.md` | H2 navigation and H3 structural headings aligned (canonical English, per F-01 Path A) | Greenfield includes Aggregate / Architecture Decisions and other Greenfield-specific H3 sections | - |
 
 ## Reference Flow Parity
 

package/bin/dflow.js

@@ -22,8 +22,9 @@ function printInitHelp() {
   dflow init
 
 Initializes Dflow project specs under dflow/specs/.
-The command prompts for project type, tech stack, prose language,
-optional starter files, and AI coding agents before showing a full file preview.
+The command prompts for project type, tech stack, migration context, prose
+language, Git policy, AI commit marker, optional starter files, and AI coding
+agents before showing a full file preview.
 `);
 }
 
@@ -38,7 +39,7 @@ dflow/specs/shared/AI-AGENT-GUIDE.md file.
 
 Options:
   --command-adapters  Also generate tool-native thin wrappers for supported tools.
-  --skills            Also generate a supported tool's skill adapter (currently Claude Code project skill, restores natural-language auto-trigger).
+  --skills            Also generate project-level skill adapters for supported tools (Claude Code and Codex), restoring natural-language auto-trigger.
 `);
 }
 

package/docs/evaluating-dflow.en.md

@@ -42,15 +42,18 @@ in your project's `dflow/specs/` directory and AI instruction files.
   completion checklists, templates). This bundle is projected from the npm
   package at init time so workflows are reachable from any clone without
   needing the Dflow source or package installed locally.
-- Mergeable AI agent instruction files for the tools you select (e.g.,
-  `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`). Each is a
-  thin pointer to the canonical guide and workflow bundle.
+- AI agent instruction files, or marked Dflow blocks inside existing files, for
+  the tools you select (e.g., `CLAUDE.md`, `AGENTS.md`,
+  `.github/copilot-instructions.md`). Each points the tool to the canonical
+  guide and workflow bundle.
 
 `init` does **not**:
 
 - Inspect, refactor, or migrate your application code.
-- Overwrite existing AI agent instruction files; if one exists, Dflow writes
-  a merge snippet under `dflow/specs/shared/` instead.
+- Overwrite custom content in existing AI agent instruction files; if one
+  exists, Dflow refreshes Dflow-generated shims, leaves a file that already
+  points to the guide as-is, shows and appends a marked Dflow block by default
+  otherwise, and writes a fallback merge snippet only on marker conflicts.
 - Modify your build system, package manager, or dependencies.
 - Send any data anywhere; it is a local scaffolding command.
 
@@ -177,8 +180,9 @@ Dflow is designed for low cost to try and low cost to leave:
 - Nothing depends on the `dflow-sdd-ddd` CLI being installed after `init`.
 - The generated files are plain Markdown; remove Dflow from a project with
   `rm -rf dflow/` plus deleting the AI agent shim files you no longer want.
-- Existing project instruction files (e.g., a pre-existing `CLAUDE.md`) are
-  not modified by Dflow, so reverting is straightforward.
+- If an existing project instruction file (e.g., a pre-existing `CLAUDE.md`)
+  received a marked Dflow block, remove that block to revert it; later
+  `init` / `configure-agents` runs will append it again.
 
 This means an evaluation pass leaves no permanent footprint if you decide
 not to adopt.

package/docs/evaluating-dflow.md

@@ -31,13 +31,16 @@ Dflow 是 Markdown-based 的 workflow 材料加上一個 scaffolding CLI。它
   各 `/dflow:*` workflow 的可執行步驟定義（step gates、completion checklists、模板）。
   這個 bundle 在 init 時從 npm 套件投影進專案，因此 workflow 步驟是 self-contained
   且可達的，任何 clone 都不需要 Dflow source 或 package 在本機安裝。
-- 你所選工具的可合併 AI 指示檔（例如 `CLAUDE.md`、`AGENTS.md`、`.github/copilot-instructions.md`）。
-  每個都是指向 canonical 指南與 workflow bundle 的薄 shim。
+- 你所選工具的 AI 指示檔或既有檔案中的 marked Dflow block（例如 `CLAUDE.md`、`AGENTS.md`、`.github/copilot-instructions.md`）。
+  每個都把工具指向 canonical 指南與 workflow bundle。
 
 `init` **不會**：
 
 - 檢查、重構、或遷移你的應用程式碼。
-- 覆寫既有的 AI 指示檔；若檔案已存在，Dflow 改在 `dflow/specs/shared/` 下寫入 merge snippet。
+- 覆寫既有 AI 指示檔中的自訂內容；若檔案已存在，Dflow 會刷新
+  Dflow-generated shim，已指向 guide 的檔案則保持原樣，其他情況預設在確認
+  preview 顯示並附加 marked Dflow block，只有 marker conflict 才寫 fallback
+  merge snippet。
 - 修改你的建構系統、套件管理工具、或相依套件。
 - 傳送任何資料到外部；它是本機的 scaffolding 指令。
 
@@ -136,7 +139,9 @@ Dflow 的設計讓試用成本低、退出成本也低：
 
 - `init` 完成後，你的專案不依賴已安裝的 `dflow-sdd-ddd` CLI。
 - 產生的檔案都是純 Markdown；用 `rm -rf dflow/` 加上刪除你不再需要的 AI 指示 shim 檔案，即可從專案中移除 Dflow。
-- 既有的專案指示檔（例如原本就存在的 `CLAUDE.md`）不會被 Dflow 修改，因此復原很直接。
+- 既有的專案指示檔（例如原本就存在的 `CLAUDE.md`）若被加入 marked Dflow
+  block，刪除該 block 即可復原；但之後再跑 `init` / `configure-agents`
+  會再附加它。
 
 這表示評估一輪後，若你決定不採用，不會留下任何永久痕跡。
 

package/docs/migrating-to-dflow-v1.md

@@ -174,9 +174,13 @@ dflow configure-agents
 ```
 
 This command adds shims for any AI tools you select. `dflow configure-agents`
-does not overwrite an existing `CLAUDE.md`; instead, it writes a
-`dflow/specs/shared/<tool>-md-snippet.md` that you can merge into the
-existing file at your own pace.
+does not overwrite custom content in an existing root instruction file. If it
+recognizes an older Dflow-generated shim, it refreshes that file to the current
+thin shim in place; a file that already points to the guide is left as-is;
+otherwise it shows the change in the preview and appends a marked Dflow block to
+the existing file. It writes a manual-merge snippet under
+`dflow/specs/shared/<tool>-md-snippet.md` only when the file contains
+conflicting or malformed Dflow markers.
 
 If you prefer a fully clean V1 layout, archive the existing root
 instruction file under another name first, then run

package/docs/using-with-claude-code.en.md

@@ -45,18 +45,18 @@ selecting Claude Code as a target tool creates a thin shim at the project root:
 
 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,
-spec locations, and SDD/DDD constraints.
-
-If your tool supports Markdown imports, the canonical guide is imported
-below:
+For routine work (refactors, renames, chores, formatting, dependency bumps, or
+general code questions), proceed normally; you need not read the guide first.
 
-@dflow/specs/shared/AI-AGENT-GUIDE.md
+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.
 ```
 
 Two things happen when Claude Code starts in this project:
@@ -64,9 +64,11 @@ Two things happen when Claude Code starts in this project:
 1. Claude Code automatically loads `CLAUDE.md` from the project root into
    its context. This is Claude Code's standard project instructions
    mechanism.
-2. The trailing `@dflow/specs/shared/AI-AGENT-GUIDE.md` line uses Claude
-   Code's Markdown import syntax to inline the canonical Dflow guide. So
-   Claude Code effectively reads both files as one set of instructions.
+2. `CLAUDE.md` is a thin pointer: it names the canonical guide but does not
+   inline it. The guide is loaded on demand — the `dflow` skill pulls it in
+   when relevant work auto-triggers the skill, or the agent follows the
+   pointer for spec-impacting work. This keeps the guide out of every
+   session's context (progressive disclosure) instead of force-loading it.
 
 The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the
 **command registry and router**: project context (track, tech stack, prose
@@ -79,9 +81,14 @@ checked into your repo, so they travel with the project when cloned. The
 without Claude-Code-specific edits.
 
 If a `CLAUDE.md` already existed in the project, `init` does not overwrite
-it. Instead it writes a merge snippet under `dflow/specs/shared/` that you
-can paste into your existing `CLAUDE.md` manually. This avoids destroying
-custom project instructions you already had.
+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
+without adding a second pointer. Otherwise 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. Dflow
+writes the fallback merge snippet `dflow/specs/shared/CLAUDE-md-snippet.md` only
+when the file contains conflicting or malformed Dflow markers.
 
 ## Using Dflow Slash Commands in Claude Code
 
@@ -225,6 +232,12 @@ This skill does not copy workflow steps; its body points to the canonical
 `dflow/specs/shared/AI-AGENT-GUIDE.md` (command registry and routing rules) and
 `dflow/specs/shared/dflow-workflows/` (vendored bundle with executable step
 definitions).
+
+The same edition-neutral skill source is now also projected by `--skills` as a
+project-level skill for Codex (`.agents/skills/dflow/SKILL.md`) and GitHub Copilot
+(`.github/skills/dflow/SKILL.md`); all three follow the same cross-tool
+agentskills.io standard.
+
 Its behavior:
 
 - **Auto-triggers on** feature / bug-fix workflows, product/domain behavior
@@ -275,7 +288,7 @@ across tools. Only the root-level shim differs:
 
 | Tool | Generated shim | Loads canonical guide via |
 |---|---|---|
-| 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 |
 | GitHub Copilot | `.github/copilot-instructions.md` | Reads file content directly |
 
@@ -315,16 +328,20 @@ their own approval gates (e.g., "I drafted the spec — do you want me to
 proceed to implementation?"). Both can fire on the same action; this is
 expected and not a sign of misconfiguration.
 
-**The `@` import is not recursive.** `CLAUDE.md` imports
-`AI-AGENT-GUIDE.md`, but if `AI-AGENT-GUIDE.md` references other files
-(e.g., feature specs), those are not auto-loaded — Claude Code reads them
-on demand when entering the relevant workflow. This keeps context usage
+**Guide references are not all loaded at once.** `CLAUDE.md` points to
+`AI-AGENT-GUIDE.md`, and the other files `AI-AGENT-GUIDE.md` references
+(e.g., feature specs) are also read on demand — Claude Code reads them
+when entering the relevant workflow. This keeps context usage
 proportional to active work.
 
 **A pre-existing `CLAUDE.md` is preserved.** `init` will not overwrite your
-existing project instructions. Look under `dflow/specs/shared/` for the
-merge snippet `init` wrote and paste the relevant sections into your
-existing `CLAUDE.md` manually.
+custom project instructions. Dflow-generated shims are refreshed in place; it
+skips other files that already point to `AI-AGENT-GUIDE.md`. Otherwise it shows
+the marked Dflow block in the confirmation preview, then refreshes that same
+block in place on later runs.
+If you delete the block, the next `init` / `configure-agents` run appends it
+again. Look under `dflow/specs/shared/` for a fallback merge snippet only when
+there is a marker conflict to resolve manually.
 
 **Cross-machine projects work.** `dflow/specs/` is plain Markdown checked
 into your repo. Anyone cloning the repo and using Claude Code in it will

package/docs/using-with-claude-code.md

@@ -40,27 +40,28 @@ commands 是如何被識別的，以及幾個值得了解的 Claude Code 專屬
 
 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,
-spec locations, and SDD/DDD constraints.
-
-If your tool supports Markdown imports, the canonical guide is imported
-below:
+For routine work (refactors, renames, chores, formatting, dependency bumps, or
+general code questions), proceed normally; you need not read the guide first.
 
-@dflow/specs/shared/AI-AGENT-GUIDE.md
+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.
 ```
 
 Claude Code 在這個專案中啟動時，會發生兩件事：
 
 1. Claude Code 自動從專案根目錄載入 `CLAUDE.md` 到它的 context 中。
    這是 Claude Code 的標準專案指示機制。
-2. 末尾的 `@dflow/specs/shared/AI-AGENT-GUIDE.md` 這行使用 Claude Code 的
-   Markdown import 語法，將 canonical Dflow 指南 inline 嵌入。因此 Claude Code
-   等效於把兩個檔案當成一組指示來讀取。
+2. `CLAUDE.md` 是一份薄指標，只指向 canonical 指南、不把它 inline 進來。
+   指南改為按需載入——`dflow` skill 在相關工作自動觸發時把它讀進來，或由
+   AI 在做 spec-impacting 工作時跟著指標讀取。指南因此不會被塞進每個 session 的
+   context（progressive disclosure），而非每次強制載入。
 
 canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）是**命令登錄表與路由器**：
 專案上下文（track、技術棧、文章語言）、`/dflow:*` workflow 表、source-of-truth
@@ -71,9 +72,12 @@ completion checklists）則放在 `init` 投影進專案的 **vendored workflow
 `CLAUDE.md` shim 刻意保持精簡，這樣 canonical 指南就能在不需要 Claude Code
 專屬修改的情況下持續演進。
 
-如果專案中已有 `CLAUDE.md`，`init` 不會覆蓋它。它改為在
-`dflow/specs/shared/` 下寫入 merge snippet，讓你手動貼入現有的 `CLAUDE.md`。
-這樣可以避免破壞你已有的自訂專案指示。
+如果專案中已有 `CLAUDE.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/CLAUDE-md-snippet.md` fallback merge snippet 讓你手動處理。
 
 ## 在 Claude Code 中使用 Dflow Slash Commands
 
@@ -199,6 +203,11 @@ dflow configure-agents --skills
 這份 skill 不複製 workflow 步驟，body 指向 canonical
 `dflow/specs/shared/AI-AGENT-GUIDE.md`（命令登錄表與路由規則）以及
 `dflow/specs/shared/dflow-workflows/`（含可執行步驟定義的 vendored bundle）。
+
+同一份 edition-neutral skill source，現在也會由 `--skills` 為 Codex
+（`.agents/skills/dflow/SKILL.md`）與 GitHub Copilot（`.github/skills/dflow/SKILL.md`）
+投影 project-level skill，三家沿用相同的跨工具 agentskills.io 標準。
+
 它的行為：
 
 - **自動觸發於** feature / bug-fix workflow、product/domain behavior 變更、新需求、
@@ -239,7 +248,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` | 啟動時直接讀取檔案內容 |
 | Codex / Copilot coding agent | `AGENTS.md` | 啟動時直接讀取檔案內容 |
 | GitHub Copilot | `.github/copilot-instructions.md` | 直接讀取檔案內容 |
 
@@ -274,14 +283,16 @@ adapter wrapper 必須保持薄指標，不應複製 workflow 語義。
 「我已起草 spec —— 你要我繼續進入實作嗎？」）。兩者可能在同一個動作上同時觸發；
 這是預期行為，不代表設定有誤。
 
-**`@` import 不是遞迴的。** `CLAUDE.md` import 了 `AI-AGENT-GUIDE.md`，但如果
-`AI-AGENT-GUIDE.md` 引用了其他檔案（例如 feature spec），那些檔案不會被自動
-載入 —— Claude Code 會在進入對應 workflow 時按需讀取它們。這樣可以讓 context
-用量與正在進行的工作保持比例。
+**指南的引用不會被一次全部載入。** `CLAUDE.md` 指向 `AI-AGENT-GUIDE.md`；而
+`AI-AGENT-GUIDE.md` 引用的其他檔案（例如 feature spec）也是按需載入 —— Claude
+Code 會在進入對應 workflow 時才讀取它們。這樣可以讓 context 用量與正在進行的
+工作保持比例。
 
-**既有的 `CLAUDE.md` 會被保留。** `init` 不會覆蓋你現有的專案指示。請到
-`dflow/specs/shared/` 下找 `init` 寫入的 merge snippet，並手動將相關段落貼入
-你現有的 `CLAUDE.md`。
+**既有的 `CLAUDE.md` 會被保留。** `init` 不會覆蓋你現有的自訂專案指示；已是
+Dflow-generated shim 會原地刷新，其他已指向 `AI-AGENT-GUIDE.md` 的檔案會略過，
+否則會在確認 preview 顯示要附加的 marked Dflow block，寫入後重跑會原地更新同一段。
+若你刪除該 block，下一次 `init` / `configure-agents` 會再附加它；只有 marker
+conflict 時才需要到 `dflow/specs/shared/` 找 fallback merge snippet 手動處理。
 
 **跨機器專案可正常運作。** `dflow/specs/` 是純 Markdown，已 check in 到你的
 repo。任何人 clone 該 repo 並在其中使用 Claude Code，都會透過已 commit 的