dflow-sdd-ddd 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -6,6 +6,32 @@
 
 ---
 
+## 0.8.0 — 2026-05-24 — DDD set-based invariant 引導擴充、雙軌 skill 殼合一、user-projected bundle 內容 polish
+
+**Proposals**：PROPOSAL-040（CLI papercuts + 文件補洞）、PROPOSAL-041（C0+C1：configure-agents idempotent bundle re-projection + 雙軌 skill 殼合一）、PROPOSAL-042（ddd-modeling-guide 補 set-based invariants 與 Phase-1 event dispatch 段）、PROPOSAL-044（user-projected bundle 內 maintainer-source path 清除）、PROPOSAL-045（user-projected bundle 內 maintainer-only provenance refs 清除）
+
+**新功能 / 新引導內容**：
+
+- **ddd-modeling-guide 補「Set-Based / Uniqueness Invariants」段**（PROPOSAL-042）：明確說明 set-based invariants（「同 X 只能一筆 active」「email 跨 User 唯一」這類）**無論選哪種 aggregate 邊界**，in-memory check 在並發下都不夠保護，需 DB unique / partial index 或 optimistic concurrency token 配合。涵蓋兩種常見 aggregate 切法（拆獨立 + folded 為 child entity）的對策；指出 child entity 寫入需 bump root version；建議將並發衝突 translate 為業務語意 conflict（HTTP 409）。同 update 補 Common Mistakes #6 與 Phase-1 event dispatch lifecycle 段落。
+
+**行為改善**：
+
+- **`configure-agents` 自動補回 bundle**（PROPOSAL-041 C0）：對 pre-039 既有專案再次跑 `configure-agents` 時，自動 re-project 缺失的 `dflow/specs/shared/dflow-workflows/` bundle（idempotent；第二次跑為 no-op）。順手關閉 PROPOSAL-039 follow-up (i)。
+- **雙軌 skill 殼合一**（PROPOSAL-041 C1）：兩份 `sdd-ddd-{green,brown}field-skill/SKILL.md` 統一為 `templates/common/skill/SKILL.md` thin shell；`lib/init.js` 從該檔讀。對 npm 使用者只是裝起來行為一致，無破壞性變更；對 maintainer 是 source-of-truth 收斂。
+- **CLI papercuts 批次修**（PROPOSAL-040 group A）：`init` / `configure-agents` 數個 CLI 摩擦點修補（issues #2/#11/#12）。
+- **`init` 後續 step 文件補洞**（PROPOSAL-040 group B）：slug 命名加 CI 相容性 caveat、`behavior.md` skeleton 註解明確（避免 user 以為 finish-feature 前就該填）、`configure-agents` 自動偵測既有 agent 配置（#13/#7）、`aggregate-design.md` 在 feature 目錄內的存放位置明文釘住。
+
+**文件 / user-facing 內容 polish**：
+
+- **user-projected bundle 內 `sdd-ddd-*-skill/` maintainer-source path 清除**（PROPOSAL-044）：原本 `npm install` 後 user project 內的 flow / template 文件含 `sdd-ddd-greenfield-skill/scaffolding/...` 這類在 user 端不存在的路徑引用——user 讀到會誤判「我裝錯了？」。本 release 把該類引用全部清為 user 端可解析路徑或自足語句。涵蓋 12 個 source + 12 個 mirror。
+- **user-projected bundle 內 maintainer-only provenance refs 清除**（PROPOSAL-045）：原本 user 端會看到的 `<!-- ... PROPOSAL-013 ... -->` HTML 註解、`init-project-flow.md` 末段 `archive/reviews/...` 引用、references body 內 bare `PROPOSAL-NNN` 引用、brownfield `CLAUDE-md-snippet.md` 內 `(established in PROPOSAL-007c)` 標註等——這些是 maintainer-only 歷史佔位、user 看到只會困惑。本 release 全部清除或改寫為自足語句；HTML 註解保留為 `<!-- Seeded by Dflow. -->`（語意精準：user 取到檔後可自行客製化、dflow 並不持續維護該副本）。涵蓋 66 個 unique files。
+
+**維護者工具**（不影響套件使用者）：
+
+- **`scripts/check-repo-consistency.sh` 新增 045 guard**：scoped git grep 對 `sdd-ddd-*-skill/{templates,scaffolding,references}/*.md` + `templates/{green,brown}field/**/*.md` 偵測 `(archive/|planning/|reviews/|proposals/|PROPOSAL-[0-9]{3})` 任一命中即 fail——防未來再引入 maintainer-only provenance refs。Pre-commit hook 不加。
+
+---
+
 ## 0.7.0 — 2026-05-22 — Opt-in Claude skill adapter、自動清理舊 command adapter、發布前 lifecycle 機檢
 
 **Proposals**：PROPOSAL-037（generated adapter commit 政策與升級流程）、PROPOSAL-038（選配 skill adapter）、PROPOSAL-035（lifecycle drift forcing-functions）

package/docs/evaluating-dflow.en.md

@@ -35,10 +35,16 @@ in your project's `dflow/specs/` directory and AI instruction files.
   map, architecture/tech-debt, features active/completed). See
   [`README.md` "Files Created by Init"](../README.en.md#files-created-by-init)
   for the full tree.
-- A canonical project guide at `dflow/specs/shared/AI-AGENT-GUIDE.md`.
+- A canonical project guide at `dflow/specs/shared/AI-AGENT-GUIDE.md` —
+  the command registry, routing rules, and project context.
+- A vendored workflow bundle at `dflow/specs/shared/dflow-workflows/` —
+  the executable step definitions for each `/dflow:*` workflow (step gates,
+  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.
+  thin pointer to the canonical guide and workflow bundle.
 
 `init` does **not**:
 
@@ -60,7 +66,9 @@ or more tools and Dflow writes the corresponding shim:
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
 Each shim points back to the canonical
-`dflow/specs/shared/AI-AGENT-GUIDE.md`. Practical implications:
+`dflow/specs/shared/AI-AGENT-GUIDE.md`. The guide acts as the command registry
+and router; executable workflow steps live in the vendored bundle at
+`dflow/specs/shared/dflow-workflows/`. Practical implications:
 
 - Multiple tools can be active in the same project without diverging
   workflow rules.
@@ -68,8 +76,9 @@ Each shim points back to the canonical
   `dflow configure-agents` to add another shim, or
   `dflow configure-agents --command-adapters` to opt in to tool-native command
   entries.
-- The project guide stays the single source of truth for Dflow workflow
-  behavior.
+- The guide and workflow bundle together are the authoritative sources for
+  Dflow workflow behavior; both are plain Markdown committed in your repo and
+  accessible to any clone.
 
 `/dflow:*` is the canonical shared vocabulary, but each tool's `/` parser
 behaves differently: Claude Code command adapters use `/dflow:<id>`, the

package/docs/evaluating-dflow.md

@@ -25,8 +25,14 @@ Dflow 是 Markdown-based 的 workflow 材料加上一個 scaffolding CLI。它
 
 - `dflow/specs/` workspace（概覽、慣例、領域詞彙表、context map、架構 / 技術債、功能 active/completed）。完整目錄樹見
   [`README.md` "Init 產生的檔案"](../README.md#init-產生的檔案)。
-- 位於 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的 canonical 專案指南。
-- 你所選工具的可合併 AI 指示檔（例如 `CLAUDE.md`、`AGENTS.md`、`.github/copilot-instructions.md`）。每個都是指向 canonical 指南的薄 shim。
+- 位於 `dflow/specs/shared/AI-AGENT-GUIDE.md` 的 canonical 專案指南 ——
+  命令登錄表、路由規則與專案上下文。
+- 位於 `dflow/specs/shared/dflow-workflows/` 的 vendored workflow bundle ——
+  各 `/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。
 
 `init` **不會**：
 
@@ -45,11 +51,14 @@ Dflow 支援多種 AI 程式設計助理。跑完 `init` 後，你選取一個
 | Claude Code | `CLAUDE.md` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 
-每個 shim 都指向 canonical 的 `dflow/specs/shared/AI-AGENT-GUIDE.md`。實際意義：
+每個 shim 都指向 canonical 的 `dflow/specs/shared/AI-AGENT-GUIDE.md`（命令登錄表）
+與 `dflow/specs/shared/dflow-workflows/`（可執行步驟定義）。實際意義：
 
 - 同一個專案可以同時啟用多個工具，而不會有 workflow 規則分歧。
-- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim，或用 `dflow configure-agents --command-adapters` opt in 工具原生命令入口。
-- 專案指南始終保持為 Dflow workflow 行為的單一 source of truth。
+- 之後切換或新增工具不需要重跑 `init`；執行 `dflow configure-agents` 即可新增 shim，
+  或用 `dflow configure-agents --command-adapters` opt in 工具原生命令入口。
+- 指南與 workflow bundle 共同成為 Dflow workflow 行為的權威來源；兩者都是純 Markdown
+  已 commit 進 repo，任何 clone 均可直接讀取。
 
 `/dflow:*` 是 canonical 共同詞彙，但各工具的 `/` parser 行為不同：Claude Code
 command adapters 使用 `/dflow:<id>`，GitHub Copilot prompt 選單使用

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

@@ -68,11 +68,15 @@ Two things happen when Claude Code starts in this project:
    Code's Markdown import syntax to inline the canonical Dflow guide. So
    Claude Code effectively reads both files as one set of instructions.
 
-The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is where the
-real workflow rules live: project context (track, tech stack, prose
+The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is the
+**command registry and router**: project context (track, tech stack, prose
 language), the `/dflow:*` workflow table, source-of-truth file paths, and
-core SDD/DDD rules. The `CLAUDE.md` shim stays small precisely so the
-canonical guide can evolve without Claude-Code-specific edits.
+core SDD/DDD rules. The executable workflow steps (Step 1→N, step gates,
+completion checklists) live in the **vendored workflow bundle** that `init`
+projects into `dflow/specs/shared/dflow-workflows/`. Both are plain Markdown
+checked into your repo, so they travel with the project when cloned. The
+`CLAUDE.md` shim stays small precisely so the canonical guide can evolve
+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
@@ -112,9 +116,11 @@ dflow/specs/features/active/. Before I do, I need a short answer on:
 The workflow then walks you through spec drafting, behavior examples,
 implementation planning, and finish-feature drift checks. The exact
 sequence depends on which workflow you entered (`/dflow:new-feature`,
-`/dflow:modify-existing`, `/dflow:bug-fix`, etc.). All workflow definitions
-live under the Dflow skill source; Claude Code follows them by reading the
-skill files when needed.
+`/dflow:modify-existing`, `/dflow:bug-fix`, etc.). The executable step
+definitions (Step 1→N, step gates, completion checklists) are in the
+vendored workflow bundle at `dflow/specs/shared/dflow-workflows/`; `init`
+projects this bundle into every initialized project so the workflow steps
+are self-contained and reachable without any external source dependency.
 
 Available workflow entry points:
 
@@ -215,8 +221,10 @@ After you select Claude Code, Dflow generates a thin skill:
 
 - `.claude/skills/dflow/SKILL.md`
 
-This skill does not copy workflow steps; its body only points to the canonical
-`dflow/specs/shared/AI-AGENT-GUIDE.md`, which carries the real workflow content.
+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).
 Its behavior:
 
 - **Auto-triggers on** feature / bug-fix workflows, product/domain behavior

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

@@ -62,10 +62,14 @@ Claude Code 在這個專案中啟動時，會發生兩件事：
    Markdown import 語法，將 canonical Dflow 指南 inline 嵌入。因此 Claude Code
    等效於把兩個檔案當成一組指示來讀取。
 
-canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）是實際 workflow
-規則的所在：專案上下文（track、技術棧、文章語言）、`/dflow:*` workflow 表、
-source-of-truth 檔案路徑，以及核心 SDD/DDD 規則。`CLAUDE.md` shim 刻意保持精簡，
-這樣 canonical 指南就能在不需要 Claude Code 專屬修改的情況下持續演進。
+canonical 指南（`dflow/specs/shared/AI-AGENT-GUIDE.md`）是**命令登錄表與路由器**：
+專案上下文（track、技術棧、文章語言）、`/dflow:*` workflow 表、source-of-truth
+檔案路徑，以及核心 SDD/DDD 規則。可執行的 workflow 步驟（Step 1→N、step gates、
+completion checklists）則放在 `init` 投影進專案的 **vendored workflow bundle**
+（`dflow/specs/shared/dflow-workflows/`）。兩者都是純 Markdown，隨 repo
+一起 commit，任何 clone 都能直接讀取，不需要 Dflow source 或 package 在本機安裝。
+`CLAUDE.md` shim 刻意保持精簡，這樣 canonical 指南就能在不需要 Claude Code
+專屬修改的情況下持續演進。
 
 如果專案中已有 `CLAUDE.md`，`init` 不會覆蓋它。它改為在
 `dflow/specs/shared/` 下寫入 merge snippet，讓你手動貼入現有的 `CLAUDE.md`。
@@ -103,8 +107,10 @@ dflow/specs/features/active/. Before I do, I need a short answer on:
 接著這個 workflow 會引導你完成 spec 起草、行為範例、實作計畫，以及
 finish-feature 漂移（drift）檢查。確切的流程取決於你進入的是哪個 workflow
 （`/dflow:new-feature`、`/dflow:modify-existing`、`/dflow:bug-fix` 等）。
-所有 workflow 定義都存放在 Dflow skill source 中；Claude Code 在需要時讀取
-skill 檔案來執行它們。
+可執行的步驟定義（Step 1→N、step gates、completion checklists）存放在
+`dflow/specs/shared/dflow-workflows/` 的 vendored bundle 中；`init` 會把這個
+bundle 投影進每個初始化的專案，因此 workflow 步驟是 self-contained 且可達的，
+不需要任何外部 source dependency。
 
 可用的 workflow 入口：
 
@@ -190,8 +196,9 @@ dflow configure-agents --skills
 
 - `.claude/skills/dflow/SKILL.md`
 
-這份 skill 不複製 workflow 步驟，body 只指向 canonical
-`dflow/specs/shared/AI-AGENT-GUIDE.md`，由 guide 承載真正的 workflow 內容。
+這份 skill 不複製 workflow 步驟，body 指向 canonical
+`dflow/specs/shared/AI-AGENT-GUIDE.md`（命令登錄表與路由規則）以及
+`dflow/specs/shared/dflow-workflows/`（含可執行步驟定義的 vendored bundle）。
 它的行為：
 
 - **自動觸發於** feature / bug-fix workflow、product/domain behavior 變更、新需求、

package/lib/init.js

@@ -12,6 +12,10 @@ const COMMAND_REGISTRY_START = '<!-- dflow-command-registry:start -->';
 const COMMAND_REGISTRY_END = '<!-- dflow-command-registry:end -->';
 const COMMAND_ADAPTER_GENERATED_MARKER = '<!-- dflow-generated: command-adapter -->';
 const SKILL_ADAPTER_GENERATED_MARKER = '<!-- dflow-generated: skill-adapter -->';
+const WORKFLOW_BUNDLE_GENERATED_MARKER = '<!-- dflow-generated: workflow-bundle -->';
+const WORKFLOW_BUNDLE_DEST = 'dflow/specs/shared/dflow-workflows';
+const WORKFLOW_BUNDLE_MANIFEST_PATH = `${WORKFLOW_BUNDLE_DEST}/.dflow-bundle-manifest.json`;
+const COMMON_SKILL_SOURCE_REL = 'common/skill/SKILL.md';
 const EXPECTED_COMMAND_IDS = [
   'new-feature',
   'modify-existing',
@@ -203,8 +207,8 @@ async function runInit(options = {}) {
 
     const detection = await detectProjectSignals(cwd);
     const answers = await promptForAnswers(rl, stdout, stderr, detection);
-    const warnings = [...preflight.warnings, ...buildDetectionWarnings(answers, detection)];
     const plan = await buildFilePlan(cwd, answers);
+    const warnings = [...preflight.warnings, ...buildDetectionWarnings(answers, detection), ...(plan.bundleWarnings || [])];
 
     renderPreview(stdout, plan, warnings);
     const confirmed = await askConfirmation(rl, 'Create these files? (y/N) ');
@@ -277,7 +281,8 @@ async function runConfigureAgents(options = {}) {
     await assertDflowInitialized(cwd);
 
     const projectContext = await inferProjectContext(cwd, rl, stdout, stderr);
-    const aiAgents = await askAiAgents(rl, stdout, stderr);
+    const detectedAgents = await detectConfiguredAgents(cwd);
+    const aiAgents = await askAiAgents(rl, stdout, stderr, detectedAgents);
 
     if (aiAgents.length === 0) {
       throw new UserAbort('No AI agents selected. Nothing changed.');
@@ -488,10 +493,32 @@ async function detectProjectSignals(cwd) {
   return {
     hasSourceTree: hasSourceTree || relNames.has('src'),
     trackHint,
-    stackHints
+    stackHints,
+    configuredAgents: await detectConfiguredAgents(cwd)
   };
 }
 
+async function detectConfiguredAgents(cwd) {
+  // Surface agents this project already has configured so init / configure-agents
+  // can default to them instead of re-asking from scratch on every invocation.
+  // Order matches AI_AGENT_OPTIONS so the prompt numbering lines up.
+  const detected = [];
+  if (await pathExists(path.join(cwd, 'AGENTS.md'))) {
+    detected.push('agents');
+  }
+  if (
+    (await pathExists(path.join(cwd, 'CLAUDE.md'))) ||
+    (await pathExists(path.join(cwd, '.claude/commands/dflow'))) ||
+    (await pathExists(path.join(cwd, '.claude/skills/dflow')))
+  ) {
+    detected.push('claude');
+  }
+  if (await pathExists(path.join(cwd, '.github/copilot-instructions.md'))) {
+    detected.push('copilot');
+  }
+  return detected;
+}
+
 async function collectProjectFiles(cwd, maxDepth, maxFiles) {
   const results = [];
   const ignored = new Set(['.git', 'node_modules', 'bin', 'obj', 'dflow']);
@@ -535,8 +562,8 @@ async function collectProjectFiles(cwd, maxDepth, maxFiles) {
 function buildDetectionWarnings(answers, detection) {
   const warnings = [];
 
-  if (answers.projectType === 'greenfield' && detection.hasSourceTree) {
-    warnings.push('Warning: source-tree signals already exist, but project type is Greenfield. Continuing with your selected project type.');
+  if (answers.projectType === 'greenfield' && detection.hasSourceTree && !detection.trackHint) {
+    warnings.push('Note: existing source files were detected (e.g. a src/ directory or a build manifest). This is expected if you just scaffolded a fresh project — Dflow will continue as Greenfield. If this is actually an existing codebase, consider re-running and selecting Brownfield.');
   }
 
   if (detection.trackHint && answers.projectType !== detection.trackHint) {
@@ -586,7 +613,7 @@ async function promptForAnswers(rl, stdout, stderr, detection) {
   }
 
   const optionalFiles = await askOptionalFiles(rl, stdout, stderr);
-  const aiAgents = await askAiAgents(rl, stdout, stderr);
+  const aiAgents = await askAiAgents(rl, stdout, stderr, detection.configuredAgents || []);
 
   return {
     projectType,
@@ -771,17 +798,24 @@ async function askOptionalFiles(rl, stdout, stderr) {
   }
 }
 
-async function askAiAgents(rl, stdout, stderr) {
+async function askAiAgents(rl, stdout, stderr, defaultKeys = []) {
   let failedAttempts = 0;
+  const validDefaults = AI_AGENT_OPTIONS
+    .filter((option) => defaultKeys.includes(option.key))
+    .map((option) => option.key);
 
   while (true) {
     stdout.write('\nWhich AI coding agents should Dflow configure?\n');
     AI_AGENT_OPTIONS.forEach((option, index) => {
-      stdout.write(`  ${index + 1}. ${option.label}\n`);
+      const marker = validDefaults.includes(option.key) ? '  (currently configured)' : '';
+      stdout.write(`  ${index + 1}. ${option.label}${marker}\n`);
     });
 
-    const answer = await askLine(rl, 'Enter comma-separated choices or "none" (default: none): ');
-    const parsed = parseMultiselectAnswer(answer || 'none', AI_AGENT_OPTIONS, []);
+    const defaultHint = validDefaults.length > 0
+      ? validDefaults.map((key) => AI_AGENT_OPTIONS.findIndex((option) => option.key === key) + 1).join(',')
+      : 'none';
+    const answer = await askLine(rl, `Enter comma-separated choices or "none" (default: ${defaultHint}): `);
+    const parsed = parseMultiselectAnswer(answer, AI_AGENT_OPTIONS, validDefaults);
 
     if (!parsed.valid) {
       failedAttempts += 1;
@@ -1012,9 +1046,14 @@ async function buildFilePlan(cwd, answers) {
 
   await finalizePlanItems(cwd, items);
 
+  // Always project the workflow bundle (required for /dflow:* workflows to be reachable).
+  const bundleWarnings = [];
+  await addWorkflowBundleItems(cwd, items, bundleWarnings, answers.edition);
+
   return {
     items,
     deferred: buildDeferredItems(answers.edition),
+    bundleWarnings,
     unresolvedInitPlaceholders: Array.from(substitution.entries())
       .filter(([placeholder, value]) => placeholder === value)
       .map(([placeholder]) => placeholder)
@@ -1056,6 +1095,14 @@ async function buildConfigureAgentsPlan(cwd, answers) {
 
   await addSkillAdapterItems(cwd, items, answers.aiAgents, answers.skills, warnings);
 
+  // Project the workflow bundle on configure-agents too, so pre-039 projects (no bundle)
+  // and edition-switch repairs get the runtime references/templates reachable. The function
+  // is idempotent: it skips fresh bundle files, updates Dflow-generated ones, and warns
+  // (without overwriting) on user-modified bundle files.
+  const bundleWarnings = [];
+  await addWorkflowBundleItems(cwd, items, bundleWarnings, answers.edition);
+  warnings.push(...bundleWarnings);
+
   return {
     items,
     deferred: [],
@@ -1078,6 +1125,183 @@ async function finalizePlanItems(cwd, items) {
   }
 }
 
+async function listBundleSourceFiles(edition) {
+  const bundleDirs = ['references', 'templates'];
+  const files = [];
+
+  for (const dir of bundleDirs) {
+    const sourceDir = path.join(TEMPLATE_ROOT, edition, dir);
+    let entries;
+    try {
+      entries = await fs.readdir(sourceDir);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        continue;
+      }
+      throw error;
+    }
+    for (const entry of entries) {
+      const sourceRel = `${dir}/${entry}`;
+      const sourcePath = path.join(sourceDir, entry);
+      const stat = await fs.stat(sourcePath);
+      if (stat.isFile()) {
+        files.push({ sourceRel, dir, name: entry });
+      }
+    }
+  }
+
+  return files;
+}
+
+async function readCurrentBundleManifest(cwd) {
+  const manifestPath = path.join(cwd, WORKFLOW_BUNDLE_MANIFEST_PATH);
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function buildBundleManifest(edition, version, files) {
+  return {
+    edition,
+    version,
+    generatedBy: 'dflow-sdd-ddd',
+    files: files.map((f) => `${WORKFLOW_BUNDLE_DEST}/${f.sourceRel}`)
+  };
+}
+
+function injectBundleMarker(content) {
+  return `${WORKFLOW_BUNDLE_GENERATED_MARKER}\n\n${content}`;
+}
+
+async function addWorkflowBundleItems(cwd, items, warnings, edition) {
+  const bundleFiles = await listBundleSourceFiles(edition);
+
+  // Detect any previous manifest to handle edition-switch stale cleanup.
+  const existingManifest = await readCurrentBundleManifest(cwd);
+  const previousEdition = existingManifest ? existingManifest.edition : null;
+
+  // If the edition changed, schedule removal of stale generated files from prior edition.
+  if (previousEdition && previousEdition !== edition) {
+    const staleFiles = existingManifest.files || [];
+    for (const staleRelPath of staleFiles) {
+      const staleAbsPath = path.join(cwd, staleRelPath);
+      let staleExists = false;
+      try {
+        await fs.stat(staleAbsPath);
+        staleExists = true;
+      } catch {
+        staleExists = false;
+      }
+      if (!staleExists) {
+        continue;
+      }
+      const staleContent = await fs.readFile(staleAbsPath, 'utf8');
+      if (!staleContent.includes(WORKFLOW_BUNDLE_GENERATED_MARKER)) {
+        warnings.push(
+          `Edition changed from ${previousEdition} to ${edition}; skipped removal of user-modified bundle file: ${staleRelPath}`
+        );
+        continue;
+      }
+      // Check if this path is also in the new edition bundle — if so, it will be overwritten, not removed.
+      const newRelPaths = new Set(bundleFiles.map((f) => `${WORKFLOW_BUNDLE_DEST}/${f.sourceRel}`));
+      if (!newRelPaths.has(staleRelPath)) {
+        items.push({
+          relativePath: staleRelPath,
+          source: `stale-bundle:${previousEdition}`,
+          notes: `stale workflow bundle file from ${previousEdition} edition`,
+          action: 'remove',
+          size: Buffer.byteLength(staleContent, 'utf8'),
+          expectedContent: staleContent
+        });
+      }
+    }
+  }
+
+  // Build items for current edition bundle files.
+  for (const { sourceRel } of bundleFiles) {
+    const relativePath = `${WORKFLOW_BUNDLE_DEST}/${sourceRel}`;
+    const absolutePath = path.join(cwd, relativePath);
+    const sourceContent = await readPackagedBundleFile(edition, sourceRel);
+    const content = injectBundleMarker(sourceContent);
+
+    let action;
+    let notes = 'workflow bundle';
+    const targetExists = await pathExists(absolutePath);
+
+    if (targetExists) {
+      const existingContent = await fs.readFile(absolutePath, 'utf8');
+      if (existingContent.includes(WORKFLOW_BUNDLE_GENERATED_MARKER)) {
+        action = 'update';
+      } else {
+        action = 'skip';
+        notes = 'workflow bundle, user-modified — skipped; remove or rename to let Dflow manage';
+        warnings.push(
+          `Existing ${relativePath} is not a Dflow-generated bundle file; left unchanged. Remove or rename it to let Dflow manage this file.`
+        );
+      }
+    } else {
+      action = 'create';
+    }
+
+    items.push({
+      relativePath,
+      source: `packaged-bundle:${edition}/${sourceRel}`,
+      notes,
+      content,
+      action,
+      overwrite: action === 'update',
+      size: Buffer.byteLength(content, 'utf8')
+    });
+  }
+
+  // Add the manifest file.
+  const manifestContent = JSON.stringify(
+    buildBundleManifest(edition, pkg.version, bundleFiles),
+    null,
+    2
+  ) + '\n';
+  const manifestExists = await pathExists(path.join(cwd, WORKFLOW_BUNDLE_MANIFEST_PATH));
+
+  items.push({
+    relativePath: WORKFLOW_BUNDLE_MANIFEST_PATH,
+    source: `generated:workflow-bundle-manifest`,
+    notes: 'workflow bundle manifest',
+    content: manifestContent,
+    action: manifestExists ? 'update' : 'create',
+    overwrite: true,
+    size: Buffer.byteLength(manifestContent, 'utf8')
+  });
+}
+
+async function readPackagedBundleFile(edition, sourceRel) {
+  const filePath = path.join(TEMPLATE_ROOT, edition, sourceRel);
+  const normalizedRoot = path.resolve(TEMPLATE_ROOT, edition);
+  const normalizedFilePath = path.resolve(filePath);
+
+  if (!normalizedFilePath.startsWith(`${normalizedRoot}${path.sep}`)) {
+    throw new InitError(`Internal error: packaged bundle file not found: templates/${edition}/${sourceRel}`);
+  }
+
+  let buffer;
+  try {
+    buffer = await fs.readFile(normalizedFilePath);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new InitError(`Internal error: packaged bundle file not found: templates/${edition}/${sourceRel}`);
+    }
+    throw new InitError(`Internal error: cannot read packaged bundle file: templates/${edition}/${sourceRel}`);
+  }
+
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+  } catch {
+    throw new InitError(`Internal error: invalid UTF-8 packaged bundle file: templates/${edition}/${sourceRel}`);
+  }
+}
+
 async function addAiAgentShim(cwd, items, agent, substitution, options = {}) {
   const target = getAiAgentTarget(agent);
   const targetPath = path.join(cwd, target.relativePath);
@@ -1157,10 +1381,11 @@ This project uses Dflow for spec-first AI-assisted development.
 
 Before planning or editing code, 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,
+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.${commandTriggerHint}${importHint}
 `;
 }
@@ -1235,39 +1460,13 @@ async function addLegacyCommandAdapterCleanupItems(cwd, items, aiAgents, warning
   }
 }
 
-function buildDflowSkillAdapter() {
-  return `---
-name: dflow
-description: >
-  Dflow SDD/DDD workflow guardian for this project. PRIMARY: the canonical
-  /dflow:* commands (/dflow:new-feature, /dflow:modify-existing, /dflow:bug-fix,
-  /dflow:new-phase, /dflow:finish-feature, /dflow:pr-review, /dflow:verify,
-  /dflow:report-dflow-feedback, /dflow:status, /dflow:next, /dflow:cancel).
-  SECONDARY (auto-trigger safety net) — engage ONLY for: adding or changing
-  product/domain behavior, new requirements, a feature or bug-fix workflow, or
-  spec-impacting architecture/domain-model decisions. Do NOT engage for pure
-  refactors, infrastructure chores, formatting, or general code questions.
-  When engaged by natural language, DO NOT auto-enter a workflow: judge the
-  intent, suggest the matching /dflow: command, and wait for confirmation.
----
-
-${SKILL_ADAPTER_GENERATED_MARKER}
-
-# Dflow SDD/DDD Workflow Guardian
-
-This project uses Dflow for spec-first AI-assisted development. The canonical
-workflow contract, command registry, spec locations, and SDD/DDD rules live in:
-
-- \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
-
-When this skill engages, read that guide and follow the matching \`/dflow:\`
-workflow or control command defined there. Do not duplicate or invent workflow
-steps here — the guide is the single source of truth.
-
-If engaged by natural language (not an explicit \`/dflow:\` command): identify
-which \`/dflow:\` command fits, suggest it, and wait for the developer to confirm
-before entering any workflow.
-`;
+// Edition-agnostic thin shell: a single canonical source at
+// templates/common/skill/SKILL.md (PROPOSAL-041 C1). Returns the file
+// verbatim — frontmatter, marker, and body all live in the source file so
+// the skill content can be edited without touching JS.
+async function buildDflowSkillAdapter() {
+  const sourcePath = path.join(TEMPLATE_ROOT, COMMON_SKILL_SOURCE_REL);
+  return fs.readFile(sourcePath, 'utf8');
 }
 
 async function addSkillAdapterItems(cwd, items, aiAgents, skills, warnings) {
@@ -1307,11 +1506,13 @@ async function addSkillAdapterItems(cwd, items, aiAgents, skills, warnings) {
     return;
   }
 
+  const skillContent = await buildDflowSkillAdapter();
   items.push({
     relativePath,
     source: 'generated:claude-skill-adapter',
     notes: 'skill adapter, thin skill pointing to AI-AGENT-GUIDE.md',
-    content: buildDflowSkillAdapter(),
+    content: skillContent,
+    size: Buffer.byteLength(skillContent, 'utf8'),
     overwrite: true
   });
 }
@@ -1381,7 +1582,8 @@ ${COMMAND_ADAPTER_GENERATED_MARKER}
 
 Execute the canonical \`${command.label}\` Dflow workflow or control command.
 
-Definition: \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+Registry and rules: \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+Workflow steps: \`dflow/specs/shared/dflow-workflows/\`
 
 ${argHint}
 `;
@@ -1952,14 +2154,17 @@ function collectUnresolvedPlaceholderWarnings(plan, createdPaths) {
     return [];
   }
 
+  const placeholderFiles = new Set();
   for (const item of plan.items) {
     if (!createdSet.has(item.relativePath)) {
       continue;
     }
     const matches = item.content.match(/{[^{}\n]+}/g) || [];
-    matches
-      .filter((match) => unresolvedInitPlaceholders.has(match))
-      .forEach((match) => placeholders.add(match));
+    const hits = matches.filter((match) => unresolvedInitPlaceholders.has(match));
+    hits.forEach((match) => placeholders.add(match));
+    if (hits.length > 0) {
+      placeholderFiles.add(item.relativePath);
+    }
   }
 
   if (placeholders.size === 0) {
@@ -1969,7 +2174,10 @@ function collectUnresolvedPlaceholderWarnings(plan, createdPaths) {
   const sorted = Array.from(placeholders).sort();
   const shown = sorted.slice(0, 25).join(', ');
   const suffix = sorted.length > 25 ? `, and ${sorted.length - 25} more` : '';
-  return [`Unresolved placeholders remain for later SDD workflows: ${shown}${suffix}.`];
+  const files = Array.from(placeholderFiles).sort();
+  const filesShown = files.slice(0, 10).join(', ');
+  const filesSuffix = files.length > 10 ? `, and ${files.length - 10} more` : '';
+  return [`Unresolved placeholders remain for later SDD workflows: ${shown}${suffix}. Fill them in (or leave for the workflow to resolve) in: ${filesShown}${filesSuffix}.`];
 }
 
 function printResultReport(stdout, result, deferred) {
@@ -2086,6 +2294,9 @@ function normalizePath(value) {
 }
 
 function formatBytes(bytes) {
+  if (!Number.isFinite(bytes)) {
+    return '—';
+  }
   if (bytes < 1024) {
     return `${bytes} B`;
   }