dflow-sdd-ddd 0.7.0 → 0.8.0

package/templates/greenfield/references/new-feature-flow.md

@@ -0,0 +1,397 @@
+# New Feature Workflow — Greenfield Clean Architecture
+
+Step-by-step guide for adding a new feature with full DDD and Clean Architecture.
+
+Triggered by `/dflow:new-feature` (or natural language implying a new-feature task — see SKILL.md § Workflow Transparency for the auto-trigger safety net behavior).
+
+**Step Gates** in this flow (stop-and-confirm before proceeding):
+- Step 3 → Step 3.5 (Aggregate / VO / Events identified → confirm slug + directory + branch names)
+- Step 4 → Step 5 (spec written → plan implementation)
+- Step 6 → Step 7 (branch ready → start implementation)
+- Step 7 → Step 8 (implementation done → completion)
+
+All other step transitions are **step-internal**: announce "Step N complete, entering Step N+1" and proceed without waiting. See SKILL.md § Workflow Transparency for the full transparency protocol and confirmation signals.
+
+**Ceremony**: this flow always defaults to **T1 Heavy** — the first phase of a brand-new feature is by definition a full SDD cycle. Tier judgement (T1 / T2 / T3) only applies to `/dflow:modify-existing` (see `references/modify-existing-flow.md` and SKILL.md § Ceremony Scaling).
+
+## Step 1: Intake — Understand the Request
+
+Before producing any spec prose, read `dflow/specs/shared/_conventions.md`
+and apply the `## Prose Language` setting. If the setting is missing or not
+an explicit language tag, ask the developer to update `_conventions.md`
+before continuing.
+
+Ask naturally:
+1. **What's the feature?** Plain-language description.
+2. **Who needs it?** Stakeholder or user role.
+3. **Why now?** Priority and urgency.
+
+Check existing assets:
+- Search `dflow/specs/domain/` for related concepts
+- Search `dflow/specs/features/` for related features
+- Check `dflow/specs/domain/glossary.md` and `context-map.md`
+
+**→ Transition (step-internal)**: Step 1 complete. Announce "Step 1 complete (intake). Entering Step 2: Identify the Bounded Context." and continue.
+
+## Step 2: Identify the Bounded Context
+
+Check `dflow/specs/domain/context-map.md`:
+
+```
+"This feature involves [concepts]. It seems to belong in the
+[Context] bounded context. Does that match your understanding?"
+```
+
+If new context needed → use context-definition template.
+
+If it crosses contexts:
+```
+"This touches both [Context A] and [Context B]. We need to decide:
+- Which context OWNS the operation?
+- How does the other context get notified? (Domain Event? Query?)
+- Do we need an Anti-Corruption Layer?"
+```
+
+**→ Transition (step-internal)**: Step 2 complete. Announce "Step 2 complete (BC identified). Entering Step 3: Domain Modeling." and continue.
+
+## Step 3: Domain Modeling
+
+This is where the Greenfield Clean Architecture workflow diverges
+significantly from the Brownfield edition.
+Read `references/ddd-modeling-guide.md` for detailed patterns.
+
+Walk through:
+
+### Aggregate Identification
+```
+"What must be consistent in a single transaction?
+Those things form an Aggregate. Everything else is eventually consistent."
+```
+
+- What are the invariants?
+- What is the Aggregate Root?
+- What entities belong inside this Aggregate?
+- What Value Objects can we extract?
+
+### Domain Events
+```
+"After this happens, what else in the system needs to know?"
+```
+
+- What events does this feature produce?
+- What events does it consume?
+- Are handlers in the same context (synchronous) or cross-context (async)?
+
+### Interface Definitions
+```
+"What external data does the domain need to make decisions?"
+```
+
+- Repository interfaces for persistence
+- Service interfaces for external systems
+- Define in Domain layer, implement in Infrastructure
+
+If foundational domain docs are missing, create them from templates before writing content:
+- `dflow/specs/domain/glossary.md` → `templates/glossary.md`
+- `dflow/specs/domain/{context}/models.md` → `templates/models.md`
+- `dflow/specs/domain/{context}/rules.md` → `templates/rules.md`
+- `dflow/specs/domain/{context}/behavior.md` → `templates/behavior.md` — at this step create only the skeleton + one section anchor per `BR-*`; the Given/When/Then scenarios are merged in later at Step 8.3 (finish-feature), not now
+- `dflow/specs/domain/{context}/events.md` (when Domain Events are involved) → `templates/events.md`
+- `dflow/specs/domain/context-map.md` (when cross-context relationships are involved) → `templates/context-map.md`
+
+**→ Step Gate: Step 3 → Step 3.5**
+
+Announce to developer:
+> "Aggregate / VO / Events identified. Before I create any files, let me confirm the SPEC-ID, slug, directory name, and branch name with you (Step 3.5). `/dflow:next` to proceed."
+
+Wait for confirmation before entering Step 3.5.
+
+## Step 3.5: Slug Confirmation
+
+AI proposes the SPEC-ID, slug, feature directory path, and branch name in
+one message and asks the developer to confirm before any directory or
+branch is created. Slug follows the language of the discussion (中文 or
+English — both are valid; see `references/git-integration.md` for the slug
+language rule).
+
+Before confirming, surface the path-encoding caveat: a non-ASCII (e.g. 中文)
+slug yields non-ASCII feature-directory and branch paths. These work on common
+Git hosts but a handful of CI runners / toolchains mishandle them. If the
+project's pipeline is unknown, offer an ASCII slug as an alternative. See
+`references/git-integration.md` for the full risk note.
+
+Example (中文 discussion):
+
+> 「依我們的討論：
+>  - SPEC-ID: `SPEC-20260424-001`
+>  - slug: `報表調整`（跟隨中文討論）
+>  - feature 目錄: `dflow/specs/features/active/SPEC-20260424-001-報表調整/`
+>  - git branch: `feature/SPEC-20260424-001-報表調整`
+>
+>  這樣可以嗎？或你想改 slug？」
+
+Example (English discussion):
+
+> "Per our discussion:
+>  - SPEC-ID: `SPEC-20260424-002`
+>  - slug: `submit-expense-report` (English following our discussion)
+>  - feature directory: `dflow/specs/features/active/SPEC-20260424-002-submit-expense-report/`
+>  - git branch: `feature/SPEC-20260424-002-submit-expense-report`
+>
+>  Sound good? Or would you prefer a different slug?"
+
+Wait for explicit confirmation. The slug agreed here is reused for:
+- The feature directory name
+- The first phase-spec filename (`phase-spec-{date}-{slug}.md`)
+- The git branch (Step 6)
+
+If the developer asks to change the slug, re-propose and re-confirm.
+
+**→ Transition (step-internal)**: Step 3.5 complete. Announce "Step 3.5 complete (slug confirmed). Entering Step 4: Write the Spec." and continue.
+
+## Step 4: Write the Spec
+
+Create the **feature directory** + **`_index.md`** + **first phase-spec**:
+
+```
+dflow/specs/features/active/{SPEC-ID}-{slug}/
+├── _index.md
+└── phase-spec-{YYYY-MM-DD}-{slug}.md
+```
+
+1. **Create the directory**: `dflow/specs/features/active/{SPEC-ID}-{slug}/`
+2. **Create `_index.md`** using `templates/_index.md`:
+   - Metadata: fill `spec-id`, `slug`, `status: in-progress`, `created`, `branch`
+   - Goals & Scope: 1-3 sentences capturing what / for whom / boundary; mention
+     the BC and Aggregate(s) involved
+   - Phase Specs: one row for the first phase
+     (`| 1 | {date} | {slug} | in-progress | [phase-spec-{date}-{slug}.md](./phase-spec-{date}-{slug}.md) |`)
+   - Current BR Snapshot: initialise from the first phase's planned BRs
+     (will be refreshed when the phase-spec finalises)
+   - Lightweight Changes: empty table at start
+   - Resume Pointer: "phase-1 in progress: drafting phase-spec." / "Next Action: finish phase-spec, then implement Domain layer."
+3. **Create the first phase-spec** at `phase-spec-{YYYY-MM-DD}-{slug}.md`
+   using `templates/phase-spec.md`. The "Delta from prior phases" section
+   is filled with "首 phase，無前置 Delta" (first phase has nothing to
+   delta against).
+4. **If this feature introduces a new Aggregate**, also create an
+   `aggregate-design.md` from `templates/aggregate-design.md` **inside this
+   feature directory** as the per-Aggregate design worksheet. It is a working
+   artifact scoped to the feature; the Aggregate's durable, long-lived catalog
+   entry still lives in `dflow/specs/domain/{context}/models.md`.
+   `aggregate-design.md` complements `models.md`, it does not replace it.
+
+Key additions compared to Brownfield edition:
+- **Aggregate State Transitions**: Document how Aggregate state changes
+- **Domain Events**: List events produced and expected handlers
+- **CQRS Split**: Identify which parts are Commands (write) vs Queries (read)
+
+### Behavior Specification
+```gherkin
+Scenario: Submit expense report
+  Given an expense report in Draft status with 3 line items totaling 5,000 TWD
+  When the employee submits the report
+  Then the report status changes to Submitted
+  And a ExpenseReportSubmitted event is raised
+  And the report can no longer be modified
+```
+
+**→ Step Gate: Step 4 → Step 5**
+
+Announce to developer:
+> "Spec is drafted — behavior scenarios, Aggregate state transitions, Domain Events, and CQRS split are captured. Ready to plan the layer-by-layer implementation (Domain → Application → Infrastructure → Presentation)? `/dflow:next` or reply 'OK' to continue, or tell me if the spec needs another iteration first."
+
+Wait for confirmation (`/dflow:next`, verbal OK, or implicit — see SKILL.md § Confirmation Signals) before entering Step 5.
+
+## Step 5: Plan the Implementation (Layer by Layer)
+
+### Domain Layer (implement first)
+```
+1. Create/update Aggregate Root with state-changing methods
+2. Create Value Objects with validation in constructors
+3. Define Domain Events (record types)
+4. Define Repository interface
+5. Write Domain unit tests
+```
+
+### Application Layer (implement second)
+```
+1. Create Command + CommandHandler (for writes)
+2. Create Query + QueryHandler (for reads)
+3. Create CommandValidator (FluentValidation)
+4. Create Domain Event handlers (if needed)
+5. Define DTOs for input/output
+```
+
+### Infrastructure Layer (implement third)
+```
+1. ORM / persistence configuration (mapping configuration, NOT Domain attributes/annotations)
+2. Repository implementation
+3. External service adapters
+4. Migration script
+```
+
+### Presentation Layer (implement last)
+```
+1. API endpoint (Controller or Minimal API)
+2. Request/Response models
+3. Swagger documentation
+```
+
+### Generate Implementation Tasks List
+
+After the layer-by-layer plan is agreed, AI generates a concrete task list and writes it into the spec's `Implementation Tasks` section (see `templates/phase-spec.md`). Each task follows `[LAYER]-[NUMBER]：description` and maps to Clean Architecture layers:
+
+- `DOMAIN` — Aggregate / Entity / VO / Domain Event / Domain Service / Repository Interface
+- `APP`    — Command/Query / Handler / Validator / DTO / Event Handler
+- `INFRA`  — EF Configuration / Repository Impl / external adapter / Migration
+- `API`    — Controller / Minimal API / Request/Response / Swagger
+- `TEST`   — Tests per layer
+
+Recommended authoring order mirrors implementation order: `DOMAIN → APP → INFRA → API` (with `TEST` interleaved).
+
+Example seed (replace with feature-specific tasks):
+
+```markdown
+- [ ] DOMAIN-1：ExpenseReport aggregate with Submit() state transition
+- [ ] DOMAIN-2：ExpenseReportSubmitted domain event
+- [ ] APP-1：SubmitExpenseReportCommand + Handler
+- [ ] INFRA-1：EF config + ExpenseReportRepository
+- [ ] API-1：POST /expense-reports/{id}/submit endpoint
+- [ ] TEST-1：Aggregate invariants + handler unit tests
+```
+
+The list becomes the execution punch-list for Step 7 and the completion checklist in Step 8.
+
+**→ Transition (step-internal)**: Step 5 complete. Announce "Step 5 complete (layer-by-layer plan + task list ready). Entering Step 6: Git Branch." and continue.
+
+## Step 6: Git Branch
+
+```
+Branch naming: feature/{SPEC-ID}-{slug}
+Examples:
+  feature/SPEC-20260424-002-submit-expense-report   (English slug)
+  feature/SPEC-20260424-001-報表調整                  (Chinese slug)
+```
+
+The slug **must match the slug agreed in Step 3.5** (which is also the
+feature directory name). The SPEC-ID + slug links the branch to its
+feature directory and `_index.md`.
+
+**→ Step Gate: Step 6 → Step 7**
+
+Announce to developer:
+> "Branch `feature/{SPEC-ID}-{description}` is created. Ready to start layer-by-layer implementation (Domain first)? `/dflow:next` to proceed, or discuss layer order / scope first."
+
+Wait for confirmation before entering Step 7.
+
+## Step 7: Implementation Checklist
+
+During implementation, continuously verify:
+
+**Domain Layer**
+- [ ] Aggregate protects all invariants
+- [ ] State changes only through methods (no public setters)
+- [ ] Value Objects are immutable with validation
+- [ ] Domain Events raised for significant state changes
+- [ ] Zero external dependencies (check the Domain package/module manifest)
+- [ ] Unit tests cover invariants and business rules
+
+**Application Layer**
+- [ ] No business logic in handlers (only orchestration)
+- [ ] Command/Query separation maintained
+- [ ] Validation in Validator, not Handler
+- [ ] DTOs map to/from Domain objects (no Domain objects in API)
+
+**Infrastructure Layer**
+- [ ] EF Config in Fluent API (no attributes on Domain entities)
+- [ ] Repository implements Domain interface correctly
+- [ ] No business logic in queries
+
+**Presentation Layer**
+- [ ] Controller is thin (parse → dispatch → respond)
+- [ ] No domain objects exposed to API consumers
+- [ ] Proper HTTP status codes
+
+**→ Step Gate: Step 7 → Step 8**
+
+Announce to developer:
+> "Implementation appears complete across all four layers. Ready to run the completion checklist (verify against spec, update domain docs + context-map, ensure test coverage, archive the spec)? `/dflow:next` to proceed."
+
+Wait for confirmation before entering Step 8. This step gate is where the completion checklist is triggered — do not skip.
+
+## Step 8: Completion
+
+Triggered by the Step 7 → Step 8 Step Gate. AI runs the completion checklist in the order below; do **not** skip a section.
+
+### 8.1 Verification — AI runs independently
+
+AI reports `✓` / `✗` for every item before touching docs. Items marked *(post-8.3)* are re-verified after the documentation merge in 8.3 lands:
+
+- [ ] `Implementation Tasks` section: all tasks checked, or unchecked items explicitly labelled as follow-up (linked to spec / tech-debt entry)
+- [ ] Every `Given/When/Then` scenario in the spec is covered by implementation or tests
+- [ ] Every `BR-*` business rule is covered by implementation or tests
+- [ ] Every `EC-*` edge case is handled
+- [ ] Every Domain Event listed in the spec is raised in the implementation
+- [ ] Domain layer/package has **no** external package-manager dependencies beyond the language/runtime baseline
+- [ ] Aggregate invariants still hold after the change (all state changes go through methods, no public setters)
+- [ ] ORM / persistence mapping is kept outside Domain entities (no persistence attributes/annotations on Domain entities)
+- [ ] *(post-8.3)* `dflow/specs/domain/{context}/behavior.md` contains a section anchor for every `BR-*` introduced by this spec (mechanical input for `/dflow:verify`)
+- [ ] *(post-8.3)* `dflow/specs/domain/{context}/behavior.md` `last-updated` is later than this spec's `created` date (mechanical drift guard)
+
+If any item fails, report the gap and pause — don't proceed to 8.2.
+
+### 8.2 Verification — needs developer confirmation
+
+AI lists findings one at a time and waits for the developer to confirm each:
+
+- [ ] Does the implementation faithfully express the **intent** of each BR? (AI lists BR → impl location; developer judges fit)
+- [ ] Are the edge case handling decisions appropriate? (AI lists EC → handling; developer judges)
+- [ ] Are Domain Event payloads and handler placements (same-context sync vs cross-context async) correct? (AI lists; developer confirms)
+- [ ] Did we miss any tech debt worth recording?
+- [ ] Do the scenarios merged into `behavior.md` (incl. Aggregate transitions + Events) faithfully express the intended behavior? (AI lists merged anchors; developer judges)
+- [ ] Should the `Implementation Tasks` section in the spec be collapsed / removed now that it's complete? (team convention — developer decides)
+
+Ask these one-by-one; do not dump all six at once.
+
+### 8.3 Documentation updates
+
+- [ ] `dflow/specs/domain/glossary.md` — new terms added
+- [ ] `dflow/specs/domain/{context}/models.md` — model definitions updated
+- [ ] `dflow/specs/domain/{context}/rules.md` — business rules updated
+- [ ] `dflow/specs/domain/{context}/behavior.md` — merge completed spec's Given/When/Then scenarios (incl. Aggregate transitions + Events) into consolidated behavior. Sub-steps:
+      - Promote any Activity 3 (Spec Writing) draft sections (from B3 mid-sync) to formal sections
+      - Update the corresponding `rules.md` anchor's `last-updated` date (B4)
+- [ ] `behavior.md` draft cleanup — if the spec was abandoned mid-way, keep the `## 提案中變更` section's history or explicitly REMOVE it
+- [ ] `dflow/specs/domain/{context}/events.md` — Domain Events updated
+- [ ] `dflow/specs/domain/context-map.md` — updated if cross-context interaction was added or changed
+- [ ] `dflow/specs/architecture/tech-debt.md` — tech debt discovered during implementation recorded
+
+### 8.4 Archival
+
+For a single-phase feature, this is the closeout point. For a multi-phase
+feature, the developer typically reaches this point at the end of the
+final phase — at which time `/dflow:finish-feature` is the recommended
+trigger (it bundles steps 8.1 / 8.2 verification, BC sync, and archival
+into one explicit ceremony). Either path is acceptable; pick the one
+that matches the developer's habit.
+
+- [ ] `_index.md` `status` field changed to `completed`
+- [ ] All `phase-spec-*.md` files in the feature directory have `status:
+      completed` in their frontmatter
+- [ ] **Whole feature directory** moved from `dflow/specs/features/active/`
+      to `dflow/specs/features/completed/` using `git mv` (preserves rename
+      tracking — see `references/git-integration.md` § "Directory Moves
+      Must Use git mv"):
+      ```
+      git mv dflow/specs/features/active/{SPEC-ID}-{slug} \
+             dflow/specs/features/completed/{SPEC-ID}-{slug}
+      ```
+
+> **Recommended path for multi-phase features**: instead of doing
+> 8.1–8.4 manually at the end of every phase, run `/dflow:finish-feature`
+> once the feature's last phase is complete. It executes the same checks
+> + BC sync + `git mv` + emits an Integration Summary. See
+> `references/finish-feature-flow.md`.
+
+Only announce "feature complete" after 8.4 is done.

package/templates/greenfield/references/new-phase-flow.md

@@ -0,0 +1,273 @@
+# New Phase Workflow — Greenfield Clean Architecture
+
+Step-by-step guide for when a developer triggers `/dflow:new-phase` —
+adding a new phase-spec to an **active** feature directory.
+
+A phase-spec captures one full "Kickoff → Domain → Design → Build → Verify"
+cycle. A feature can have N phase-specs over its lifetime; together they
+build up the feature in iterations. The `_index.md` dashboard aggregates
+their state.
+
+**Distinction from `/dflow:new-feature`**: this command does NOT create a
+branch and does NOT create a feature directory. Both must already exist
+(produced by the original `/dflow:new-feature` invocation). This command
+adds a new phase to an in-progress feature only.
+
+**Step Gates** in this flow (stop-and-confirm before proceeding):
+- Step 3 → Step 4 (phase scope confirmed → write the phase-spec)
+- Step 4 → Step 5 (phase-spec drafted → refresh `_index.md`)
+- Step 5 → Step 6 (`_index.md` refreshed → start implementation)
+- Step 6 → Step 7 (implementation done → complete the phase)
+
+All other step transitions are **step-internal**: announce "Step N complete,
+entering Step N+1" and proceed without waiting. See SKILL.md § Workflow
+Transparency for the full transparency protocol and confirmation signals.
+
+## Step 1: Read Active Feature Context
+
+Before producing any spec prose, read `dflow/specs/shared/_conventions.md`
+and apply the `## Prose Language` setting. If the setting is missing or not
+an explicit language tag, ask the developer to update `_conventions.md`
+before continuing.
+
+AI must locate the target feature and load its current state:
+
+1. **Identify the target feature**
+   - If the developer is on a `feature/{SPEC-ID}-{slug}` branch → infer the
+     feature directory at `dflow/specs/features/active/{SPEC-ID}-{slug}/`
+   - Otherwise → ask the developer which feature this phase is for
+
+2. **Refuse if the feature is in `completed/`**
+
+   `/dflow:new-phase` strictly applies to **active features only**. If the
+   target feature directory is found at `dflow/specs/features/completed/...`
+   instead of `dflow/specs/features/active/...`, refuse with:
+
+   ```
+   "Feature `{SPEC-ID}-{slug}` is in completed/ — completed features are
+   frozen history and cannot accept new phases.
+
+   If you need to extend this feature's behavior, run /dflow:modify-existing
+   and choose the 'follow-up' branch — that creates a new follow-up feature
+   with a fresh SPEC-ID and a `follow-up-of: {SPEC-ID}` link back to this
+   one."
+   ```
+
+   Do NOT offer to `git mv` the feature back to `active/` — that breaks the
+   completed = frozen-history semantic and produces confusing dir-rename
+   history. The follow-up path is the only correct route.
+
+3. **Load context for the new phase**
+   - Read the feature's `_index.md` — Metadata, Goals & Scope, Phase Specs,
+     Current BR Snapshot, Resume Pointer
+   - Read the most recent phase-spec to understand where the prior phase
+     left off (its Business Rules and Delta-from-prior-phases sections in
+     particular)
+   - Cross-reference the bounded context's `dflow/specs/domain/{context}/rules.md`
+     and `behavior.md` if the new phase is likely to touch system-level
+     state (BC-level current state lives there, not in `_index.md`)
+
+Share what you found:
+
+> "OK — `{SPEC-ID}-{slug}` has {N} prior phases in BC `{context}`. The
+> most recent (phase-{N}) ended with {一句話 from Resume Pointer}. Current BR
+> Snapshot has {count} active BRs. Ready to scope the new phase."
+
+**→ Transition (step-internal)**: Step 1 complete. Announce "Step 1 complete (active feature context loaded). Entering Step 2: Confirm Phase Scope." and continue.
+
+## Step 2: Confirm the Phase Scope
+
+Walk the developer through what the new phase covers:
+
+1. **What does this phase add or change?** Plain-language description.
+2. **Which BRs are touched?** Compare against the current BR Snapshot. New
+   BRs (ADDED), changed BRs (MODIFIED), removed BRs (REMOVED), renamed
+   (RENAMED). Items not mentioned stay UNCHANGED implicitly.
+3. **Any Aggregate / Domain concepts introduced or changed?** New
+   Aggregates, Value Objects, Domain Events, or invariants?
+4. **Cross-context impact?** Does this phase introduce / change Domain
+   Events that other contexts consume? (If yes, plan for `context-map.md`
+   updates at finish-feature time.)
+5. **Data structure impact?** New tables, columns, indices, EF
+   configuration changes?
+6. **Why now?** Priority — informs sequencing relative to other phases.
+
+This is also the moment to ask: "Should this be its own follow-up feature
+instead of a phase here?" — useful when the scope drift suggests a
+separate concern (different Aggregate, different BC, etc.).
+
+**→ Transition (step-internal)**: Step 2 complete. Announce "Step 2 complete (phase scope agreed). Entering Step 3: Phase Slug Confirmation." and continue.
+
+## Step 3: Phase Slug Confirmation
+
+AI proposes the new phase-spec filename and asks the developer to confirm
+before any file is written.
+
+> "Proposed phase-spec for `{SPEC-ID}-{slug}`:
+>
+>     phase-spec-{YYYY-MM-DD}-{phase-slug}.md
+>
+> Phase slug follows our discussion language (中文/英文皆可). Do you want
+> to keep `{phase-slug}`, or use a different slug?"
+
+Slug rules (matches the feature-level slug rule):
+- Follows the language the developer / AI discuss the phase in (no forced
+  translation)
+- Keep it short (2–4 words / 2–6 中文字)
+- Avoid characters that would break filesystems on the developer's
+  platform (slashes, colons, etc.)
+
+Wait for the developer to confirm before proceeding.
+
+**→ Step Gate: Step 3 → Step 4**
+
+Announce to developer:
+> "Phase slug confirmed as `{phase-slug}`. Ready to draft the phase-spec
+> (`phase-spec-{date}-{phase-slug}.md`) — I'll cover problem / domain
+> modeling / behavior (with Aggregate transitions + Events) / business
+> rules / Delta-from-prior-phases / edge cases / layer-by-layer
+> implementation plan? `/dflow:next` to proceed, or adjust the scope
+> first."
+
+Wait for confirmation before entering Step 4.
+
+## Step 4: Write the Phase Spec
+
+Create the file at:
+
+```
+dflow/specs/features/active/{SPEC-ID}-{slug}/phase-spec-{YYYY-MM-DD}-{phase-slug}.md
+```
+
+Use the `templates/phase-spec.md` template and set the phase-spec
+frontmatter `status` to `in-progress`. Phase-2-onward specs **must** fill
+in the **Delta from prior phases** section (the first phase typically has
+just "首 phase，無前置 Delta"; this is phase 2+, so the section is required).
+
+Walk the developer through each section, in the same way `new-feature-flow`
+Step 4 does — Behavior (with Aggregate state transitions and Domain
+Events) / Business Rules / Delta / Edge Cases / Domain Events / layer-by-
+layer implementation plan — but only list NEW or MODIFIED BRs in Business Rules;
+UNCHANGED BRs from prior phases stay in the Current BR Snapshot table on
+`_index.md` and are NOT re-copied here. The Delta section uses the same
+ADDED / MODIFIED / REMOVED / RENAMED + optional UNCHANGED format defined
+in `references/modify-existing-flow.md` (Aggregate state transitions and
+Domain Events go in the Given/When/Then within each Delta entry).
+
+After the spec body is drafted, generate the `Implementation Tasks` section
+(format `[LAYER]-[NUMBER]：description` with Core layer tags
+DOMAIN / APP / INFRA / API / TEST — see `new-feature-flow.md` Step 5 for
+the detailed list, recommended order: DOMAIN → APP → INFRA → API).
+
+**→ Step Gate: Step 4 → Step 5**
+
+Announce to developer:
+> "Phase-spec drafted at
+> `dflow/specs/features/active/{SPEC-ID}-{slug}/phase-spec-{date}-{phase-slug}.md`.
+> Ready to refresh `_index.md` (add Phase Specs row, regenerate Current BR
+> Snapshot from the Delta)? `/dflow:next` to proceed."
+
+Wait for confirmation before entering Step 5.
+
+## Step 5: Refresh `_index.md`
+
+Update the feature's `_index.md`:
+
+1. **Phase Specs table** — add a new row for this phase:
+   ```
+   | {N+1} | {YYYY-MM-DD} | {phase-slug} | in-progress | [phase-spec-{date}-{phase-slug}.md](./phase-spec-{date}-{phase-slug}.md) |
+   ```
+
+2. **Current BR Snapshot table** — regenerate to reflect the new phase's
+   Delta:
+   - **ADDED** entries → new rows (First Seen = `phase-{N+1}`, Last Updated =
+     `phase-{N+1}`, Status = `active`)
+   - **MODIFIED** entries → update Current Rule + bump Last Updated to `phase-{N+1}`
+   - **REMOVED** entries → flip Status to `removed`, bump Last Updated to
+     `phase-{N+1}` (do NOT delete the row — keep the audit trail)
+   - **RENAMED** entries → update BR-ID / Current Rule as appropriate; bump
+     Last Updated
+
+3. **Resume Pointer** — update to "phase-{N+1} in progress:
+   {one-line about what's actively being worked on}" and "Next Action:
+   implement DOMAIN-1 / write Aggregate ... / etc."
+
+The Snapshot is the feature-level CURRENT STATE, not history. Do not let
+it grow into a cumulative log; the per-phase Delta sections are the
+historical audit trail. The bounded context's `rules.md` / `behavior.md`
+remain the system-level current state and are NOT updated here — that
+synchronisation happens at `/dflow:finish-feature`.
+
+After the refresh, summarize for the developer:
+> "Phase-spec ready, `_index.md` refreshed. Snapshot now shows
+> {n_active} active BRs ({n_added} added in this phase, {n_modified}
+> modified, {n_removed} removed). Ready to enter Step 6 —
+> follow the phase-spec's Implementation Tasks list (DOMAIN → APP → INFRA → API)?
+> `/dflow:next` to proceed, or adjust the plan first."
+
+**→ Step Gate: Step 5 → Step 6**
+
+Wait for confirmation before entering Step 6.
+
+## Step 6: Implement and Verify the Phase
+
+Follow the phase-spec's `Implementation Tasks` in the recommended layer order:
+DOMAIN → APP → INFRA → API, with TEST tasks interleaved where they prove the
+layer behavior.
+
+During implementation, continuously verify:
+
+- [ ] `Implementation Tasks` are checked off as they complete, or unchecked
+      items are explicitly labelled as follow-up
+- [ ] Every ADDED / MODIFIED / REMOVED / RENAMED Delta entry is covered by
+      implementation or tests
+- [ ] Every affected `BR-*` business rule is covered by implementation or tests
+- [ ] Every affected Given/When/Then scenario is covered by implementation or tests
+- [ ] New or changed Domain Events are raised in the implementation
+- [ ] Aggregate invariants still hold after the change
+- [ ] Domain layer remains framework-pure; EF configuration stays in Infrastructure
+- [ ] No business logic leaks into Application handlers, Infrastructure queries,
+      or Presentation controllers
+- [ ] Test failures have been resolved or explicitly recorded as follow-up
+
+If implementation changes the agreed Delta, update the phase-spec before
+continuing. Do not let code and spec diverge silently.
+
+**→ Step Gate: Step 6 → Step 7**
+
+Announce to developer:
+> "Phase implementation appears complete and verified against the phase-spec.
+> Ready to mark this phase completed and update `_index.md`? `/dflow:next`
+> to proceed."
+
+Wait for confirmation before entering Step 7.
+
+## Step 7: Complete the Phase
+
+Update the feature artifacts:
+
+1. **Phase spec status** — change this phase-spec's frontmatter `status`
+   from `in-progress` to `completed`.
+2. **Implementation Tasks** — keep completed tasks checked. If any task is not
+   done, mark it explicitly as follow-up and link to the relevant future
+   phase, issue, or tech-debt entry.
+3. **Phase Specs table** — update this phase's `_index.md` row from
+   `in-progress` to `completed`.
+4. **Current BR Snapshot** — reconcile the snapshot against the implemented
+   Delta. If implementation changed the Delta, update the phase-spec first,
+   then regenerate the snapshot.
+5. **Resume Pointer** — update to one of:
+   - "phase-{N+1} completed; next action: run `/dflow:new-phase` for the next
+     slice"
+   - "phase-{N+1} completed; next action: run `/dflow:finish-feature` if the
+     feature is ready to wrap up"
+
+The bounded context's `rules.md` / `behavior.md` / `events.md` and the
+feature directory move to `completed/` remain `/dflow:finish-feature`
+responsibilities. Do not sync BC-level current state or archive the whole
+feature from `/dflow:new-phase`.
+
+After completion, summarize for the developer:
+> "Phase {N+1} is implemented and marked completed. `_index.md` is refreshed.
+> If another slice is needed, run `/dflow:new-phase`; if the feature is done,
+> run `/dflow:finish-feature`."