dflow-sdd-ddd 0.9.0 → 0.11.0

package/docs/migrating-to-dflow-v1.md

@@ -1,230 +0,0 @@
-# Migrating to Dflow V1
-
-> **Audience**: maintainers of an existing project that adopted an early
-> Dflow form (pre-`dflow-sdd-ddd@0.1.0`) and want to align it with the
-> V1 baseline that ships from npm.
->
-> **Stance**: V1 took a clean cut. Dflow does not perform automatic
-> migration. This guide is a manual checklist. The CLI only warns when
-> it detects legacy paths; it does not modify existing files.
-
-> **Audience reality (2026-05-15)**: To date, the only known user of
-> this guide has been the **OBTS** migration (a single, completed
-> one-off). Dflow has not had broad pre-V1 adoption; this guide is
-> maintained as a contingency endpoint for `dflow doctor` and
-> `dflow init` warning messages, not as documentation of an active
-> migration program. If you reach this page via those tool outputs
-> and your case isn't covered below, please open a docs feedback issue
-> so the guide can be extended.
-
-## When You Need This Guide
-
-Skip this guide if you started using Dflow at `dflow-sdd-ddd@0.1.0`
-or later. Your project is already on the V1 baseline.
-
-Read this guide if any of the following are true:
-
-- Your project has a top-level `specs/` directory that holds Dflow
-  spec material (not the V1 `dflow/specs/`).
-- Your project has `specs/_共用/` instead of `dflow/specs/shared/`.
-- Your spec headings are in Traditional Chinese rather than the
-  canonical English vocabulary documented in
-  `TEMPLATE-LANGUAGE-GLOSSARY.md`.
-- Your AI instructions point teammates to `/dflow:init-project`
-  instead of the Dflow CLI init command (`dflow init`, or
-  `npx dflow-sdd-ddd init` on the no-install path).
-- Your `CLAUDE.md` (or equivalent root instruction file) was generated
-  by an early Dflow variant that wrote a full Claude-only file rather
-  than the V1 multi-AI thin shim that points to
-  `dflow/specs/shared/AI-AGENT-GUIDE.md`.
-
-You may need only some of these steps; the five sections below are
-independent.
-
-## Before You Start
-
-- Work on a dedicated branch or a disposable copy. None of the steps
-  are destructive, but move-and-rename mistakes are easier to recover
-  from a clean branch.
-- Make sure the working tree is clean (`git status`).
-- Note your current Dflow version if you can identify it. Older
-  internal Dflow forms may not have been versioned at all.
-- Open these V1 reference files for cross-checking:
-  - `TEMPLATE-LANGUAGE-GLOSSARY.md` — canonical English headings.
-  - `TEMPLATE-COVERAGE.md` — V1 file layout and parity matrix.
-  - `docs/evaluating-dflow.en.md` — what a fresh V1 `init` produces, if
-    you want to spin up a sample project to compare against.
-- For an on-demand read-only summary of legacy artifacts in your
-  project, run `dflow doctor` (or `npx dflow-sdd-ddd doctor` on the
-  no-install path). The command lists detected legacy paths and missing
-  V1 fields; it never modifies files.
-
-## Migration Steps
-
-### 1. Move root `specs/` to `dflow/specs/`
-
-V1 puts every Dflow-managed spec under `dflow/specs/`, so the `dflow/`
-directory becomes a single Dflow namespace separate from any
-unrelated `specs/` directory another tool may own (PROPOSAL-014).
-
-If your project has top-level `specs/` containing Dflow content:
-
-```bash
-mkdir -p dflow
-git mv specs dflow/specs
-git status
-```
-
-Commit the rename in a single commit. Avoid mixing the rename with
-content edits in the same commit so reviewers can read the diff
-cleanly.
-
-If you also have an unrelated `specs/` directory used by another
-tool, move only the Dflow material into `dflow/specs/`. The CLI will
-warn when it sees a non-Dflow `specs/` directory but will not modify
-it.
-
-### 2. Rename `_共用/` to `shared/`
-
-V1 uses canonical English directory names (PROPOSAL-012). If your
-project has `dflow/specs/_共用/`:
-
-```bash
-git mv dflow/specs/_共用 dflow/specs/shared
-git status
-```
-
-Update any cross-references in spec files or AI instructions. A
-project-wide grep after the rename catches leftover references:
-
-```bash
-grep -rn "_共用" .
-```
-
-### 3. Translate Chinese headings to canonical English
-
-V1 templates use canonical English structure for section headings,
-field labels, anchors, and placeholders (PROPOSAL-013). Free prose
-inside those sections may stay in your team language.
-
-This is the most labor-intensive step. Recommended approach:
-
-1. Open `TEMPLATE-LANGUAGE-GLOSSARY.md` for the heading-by-heading
-   mapping.
-2. For each generated spec file, replace Chinese H2 / H3 headings,
-   table column labels, and bold inline labels with their canonical
-   English form.
-3. Leave free prose (descriptions, decision rationale, task text) in
-   the team language. The Prose Language convention recorded in
-   `dflow/specs/shared/_conventions.md` applies here — see also
-   step 6 below.
-
-An AI assistant can walk through each spec file heading-by-heading
-faster than a global search-and-replace, because earlier Dflow
-adoption may have used slightly different wording per team. After
-translation, run a project-wide search for the most common Chinese
-headings to catch missed files. Adjust the search list to match the
-templates your team actually used:
-
-```bash
-grep -rn "## 業務規則\|## 行為情境\|## 領域模型" dflow/specs/
-```
-
-### 4. Switch the init entry point
-
-Pre-V1 documentation may have instructed teammates to start a Dflow
-project by running `/dflow:init-project` from inside an AI agent. V1
-removed that runtime slash command (PROPOSAL-014). The init flow now
-runs as a shell command. Install Dflow globally and run:
-
-```bash
-npm install -g dflow-sdd-ddd
-dflow init
-```
-
-If you cannot or do not want to install globally, use the no-install path:
-
-```bash
-npx dflow-sdd-ddd init
-```
-
-If you already have an initialized project, you do not need to re-run
-`init`. The other `/dflow:*` workflow commands (`/dflow:new-feature`,
-`/dflow:modify-existing`, `/dflow:bug-fix`, `/dflow:new-phase`,
-`/dflow:finish-feature`, `/dflow:verify`, `/dflow:pr-review`) are
-unchanged and continue to work.
-
-Update any team documentation, runbooks, or onboarding notes that
-still reference `/dflow:init-project` so new project setups use the
-shell command instead.
-
-### 5. Adopt multi-AI thin shims
-
-V1 separates the canonical project guide from each per-tool
-instruction file (PROPOSAL-020). The canonical guide lives at
-`dflow/specs/shared/AI-AGENT-GUIDE.md`. Per-tool files (`AGENTS.md`,
-`CLAUDE.md`, `.github/copilot-instructions.md`) are thin
-shims pointing at the canonical guide.
-
-If your project's `CLAUDE.md` (or equivalent) was generated by an
-early Dflow form that wrote a full file rather than a thin shim:
-
-```bash
-dflow configure-agents
-```
-
-This command adds shims for any AI tools you select. `dflow configure-agents`
-does not overwrite an existing `CLAUDE.md`; instead, it writes a
-`dflow/specs/shared/<tool>-md-snippet.md` that you can merge into the
-existing file at your own pace.
-
-If you prefer a fully clean V1 layout, archive the existing root
-instruction file under another name first, then run
-`dflow configure-agents` so it can write the new shim from scratch.
-
-## After Migration
-
-Verify the migrated project:
-
-- Ask the AI agent to run `/dflow:status` and confirm it can locate
-  Dflow flow material and report the project's current state.
-- Open `dflow/specs/shared/_conventions.md` and confirm a `## Prose
-  Language` section exists. If your project predates the
-  prose-language convention (PROPOSAL-015), add the section manually
-  with the correct BCP-47 language tag, for example `zh-TW` or `en`.
-- Run a final grep to confirm no legacy paths or terms remain inside
-  `dflow/specs/`. Adjust the term list to match your earlier Dflow
-  adoption:
-
-```bash
-grep -rn "_共用\|/dflow:init-project" dflow/specs/
-```
-
-## Out of Scope
-
-This guide stays manual on purpose. The items below are not part of
-V1 and may or may not arrive in a later release; do not rely on them
-when planning a migration today.
-
-- Automatic migration of legacy paths or headings.
-- A `dflow doctor` health check command.
-- A `dflow migrate` subcommand that edits files.
-- Automated translation of free prose between languages.
-
-If any of these would help your team, open a docs feedback issue so
-the request is recorded. The maintainer position is not to refuse
-them, only to keep V1 a clean cut.
-
-## Where To Go Next
-
-- `docs/evaluating-dflow.en.md` for what a fresh V1 `init` produces, in
-  case you want to compare against your migrated project.
-- Per-tool walkthroughs under `docs/` for the AI tool you use:
-  - `docs/using-with-claude-code.en.md`
-  - `docs/using-with-codex.en.md`
-- `TEMPLATE-COVERAGE.md` for the V1 logical / generated file parity
-  between Greenfield and Brownfield tracks.
-
-If something in this guide does not match your project's actual
-pre-V1 state, open a docs feedback issue. The guide can be extended
-as new edge cases come in.

package/templates/brownfield/templates/CLAUDE.md

@@ -1,165 +0,0 @@
-# Project: {系統名稱} — {Framework}
-
-**重要：所有開發工作都必須遵循本文件定義的流程。**
-
----
-
-## System Context
-
-> 技術棧、業務領域、目錄結構
-
-### Background
-
-這是一個運行中的既有系統，使用 {Framework} / {Language}，目前持續新增與修改功能。
-目前採用 SDD 流程，同時為 DDD 與 target architecture 做準備。
-
-### Project Structure
-
-```
-dflow/specs/
-├── shared/                   # 專案級治理文件（由 dflow init 寫入）
-│   ├── _overview.md          # 系統現況與 target architecture
-│   └── _conventions.md       # 規格撰寫慣例與模板
-├── domain/                   # 領域知識
-│   ├── glossary.md           # 術語表（Ubiquitous Language）
-│   └── {context}/            # 按 Bounded Context 分
-│       ├── context.md        # Context 邊界與職責
-│       ├── models.md         # 領域模型定義
-│       └── rules.md          # 業務規則目錄
-├── 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 寫一列
-└── migration/
-    └── tech-debt.md          # 技術債與遷移備忘
-
-src/
-├── Domain/                   # 抽離的領域邏輯（framework-pure）
-│   ├── {Context}/
-│   │   ├── Entities/
-│   │   ├── ValueObjects/
-│   │   ├── Services/
-│   │   └── Interfaces/
-│   └── SharedKernel/
-└── Delivery/                 # delivery-layer code（entrypoints, controllers, handlers）
-```
-
-> **目錄命名說明**：上方 `src/Domain/` / `src/Delivery/` 是 Clean
-> Architecture 通用示意，不限 stack。請依專案實際慣例對應（例：Java/Spring 用
-> `src/main/java/com/example/domain/`、Node/TS 用 `src/domain/` /
-> `src/routes/`、Python 用 `domain/` package、Go 用 `internal/domain/` /
-> `internal/handler/`、.NET 用 `src/{Project}.Domain/` + `.csproj` 分層）。
-> 完整 per-stack 範例見 `docs/examples-by-stack.md`。重點是
-> `src/Domain/`（或對應命名）保持與 delivery/entrypoint code 獨立。
-
----
-
-## Development Workflow
-
-> SDD 流程、Git 整合、Domain 層規範、術語表、AI 協作
-
-### Core Principles
-1. **Spec Before Code** — 沒有規格就不寫實作
-2. **Domain Extraction** — 業務邏輯屬於 `src/Domain/`，不屬於 delivery/entrypoint code（presentation/UI layer、controllers、handlers、jobs、message consumers、data pipelines、stored procedures）
-3. **Ubiquitous Language** — 使用 `dflow/specs/domain/glossary.md` 中定義的術語
-4. **Migration Awareness** — 每個決策都要考慮 target architecture
-
-### Three Ceremony Tiers
-
-不是每次修改都要跑完整流程。AI 依下列判準選 tier：
-
-- **T1 Heavy** — 新功能、新 phase、架構變動、新增 BR → 建獨立 phase-spec，
-  走 `/dflow:new-feature` 或 `/dflow:new-phase`
-- **T2 Light** — bug fix、UI 輸入驗證、流程分支修改（有 BR Delta 但無 Domain /
-  資料結構變動）→ 建獨立 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. 識別涉及的領域概念，更新 `dflow/specs/domain/` 下的對應文件
-4. 盡可能將業務邏輯實作在 `src/Domain/` 中（語言純粹的 class，不依賴 delivery framework）
-5. Delivery/entrypoint code 僅負責輸入解析、協調流程與輸出綁定，呼叫 Domain 層處理邏輯
-6. 撰寫測試驗證 Domain 層行為符合規格
-
-### 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. 如果該功能的邏輯還在 delivery/entrypoint code 中，評估是否值得先抽離到 Domain 層
-4. 在 `dflow/specs/migration/tech-debt.md` 記錄發現的技術債
-
-### Bug Fix
-1. 建立輕量規格（問題 + 現有行為 + 預期行為 + 修復方式）
-2. 若 bug 不附掛既有 feature，先建最小 feature 目錄再放 lightweight-spec
-3. 修 Bug 時順便記錄發現的技術債
-
-### Feature Closeout
-1. 驗證 feature 目錄內所有 phase-spec `status: completed`
-2. 把 `_index.md` Current BR Snapshot 同步到 BC 層 `rules.md` / `behavior.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] 簡述變更
-```
-
-**分支規則**
-- **feature/** — 必須先有 spec 才能開始編碼
-- **bugfix/** — 至少要有輕量 spec
-- **`/dflow:bug-fix`** 不綁定任何分支策略；採 Git Flow 的專案可選擇把
-  緊急修復放在 `hotfix/` 分支，但這是專案決策，Dflow 不代為規定
-
-### Domain Layer Rules (`src/Domain/`)
-
-此目錄中的程式碼必須遵守：
-- ❌ 不可引用任何 delivery-framework 命名空間（例：HTTP 請求/回應物件、Session/Cookie context、job runner context、CLI flag parser、ViewState 類等）
-- ❌ 不可直接存取資料庫（使用 interface + Repository pattern）
-- ❌ 不可使用 delivery-framework runtime context（例：HTTP request/response、session/cookie、job runner state、CLI args）
-- ❌ 不可有 UI / entrypoint 相關邏輯（格式化顯示、controller/page/handler 引用）
-- ✅ 語言純粹的 class（不依賴 delivery framework），可直接搬到 target architecture
-- ✅ 所有公開行為都能在沒有 delivery infrastructure 的情況下測試
-
-### Glossary
-
-所有業務術語必須使用 `dflow/specs/domain/glossary.md` 中定義的名稱。
-遇到新術語時，先新增到術語表再使用。
-
-### AI Collaboration Notes
-
-- 開發者提出任何功能需求時，先引導建立 spec
-- 在回答 Domain 相關問題時，優先參考 `dflow/specs/domain/` 中的文件
-- 發現 delivery/entrypoint code 中的業務邏輯時，建議抽離到 `src/Domain/`
-- 每次開發循環結束時，提醒更新術語表和技術債記錄
-- 建立分支前，確認命名符合規範且對應 spec 存在