dflow-sdd-ddd 0.1.0 → 0.2.0

package/CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Contributing to Dflow
+
+Thanks for taking the time to improve Dflow. This project is a spec-first
+SDD/DDD workflow kit for AI-assisted development, so changes are reviewed for
+both implementation correctness and workflow clarity.
+
+## Before You Start
+
+Please read:
+
+- `README.md` for the public project overview and installation flow.
+- `TEMPLATE-COVERAGE.md` before changing templates, scaffolding, or generated
+  document structure.
+- `TEMPLATE-LANGUAGE-GLOSSARY.md` before changing template headings or field
+  labels.
+- The relevant Greenfield or Brownfield skill source when changing workflow
+  behavior.
+
+The public source is kept intentionally smaller than the development workspace.
+Internal planning notes, proposal handoffs, and review artifacts are maintainer
+records; public issues and pull requests should be understandable without them.
+
+## What to Open
+
+Open a bug report when an existing command, generated file, or documented flow
+does not behave as described.
+
+Open a workflow change request when you want to change Dflow behavior, template
+shape, generated scaffolding, DDD guidance, or the contract of a `/dflow:*`
+flow.
+
+Open docs feedback when the current documentation is confusing, incomplete, or
+hard to follow.
+
+Open a question when you need help deciding how Dflow applies to your project.
+Questions are welcome, but this project does not promise a general support SLA.
+
+If an AI assistant notices a possible Dflow issue while helping in your project,
+you can ask it to run `/dflow:report-dflow-feedback`. That flow should produce a
+sanitized local draft that you review before opening a GitHub issue or PR. It
+must not submit private project details or publish anything automatically.
+
+## Pull Request Expectations
+
+Keep pull requests focused. A good PR explains:
+
+- What changed and why.
+- Which files or workflow contracts are affected.
+- Whether the change affects Greenfield, Brownfield, or both tracks.
+- Whether common flow files were synchronized across both tracks.
+- Whether generated templates, tutorial material, or coverage docs need updates.
+- What verification was run.
+
+For code or packaging changes, run:
+
+```bash
+npm test
+npm pack --dry-run
+git diff --check
+```
+
+For documentation-only changes, at minimum run:
+
+```bash
+git diff --check
+```
+
+If a command cannot be run in your environment, note that in the PR.
+
+GitHub Actions runs the same verification commands on every pull request to
+`main` and on every push to `main`. The CI is verification-only — it does not
+publish releases, change versions, or create tags.
+
+When changing templates or scaffolding, keep both source surfaces aligned:
+
+- skill source under `sdd-ddd-greenfield-skill/` or
+  `sdd-ddd-brownfield-skill/`
+- packaged templates under `templates/greenfield/` or `templates/brownfield/`
+
+If you are unsure which surface to edit, describe that uncertainty in the PR.
+
+## Greenfield and Brownfield Synchronization
+
+Several Dflow flows are shared between the Greenfield and Brownfield tracks. If
+you change a common SDD flow, update both copies unless the change is
+intentionally track-specific.
+
+Common shared flows include:
+
+- `dflow-feedback-flow.md`
+- `init-project-flow.md`
+- `new-feature-flow.md`
+- `modify-existing-flow.md`
+- `new-phase-flow.md`
+- `finish-feature-flow.md`
+- `drift-verification.md`
+- `pr-review-checklist.md`
+- `git-integration.md`
+
+Track-specific behavior is fine, but it should be named explicitly in the PR.
+
+## Template and Heading Changes
+
+Dflow templates use canonical English structure so AI agents can locate sections
+reliably across projects. User-authored prose inside generated documents may use
+the team's chosen prose language.
+
+Do not localize template headings or structural field labels as a drive-by
+change. Localized headings require a separate design decision because they
+affect templates, anchors, tutorial output, and verification strategy.
+
+## Release Changes
+
+If your change affects published behavior, generated files, CLI commands, or
+workflow contracts, mention the expected version impact in the PR:
+
+- Patch: bug fix, docs clarification, release metadata, or non-breaking wording.
+- Minor: new command, new generated file, workflow contract expansion, or
+  materially changed template shape.
+- Breaking change: anything that can make existing Dflow projects or automation
+  need manual adjustment.
+
+See `docs/release-versioning-policy.md` for the maintainer release policy.

package/README.md

@@ -1,209 +1,251 @@
-# AI-Guided SDD/DDD Development Skills
+# Dflow
 
-AI 引導的規格驅動開發（SDD）與領域驅動設計（DDD）工作流程規範，設計用於 Claude Code 協作開發。
+Dflow is a spec-first workflow kit for AI-assisted software development. It gives your AI coding agent a concrete process for turning change requests into structured specs, domain language, implementation plans, drift checks, and reviewable code instead of jumping straight from prompt to code.
 
-## 這是什麼
+AI makes delivery faster, but it also makes ambiguous domain knowledge more dangerous. Dflow uses DDD ideas such as ubiquitous language, bounded contexts, domain rules, and model ownership as the semantic backbone of SDD, so the AI has constraints before it generates code. The goal is not ceremony for its own sake; the goal is repeatable software change with clearer meaning, fewer scattered rules, and less prompt-dependent behavior.
 
-這套 Skill 讓 AI 在開發過程中擔任**流程守衛（Workflow Guardian）**的角色。開發者不需要熟悉 SDD 或 DDD 的所有細節——AI 會在對的時機問對的問題，引導開發者自然地產出規格文件、領域模型、和技術債記錄。
+## Key Features
 
-適用場景：
-- 團隊導入 SDD/DDD 但成員經驗不一
-- 希望在開發過程中保持架構紀律
-- ASP.NET WebForms 專案準備遷移到 ASP.NET Core
-- 學習 DDD 並透過模擬專案練習
+| Feature | What it gives engineering teams |
+|---|---|
+| **Spec-first development** | Every meaningful change starts from an explicit spec, acceptance behavior, and implementation plan before code changes begin. |
+| **Greenfield and Brownfield tracks** | Start clean in a new project, or introduce Dflow into an existing codebase through progressive domain extraction and safer incremental change. |
+| **Hybrid workflow control** | Command-first entry points for intentional work, auto-trigger checks as a safety net, and transparent phase gates so developers stay in control. |
+| **DDD semantic backbone** | Captures domain language, context boundaries, business rules, and model decisions so AI output is constrained by project meaning. |
+| **Three-layer documentation model** | Keeps short-lived phase deltas, feature snapshots, and system-level state separate, so specs stay useful instead of becoming one large document dump. |
+| **Drift verification** | Checks whether specs, domain documents, implementation, tests, and technical debt records still describe the same system. |
+
+## Get Started
 
-## 目錄結構
+Prerequisite: a local Node.js / npm environment that can run `npx`.
 
+Run Dflow from the root of the project you want to adopt it in:
+
+```bash
+npx dflow-sdd-ddd init
 ```
-├── bin/                           # dflow CLI entrypoint
-├── lib/                           # init runtime implementation
-├── templates/                     # npm package template source
-├── test/                          # smoke tests
-├── tutorial/                      # 人讀教學劇本與範例 outputs
-├── planning/                      # handoff / contract / planning notes
-├── proposals/                     # Proposal 管理目錄
-├── reviews/                       # cross-round review reports and prompts
-├── sdd-ddd-webforms-skill/        # WebForms 版 Skill（英文，供 AI 使用）
-└── sdd-ddd-core-skill/            # ASP.NET Core 版 Skill（英文，供 AI 使用）
+
+The init flow asks whether the project is greenfield or brownfield, then
+previews the files it will create. Existing files are not overwritten. Init
+creates workflow documentation and AI instruction files; it does not inspect,
+refactor, or migrate your application code.
+
+For a fixed global CLI:
+
+```bash
+npm install -g dflow-sdd-ddd
+dflow init
 ```
 
----
+If the project is already initialized and you later add another AI coding
+tool, run:
 
-## 兩套 Skill 的差異
+```bash
+dflow configure-agents
+```
 
-| | WebForms Skill | Core Skill |
-|---|---|---|
-| **適用階段** | 目前：在運行中的 WebForms 專案開發 | 未來：ASP.NET Core 新專案 / 模擬練習 |
-| **架構** | Domain 層 + Code-Behind（兩層） | Clean Architecture 四層 |
-| **DDD 深度** | 準備性——術語表、Context 識別、基本抽離 | 完整戰術模式——Aggregate、Domain Events、CQRS |
-| **核心引導** | 「Code-Behind 盡量薄」 | 「每一層各司其職，業務邏輯只在 Domain」 |
-| **遷移意識** | 每次開發都產出可遷移的資產 | 從頭設計乾淨架構 |
-| **附加內容** | — | DDD 建模指南、Aggregate 設計工作表、模擬練習計畫 |
+This command only configures AI instruction files. It does not rerun project
+initialization or touch existing specs.
 
----
+To check whether the project still has legacy or pre-V1 artifacts (such as
+a top-level `specs/` directory or a `_共用/` directory left over from older
+Dflow forms), run:
 
-## WebForms Skill 檔案說明
+```bash
+dflow doctor
+```
 
-### SKILL.md — 主文件
-AI 的決策樹和核心規範。定義了五個核心原則、流程嚴謹度對照表、專案目錄結構、各階段引導問題、Domain 層規範。
+`doctor` is a read-only health check. It never modifies files; it only
+reports findings and points at the migration guide.
 
-### references/ — 流程參考
-| 檔案 | 內容 |
-|---|---|
-| `init-project-flow.md` | `npx dflow-sdd-ddd init` 的 internal flow / manual fallback，定義 project bootstrap 問答和 scaffolding 行為 |
-| `new-feature-flow.md` | 新功能 8 步驟流程：需求理解 → Context 識別 → 概念發掘 → 撰寫規格 → 實作規劃 → 分支 → 實作 → 完成 |
-| `modify-existing-flow.md` | 修改既有功能流程，重點在趁機從 Code-Behind 抽離業務邏輯到 Domain 層 |
-| `new-phase-flow.md` | 在既有 feature 下新增 phase 的規格與實作流程 |
-| `finish-feature-flow.md` | 完成功能時的 drift 檢查、文件收斂與 tech-debt 收尾 |
-| `drift-verification.md` | 規格、模型、實作與文件間的 drift verification 檢查 |
-| `git-integration.md` | Git principles 與 SDD 階段對齊，每個 gate 有具體檢查項目 |
-| `pr-review-checklist.md` | PR 審查時的合規檢查和遷移準備度 A~F 評分 |
-
-### scaffolding/ — init 建立的基線文件
-| 檔案 | 用途 |
-|---|---|
-| `_overview.md` | Dflow-owned spec tree 的總覽 |
-| `_conventions.md` | 專案 convention，包含 `Prose Language` |
-| `Git-principles-*.md` | Git Flow / Trunk-Based Development 原則模板 |
+After init, start work through the Dflow workflow in your AI coding agent:
 
-### templates/ — 模板
-| 檔案 | 用途 |
-|---|---|
-| `_index.md` | feature / phase 索引與 integration summary |
-| `phase-spec.md` | phase 級規格模板 |
-| `behavior.md` | Given/When/Then 行為規格模板 |
-| `lightweight-spec.md` | Bug 修復用的輕量規格模板 |
-| `context-definition.md` | 新 Bounded Context 定義模板 |
-| `CLAUDE.md` | init 用的 AI 協作規範模板來源；採用時由 `npx dflow-sdd-ddd init` 處理 |
-| `context-map.md`、`glossary.md`、`models.md`、`rules.md`、`tech-debt.md` | domain / migration 文件模板 |
+```text
+/dflow:new-feature
+/dflow:modify-existing
+/dflow:bug-fix
+/dflow:new-phase
+/dflow:finish-feature
+/dflow:verify
+/dflow:pr-review
+```
 
----
+If your tool does not support custom slash commands, use the same command names as plain instructions in chat. Dflow is Markdown-based workflow material plus a scaffolding CLI, so it can be used with AI coding agents that can read project instructions and repository context.
 
-## Core Skill 檔案說明
+For the first adoption pass, use a branch or disposable sample project so your
+team can inspect the generated `dflow/specs/` workspace before bringing the
+workflow into an active codebase.
 
-### SKILL.md — 主文件
-在 WebForms 版基礎上新增：Clean Architecture 四層架構圖、各層不可妥協的規範、DDD 戰術模式的引導問題。
+For a guided evaluation walk-through — what `init` creates, AI tool support,
+track choice, and a 30-minute sample-project playbook — see [Evaluating
+Dflow](docs/evaluating-dflow.md). For end-to-end scenario walk-throughs of
+Greenfield and Brownfield workflows with worked spec outputs, see the
+[`tutorial/`](tutorial/README.md) index (top of file has an English reading
+guide).
 
-### references/ — 流程參考
-| 檔案 | 內容 |
-|---|---|
-| `init-project-flow.md` | `npx dflow-sdd-ddd init` 的 internal flow / manual fallback，定義 project bootstrap 問答和 scaffolding 行為 |
-| `new-feature-flow.md` | 新功能流程，新增逐層實作順序（Domain → Application → Infrastructure → Presentation） |
-| `modify-existing-flow.md` | 修改流程，新增 Aggregate 設計重新評估 |
-| `new-phase-flow.md` | 在既有 feature 下新增 phase 的規格與實作流程 |
-| `finish-feature-flow.md` | 完成功能時的 drift 檢查、文件收斂與 tech-debt 收尾 |
-| `drift-verification.md` | 規格、模型、實作與文件間的 drift verification 檢查 |
-| `ddd-modeling-guide.md` | **核心新增**：DDD 建模完整指南，涵蓋 Aggregate 設計規則、Value Object、Domain Events、Specification、Domain Service、Bounded Context 關係、常見錯誤 |
-| `git-integration.md` | Git principles 與 SDD 階段對齊，閘門檢查新增 Aggregate 設計和 Domain Events |
-| `pr-review-checklist.md` | PR 審查，四層各自的檢查項目 |
-
-### scaffolding/ — init 建立的基線文件
-| 檔案 | 用途 |
-|---|---|
-| `_overview.md` | Dflow-owned spec tree 的總覽 |
-| `_conventions.md` | 專案 convention，包含 `Prose Language` |
-| `architecture-decisions-README.md` | architecture decisions 目錄說明 |
-| `Git-principles-*.md` | Git Flow / Trunk-Based Development 原則模板 |
+## Project Tracks
 
-### templates/ — 模板
-| 檔案 | 用途 |
-|---|---|
-| `_index.md` | feature / phase 索引與 integration summary |
-| `phase-spec.md` | phase 級規格模板，支援 Domain Events 和逐層實作計畫 |
-| `behavior.md` | Given/When/Then 行為規格模板 |
-| `lightweight-spec.md` | 輕量規格模板 |
-| `context-definition.md` | Bounded Context 定義模板 |
-| `aggregate-design.md` | **核心新增**：Aggregate 設計工作表（不變條件、狀態變更方法、Events、引用關係） |
-| `CLAUDE.md` | init 用的 AI 協作規範模板來源；採用時由 `npx dflow-sdd-ddd init` 處理 |
-| `events.md`、`context-map.md`、`glossary.md`、`models.md`、`rules.md`、`tech-debt.md` | domain / architecture 文件模板 |
-
-### PRACTICE_PLAN_tw.md — 模擬練習計畫
-7 個 Phase 的 DDD 學習路線，使用費用報銷系統作為模擬專案，預估 15-22 小時：
-
-| Phase | 內容 | 學到的 DDD 概念 |
+| Track | Use it when | Main outcome |
 |---|---|---|
-| 1 | 建立基礎、識別 Bounded Context | Context Map、Ubiquitous Language |
-| 2 | 第一個 Aggregate + Value Objects | Aggregate Root、不變條件、Private Setter |
-| 3 | Domain Events | 事件驅動、最終一致性 |
-| 4 | 第二個 Aggregate + 跨 Aggregate 溝通 | Reference by ID、狀態機 |
-| 5 | CQRS + Application 層 | Command/Query 分離 |
-| 6 | Infrastructure 整合 | EF Core 設定、Repository、Event Dispatching |
-| 7 | 回顧 + Skill 檢視 | 流程改善 |
+| **Greenfield** | You are starting a new system or a new bounded area with room to shape architecture and domain model early. | Clean spec baseline, domain model ownership, feature-by-feature implementation through SDD. |
+| **Brownfield** | You are adding or changing behavior in an existing codebase where business rules may already be scattered. | Progressive domain extraction, safer change planning, and migration-ready domain knowledge. |
 
----
+These tracks describe adoption style, not framework branding. Dflow should be read as a workflow system for software teams that want AI assistance without giving up domain clarity.
 
-## How to adopt Dflow in your project
+## Workflow Model
 
-Dflow is the AI-guided SDD/DDD workflow contained in this repo (see `sdd-ddd-webforms-skill/` and `sdd-ddd-core-skill/`). In V1, project bootstrap is npm CLI first: the default entry is `npx dflow-sdd-ddd init`, which seeds `dflow/specs/` and keeps Dflow-owned documents under the `dflow/` namespace.
+Dflow uses a hybrid design:
 
-The npm package is published as `dflow-sdd-ddd` because the unscoped `dflow` package name is already occupied on npm. The installed CLI still exposes the `dflow` binary for global installs.
+| Layer | Purpose |
+|---|---|
+| **Command-first entry** | Developers intentionally start work with commands such as `/dflow:new-feature` or `/dflow:modify-existing`. |
+| **Auto-trigger safety net** | When the conversation clearly implies a feature, phase, bug fix, verification, or review, the AI should suggest the matching Dflow flow. |
+| **Transparency gates** | The AI announces flow entry, phase transitions, and important internal steps so the developer can approve direction before work expands. |
 
-Adopting Dflow in a project takes 4 steps:
+Dflow also scales ceremony by change risk:
 
-1. In your project root, run `npx dflow-sdd-ddd init`.
-2. Answer the intake questions. Dflow will ask for the edition, project context, optional starter files, and the required project prose language for generated spec content.
-3. Review the file-list preview and confirm the writes. Existing files are never overwritten.
-4. Start your first feature with `/dflow:new-feature`, or for an existing codebase, `/dflow:modify-existing` to work from an incoming change request.
+| Tier | Typical use | Expected weight |
+|---|---|---|
+| **T1 Lightweight** | Small bug fixes or narrow edits. | Minimal spec, focused verification. |
+| **T2 Standard** | Normal feature work. | Feature spec, behavior examples, implementation plan, finish checks. |
+| **T3 Full** | Cross-cutting changes, new bounded contexts, risky architecture work. | Full domain modeling, phase planning, broader drift verification, stronger review gates. |
 
-The generated baseline lives under `dflow/specs/`, for example `dflow/specs/shared/_conventions.md`, `dflow/specs/domain/glossary.md`, and `dflow/specs/features/active/`. The project AI guide is the one special root-level exception: `CLAUDE.md` stays at the project root so AI tools can discover it normally. If a root `CLAUDE.md` already exists, Dflow writes a mergeable snippet instead of overwriting it.
+The transparency gates and T1/T2/T3 tiers are related but separate: transparency controls how the AI communicates the workflow; tiers control how much specification and verification the change needs.
 
-Dflow keeps template structure stable in English: headings, table headers, labels, anchors, IDs, placeholders, file paths, and code-facing terms remain canonical English. Free prose inside those sections follows the project's `Prose Language` setting in `dflow/specs/shared/_conventions.md`.
+## Documentation Model
 
-Advanced usage: `npm install -g dflow-sdd-ddd` may be useful for users who want a fixed global CLI, then run `dflow init`. This is not the V1 default. `npm create dflow-sdd-ddd` is not implemented in V1 and remains a V2 evaluation item.
+Dflow separates documents by lifecycle:
 
-For what gets created at init time, how scaffolding templates are chosen, and how to re-run safely, see `sdd-ddd-webforms-skill/references/init-project-flow.md` (or the Core equivalent).
+| Layer | Shape | Purpose |
+|---|---|---|
+| **Phase Delta** | Short-lived phase spec. | Captures what this phase changes, why, and how it will be verified. |
+| **Feature Snapshot** | Feature-level summary and behavior. | Preserves the accepted behavior and implementation decisions after phases complete. |
+| **System State** | Shared domain and architecture documents. | Maintains durable knowledge such as glossary, context map, rules, models, conventions, and technical debt. |
+
+This keeps AI collaboration grounded. The phase layer gives the agent immediate execution context, the feature layer records what was delivered, and the system layer becomes the long-term source of truth for future prompts and reviews.
+
+## Files Created by Init
+
+A typical initialized project receives a `dflow/` workspace:
+
+```text
+dflow/
+  specs/
+    shared/
+      _overview.md
+      _conventions.md
+      Git-principles-*.md
+    domain/
+      glossary.md
+      context-map.md
+    architecture/
+      tech-debt.md
+    features/
+      active/
+      completed/
+```
 
-### V2 Starter Kit and Dflow — division of labour
+Dflow also creates or provides a mergeable project instruction file for your AI coding agent. The exact file depends on the target tool and existing project setup; Dflow avoids overwriting existing project instructions.
 
-Dflow is distributed alongside a sister project, **V2 Starter Kit** (`SDD-Starter-Kit`), which plays a complementary role:
+When you select AI agent setup during init, Dflow writes
+`dflow/specs/shared/AI-AGENT-GUIDE.md` as the canonical project guide, then
+creates small tool-specific shims that point back to it:
 
-| | V2 Starter Kit | Dflow (this repo) |
-|---|---|---|
-| **Format** | Complete distributable starter kit (flat files + tutorial docs) | AI-guided skill (read and executed by Claude Code at runtime) |
-| **Onboarding documents** | Ships full onboarding pack (e.g. `SDD-AI協作開發模式介紹.md`, `使用說明.md`) | Ships minimal scaffolding templates only (`scaffolding/`) |
-| **Primary audience** | Humans reading + copying files manually | AI running slash commands in a live project |
-| **Typical use** | Teams evaluating SDD/DDD or wanting a human-readable reference | Teams who want the workflow enforced at development time |
+| Tool target | Generated file |
+|---|---|
+| Codex / Copilot coding agent | `AGENTS.md` |
+| Claude Code | `CLAUDE.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
 
-The two are designed to coexist: you can start with V2's onboarding docs for reading/training, then adopt Dflow in the project itself for enforcement. Dflow's `scaffolding/` is intentionally a **minimal** template set; if you want the full V2 onboarding documents, copy them from V2 separately (V2's Tutorial rebuild is tracked as Closeout C2 of this repo's work plan).
+If one of those files already exists, Dflow leaves it unchanged and writes a
+merge snippet under `dflow/specs/shared/` instead. The project guide stays the
+single source of truth, so teams can use multiple AI tools without maintaining
+multiple copies of the workflow rules.
 
----
+You can run `dflow configure-agents` later to add more tool shims as the team
+adopts additional AI coding agents.
 
-## 如何使用
+For tool-specific walk-throughs of what `init` writes and how Dflow's
+workflow commands appear in a given AI tool, see the per-tool guides under
+`docs/`:
 
-### 在專案中採用 Dflow
+- [Using Dflow with Claude Code](docs/using-with-claude-code.md)
+- [Using Dflow with Codex CLI](docs/using-with-codex.md)
 
-1. 在專案根目錄執行 `npx dflow-sdd-ddd init`
-2. 依提示選擇 edition、starter files、project prose language
-3. 預覽並確認寫入清單；Dflow 不會覆寫既有檔案
-4. 啟動 AI coding agent，從 `/dflow:new-feature` 或 `/dflow:modify-existing` 開始
+Guides for Gemini CLI and GitHub Copilot may follow as maintainer
+experience with each tool stabilizes.
 
-### 在 Claude Code 中進行 DDD 模擬練習
+Init does not copy the `tutorial/` directory into your project. The
+[`tutorial/`](tutorial/README.md) directory lives in this source repository
+as evaluation material for understanding how Dflow works on Greenfield and
+Brownfield scenarios; the tutorial index opens with an English reading guide
+for non-Chinese readers.
 
-1. 在練習專案根目錄執行 `npx dflow-sdd-ddd init`，選擇 Core edition
-2. 啟動 Claude Code，輸入：
-```
-我要開始一個 DDD 模擬練習專案：員工費用報銷系統（ExpenseTracker）。
-請依照 Skill 中定義的流程引導我，從 Phase 1 開始。
-```
+## Main Flows
 
----
+| Flow | When to use it | Typical outputs |
+|---|---|---|
+| `/dflow:new-feature` | A new user-visible capability or business behavior. | Feature spec, behavior examples, phase plan, domain updates. |
+| `/dflow:modify-existing` | A change to behavior already present in the system. | Impact analysis, updated specs, adjusted domain rules, migration notes when needed. |
+| `/dflow:bug-fix` | A defect where expected behavior can be stated narrowly. | Lightweight spec, reproduction, fix plan, regression check. |
+| `/dflow:new-phase` | A feature needs another implementation slice. | Phase delta, acceptance checks, focused implementation plan. |
+| `/dflow:finish-feature` | The implementation is done and needs closure. | Drift verification, feature snapshot, technical debt update, review checklist. |
+| `/dflow:verify` | You need confidence that docs and code still match. | Drift report across spec, domain docs, implementation, tests, and debt records. |
+| `/dflow:pr-review` | A change is ready for review. | SDD/DDD compliance review with risks, gaps, and follow-up items. |
+| `/dflow:report-dflow-feedback` | You or the AI found a Dflow issue or improvement while using the workflow. | Sanitized local feedback draft for a GitHub issue or future PR; nothing is submitted automatically. |
 
-## 設計理念
+## Why DDD Matters More with AI
 
-### Spec Before Code（先規格、後程式碼）
-每一次程式碼變更都應該有對應的規格文件。規格不是額外的負擔，而是思考的工具——在寫程式之前先想清楚要做什麼。
+AI agents are strong at filling gaps. That is useful when the missing detail is mechanical, but risky when the missing detail is business meaning. If a prompt does not define the language, boundaries, and allowed behavior, the model may invent plausible rules that are hard to notice in review.
 
-### AI 作為流程守衛
-AI 不只是回答問題的工具，它主動引導開發流程：在你開分支前確認規格存在、在你寫 Code-Behind 時提醒業務邏輯應該在 Domain 層、在 PR 時檢查架構合規性。
+Dflow treats DDD as the semantic structure behind the spec. Ubiquitous language keeps names consistent. Bounded contexts keep meanings from leaking across areas. Domain rules define what is correct, allowed, or forbidden before implementation starts.
 
-### 漸進式 DDD
-不需要一次到位。WebForms 階段先累積術語表和領域知識，ASP.NET Core 階段再完整落地 DDD 戰術模式。現在寫的每一份規格和每一段 Domain 層程式碼，都是未來遷移的資產。
+In a code-first workflow, design often appears after the fact in classes, handlers, and tests. In an AI-assisted workflow, the spec must become the precondition for generation. The practical flow becomes:
 
-### 三份資產
-每次開發循環都產出：**規格文件**（未來的需求文件）、**Domain 層程式碼**（可直接遷移）、**技術債記錄**（遷移指南）。
+```text
+Domain meaning -> Structured spec -> AI implementation -> Code as output
+```
+
+For a longer explanation, see [Why DDD Matters More with AI](docs/why-ddd-for-ai.md).
 
----
+## Repository Layout
 
-## 授權
+| Path | Purpose |
+|---|---|
+| `bin/` | CLI entrypoint. |
+| `lib/` | Init runtime implementation. |
+| `templates/` | Files copied by the init command. |
+| `test/` | Smoke tests for generated output. |
+| `tutorial/` | Guided learning scenarios and expected outputs. |
+| `sdd-ddd-*-skill/` | Source workflow material consumed by AI coding agents. |
+
+## Contributing and Releases
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for issue and pull request guidance.
+Pull requests run an automated verification workflow on GitHub before review.
+Maintainer-facing release rules are documented in [Release and Versioning
+Policy](docs/release-versioning-policy.md), with the manual npm flow in [npm
+Publish Checklist](docs/npm-publish-checklist.md).
+
+## Status
+
+Dflow is currently published as `dflow-sdd-ddd` on npm. The latest published
+npm package is `0.2.0`, covering project initialization, workflow
+documentation, multi-AI agent setup, AI-agent-readable SDD/DDD guidance,
+public migration tooling (manual migration guide and `dflow doctor`
+read-only health check), public onboarding (evaluator guide and per-tool
+walkthroughs for Claude Code and Codex CLI), and a verification-only CI
+workflow.
+
+The GitHub source may include post-`0.2.0` repository changes before the
+next npm release is published. See [CHANGELOG.md](CHANGELOG.md) for full
+release history.
+
+If you maintain a project that adopted an early Dflow form before
+`0.1.0` was published, see [Migrating to Dflow
+V1](docs/migrating-to-dflow-v1.md) for the manual migration checklist.
+
+## License
 
 MIT License. See [LICENSE](LICENSE).

package/TEMPLATE-COVERAGE.md

@@ -0,0 +1,46 @@
+<!-- Maintenance contract for Dflow. See archive/proposals/PROPOSAL-013-system-document-template-coverage.md §4 for origin. -->
+
+# Template Coverage Matrix
+
+This file is a maintenance contract for Dflow, not the runtime brain. `SKILL.md` should point to this matrix for review and maintenance work instead of duplicating the full table.
+
+The matrix lists Brownfield / Greenfield logical template parity so reviewers can check which templates should remain aligned and which differences are intentional.
+
+## Matrix
+
+| Logical document | Generated / maintained path | Brownfield template | Greenfield template | Parity requirement | Allowed differences | Section anchors |
+|---|---|---|---|---|---|---|
+| Feature dashboard | `dflow/specs/features/{active\|completed}/{SPEC-ID}-{slug}/_index.md` | `templates/_index.md` | `templates/_index.md` | Required sections same | Greenfield may mention Aggregate / Domain Events | `current-br-snapshot`, `lightweight-changes` |
+| Phase spec | `dflow/specs/features/active/{SPEC-ID}-{slug}/phase-spec-YYYY-MM-DD-{slug}.md` | `templates/phase-spec.md` | `templates/phase-spec.md` | Lifecycle sections same | Greenfield has layer-by-layer plan + Domain Events | `implementation-tasks`, `behavior-scenarios`, `open-questions` |
+| Lightweight spec | `dflow/specs/features/active/{SPEC-ID}-{slug}/lightweight-YYYY-MM-DD-{slug}.md` or `BUG-{NUMBER}-{slug}.md` | `templates/lightweight-spec.md` | `templates/lightweight-spec.md` | T2 structure and task checklist intent same | Layer tags differ | `implementation-tasks` |
+| Glossary | `dflow/specs/domain/glossary.md` | `templates/glossary.md` | `templates/glossary.md` | Same columns | none | - |
+| Bounded Context definition | `dflow/specs/domain/{context}/context-definition.md` | `templates/context-definition.md` | `templates/context-definition.md` | Same purpose / structural sections | Greenfield may reference Aggregate / Domain Service / Repository Interface | - |
+| Rules index | `dflow/specs/domain/{context}/rules.md` | `templates/rules.md` | `templates/rules.md` | BR-ID / anchor / status format same | Greenfield may include Aggregate column | `business-rules` |
+| Models catalog | `dflow/specs/domain/{context}/models.md` | `templates/models.md` | `templates/models.md` | Same purpose | Greenfield has Aggregate / Specification depth | - |
+| Aggregate worksheet | `dflow/specs/domain/{context}/aggregates/{name}.md` (per Aggregate, on demand) | n/a | `templates/aggregate-design.md` | Greenfield only | Brownfield does not use the Aggregate worksheet | - |
+| Behavior snapshot | `dflow/specs/domain/{context}/behavior.md` | `templates/behavior.md` | `templates/behavior.md` | BR anchor and drift-verification structure same | Greenfield may reference Domain Events | `behavior-scenarios` |
+| Events catalog | `dflow/specs/domain/{context}/events.md` | n/a | `templates/events.md` | Greenfield only | Brownfield does not require event catalog | - |
+| Context map | `dflow/specs/domain/context-map.md` | `templates/context-map.md` optional | `templates/context-map.md` mandatory | Similar concept | Brownfield optional / emergent | - |
+| Tech debt | Brownfield: `dflow/specs/migration/tech-debt.md`; Greenfield: `dflow/specs/architecture/tech-debt.md` | `templates/tech-debt.md` | `templates/tech-debt.md` | Same backlog intent | Brownfield migration focus; Greenfield architecture focus | - |
+| ADR guide | `dflow/specs/architecture/decisions/README.md` | n/a | `scaffolding/architecture-decisions-README.md` | Greenfield only | Brownfield not applicable | - |
+| Project AI guide | `dflow/specs/shared/AI-AGENT-GUIDE.md` when at least one AI agent is selected during init | `scaffolding/AI-AGENT-GUIDE.md` | `scaffolding/AI-AGENT-GUIDE.md` | Same canonical tool-neutral workflow guide and source-of-truth pointers | Track-specific seeded values and available source-of-truth paths may differ | - |
+| AI tool shims | `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`, or merge snippets under `dflow/specs/shared/` | generated by CLI | generated by CLI | Thin files must point back to `dflow/specs/shared/AI-AGENT-GUIDE.md`; existing files are not overwritten | Tool-specific import hints differ | - |
+| Legacy Claude guide template | `<project root>/CLAUDE.md` | `templates/CLAUDE.md` | `templates/CLAUDE.md` | H2 navigation and H3 structural headings aligned (canonical English, per F-01 Path A) | Greenfield includes Aggregate / Architecture Decisions and other Greenfield-specific H3 sections | - |
+
+## Reference Flow Parity
+
+Common reference flows under `sdd-ddd-brownfield-skill/references/` and
+`sdd-ddd-greenfield-skill/references/` must stay synchronized unless a
+track-specific difference is explicit. This includes
+`dflow-feedback-flow.md`; it is a governance/support flow and should not grow
+GitHub CLI submission behavior without a separate proposal.
+
+## Section Anchors
+
+The `Section anchors` column is the single maintenance location for template section anchor coverage. Do not create a separate `SECTION-ANCHORS.md`.
+
+When adding a new anchor:
+
+1. Add the anchor definition to `archive/proposals/PROPOSAL-013-system-document-template-coverage.md` §1 "Important Dflow-updated sections" (historical reference) or its successor governance document.
+2. Add the anchor id to the matching row in this matrix.
+3. Follow the anchor naming / namespacing / versioning rules defined in `archive/proposals/PROPOSAL-013-system-document-template-coverage.md` §1.