dflow-sdd-ddd 0.9.0 → 0.10.0

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

@@ -28,7 +28,7 @@ are not available in the current AI tool:
 | `/dflow:bug-fix` | A defect can be described with expected vs actual behavior. |
 | `/dflow:new-phase` | An active feature needs another implementation slice. |
 | `/dflow:finish-feature` | Implementation is complete and needs drift closure. |
-| `/dflow:verify` | Specs, domain docs, implementation, and tests need consistency checks. |
+| `/dflow:verify` | A bounded context's domain docs (`rules.md` ↔ `behavior.md`) need a consistency / drift check. |
 | `/dflow:pr-review` | A change is ready for SDD/DDD review. |
 | `/dflow:report-dflow-feedback` | You found a Dflow issue or improvement and want a sanitized upstream feedback draft. |
 | `/dflow:status` | You need the current workflow state, current step, completed work, in-progress work, remaining work, pending decision, and next valid action. |
@@ -45,7 +45,7 @@ Machine-readable source for rendering tool-specific thin wrappers:
 | bug-fix | /dflow:bug-fix | Investigate a defect described by expected vs actual behavior. | expected vs actual | workflow |
 | new-phase | /dflow:new-phase | Add another implementation slice to an active feature. | feature id or phase goal | workflow |
 | finish-feature | /dflow:finish-feature | Close implementation with drift checks and archived feature state. | feature id | workflow |
-| verify | /dflow:verify | Check specs, domain docs, implementation, and tests for consistency. | area or feature id | workflow |
+| verify | /dflow:verify | Check a bounded context's domain docs (`rules.md` ↔ `behavior.md`) for consistency. | bounded context or all | workflow |
 | pr-review | /dflow:pr-review | Review a ready change for SDD/DDD alignment. | change or branch | workflow |
 | report-dflow-feedback | /dflow:report-dflow-feedback | Draft sanitized upstream feedback about Dflow. | issue or improvement | workflow |
 | status | /dflow:status | Report current workflow state and next valid action. | - | control |
@@ -53,6 +53,25 @@ Machine-readable source for rendering tool-specific thin wrappers:
 | cancel | /dflow:cancel | Abort the active workflow and return to free conversation. | - | control |
 <!-- dflow-command-registry:end -->
 
+## Routing Non-Command Input
+
+Not every developer message maps to a `/dflow:*` workflow. Route non-command
+input like this (supporting files live in the workflow bundle at
+`dflow/specs/shared/dflow-workflows/`):
+
+- **"I'm designing a domain model" / "How should I model X?"** → read
+  `references/ddd-modeling-guide.md`.
+- **"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`.
+- **"Dflow seems wrong" / "this template is confusing"** (or you notice Dflow
+  guidance drift) → suggest `/dflow:report-dflow-feedback`; never submit
+  anything upstream automatically.
+- **Anything else code-related** → assess whether it touches business logic. If
+  it does, use the auto-trigger safety net (suggest the matching `/dflow:*`
+  command and wait for confirmation — see § Workflow Transparency); if not, help
+  directly with no ceremony.
+
 ## Status / Control Commands
 
 `/dflow:status` reports active workflow state. Include these fields: workflow,
@@ -71,6 +90,67 @@ workflow was cancelled.
 When no workflow is active, `/dflow:next` and `/dflow:cancel` must report that
 there is no active workflow to advance or cancel.
 
+## Workflow Transparency
+
+Dflow uses a hybrid interaction design: `/dflow:*` commands are the primary
+entry, natural-language auto-trigger is a safety net, and tiered transparency
+keeps the developer aware of where they are in a workflow.
+
+### Auto-Trigger Safety Net
+
+When natural language implies a development task, detect the intent — but do
+**not** auto-enter a workflow. Instead:
+
+1. State your judgment clearly:
+   > "I think this is a new-feature task."
+2. Offer the developer three options:
+   - Type `/dflow:new-feature` to start explicitly
+   - Reply "OK" / "繼續" to confirm this workflow
+   - Or correct the workflow (e.g., "no, this is a bug fix")
+3. Wait for confirmation before entering any workflow.
+
+This addresses three failure modes of pure auto-trigger: missed triggers, wrong
+workflow selection, and invisible state.
+
+### Three-Tier Transparency
+
+During an active workflow, communicate at three levels — no more, no less:
+
+| Level | Trigger point | AI behavior |
+|---|---|---|
+| **Flow entry (must confirm)** | After judging the workflow from NL | Stop and wait for confirmation (command, "OK", or implicit) |
+| **Step gate (notify + optional confirm)** | Before major milestones | Announce the transition; if the developer provides next-step input, treat it as implicit confirmation |
+| **Step-internal (notify only)** | Step N → Step N+1 | Announce "Step N complete, entering Step N+1" — do not wait |
+
+The specific step-gate positions for each workflow live in that flow's own file
+(`dflow/specs/shared/dflow-workflows/references/<flow>.md`), which is the source
+of truth for its gate sequence.
+
+### Confirmation Signals (NL ↔ Command Equivalence)
+
+Any of these count as "proceed to next step" — accept whichever the developer
+uses:
+
+- **Command**: `/dflow:next`
+- **Verbal (English)**: OK / yes / continue / go ahead / sounds good / proceed
+- **Verbal (Chinese)**: 好 / 對 / 繼續 / 可以 / 沒問題
+- **Implicit**: the developer provides the information needed for the next step
+  (e.g., the AI asks "Which Aggregate?" and the developer answers with the
+  Aggregate name → implicit confirmation)
+
+The implicit-confirmation rule matters — do not turn every transition into a
+ceremony where the developer must say "OK" before every sentence.
+
+### Completion Checklist Skip Guard
+
+Completion checklists and their step ordering live in the flow files and run at
+the gate each flow specifies (the feature-level completion gate in
+`new-feature-flow` / `modify-existing-flow`, the phase-level gate in
+`new-phase-flow`). Do not run a checklist opportunistically. But if the
+developer skips the gate and commits directly, use the auto-trigger safety net
+to prompt — "It looks like you're wrapping up — should I run the Step N
+completion checklist?" — before giving commit guidance.
+
 ## Source of Truth
 
 Dflow-owned project documents live under `dflow/specs/`.
@@ -85,6 +165,41 @@ Dflow-owned project documents live under `dflow/specs/`.
 | Completed feature snapshots | `dflow/specs/features/completed/` |
 | Technical debt | `dflow/specs/architecture/tech-debt.md` or `dflow/specs/migration/tech-debt.md` |
 
+### Project Structure
+
+The full `dflow/specs/` layout Dflow seeds and maintains:
+
+```
+dflow/specs/
+├── shared/                         # Project-level governance docs (seeded by npx dflow-sdd-ddd init)
+│   ├── _overview.md
+│   └── _conventions.md
+├── domain/
+│   ├── glossary.md
+│   ├── context-map.md              # Bounded Context relationships
+│   └── {bounded-context}/
+│       ├── context.md
+│       ├── models.md               # Aggregates, Entities, VOs
+│       ├── rules.md                # Business rules index (BR-ID + one-line)
+│       ├── behavior.md             # Consolidated behavior (Given/When/Then)
+│       └── events.md               # Domain Events catalog
+├── features/
+│   ├── active/
+│   │   └── {SPEC-ID}-{slug}/       # One feature = one directory
+│   │       ├── _index.md           # Feature dashboard + BR Snapshot + Resume Pointer
+│   │       ├── phase-spec-YYYY-MM-DD-{slug}.md   # T1: 0..N phase specs
+│   │       └── lightweight-YYYY-MM-DD-{slug}.md  # T2: 0..N lightweight specs
+│   │                                             #     (or BUG-{NUMBER}-{slug}.md)
+│   ├── completed/                  # Done (whole feature directory archived here)
+│   └── backlog/
+│   #
+│   # SPEC-ID format: SPEC-YYYYMMDD-NNN; slug follows discussion language (中文 / 英文 both OK).
+│   # T3 trivial changes have NO independent file — just a row in _index.md Lightweight Changes.
+└── architecture/
+    ├── decisions/                  # Architecture Decision Records
+    └── tech-debt.md
+```
+
 ## Core Rules
 
 1. Spec before code: meaningful behavior changes need a spec or lightweight bug spec before implementation.
@@ -93,6 +208,111 @@ Dflow-owned project documents live under `dflow/specs/`.
 4. Check drift before calling work complete.
 5. Follow `dflow/specs/shared/_conventions.md`, especially `## Prose Language`.
 
+## Ceremony Scaling
+
+Dflow uses three tiers — **T1 Heavy / T2 Light / T3 Trivial** — chosen by the AI
+per change. `/dflow:new-feature` and `/dflow:new-phase` always default to T1 (no
+judgement needed). The criteria below apply when `/dflow:modify-existing` or
+`/dflow:bug-fix` decides which tier fits a modification.
+
+| 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) |
+| **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):
+
+1. No BR-ID change (no ADDED / MODIFIED / REMOVED / RENAMED business rule)
+2. No Domain concept added or changed (Aggregate / Entity / VO / Event)
+3. No data structure change (table, column, relation, index)
+4. Only changes UI surface (colour, text, layout), pure comments, or pure formatting
+
+If any criterion fails → drop to T2; if Domain / BR / data structure is touched → escalate to T1.
+
+**Below T3 — Dflow doesn't track at all**: pure typo fixes, commit-message
+typos, pure formatting commits (e.g. `prettier` / `dotnet format` auto-runs).
+You can `git commit` directly without writing even a T3 inline row.
+
+**DDD Modeling Depth (still informs T1 scope)**:
+
+- New Aggregate / BC → **Full**: create an `aggregate-design.md` from `templates/aggregate-design.md` in the feature directory (durable summary stays in `models.md`), update `context-map.md`, define Domain Events in `events.md`
+- Feature within an existing BC → **Standard**: confirm Aggregate ownership, update `models.md` and `rules.md`
+- T2 / T3 → confirm the fix lands in the correct architectural layer; no design-level updates required
+
+## Behavior Source of Truth (rules.md + behavior.md)
+
+Each Bounded Context has two complementary files that together describe the
+system's current behavior:
+
+- **`rules.md`** — declarative index: lists each BR-ID with a one-line summary.
+  Quick lookup, easy to scan.
+- **`behavior.md`** — scenario-level detail: the full Given/When/Then scenarios
+  for each BR-ID, including Aggregate state transitions and Domain Events. This
+  is the consolidated source of truth for "what does the system actually do
+  right now?"
+
+`dflow/specs/features/completed/` is a historical archive (individual change
+records). `behavior.md` is the **merged current state** — when a feature is
+completed, the AI merges its scenarios into `behavior.md`; when behavior is
+modified, the AI updates the corresponding section to reflect the new behavior
+(git preserves history). See the `behavior.md` template in the workflow bundle
+at `dflow/specs/shared/dflow-workflows/templates/behavior.md`.
+
+## Guiding Questions by Activity
+
+SDD has five conceptual activities (Understanding / Domain Modeling / Spec
+Writing / Implementation Planning / Testing Strategy) that the AI walks the
+developer through inside a workflow. They cut across workflow steps — Activity 2
+(Domain Modeling) might span Step 2 and Step 3 of new-feature-flow, for example.
+
+**Activity markers in the phase-spec template**: each section in
+`templates/phase-spec.md` carries an HTML comment (e.g.,
+`<!-- Fill timing: Activity 2: Domain Modeling -->`) indicating the activity in
+which that section should be filled. These markers align with the activities
+below and are used by `/dflow:status` and the completion checklist to track
+progress. When guiding a developer, fill sections in activity order; do not jump
+ahead to Activity 4 (Implementation Planning) before Activity 3 (Spec Writing)
+is agreed. The `Implementation Tasks` section at the end of the template is
+produced by the AI at the end of Activity 4 — see new-feature-flow.md Step 5 /
+new-phase-flow.md Step 4 / modify-existing-flow.md Step 3.
+
+Note: the phase-spec template HTML comments cover Activity 1–4; Activity 5
+(Testing Strategy) is a conceptual category folded into the Test Strategy
+section that the template marks with Activity 4 timing. In `new-phase-flow`,
+Activity 5 is exercised operationally in Step 6 when implementation and tests
+are verified against the phase-spec before Step 7 completion.
+
+### Activity 1: Understanding (What & Why)
+- What problem does this solve? Who asked for it?
+- What's the expected behavior from the user's perspective?
+- Are there existing specs or domain docs related to this?
+
+### Activity 2: Domain Modeling (DDD)
+- Which Bounded Context? (Check context-map.md)
+- What Aggregate does this belong to? Or is it a new Aggregate?
+- What are the invariants this Aggregate must protect?
+- Are there Value Objects to extract? (Money, DateRange, Address...)
+- Will this produce Domain Events? Who consumes them?
+- Does this cross Aggregate / Context boundaries? → Need an integration strategy
+
+### Activity 3: Spec Writing
+- Write the spec using the template (see `templates/phase-spec.md`)
+- Define Given/When/Then with Aggregate state transitions
+- Document Domain Events produced and consumed
+- Identify edge cases around Aggregate invariants
+
+### Activity 4: Implementation Planning
+- Domain layer: Aggregate design, Value Objects, Domain Events
+- Application layer: Command / Query, handlers, validation
+- Infrastructure: Repository implementation, persistence / ORM configuration
+- Presentation: API endpoint design
+
+### Activity 5: Testing Strategy
+- Domain unit tests: invariants, business rules, value object equality
+- Application tests: command / query handler behavior
+- Integration tests: repository, external services
+
 ## Pre-V1 Artifacts Detection
 
 When working in a project that adopted Dflow before `dflow-sdd-ddd@0.1.0`,

package/templates/greenfield/scaffolding/CLAUDE-md-snippet.md

@@ -5,12 +5,10 @@
 > Source: `scaffolding/CLAUDE-md-snippet.md`
 > Purpose: a minimal block you paste into (or replace with) your
 > project's root `CLAUDE.md` when adopting Dflow.
-> For the Greenfield track, the full reference template lives in the
-> in-project bundle at
-> `dflow/specs/shared/dflow-workflows/templates/CLAUDE.md` (projected by
-> `dflow init`) — if you want the complete legacy Claude-specific version,
-> use that instead. New CLI init output uses `AI-AGENT-GUIDE.md` plus a
-> generated `CLAUDE.md` shim.
+> New CLI init output uses `dflow/specs/shared/AI-AGENT-GUIDE.md` as the
+> canonical guide plus a thin generated `CLAUDE.md` shim. This snippet is
+> only the older Claude-specific two-H2 layout, for when you intentionally
+> want that shape in your project's root `CLAUDE.md`.
 
 ---
 
@@ -23,8 +21,7 @@
   Claude-specific two-H2 layout in your project's root `CLAUDE.md`.
 
 The two-H2 structure (`System Context` / `Development Workflow`) is intentional and must be
-preserved — it matches the Dflow skill's `templates/CLAUDE.md` and
-keeps every project's `CLAUDE.md` scannable for AI in the same shape.
+preserved — it keeps every project's `CLAUDE.md` scannable for AI in the same shape.
 
 ---
 
@@ -67,7 +64,7 @@ Presentation → Application → Domain ← Infrastructure
 
 ### Project Structure
 
-完整 specs 目錄結構見 Dflow skill `SKILL.md` § "Project Structure"。
+完整 specs 目錄結構見 `AI-AGENT-GUIDE.md` § Source of Truth。
 以下只列本專案當前狀態（Dflow CLI init 建立後可能還未全填）：
 
 ```
@@ -161,13 +158,11 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 
 ## Notes
 
-- This snippet is intentionally lighter than the in-project bundle
-  template at `dflow/specs/shared/dflow-workflows/templates/CLAUDE.md`. If
-  you want the full version (with detailed flow descriptions per slash
-  command), use that template instead
+- This snippet is intentionally minimal — the older Claude-specific two-H2
+  layout, not a full restatement of Dflow's logic
 - The snippet does NOT re-copy the Dflow decision tree, Ceremony
-  Scaling criteria, or per-flow step details — those live in the
-  skill and change when the skill evolves
+  Scaling criteria, or per-flow step details — those live in
+  `AI-AGENT-GUIDE.md` and the workflow bundle, and change as Dflow evolves
 - Re-running the Dflow CLI init command (`dflow init`, or `npx dflow-sdd-ddd init`
   when using the no-install path) will NOT overwrite an existing `CLAUDE.md`;
   if you want to re-sync, merge manually

package/templates/greenfield/scaffolding/Git-principles-trunk.md

@@ -58,7 +58,7 @@ gh pr create --base main --fill
 
 - **Short-lived feature branches**: typically hours to a few days, not
   weeks. Encourage splitting large features into multiple phase-specs
-  and merging each phase to `main` (see Dflow's Ceremony Scaling +
+  and merging each phase to `main` (see `AI-AGENT-GUIDE.md` § Ceremony Scaling +
   `/dflow:new-phase`)
 - **Main is always releasable**: feature flags or dark launches for
   incomplete functionality; CI must be green on `main` at all times

package/templates/greenfield/scaffolding/_conventions.md

@@ -8,15 +8,16 @@
 > Audience: engineers writing specs; AI assistants producing spec drafts.
 
 This file captures **project-level** conventions only. Template shapes
-and Ceremony criteria are defined by the Dflow skill; here we just
-record how *this* project fills them in.
+and Ceremony criteria are defined by Dflow itself (the Ceremony tier criteria
+live in `AI-AGENT-GUIDE.md` § Ceremony Scaling; template shapes live in the
+workflow bundle); here we just record how *this* project fills them in.
 
 ---
 
 ## Where Specs Live
 
 All spec documents live under `dflow/specs/`. The feature directory pattern
-and file names follow Dflow (see the Dflow skill § "Project Structure"
+and file names follow Dflow (see `AI-AGENT-GUIDE.md` § Source of Truth
 for the full tree):
 
 ```
@@ -119,8 +120,8 @@ Project-specific guidance when filling these templates:
 
 ## Ceremony Scaling (Project Application)
 
-The Dflow skill defines three tiers — **T1 Heavy / T2 Light / T3
-Trivial**. See the Dflow skill § "Ceremony Scaling" for the full
+Dflow defines three tiers — **T1 Heavy / T2 Light / T3
+Trivial**. See `AI-AGENT-GUIDE.md` § Ceremony Scaling for the full
 criteria table. We do not re-define the tier criteria here; this
 section records how *this* project applies them in borderline
 situations.
@@ -132,9 +133,9 @@ situations.
 | {e.g. EF configuration tweak in Infrastructure} | T3 if no Domain change | Infra-only; inline row in `_index.md` |
 | {e.g. Domain Event payload extension} | T1 | Event contract change affects cross-context consumers |
 
-### DDD Modeling Depth (Dflow skill § Ceremony Scaling)
+### DDD Modeling Depth (`AI-AGENT-GUIDE.md` § Ceremony Scaling)
 
-The Dflow skill further distinguishes:
+Dflow further distinguishes:
 
 - **Full** (new Aggregate / new BC): use `templates/aggregate-design.md`
   + update `context-map.md` + define events in `events.md`
@@ -170,7 +171,7 @@ and `/dflow:new-phase` flows; the project-level convention is simply
 - [Git principles](Git-principles-{gitflow|trunk}.md)
 - [Context map](../domain/context-map.md)
 - [Glossary](../domain/glossary.md)
-- Dflow skill `SKILL.md` — canonical source for Ceremony Scaling, flow
+- `AI-AGENT-GUIDE.md` — canonical source for Ceremony Scaling, flow
   selection, and template shapes.
 - Dflow skill `references/ddd-modeling-guide.md` — DDD tactical
   pattern reference.

package/templates/greenfield/templates/_index.md

@@ -89,7 +89,7 @@ Template note (for AI):
 > T3 行：inline 完整描述一句話 + 標籤（如 `[cosmetic]` / `[text]` /
 >        `[format]`）；T3 不產獨立 spec 檔
 >
-> Tier 判準見 SKILL.md § Ceremony Scaling 三層表。
+> Tier 判準見 AI-AGENT-GUIDE.md § Ceremony Scaling 三層表。
 
 | Date | Tier | Description | Commit |
 |---|---|---|---|

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

@@ -11,7 +11,7 @@ branch: bugfix/BUG-{NUMBER}-{short-description}
 Template note (for AI):
   This is the **lightweight-spec** template — it corresponds to T2 Light
   ceremony in the three-tier Ceremony Scaling (T1 Heavy / T2 Light /
-  T3 Trivial; see SKILL.md § Ceremony Scaling for the tier criteria).
+  T3 Trivial; see AI-AGENT-GUIDE.md § Ceremony Scaling for the tier criteria).
 
   - T1 Heavy → use templates/phase-spec.md instead
   - T2 Light → THIS template; produces an independent file

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

@@ -21,7 +21,7 @@ Template note (for AI):
 
   Each section below carries an HTML comment indicating its fill-in activity (Activity 1-4).
   These activity markers let /dflow:status and the completion checklist track progress.
-  Activities correspond to SKILL.md § Guiding Questions by Activity:
+  Activities correspond to AI-AGENT-GUIDE.md § Guiding Questions by Activity:
     Activity 1: Understanding (What & Why)
     Activity 2: Domain Modeling (BC, Aggregate, VO, Events)
     Activity 3: Spec Writing (Behavior + Rules + Edge Cases)

package/templates/brownfield/templates/CLAUDE.md

@@ -1,165 +0,0 @@
-# Project: {系統名稱} — {Framework}
-
-**重要：所有開發工作都必須遵循本文件定義的流程。**
-
----
-
-## System Context
-
-> 技術棧、業務領域、目錄結構
-
-### Background
-
-這是一個運行中的既有系統，使用 {Framework} / {Language}，目前持續新增與修改功能。
-目前採用 SDD 流程，同時為 DDD 與 target architecture 做準備。
-
-### Project Structure
-
-```
-dflow/specs/
-├── shared/                   # 專案級治理文件（由 dflow init 寫入）
-│   ├── _overview.md          # 系統現況與 target architecture
-│   └── _conventions.md       # 規格撰寫慣例與模板
-├── domain/                   # 領域知識
-│   ├── glossary.md           # 術語表（Ubiquitous Language）
-│   └── {context}/            # 按 Bounded Context 分
-│       ├── context.md        # Context 邊界與職責
-│       ├── models.md         # 領域模型定義
-│       └── rules.md          # 業務規則目錄
-├── features/
-│   ├── active/               # 進行中的 feature
-│   │   └── {SPEC-ID}-{slug}/ # 一個 feature 一個目錄
-│   │       ├── _index.md     # Feature dashboard：Goals & Scope / Phase Specs / Current BR Snapshot / Lightweight Changes / Resume Pointer
-│   │       ├── phase-spec-YYYY-MM-DD-{slug}.md   # T1 Heavy：每 phase 一份
-│   │       └── lightweight-YYYY-MM-DD-{slug}.md  # T2 Light（或 BUG-NNN-{slug}.md）
-│   ├── completed/            # 整個 feature 目錄 git mv 到這裡
-│   └── backlog/              # 待處理
-│   # SPEC-ID 格式：SPEC-YYYYMMDD-NNN；slug 跟隨討論語言（中文/英文皆可）
-│   # T3 無獨立檔，只在 _index.md Lightweight Changes 寫一列
-└── migration/
-    └── tech-debt.md          # 技術債與遷移備忘
-
-src/
-├── Domain/                   # 抽離的領域邏輯（framework-pure）
-│   ├── {Context}/
-│   │   ├── Entities/
-│   │   ├── ValueObjects/
-│   │   ├── Services/
-│   │   └── Interfaces/
-│   └── SharedKernel/
-└── Delivery/                 # delivery-layer code（entrypoints, controllers, handlers）
-```
-
-> **目錄命名說明**：上方 `src/Domain/` / `src/Delivery/` 是 Clean
-> Architecture 通用示意，不限 stack。請依專案實際慣例對應（例：Java/Spring 用
-> `src/main/java/com/example/domain/`、Node/TS 用 `src/domain/` /
-> `src/routes/`、Python 用 `domain/` package、Go 用 `internal/domain/` /
-> `internal/handler/`、.NET 用 `src/{Project}.Domain/` + `.csproj` 分層）。
-> 完整 per-stack 範例見 `docs/examples-by-stack.md`。重點是
-> `src/Domain/`（或對應命名）保持與 delivery/entrypoint code 獨立。
-
----
-
-## Development Workflow
-
-> SDD 流程、Git 整合、Domain 層規範、術語表、AI 協作
-
-### Core Principles
-1. **Spec Before Code** — 沒有規格就不寫實作
-2. **Domain Extraction** — 業務邏輯屬於 `src/Domain/`，不屬於 delivery/entrypoint code（presentation/UI layer、controllers、handlers、jobs、message consumers、data pipelines、stored procedures）
-3. **Ubiquitous Language** — 使用 `dflow/specs/domain/glossary.md` 中定義的術語
-4. **Migration Awareness** — 每個決策都要考慮 target architecture
-
-### Three Ceremony Tiers
-
-不是每次修改都要跑完整流程。AI 依下列判準選 tier：
-
-- **T1 Heavy** — 新功能、新 phase、架構變動、新增 BR → 建獨立 phase-spec，
-  走 `/dflow:new-feature` 或 `/dflow:new-phase`
-- **T2 Light** — bug fix、UI 輸入驗證、流程分支修改（有 BR Delta 但無 Domain /
-  資料結構變動）→ 建獨立 lightweight spec 置於 feature 目錄內
-- **T3 Trivial** — 按鈕顏色、文案修正、typo、排版、純註解（無 BR 變動、
-  無 Domain 概念動、無資料結構動、只改 UI 表層 / 註解 / 格式化）→
-  只在 `_index.md` Lightweight Changes inline 寫一列
-
-純 typo / 純格式化 commit（`dotnet format` / `prettier` 自動整理）**低於 T3**：
-直接 `git commit`，不走 Dflow。
-
-### New Feature
-1. 建 feature 目錄 `dflow/specs/features/active/{SPEC-ID}-{slug}/`
-2. 建 `_index.md`（feature dashboard）+ 第一份 `phase-spec-YYYY-MM-DD-{slug}.md`
-3. 識別涉及的領域概念，更新 `dflow/specs/domain/` 下的對應文件
-4. 盡可能將業務邏輯實作在 `src/Domain/` 中（語言純粹的 class，不依賴 delivery framework）
-5. Delivery/entrypoint code 僅負責輸入解析、協調流程與輸出綁定，呼叫 Domain 層處理邏輯
-6. 撰寫測試驗證 Domain 層行為符合規格
-
-### New Phase
-1. 在已啟動的 active feature 上新增一份 phase-spec（含 Delta-from-prior-phases）
-2. 更新 `_index.md` 的 Phase Specs 表 + regenerate Current BR Snapshot
-3. 嚴格只適用於 active feature；completed 的 feature 不接受新 phase
-
-### Modify Existing
-1. AI 依 T1 / T2 / T3 判準分流
-2. 若偵測到改動與 completed feature 相關，主動詢問是否為 follow-up
-   （follow-up 走新建 feature + `follow-up-of` 鏈回原 feature；不把 T2/T3
-   寫回 completed 目錄）
-3. 如果該功能的邏輯還在 delivery/entrypoint code 中，評估是否值得先抽離到 Domain 層
-4. 在 `dflow/specs/migration/tech-debt.md` 記錄發現的技術債
-
-### Bug Fix
-1. 建立輕量規格（問題 + 現有行為 + 預期行為 + 修復方式）
-2. 若 bug 不附掛既有 feature，先建最小 feature 目錄再放 lightweight-spec
-3. 修 Bug 時順便記錄發現的技術債
-
-### Feature Closeout
-1. 驗證 feature 目錄內所有 phase-spec `status: completed`
-2. 把 `_index.md` Current BR Snapshot 同步到 BC 層 `rules.md` / `behavior.md`
-3. `git mv` 整個 feature 目錄從 `active/` 搬到 `completed/`
-4. 產出 Integration Summary（Git-strategy-neutral；不自動 merge）
-
-### Git Integration
-
-> 本流程只規定 SDD 必要的最小 Git 耦合（feature branch per feature、
-> `git mv`、commit 對應 SPEC-ID）。實際採用的分支策略（Git Flow /
-> GitHub Flow / trunk-based / 單一 main）由專案決定，不在此強制。
-> 若採用 Git Flow，可參考 `scaffolding/Git-principles-gitflow.md` 範本。
-
-**分支命名**
-```
-feature/{SPEC-ID}-{short-description}    # 新功能（SDD 必須）
-bugfix/{BUG-ID}-{short-description}      # Bug 修復（SDD 必須）
-```
-
-**Commit Message**
-```
-[SPEC-ID] 簡述變更
-```
-
-**分支規則**
-- **feature/** — 必須先有 spec 才能開始編碼
-- **bugfix/** — 至少要有輕量 spec
-- **`/dflow:bug-fix`** 不綁定任何分支策略；採 Git Flow 的專案可選擇把
-  緊急修復放在 `hotfix/` 分支，但這是專案決策，Dflow 不代為規定
-
-### Domain Layer Rules (`src/Domain/`)
-
-此目錄中的程式碼必須遵守：
-- ❌ 不可引用任何 delivery-framework 命名空間（例：HTTP 請求/回應物件、Session/Cookie context、job runner context、CLI flag parser、ViewState 類等）
-- ❌ 不可直接存取資料庫（使用 interface + Repository pattern）
-- ❌ 不可使用 delivery-framework runtime context（例：HTTP request/response、session/cookie、job runner state、CLI args）
-- ❌ 不可有 UI / entrypoint 相關邏輯（格式化顯示、controller/page/handler 引用）
-- ✅ 語言純粹的 class（不依賴 delivery framework），可直接搬到 target architecture
-- ✅ 所有公開行為都能在沒有 delivery infrastructure 的情況下測試
-
-### Glossary
-
-所有業務術語必須使用 `dflow/specs/domain/glossary.md` 中定義的名稱。
-遇到新術語時，先新增到術語表再使用。
-
-### AI Collaboration Notes
-
-- 開發者提出任何功能需求時，先引導建立 spec
-- 在回答 Domain 相關問題時，優先參考 `dflow/specs/domain/` 中的文件
-- 發現 delivery/entrypoint code 中的業務邏輯時，建議抽離到 `src/Domain/`
-- 每次開發循環結束時，提醒更新術語表和技術債記錄
-- 建立分支前，確認命名符合規範且對應 spec 存在