dflow-sdd-ddd 0.9.0 → 0.10.0

package/docs/using-with-codex.en.md

@@ -48,12 +48,17 @@ 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,
+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.
 ```
 
@@ -61,13 +66,14 @@ Two things matter when Codex starts in this project:
 
 1. Codex CLI reads `AGENTS.md` as project instructions. This is Codex's
    standard repository-instruction mechanism.
-2. The Dflow shim does not include a Markdown import line. Unlike the
-   Claude Code shim, generated `AGENTS.md` does not contain
-   `@dflow/specs/shared/AI-AGENT-GUIDE.md`.
+2. The Dflow shim is a thin pointer and does not inline the guide. Generated
+   `AGENTS.md` points to `dflow/specs/shared/AI-AGENT-GUIDE.md` with a plain
+   Markdown bullet.
 
 That means Codex sees the pointer immediately, but the canonical Dflow guide
-is not auto-inlined by the shim. Before planning or editing, Codex should
-follow the pointer and read `dflow/specs/shared/AI-AGENT-GUIDE.md`. If Codex
+is not auto-inlined by the shim. For spec-impacting work (a feature, a
+behavior change, or a bug fix), Codex should follow the pointer and read
+`dflow/specs/shared/AI-AGENT-GUIDE.md`. If Codex
 starts answering a Dflow request without mentioning that file, steer it
 explicitly: "Before continuing, read and follow
 `dflow/specs/shared/AI-AGENT-GUIDE.md`."
@@ -79,13 +85,25 @@ stays small so the same canonical guide can serve Codex CLI, Claude Code,
 GitHub Copilot, and other tools.
 
 If an `AGENTS.md` already existed in the project, `init` does not overwrite
-it. If the existing file does not already point to
-`dflow/specs/shared/AI-AGENT-GUIDE.md`, `init` writes a merge snippet under
-`dflow/specs/shared/AGENTS-md-snippet.md` that you can merge manually. This
-avoids destroying custom project instructions you already had.
-
-In the `dflow configure-agents --command-adapters` case, the corresponding
-snippet path is `dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`.
+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. Dflow writes the fallback merge
+snippet
+`dflow/specs/shared/AGENTS-md-snippet.md` only when the file contains
+conflicting or malformed Dflow markers.
+
+With `dflow configure-agents --command-adapters`, the marker-conflict fallback
+splits into two files depending on which markers are broken: when only the
+trigger markers are malformed but the file still points to the canonical guide,
+Dflow writes the trigger-only
+`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`; any other marker
+conflict (the agent-shim markers are malformed, or the two marked regions overlap
+or straddle) takes the full-shim `dflow/specs/shared/AGENTS-md-snippet.md`. Both
+appear only on a marker conflict;
+see *Codex Behavior With Optional Command Adapters* below.
 
 ## Using Dflow Workflow Commands in Codex CLI
 
@@ -157,9 +175,12 @@ workflows.
 ### Codex Behavior With Optional Command Adapters
 
 For Codex, `dflow configure-agents --command-adapters` strengthens text
-triggers only. It does not create Codex command files and it does not add
-`.agents/skills/dflow/SKILL.md`. Codex v1 has no Dflow command-file adapter
-equivalent to Claude `.claude/commands` or Copilot `.github/prompts`.
+triggers only. It does not create Codex command files. Codex v1 has no Dflow
+command-file adapter equivalent to Claude `.claude/commands` or Copilot
+`.github/prompts`.
+
+**Auto-trigger skills come from `--skills`, not `--command-adapters`.** See
+"Codex Behavior With Optional Skills" below.
 
 When you select `AGENTS.md - Codex / Copilot coding agent` in
 `--command-adapters` mode, Dflow writes a trigger list generated from the
@@ -177,21 +198,76 @@ in markers, with zero manual merge. Re-running re-projects that same section in
 place instead of appending a duplicate.
 
 If `AGENTS.md` was edited after Dflow generated it, or is your own custom file,
-Dflow leaves it untouched and instead writes the trigger section to a merge
-snippet for you to merge manually. In that case the Codex-target merge snippet
-filename is `dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`.
+Dflow still preserves the existing content and appends (or refreshes in place)
+the trigger section as an adjacent marked block in `AGENTS.md` through the same
+mechanism. The confirmation preview shows that block first. Dflow falls back to a
+manual-merge snippet only when existing Dflow markers are too broken to edit in
+place safely, and which snippet it writes depends on which markers are broken:
+
+- **Only the trigger markers are malformed, while the agent-shim markers and their
+  region are otherwise intact (no overlap or straddle), and the file already points
+  to the canonical guide.** The guide pointer is already in place, so the snippet
+  carries just the trigger section:
+  `dflow/specs/shared/AGENTS-md-command-adapters-snippet.md`.
+- **Any other marker conflict** — for example the agent-shim markers themselves
+  are malformed, or the agent-shim and trigger marked regions overlap or straddle
+  each other. The snippet then carries the full shim (title, guide pointers, and,
+  under `--command-adapters`, the trigger section):
+  `dflow/specs/shared/AGENTS-md-snippet.md`.
+
+Both snippets appear only on a marker conflict. A clean custom `AGENTS.md` with
+no conflicting markers does not produce a snippet at all — Dflow just appends the
+adjacent marked block in place.
+
+### Codex Behavior With Optional Skills (Auto-Trigger)
+
+`dflow configure-agents --skills` projects a thin, tool-neutral skill to
+`.agents/skills/dflow/SKILL.md` — Codex's project-level skill path. This gives
+Codex **natural-language auto-trigger on par with Claude Code**: when you
+describe intent like "help me start a new feature", Codex can judge relevance
+from the skill's `description`, suggest the matching `dflow:<id>` workflow, and
+no longer require you to remember a command every time.
+
+The skill body and frontmatter (`name` / `description`) are plain text that
+only point to the canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) and
+the vendored workflow bundle. It is the **same source** Claude projects
+(`templates/common/skill/SKILL.md`) — no per-tool content fork. When
+auto-triggered, the skill's contract is to judge intent, suggest the matching
+`dflow:<id>`, and wait for your confirmation before entering a workflow rather
+than running one directly.
+
+Re-running `--skills` rewrites the same marker-stamped skill in place
+(idempotent). If a **non**-Dflow file already exists at that path (no
+`<!-- dflow-generated: skill-adapter -->` marker), Dflow does not overwrite it —
+it warns and leaves your file untouched.
+
+> GitHub Copilot is supported too: selecting Copilot under `--skills` projects
+> `.github/skills/dflow/SKILL.md` (the same thin skill). Copilot also cross-reads
+> the `.claude`/`.agents` paths; Dflow-generated copies are byte-identical, 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 same-name duplicate.
 
 ### Version-Control Policy for Generated Artifacts (Codex)
 
 Codex does not generate command files, so there is **no derived adapter to
-gitignore**. On the Codex side, what you version-control is the `AGENTS.md`
-shim and `dflow/` (the canonical guide and specs); the merge helper
-`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md` is part of `dflow/`
-and is **version-controlled along with `dflow/`**. `--command-adapters` only
-strengthens the text triggers in `AGENTS.md` for Codex; it adds no `.claude/`,
-`.github/`, or `.agents/` command files, so the Claude / Copilot
-"version-control the generated adapter or not" trade-off does not apply on the
-Codex side. The adapter version-control policy for other tools is covered in
+gitignore** on the `--command-adapters` side. On the Codex side, what you
+version-control is the `AGENTS.md` shim / marked blocks and `dflow/` (the
+canonical guide and specs). The fallback merge helpers
+(`dflow/specs/shared/AGENTS-md-command-adapters-snippet.md` or
+`dflow/specs/shared/AGENTS-md-snippet.md`) are created only on a marker conflict;
+if one appears, it is part of `dflow/` and is **version-controlled along with
+`dflow/`**. `--command-adapters` only strengthens
+the text triggers in `AGENTS.md` for Codex; it adds no `.claude/`, `.github/`,
+or `.agents/` command files.
+
+The one Codex derived artifact comes from `--skills`:
+`.agents/skills/dflow/SKILL.md`. Like Claude's `.claude/skills/dflow/SKILL.md`,
+it is regenerable from the canonical guide and follows the same **recommended
+default** (do not version-control; regenerate after clone with
+`configure-agents --skills`; version-controlling it is also reasonable if your
+team wants auto-trigger immediately after clone — the rule is one consistent
+policy across tools in a project). The adapter / skill version-control policy
+for other tools is covered in
 [README "Files Created by Init"](../README.en.md#files-created-by-init) and the
 per-tool guides.
 
@@ -202,7 +278,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` | Project instructions load the shim; follow the pointer to read the guide |
 | Codex / Copilot coding agent | `AGENTS.md` | Project instructions load the shim; Codex must follow the pointer and read the guide |
 | GitHub Copilot | `.github/copilot-instructions.md` | Reads repository instructions directly |
 
@@ -220,7 +296,7 @@ root, and keep the Dflow pointer in the nearest relevant `AGENTS.md`.
 
 If your team uses both Claude Code and Codex CLI on the same project, no
 extra Dflow coordination is needed. Both tools use the same canonical guide;
-only the shim file and loading mechanism differ.
+only the shim file differs.
 
 ## Common Patterns and Gotchas
 
@@ -230,9 +306,9 @@ locations, or SDD constraints to `AGENTS.md`, those belong in
 other tools' shims do not drift away from it.
 
 **Codex does not inline the Dflow guide from `AGENTS.md`.** The generated
-Codex shim has a normal Markdown bullet pointing to the canonical guide, not
-an `@...` import. Ask Codex to read `AI-AGENT-GUIDE.md` if it appears to be
-working from the shim alone.
+Codex shim has a normal Markdown bullet pointing to the canonical guide. Ask
+Codex to read `AI-AGENT-GUIDE.md` if it appears to be working from the shim
+alone.
 
 **`/dflow:*` is not a Codex CLI built-in slash command.** Codex slash commands
 control the Codex session itself. When raw slash input is intercepted or
@@ -241,9 +317,12 @@ rejected, use the no-slash text form `dflow:<id>`, for example
 workflow by reading `AI-AGENT-GUIDE.md`.
 
 **Codex does not generate command files.** Even with `--command-adapters`,
-Codex only strengthens text-trigger guidance in `AGENTS.md` / merge
-snippets. Do not expect Codex-specific files under `.claude/commands`,
-`.github/prompts`, or `.agents/skills/dflow/SKILL.md`.
+Codex only strengthens text-trigger guidance in marked blocks inside
+`AGENTS.md`; fallback merge snippets are created only on marker conflicts. Do
+not expect Codex-specific **command** files under `.claude/commands` or
+`.github/prompts`. (Auto-trigger **skills** are separate: `--skills` projects
+one to `.agents/skills/dflow/SKILL.md`, see "Codex Behavior With Optional
+Skills" above.)
 
 **Do not confuse Codex `/init` with Dflow `init`.** Codex `/init` creates a
 generic `AGENTS.md` scaffold for Codex. Dflow setup is `dflow init` (or
@@ -262,10 +341,14 @@ approvals.** In current Codex CLI terminology this is
 Codex can work inside the project and asks before going beyond the sandbox,
 such as writing outside the workspace or accessing network.
 
-**Existing `AGENTS.md` files are preserved.** If Dflow cannot safely write
-the root shim because the file already exists, look under
-`dflow/specs/shared/` for the merge snippet and merge the Dflow pointer into
-your existing project instructions manually.
+**Existing `AGENTS.md` files are preserved.** Dflow does not overwrite your
+custom project instructions. The base pointer is refreshed in place for a
+Dflow-generated shim; other files that already point to `AI-AGENT-GUIDE.md` are
+skipped. Otherwise Dflow shows and appends a marked Dflow block, then refreshes
+that block in place on later runs. `--command-adapters` can still add or refresh
+the adjacent trigger block. If you delete a block, later `init` /
+`configure-agents` runs append it again. Look under `dflow/specs/shared/` for a
+fallback merge snippet only when there is a marker conflict to resolve manually.
 
 **Nested `AGENTS.md` files can change what Codex sees.** Codex layers project
 instructions along the path to the current working directory. If a subfolder

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` 或