dflow-sdd-ddd 0.9.0 → 0.11.0

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/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 的

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