dflow-sdd-ddd 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "dflow-sdd-ddd",
+  "version": "0.1.0",
+  "description": "Dflow SDD/DDD project scaffolding CLI",
+  "type": "commonjs",
+  "bin": {
+    "dflow": "bin/dflow.js",
+    "dflow-sdd-ddd": "bin/dflow.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "README.md"
+  ],
+  "keywords": [
+    "sdd",
+    "ddd",
+    "specification-driven-development",
+    "domain-driven-design",
+    "codex",
+    "claude-code"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/weilung/AI-Guided-SDD-DDD-Development-Skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/weilung/AI-Guided-SDD-DDD-Development-Skills/issues"
+  },
+  "homepage": "https://github.com/weilung/AI-Guided-SDD-DDD-Development-Skills#readme",
+  "scripts": {
+    "test": "node test/smoke.mjs"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,168 @@
+<!-- Scaffolding template maintained alongside Dflow skill. See proposals/PROPOSAL-010 for origin. -->
+
+# CLAUDE.md Snippet — Dflow Adoption (Core edition)
+
+> 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 Core skill, the full reference template lives at
+> `sdd-ddd-core-skill/templates/CLAUDE.md` — if you want the complete
+> version, use that instead. This snippet is a lighter starting point.
+
+---
+
+## How to use this snippet
+
+- **If your project has no `CLAUDE.md`**: `npx dflow-sdd-ddd init` will
+  create one using this snippet as the base
+- **If your project already has a `CLAUDE.md`**: do NOT overwrite.
+  Merge the **two H2 blocks** below (`System Context` / `Development Workflow`) into your
+  existing file, preserving any project-specific content you already
+  have
+
+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.
+
+---
+
+## Snippet to merge into `CLAUDE.md`
+
+```markdown
+# Project: {系統名稱} — ASP.NET Core + DDD
+
+**重要：所有開發工作都必須遵循本文件定義的流程。**
+
+---
+
+## System Context
+
+> 技術棧、架構、業務領域、目錄結構
+
+### Background
+
+- **Business Domain**: {業務領域概述，e.g. "企業差旅費用申報與核銷"}
+- **Users / Customers**: {使用者 / 客戶描述}
+- **Team**: {團隊組成；e.g. "全端工程團隊，3-5 人；DDD 經驗中等"}
+- **Dflow Adoption Context**: {新專案 greenfield / 既有系統導入 / 遷移等}
+- **Tech Stack**: ASP.NET Core {版本}；EF Core / MediatR / {其他};
+  .NET {版本}
+
+### Architecture (Clean Architecture)
+
+```
+Presentation → Application → Domain ← Infrastructure
+```
+
+依賴方向永遠朝內。Domain 層是核心，不依賴任何外部套件。
+
+| Layer | Responsibilities | Must NOT |
+|---|---|---|
+| Domain | 業務規則、Aggregate、Value Object、Domain Event | 依賴外部套件、存取資料庫、處理 HTTP |
+| Application | 編排領域操作、CQRS、驗證、DTO | 包含業務邏輯、直接存取資料庫 |
+| Infrastructure | EF Core、外部 API、檔案存取 | 包含業務邏輯 |
+| Presentation | HTTP 端點、Request/Response | 包含業務邏輯、直接操作 Domain 物件 |
+
+### Project Structure
+
+完整 specs 目錄結構見 Dflow skill `SKILL.md` § "Project Structure"。
+以下只列本專案當前狀態（`npx dflow-sdd-ddd init` 建立後可能還未全填）：
+
+```
+dflow/specs/
+├── domain/
+│   ├── glossary.md
+│   ├── context-map.md
+│   └── {context}/  # 首個 bounded context 被 P007a 建立時會補齊
+│       ├── context.md
+│       ├── models.md
+│       ├── rules.md
+│       ├── behavior.md
+│       └── events.md
+├── features/{active,completed,backlog}/
+└── architecture/
+    ├── decisions/
+    └── tech-debt.md
+```
+
+---
+
+## Development Workflow
+
+> SDD 流程、Git 整合、Domain 層規範、AI 協作
+
+### Dflow Skill — Canonical Decision Logic Lives in the Skill
+
+AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
+（T1 Heavy / T2 Light / T3 Trivial）、所有 slash command 的 step-by-step
+流程 **不在此重述**，請以 Dflow skill 本體為準：
+
+- `sdd-ddd-core-skill/SKILL.md`（決策樹 + Slash Commands 總表）
+- `sdd-ddd-core-skill/references/` 內各 flow 文件
+
+本專案採用的 Dflow entry points：
+- `npx dflow-sdd-ddd init` — 專案初始化（一次性，已執行過）
+- `/dflow:new-feature` — 新功能
+- `/dflow:new-phase` — 既有 active feature 加新 phase
+- `/dflow:modify-existing` — 修改既有行為
+- `/dflow:bug-fix` — Bug 修復
+- `/dflow:finish-feature` — Feature 收尾 + 整合摘要
+- `/dflow:pr-review` — PR 審查檢查點
+
+### Core Principles (Project Reaffirmed)
+
+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 實作
+
+### Domain Layer Rules (Hard Invariants)
+
+- ❌ 不可有任何 NuGet 套件依賴（純 .NET 類型）
+- ❌ 不可有 ORM 屬性（`[Table]`、`[Column]` 等）
+- ❌ 不可有序列化屬性（`[JsonProperty]` 等）
+- ❌ 不可有 `DbContext`、`IConfiguration`、`HttpClient`
+- ✅ Entity 使用 `private set;`，透過方法改變狀態
+- ✅ Value Object 使用 `record`，建構式驗證
+- ✅ Aggregate Root 管理 `DomainEvents` 集合
+- ✅ 其他 Aggregate 只透過 ID 引用
+
+### Project-Level Supplemental Rules
+
+{此段由專案自行填入。例如：}
+
+- **本專案使用 MediatR 做 Command / Query dispatch**，Application 層
+  Command / Query Handler 命名為 `{Name}CommandHandler` /
+  `{Name}QueryHandler`
+- **整合測試使用 {Testcontainers / WebApplicationFactory / 其他}**；
+  CI 流程中自動跑
+- **{其他團隊協議}**
+
+### Git Branching Strategy
+
+本專案採用：{填寫 Git Flow / trunk-based / GitHub Flow / 自訂}
+詳見 `dflow/specs/shared/Git-principles-{gitflow|trunk}.md`。
+
+### AI Collaboration Notes
+
+- 開發者提出任何需求時，先引導建立 spec 和 Aggregate 設計
+- 確認實作順序：Domain → Application → Infrastructure → Presentation
+- 發現業務邏輯在錯誤的層時，指出並建議搬移
+- 每次開發循環結束時，提醒更新術語表、models.md、events.md
+- Review 時檢查 Domain 層的純淨度（零外部依賴）
+```
+
+---
+
+## Notes
+
+- This snippet is intentionally lighter than
+  `sdd-ddd-core-skill/templates/CLAUDE.md`. If you want the full version
+  (with detailed flow descriptions per slash command), use that
+  template instead
+- 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

package/templates/core/scaffolding/Git-principles-gitflow.md

@@ -0,0 +1,350 @@
+<!-- Scaffolding template maintained alongside Dflow skill. See proposals/PROPOSAL-010 for origin. -->
+
+# Git Principles — Git Flow edition
+
+> Created: {YYYY-MM-DD}
+> Scope: project Git conventions. This project adopts **Git Flow** as
+> its branching strategy.
+> Audience: engineers + AI assistants performing Git operations.
+
+Dflow itself is branching-strategy-neutral — it only requires the
+feature-branch-per-feature convention (see the Dflow skill's
+`references/git-integration.md`). This file records the Git Flow-
+specific conventions chosen by this project.
+
+If your project adopts a different branching strategy (single `main`,
+trunk-based, GitHub Flow), use `Git-principles-trunk.md` instead.
+
+---
+
+## 1. Branch Structure
+
+| Branch | Naming | Cut from | Merges to |
+|--------|--------|----------|-----------|
+| `main` / `master` | `main` | — | release / hotfix only |
+| `develop` | `develop` | — | integration branch for features |
+| feature | `feature/{SPEC-ID}-{slug}` | `develop` | `develop` |
+| release | `release/{version}` | `develop` | `main` + `develop` |
+| hotfix | `hotfix/{version}-hotfix{n}` | `main` | `main` + `develop` |
+
+The `feature/{SPEC-ID}-{slug}` pattern is a **Dflow requirement** (not
+a Git Flow requirement). It ties each feature branch to its
+corresponding `dflow/specs/features/active/{SPEC-ID}-{slug}/` directory.
+
+### Feature Branch Workflow
+
+```bash
+# 1. Create feature branch
+git checkout develop
+git pull origin develop
+git checkout -b feature/{SPEC-ID}-{slug}
+
+# 2. Stay in sync with develop during development
+git fetch origin
+git rebase origin/develop
+
+# 3. Commit as you go (see § 2 below)
+git add .
+git commit -m "[{SPEC-ID}] {short description}"
+
+# 4. Push
+git push -u origin feature/{SPEC-ID}-{slug}
+```
+
+### Release Workflow
+
+```bash
+# 1. Cut release branch
+git checkout develop
+git pull origin develop
+git checkout -b release/{version}
+
+# 2. Version bump / final adjustments (e.g. update AssemblyInfo,
+#    appsettings version, db migration baseline)
+git add .
+git commit -m "release {version}"
+
+# 3. Merge to main with --no-ff
+git checkout main
+git pull origin main
+git merge --no-ff release/{version} -m "Release {version}"
+
+# 4. Tag
+git tag -a {version} -m "{version summary}"
+
+# 5. Back-merge into develop
+git checkout develop
+git merge --no-ff release/{version} -m "Merge release/{version} back to develop"
+
+# 6. Push + cleanup
+git push origin main develop --tags
+git branch -d release/{version}
+```
+
+### Hotfix Workflow
+
+```bash
+# 1. Cut hotfix branch from main
+git checkout main
+git pull origin main
+git checkout -b hotfix/{version}-hotfix{n}
+
+# 2. Fix + commit
+git add .
+git commit -m "hotfix{n}: {fix description}"
+
+# 3. Merge to main + tag
+git checkout main
+git merge --no-ff hotfix/{version}-hotfix{n}
+git tag -a {version}-hotfix{n} -m "{fix description}"
+
+# 4. Back-merge to develop
+git checkout develop
+git merge --no-ff hotfix/{version}-hotfix{n}
+
+# 5. Push + cleanup
+git push origin main develop --tags
+git branch -d hotfix/{version}-hotfix{n}
+```
+
+**Hotfix spec requirement (team convention)**: Hotfixes often skip the
+upfront SDD cycle for speed. This project commits to writing a
+lightweight spec within **24 hours** after the hotfix lands, documenting
+root cause + fix + (if applicable) a tech-debt entry in
+`dflow/specs/architecture/tech-debt.md` if the bug reveals a systemic issue.
+This is a **human-to-human commitment** — Dflow / AI cannot track the
+24-hour clock; the team enforces it in retros.
+
+---
+
+## 2. Commit Message Format
+
+Commits must tie back to a SPEC-ID:
+
+```
+[{SPEC-ID}] {short description}
+
+{optional detailed body}
+
+Co-Authored-By: Claude <noreply@anthropic.com>   ← suggested, not mandatory
+```
+
+### Type prefix (recommended)
+
+When applicable, prefix with a type (conventional commits-style):
+
+| Type | Meaning |
+|------|---------|
+| feat | new feature |
+| fix | bug fix |
+| refactor | internal refactor (no behavior change) |
+| docs | documentation only |
+| style | formatting only |
+| test | tests only |
+| chore | build / tooling |
+
+Example: `[EXP-001] feat: introduce ExpenseReport Aggregate with submission invariants`
+
+---
+
+## 3. Gate Checks
+
+Before making key Git operations:
+
+### Before `git commit`
+
+- [ ] If the change corresponds to a phase-spec, that phase-spec's
+      `Implementation Tasks` section items are checked (or remaining items have
+      justification in the spec's notes section)
+- [ ] `_index.md` status reflects the current work (Phase Specs row
+      updated, `Resume Pointer` refreshed if the commit reaches a meaningful
+      checkpoint)
+- [ ] Clean Architecture layer rules hold (Domain has no external
+      package deps, no business logic leaked into handlers /
+      controllers)
+
+### Before merging a feature branch to `develop`
+
+- [ ] `/dflow:finish-feature` has run (or the equivalent Step 8.4
+      manual archival is complete)
+- [ ] `_index.md` status = `completed`, feature directory moved to
+      `dflow/specs/features/completed/` via `git mv`
+- [ ] BC layer synced: `dflow/specs/domain/{context}/rules.md`,
+      `behavior.md`, `events.md`, and (if cross-context)
+      `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
+- [ ] No ORM / serialization attributes on Domain entities
+- [ ] Domain unit tests pass (invariants + value object equality)
+
+---
+
+## 4. Integration Commit Message Conventions
+
+`/dflow:finish-feature` emits a **Git-strategy-neutral Integration
+Summary** (see `references/finish-feature-flow.md` in the Dflow skill).
+This section specifies how to turn that Summary into the actual merge
+commit message under Git Flow.
+
+Git Flow typically uses `--no-ff` merges (keeps the branch history
+visible). The recommended merge commit format is:
+
+```
+Merge feature/{SPEC-ID}-{slug} into develop
+
+{Feature Goal block, copied from Integration Summary}
+
+Change Scope:
+- BC: {context-name}
+- Aggregate(s) touched: {Aggregate names}
+- Phase Count: {N}
+- Lightweight Changes: {n_t2} T2 + {n_t3} T3
+
+Related BR-IDs:
+- ADDED: BR-NN, BR-NN
+- MODIFIED: BR-NN
+- REMOVED: (none)
+
+Domain Events introduced / modified: {Event names, or "(none)"}
+
+Related SPEC-IDs: {SPEC-ID}{, follow-up SPEC-IDs if any}
+```
+
+### Concrete example
+
+```bash
+git checkout develop
+git pull origin develop
+git merge --no-ff feature/SPEC-20260421-001-submit-expense-report \
+  -m "Merge feature/SPEC-20260421-001-submit-expense-report into develop" \
+  -m "Feature Goal: 實作 ExpenseReport 提交流程，含狀態機與事件發佈。" \
+  -m "Change Scope: BC Expense; Aggregate ExpenseReport; Phase Count 2; Lightweight Changes 0 T2" \
+  -m "Related BR-IDs: ADDED BR-12; MODIFIED BR-05" \
+  -m "Domain Events: ExpenseReportSubmitted" \
+  -m "Related SPEC-IDs: SPEC-20260421-001"
+git push origin develop
+```
+
+The `-m` flags stack as separate paragraphs in the commit body.
+Alternatively, write a single `-m` with the entire body or open the
+editor with `git merge --no-ff feature/...` and paste the Integration
+Summary directly.
+
+### Why `--no-ff` is recommended here
+
+Git Flow's value proposition is preserving branch history. `--no-ff`
+makes the merge commit an explicit node on `develop`, which:
+- Keeps the feature branch visible in `git log --graph`
+- Lets `git log --first-parent develop` summarise features as single
+  commits
+- Gives reviewers a single commit to reference for the whole feature
+
+If your project prefers squash merge under Git Flow (unusual but valid),
+use the trunk-edition template (`Git-principles-trunk.md`) for the
+commit format; the branch model stays Git Flow.
+
+---
+
+## 5. Tags & Release Notes
+
+### Tag naming
+
+```bash
+git tag -a v{major}.{minor}.{patch} -m "{release summary}"
+# e.g. git tag -a v1.2.3 -m "Expense report submission + event handlers"
+```
+
+### `CHANGELOG.md`
+
+Detailed version history lives in `CHANGELOG.md` at the repo root. One
+section per release tag; link back to the SPEC-IDs included in that
+release.
+
+Example entry:
+
+```markdown
+## [1.2.3] — {YYYY-MM-DD}
+
+### Added
+- {SPEC-20260421-001}: ExpenseReport submission flow with Domain Events
+
+### Changed
+- {SPEC-20260415-003}: ApprovalPolicy Aggregate invariant tightened
+
+### Fixed
+- {BUG-042}: Fix Money rounding in multi-currency totals
+```
+
+---
+
+## 6. AI Collaboration Rules (Project Policy)
+
+Three categories:
+
+### Must-confirm operations (AI asks before running)
+
+| Operation | Why |
+|-----------|-----|
+| `git commit` | Stage needs human review |
+| `git push` | Publishing to shared remote |
+| `git merge` (onto develop / main / release) | Shared-branch impact |
+| Any `git rebase` that rewrites shared history | Force-push risk |
+
+### Forbidden operations
+
+| Operation | Reason |
+|-----------|--------|
+| `git push -f` to `main` / `develop` | Overwrites other people's work |
+| `git reset --hard` to a remote branch | Irreversible |
+| `git commit --amend` on a pushed commit | Rewrites public history |
+| Deleting `main` / `develop` | Protected branches |
+
+### Allowed without asking
+
+| Operation |
+|-----------|
+| `git status` / `git diff` / `git log` / `git show` |
+| `git fetch` (no merge) |
+| `git stash` (local-only) |
+| `git branch` (listing only) |
+
+### AI commit authorship (suggested, not enforced)
+
+When an AI assists in producing a commit, appending a `Co-Authored-By`
+line is **suggested** but not mandatory. The canonical form for
+Claude is:
+
+```
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+For other AI assistants, use the vendor-documented author line (or omit
+it). This is a project-level transparency convention, not a Dflow
+requirement.
+
+---
+
+## 7. CI / CD
+
+{Fill in this project's CI/CD pipeline shape: trigger (e.g. push to
+develop, tag), stages (build → test → deploy), environments
+(dev / staging / prod). Reference the pipeline config file if one
+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
+- Run Domain unit tests + Application tests on every PR
+- Run Integration tests on `develop` and `release/*` branches
+- Verify EF migrations build cleanly
+
+---
+
+## Related Documents
+
+- `references/git-integration.md` in the Dflow skill — canonical
+  source for feature-branch-per-feature, `git mv` mandate, Gate Checks
+- [System overview](_overview.md)
+- [Spec conventions](_conventions.md)
+- `CHANGELOG.md` at repo root