dflow-sdd-ddd 0.1.0

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

@@ -0,0 +1,25 @@
+<!-- Template maintained by Dflow. See proposals/PROPOSAL-013 for origin. -->
+
+# Context Map
+
+> Bounded context relationship map for the Core architecture.
+
+## Contexts
+
+| Bounded Context | Responsibility | Owner / Team | Primary Module | Notes |
+|---|---|---|---|---|
+| {Context name} | {業務責任} | {owner} | `{module/project}` | {optional notes} |
+
+## Relationships
+
+| Upstream | Downstream | Relationship Type | Published Language | ACL | Events |
+|---|---|---|---|---|---|
+| {Upstream context} | {Downstream context} | {Customer/Supplier, Conformist, ACL, Shared Kernel, etc.} | {shared terms / contract} | {Yes/No + location} | {event names or n/a} |
+
+## Integration Notes
+
+- {跨 context 的資料流、contract、ACL 或 integration event 設計}
+
+## Open Questions
+
+- {尚未釐清的 context 邊界或 upstream/downstream 關係}

package/templates/core/templates/events.md

@@ -0,0 +1,19 @@
+<!-- Template maintained by Dflow. See proposals/PROPOSAL-013 for origin. -->
+
+# Domain Events
+
+> Domain event catalog for one bounded context.
+
+## Event Catalog
+
+| Event name | Producer | Trigger | Payload | Consumers | Delivery expectation |
+|---|---|---|---|---|---|
+| {EventName} | {Aggregate / Application Service} | {觸發條件} | `{Payload shape}` | {consumer names} | {in-process / outbox / integration event / manual} |
+
+## Event Flow Notes
+
+- {事件發生時序、交易邊界、重試或一致性注意事項}
+
+## Open Questions
+
+- {尚未確定的事件命名、payload 或 delivery expectation}

package/templates/core/templates/glossary.md

@@ -0,0 +1,15 @@
+<!-- Template maintained by Dflow. See proposals/PROPOSAL-013 for origin. -->
+
+# Glossary
+
+> Ubiquitous Language for this project or bounded context.
+
+## Terms
+
+| Term | Definition | Bounded Context | Code Mapping | Notes |
+|---|---|---|---|---|
+| {Term} | {這個術語在業務中的定義} | {Context name} | `{Namespace/Class/Member}` | {optional notes} |
+
+## Open Questions
+
+- {需要和 domain expert 確認的術語或命名差異}

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

@@ -0,0 +1,82 @@
+---
+id: BUG-{NUMBER}
+title: {簡述問題}
+status: in-progress
+bounded-context: {ContextName}
+created: {YYYY-MM-DD}
+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).
+
+  - T1 Heavy → use templates/phase-spec.md instead
+  - T2 Light → THIS template; produces an independent file
+  - T3 Trivial → no independent file; just one inline row in _index.md
+                 Lightweight Changes with a tag like [cosmetic] / [text] / [format]
+
+  Instance file location and naming:
+    Place the instantiated file inside the corresponding feature directory:
+      dflow/specs/features/active/{SPEC-ID}-{slug}/lightweight-{YYYY-MM-DD}-{slug}.md
+    or, when the lightweight change is a tracked bug:
+      dflow/specs/features/active/{SPEC-ID}-{slug}/BUG-{NUMBER}-{slug}.md
+
+    If the change is a standalone bug not yet attached to any existing
+    feature, /dflow:bug-fix must first create a feature directory (with a
+    minimal _index.md) before placing the lightweight-spec instance inside.
+    This keeps the structure invariant: every spec file lives under some
+    feature directory.
+
+  After finalizing this lightweight-spec, AI must:
+    1. Add an outbound-link row to the feature's _index.md Lightweight Changes table
+       (Tier = T2; description includes the link to this file)
+    2. Refresh the feature's _index.md Current BR Snapshot table to reflect
+       any BR ADDED / MODIFIED / REMOVED / RENAMED in this lightweight-spec
+-->
+
+# {問題簡述}
+
+## Problem
+
+{什麼東西壞了？或什麼行為不正確？}
+
+## Behavior Delta
+
+> 精簡 delta 格式：bug fix 多數只需 MODIFIED；若確實是新增規則可改用 ADDED、移除用 REMOVED、改名用 RENAMED。多項變更時照類別列。
+
+### MODIFIED - behavior modified in this fix
+#### Rule: BR-NN {規則名稱}
+**Before**: Given {current Aggregate state} When {action} Then {current (incorrect) result} / {event}
+**After**: Given {same state} When {same action} Then {correct result} / {event}
+**Reason**: {why this change — bug / invariant violation / requirement clarification}
+
+<!-- 若需要 ADDED / REMOVED / RENAMED / UNCHANGED 請比照 references/modify-existing-flow.md 的 Delta 格式 -->
+
+
+## Root Cause
+
+{為什麼會這樣？是邏輯錯誤？資料問題？還是需求理解有誤？}
+
+## Fix Approach
+
+{怎麼修？有沒有抽到 Domain 層的機會？}
+
+<!-- dflow:section implementation-tasks -->
+## Implementation Tasks
+
+> Keep T2 Light tasks concise. If the fix scope starts to expand, AI should pause and ask the developer whether to keep this as T2 or upgrade it to T1. Do not auto-upgrade based on task count alone.
+>
+> Recommended layer tags (Core): `DOMAIN` / `APP` / `INFRA` / `API` / `TEST` / `DOC`
+
+- [ ] {LAYER}-1: {minimal required change}
+- [ ] TEST-1: {minimal verification / regression test}
+- [ ] DOC-1: Update `_index.md` Lightweight Changes and Current BR Snapshot
+
+Layer tag list above is the recommended set; the developer may extend with project-specific tags as needed.
+
+## Tech Debt Discovered (if any)
+
+{在修這個 bug 時發現的其他問題，記錄到 tech-debt.md}

package/templates/core/templates/models.md

@@ -0,0 +1,47 @@
+<!-- Template maintained by Dflow. See proposals/PROPOSAL-013 for origin. -->
+
+# Domain Models
+
+> DDD model catalog for one bounded context.
+
+## Context
+
+- **Bounded Context**: {Context name}
+- **Source Code Area**: `{project/path/or/namespace}`
+- **Last Updated**: {YYYY-MM-DD}
+
+## Aggregates
+
+| Aggregate | Root Entity | Invariants | Code Mapping | Notes |
+|---|---|---|---|---|
+| {AggregateName} | {RootEntityName} | {核心不變量} | `{Namespace.Class}` | {optional notes} |
+
+## Entities
+
+| Entity | Responsibility | Key Identity | Aggregate | Code Mapping |
+|---|---|---|---|---|
+| {EntityName} | {核心職責} | {Id / composite key} | {AggregateName} | `{Namespace.Class}` |
+
+## Value Objects
+
+| Value Object | Responsibility | Equality Components | Code Mapping | Notes |
+|---|---|---|---|---|
+| {ValueObjectName} | {代表的概念} | {fields} | `{Namespace.Class}` | {optional notes} |
+
+## Domain Services
+
+| Service | Responsibility | Inputs / Outputs | Code Mapping | Notes |
+|---|---|---|---|---|
+| {ServiceName} | {跨 aggregate/entity/value object 的 domain operation} | {inputs -> outputs} | `{Namespace.Class}` | {optional notes} |
+
+## Specifications
+
+| Specification | Rule / Invariant | Used By | Code Mapping | Notes |
+|---|---|---|---|---|
+| {SpecificationName} | {規則或查詢條件} | {use case / aggregate} | `{Namespace.Class}` | {optional notes} |
+
+## Repository Interfaces
+
+| Repository | Aggregate | Query Responsibility | Code Mapping | Notes |
+|---|---|---|---|---|
+| {RepositoryName} | {AggregateName} | {查詢或保存責任} | `{Namespace.Interface}` | {optional notes} |

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

@@ -0,0 +1,195 @@
+---
+id: {CONTEXT}-{NUMBER}
+title: 功能標題
+status: draft | in-progress | completed
+bounded-context: {ContextName}
+created: {YYYY-MM-DD}
+author: {developer-name}
+branch: feature/{CONTEXT}-{NUMBER}-{short-description}
+---
+
+# {功能標題}
+
+<!--
+Template note (for AI):
+  This is the **phase-spec** template - one phase-spec captures one full
+  "Kickoff -> Domain -> Design -> Build -> Verify" cycle inside a feature directory.
+  A feature can have 1..N phase-specs; the feature-level dashboard lives in
+  the sibling `_index.md` (see templates/_index.md). The instance file name is
+  `phase-spec-YYYY-MM-DD-{slug}.md` placed at
+  `dflow/specs/features/active/{SPEC-ID}-{slug}/`.
+
+  Each section below carries an HTML comment indicating its fill-in phase (Phase 1-4).
+  These phase markers let /dflow:status and the completion checklist track progress.
+  Phases correspond to SKILL.md § Guiding Questions by Phase:
+    Phase 1 - Understanding (What & Why)
+    Phase 2 - Domain Modeling (BC, Aggregate, VO, Events)
+    Phase 3 - Spec Writing (Behavior + Rules + Edge Cases)
+    Phase 4 - Implementation Planning (layer-by-layer)
+  The "Implementation Tasks" section at the end is generated by AI after Phase 4 planning is done
+  (see new-feature-flow.md Step 5 end / new-phase-flow.md Step 4 end /
+   modify-existing-flow.md Step 3 end).
+
+  For phase 2+ specs in the same feature: only list BRs that are NEW or
+  MODIFIED in this phase under "Business Rules"; do not re-copy unchanged BRs from
+  prior phases. The cumulative state lives in the feature's `_index.md`
+  Current BR Snapshot table; the system-level current state lives in the
+  bounded context's `rules.md` / `behavior.md` (synced at /dflow:finish-feature).
+-->
+
+## Problem Description <!-- Fill timing: Phase 1 -->
+
+> 用使用者的角度描述，避免技術用語。
+
+## Domain Concepts <!-- Fill timing: Phase 2 -->
+
+涉及的 Domain 概念（引用 `dflow/specs/domain/{context}/models.md`）：
+
+| Concept | Type | Description |
+|---|---|---|
+| {Name} | Aggregate Root / Entity / Value Object / Domain Service | 角色 |
+
+更新檢查：
+- [ ] `dflow/specs/domain/glossary.md` — 新術語
+- [ ] `dflow/specs/domain/{context}/models.md` — 模型定義
+- [ ] `dflow/specs/domain/{context}/events.md` — Domain Events
+
+<!-- dflow:section behavior-scenarios -->
+## Behavior Scenarios <!-- Fill timing: Phase 3 -->
+
+### Main Success Scenario
+
+```gherkin
+Scenario: {情境名稱}
+  Given {Aggregate 的初始狀態}
+  When {呼叫的 Aggregate 方法或 Command}
+  Then {Aggregate 的新狀態}
+  And {產生的 Domain Event}
+```
+
+### Alternative Scenarios
+
+```gherkin
+Scenario: {替代情境}
+  Given {不同初始狀態}
+  When {相同或不同操作}
+  Then {不同結果}
+```
+
+## Business Rules <!-- Fill timing: Phase 3 -->
+
+> Phase 2+ 注意：本段僅列**本 phase 新增 / 修改到的 BR**；未變動的 BR 不重抄
+> （它們的當前狀態見 feature 的 `_index.md` Current BR Snapshot 表）。
+
+| BR-ID | Rule | Implementation Location |
+|---|---|---|
+| BR-01 | {規則描述} | Domain: {Entity/VO/Service} |
+| BR-02 | {規則描述} | Domain: {Entity/VO/Service} |
+
+## Delta from prior phases <!-- Fill timing: Phase 3; skip for the first phase -->
+
+> 本段僅記**本 phase 相對前一 phase 的變化**，不累積歷史。歷史由 feature 目錄下
+> 各 phase-spec 的本段串接閱讀；feature 層的當前累積狀態見 `_index.md` 的
+> Current BR Snapshot；BC 層當前狀態見 `dflow/specs/domain/{context}/rules.md` /
+> `behavior.md`（在 `/dflow:finish-feature` 時同步）。
+>
+> **首 phase**：標註「首 phase，無前置 Delta」即可，不需逐項填。
+> **Phase 2+**：必填；格式沿用 modify-existing-flow.md 的 Delta 規則
+> （ADDED / MODIFIED / REMOVED / RENAMED + 選用 UNCHANGED）。
+
+### ADDED - BR / behavior added in this phase
+#### Rule: BR-NN {規則名稱}
+Given {Aggregate 初始狀態}
+When {呼叫的 Command 或 Aggregate 方法}
+Then {新的 Aggregate 狀態}
+And {產生的 Domain Event}
+
+### MODIFIED - BR / behavior modified in this phase
+#### Rule: BR-NN {規則名稱}
+**Before**: Given … When … Then {old result} / {old event}
+**After**: Given … When … Then {new result} / {new event}
+**Reason**: {why this change}
+
+### REMOVED - BR removed in this phase
+#### Rule: BR-NN {規則名稱}
+**Reason**: {why removed}
+
+### RENAMED - BR renamed in this phase
+#### Rule: {old name} -> {new name}
+**Reason**: {why renamed}
+
+### UNCHANGED - explicitly unaffected (optional)
+- BR-003 金額上限
+- BR-005 提交後不可修改
+
+## Edge Cases <!-- Fill timing: Phase 3 -->
+
+| ID | Case | Expected Handling |
+|---|---|---|
+| EC-01 | {邊界描述} | {處理方式} |
+
+## Domain Events <!-- Fill timing: Phase 2-3; draft during design, finalized during spec writing -->
+
+| Event | Trigger | Handler | Sync / Async |
+|---|---|---|---|
+| {EventName} | {何時觸發} | {Handler} | 同步/異步 |
+
+## Implementation Plan (Layer by Layer) <!-- Fill timing: Phase 4 -->
+
+### Domain Layer
+> Aggregate 設計、Value Objects、Events、Interfaces
+
+### Application Layer
+> Command/Query、Handler、Validator、DTO
+
+### Infrastructure Layer
+> EF 設定、Repository 實作、外部服務
+
+### Presentation Layer
+> API Endpoint 設計、Request/Response 模型
+
+## Data Structure Changes <!-- Fill timing: Phase 4 -->
+
+| Table | Column | Change Type | Description |
+|---|---|---|---|
+| {Table} | {Column} | 新增/修改/刪除 | |
+
+## Test Strategy <!-- Fill timing: Phase 4 -->
+
+### Domain Unit Tests
+- [ ] {不變條件測試}
+- [ ] {業務規則測試}
+- [ ] {Value Object 相等性測試}
+
+### Application Tests
+- [ ] {Command Handler 測試}
+- [ ] {Query Handler 測試}
+
+### Integration Tests
+- [ ] {Repository 測試}
+
+<!-- dflow:section open-questions -->
+## Open Questions <!-- Fill timing: Phase 1-4 -->
+
+- {尚未釐清的需求、規則、資料或實作問題}
+
+<!-- dflow:section implementation-tasks -->
+## Implementation Tasks <!-- Fill timing: generated by AI after Phase 4; all items should be checked at completion -->
+
+> AI 在 Phase 4 實作規劃完成後，根據「Implementation Plan (Layer by Layer)」產生的具體任務清單。
+> 格式：`[LAYER]-[NUMBER]: 任務描述`
+> 分類標籤（Core 版，對應 Clean Architecture 各層）：
+>   - `DOMAIN` — Aggregate、Entity、VO、Domain Event、Domain Service、Repository Interface
+>   - `APP`    — Command/Query、Handler、Validator、DTO、Event Handler
+>   - `INFRA`  — EF Configuration、Repository Impl、外部服務 adapter、Migration
+>   - `API`    — Controller / Minimal API、Request/Response 模型、Swagger
+>   - `TEST`   — 各層測試案例
+> 建議產出順序與實作順序相符：DOMAIN -> APP -> INFRA -> API。
+> 本段在 spec 歸檔（搬到 `completed/`）前應確認全部勾選，或明確標註未完成項的 follow-up。
+
+- [ ] DOMAIN-1: {任務描述}
+- [ ] DOMAIN-2: {任務描述}
+- [ ] APP-1: {任務描述}
+- [ ] INFRA-1: {任務描述}
+- [ ] API-1: {任務描述}
+- [ ] TEST-1: {任務描述}

package/templates/core/templates/rules.md

@@ -0,0 +1,24 @@
+<!-- Template maintained by Dflow. See proposals/PROPOSAL-013 for origin. -->
+
+# Business Rules
+
+> Declarative BR-ID index for one bounded context.
+
+<!-- dflow:section business-rules -->
+## Rule Index
+
+| BR-ID | Rule summary | Behavior anchor | Aggregate | Status | Last updated |
+|---|---|---|---|---|---|
+| BR-001 | {業務規則摘要} | [BR-001](./behavior.md#br-001-rule-name) | {AggregateName} | draft | {YYYY-MM-DD} |
+
+## Status Legend
+
+| Status | Meaning |
+|---|---|
+| draft | Rule is identified but not fully validated. |
+| active | Rule is validated and expected to be enforced. |
+| deprecated | Rule is retained for history but no longer active. |
+
+## Open Questions
+
+- {需要 domain expert 確認的規則}

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

@@ -0,0 +1,15 @@
+<!-- Template maintained by Dflow. See proposals/PROPOSAL-013 for origin. -->
+
+# Architecture Tech Debt
+
+> Architecture debt backlog discovered during SDD/DDD work.
+
+## Debt Items
+
+| Item | Layer | Decision / debt | Impact | Follow-up | Status |
+|---|---|---|---|---|---|
+| {Debt item} | {Domain/Application/Infrastructure/API} | {決策或債務描述} | {影響範圍} | {後續處理方式} | {open/planned/in-progress/done} |
+
+## Follow-up Notes
+
+- {需要後續 proposal、ADR、refactor 或 architecture review 的事項}

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

@@ -0,0 +1,167 @@
+<!-- Scaffolding template maintained alongside Dflow skill. See proposals/PROPOSAL-010 for origin. -->
+
+# CLAUDE.md Snippet — Dflow Adoption
+
+> This file is a **snippet**, not a standalone `CLAUDE.md`. Its purpose
+> is to be merged into your project's root `CLAUDE.md`:
+>
+> - If your project does **not** yet have a `CLAUDE.md`, the
+>   `npx dflow-sdd-ddd init` flow will create one using this snippet as
+>   the starting content.
+> - If your project **already has** a `CLAUDE.md`, the init flow will
+>   copy this file into your repo and prompt you to merge the
+>   sections below into the appropriate places in your existing
+>   `CLAUDE.md`. No auto-merge — you keep editorial control.
+
+The snippet follows the Dflow `templates/CLAUDE.md` H2 segmentation
+(established in PROPOSAL-007c): **System Context** (what the system is)
+and **Development Workflow** (how we work). Keep those two H2 sections as the backbone
+when merging into an existing `CLAUDE.md`.
+
+---
+
+## Snippet to merge into `CLAUDE.md`
+
+```markdown
+# Project: {系統名稱} — ASP.NET WebForms
+
+**重要：所有開發工作都必須遵循本文件定義的流程。**
+
+---
+
+## System Context
+
+> 技術棧、業務領域、目錄結構
+
+### Background
+
+這是一個運行中的 ASP.NET WebForms 系統，{一句話描述業務領域：例如
+「提供員工費用報銷」/「處理 HR 人事流程」/「訂單管理」}。採用 Dflow
+（SDD/DDD workflow guardian skill）引導開發流程，同時為未來遷移到
+ASP.NET Core 做準備。
+
+{選填：補上團隊規模、使用者規模、主要 stakeholders 等 context，
+1-3 行即可。完整內容放在 `dflow/specs/shared/_overview.md`。}
+
+### Project Structure
+
+```
+dflow/specs/
+├── shared/                   # 專案級治理文件（由 npx dflow-sdd-ddd init 寫入）
+│   ├── _overview.md          # 系統現況與遷移策略
+│   ├── _conventions.md       # 規格撰寫慣例
+│   └── Git-principles-*.md   # Git 規範（gitflow 或 trunk 版）
+├── domain/                   # 領域知識
+│   ├── glossary.md           # 術語表（Ubiquitous Language）
+│   └── {context}/            # 按 Bounded Context 分
+│       ├── context.md
+│       ├── models.md
+│       ├── rules.md
+│       └── behavior.md
+├── features/
+│   ├── active/
+│   │   └── {SPEC-ID}-{slug}/
+│   │       ├── _index.md
+│   │       ├── phase-spec-YYYY-MM-DD-{slug}.md
+│   │       └── lightweight-YYYY-MM-DD-{slug}.md
+│   ├── completed/
+│   └── backlog/
+└── migration/
+    └── tech-debt.md
+
+src/
+├── Domain/                   # 抽離的領域邏輯（純 C#）
+│   ├── {BoundedContext}/
+│   └── SharedKernel/
+└── Pages/                    # 既有 WebForms 頁面
+```
+
+---
+
+## Development Workflow
+
+> SDD 流程、Git 整合、Domain 層規範、術語表、AI 協作
+
+### Core Principles
+
+1. **Spec Before Code** — 沒有規格就不寫實作（依 Ceremony Scaling 調整嚴謹度）
+2. **Domain Extraction** — 業務邏輯屬於 `src/Domain/`，不屬於 Code-Behind
+3. **Ubiquitous Language** — 使用 `dflow/specs/domain/glossary.md` 中定義的術語
+4. **Migration Awareness** — 每個決策都要考慮未來 ASP.NET Core 遷移
+
+### Dflow Skill — Canonical Decision Logic Lives in the Skill
+
+AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
+（T1/T2/T3）、各 `/dflow:` 命令的具體流程，**全部定義於 Dflow skill
+本體**（`sdd-ddd-webforms-skill/SKILL.md` 與 `references/*.md`）。
+本 `CLAUDE.md` 不重述這些內容，避免雙份維護。
+
+當你作為 AI assistant 被呼叫時，若偵測到使用者需要 SDD/DDD 工作流
+引導，請參考 Dflow entry points：
+
+- `npx dflow-sdd-ddd init` — 專案初始化（建立 `dflow/specs/` 結構）
+- `/dflow:new-feature` — 新功能開發
+- `/dflow:new-phase` — 在 active feature 內新增階段
+- `/dflow:modify-existing` — 修改既有功能
+- `/dflow:bug-fix` — 輕量修復
+- `/dflow:finish-feature` — feature 收尾
+- `/dflow:pr-review` — PR 審查
+- `/dflow:verify` — rules.md ↔ behavior.md 漂移檢查
+- `/dflow:status` / `/dflow:next` / `/dflow:cancel` — 狀態管理
+
+### Project-Level Supplemental Rules
+
+（本 `CLAUDE.md` 只記這一層——Dflow skill 不管的專案決策）
+
+- **Git 分支策略**：見 `dflow/specs/shared/Git-principles-{gitflow|trunk}.md`
+- **規格撰寫慣例**：見 `dflow/specs/shared/_conventions.md`
+- **系統現況與遷移**：見 `dflow/specs/shared/_overview.md`
+- {其他專案特有規則，例如「JPY 金額必須以最小貨幣單位（yen）儲存」/
+  「所有費用報銷需主管審核」/「跨時區行程以 UTC 記錄」}
+
+### Domain Layer Rules (`src/Domain/`)
+
+此目錄中的程式碼必須遵守（與 Dflow skill 的 Domain Layer Rules 一致）：
+
+- ❌ 不可引用 `System.Web` 或任何 WebForms 命名空間
+- ❌ 不可直接存取資料庫（使用 interface + Repository pattern）
+- ❌ 不可使用 `HttpContext`、`Session`、`ViewState`
+- ❌ 不可有 UI 相關邏輯
+- ✅ 純 C# 類別，可直接搬到 ASP.NET Core 專案
+- ✅ 所有公開行為都能在沒有 Web 基礎設施的情況下測試
+
+### AI Collaboration Notes
+
+- 遇到開發需求時，優先引導使用 `/dflow:` 命令
+- 回答 Domain 相關問題時，優先參考 `dflow/specs/domain/` 中的文件
+- 發現 Code-Behind 中的業務邏輯時，建議抽離到 `src/Domain/`
+- 建立分支前，確認命名符合規範且對應 spec 存在
+- 詳細 Git 操作規則見 `dflow/specs/shared/Git-principles-{gitflow|trunk}.md`
+```
+
+---
+
+## Merge Guidance
+
+When merging this snippet into an existing `CLAUDE.md`:
+
+1. **Keep the two H2 sections** (`System Context` / `Development Workflow`) as the
+   backbone. This alignment with the Dflow skill's
+   `templates/CLAUDE.md` is important — AI assistants navigate by
+   these headings.
+2. **Under `System Context`**: merge the background paragraph and the
+   directory tree. If your project already documents directory
+   structure elsewhere, keep the tree pointing to `dflow/specs/` and
+   `src/Domain/` at minimum (those are Dflow-specific).
+3. **Under `Development Workflow`**: merge the core principles, the Dflow skill
+   pointer, and the project-level supplementary rules. The Domain
+   layer rules and AI collaboration rules can be kept here or
+   cross-referenced from the scaffolding `Git-principles-*.md`.
+4. **Avoid duplication**: do not re-inline the Dflow skill's decision
+   tree, Workflow Transparency rules, or Ceremony Scaling criteria
+   into `CLAUDE.md`. Let `CLAUDE.md` point to the skill, not
+   duplicate it.
+
+If you are starting from scratch (no existing `CLAUDE.md`), the
+`npx dflow-sdd-ddd init` flow will install this snippet as-is and you
+can refine from there.