dflow-sdd-ddd 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -6,6 +6,59 @@
 
 ---
 
+## 0.10.0 — 2026-06-06 — agentskills 標準三家觸發 parity、既有 agent 檔自動注入、投影內容保全與清理
+
+**Proposals**：PROPOSAL-049（feature-slice 使用面語意體檢）、PROPOSAL-050（還原 041 雙軌合一丟失的 skill 內容進 AI-AGENT-GUIDE）、PROPOSAL-051（退役 `templates/CLAUDE.md`）、PROPOSAL-052（bundle stale-removal 推廣到同-edition）、PROPOSAL-054（既有 agent 檔 Dflow 墊片 auto-inject）、PROPOSAL-056（Codex 專案層 skill `--skills` parity）、PROPOSAL-057（以 agentskills.io 標準為三家共同自動觸發層；Phase 2）
+
+本版兩條主線：
+
+1. **入口層標準化 + 降低採用摩擦**（054 / 056 / 057 + Copilot 指南）—— 三家（Claude / Codex / Copilot）以 agentskills.io 開放標準取得 project-level skill 投影 parity（自然語言觸發；Copilot CLI 仍需 `/dflow` 喚起）、既有 agent 檔零手動合併即接上、Claude shim 瘦身、Copilot 跨介面用法講清楚。
+2. **投影內容保全與清理**（049 / 050 / 051 / 052）—— 一輪 feature-by-feature 語意體檢補回 041 雙軌合一時孤兒化的 canonical 內容、退役 legacy 範本、把 bundle 退役檔清除推廣到最常見的同-edition 升級。
+
+### 新功能 / 行為改善
+
+- **`dflow configure-agents --skills` 三家專案層 skill parity（Codex 補自動觸發、Copilot 補原生 skill）**（PROPOSAL-056 + #4 un-defer）：`--skills` 從「只投 Claude、寫死單一路徑」一般化為「把同一份工具中立 thin skill（`templates/common/skill/SKILL.md`）投影到每個被選工具各自的 project-level skill 路徑」。Claude 維持 `.claude/skills/dflow/SKILL.md`；**Codex 新增 `.agents/skills/dflow/SKILL.md`**，找回 Codex 的自然語言自動觸發（先前只有手動命令 / 文字 trigger）；**GitHub Copilot 新增 `.github/skills/dflow/SKILL.md`**（#4 un-defer：spike 確認 Copilot 從自己原生 `.github/skills/` 探索成立、即使移除 `.claude`/`.agents` 跨讀路徑也成立——**VS Code Chat 自然語言自動觸發、Copilot CLI 仍需 `/dflow` 手動喚起**）。Copilot 也會跨讀 `.claude`/`.agents`；Dflow 產生的各份逐字相同，但若該路徑已有非 Dflow 的同名 skill，Dflow 會保留不覆寫、可能內容不同（移除或改名即可避免同名重複）。依據：Claude / Codex / Copilot 已收斂於 agentskills.io 開放標準（皆以 `SKILL.md` 為入口、`name`/`description` frontmatter、project-level 探索、description 驅動自動觸發）。
+
+- **既有 agent 檔的 Dflow 墊片 auto-inject（三工具統一）**（PROPOSAL-054）：當使用者已有自己的根 agent 檔（Claude `CLAUDE.md`、Codex `AGENTS.md`、Copilot `.github/copilot-instructions.md`）且尚未引用 guide，`init` / `configure-agents` 不再預設「丟一個 snippet 檔、Notes 一行請你手動合併」，改為**附加一塊帶 `<!-- dflow-generated: agent-shim START/END -->` 標記的 Dflow 區塊**（呈現為確認預覽裡的一般項目），重跑時**原地抽換**該區塊（idempotent）。snippet + 警告降為 fallback，只在標記殘缺 / 重複 / 顛倒等無法安全注入時才用；並補上先前缺的對稱警告（最常見路徑反而 signpost 最弱的洞）。指令只能以文字寫進 `AGENTS.md` 的 Codex 受惠最大。
+
+- **bundle 退役檔在同-edition 升級也自動清除**（PROPOSAL-052）：`configure-agents` 的 bundle stale-removal 原本只在 **edition 改變**時觸發；現在推廣為「依 manifest diff 清除『舊 manifest 有、當前 bundle 已無』的退役檔」，涵蓋最常見的**同-edition 重跑升級**。一併補三道 projection-cleanup 硬化：current-bundle 非空 guard（防 bundle 掃出空集合時誤刪整包、砍掉 `/dflow:*` 可達性）、壞 manifest 區分 ENOENT vs parse/IO error（後者至少 warn，不再靜默跳過）、待刪檔措辭從硬編「stale adapter / edition changed」修正為通用。**直接受惠**：051 退役 `templates/CLAUDE.md` 後既有同-edition 專案殘留的 vendored copy，重跑 `dflow configure-agents` 即被清掉。
+
+- **Claude shim 瘦身為薄指標**（PROPOSAL-057 Phase 2）：`init` 生成的根 `CLAUDE.md` 墊片不再用 `@import` 把整份 `AI-AGENT-GUIDE.md`（~5k tokens）每個 session 強制載入，改為路徑無關的薄 awareness，並把「讀 guide」scoping 到 spec-impacting work（對齊 progressive disclosure；workflow 步驟本就按需載入）。
+
+- **skill 自動觸發 recall 強化**（PROPOSAL-057 Phase 2）：`templates/common/skill/SKILL.md` 的 `description` 補上間接觸發語（不點命令名的自然語句也能觸發），修掉先前「最間接語句 recall 較弱」的弱點；同時收斂在 **Codex 的 1024 字元上限**內（986 chars），並加 `test/registry-parity.mjs` 護欄斷言 folded description ≤ 1024 防回歸。觸發契約維持 suggest-and-wait（建議命令、等確認，不自動跑完整個 workflow）。
+
+### 文件
+
+- **GitHub Copilot 指南分介面重寫**（copilot-cmd-surface，2026-06-05 實測）：`docs/using-with-github-copilot.md` + `.en.md` 把 Copilot 用法分為 **VS Code Copilot Chat** 與 **GitHub Copilot CLI** 兩節，各自講自動觸發有無、命令能不能用、正確語法 —— VS Code Chat 自然語言自動觸發 + `/dflow-<id>`（連字號，需 `--command-adapters`）；Copilot CLI 無自動觸發、先打 `/dflow` 手動喚起 skill、無 per-id 命令（`.github/prompts/` CLI 不讀取）。冒號形式 `/dflow:<id>` 釐清為 canonical / Claude·Codex 命令語法，在 Copilot 只能當文字稱呼。移除舊的「chat 文字可直接說 canonical `/dflow:<id>`」易誤導措辭。雙語 parity。
+
+### 投影內容保全（PROPOSAL-049 / 050）
+
+- **feature-slice 使用面語意體檢**（PROPOSAL-049）：對「使用 Dflow 時實際會碰到的範圍」（CLI runtime + init 投影的 bundle / adapter + 雙軌 skill source）做一輪 feature-by-feature 人讀語意體檢，補 047（首次 implementation-stage cross-model review）之前 ship、未過該層 review 的盲區。修掉的 drift 含：`modify-existing-flow` 等殘留「the developer commits」的 pre-047 行為者口吻、Greenfield context-definition 路徑兩軌 parity、`/dflow:verify` scope over-claim、`last-updated` 權威歸 `rules.md` 等。純語意 / 結構修正，grep 擋不住。
+
+- **還原 041 合一丟失的 canonical 內容**（PROPOSAL-050）：041 把兩份 per-edition `SKILL.md` 合一成 35 行薄殼時，數個被各 flow 以 `see SKILL.md § …` 指向的 workflow-protocol 段變成**懸空 ref**。本版把這些段（Workflow Transparency〔Auto-Trigger Safety Net / Three-Tier Transparency / Confirmation Signals NL↔Command / Completion Checklist〕、Ceremony Scaling 完整 T1/T2/T3 表、Guiding Questions by Activity、Project Structure）還原進**兩軌 `AI-AGENT-GUIDE.md`**（runtime 面），並 repoint ~15 處 ref；另還原 conservation audit 抓到的 silent-drop（Brownfield 不適用排除條款、三項可攜資產立論、非指令 decision routing、完成清單 skip-detection guard）。使用者專案的 canonical 指南因此恢復完整、ref 不再撲空。
+
+### Migration / 升級提醒
+
+- **`templates/CLAUDE.md` 退役（移除一個 vendored generated 檔）**（PROPOSAL-051）：刪除 Greenfield / Brownfield 各一份 source + mirror 共 4 檔（legacy full-layout 範例）。它**不是** `init` 來源（根 `CLAUDE.md` 由 `lib/init.js` 程式化生成薄殼），canonical 內容（decision routing / Ceremony 表 / per-flow steps）已於 050 全數移進 `AI-AGENT-GUIDE.md` + bundle。**對既有專案的影響**：先前以同-edition 跑過的專案，其 vendored copy `dflow/specs/shared/dflow-workflows/templates/CLAUDE.md` 會留為**無害殘檔**（帶 generated marker、不被任何 flow 消費）；**重跑 `dflow configure-agents` 即自動清除**（PROPOSAL-052 的同-edition stale-removal）。npm tarball 因此縮減一個 generated file。
+
+- **Claude shim 形狀改變**（PROPOSAL-057）：既有專案的根 `CLAUDE.md` 仍可用；若要拿到瘦身後的薄指標版，重跑 `dflow init` / `dflow configure-agents` 即原地刷新該 Dflow 區塊。
+
+### 維護者工具 / 測試（不影響套件使用者）
+
+- **cross-ref resolver guard**（PROPOSAL-055，dev-only）：新增 `scripts/check-cross-refs.mjs`（納入 `check-repo-consistency.sh`），把「文件 `§` / 檔名 / 路徑 ref 解不解得開」從一次性人工 grep 固化為常駐檢查；namespace-aware（限 public source + governance 範圍、跳過 history 與 `{token}` 佔位、§/anchor longest-prefix）。`scripts/` 不投影 dist、不進 tarball。
+- **registry-parity 測試**（PROPOSAL-053，dev-only）：新增 `test/registry-parity.mjs`，斷言 11 個 `/dflow:*` 指令表跨 surface / 雙軌一致（F-02 安全網）；後並加 057 的 folded description ≤ 1024 斷言。
+- **`test/agent-inject.mjs`**（PROPOSAL-054）：新增既有 agent 檔 auto-inject 的注入 / idempotent 抽換 / fallback 矩陣覆蓋。
+- `test/smoke.mjs`：擴充 054 auto-inject、056 `--skills` 各家路徑、052 同-edition stale-removal 等斷言。
+
+### 驗證
+
+- `npm test`（`smoke.mjs` + `registry-parity.mjs` + `agent-inject.mjs` 全綠）
+- `scripts/check-repo-consistency.sh`（含 `check-cross-refs.mjs` + registry parity + source↔mirror diff + `npm pack --dry-run` + `git diff --check`）pass、0 error
+- `scripts/export-dist.sh --dry-run`：dev / dist 已同步、無 drift
+- 049–057 各 proposal 實作均經 implementation-stage cross-model review 收斂 approve（見各 closeout 紀錄）
+
+---
+
 ## 0.9.0 — 2026-05-28 — 執行當下對齊：feedback 逐欄產出、Codex trigger 注入、commit checkpoints + branch gate（含 breaking changes）
 
 **Proposals**：PROPOSAL-048（feedback 輸出對齊目標 issue 表單）、PROPOSAL-046（Codex command-trigger 注入既有 AGENTS.md shim）、PROPOSAL-047（commit checkpoints、branch lifecycle 強制、AI commit 政策翻轉、init Git policy 升必選）

package/README.en.md

@@ -216,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
@@ -229,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)
 
@@ -247,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

package/README.md

@@ -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、一邊版控。
 

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,9 +22,9 @@ function printInitHelp() {
   dflow init
 
 Initializes Dflow project specs under dflow/specs/.
-The command prompts for project type, tech stack, prose language, Git policy,
-AI commit marker, 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.
 `);
 }
 
@@ -39,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 的