dflow-sdd-ddd 0.9.0 → 0.11.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,33 @@ 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.
+- **"I'm designing a domain model" / "How should I model X?" / building or
+  reshaping an Aggregate** → read `references/ddd-modeling-guide.md` (DDD
+  tactical patterns: aggregates, invariants, value objects, domain events). It
+  is written with Greenfield artifact names; see its **Edition note** for where
+  Brownfield records the same decisions (`models.md` / `rules.md` /
+  `behavior.md` / `migration/tech-debt.md`).
+- **"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 +134,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 +209,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,33 +249,106 @@ 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`.
 
-## Pre-V1 Artifacts Detection
-
-When working in a project that adopted Dflow before `dflow-sdd-ddd@0.1.0`,
-you may encounter layout or naming patterns that predate the V1 baseline.
-If any of the following appear, surface the observation to the developer
-and recommend manual migration; do not rewrite anything silently.
-
-Signals:
-
-- Top-level `specs/` directory containing Dflow-shaped content (V1 layout
-  uses `dflow/specs/`).
-- `_共用/` directory under `specs/` or `dflow/specs/` (V1 uses `shared/`).
-- Section headings in Traditional Chinese where V1 templates render
-  canonical English; compare against `TEMPLATE-LANGUAGE-GLOSSARY.md` if
-  available.
-- References to a runtime `/dflow:init-project` slash command (V1
-  replaced it with the Dflow CLI init command (`dflow init`, or
-  `npx dflow-sdd-ddd init` when using the no-install path)).
-- A root `CLAUDE.md`, `AGENTS.md`, or equivalent that holds the full
-  Dflow workflow text instead of being a thin shim pointing to this
-  file.
-- `dflow/specs/shared/_conventions.md` is missing the `> Dflow Version:`
-  front-matter line (V1 init writes it automatically).
-
-Recommend `docs/migrating-to-dflow-v1.md` for the manual migration
-checklist. Migration affects every spec the team has written; manual
-review is required.
+## 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
 
 ## Workflow Steps
 

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/_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

@@ -81,7 +81,7 @@ 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 |
 |---|---|---|---|

package/templates/brownfield/templates/context-map.md

@@ -6,15 +6,23 @@
 
 ## Context List
 
-| Bounded Context | Responsibility | Owner / Team | Primary Code Area | Notes |
-|---|---|---|---|---|
-| {Context name} | {業務責任} | {owner} | `{project/path/or/namespace}` | {optional notes} |
+| Bounded Context | Responsibility | Subdomain Type | Owner / Team | Primary Code Area | Notes |
+|---|---|---|---|---|---|
+| {Context name} | {業務責任} | core / supporting / generic | {owner} | `{project/path/or/namespace}` | {optional notes} |
+
+> **Subdomain Type** — 判別問句:「這塊功能換成現成 SaaS / 套件,系統的差異化會消失嗎?」
+> (差異化不限商業競爭優勢;內部系統指獨特的營運優勢 / 任務成果。)會 → `core`;
+> 不會、但需要為自家流程客製 → `supporting`(必要、常需客製、非差異化);
+> 不會、且現成方案存在 → `generic`。多數 BC 是 supporting,`core` 通常只有 1–2 個;
+> 全標 core = 沒分類。分類是可修訂的初判,改判時更新本欄並在 Notes 留一行理由。
+> 它影響漸進抽離的取捨(`generic` 傾向整塊替換而非逐條抽離,見 modify-existing-flow
+> Step 4),但**不**降低 BR 紀錄、Tier ceremony、或安全 / 測試 / 可靠性要求。
 
 ## Relationships
 
 | Source Context | Target Context | Relationship Type | Integration Mechanism | Notes |
 |---|---|---|---|---|
-| {Source} | {Target} | {Customer/Supplier, Conformist, ACL, Shared Kernel, etc.} | {DB table, service call, file, manual process} | {optional notes} |
+| {Source} | {Target} | {Customer/Supplier, Conformist, ACL, Shared Kernel, Separate Ways, Big Ball of Mud (BBoM), OHS, etc.} | {DB table, service call, file, manual process} | {optional notes} |
 
 ## Integration Notes
 

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)