dflow-sdd-ddd 0.8.0 → 0.10.0

package/templates/brownfield/scaffolding/AI-AGENT-GUIDE.md

@@ -13,6 +13,42 @@ This project uses Dflow for spec-first AI-assisted development.
 | Migration / legacy context | {migration-context} |
 | Prose language | {prose-language} |
 
+## Why This Matters
+
+This project has business logic embedded in delivery/entrypoint code
+(presentation/UI layer, controllers, handlers, jobs, message consumers, data
+pipelines, or stored procedures), direct SQL in entrypoints, and duplicated
+calculations across multiple flows. Every feature developed without specs makes
+the target architecture harder to reach; every spec written and every domain
+concept extracted makes it easier to reach.
+
+Your role is not to lecture — it's to ask the right questions at the right time
+so developers naturally produce three assets with every change:
+
+1. **Spec documents** — future requirements documentation
+2. **Domain layer code** — portable to a cleaner future architecture
+3. **Tech debt records** — migration guide entries
+
+## Scope: When Brownfield Applies
+
+Dflow Brownfield is designed for existing systems where:
+
+- **Business rules and domain concepts** can be extracted and re-expressed as
+  portable code (entities, value objects, services, repository interfaces)
+- **Business logic is currently embedded in delivery/entrypoint code** —
+  presentation/UI layer, controllers, handlers, jobs, message consumers, data
+  pipelines, or stored procedures — making changes risky and slow
+- The team wants to **gradually move toward a cleaner architecture** without a
+  full rewrite
+
+It is **not** a fit for:
+
+- Pure infrastructure scripts (deployment, monitoring) without a stable domain
+  model
+- Data pipelines or batch jobs that are purely transformational with no
+  business-rule complexity
+- Greenfield projects (use the Greenfield track instead)
+
 ## Before Editing Code
 
 Do not jump from a request directly to code. First identify the matching
@@ -28,7 +64,7 @@ are not available in the current AI tool:
 | `/dflow:bug-fix` | A defect can be described with expected vs actual behavior. |
 | `/dflow:new-phase` | An active feature needs another implementation slice. |
 | `/dflow:finish-feature` | Implementation is complete and needs drift closure. |
-| `/dflow:verify` | Specs, domain docs, implementation, and tests need consistency checks. |
+| `/dflow:verify` | A bounded context's domain docs (`rules.md` ↔ `behavior.md`) need a consistency / drift check. |
 | `/dflow:pr-review` | A change is ready for SDD/DDD review. |
 | `/dflow:report-dflow-feedback` | You found a Dflow issue or improvement and want a sanitized upstream feedback draft. |
 | `/dflow:status` | You need the current workflow state, current step, completed work, in-progress work, remaining work, pending decision, and next valid action. |
@@ -45,7 +81,7 @@ Machine-readable source for rendering tool-specific thin wrappers:
 | bug-fix | /dflow:bug-fix | Investigate a defect described by expected vs actual behavior. | expected vs actual | workflow |
 | new-phase | /dflow:new-phase | Add another implementation slice to an active feature. | feature id or phase goal | workflow |
 | finish-feature | /dflow:finish-feature | Close implementation with drift checks and archived feature state. | feature id | workflow |
-| verify | /dflow:verify | Check specs, domain docs, implementation, and tests for consistency. | area or feature id | workflow |
+| verify | /dflow:verify | Check a bounded context's domain docs (`rules.md` ↔ `behavior.md`) for consistency. | bounded context or all | workflow |
 | pr-review | /dflow:pr-review | Review a ready change for SDD/DDD alignment. | change or branch | workflow |
 | report-dflow-feedback | /dflow:report-dflow-feedback | Draft sanitized upstream feedback about Dflow. | issue or improvement | workflow |
 | status | /dflow:status | Report current workflow state and next valid action. | - | control |
@@ -53,6 +89,27 @@ Machine-readable source for rendering tool-specific thin wrappers:
 | cancel | /dflow:cancel | Abort the active workflow and return to free conversation. | - | control |
 <!-- dflow-command-registry:end -->
 
+## Routing Non-Command Input
+
+Not every developer message maps to a `/dflow:*` workflow. Route non-command
+input like this (supporting files live in the workflow bundle at
+`dflow/specs/shared/dflow-workflows/`):
+
+- **"Quick question about..." / "How does X work?"** → check
+  `dflow/specs/domain/` first and answer from the documented domain knowledge.
+  If no spec exists yet, suggest documenting the answer as domain knowledge.
+- **"What should I work on next?" / sprint planning** → review
+  `dflow/specs/features/backlog/` and suggest work based on migration value.
+- **"I'm creating a branch"** → read `references/git-integration.md`; verify
+  branch naming and ensure a spec exists before coding starts.
+- **"Dflow seems wrong" / "this template is confusing"** (or you notice Dflow
+  guidance drift) → suggest `/dflow:report-dflow-feedback`; never submit
+  anything upstream automatically.
+- **Anything else code-related** → assess whether it touches business logic. If
+  it does, use the auto-trigger safety net (suggest the matching `/dflow:*`
+  command and wait for confirmation — see § Workflow Transparency); if not, help
+  directly with no ceremony.
+
 ## Status / Control Commands
 
 `/dflow:status` reports active workflow state. Include these fields: workflow,
@@ -71,6 +128,67 @@ workflow was cancelled.
 When no workflow is active, `/dflow:next` and `/dflow:cancel` must report that
 there is no active workflow to advance or cancel.
 
+## Workflow Transparency
+
+Dflow uses a hybrid interaction design: `/dflow:*` commands are the primary
+entry, natural-language auto-trigger is a safety net, and tiered transparency
+keeps the developer aware of where they are in a workflow.
+
+### Auto-Trigger Safety Net
+
+When natural language implies a development task, detect the intent — but do
+**not** auto-enter a workflow. Instead:
+
+1. State your judgment clearly:
+   > "I think this is a new-feature task."
+2. Offer the developer three options:
+   - Type `/dflow:new-feature` to start explicitly
+   - Reply "OK" / "繼續" to confirm this workflow
+   - Or correct the workflow (e.g., "no, this is a bug fix")
+3. Wait for confirmation before entering any workflow.
+
+This addresses three failure modes of pure auto-trigger: missed triggers, wrong
+workflow selection, and invisible state.
+
+### Three-Tier Transparency
+
+During an active workflow, communicate at three levels — no more, no less:
+
+| Level | Trigger point | AI behavior |
+|---|---|---|
+| **Flow entry (must confirm)** | After judging the workflow from NL | Stop and wait for confirmation (command, "OK", or implicit) |
+| **Step gate (notify + optional confirm)** | Before major milestones | Announce the transition; if the developer provides next-step input, treat it as implicit confirmation |
+| **Step-internal (notify only)** | Step N → Step N+1 | Announce "Step N complete, entering Step N+1" — do not wait |
+
+The specific step-gate positions for each workflow live in that flow's own file
+(`dflow/specs/shared/dflow-workflows/references/<flow>.md`), which is the source
+of truth for its gate sequence.
+
+### Confirmation Signals (NL ↔ Command Equivalence)
+
+Any of these count as "proceed to next step" — accept whichever the developer
+uses:
+
+- **Command**: `/dflow:next`
+- **Verbal (English)**: OK / yes / continue / go ahead / sounds good / proceed
+- **Verbal (Chinese)**: 好 / 對 / 繼續 / 可以 / 沒問題
+- **Implicit**: the developer provides the information needed for the next step
+  (e.g., the AI asks "Which Bounded Context?" and the developer answers with the
+  Bounded Context name → implicit confirmation)
+
+The implicit-confirmation rule matters — do not turn every transition into a
+ceremony where the developer must say "OK" before every sentence.
+
+### Completion Checklist Skip Guard
+
+Completion checklists and their step ordering live in the flow files and run at
+the gate each flow specifies (the feature-level completion gate in
+`new-feature-flow` / `modify-existing-flow`, the phase-level gate in
+`new-phase-flow`). Do not run a checklist opportunistically. But if the
+developer skips the gate and commits directly, use the auto-trigger safety net
+to prompt — "It looks like you're wrapping up — should I run the Step N
+completion checklist?" — before giving commit guidance.
+
 ## Source of Truth
 
 Dflow-owned project documents live under `dflow/specs/`.
@@ -85,6 +203,38 @@ Dflow-owned project documents live under `dflow/specs/`.
 | Completed feature snapshots | `dflow/specs/features/completed/` |
 | Technical debt | `dflow/specs/architecture/tech-debt.md` or `dflow/specs/migration/tech-debt.md` |
 
+### Project Structure
+
+The `dflow/specs/` layout Dflow seeds and maintains (Brownfield track):
+
+```
+dflow/specs/
+├── shared/                       # Project-level governance docs (seeded by npx dflow-sdd-ddd init)
+│   ├── _overview.md              # System status & migration strategy
+│   └── _conventions.md           # Spec writing conventions
+├── domain/                       # Domain knowledge (DDD preparation)
+│   ├── glossary.md               # Ubiquitous Language
+│   └── {bounded-context}/        # e.g., expense/, hr/, leave/
+│       ├── context.md            # Context boundary & responsibilities
+│       ├── models.md             # Entity, VO, Aggregate definitions
+│       ├── rules.md              # Business rules index (BR-ID + one-line)
+│       └── behavior.md           # Consolidated behavior (Given/When/Then)
+├── features/
+│   ├── active/                   # Currently in development
+│   │   └── {SPEC-ID}-{slug}/     # One feature = one directory
+│   │       ├── _index.md         # Feature dashboard + BR Snapshot + Resume Pointer
+│   │       ├── phase-spec-YYYY-MM-DD-{slug}.md   # T1: 0..N phase specs
+│   │       └── lightweight-YYYY-MM-DD-{slug}.md  # T2: 0..N lightweight specs
+│   │                                             #     (or BUG-{NUMBER}-{slug}.md)
+│   ├── completed/                # Done (whole feature directory archived here)
+│   └── backlog/                  # Planned
+│   #
+│   # SPEC-ID format: SPEC-YYYYMMDD-NNN; slug follows discussion language (中文 / 英文 both OK).
+│   # T3 trivial changes have NO independent file — just a row in _index.md Lightweight Changes.
+└── migration/
+    └── tech-debt.md              # Issues to fix in the target system
+```
+
 ## Core Rules
 
 1. Spec before code: meaningful behavior changes need a spec or lightweight bug spec before implementation.
@@ -93,6 +243,107 @@ Dflow-owned project documents live under `dflow/specs/`.
 4. Check drift before calling work complete.
 5. Follow `dflow/specs/shared/_conventions.md`, especially `## Prose Language`.
 
+## Ceremony Scaling
+
+Not everything needs full ceremony — match effort to impact. Dflow uses three
+tiers — **T1 Heavy / T2 Light / T3 Trivial** — chosen by the AI per change.
+`/dflow:new-feature` and `/dflow:new-phase` always default to T1 (no judgement
+needed). The criteria below apply when `/dflow:modify-existing` or
+`/dflow:bug-fix` decides which tier fits a modification.
+
+| Tier | Scenario | Output | Command / Trigger |
+|---|---|---|---|
+| **T1 Heavy** | New feature, new phase, architectural change, new BR | Independent `phase-spec-YYYY-MM-DD-{slug}.md` placed in the feature directory + `_index.md` Phase Specs row + refresh BR Snapshot | `/dflow:new-feature` / `/dflow:new-phase` |
+| **T2 Light** | Bug fix, UI input validation tweak, flow branch change — has BR Delta | Independent `lightweight-{YYYY-MM-DD}-{slug}.md` (or `BUG-{NUMBER}-{slug}.md`) inside the feature directory + `_index.md` Lightweight Changes row (outbound link) + refresh BR Snapshot | `/dflow:bug-fix` or `/dflow:modify-existing` (lightweight branch) |
+| **T3 Trivial** | Button colour, copy/text fix, typo, formatting, pure comments — **no BR change, no Domain concept change, no data structure change** | **Inline row in `_index.md` Lightweight Changes only** (no independent spec file) | `/dflow:modify-existing` (`_index-only` branch) |
+
+**T3 criteria** (the AI must satisfy **all four** before classifying T3):
+
+1. No BR-ID change (no ADDED / MODIFIED / REMOVED / RENAMED business rule)
+2. No Domain concept added or changed (Aggregate / Entity / VO / Event)
+3. No data structure change (table, column, relation, index)
+4. Only changes UI surface (colour, text, layout), pure comments, or pure formatting
+
+If any criterion fails → drop to T2; if Domain / BR / data structure is touched → escalate to T1.
+
+**Below T3 — Dflow doesn't track at all**: pure typo fixes, commit-message
+typos, pure formatting commits (e.g. `prettier` / `dotnet format` auto-runs).
+You can `git commit` directly without writing even a T3 inline row.
+
+**Lightweight spec** = Problem + Expected behavior + 1–2 Given/When/Then. The
+instantiated file is placed inside the feature directory (see
+`templates/lightweight-spec.md`).
+
+## Behavior Source of Truth (rules.md + behavior.md)
+
+Each Bounded Context has two complementary files that together describe the
+system's current behavior:
+
+- **`rules.md`** — declarative index: lists each BR-ID with a one-line summary.
+  Quick lookup, easy to scan.
+- **`behavior.md`** — scenario-level detail: the full Given/When/Then scenarios
+  for each BR-ID. This is the consolidated source of truth for "what does the
+  system actually do right now?"
+
+`dflow/specs/features/completed/` is a historical archive (individual change
+records). `behavior.md` is the **merged current state** — when a feature is
+completed, the AI merges its scenarios into `behavior.md`; when behavior is
+modified, the AI updates the corresponding section to reflect the new behavior
+(git preserves history). See the `behavior.md` template in the workflow bundle
+at `dflow/specs/shared/dflow-workflows/templates/behavior.md`.
+
+## Guiding Questions by Activity
+
+SDD has five conceptual activities (Understanding / Domain Analysis / Spec
+Writing / Implementation Planning / Tech Debt Awareness) that the AI walks the
+developer through inside a workflow. They cut across workflow steps — Activity 2
+(Domain Analysis) might span Step 2 and Step 3 of new-feature-flow, for example.
+
+When a developer starts working, guide them with these questions in order. Don't
+dump all questions at once — ask naturally as the conversation progresses.
+
+**Activity markers in the phase-spec template**: each section in
+`templates/phase-spec.md` carries an HTML comment (e.g.,
+`<!-- Fill timing: Activity 2: Domain Analysis -->`) indicating the activity in
+which that section should be filled. These markers align with the activities
+below and are used by `/dflow:status` and the completion checklist to track
+progress. When guiding a developer, fill sections in activity order; do not jump
+ahead to Activity 4 (Implementation Planning) before Activity 3 (Spec Writing)
+is agreed. The `Implementation Tasks` section at the end of the template is
+produced by the AI at the end of Activity 4 — see new-feature-flow.md Step 5 /
+new-phase-flow.md Step 4 / modify-existing-flow.md Step 4.
+
+Note: the phase-spec template HTML comments cover Activity 1–4; Activity 5 (Tech
+Debt Awareness) is a closeout-time concern handled when updating `tech-debt.md`
+during the completion checklist, not via template section markers.
+
+### Activity 1: Understanding (What & Why)
+- What problem does this solve? Who asked for it?
+- What's the expected behavior from the user's perspective?
+- Are there existing specs or domain docs related to this?
+
+### Activity 2: Domain Analysis (Where does it live?)
+- Which Bounded Context does this belong to? (Check dflow/specs/domain/)
+- What domain concepts are involved? (Entities, Value Objects, Services)
+- Are there new terms? → Update glossary.md
+- Are there new or changed business rules? → Document in rules.md
+
+### Activity 3: Spec Writing (Document before coding)
+- Write the spec using the template (see `templates/phase-spec.md`)
+- Define Given/When/Then scenarios for key behaviors
+- Identify edge cases and business rule interactions
+
+### Activity 4: Implementation Planning (How to build it)
+- Can the business logic live in `src/Domain/` as framework-pure code?
+- What interfaces are needed? (Repository, external services)
+- How thin can the delivery/entrypoint code be? (Ideally: parse input → call Domain → return or display result)
+
+### Activity 5: Tech Debt Awareness (What did we find?)
+- Did we discover scattered business logic? → Record in tech-debt.md
+- Are there duplicated calculations? → Record
+- Direct SQL in delivery/entrypoint code? → Record
+- Magic numbers or undocumented statuses? → Record and add to glossary
+
 ## Pre-V1 Artifacts Detection
 
 When working in a project that adopted Dflow before `dflow-sdd-ddd@0.1.0`,

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

@@ -11,10 +11,9 @@
 > - Use this legacy snippet only if you intentionally want the older
 >   Claude-specific two-H2 layout in your project's root `CLAUDE.md`.
 
-The snippet follows the Dflow `templates/CLAUDE.md` H2 segmentation:
-**System Context** (what the system is) and **Development Workflow**
-(how we work). Keep those two H2 sections as the backbone when merging
-into an existing `CLAUDE.md`.
+The snippet uses a two-H2 segmentation: **System Context** (what the
+system is) and **Development Workflow** (how we work). Keep those two H2
+sections as the backbone when merging into an existing `CLAUDE.md`.
 
 ---
 
@@ -159,9 +158,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 When merging this snippet into an existing `CLAUDE.md`:
 
 1. **Keep the two H2 sections** (`System Context` / `Development Workflow`) as the
-   backbone. This alignment with the Dflow skill's
-   `templates/CLAUDE.md` is important — AI assistants navigate by
-   these headings.
+   backbone — AI assistants navigate by these headings.
 2. **Under `System Context`**: merge the background paragraph and the
    directory tree. If your project already documents directory
    structure elsewhere, keep the tree pointing to `dflow/specs/` and
@@ -172,7 +169,7 @@ When merging this snippet into an existing `CLAUDE.md`:
    cross-referenced from the scaffolding `Git-principles-*.md`.
 4. **Avoid duplication**: do not re-inline the Dflow skill's decision
    tree, Workflow Transparency rules, or Ceremony Scaling criteria
-   into `CLAUDE.md`. Let `CLAUDE.md` point to the skill, not
+   into `CLAUDE.md`. Let `CLAUDE.md` point to `AI-AGENT-GUIDE.md` and the workflow bundle, not
    duplicate it.
 
 If you are starting from scratch (no existing `CLAUDE.md`), the

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

@@ -124,8 +124,6 @@ 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)
@@ -299,19 +297,22 @@ Three categories:
 | `git stash` (local-only) |
 | `git branch` (listing only) |
 
-### AI commit authorship (suggested, not enforced)
+### AI commit authorship
 
-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:
+How AI-made commits are marked is chosen once at `dflow init` and recorded in
+`dflow/specs/shared/_conventions.md` § AI Commit Policy:
 
-```
-Co-Authored-By: Claude <noreply@anthropic.com>
-```
+- `none` — AI commits carry no extra marker.
+- `co-authored-by` — a `Co-Authored-By: dflow-ai <noreply@dflow.local>` trailer
+  (teams may customize the name / email).
+- `prefix` — an `[ai-assisted]` commit-subject prefix.
 
-For other AI assistants, use the vendor-documented author line (or omit
-it). This is a project-level transparency convention, not a Dflow
-requirement.
+This recorded setting is authoritative and the runtime does not re-ask. The AI
+offers commits at lifecycle checkpoints (see `references/git-integration.md`
+§ Commit Checkpoints, Branch Gate & AI Commits) using your Git identity, and you
+can always decline. If your team also wants vendor attribution, appending the
+assistant's documented line (e.g. `Co-Authored-By: Claude
+<noreply@anthropic.com>`) is an independent, optional convention on top.
 
 ---
 

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

@@ -72,8 +72,6 @@ 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
 ```
 
 ### Conventional Commits style (recommended, optional)
@@ -170,8 +168,6 @@ Related BR-IDs:
 - REMOVED: (none)
 
 Related SPEC-IDs: {SPEC-ID}{, follow-up SPEC-IDs if any}
-
-Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
 Example:
@@ -191,8 +187,6 @@ Related BR-IDs:
 - MODIFIED: BR-03
 
 Related SPEC-IDs: SPEC-20260421-001
-
-Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
 ### 4.2 Rebase + merge (preserve feature commits on `main`)
@@ -281,19 +275,22 @@ Three categories:
 | `git branch` (listing only) |
 | `git rebase` on a private (not-yet-pushed) branch |
 
-### AI commit authorship (suggested, not enforced)
+### AI commit authorship
 
-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:
+How AI-made commits are marked is chosen once at `dflow init` and recorded in
+`dflow/specs/shared/_conventions.md` § AI Commit Policy:
 
-```
-Co-Authored-By: Claude <noreply@anthropic.com>
-```
+- `none` — AI commits carry no extra marker.
+- `co-authored-by` — a `Co-Authored-By: dflow-ai <noreply@dflow.local>` trailer
+  (teams may customize the name / email).
+- `prefix` — an `[ai-assisted]` commit-subject prefix.
 
-For other AI assistants, use the vendor-documented author line (or omit
-it). This is a project-level transparency convention, not a Dflow
-requirement.
+This recorded setting is authoritative and the runtime does not re-ask. The AI
+offers commits at lifecycle checkpoints (see `references/git-integration.md`
+§ Commit Checkpoints, Branch Gate & AI Commits) using your Git identity, and you
+can always decline. If your team also wants vendor attribution, appending the
+assistant's documented line (e.g. `Co-Authored-By: Claude
+<noreply@anthropic.com>`) is an independent, optional convention on top.
 
 ---
 

package/templates/brownfield/scaffolding/_conventions.md

@@ -8,16 +8,17 @@
 > Audience: engineers writing specs; AI assistants producing spec drafts.
 
 This file captures **project-level** conventions only. Template shapes
-and Ceremony criteria are defined by the Dflow skill; here we just
-record how *this* project fills them in.
+and Ceremony criteria are defined by Dflow itself (the Ceremony tier criteria
+live in `AI-AGENT-GUIDE.md` § Ceremony Scaling; template shapes live in the
+workflow bundle); here we just record how *this* project fills them in.
 
 ---
 
 ## Where Specs Live
 
 All spec documents live under `dflow/specs/`. The feature directory pattern
-and file names follow Dflow (see the Dflow skill § "Project Structure
-Reference" for the full tree):
+and file names follow Dflow (see `AI-AGENT-GUIDE.md` § Source of Truth
+for the full tree):
 
 ```
 dflow/specs/features/active/{SPEC-ID}-{slug}/
@@ -98,8 +99,8 @@ Project-specific guidance when filling these templates:
 
 ## Ceremony Scaling (Project Application)
 
-The Dflow skill defines three tiers — **T1 Heavy / T2 Light / T3
-Trivial**. See the Dflow skill § "Ceremony Scaling" for the full
+Dflow defines three tiers — **T1 Heavy / T2 Light / T3
+Trivial**. See `AI-AGENT-GUIDE.md` § Ceremony Scaling for the full
 criteria table. We do not re-define the tier criteria here; this
 section records how *this* project applies them in borderline
 situations.
@@ -111,8 +112,8 @@ situations.
 | {e.g. UI refresh across multiple entrypoints} | T1 (project convention) | We treat multi-entrypoint UI/API refresh as T1 for this project even though Dflow default would be T2, because these changes often leak into business logic embedded in delivery/entrypoint code (presentation/UI layer, controllers, handlers, jobs, message consumers, data pipelines, or stored procedures) |
 
 If the team disagrees on tier classification for a specific change,
-run through the T3 four-criteria checklist (in the Dflow skill) and
-record the decision here the first time it arises.
+run through the T3 four-criteria checklist (in `AI-AGENT-GUIDE.md` §
+Ceremony Scaling) and record the decision here the first time it arises.
 
 ---
 
@@ -136,5 +137,5 @@ and `/dflow:new-phase` flows; the project-level convention is simply
 - [System overview](_overview.md)
 - [Git principles](Git-principles-{gitflow|trunk}.md)
 - [Glossary](../domain/glossary.md)
-- Dflow skill SKILL.md — canonical source for Ceremony Scaling, flow
+- `AI-AGENT-GUIDE.md` — canonical source for Ceremony Scaling, flow
   selection, and template shapes.

package/templates/brownfield/templates/_index.md

@@ -12,13 +12,14 @@ Template note (for AI):
   This is the **feature-level dashboard** (`_index.md`) for a feature
   directory. Place at `dflow/specs/features/active/{SPEC-ID}-{slug}/_index.md`.
 
-  Six required sections (see below):
+  Seven required sections (see below):
     1. Metadata (YAML front matter above)
     2. Goals & Scope (prose)
     3. Phase Specs (T1 list)
     4. Current BR Snapshot (feature-level cumulative state)
     5. Lightweight Changes (T2 outbound link + T3 inline)
-    6. Resume Pointer
+    6. Checkpoint Log (commit / skip timeline)
+    7. Resume Pointer
 
   Optional section (append at end if applicable):
     - Follow-up Tracking (when this feature has follow-up features derived)
@@ -80,13 +81,30 @@ Template note (for AI):
 > T3 行：inline 完整描述一句話 + 標籤（如 `[cosmetic]` / `[text]` /
 >        `[format]`）；T3 不產獨立 spec 檔
 >
-> Tier 判準見 SKILL.md § Ceremony Scaling 三層表。
+> Tier 判準見 AI-AGENT-GUIDE.md § Ceremony Scaling 三層表。
 
 | Date | Tier | Description | Commit |
 |---|---|---|---|
 | {YYYY-MM-DD} | T2 | bug fix XYZ — 見 [`lightweight-{date}-{slug}.md`](./lightweight-{date}-{slug}.md) | {hash} |
 | {YYYY-MM-DD} | T3 | 按鈕顏色從藍改綠 `[cosmetic]` | {hash} |
 
+<!-- dflow:section checkpoint-log -->
+## Checkpoint Log
+
+> 生命週期 checkpoint 的 commit / skip 時間線（讓三週後回溯不必手動重建）。
+> 每個 checkpoint 無論 commit 或 skip 都記一列。Tier 決定 checkpoint 數：
+> T1 三點（spec 完 / impl 完 / closeout）、T2 兩點（spec+impl 合併 / closeout）、
+> T3 單一 commit。
+>
+> commit hash 只在 commit 實際成功後填入；pre-commit hook reject 或 commit
+> 失敗記 `failed`、不寫假 hash。
+
+| Timestamp | Checkpoint | Result |
+|---|---|---|
+| {YYYY-MM-DD HH:MM} | spec-baseline | committed ({hash}) / skipped / failed |
+| {YYYY-MM-DD HH:MM} | implementation | committed ({hash}) / skipped / failed |
+| {YYYY-MM-DD HH:MM} | closeout | committed ({hash}) / skipped / failed |
+
 ## Resume Pointer
 
 > 一句話：目前進展到哪？下一個動作是什麼？

package/templates/brownfield/templates/lightweight-spec.md

@@ -11,7 +11,7 @@ branch: bugfix/BUG-{NUMBER}-{short-description}
 Template note (for AI):
   This is the **lightweight-spec** template — it corresponds to T2 Light
   ceremony in the three-tier Ceremony Scaling (T1 Heavy / T2 Light /
-  T3 Trivial; see SKILL.md § Ceremony Scaling for the tier criteria).
+  T3 Trivial; see AI-AGENT-GUIDE.md § Ceremony Scaling for the tier criteria).
 
   - T1 Heavy → use templates/phase-spec.md instead
   - T2 Light → THIS template; produces an independent file

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

@@ -21,7 +21,7 @@ Template note (for AI):
 
   Each section below carries an HTML comment indicating its fill-in activity (Activity 1-4).
   These activity markers let /dflow:status and the completion checklist track progress.
-  Activities correspond to SKILL.md § Guiding Questions by Activity:
+  Activities correspond to AI-AGENT-GUIDE.md § Guiding Questions by Activity:
     Activity 1: Understanding (What & Why)
     Activity 2: Domain Analysis (Where does it live?)
     Activity 3: Spec Writing (Behavior + Rules + Edge Cases)

package/templates/common/skill/SKILL.md

@@ -5,12 +5,15 @@ description: >
   /dflow:* commands (/dflow:new-feature, /dflow:modify-existing, /dflow:bug-fix,
   /dflow:new-phase, /dflow:finish-feature, /dflow:pr-review, /dflow:verify,
   /dflow:report-dflow-feedback, /dflow:status, /dflow:next, /dflow:cancel).
-  SECONDARY (auto-trigger safety net) — engage ONLY for: adding or changing
-  product/domain behavior, new requirements, a feature or bug-fix workflow, or
-  spec-impacting architecture/domain-model decisions. Do NOT engage for pure
-  refactors, infrastructure chores, formatting, or general code questions.
-  When engaged by natural language, DO NOT auto-enter a workflow: judge the
-  intent, suggest the matching /dflow: command, and wait for confirmation.
+  SECONDARY — engage ONLY for adding or changing product/user-facing/domain
+  behavior, a new requirement, a feature or bug-fix workflow, or spec-impacting
+  architecture/domain-model decisions. Includes indirect phrasings, e.g. "I want
+  to build/add ...", "let's add the ability to ...", "we need to support ...",
+  "can you implement ...", "users should be able to ...", "the app should also
+  ...". Do NOT engage for pure refactors, renames, infra/build chores,
+  formatting, dep bumps, or general code questions ("how does X work", "explain
+  this"). When engaged by natural language, DO NOT auto-enter a workflow: judge
+  the intent, suggest the matching /dflow: command, and wait for confirmation.
 ---
 
 <!-- dflow-generated: skill-adapter -->