dflow-sdd-ddd 0.12.0 → 0.14.0

package/bin/dflow.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const { runConfigureAgents, runDoctor, runInit } = require('../lib/init');
+const { runRender } = require('../lib/render');
 const pkg = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -12,6 +13,7 @@ Usage:
   dflow init              Initialize Dflow specs in the current project
   dflow configure-agents  Add or update AI agent instruction shims
   dflow doctor            Read-only project health check
+  dflow render            Render the specs Markdown tree to browsable HTML
   dflow --help            Show this help
   dflow --version         Show the CLI version
 `);
@@ -24,7 +26,11 @@ function printInitHelp() {
 Initializes Dflow project specs under dflow/specs/.
 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.
+agents, then — when agents were selected on an interactive terminal — whether
+to install the project-level Dflow skill (default yes), before showing a full
+file preview. Non-interactive runs never read an extra stdin answer for the
+skill question: existing scripted answer sequences run unchanged, and the
+skill is installed by default for the selected agents.
 `);
 }
 
@@ -39,7 +45,51 @@ dflow/specs/shared/AI-AGENT-GUIDE.md file.
 
 Options:
   --command-adapters  Also generate tool-native thin wrappers for supported tools.
-  --skills            Also generate project-level skill adapters for supported tools (Claude Code, Codex, and GitHub Copilot), restoring natural-language auto-trigger.
+  --skills            Regenerate project-level skill adapters for all selected supported tools (Claude Code, Codex, and GitHub Copilot), restoring natural-language auto-trigger.
+
+Without --skills, selecting an agent that has no project-level skill yet
+prompts to install it (default yes) on an interactive terminal; non-interactive
+runs install it by default without reading an extra stdin answer. Agents whose
+skill file already exists are not re-asked and not regenerated.
+
+On upgrade re-runs the command also refreshes the marker-guarded canonical
+region of dflow/specs/shared/AI-AGENT-GUIDE.md (content outside the markers,
+including "## Project Context", is kept) and advances the "> Dflow Version:"
+last-reconciled line in _conventions.md. A pre-marker guide, or an agent file
+you edited yourself, is never rewritten silently: interactive runs offer
+marker adoption (default No); non-interactive runs skip and warn. (A pristine,
+unedited Dflow shim is still regenerated in place, as before.)
+`);
+}
+
+function printRenderHelp() {
+  process.stdout.write(`Usage:
+  dflow render [--src <dir>] [--out <dir>] [--title <text>]
+
+Renders the Markdown specs tree into a mirrored static HTML tree for human
+reading (record tables become cards, AI markers become badges), plus an
+index.html file tree at the output root. Open index.html directly in a
+browser; file:// works, no server needed.
+
+Markdown stays the AI-facing source of truth. Re-run this command whenever
+the sources change; every run is a full rebuild.
+
+Options:
+  --src <dir>     Specs root to render (default: dflow/specs)
+  --out <dir>     Output directory (default: dflow-specs-html)
+  --title <text>  index.html page title (default: "dflow specs")
+
+The output directory is owned by dflow render: every rendered file embeds a
+generated-by marker, and a .dflow-render-manifest.json ledger tracks the
+mirror. Files whose sources were deleted or renamed are cleaned up on the
+next run — a file is deleted only when it is both ledger-listed and
+marker-verified, and an existing file at a path being rendered is
+overwritten only when it is marker-verified (that is how the partial
+outputs of an interrupted run converge on the next run). render refuses a
+non-empty directory without a ledger, anything it never creates (symlinks,
+junctions, hardlinked files), unrecognized files at paths it must write,
+and source trees whose outputs would collide. render only writes --out; it
+never modifies --src.
 `);
 }
 
@@ -50,7 +100,20 @@ function printDoctorHelp() {
 Read-only health check for the current project. Reports findings such as:
 
   - dflow/specs/shared/_conventions.md missing the Dflow Version
-    front-matter line
+    front-matter line, or recording an older last-reconciled version
+  - policy sections (Git Policy / AI Commit Policy / Prose Language)
+    missing or no longer machine-readable
+  - AI-AGENT-GUIDE.md frozen at an older Dflow version (missing or
+    malformed guide-canonical markers, stale canonical content) and
+    dangling "AI-AGENT-GUIDE.md § ..." references from the workflow bundle
+  - AI-AGENT-GUIDE.md "## Project Context" missing the machine-readable
+    Tech stack / Migration rows that context inference reads
+  - init-only starters drifted (missing or edited Git-principles file
+    for the selected policy)
+  - active feature _index.md files created from an older template shape
+  - root agent files (AGENTS.md / CLAUDE.md / copilot-instructions.md)
+    with malformed Dflow markers or unmanaged Dflow wording
+  - workflow bundle orphans and a bundle projected by an older Dflow
 
 Doctor never modifies files.
 `);
@@ -111,6 +174,20 @@ async function main() {
     });
   }
 
+  if (args[0] === 'render') {
+    if (args.length > 1 && (args[1] === '--help' || args[1] === '-h')) {
+      printRenderHelp();
+      return 0;
+    }
+
+    return await runRender({
+      cwd: process.cwd(),
+      args: args.slice(1),
+      stdout: process.stdout,
+      stderr: process.stderr
+    });
+  }
+
   if (args[0] === 'doctor') {
     if (args.length > 1 && (args[1] === '--help' || args[1] === '-h')) {
       printDoctorHelp();

package/docs/evaluating-dflow.en.md

@@ -46,6 +46,12 @@ in your project's `dflow/specs/` directory and AI instruction files.
   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.
+- The project-level skill for the selected tools (`.claude/skills/dflow/` /
+  `.agents/skills/dflow/` / `.github/skills/dflow/`), installed **by default**
+  — the source of natural-language auto-trigger. Interactive runs ask one
+  `(Y/n)` question (Enter = install); non-interactive runs never read an extra
+  answer and install by default. If you answer `n`, add it later with
+  `dflow configure-agents --skills`.
 
 `init` does **not**:
 
@@ -76,7 +82,8 @@ and router; executable workflow steps live in the vendored bundle at
 - Multiple tools can be active in the same project without diverging
   workflow rules.
 - Switching or adding tools later does not require re-running `init`; run
-  `dflow configure-agents` to add another shim, or
+  `dflow configure-agents` to add another shim (it asks the same default-yes
+  skill question for newly selected tools that have no skill yet), or
   `dflow configure-agents --command-adapters` to opt in to tool-native command
   entries.
 - The guide and workflow bundle together are the authoritative sources for
@@ -154,6 +161,13 @@ real codebase.
    `dflow/specs/shared/_conventions.md`, and
    `dflow/specs/shared/AI-AGENT-GUIDE.md` to see the shape.
 
+   You can also run `dflow render` to project the specs tree into
+   human-readable HTML (output in `dflow-specs-html/`; open `index.html` to
+   browse). A freshly initialized project is mostly starter templates; for a
+   closer-to-real rendering, clone this repo and render the tutorial's worked
+   specs: `dflow render --src tutorial/01-greenfield/outputs/dflow/specs
+   --out <any output dir>`.
+
 4. **Read one tutorial walk-through** to see what a real feature flow looks
    like end to end:
    - Greenfield: [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)
@@ -177,7 +191,12 @@ against.
 
 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`.
+- After `init`, the specs and workflow documents themselves do not depend on
+  the `dflow-sdd-ddd` CLI being installed — they are plain Markdown committed
+  into your repo, readable from any clone. The CLI is only needed for three
+  things: upgrade re-projection (`configure-agents`), health checks
+  (`doctor`), and rendering the specs as human-readable HTML (`dflow render`,
+  see playbook step 3 above).
 - 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.
 - If an existing project instruction file (e.g., a pre-existing `CLAUDE.md`)

package/docs/evaluating-dflow.md

@@ -33,6 +33,10 @@ Dflow 是 Markdown-based 的 workflow 材料加上一個 scaffolding CLI。它
   且可達的，任何 clone 都不需要 Dflow source 或 package 在本機安裝。
 - 你所選工具的 AI 指示檔或既有檔案中的 marked Dflow block（例如 `CLAUDE.md`、`AGENTS.md`、`.github/copilot-instructions.md`）。
   每個都把工具指向 canonical 指南與 workflow bundle。
+- 選定工具的 project-level skill（`.claude/skills/dflow/` / `.agents/skills/dflow/` /
+  `.github/skills/dflow/`），**預設安裝**——自然語言自動觸發的來源。互動模式會問
+  一題 `(Y/n)`（Enter = 裝）；非互動不多讀答案、直接預設裝。答 `n` 可之後用
+  `dflow configure-agents --skills` 補裝。
 
 `init` **不會**：
 
@@ -58,8 +62,9 @@ Dflow 支援多種 AI 程式設計助理。跑完 `init` 後，你選取一個
 與 `dflow/specs/shared/dflow-workflows/`（可執行步驟定義）。實際意義：
 
 - 同一個專案可以同時啟用多個工具，而不會有 workflow 規則分歧。
-- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim，
-  或用 `dflow configure-agents --command-adapters` opt in 工具原生命令入口。
+- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim
+  （對新選且尚無 skill 的工具會問同一題預設 Y 的 skill 安裝問句），或用
+  `dflow configure-agents --command-adapters` opt in 工具原生命令入口。
 - 指南與 workflow bundle 共同成為 Dflow workflow 行為的權威來源；兩者都是純 Markdown
   已 commit 進 repo，任何 clone 均可直接讀取。
 
@@ -123,6 +128,12 @@ repo 上下文的 AI 助理一起運作。
 
    開啟 `dflow/specs/shared/_overview.md`、`dflow/specs/shared/_conventions.md`、以及 `dflow/specs/shared/AI-AGENT-GUIDE.md` 看看整體架構。
 
+   也可以跑 `dflow render` 把 specs 樹轉成人類閱讀的 HTML（輸出
+   `dflow-specs-html/`，開 `index.html` 即可瀏覽）。剛 init 完的 specs 多是
+   起始模板；要看接近實戰的渲染效果，clone 本 repo 後對 tutorial 的規格範例
+   跑 `dflow render --src tutorial/01-greenfield/outputs/dflow/specs --out
+   <任意輸出目錄>`。
+
 4. **閱讀一份 tutorial walk-through** 以了解完整的 feature flow：
    - Greenfield：[`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md)
    - Brownfield：[`tutorial/02-brownfield/`](../tutorial/02-brownfield/walkthrough-00-setup.md)
@@ -137,7 +148,10 @@ repo 上下文的 AI 助理一起運作。
 
 Dflow 的設計讓試用成本低、退出成本也低：
 
-- `init` 完成後，你的專案不依賴已安裝的 `dflow-sdd-ddd` CLI。
+- `init` 完成後，specs 與 workflow 文件本身不依賴已安裝的 `dflow-sdd-ddd`
+  CLI——它們是已 commit 進 repo 的純 Markdown，任何 clone 都讀得到。CLI 只在
+  三種時機用到：升級重投影（`configure-agents`）、健康檢查（`doctor`）、以及
+  把 specs 轉成人類閱讀的 HTML（`dflow render`，見上方 playbook 第 3 步）。
 - 產生的檔案都是純 Markdown；用 `rm -rf dflow/` 加上刪除你不再需要的 AI 指示 shim 檔案，即可從專案中移除 Dflow。
 - 既有的專案指示檔（例如原本就存在的 `CLAUDE.md`）若被加入 marked Dflow
   block，刪除該 block 即可復原；但之後再跑 `init` / `configure-agents`

package/docs/npm-publish-checklist.md

@@ -12,7 +12,9 @@ Replace `<version>` with the version being published, for example `0.1.2`.
 - [ ] Update `CHANGELOG.md`.
 - [ ] Confirm `README.md` installation instructions match the release.
 - [ ] Confirm Greenfield and Brownfield common flow changes are synchronized.
-- [ ] Confirm generated templates match skill source where applicable.
+- [ ] Confirm workflow content changes are complete under `templates/` — the
+      single content source; there is no separate skill-source copy to
+      synchronize.
 - [ ] Run the lifecycle check in the development repo and confirm it is green,
       so every proposal this release covers is terminal (`implemented` /
       `rejected` / `superseded`) and already archived:

package/docs/release-versioning-policy.md

@@ -95,8 +95,9 @@ the only place where release history is recorded.
 
 ## Greenfield and Brownfield Changes
 
-If a change touches a common SDD flow, update both Greenfield and Brownfield
-skill sources unless the release intentionally changes only one track.
+If a change touches a common SDD flow, update the flow under both
+`templates/greenfield/references/` and `templates/brownfield/references/`
+unless the release intentionally changes only one track.
 
 Common synchronized flow files include:
 

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

@@ -82,8 +82,11 @@ without Claude-Code-specific edits.
 
 If a `CLAUDE.md` already existed in the project, `init` does not overwrite
 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
+that already points to `dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped with
+a warning, without adding a second pointer — a later interactive
+`dflow configure-agents` run offers to append the marked managed block
+(default No), while non-interactive runs keep skipping with the warning.
+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
@@ -208,23 +211,31 @@ git rm --cached -r .claude/commands/dflow/
 files.)
 
 After upgrading Dflow, re-running `dflow configure-agents --command-adapters`
-re-projects adapters from the **new registry**, but an existing
-`dflow/specs/shared/AI-AGENT-GUIDE.md` is **not** overwritten — "re-projecting
-adapters" is not the same as "migrating the canonical guide." Re-project with
-the **same dflow CLI version** to avoid a registry / guide version mismatch.
+re-projects adapters from the **new registry** and also refreshes the
+**marker-guarded canonical region** of `dflow/specs/shared/AI-AGENT-GUIDE.md`
+in place (everything outside the markers — including `## Project Context` — is
+kept). If an older project's guide has no markers yet, an interactive run asks
+before adopting them (default No); a non-interactive run skips with a warning.
+Re-project with the **same dflow CLI version**, and run `dflow doctor`
+afterwards to review any remaining drift (read-only).
 
-### Optional Skill Adapter (Restore Natural-Language Auto-Trigger)
+### Skill Adapter (Natural-Language Auto-Trigger, Installed by Default)
 
 Command adapters give you a `/` menu entry, but they **do not auto-trigger** —
-you have to invoke the command yourself. If you want to restore the "say 'I want
-to add a feature' and it shows up automatically" experience, run this in an
-initialized project:
+you have to invoke the command yourself. Auto-trigger comes from the
+project-level skill, and it now installs **by default**: `dflow init` installs
+it when AI tools were selected (interactive runs ask one question — press Enter
+to install; non-interactive runs never read an extra answer and install by
+default), and `dflow configure-agents` asks the same question for newly
+selected tools that have no skill yet. If you answered `n` back then, or want
+to force-regenerate (for example to refresh after upgrading Dflow), run:
 
 ```bash
 dflow configure-agents --skills
 ```
 
-After you select Claude Code, Dflow generates a thin skill:
+After you select Claude Code (in init or configure-agents), Dflow generates a
+thin skill:
 
 - `.claude/skills/dflow/SKILL.md`
 
@@ -233,8 +244,8 @@ This skill does not copy workflow steps; its body points to the canonical
 `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
+The same edition-neutral skill source is also projected 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.
 
@@ -249,14 +260,14 @@ Its behavior:
   judges the intent, **suggests the matching `/dflow:` command, and waits for
   your confirmation** before proceeding.
 
-**The four combinations** (command adapters and the skill are each independently
-opt-in):
+**The four combinations** (command adapters stay opt-in; the skill installs by
+default — answer `n` at init to skip it, or delete it later):
 
 | Installed | Entry behavior |
 |---|---|
-| Neither | Root shim only (CLAUDE.md points to the guide); no `/` menu, no auto-trigger |
+| Neither (skill skipped with `n`, no adapters) | Root shim only (CLAUDE.md points to the guide); no `/` menu, no auto-trigger |
 | Command adapters only | `/dflow:*` appears in the `/` menu; no natural-language auto-trigger |
-| Skill only | Natural-language auto-trigger (suggest-and-wait); no `/` menu |
+| Skill only (init's default outcome) | Natural-language auto-trigger (suggest-and-wait); no `/` menu |
 | Both | `/` menu + natural-language safety net **may coexist** |
 
 **Both may coexist with no mutex needed** (validated in a real Claude Code
@@ -307,11 +318,13 @@ spec locations, or SDD constraints to `CLAUDE.md`, those belong in
 `dflow/specs/shared/AI-AGENT-GUIDE.md` instead. The shim stays small so
 that other tools' shims don't drift away from it.
 
-**`/dflow:*` is not a Claude Code Skill installation.** `init` does not
-install anything into Claude Code's skill system. Without command adapters,
-Dflow names are text triggers the AI recognizes from the workflow table. After
-you run `dflow configure-agents --command-adapters`, the added files are thin
-command wrappers, not a second workflow definition.
+**The `/dflow:*` command names are not the skill.** `init` does install the
+auto-trigger skill into Claude Code's skill system by default
+(`.claude/skills/dflow/SKILL.md`; answer `n` at the skill question to skip),
+but the `/dflow:*` **command names** themselves are not a skill. Without
+command adapters, those names are text triggers the AI recognizes from the
+workflow table. After you run `dflow configure-agents --command-adapters`, the
+added files are thin command wrappers, not a second workflow definition.
 
 **Choose either legacy Claude skills or the installed adapter.** If the
 project still has legacy `.claude/skills/sdd-ddd-*` skills, choose either

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

@@ -184,19 +184,24 @@ git rm --cached -r .claude/commands/dflow/
 （`--cached` 只移出版控、保留工作目錄檔案。）
 
 升級 dflow 後重跑 `dflow configure-agents --command-adapters`，adapter 會用**新版 registry**
-重投影；但既有 `dflow/specs/shared/AI-AGENT-GUIDE.md` **不會**被覆寫——「重投影 adapter」不等於
-「升級 canonical guide」。請以**相同的 dflow CLI 版本**重投影，避免 registry 與 guide 版本錯位。
+重投影；`dflow/specs/shared/AI-AGENT-GUIDE.md` 內**帶 marker 的 canonical 區**也會原地刷新
+（marker 以外——含 `## Project Context`——保留不動）。較舊專案的 guide 還沒有 marker 時，
+互動執行會詢問是否採用（預設 N）、非互動則跳過並警告。請以**相同的 dflow CLI 版本**重投影，
+升級後先跑 `dflow doctor` 檢視殘餘漂移（read-only）。
 
-### 選配 Skill Adapter（找回自然語言自動觸發）
+### Skill Adapter（自然語言自動觸發，init 預設安裝）
 
-Command adapter 提供 `/` 選單入口，但**不會自動觸發**——你得主動打命令。若想找回
-「講『我要加一個功能』就自動現身」的體驗，可在已初始化的專案中執行：
+Command adapter 提供 `/` 選單入口，但**不會自動觸發**——你得主動打命令。自動觸發
+來自 project-level skill，而它現在是**預設安裝**：`dflow init` 有選 AI 工具時就會裝
+（互動模式問一題、直接按 Enter = 裝；非互動不多讀答案、直接預設裝），
+`dflow configure-agents` 對「新選且尚無 skill」的工具也補問同一題。若當時答 `n`
+略過、或想強制重生成（例如升級 Dflow 後刷新），執行：
 
 ```bash
 dflow configure-agents --skills
 ```
 
-選擇 Claude Code 後，Dflow 會產生一份薄 skill：
+選擇 Claude Code 後（init 或 configure-agents 皆同），Dflow 會產生一份薄 skill：
 
 - `.claude/skills/dflow/SKILL.md`
 
@@ -204,7 +209,7 @@ dflow configure-agents --skills
 `dflow/specs/shared/AI-AGENT-GUIDE.md`（命令登錄表與路由規則）以及
 `dflow/specs/shared/dflow-workflows/`（含可執行步驟定義的 vendored bundle）。
 
-同一份 edition-neutral skill source，現在也會由 `--skills` 為 Codex
+同一份 edition-neutral skill source，也會為 Codex
 （`.agents/skills/dflow/SKILL.md`）與 GitHub Copilot（`.github/skills/dflow/SKILL.md`）
 投影 project-level skill，三家沿用相同的跨工具 agentskills.io 標準。
 
@@ -216,14 +221,15 @@ dflow configure-agents --skills
 - 由自然語言觸發時，**不會直接進 workflow**：它會判斷意圖、**建議對應的 `/dflow:`
   命令並等待你確認**，再進入流程。
 
-**四種組合**（command adapter 與 skill 各自獨立 opt-in）：
+**四種組合**（command adapter 維持 opt-in；skill 預設安裝，可在 init 答 `n`
+略過或事後刪除）：
 
 | 安裝組合 | 入口行為 |
 |---|---|
-| 都不裝 | 只有根目錄 shim（CLAUDE.md 指向 guide）；無 `/` 選單、無自動觸發 |
-| 只裝 command adapters | `/dflow:*` 出現在 `/` 選單；無自然語言自動觸發 |
-| 只裝 skill | 自然語言自動觸發（suggest-and-wait）；無 `/` 選單 |
-| 兩者都裝 | `/` 選單 + 自然語言 safety net **可共存** |
+| 都沒有（skill 題答 `n`、未裝 adapters） | 只有根目錄 shim（CLAUDE.md 指向 guide）；無 `/` 選單、無自動觸發 |
+| 只有 command adapters | `/dflow:*` 出現在 `/` 選單；無自然語言自動觸發 |
+| 只有 skill（init 預設結果） | 自然語言自動觸發（suggest-and-wait）；無 `/` 選單 |
+| 兩者都有 | `/` 選單 + 自然語言 safety net **可共存** |
 
 **兩者可共存、無需互斥**（已在真實 Claude Code 環境驗證）：skill 名稱 `dflow` 與
 command adapter 的 `dflow:<id>` 不撞名，明確命令各自精準載入、不會雙觸發；skill 當
@@ -266,10 +272,12 @@ SDD 約束加入 `CLAUDE.md`，這些內容應該放到
 `dflow/specs/shared/AI-AGENT-GUIDE.md`。shim 保持精簡，其他工具的 shim 才不會
 與它產生漂移（drift）。
 
-**`/dflow:*` 不是安裝 Claude Code Skill。** `init` 不會在 Claude Code 的
-skill 系統中安裝任何東西。未安裝 command adapters 時，Dflow 名稱只是 AI 從
-workflow 表識別的文字 trigger；安裝 `dflow configure-agents --command-adapters`
-後，新增的是薄 command wrapper，不是 workflow 的第二份定義。
+**`/dflow:*` 命令名不等於 skill。** init 預設會在 Claude Code 的 skill 系統
+裝一份自動觸發 skill（`.claude/skills/dflow/SKILL.md`，skill 題答 `n` 可略過），
+但 `/dflow:*` 這組**命令名**本身不是 skill——未安裝 command adapters 時，它們
+只是 AI 從 workflow 表識別的文字 trigger；安裝
+`dflow configure-agents --command-adapters` 後，新增的是薄 command wrapper，
+不是 workflow 的第二份定義。
 
 **legacy Claude skill 與 installed adapter 擇一。** 如果專案仍保留舊的
 `.claude/skills/sdd-ddd-*` skill，請在 legacy skill 與 `--command-adapters`
@@ -289,7 +297,9 @@ Code 會在進入對應 workflow 時才讀取它們。這樣可以讓 context
 工作保持比例。
 
 **既有的 `CLAUDE.md` 會被保留。** `init` 不會覆蓋你現有的自訂專案指示；已是
-Dflow-generated shim 會原地刷新，其他已指向 `AI-AGENT-GUIDE.md` 的檔案會略過，
+Dflow-generated shim 會原地刷新，其他已指向 `AI-AGENT-GUIDE.md` 的檔案會略過
+並警告、不新增第二個指標（之後在互動終端跑 `dflow configure-agents` 會詢問
+是否附加帶 marker 的管理區塊，預設 N；非互動執行維持略過並警告），
 否則會在確認 preview 顯示要附加的 marked Dflow block，寫入後重跑會原地更新同一段。
 若你刪除該 block，下一次 `init` / `configure-agents` 會再附加它；只有 marker
 conflict 時才需要到 `dflow/specs/shared/` 找 fallback merge snippet 手動處理。

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

@@ -86,8 +86,11 @@ GitHub Copilot, and other tools.
 
 If an `AGENTS.md` already existed in the project, `init` does not overwrite
 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
+that already points to `dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped with
+a warning, without adding a second pointer — a later interactive
+`dflow configure-agents` run offers to append the marked managed block
+(default No), while non-interactive runs keep skipping with the warning.
+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
@@ -179,8 +182,9 @@ 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.
+**Auto-trigger skills come from the skill install (init's default, or
+`--skills`), not `--command-adapters`.** See "Codex Behavior With Skills"
+below.
 
 When you select `AGENTS.md - Codex / Copilot coding agent` in
 `--command-adapters` mode, Dflow writes a trigger list generated from the
@@ -219,10 +223,16 @@ 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)
+### Codex Behavior With Skills (Auto-Trigger, Installed by Default)
 
-`dflow configure-agents --skills` projects a thin, tool-neutral skill to
-`.agents/skills/dflow/SKILL.md` — Codex's project-level skill path. This gives
+Dflow projects a thin, tool-neutral skill to
+`.agents/skills/dflow/SKILL.md` — Codex's project-level skill path. The skill
+now installs **by default**: `dflow init` installs it when Codex was selected
+(interactive runs ask one default-yes question; non-interactive runs install
+without reading extra stdin), and `dflow configure-agents` asks the same
+question when Codex is newly selected without a skill;
+`dflow configure-agents --skills` backfills a previously skipped skill or
+force-regenerates it. 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
@@ -320,9 +330,9 @@ workflow by reading `AI-AGENT-GUIDE.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.)
+`.github/prompts`. (Auto-trigger **skills** are separate: init installs one to
+`.agents/skills/dflow/SKILL.md` by default and `--skills` regenerates it, see
+"Codex Behavior With 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

package/docs/using-with-codex.md

@@ -76,7 +76,9 @@ Claude Code、GitHub Copilot 與其他工具。
 
 如果專案中已有 `AGENTS.md`，`init` 不會覆蓋自訂內容。已是 Dflow-generated shim
 的檔案會原地刷新；其他已指向 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的檔案會
-略過，不會新增第二個指標。否則 Dflow 會在確認 preview 顯示並於檔案末尾附加帶有
+略過並警告，不會新增第二個指標——之後在互動終端跑 `dflow configure-agents`
+會詢問是否附加帶 marker 的管理區塊（預設 N），非互動執行維持略過並警告。
+否則 Dflow 會在確認 preview 顯示並於檔案末尾附加帶有
 `<!-- dflow-generated: agent-shim START/END -->` markers 的 Dflow block，重跑會
 原地更新同一段。只有遇到衝突或 malformed Dflow markers 時，才會改寫
 `dflow/specs/shared/AGENTS-md-snippet.md` fallback merge snippet 讓你手動合併。
@@ -158,8 +160,8 @@ guide 中記為 `/dflow:*`）。
 Codex 命令檔。Codex v1 沒有與 Claude `.claude/commands` 或 Copilot `.github/prompts`
 對等的 Dflow command-file adapter。
 
-**自動觸發 skill 走的是 `--skills`（非 `--command-adapters`）。** 見下方
-〈選配 Skill 的 Codex 行為〉。
+**自動觸發 skill 走的是 skill 安裝（init 預設、或 `--skills`），非
+`--command-adapters`。** 見下方〈Skill 的 Codex 行為〉。
 
 當你在 `--command-adapters` 模式下選擇 `AGENTS.md - Codex / Copilot coding agent`
 時，Dflow 會把從 canonical command registry 產生的 trigger 清單寫進 `AGENTS.md`。
@@ -189,10 +191,13 @@ marker」分成兩種小抄：
 兩種小抄都只在 marker conflict 時出現。乾淨、沒有 marker 衝突的自訂 `AGENTS.md` 不會
 產生任何小抄——Dflow 會直接把相鄰 marked block append 進去。
 
-### 選配 Skill 的 Codex 行為（自動觸發）
+### Skill 的 Codex 行為（自動觸發，init 預設安裝）
 
-`dflow configure-agents --skills` 會把一份精簡、工具中立的 skill 投影到
-`.agents/skills/dflow/SKILL.md`——Codex 的專案層 skill 路徑。這讓 Codex 取得與
+Dflow 會把一份精簡、工具中立的 skill 投影到
+`.agents/skills/dflow/SKILL.md`——Codex 的專案層 skill 路徑。這份 skill 現在
+**預設安裝**：`dflow init` 有選 Codex 就裝（互動問一題預設 Y、非互動直接裝）、
+`dflow configure-agents` 對新選且尚無 skill 的 Codex 也補問；
+`dflow configure-agents --skills` 用於補裝先前略過的、或強制重生成。這讓 Codex 取得與
 Claude Code **對等的自然語言自動觸發**：你用「help me start a new feature」這類描述
 時，Codex 可依該 skill 的 `description` 自動判斷是否相關，建議對應的 `dflow:<id>`
 workflow，而不必每次都記得手打命令。
@@ -272,8 +277,8 @@ canonical `/dflow:<id>` workflow。
 **Codex 不產生命令檔。** 即使使用 `--command-adapters`，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 專屬**命令**檔。（自動觸發 **skill** 是另一回事，init 預設安裝、`--skills`
+可重生成，路徑 `.agents/skills/dflow/SKILL.md`，見上方〈Skill 的 Codex 行為〉。）
 
 **不要混淆 Codex `/init` 與 Dflow `init`。** Codex `/init` 為 Codex 建立
 通用的 `AGENTS.md` scaffold。Dflow 的設定是 `dflow init`（或免安裝路徑的

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

@@ -142,11 +142,16 @@ steps. Note the command syntax uses the **hyphen** `/dflow-<id>`, not the
 canonical **colon** `/dflow:<id>` — the colon form is Claude / Codex's command
 syntax and in Copilot can only be a text reference, never typed as a command.
 
-### The `--skills` Flag and Skill Triggering on Copilot
+### Skill Triggering on Copilot (Installed by Default)
 
-`dflow configure-agents --skills` projects the same tool-neutral thin skill for
+Dflow projects the same tool-neutral thin skill for
 **Claude Code, Codex, and GitHub Copilot**, each at its own project-level skill
-path; Copilot's is `.github/skills/dflow/SKILL.md`. Testing (2026-06-05) confirmed
+path; Copilot's is `.github/skills/dflow/SKILL.md`. The skill now installs **by
+default**: `dflow init` installs it when Copilot was selected (interactive runs
+ask one default-yes question; non-interactive runs install without reading
+extra stdin), `dflow configure-agents` asks the same question when Copilot is
+newly selected without a skill, and `dflow configure-agents --skills` backfills
+or force-regenerates it. Testing (2026-06-05) confirmed
 Copilot discovers and runs the skill from its own native `.github/skills/` path
 (it still works with the cross-read `.claude`/`.agents` paths removed); the
 trigger differs by surface — **VS Code Chat auto-triggers on natural language**,
@@ -191,10 +196,13 @@ git rm --cached .github/prompts/dflow-*.prompt.md
 files.)
 
 After upgrading Dflow, re-running `dflow configure-agents --command-adapters`
-re-projects prompt adapters from the **new registry**, but an existing
-`dflow/specs/shared/AI-AGENT-GUIDE.md` is **not** overwritten — "re-projecting
-adapters" is not the same as "migrating the canonical guide." Re-project with
-the **same dflow CLI version**.
+re-projects prompt adapters from the **new registry** and also refreshes the
+**marker-guarded canonical region** of `dflow/specs/shared/AI-AGENT-GUIDE.md`
+in place (everything outside the markers — including `## Project Context` — is
+kept). If an older project's guide has no markers yet, an interactive run asks
+before adopting them (default No); a non-interactive run skips with a warning.
+Re-project with the **same dflow CLI version**, and run `dflow doctor`
+afterwards to review any remaining drift (read-only).
 
 ### Sample Conversation Flow
 
@@ -225,7 +233,10 @@ Copilot: Got it. I'll create the feature spec at dflow/specs/features/active/
 If a `.github/copilot-instructions.md` file already exists in your project,
 `init` does not overwrite 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
+`dflow/specs/shared/AI-AGENT-GUIDE.md` is skipped with a warning — a later
+interactive `dflow configure-agents` run offers to append the marked managed
+block (default No), while non-interactive runs keep skipping with the warning.
+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
@@ -287,7 +298,7 @@ The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the same across
 ## Where to Go Next
 
 - If you have not run `init`: run `dflow init` (after `npm install -g dflow-sdd-ddd`) or `npx dflow-sdd-ddd init` and choose the Copilot target to create `.github/copilot-instructions.md`.
-- Read [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../sdd-ddd-greenfield-skill/scaffolding/AI-AGENT-GUIDE.md) (or the brownfield equivalent) before starting a workflow.
+- Read [`dflow/specs/shared/AI-AGENT-GUIDE.md`](../templates/greenfield/scaffolding/AI-AGENT-GUIDE.md) (or the brownfield equivalent) before starting a workflow.
 - See [`tutorial/01-greenfield/`](../tutorial/01-greenfield/walkthrough-00-setup.md) for conversation examples that demonstrate Copilot chat flows.
 - Read [`docs/why-ddd-for-ai.en.md`](why-ddd-for-ai.en.md) for the design rationale behind spec-first plus DDD.