dflow-sdd-ddd 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {
@@ -39,10 +39,13 @@
   },
   "homepage": "https://github.com/weilung/dflow-sdd-ddd#readme",
   "scripts": {
-    "test": "node test/smoke.mjs && node test/registry-parity.mjs && node test/agent-inject.mjs && node test/bundle-guards.mjs"
+    "test": "node test/smoke.mjs && node test/skill-default.mjs && node test/registry-parity.mjs && node test/agent-inject.mjs && node test/upgrade-drift.mjs && node test/bundle-guards.mjs && node test/render.mjs"
   },
   "license": "AGPL-3.0-or-later",
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "marked": "18.0.5"
   }
 }

package/templates/brownfield/references/init-project-flow.md

@@ -104,7 +104,9 @@ Used to substitute `{Framework}` / `{Framework version}` / `{Language}` /
 If yes → `_overview.md` "Target Architecture Strategy" section is emphasised and
 `migration/tech-debt.md` is prioritised. If no → the scaffolding still
 mentions the principles (Migration Awareness / Domain Extraction /
-Dual-Track Parallel / Pragmatic First) but framed as forward-option.
+Dual-Track Parallel / Pragmatic First) but framed as forward-option. Either
+way the answer is recorded in the `Migration / legacy context` row of the AI
+agent guide's `## Project Context` table.
 
 ### Q4. Project prose language
 
@@ -167,6 +169,32 @@ Wait for answers.
 > and refreshes it in place on re-run. Merge snippets under
 > `dflow/specs/shared/` are used only if Dflow markers conflict."
 
+Wait for answers.
+
+### Q9. Project-level skill (agent-gated, default yes)
+
+Asked only when Q8 selected at least one agent — with no agents there is no
+projection target and this question is skipped entirely.
+
+> "Install the project-level Dflow skill for natural-language auto-trigger?
+> (Y/n)
+>
+> The skill is what makes requests like 'I want to add a feature' surface the
+> matching workflow automatically; without it, triggering relies on the
+> instruction files alone and degrades in long sessions. Skill files are
+> Dflow-generated derivatives — the recommended default is to gitignore them
+> and re-project after cloning."
+
+Wait for the answer. **Blank defaults to yes.** On `n`, tell the developer:
+
+> "Skipped the project-level skill; add it later with
+> `dflow configure-agents --skills`."
+
+CLI note: the CLI asks this question only on an interactive terminal. A
+non-interactive (piped) `dflow init` never reads an extra stdin answer for it
+— existing scripted answer sequences keep their structure and keep working —
+and installs the skill for the selected agents by default.
+
 **→ Transition (step-internal)**: Step 2 complete. Announce
 > "Step 2 complete (project information captured). Entering Step 3:
 > File-list preview."
@@ -274,7 +302,7 @@ skip, and wait for developer confirmation:
 **→ Step Gate: Step 3 → Step 4**
 
 Wait for explicit confirmation. If the developer asks to change the
-selection, go back to the relevant Step 2 question (Q5–Q8) and re-run Step 3.
+selection, go back to the relevant Step 2 question (Q5–Q9) and re-run Step 3.
 
 ---
 
@@ -346,6 +374,22 @@ For each selected tool-specific file (`AGENTS.md`, `CLAUDE.md`,
   in the preview, and refresh that same block on re-run. If the developer later
   deletes the block, a later `init` / `configure-agents` run appends it again
 
+If the developer chose to install the project-level skill (Q9), the CLI also
+creates the skill file for each selected tool at its native project-level
+path:
+
+- `.claude/skills/dflow/SKILL.md` — Claude Code
+- `.agents/skills/dflow/SKILL.md` — Codex
+- `.github/skills/dflow/SKILL.md` — GitHub Copilot
+
+All three are the same edition-neutral thin skill projected from the single
+canonical source in the npm package. An existing file at one of those paths
+that is **not** Dflow-generated (missing the
+`<!-- dflow-generated: skill-adapter -->` marker) is left unchanged with a
+warning. Manual AI fallback (no npm available): do **not** hand-write SKILL.md
+content — report that the skill install is deferred and the developer should
+run `dflow configure-agents --skills` once npm is available.
+
 ### 4.4 Directory-only entries
 
 For directories that Git otherwise wouldn't track (empty `active/` /

package/templates/brownfield/scaffolding/AI-AGENT-GUIDE.md

@@ -13,6 +13,11 @@ This project uses Dflow for spec-first AI-assisted development.
 | Migration / legacy context | {migration-context} |
 | Prose language | {prose-language} |
 
+<!-- dflow-generated: guide-canonical START -->
+<!-- Everything between these markers is Dflow-managed canonical guide content.
+     `dflow configure-agents` refreshes it in place on upgrade. Put project-specific
+     notes in "## Project Context" above (or outside the markers), not in here. -->
+
 ## Why This Matters
 
 This project has business logic embedded in delivery/entrypoint code
@@ -108,6 +113,11 @@ input like this (supporting files live in the workflow bundle at
   is written with Greenfield artifact names; see its **Edition note** for where
   Brownfield records the same decisions (`models.md` / `rules.md` /
   `behavior.md` / `migration/tech-debt.md`).
+- **"Turn the specs into HTML" / "make the specs easier to read"** → run the
+  CLI command `dflow render` (a human-readability tool, not a `/dflow:*`
+  workflow). It mirrors `dflow/specs/` into a browsable static HTML tree
+  (default output: `dflow-specs-html/`); re-run it after specs change —
+  Markdown stays the AI-facing source of truth.
 - **"Dflow seems wrong" / "this template is confusing"** (or you notice Dflow
   guidance drift) → suggest `/dflow:report-dflow-feedback`; never submit
   anything upstream automatically.
@@ -295,7 +305,7 @@ needed). The criteria below apply when `/dflow:modify-existing` or
 | Tier | Scenario | Output | Command / Trigger |
 |---|---|---|---|
 | **T1 Heavy** | New feature, new phase, architectural change, new BR | Independent `phase-spec-YYYY-MM-DD-{slug}.md` placed in the feature directory + `_index.md` Phase Specs row + refresh BR Snapshot | `/dflow:new-feature` / `/dflow:new-phase` |
-| **T2 Light** | Bug fix, UI input validation tweak, flow branch change — has BR Delta | Independent `lightweight-{YYYY-MM-DD}-{slug}.md` (or `BUG-{NUMBER}-{slug}.md`) inside the feature directory + `_index.md` Lightweight Changes row (outbound link) + refresh BR Snapshot | `/dflow:bug-fix` or `/dflow:modify-existing` (lightweight branch) |
+| **T2 Light** | Bug fix, UI input validation tweak, flow branch change — has BR Delta | Independent `lightweight-YYYY-MM-DD-{slug}.md` (or `BUG-{NUMBER}-{slug}.md`) inside the feature directory + `_index.md` Lightweight Changes row (outbound link) + refresh BR Snapshot | `/dflow:bug-fix` or `/dflow:modify-existing` (lightweight branch) |
 | **T3 Trivial** | Button colour, copy/text fix, typo, formatting, pure comments — **no BR change, no Domain concept change, no data structure change** | **Inline row in `_index.md` Lightweight Changes only** (no independent spec file) | `/dflow:modify-existing` (`_index-only` branch) |
 
 **T3 criteria** (the AI must satisfy **all four** before classifying T3):
@@ -421,3 +431,5 @@ should stay thin and point back here.
 If a tool does not support Dflow slash commands, treat the command names as
 plain workflow names and follow the matching flow file from the workflow bundle
 at `dflow/specs/shared/dflow-workflows/`.
+
+<!-- dflow-generated: guide-canonical END -->

package/templates/brownfield/templates/_index.md

@@ -39,6 +39,8 @@ Template note (for AI):
     initial BR Snapshot + Resume Pointer. The other sections can stay empty.
 -->
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {Feature Title}
 
 ## Goals & Scope

package/templates/brownfield/templates/context-definition.md

@@ -5,6 +5,8 @@ owner: {負責的開發者或團隊}
 created: {YYYY-MM-DD}
 ---
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {ContextName} Bounded Context
 
 ## Responsibilities

package/templates/brownfield/templates/context-map.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Context Map
 

package/templates/brownfield/templates/glossary.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Glossary
 

package/templates/brownfield/templates/models.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Domain Models
 

package/templates/brownfield/templates/phase-spec.md

@@ -8,6 +8,8 @@ author: {developer-name}
 branch: feature/{SPEC-ID}-{slug}
 ---
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {Feature Title}
 
 <!--

package/templates/brownfield/templates/rules.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Business Rules
 

package/templates/brownfield/templates/tech-debt.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Migration Tech Debt
 

package/templates/greenfield/references/init-project-flow.md

@@ -110,12 +110,12 @@ Used to substitute `{Framework version}` / `{ORM version}` /
 
 > "Was this project ported / migrated from a prior stack (e.g. legacy
 > presentation framework, monolith), or is it new-build on the chosen
-> framework? If migrated, is there any legacy concern you'd like the
-> overview to flag?"
+> framework? If migrated, is there any legacy concern you'd like noted?"
 
-If migrated → `_overview.md` can carry a short migration-context note.
-Otherwise skip. In the Greenfield track, migration is not the first-class
-concern, but noting origin is still useful.
+If migrated → the answer is recorded in the `Migration / legacy context` row
+of the AI agent guide's `## Project Context` table. If not migrated, skip —
+the row records `none`. In the Greenfield track, migration is not the
+first-class concern, but noting origin is still useful.
 
 ### Q4. Project prose language
 
@@ -178,6 +178,32 @@ Wait for answers.
 > and refreshes it in place on re-run. Merge snippets under
 > `dflow/specs/shared/` are used only if Dflow markers conflict."
 
+Wait for answers.
+
+### Q9. Project-level skill (agent-gated, default yes)
+
+Asked only when Q8 selected at least one agent — with no agents there is no
+projection target and this question is skipped entirely.
+
+> "Install the project-level Dflow skill for natural-language auto-trigger?
+> (Y/n)
+>
+> The skill is what makes requests like 'I want to add a feature' surface the
+> matching workflow automatically; without it, triggering relies on the
+> instruction files alone and degrades in long sessions. Skill files are
+> Dflow-generated derivatives — the recommended default is to gitignore them
+> and re-project after cloning."
+
+Wait for the answer. **Blank defaults to yes.** On `n`, tell the developer:
+
+> "Skipped the project-level skill; add it later with
+> `dflow configure-agents --skills`."
+
+CLI note: the CLI asks this question only on an interactive terminal. A
+non-interactive (piped) `dflow init` never reads an extra stdin answer for it
+— existing scripted answer sequences keep their structure and keep working —
+and installs the skill for the selected agents by default.
+
 **→ Transition (step-internal)**: Step 2 complete. Announce
 > "Step 2 complete (project information captured). Entering Step 3:
 > File-list preview."
@@ -293,7 +319,7 @@ skip, and wait for developer confirmation:
 **→ Step Gate: Step 3 → Step 4**
 
 Wait for explicit confirmation. If the developer asks to change the
-selection, go back to the relevant Step 2 question (Q5–Q8) and re-run Step 3.
+selection, go back to the relevant Step 2 question (Q5–Q9) and re-run Step 3.
 
 ---
 
@@ -367,6 +393,22 @@ For each selected tool-specific file (`AGENTS.md`, `CLAUDE.md`,
   in the preview, and refresh that same block on re-run. If the developer later
   deletes the block, a later `init` / `configure-agents` run appends it again
 
+If the developer chose to install the project-level skill (Q9), the CLI also
+creates the skill file for each selected tool at its native project-level
+path:
+
+- `.claude/skills/dflow/SKILL.md` — Claude Code
+- `.agents/skills/dflow/SKILL.md` — Codex
+- `.github/skills/dflow/SKILL.md` — GitHub Copilot
+
+All three are the same edition-neutral thin skill projected from the single
+canonical source in the npm package. An existing file at one of those paths
+that is **not** Dflow-generated (missing the
+`<!-- dflow-generated: skill-adapter -->` marker) is left unchanged with a
+warning. Manual AI fallback (no npm available): do **not** hand-write SKILL.md
+content — report that the skill install is deferred and the developer should
+run `dflow configure-agents --skills` once npm is available.
+
 ### 4.4 Directory-only entries
 
 For directories that Git otherwise wouldn't track (empty `active/` /

package/templates/greenfield/scaffolding/AI-AGENT-GUIDE.md

@@ -13,6 +13,11 @@ This project uses Dflow for spec-first AI-assisted development.
 | Migration / legacy context | {migration-context} |
 | Prose language | {prose-language} |
 
+<!-- dflow-generated: guide-canonical START -->
+<!-- Everything between these markers is Dflow-managed canonical guide content.
+     `dflow configure-agents` refreshes it in place on upgrade. Put project-specific
+     notes in "## Project Context" above (or outside the markers), not in here. -->
+
 ## Before Editing Code
 
 Do not jump from a request directly to code. First identify the matching
@@ -64,6 +69,11 @@ input like this (supporting files live in the workflow bundle at
 - **"Quick question about..." / "How does X work?"** → check
   `dflow/specs/domain/` first and answer from the documented domain knowledge.
 - **"I'm creating a branch"** → read `references/git-integration.md`.
+- **"Turn the specs into HTML" / "make the specs easier to read"** → run the
+  CLI command `dflow render` (a human-readability tool, not a `/dflow:*`
+  workflow). It mirrors `dflow/specs/` into a browsable static HTML tree
+  (default output: `dflow-specs-html/`); re-run it after specs change —
+  Markdown stays the AI-facing source of truth.
 - **"Dflow seems wrong" / "this template is confusing"** (or you notice Dflow
   guidance drift) → suggest `/dflow:report-dflow-feedback`; never submit
   anything upstream automatically.
@@ -253,7 +263,7 @@ judgement needed). The criteria below apply when `/dflow:modify-existing` or
 | Tier | Scenario | Output | Command / Trigger |
 |---|---|---|---|
 | **T1 Heavy** | New feature, new phase, new Aggregate / BC, architectural change, new BR | Independent `phase-spec-YYYY-MM-DD-{slug}.md` placed in the feature directory + `_index.md` Phase Specs row + refresh BR Snapshot. For a new Aggregate / BC also create an `aggregate-design.md` from `templates/aggregate-design.md` **in the feature directory** (working worksheet; the durable summary stays in `models.md`) + update `context-map.md` + `events.md`. | `/dflow:new-feature` / `/dflow:new-phase` |
-| **T2 Light** | Bug fix (logic error), UI input validation tweak, flow branch change — has BR Delta | Independent `lightweight-{YYYY-MM-DD}-{slug}.md` (or `BUG-{NUMBER}-{slug}.md`) inside the feature directory + `_index.md` Lightweight Changes row (outbound link) + refresh BR Snapshot. Confirm the fix lands in the correct architectural layer. | `/dflow:bug-fix` or `/dflow:modify-existing` (lightweight branch) |
+| **T2 Light** | Bug fix (logic error), UI input validation tweak, flow branch change — has BR Delta | Independent `lightweight-YYYY-MM-DD-{slug}.md` (or `BUG-{NUMBER}-{slug}.md`) inside the feature directory + `_index.md` Lightweight Changes row (outbound link) + refresh BR Snapshot. Confirm the fix lands in the correct architectural layer. | `/dflow:bug-fix` or `/dflow:modify-existing` (lightweight branch) |
 | **T3 Trivial** | Button colour, copy/text fix, typo, formatting, pure comments — **no BR change, no Domain concept change, no data structure change** | **Inline row in `_index.md` Lightweight Changes only** (no independent spec file) | `/dflow:modify-existing` (`_index-only` branch) |
 
 **T3 criteria** (the AI must satisfy **all four** before classifying T3):
@@ -384,3 +394,5 @@ should stay thin and point back here.
 If a tool does not support Dflow slash commands, treat the command names as
 plain workflow names and follow the matching flow file from the workflow bundle
 at `dflow/specs/shared/dflow-workflows/`.
+
+<!-- dflow-generated: guide-canonical END -->

package/templates/greenfield/templates/_index.md

@@ -46,6 +46,8 @@ Template note (for AI):
     initial BR Snapshot + Resume Pointer. The other sections can stay empty.
 -->
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {Feature Title}
 
 ## Goals & Scope

package/templates/greenfield/templates/aggregate-design.md

@@ -4,6 +4,8 @@ bounded-context: {ContextName}
 created: {YYYY-MM-DD}
 ---
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {AggregateName} Aggregate
 
 ## Purpose

package/templates/greenfield/templates/context-definition.md

@@ -5,6 +5,8 @@ owner: {負責的開發者或團隊}
 created: {YYYY-MM-DD}
 ---
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {ContextName} Bounded Context
 
 ## Responsibilities

package/templates/greenfield/templates/context-map.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Context Map
 

package/templates/greenfield/templates/events.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Domain Events
 

package/templates/greenfield/templates/glossary.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Glossary
 

package/templates/greenfield/templates/models.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Domain Models
 

package/templates/greenfield/templates/phase-spec.md

@@ -8,6 +8,8 @@ author: {developer-name}
 branch: feature/{SPEC-ID}-{slug}
 ---
 
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
+
 # {功能標題}
 
 <!--

package/templates/greenfield/templates/rules.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Business Rules
 

package/templates/greenfield/templates/tech-debt.md

@@ -1,4 +1,5 @@
 <!-- Seeded by Dflow. -->
+<!-- Formatting convention: keep table cells concise. When one cell holds multiple short items (invariants, rules, steps), separate them with <br> so each renders on its own line - never chain them into one line with ；/; separators. Long narrative detail does not belong in a table cell: keep the cell to a concise summary and put extended detail in an existing section of this document when one fits, or give each item its own row. -->
 
 # Architecture Tech Debt