dflow-sdd-ddd 0.2.0 → 0.4.0

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

@@ -14,9 +14,9 @@
 
 ## How to use this snippet
 
-- New `npx dflow-sdd-ddd init` output uses
-  `dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical guide and creates
-  a thin `CLAUDE.md` shim that points back to it.
+- New Dflow CLI init output (`dflow init`, or `npx dflow-sdd-ddd init` when
+  using the no-install path) uses `dflow/specs/shared/AI-AGENT-GUIDE.md` as
+  the canonical guide and creates a thin `CLAUDE.md` shim that points back to it.
 - Use this legacy snippet only if you intentionally want the older
   Claude-specific two-H2 layout in your project's root `CLAUDE.md`.
 
@@ -29,7 +29,7 @@ keeps every project's `CLAUDE.md` scannable for AI in the same shape.
 ## Snippet to merge into `CLAUDE.md`
 
 ```markdown
-# Project: {系統名稱} — ASP.NET Core + DDD
+# Project: {系統名稱} — Clean Architecture + DDD
 
 **重要：所有開發工作都必須遵循本文件定義的流程。**
 
@@ -45,8 +45,8 @@ keeps every project's `CLAUDE.md` scannable for AI in the same shape.
 - **Users / Customers**: {使用者 / 客戶描述}
 - **Team**: {團隊組成；e.g. "全端工程團隊，3-5 人；DDD 經驗中等"}
 - **Dflow Adoption Context**: {新專案 greenfield / 既有系統導入 / 遷移等}
-- **Tech Stack**: ASP.NET Core {版本}；EF Core / MediatR / {其他};
-  .NET {版本}
+- **Tech Stack**: {Framework} {Framework version}；{ORM / persistence} {ORM version} / {Mediator} / {其他};
+  {Language}
 
 ### Architecture (Clean Architecture)
 
@@ -60,13 +60,13 @@ Presentation → Application → Domain ← Infrastructure
 |---|---|---|
 | Domain | 業務規則、Aggregate、Value Object、Domain Event | 依賴外部套件、存取資料庫、處理 HTTP |
 | Application | 編排領域操作、CQRS、驗證、DTO | 包含業務邏輯、直接存取資料庫 |
-| Infrastructure | EF Core、外部 API、檔案存取 | 包含業務邏輯 |
+| Infrastructure | {ORM / persistence}、外部 API、檔案存取 | 包含業務邏輯 |
 | Presentation | HTTP 端點、Request/Response | 包含業務邏輯、直接操作 Domain 物件 |
 
 ### Project Structure
 
 完整 specs 目錄結構見 Dflow skill `SKILL.md` § "Project Structure"。
-以下只列本專案當前狀態（`npx dflow-sdd-ddd init` 建立後可能還未全填）：
+以下只列本專案當前狀態（Dflow CLI init 建立後可能還未全填）：
 
 ```
 dflow/specs/
@@ -101,7 +101,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - `sdd-ddd-greenfield-skill/references/` 內各 flow 文件
 
 本專案採用的 Dflow entry points：
-- `npx dflow-sdd-ddd init` — 專案初始化（一次性，已執行過）
+- Dflow CLI init command (`dflow init`, or `npx dflow-sdd-ddd init` when using the no-install path) — 專案初始化（一次性，已執行過）
 - `/dflow:new-feature` — 新功能
 - `/dflow:new-phase` — 既有 active feature 加新 phase
 - `/dflow:modify-existing` — 修改既有行為
@@ -120,7 +120,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 
 ### Domain Layer Rules (Hard Invariants)
 
-- ❌ 不可有任何 NuGet 套件依賴（純 .NET 類型）
+- ❌ 不可有任何外部套件依賴（語言純粹 types）
 - ❌ 不可有 ORM 屬性（`[Table]`、`[Column]` 等）
 - ❌ 不可有序列化屬性（`[JsonProperty]` 等）
 - ❌ 不可有 `DbContext`、`IConfiguration`、`HttpClient`
@@ -133,7 +133,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 
 {此段由專案自行填入。例如：}
 
-- **本專案使用 MediatR 做 Command / Query dispatch**，Application 層
+- **本專案使用 {Mediator} 做 Command / Query dispatch（若適用）**，Application 層
   Command / Query Handler 命名為 `{Name}CommandHandler` /
   `{Name}QueryHandler`
 - **整合測試使用 {Testcontainers / WebApplicationFactory / 其他}**；
@@ -165,5 +165,6 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - 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
-- Re-run `npx dflow-sdd-ddd init` will NOT overwrite an existing
-  `CLAUDE.md`; if you want to re-sync, merge manually
+- 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-gitflow.md

@@ -174,7 +174,7 @@ Before making key Git operations:
       `context-map.md` reflect the feature's net changes
 - [ ] `dflow/specs/domain/glossary.md` updated with any new terms
 - [ ] `dflow/specs/architecture/tech-debt.md` updated with any debt discovered
-- [ ] Domain project has zero external NuGet dependencies
+- [ ] Domain project has zero external package dependencies
 - [ ] No ORM / serialization attributes on Domain entities
 - [ ] Domain unit tests pass (invariants + value object equality)
 
@@ -334,7 +334,7 @@ exists, e.g. `.github/workflows/ci.yml` or `azure-pipelines.yml`.}
 
 ### Suggested CI gates for Clean Architecture
 
-- Verify Domain project has zero (or allow-listed) NuGet deps
+- Verify Domain project has zero (or allow-listed) external package deps
 - Run Domain unit tests + Application tests on every PR
 - Run Integration tests on `develop` and `release/*` branches
 - Verify EF migrations build cleanly

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

@@ -249,7 +249,7 @@ Before making key Git operations:
       `context-map.md` reflect the feature's net changes
 - [ ] `dflow/specs/domain/glossary.md` updated with any new terms
 - [ ] `dflow/specs/architecture/tech-debt.md` updated with any debt discovered
-- [ ] Domain project has zero external NuGet dependencies
+- [ ] Domain project has zero external package dependencies
 - [ ] No ORM / serialization attributes on Domain entities
 - [ ] Domain unit tests pass (invariants + value object equality)
 - [ ] CI is green (all required checks passing)
@@ -359,7 +359,7 @@ exists, e.g. `.github/workflows/ci.yml` or `azure-pipelines.yml`.}
 
 ### Suggested CI gates for Clean Architecture
 
-- Verify Domain project has zero (or allow-listed) NuGet deps
+- Verify Domain project has zero (or allow-listed) external package deps
 - Run Domain unit tests + Application tests on every PR
 - Run Integration tests on `main` and pre-deploy
 - Verify EF migrations build cleanly

package/templates/greenfield/scaffolding/_conventions.md

@@ -101,7 +101,7 @@ Project-specific guidance when filling these templates:
   descriptions (Mermaid state diagram or Given / When / Then + "And
   the Aggregate is in state X").
 - **CQRS split**: commands (write) vs queries (read) should be
-  identified during Phase 4 (Implementation Planning). Commands
+  identified during Activity 4 (Implementation Planning). Commands
   generally map 1:1 to an Aggregate method; queries bypass the
   Domain layer and read projections.
 

package/templates/greenfield/scaffolding/_overview.md

@@ -30,19 +30,18 @@ delivers. Keep it non-technical enough that a new hire can skim it in
 
 ## 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.
+This project follows **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} |
+| Language | {Language} |
+| Framework | {Framework} {Framework version} |
+| ORM / persistence | {ORM / persistence} {ORM version} |
+| Mediator | {Mediator} (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} |
@@ -57,13 +56,32 @@ 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 |
+| Domain | Aggregates, Entities, Value Objects, Domain Events, Domain Services, repository interfaces | Depend on package-manager libraries outside the project's allow-list; know about ORM/persistence frameworks, 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 |
+| Infrastructure | ORM / persistence configuration, 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
 
+> **Note**: The project layout below uses .NET/C# conventions —
+> project-level namespaces like `{Project}.Domain` and a separate `.csproj`
+> per layer. This is shown as a concrete example so you can see "what a
+> real Clean Architecture layout looks like".
+>
+> If this project's stack is **not** .NET, this layout does **not**
+> literally apply — translate to the conventions of your stack:
+>
+> - Java/Spring: `com.example.domain` / `com.example.application` packages, often a multi-module Maven/Gradle build
+> - Node/TypeScript: `src/domain/` / `src/application/` folders, monorepo workspaces optional
+> - Python: `domain/` / `application/` packages
+> - Go: `internal/domain/` / `internal/application/`
+> - PHP/Laravel: `app/Domain/` / `app/Application/`
+>
+> For full per-stack examples, see `docs/examples-by-stack.md`. If the
+> convention for your stack is unclear, consult authoritative sources
+> for the stack (e.g., its official project structure guide) or ask the
+> developer before placing code.
+
 ```
 src/
 ├── {Project}.Domain/
@@ -147,7 +165,7 @@ format / MADR / other}.
 Initial ADRs that typically exist:
 
 - **ADR-0001** — Choice of ORM / persistence approach
-- **ADR-0002** — CQRS + MediatR vs direct handlers
+- **ADR-0002** — CQRS + mediator/dispatcher vs direct handlers
 - **ADR-0003** — Auth strategy
 
 ---

package/templates/greenfield/templates/CLAUDE.md

@@ -1,4 +1,4 @@
-# Project: {系統名稱} — ASP.NET Core + DDD
+# Project: {系統名稱} — Clean Architecture + DDD
 
 **重要：所有開發工作都必須遵循本文件定義的流程。**
 
@@ -10,7 +10,7 @@
 
 ### Background
 
-這是一個使用 Clean Architecture 和 Domain-Driven Design 的 ASP.NET Core 系統。
+這是一個遵循 Clean Architecture 與 Domain-Driven Design 的新建專案；具體 stack 詳見 `dflow/specs/shared/_overview.md`。
 採用 SDD 流程，所有開發工作必須遵循本文件定義的流程。
 
 ### Architecture (Clean Architecture)
@@ -27,15 +27,15 @@ Presentation → Application → Domain ← Infrastructure
 |---|---|---|
 | Domain | 業務規則、Aggregate、Value Object、Domain Event | 依賴外部套件、存取資料庫、處理 HTTP |
 | Application | 編排領域操作、CQRS、驗證、DTO | 包含業務邏輯、直接存取資料庫 |
-| Infrastructure | EF Core、外部 API、檔案存取 | 包含業務邏輯 |
+| Infrastructure | {ORM / persistence}、外部 API、檔案存取 | 包含業務邏輯 |
 | Presentation | HTTP 端點、Request/Response | 包含業務邏輯、直接操作 Domain 物件 |
 
 ### Project Structure
 
 ```
 dflow/specs/
-├── shared/                   # 專案級治理文件（由 npx dflow-sdd-ddd init 寫入）
-│   ├── _overview.md          # 系統現況與遷移策略
+├── shared/                   # 專案級治理文件（由 dflow init 寫入）
+│   ├── _overview.md          # 系統概覽與架構方向
 │   └── _conventions.md       # 規格撰寫慣例
 ├── domain/
 │   ├── glossary.md
@@ -154,7 +154,7 @@ bugfix/{BUG-ID}-{short-description}      # Bug 修復（SDD 必須）
 
 ### Domain Layer Rules
 
-- ❌ 不可有任何 NuGet 套件依賴（純 .NET 類型）
+- ❌ 不可有任何外部套件依賴（語言純粹 types）
 - ❌ 不可有 ORM 屬性（[Table], [Column] 等）
 - ❌ 不可有序列化屬性（[JsonProperty] 等）
 - ❌ 不可有 DbContext、IConfiguration、HttpClient

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

@@ -19,17 +19,20 @@ Template note (for AI):
   `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
+  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:
+    Activity 1: Understanding (What & Why)
+    Activity 2: Domain Modeling (BC, Aggregate, VO, Events)
+    Activity 3: Spec Writing (Behavior + Rules + Edge Cases)
+    Activity 4: Implementation Planning (layer-by-layer)
+  The "Implementation Tasks" section at the end is generated by AI after Activity 4 (Implementation 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).
 
+  Note: "phase 2+ specs" / "Phase 2+" in the BR and Delta sections below refers to
+  the N-th phase-spec of this feature (i.e. iteration unit), NOT an activity number.
+
   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`
@@ -37,11 +40,11 @@ Template note (for AI):
   bounded context's `rules.md` / `behavior.md` (synced at /dflow:finish-feature).
 -->
 
-## Problem Description <!-- Fill timing: Phase 1 -->
+## Problem Description <!-- Fill timing: Activity 1: Understanding -->
 
 > 用使用者的角度描述，避免技術用語。
 
-## Domain Concepts <!-- Fill timing: Phase 2 -->
+## Domain Concepts <!-- Fill timing: Activity 2: Domain Modeling -->
 
 涉及的 Domain 概念（引用 `dflow/specs/domain/{context}/models.md`）：
 
@@ -55,7 +58,7 @@ Template note (for AI):
 - [ ] `dflow/specs/domain/{context}/events.md` — Domain Events
 
 <!-- dflow:section behavior-scenarios -->
-## Behavior Scenarios <!-- Fill timing: Phase 3 -->
+## Behavior Scenarios <!-- Fill timing: Activity 3: Spec Writing -->
 
 ### Main Success Scenario
 
@@ -76,7 +79,7 @@ Scenario: {替代情境}
   Then {不同結果}
 ```
 
-## Business Rules <!-- Fill timing: Phase 3 -->
+## Business Rules <!-- Fill timing: Activity 3: Spec Writing -->
 
 > Phase 2+ 注意：本段僅列**本 phase 新增 / 修改到的 BR**；未變動的 BR 不重抄
 > （它們的當前狀態見 feature 的 `_index.md` Current BR Snapshot 表）。
@@ -86,7 +89,7 @@ Scenario: {替代情境}
 | 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 -->
+## Delta from prior phases <!-- Fill timing: Activity 3: Spec Writing; skip for the first phase -->
 
 > 本段僅記**本 phase 相對前一 phase 的變化**，不累積歷史。歷史由 feature 目錄下
 > 各 phase-spec 的本段串接閱讀；feature 層的當前累積狀態見 `_index.md` 的
@@ -122,19 +125,19 @@ And {產生的 Domain Event}
 - BR-003 金額上限
 - BR-005 提交後不可修改
 
-## Edge Cases <!-- Fill timing: Phase 3 -->
+## Edge Cases <!-- Fill timing: Activity 3: Spec Writing -->
 
 | ID | Case | Expected Handling |
 |---|---|---|
 | EC-01 | {邊界描述} | {處理方式} |
 
-## Domain Events <!-- Fill timing: Phase 2-3; draft during design, finalized during spec writing -->
+## Domain Events <!-- Fill timing: Activity 2-3; draft during Domain Modeling, finalized during Spec Writing -->
 
 | Event | Trigger | Handler | Sync / Async |
 |---|---|---|---|
 | {EventName} | {何時觸發} | {Handler} | 同步/異步 |
 
-## Implementation Plan (Layer by Layer) <!-- Fill timing: Phase 4 -->
+## Implementation Plan (Layer by Layer) <!-- Fill timing: Activity 4: Implementation Planning -->
 
 ### Domain Layer
 > Aggregate 設計、Value Objects、Events、Interfaces
@@ -148,13 +151,13 @@ And {產生的 Domain Event}
 ### Presentation Layer
 > API Endpoint 設計、Request/Response 模型
 
-## Data Structure Changes <!-- Fill timing: Phase 4 -->
+## Data Structure Changes <!-- Fill timing: Activity 4: Implementation Planning -->
 
 | Table | Column | Change Type | Description |
 |---|---|---|---|
 | {Table} | {Column} | 新增/修改/刪除 | |
 
-## Test Strategy <!-- Fill timing: Phase 4 -->
+## Test Strategy <!-- Fill timing: Activity 4: Implementation Planning -->
 
 ### Domain Unit Tests
 - [ ] {不變條件測試}
@@ -169,14 +172,14 @@ And {產生的 Domain Event}
 - [ ] {Repository 測試}
 
 <!-- dflow:section open-questions -->
-## Open Questions <!-- Fill timing: Phase 1-4 -->
+## Open Questions <!-- Fill timing: Activity 1-4; any time during planning -->
 
 - {尚未釐清的需求、規則、資料或實作問題}
 
 <!-- dflow:section implementation-tasks -->
-## Implementation Tasks <!-- Fill timing: generated by AI after Phase 4; all items should be checked at completion -->
+## Implementation Tasks <!-- Fill timing: generated by AI after Activity 4: Implementation Planning; all items should be checked at completion -->
 
-> AI 在 Phase 4 實作規劃完成後，根據「Implementation Plan (Layer by Layer)」產生的具體任務清單。
+> AI 在 Activity 4 (Implementation Planning) 完成後，根據「Implementation Plan (Layer by Layer)」產生的具體任務清單。
 > 格式：`[LAYER]-[NUMBER]: 任務描述`
 > 分類標籤（Greenfield track，對應 Clean Architecture 各層）：
 >   - `DOMAIN` — Aggregate、Entity、VO、Domain Event、Domain Service、Repository Interface