dflow-sdd-ddd 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.12.0",
+  "version": "0.13.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/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

@@ -167,6 +167,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 +300,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 +372,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

@@ -108,6 +108,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.

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

@@ -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

@@ -64,6 +64,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.

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