dflow-sdd-ddd 0.1.0

package/templates/core/scaffolding/_overview.md

@@ -0,0 +1,165 @@
+<!-- Scaffolding template maintained alongside Dflow skill. See proposals/PROPOSAL-010 for origin. -->
+
+# System Overview — {System Name}
+
+> Created: {YYYY-MM-DD}
+> Scope: architectural overview and long-term direction of {System Name}.
+> Audience: team members onboarding to the system + AI assistants reading
+> `dflow/specs/` for context.
+
+This file is a **project-level starting point**. It does not duplicate
+Dflow's workflow rules (see `CLAUDE.md` and the Dflow skill for those) —
+it captures the unique context of *this* system so that new engineers (or
+AI) can quickly understand what they are working on.
+
+---
+
+## System Summary
+
+{One paragraph: what this system does, who uses it, what business value it
+delivers. Keep it non-technical enough that a new hire can skim it in
+30 seconds.}
+
+### Business Domain
+
+- **Primary domain**: {e.g. expense management, HR, order processing}
+- **Key stakeholders**: {e.g. finance team, HR admins, end-user employees}
+- **User scale**: {e.g. ~200 internal users, 5 countries}
+
+---
+
+## Technical Architecture
+
+This project is an ASP.NET Core application built with **Clean
+Architecture** and **Domain-Driven Design (DDD)**. Dependencies flow
+inward only — the Domain layer is the core and depends on nothing.
+
+### Stack
+
+| Item | Choice |
+|------|--------|
+| Runtime | .NET {version, e.g. 8} |
+| Language | C# {version, e.g. 12} |
+| Web framework | ASP.NET Core (Web API / Minimal API — {which}) |
+| ORM | Entity Framework Core {version} |
+| Mediator | {e.g. MediatR, internal CQRS dispatcher, or none} |
+| Validation | {e.g. FluentValidation} |
+| Database | {e.g. PostgreSQL 16, SQL Server 2022} |
+| Auth | {e.g. JWT bearer, OIDC via Azure AD, cookie auth} |
+| Hosting | {e.g. Azure App Service, Kubernetes, Docker compose} |
+| Testing | {e.g. xUnit + FluentAssertions + NSubstitute} |
+
+### Clean Architecture Layers
+
+```
+Presentation  →  Application  →  Domain  ←  Infrastructure
+```
+
+| Layer | Responsibilities | Must NOT |
+|-------|------------------|----------|
+| Domain | Aggregates, Entities, Value Objects, Domain Events, Domain Services, repository interfaces | Depend on any NuGet package outside allowed list; know about EF Core, HTTP, DI containers |
+| Application | Commands / Queries (CQRS), Validators, DTOs, Event Handlers, orchestration | Contain business logic; access database directly |
+| Infrastructure | EF Core `DbContext` + configurations, repository implementations, external API clients | Contain business logic |
+| Presentation | HTTP endpoints, Request / Response mapping, auth + middleware | Contain business logic; expose Domain objects directly |
+
+### Project Layout
+
+```
+src/
+├── {Project}.Domain/
+│   ├── Common/                # Entity, AggregateRoot, ValueObject base classes
+│   ├── {BoundedContext}/
+│   │   ├── Entities/
+│   │   ├── ValueObjects/
+│   │   ├── Events/
+│   │   ├── Services/
+│   │   ├── Specifications/
+│   │   └── Interfaces/        # Repository / external service interfaces
+│   └── SharedKernel/
+├── {Project}.Application/
+│   ├── Common/                # Pipeline behaviors, interfaces (IUnitOfWork, ...)
+│   └── {BoundedContext}/
+│       ├── Commands/
+│       ├── Queries/
+│       ├── DTOs/
+│       └── EventHandlers/
+├── {Project}.Infrastructure/
+│   ├── Persistence/           # DbContext + EF Core configurations
+│   ├── Repositories/
+│   └── ExternalServices/
+└── {Project}.WebAPI/          # Presentation layer
+
+tests/
+├── {Project}.Domain.UnitTests/
+├── {Project}.Application.UnitTests/
+└── {Project}.Integration.Tests/
+```
+
+---
+
+## Bounded Contexts (Current Map)
+
+{List the current Bounded Contexts in this system. Each entry: name +
+one-line responsibility + link to its `dflow/specs/domain/{context}/` folder.
+If only one BC exists at adoption time, that is fine — the map grows.}
+
+- **{Context A}** — {responsibility}. See
+  [`dflow/specs/domain/{context-a}/`](../domain/{context-a}/).
+- **{Context B}** — {responsibility}. See
+  [`dflow/specs/domain/{context-b}/`](../domain/{context-b}/).
+
+Full context relationships (upstream / downstream, shared kernel,
+anti-corruption layer) are documented in
+[`dflow/specs/domain/context-map.md`](../domain/context-map.md).
+
+---
+
+## Principles This Project Adopts
+
+Clean Architecture + DDD is more than a folder layout; the team commits
+to the following design habits. Expand / adapt each to this project:
+
+- **Domain at the Center** — Business rules live in `*.Domain`. If you
+  find business logic in `*.Application` handlers or (worse) in
+  controllers, raise a tech-debt entry.
+- **Aggregate Boundaries** — Each transaction modifies exactly one
+  Aggregate. Cross-aggregate workflows go through Domain Events.
+- **Dependency Inversion** — The Domain declares interfaces; the
+  Infrastructure layer implements them. No Domain code imports
+  `Microsoft.EntityFrameworkCore`.
+- **Ubiquitous Language** — Class / method / variable names come from
+  `dflow/specs/domain/glossary.md`. When business language evolves, the
+  glossary moves first, code follows.
+- **Pragmatic First** — We do not gold-plate. If a feature needs a
+  quick fix, record the debt in `dflow/specs/architecture/tech-debt.md` and
+  ship.
+
+---
+
+## Architecture Decision Records (ADRs)
+
+Significant architectural choices are recorded as ADRs under
+`dflow/specs/architecture/decisions/`. Each ADR captures: decision, context,
+alternatives considered, consequences. See the `decisions/` folder's
+README (if present) or the ADR convention in {Michael Nygard's ADR
+format / MADR / other}.
+
+Initial ADRs that typically exist:
+
+- **ADR-0001** — Choice of ORM / persistence approach
+- **ADR-0002** — CQRS + MediatR vs direct handlers
+- **ADR-0003** — Auth strategy
+
+---
+
+## Related Documents
+
+- [Spec conventions](_conventions.md)
+- [Git principles](Git-principles-{gitflow|trunk}.md) — choose the
+  branching-strategy-specific file that matches this project
+- [Context map](../domain/context-map.md)
+- [Glossary](../domain/glossary.md)
+- [Tech debt backlog](../architecture/tech-debt.md)
+- [Architecture decisions](../architecture/decisions/)
+- Dflow skill: see `CLAUDE.md` and the `sdd-ddd-core-skill/` bundle
+  for the full AI workflow guidance.

package/templates/core/scaffolding/architecture-decisions-README.md

@@ -0,0 +1,34 @@
+<!-- Template maintained by Dflow. See proposals/PROPOSAL-013 for origin. -->
+
+# Architecture Decisions
+
+This directory stores Architecture Decision Records (ADRs) for decisions that affect architecture, bounded contexts, cross-cutting policies, integrations, or long-term maintainability.
+
+## ADR Naming Convention
+
+Use a stable numeric prefix and a short kebab-case title:
+
+```text
+ADR-0001-short-decision-title.md
+ADR-0002-another-decision.md
+```
+
+## When To Write An ADR
+
+Write an ADR when a decision:
+
+- Changes architectural boundaries, dependency direction, or layer responsibilities.
+- Introduces or rejects a major technology, integration pattern, persistence strategy, or deployment approach.
+- Creates a trade-off that future maintainers need to understand.
+- Resolves a recurring design debate that should not be reopened without new evidence.
+
+## Minimal ADR Fields
+
+Each ADR should include:
+
+- **Status**: proposed / accepted / superseded / deprecated
+- **Date**: YYYY-MM-DD
+- **Context**: the forces, constraints, and problem being addressed
+- **Decision**: the chosen approach
+- **Consequences**: expected benefits, trade-offs, and follow-up work
+- **Related Specs / BR-IDs**: links to relevant specs, rules, or implementation references

package/templates/core/templates/CLAUDE.md

@@ -0,0 +1,172 @@
+# Project: {系統名稱} — ASP.NET Core + DDD
+
+**重要：所有開發工作都必須遵循本文件定義的流程。**
+
+---
+
+## System Context
+
+> 技術棧、架構、業務領域、目錄結構
+
+### Background
+
+這是一個使用 Clean Architecture 和 Domain-Driven Design 的 ASP.NET Core 系統。
+採用 SDD 流程，所有開發工作必須遵循本文件定義的流程。
+
+### Architecture (Clean Architecture)
+
+```
+Presentation → Application → Domain ← Infrastructure
+```
+
+依賴方向永遠朝內。Domain 層是核心，不依賴任何外部套件。
+
+**各層職責**
+
+| 層 | 職責 | 不可以做的事 |
+|---|---|---|
+| Domain | 業務規則、Aggregate、Value Object、Domain Event | 依賴外部套件、存取資料庫、處理 HTTP |
+| Application | 編排領域操作、CQRS、驗證、DTO | 包含業務邏輯、直接存取資料庫 |
+| Infrastructure | EF Core、外部 API、檔案存取 | 包含業務邏輯 |
+| Presentation | HTTP 端點、Request/Response | 包含業務邏輯、直接操作 Domain 物件 |
+
+### Project Structure
+
+```
+dflow/specs/
+├── shared/                   # 專案級治理文件（由 npx dflow-sdd-ddd init 寫入）
+│   ├── _overview.md          # 系統現況與遷移策略
+│   └── _conventions.md       # 規格撰寫慣例
+├── domain/
+│   ├── glossary.md
+│   ├── context-map.md
+│   └── {context}/
+│       ├── context.md
+│       ├── models.md
+│       ├── rules.md
+│       └── events.md          # Domain Events 目錄
+├── 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 寫一列
+└── architecture/
+    ├── decisions/              # ADR
+    └── tech-debt.md
+
+src/
+├── {Project}.Domain/
+├── {Project}.Application/
+├── {Project}.Infrastructure/
+└── {Project}.WebAPI/
+
+tests/
+├── Domain.UnitTests/
+├── Application.UnitTests/
+└── Integration.Tests/
+```
+
+---
+
+## Development Workflow
+
+> SDD 流程、Git 整合、Domain 層規範、AI 協作
+
+### Core Principles
+1. **Spec Before Code** — 沒有規格就不寫實作
+2. **Domain at the Center** — 業務邏輯只存在於 Domain 層
+3. **Ubiquitous Language** — 使用 `dflow/specs/domain/glossary.md` 中定義的術語
+4. **One Aggregate per Transaction** — 單一操作只修改一個 Aggregate
+5. **Dependency Inversion** — Domain 定義介面，Infrastructure 實作
+
+### Three Ceremony Tiers
+
+不是每次修改都要跑完整流程。AI 依下列判準選 tier：
+
+- **T1 Heavy** — 新功能、新 phase、新 Aggregate / BC、新增 BR、新 Domain Event →
+  建獨立 phase-spec，走 `/dflow:new-feature` 或 `/dflow:new-phase`
+- **T2 Light** — bug fix（邏輯錯誤）、UI 輸入驗證、流程分支修改（有 BR Delta
+  但無 Aggregate / 資料結構動）→ 建獨立 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. 設計 Aggregate（不變條件、狀態變更方法、Domain Events）
+4. 實作順序：Domain → Application → Infrastructure → Presentation
+5. 撰寫測試：Domain 單元測試 → Application 測試 → 整合測試
+
+### 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. 確認 fix 在正確的 Clean Architecture 層
+
+### Bug Fix
+1. 建立輕量規格
+2. 若 bug 不附掛既有 feature，先建最小 feature 目錄再放 lightweight-spec
+3. 找到問題所在的層
+4. 在正確的層修復
+
+### Feature Closeout
+1. 驗證 feature 目錄內所有 phase-spec `status: completed`
+2. 把 `_index.md` Current BR Snapshot 同步到 BC 層 `rules.md` /
+   `behavior.md` / `events.md` / `context-map.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] 簡述變更
+```
+
+> `/dflow:bug-fix` 不綁定任何分支策略；採 Git Flow 的專案可選擇把緊急修復
+> 放在 `hotfix/` 分支，但這是專案決策，Dflow 不代為規定。
+
+### Domain Layer Rules
+
+- ❌ 不可有任何 NuGet 套件依賴（純 .NET 類型）
+- ❌ 不可有 ORM 屬性（[Table], [Column] 等）
+- ❌ 不可有序列化屬性（[JsonProperty] 等）
+- ❌ 不可有 DbContext、IConfiguration、HttpClient
+- ✅ Entity 使用 private setter，透過方法改變狀態
+- ✅ Value Object 使用 record，建構式驗證
+- ✅ Aggregate Root 管理 DomainEvents 集合
+- ✅ 其他 Aggregate 只透過 ID 引用
+
+### AI Collaboration Notes
+
+- 開發者提出任何需求時，先引導建立 spec 和 Aggregate 設計
+- 確認實作順序：Domain → Application → Infrastructure → Presentation
+- 發現業務邏輯在錯誤的層時，指出並建議搬移
+- 每次開發循環結束時，提醒更新術語表、models.md、events.md
+- Review 時檢查 Domain 層的純淨度（零外部依賴）

package/templates/core/templates/_index.md

@@ -0,0 +1,118 @@
+---
+spec-id: SPEC-{YYYYMMDD}-{NNN}
+slug: {slug-following-discussion-language}
+status: in-progress    # in-progress | completed
+created: {YYYY-MM-DD}
+branch: feature/{SPEC-ID}-{slug}
+# follow-up-of: {原 SPEC-ID}    # 選用：本 feature 為某個已 completed feature 的 follow-up 時填入
+---
+
+<!--
+Template note (for AI):
+  This is the **feature-level dashboard** (`_index.md`) for a feature
+  directory. Place at `dflow/specs/features/active/{SPEC-ID}-{slug}/_index.md`.
+
+  Six required sections (see below):
+    1. Metadata (YAML front matter above)
+    2. Goals & Scope (prose)
+    3. Phase Specs (T1 list)
+    4. Current BR Snapshot (feature-level cumulative state)
+    5. Lightweight Changes (T2 outbound link + T3 inline)
+    6. Resume Pointer
+
+  Optional section (append at end if applicable):
+    - Follow-up Tracking (when this feature has follow-up features derived)
+
+  Refresh discipline for "Current BR Snapshot":
+    - Regenerate when /dflow:new-phase enters
+    - Regenerate when a phase-spec is finalized (completed)
+    - Regenerate when a T2 lightweight-spec is finalized
+    - This table is the feature-level CURRENT STATE (not history).
+      History lives in each phase-spec's "Delta from prior phases" section.
+
+  Sync to BC layer:
+    - At /dflow:finish-feature, BR Snapshot is reconciled with the bounded
+      context's `dflow/specs/domain/{context}/rules.md` and `behavior.md`
+      (continues the existing Step 8.3 / Step 5.3 sync mechanism — no new
+      flow is introduced).
+    - rules.md is the SYSTEM-LEVEL truth across features; _index.md is the
+      FEATURE-LEVEL aggregation. Both can co-exist; on conflict, finish-feature
+      reconciles them and rules.md wins as the system truth.
+
+  Minimal usage:
+    For a 1-commit / 1-phase feature this template can be ~30 lines —
+    fill metadata + a short Goals & Scope + one row in Phase Specs +
+    initial BR Snapshot + Resume Pointer. The other sections can stay empty.
+-->
+
+# {Feature Title}
+
+## Goals & Scope
+
+> 1-3 段：本 feature 解決什麼問題？為誰解決？邊界在哪？涉及哪些 Bounded
+> Context / Aggregate？
+>
+> 若是 follow-up feature，AI 會在頂部自動加註：
+> 「本 feature 為 `{原 SPEC-ID}-{原 slug}` 的 follow-up，原 feature 完成於
+>  `{date}`，詳見 `completed/{原 SPEC-ID}-{原 slug}/_index.md`」
+
+## Phase Specs
+
+> T1 Heavy ceremony 產出的 phase-spec 列表（一份 phase-spec ≈ 一次完整
+> Kickoff → Domain → Design → Build → Verify 循環）。
+
+| Phase | Date | Slug | Status | File Link |
+|---|---|---|---|---|
+| 1 | {YYYY-MM-DD} | {phase-slug} | in-progress / completed | [phase-spec-{date}-{phase-slug}.md](./phase-spec-{date}-{phase-slug}.md) |
+
+<!-- dflow:section current-br-snapshot -->
+## Current BR Snapshot
+
+> Feature 層的 BR 當前狀態（不是歷史）。AI 在以下時機 regenerate 本表：
+> - `/dflow:new-phase` 進入時
+> - 完成一份 phase-spec 時
+> - T2 lightweight spec 定稿時
+>
+> 歷史由各 phase-spec 的「Delta from prior phases」段串接閱讀；feature
+> 完成時 `/dflow:finish-feature` 把本表推進到對應 BC 的 `rules.md` /
+> `behavior.md`（延續 Step 5.3 既有 sync 機制）。
+
+| BR-ID | Current Rule | First Seen (phase) | Last Updated (phase) | Status |
+|---|---|---|---|---|
+| BR-01 | {規則描述} | phase-1 / inherited from rules.md | phase-N | active / removed |
+
+<!-- dflow:section lightweight-changes -->
+## Lightweight Changes
+
+> T2 行：描述含「見 `lightweight-{date}-{slug}.md`」外連
+> T3 行：inline 完整描述一句話 + 標籤（如 `[cosmetic]` / `[text]` /
+>        `[format]`）；T3 不產獨立 spec 檔
+>
+> Tier 判準見 SKILL.md § Ceremony Scaling 三層表。
+
+| Date | Tier | Description | Commit |
+|---|---|---|---|
+| {YYYY-MM-DD} | T2 | bug fix XYZ — 見 [`lightweight-{date}-{slug}.md`](./lightweight-{date}-{slug}.md) | {hash} |
+| {YYYY-MM-DD} | T3 | 按鈕顏色從藍改綠 `[cosmetic]` | {hash} |
+
+## Resume Pointer
+
+> 一句話：目前進展到哪？下一個動作是什麼？
+> 開新對話接續工作時，從這裡讀起。
+
+**Current Progress**: {one-line summary}
+
+**Next Action**: {suggested next action}
+
+<!--
+## Follow-up Tracking
+>（選用段；只有當本 feature 衍生出 follow-up feature 時才填）
+> 由 `/dflow:new-feature` / `/dflow:modify-existing` 在新建 follow-up
+> feature 時自動更新；新 feature 完成時 `/dflow:finish-feature` 反向更新
+> 該列 Status 欄為 `completed`。
+> 連結權威是新 feature 的 `follow-up-of` 欄；本表為衍生索引。
+
+| SPEC-ID | slug | Created | Status |
+|---|---|---|---|
+| SPEC-{YYYYMMDD}-{NNN} | {slug} | {YYYY-MM-DD} | in-progress / completed |
+-->

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

@@ -0,0 +1,58 @@
+---
+aggregate: {AggregateName}
+bounded-context: {ContextName}
+created: {YYYY-MM-DD}
+---
+
+# {AggregateName} Aggregate
+
+## Purpose
+
+> 這個 Aggregate 代表什麼業務概念？一句話描述。
+
+## Invariants
+
+> 必須永遠為真的規則。這是 Aggregate 存在的理由。
+
+| ID | Invariant | Behavior on Violation |
+|---|---|---|
+| INV-01 | {必須為真的條件} | 拋出 DomainException |
+| INV-02 | {必須為真的條件} | 拋出 DomainException |
+
+## Structure
+
+```
+{AggregateName} (Aggregate Root)
+├── {ChildEntity}       (Entity)
+├── {ValueObject1}      (Value Object)
+└── {ValueObject2}      (Value Object)
+```
+
+## Aggregate Root
+
+| Property | Type | Description |
+|---|---|---|
+| Id | {AggregateName}Id | 唯一識別 |
+| {Property} | {Type} | {說明} |
+
+## State Transition Methods
+
+| Method | Preconditions | Postconditions | Domain Event |
+|---|---|---|---|
+| {MethodName}() | {必須滿足什麼} | {狀態如何改變} | {EventName} |
+
+## Domain Events
+
+| Event | Trigger | Consumer |
+|---|---|---|
+| {EventName} | {觸發條件} | {處理者或 Context} |
+
+## Referenced Aggregates (ID only)
+
+| Aggregate | Reference Type | Purpose |
+|---|---|---|
+| {OtherAggregate} | {OtherAggregate}Id | {為什麼需要引用} |
+
+## Design Decisions
+
+> 為什麼 Aggregate 的邊界劃在這裡？有沒有考慮過其他方案？

package/templates/core/templates/behavior.md

@@ -0,0 +1,62 @@
+# {Bounded Context} — Behavior Specification
+
+> **Purpose**: Consolidated source of truth for this context's current behavior.
+> Unlike `dflow/specs/features/completed/` (historical archive), this file always reflects
+> the **current** system behavior — what the system does right now.
+>
+> **Maintenance**: AI updates this file during the completion flow (Step 8.3 / Step 5.3).
+> When a feature is completed, merge its Given/When/Then scenarios here.
+> When behavior is modified, update the corresponding section using the Delta result
+> (not the Delta markup — merge the final state).
+>
+> **Relationship to rules.md**: `rules.md` is the declarative index (BR-ID + one-line summary).
+> This file is the scenario-level detail. Each BR-ID in `rules.md` should have a
+> corresponding section here. If they drift, `/dflow:verify` will catch it.
+
+---
+
+<!-- dflow:section behavior-scenarios -->
+## {Feature Area 1}
+
+### BR-001: {Rule Name}
+
+Given {Aggregate in initial state}
+When {Command is issued / Aggregate method is called}
+Then {Aggregate transitions to new state}
+And {Domain Event is raised}
+
+### BR-002: {Rule Name}
+
+Given {Aggregate in initial state}
+When {Command is issued}
+Then {expected result}
+
+#### Edge cases
+
+- EC-001: Given {edge case state} When {action} Then {handling}
+
+---
+
+## {Feature Area 2}
+
+### BR-003: {Rule Name}
+
+Given {Aggregate state}
+When {Command}
+Then {new state}
+And {Domain Event}
+
+---
+
+<!-- 
+Maintenance notes:
+- Organize by feature area, not by spec ID (specs are transient; behavior areas are stable)
+- When merging a completed spec, place its scenarios under the matching feature area
+- When a MODIFIED delta changes a rule, update the scenario here to reflect the NEW behavior
+  (git history preserves the old version — don't keep "原本/改為" pairs here)
+- When a REMOVED delta drops a rule, delete the corresponding section
+- When a RENAMED delta renames a concept, update all references in this file
+- Keep BR-IDs in sync with rules.md
+- Include Aggregate state transitions and Domain Events in each scenario
+  (this is what /dflow:pr-review Step 0 reads to understand intent)
+-->

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

@@ -0,0 +1,64 @@
+---
+context: {ContextName}
+chinese-name: {中文名稱}
+owner: {負責的開發者或團隊}
+created: {YYYY-MM-DD}
+---
+
+# {ContextName} Bounded Context
+
+## Responsibilities
+
+> 這個 Context 負責什麼？用 2-3 句話描述。
+
+## Boundaries
+
+### In Scope
+- {職責 1}
+- {職責 2}
+
+### Out of Scope
+- {排除項 1} → 由 {OtherContext} 處理
+- {排除項 2} → 由 {OtherContext} 處理
+
+## Core Domain Models
+
+> 詳細定義在 `models.md`，這裡只列出概覽。
+
+### Aggregates
+- **{AggregateName}** — {一句話描述}
+
+### Entities
+- **{EntityName}** — {一句話描述}
+
+### Value Objects
+- **{VOName}** — {一句話描述}
+
+### Domain Services
+- **{ServiceName}** — {一句話描述}
+
+### Repository Interfaces
+- **{RepositoryName}** — {一句話描述}
+
+## Interactions with Other Contexts
+
+| Other Context | Interaction Type | Description |
+|---|---|---|
+| {OtherContext} | 呼叫 / 事件 / 共享資料 | {描述} |
+
+## Key Business Rules
+
+> 規則索引在 `rules.md`（BR-ID + 一行摘要），完整 Behavior Scenarios 在 `behavior.md`（Given/When/Then）。這裡只列最重要的幾條。
+
+1. {最重要的規則}
+2. {第二重要的規則}
+
+## Code Mapping
+
+### Current Implementation
+- Domain: `src/{Project}.Domain/{Context}/`
+- Application: `src/{Project}.Application/{Context}/`
+- Infrastructure: `src/{Project}.Infrastructure/`
+
+### Architecture Notes
+- 依 Clean Architecture dependency direction 維持 Domain 純淨。