dflow-sdd-ddd 0.1.1 → 0.2.0

package/CONTRIBUTING.md

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

package/README.md

@@ -17,13 +17,18 @@ AI makes delivery faster, but it also makes ambiguous domain knowledge more dang
 
 ## Get Started
 
+Prerequisite: a local Node.js / npm environment that can run `npx`.
+
 Run Dflow from the root of the project you want to adopt it in:
 
 ```bash
 npx dflow-sdd-ddd init
 ```
 
-The init flow asks whether the project is greenfield or brownfield, then previews the files it will create. Existing files are not overwritten.
+The init flow asks whether the project is greenfield or brownfield, then
+previews the files it will create. Existing files are not overwritten. Init
+creates workflow documentation and AI instruction files; it does not inspect,
+refactor, or migrate your application code.
 
 For a fixed global CLI:
 
@@ -42,6 +47,17 @@ dflow configure-agents
 This command only configures AI instruction files. It does not rerun project
 initialization or touch existing specs.
 
+To check whether the project still has legacy or pre-V1 artifacts (such as
+a top-level `specs/` directory or a `_共用/` directory left over from older
+Dflow forms), run:
+
+```bash
+dflow doctor
+```
+
+`doctor` is a read-only health check. It never modifies files; it only
+reports findings and points at the migration guide.
+
 After init, start work through the Dflow workflow in your AI coding agent:
 
 ```text
@@ -56,6 +72,17 @@ After init, start work through the Dflow workflow in your AI coding agent:
 
 If your tool does not support custom slash commands, use the same command names as plain instructions in chat. Dflow is Markdown-based workflow material plus a scaffolding CLI, so it can be used with AI coding agents that can read project instructions and repository context.
 
+For the first adoption pass, use a branch or disposable sample project so your
+team can inspect the generated `dflow/specs/` workspace before bringing the
+workflow into an active codebase.
+
+For a guided evaluation walk-through — what `init` creates, AI tool support,
+track choice, and a 30-minute sample-project playbook — see [Evaluating
+Dflow](docs/evaluating-dflow.md). For end-to-end scenario walk-throughs of
+Greenfield and Brownfield workflows with worked spec outputs, see the
+[`tutorial/`](tutorial/README.md) index (top of file has an English reading
+guide).
+
 ## Project Tracks
 
 | Track | Use it when | Main outcome |
@@ -139,6 +166,22 @@ multiple copies of the workflow rules.
 You can run `dflow configure-agents` later to add more tool shims as the team
 adopts additional AI coding agents.
 
+For tool-specific walk-throughs of what `init` writes and how Dflow's
+workflow commands appear in a given AI tool, see the per-tool guides under
+`docs/`:
+
+- [Using Dflow with Claude Code](docs/using-with-claude-code.md)
+- [Using Dflow with Codex CLI](docs/using-with-codex.md)
+
+Guides for Gemini CLI and GitHub Copilot may follow as maintainer
+experience with each tool stabilizes.
+
+Init does not copy the `tutorial/` directory into your project. The
+[`tutorial/`](tutorial/README.md) directory lives in this source repository
+as evaluation material for understanding how Dflow works on Greenfield and
+Brownfield scenarios; the tutorial index opens with an English reading guide
+for non-Chinese readers.
+
 ## Main Flows
 
 | Flow | When to use it | Typical outputs |
@@ -150,6 +193,7 @@ adopts additional AI coding agents.
 | `/dflow:finish-feature` | The implementation is done and needs closure. | Drift verification, feature snapshot, technical debt update, review checklist. |
 | `/dflow:verify` | You need confidence that docs and code still match. | Drift report across spec, domain docs, implementation, tests, and debt records. |
 | `/dflow:pr-review` | A change is ready for review. | SDD/DDD compliance review with risks, gaps, and follow-up items. |
+| `/dflow:report-dflow-feedback` | You or the AI found a Dflow issue or improvement while using the workflow. | Sanitized local feedback draft for a GitHub issue or future PR; nothing is submitted automatically. |
 
 ## Why DDD Matters More with AI
 
@@ -176,9 +220,31 @@ For a longer explanation, see [Why DDD Matters More with AI](docs/why-ddd-for-ai
 | `tutorial/` | Guided learning scenarios and expected outputs. |
 | `sdd-ddd-*-skill/` | Source workflow material consumed by AI coding agents. |
 
+## Contributing and Releases
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for issue and pull request guidance.
+Pull requests run an automated verification workflow on GitHub before review.
+Maintainer-facing release rules are documented in [Release and Versioning
+Policy](docs/release-versioning-policy.md), with the manual npm flow in [npm
+Publish Checklist](docs/npm-publish-checklist.md).
+
 ## Status
 
-Dflow is currently published as `dflow-sdd-ddd` on npm. Version `0.1.0` focuses on project initialization, workflow documentation, and AI-agent-readable SDD/DDD guidance. Additional packaging for specific AI tools can be layered on top without changing the core workflow model.
+Dflow is currently published as `dflow-sdd-ddd` on npm. The latest published
+npm package is `0.2.0`, covering project initialization, workflow
+documentation, multi-AI agent setup, AI-agent-readable SDD/DDD guidance,
+public migration tooling (manual migration guide and `dflow doctor`
+read-only health check), public onboarding (evaluator guide and per-tool
+walkthroughs for Claude Code and Codex CLI), and a verification-only CI
+workflow.
+
+The GitHub source may include post-`0.2.0` repository changes before the
+next npm release is published. See [CHANGELOG.md](CHANGELOG.md) for full
+release history.
+
+If you maintain a project that adopted an early Dflow form before
+`0.1.0` was published, see [Migrating to Dflow
+V1](docs/migrating-to-dflow-v1.md) for the manual migration checklist.
 
 ## License
 

package/TEMPLATE-COVERAGE.md

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

package/TEMPLATE-LANGUAGE-GLOSSARY.md

@@ -0,0 +1,52 @@
+<!-- Maintenance contract for Dflow. See archive/proposals/PROPOSAL-013-system-document-template-coverage.md §1.1 for origin. -->
+
+# Template Language Glossary
+
+This file is a human reading aid and review reference for Dflow template terminology. It is not a second template set.
+
+Template headings, field labels, anchors, and placeholder names use canonical English. Free prose inside those sections follows the project `Prose Language` convention.
+
+## Inclusion Criteria
+
+A term is included in this glossary when it meets **any** of these:
+
+1. **Cross-file structural term** — appears as a heading / column / inline label in two or more templates (e.g. `Implementation Tasks`, `Business Rules`).
+2. **Translation-sensitive concept** — direct Chinese translation may lose precision or differ from common usage (e.g. `Behavior Delta` vs 「行為變更」, `Resume Pointer` vs 「接續入口」).
+3. **Workflow-critical inline label** — bold inline labels that AI / tooling reads as fixed fields within a section (e.g. `**Before** / **After** / **Reason**`).
+4. **Commit message convention label** — labels used in Integration Commit Message Conventions (e.g. `Feature Goal`, `Change Scope`, `Phase Count`).
+
+A term is **NOT** included when:
+
+- The English heading is self-explanatory and its Chinese translation is unambiguous (e.g. `Open Questions`, `Edge Cases`, `Test Strategy`, `Implementation Notes`, `Goals & Scope`, `Phase Specs`, `Problem`, `Root Cause`, `Fix Approach`, `Tech Debt Discovered`).
+- It only appears once in a single template as a section heading without cross-file reference.
+- It is a placeholder example (e.g. `{one-line summary}`) rather than a structural term.
+
+The "使用位置" column refers to file paths where the term appears structurally (as heading / column / label), not necessarily a specific section. For example, `Domain Models` appears as the H1 of `models.md`, representing the file's central concept; `Implementation Tasks` appears as an H2 in two different templates.
+
+## Glossary
+
+| English term | 繁體中文對照 | 使用位置 | 說明 |
+|---|---|---|---|
+| Implementation Tasks | 實作任務 | `phase-spec.md`, `lightweight-spec.md` | AI 產生與追蹤 task checklist 的段落 |
+| Behavior Scenarios | 行為情境 | `phase-spec.md`, `behavior.md` | Given/When/Then 行為規格 |
+| Business Rules | 業務規則 | `rules.md`, `_index.md` | BR-ID declarative rules |
+| Current BR Snapshot | 目前業務規則快照 | `_index.md` | feature-level rules snapshot |
+| Domain Models | 領域模型 | `models.md` | Entities / Value Objects / Services 等模型索引 |
+| Change Scope | 變動範圍 | `Git-principles-*.md`, spec templates | 描述本次變更涵蓋的功能 / 文件 / 程式碼範圍 |
+| Feature Goal | 功能目標 | `Git-principles-*.md`, `finish-feature-flow.md` | Integration Summary 與整合 commit message 的主目標段落 |
+| Related BR-IDs | 關聯 BR-ID 清單 | `Git-principles-*.md`, `finish-feature-flow.md` | 統整本次變更涉及的 ADDED / MODIFIED / REMOVED BR-ID |
+| Phase Count | Phase 數 | `Git-principles-*.md`, `finish-feature-flow.md` | 整合摘要中描述本次 feature 涵蓋的 phase-spec 數量 |
+| Lightweight Change | 輕量修改 | `_index.md`, `lightweight-spec.md`, Git principles | T2 / small change 類型的固定術語 |
+| Lightweight Changes | 輕量修改紀錄 | `_index.md` | `_index.md` 中登記 T2 外連 + T3 inline 的 section heading |
+| Resume Pointer | 接續入口 | `_index.md` | `_index.md` 末段「目前進展 + 下一動作」的 section heading |
+| Behavior Delta | 行為變更 | `lightweight-spec.md` | lightweight-spec 中 BR delta 段的 section heading |
+| Current Progress | 目前進展 | `_index.md` | Resume Pointer 段內描述當下狀態的 inline bold label（per F-04 / DD-A Path A）|
+| Next Action | 下一個動作 | `_index.md` | Resume Pointer 段內描述下一動作的 inline bold label（per F-04 / DD-A Path A）|
+| Before | 原本 | `lightweight-spec.md`, `phase-spec.md`, `references/modify-existing-flow.md` | Behavior Delta MODIFIED 段內描述變更前狀態的 inline bold label（per F-08 / DD-A Path A）|
+| After | 改為 | `lightweight-spec.md`, `phase-spec.md`, `references/modify-existing-flow.md` | Behavior Delta MODIFIED 段內描述變更後狀態的 inline bold label（per F-08 / DD-A Path A）|
+| Reason | 原因 | `lightweight-spec.md`, `phase-spec.md`, `references/modify-existing-flow.md` | Behavior Delta 段內描述變更原因的 inline bold label（per F-08 / DD-A Path A）|
+| Prose Language | prose 語言 / 自由文字語言 | `dflow/specs/shared/_conventions.md`, init flow, prose-generating references | 專案層級設定，規範 AI 生成自由 prose 時使用的 explicit BCP-47 language tag，例如 `zh-TW` 或 `en` |
+| Free prose | 自由 prose / 自由文字 | Templates, generated specs, workflow references | 由使用者或 AI 撰寫的段落內容，例如 task 描述、Root Cause、Fix Approach、Open Questions；遵循專案 `Prose Language` |
+| Structural language | 結構性語言 | Templates, generated specs, `TEMPLATE-COVERAGE.md` | 固定文件結構語言，例如 headings、table headers、labels、placeholders、IDs、anchors；Dflow 保持 canonical English |
+| Canonical English | 標準英文結構 | Templates, scaffolding, generated specs | Dflow 固定使用的英文結構詞彙，用於穩定 AI 導航、anchor 定位與跨檔維護 |
+| Code-facing terms | 面向程式碼的術語 | Templates, generated specs, `_conventions.md` | 不應只為符合 prose 語言而翻譯的內容，例如 code identifiers、DDD pattern names、BR IDs、SPEC IDs、file paths、branch names、anchors、inline code |

package/bin/dflow.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { runConfigureAgents, runInit } = require('../lib/init');
+const { runConfigureAgents, runDoctor, runInit } = require('../lib/init');
 const pkg = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -11,6 +11,7 @@ function printHelp() {
 Usage:
   dflow init              Initialize Dflow specs in the current project
   dflow configure-agents  Add or update AI agent instruction shims
+  dflow doctor            Read-only health check for legacy / pre-V1 artifacts
   dflow --help            Show this help
   dflow --version         Show the CLI version
 `);
@@ -37,6 +38,23 @@ dflow/specs/shared/AI-AGENT-GUIDE.md file.
 `);
 }
 
+function printDoctorHelp() {
+  process.stdout.write(`Usage:
+  dflow doctor
+
+Read-only health check for the current project. Reports legacy
+or pre-V1 artifacts that may need manual migration:
+
+  - root specs/ directory containing Dflow content
+  - _共用/ directory under specs/ or dflow/specs/
+  - dflow/specs/shared/_conventions.md missing the Dflow Version
+    front-matter line
+
+Doctor never modifies files. See docs/migrating-to-dflow-v1.md
+for the manual migration checklist.
+`);
+}
+
 async function main() {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     printHelp();
@@ -86,6 +104,24 @@ async function main() {
     });
   }
 
+  if (args[0] === 'doctor') {
+    if (args.length > 1 && (args[1] === '--help' || args[1] === '-h')) {
+      printDoctorHelp();
+      return 0;
+    }
+
+    if (args.length > 1) {
+      process.stderr.write(`Unsupported doctor option: ${args.slice(1).join(' ')}\n`);
+      return 1;
+    }
+
+    return await runDoctor({
+      cwd: process.cwd(),
+      stdout: process.stdout,
+      stderr: process.stderr
+    });
+  }
+
   process.stderr.write(`Unsupported subcommand: ${args[0]}\n\n`);
   printHelp();
   return 1;

package/docs/evaluating-dflow.md

@@ -0,0 +1,226 @@
+# Evaluating Dflow
+
+A short guide for first-time evaluators deciding whether Dflow fits a project.
+About 10 minutes to read, optional 30 minutes to try in a sample project.
+
+## Who This Guide Is For
+
+You are deciding whether to introduce Dflow into a codebase. You may be a
+tech lead evaluating workflow changes for an AI-assisted team, a solo
+developer comparing AI coding workflows, or a team member asked to assess
+Dflow before broader adoption.
+
+This guide answers the most common evaluation questions in one place. It does
+not replace [`README.md`](../README.md) (overview) or [`tutorial/`](../tutorial/)
+(deep walk-throughs); it is a focused decision aid.
+
+## What Is Dflow
+
+Dflow is a workflow kit for AI-assisted development. It gives an AI coding
+agent a concrete process for turning change requests into structured specs,
+domain language, and reviewable code, instead of jumping from prompt straight
+to code.
+
+Dflow is Markdown-based workflow material plus a scaffolding CLI. It does not
+require a runtime, server, or framework. Once `init` runs, Dflow lives entirely
+in your project's `dflow/specs/` directory and AI instruction files.
+
+## What `init` Creates and Does Not Do
+
+`npx dflow-sdd-ddd init` creates:
+
+- A `dflow/specs/` workspace (overview, conventions, domain glossary, context
+  map, architecture/tech-debt, features active/completed). See
+  [`README.md` "Files Created by Init"](../README.md#files-created-by-init)
+  for the full tree.
+- A canonical project guide at `dflow/specs/shared/AI-AGENT-GUIDE.md`.
+- Mergeable AI agent instruction files for the tools you select (e.g.,
+  `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
+  `.github/copilot-instructions.md`). Each is a thin pointer to the
+  canonical guide.
+
+`init` does **not**:
+
+- Inspect, refactor, or migrate your application code.
+- Overwrite existing AI agent instruction files; if one exists, Dflow writes
+  a merge snippet under `dflow/specs/shared/` instead.
+- Modify your build system, package manager, or dependencies.
+- Send any data anywhere; it is a local scaffolding command.
+
+## How Dflow Works With Different AI Tools
+
+Dflow targets multiple AI coding agents. After running `init`, you select one
+or more tools and Dflow writes the corresponding shim:
+
+| Tool | Generated file |
+|---|---|
+| Codex / Copilot coding agent | `AGENTS.md` |
+| Claude Code | `CLAUDE.md` |
+| Gemini CLI | `GEMINI.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+
+Each shim points back to the canonical
+`dflow/specs/shared/AI-AGENT-GUIDE.md`. Practical implications:
+
+- Multiple tools can be active in the same project without diverging
+  workflow rules.
+- Switching or adding tools later does not require re-running `init`; use
+  `dflow configure-agents` to add another shim.
+- The project guide stays the single source of truth for Dflow workflow
+  behavior.
+
+If your tool does not support custom slash commands, use the same command
+names (e.g., `/dflow:new-feature`) as plain instructions in chat. Dflow is
+Markdown-based workflow material; it works with any AI agent that can read
+project instructions and repository context.
+
+For a tool-specific walk-through of what `init` writes and how the slash
+commands appear in conversation, see the per-tool guides:
+
+- [Using Dflow with Claude Code](using-with-claude-code.md)
+- [Using Dflow with Codex CLI](using-with-codex.md)
+- (Guides for Gemini and GitHub Copilot may follow as maintainer experience
+  with each tool stabilizes.)
+
+## Greenfield or Brownfield: Choosing a Track
+
+Pick **Greenfield** if:
+
+- You are starting a new system or a new bounded module.
+- You have room to shape architecture before legacy constraints accumulate.
+- You want explicit domain models from feature 1.
+
+Pick **Brownfield** if:
+
+- You are extending or modifying an existing codebase.
+- Business rules are scattered across handlers, stored procedures, UI code,
+  or scripts.
+- You want to introduce specs and domain extraction incrementally without
+  refactoring everything first.
+
+Mixed cases:
+
+- New module inside an existing app: usually Greenfield, scoped to the new
+  bounded context.
+- Existing app with clean architecture and active development: either track
+  works; Brownfield is safer if rules are not yet documented.
+
+## A 30-Minute Evaluation Playbook
+
+This walk-through lets you see what Dflow does without committing it to a
+real codebase.
+
+1. **Create a sample project** (Greenfield):
+
+   ```bash
+   mkdir dflow-sample && cd dflow-sample
+   git init
+   ```
+
+2. **Run init**:
+
+   ```bash
+   npx dflow-sdd-ddd init
+   ```
+
+   When prompted, choose Greenfield. Pick one AI tool to generate the shim
+   for.
+
+3. **Inspect what was created**:
+
+   ```bash
+   ls -la
+   find dflow -type f
+   ```
+
+   Open `dflow/specs/shared/_overview.md`,
+   `dflow/specs/shared/_conventions.md`, and
+   `dflow/specs/shared/AI-AGENT-GUIDE.md` to see the shape.
+
+4. **Read one tutorial walk-through** to see what a real feature flow looks
+   like end to end:
+   - Greenfield: [`tutorial/01-greenfield/`](../tutorial/01-greenfield/00-setup.md)
+   - Brownfield: [`tutorial/02-brownfield/`](../tutorial/02-brownfield/00-setup.md)
+
+5. **Optional: try one workflow command**. Open the sample project in your
+   AI tool and ask it to run `/dflow:new-feature` (or paste the equivalent
+   instruction in chat). Inspect what it writes to `dflow/specs/`.
+
+6. **Decide and clean up**. If Dflow does not fit, delete the sample
+   directory. There is no global state to clean; nothing was installed
+   beyond the one-shot `npx` cache.
+
+If you want a deeper read instead of running anything, the tutorial
+walk-throughs cover the same flow with worked outputs you can compare
+against.
+
+## What If You Stop Using Dflow
+
+Dflow is designed for low cost to try and low cost to leave:
+
+- Nothing depends on the `dflow-sdd-ddd` CLI being installed after `init`.
+- The generated files are plain Markdown; remove Dflow from a project with
+  `rm -rf dflow/` plus deleting the AI agent shim files you no longer want.
+- Existing project instruction files (e.g., a pre-existing `CLAUDE.md`) are
+  not modified by Dflow, so reverting is straightforward.
+
+This means an evaluation pass leaves no permanent footprint if you decide
+not to adopt.
+
+## Cost Per Feature: A Rough Estimate
+
+Dflow scales ceremony to change risk through three tiers (see
+[`README.md` "Workflow Model"](../README.md#workflow-model) for full
+detail):
+
+- **T1 Lightweight** — small bug fixes, narrow edits. Roughly the same
+  speed as ad-hoc AI coding, with a short spec and verification on top.
+- **T2 Standard** — normal feature work. Adds a feature spec, behavior
+  examples, and finish checks. Expect modest upfront overhead in exchange
+  for a reusable spec, fewer review cycles, and lower drift risk.
+- **T3 Full** — cross-cutting changes, new bounded contexts, risky
+  architecture work. Adds full domain modeling and broader verification.
+  The cost is real but proportional to the risk being managed.
+
+Tier choice is intentional, not automatic. You are not forced into T3
+ceremony for a one-line fix.
+
+## Project Language Compatibility
+
+Dflow templates use **canonical English** structure (headings, field labels)
+so AI agents can locate sections reliably across projects. The free-form
+content you write inside templates can be in any team language — English,
+Traditional Chinese, Simplified Chinese, or others. The init flow asks for
+the project's prose language and stores it in
+`dflow/specs/shared/_conventions.md`.
+
+Practical effect:
+
+- AI tools see stable English structure across projects.
+- Humans read and write specs in the team's chosen language.
+- No need to translate templates or maintain parallel localized copies.
+
+## Where to Go Next
+
+If you decided Dflow fits:
+
+- Run `init` in your real project (consider a branch first).
+- Read [`tutorial/`](../tutorial/) for end-to-end walk-throughs and worked
+  outputs.
+- See [`CONTRIBUTING.md`](../CONTRIBUTING.md) before opening issues or
+  pull requests.
+
+If you are still deciding:
+
+- Read [`docs/why-ddd-for-ai.md`](why-ddd-for-ai.md) for the design
+  rationale behind spec-first plus DDD.
+- Compare a tutorial scenario step-by-step with its `outputs/` tree to see
+  what production-shape Dflow specs look like.
+
+If Dflow does not fit your project today:
+
+- The structured-spec idea is portable; you can adopt parts of it without
+  the CLI.
+- Open a docs feedback issue (see
+  [`CONTRIBUTING.md`](../CONTRIBUTING.md)) if a specific gap blocked you.
+  That feedback helps future evaluators.