dflow-sdd-ddd 0.1.0 → 0.2.0

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 { runInit } = require('../lib/init');
+const { runConfigureAgents, runDoctor, runInit } = require('../lib/init');
 const pkg = require('../package.json');
 
 const args = process.argv.slice(2);
@@ -9,11 +9,11 @@ function printHelp() {
   process.stdout.write(`Dflow CLI ${pkg.version}
 
 Usage:
-  dflow init       Initialize Dflow specs in the current project
-  dflow --help     Show this help
-  dflow --version  Show the CLI version
-
-Only the init subcommand is implemented in this version.
+  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
 `);
 }
 
@@ -22,8 +22,36 @@ function printInitHelp() {
   dflow init
 
 Initializes Dflow project specs under dflow/specs/.
-The command prompts for project type, edition, tech stack, prose language,
-and optional starter files before showing a full file preview.
+The command prompts for project type, tech stack, prose language,
+optional starter files, and AI coding agents before showing a full file preview.
+`);
+}
+
+function printConfigureAgentsHelp() {
+  process.stdout.write(`Usage:
+  dflow configure-agents
+
+Adds AI agent instruction files to an existing Dflow project.
+The command can create AGENTS.md, CLAUDE.md, GEMINI.md, and
+.github/copilot-instructions.md shims that point to the canonical
+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.
 `);
 }
 
@@ -57,6 +85,43 @@ async function main() {
     });
   }
 
+  if (args[0] === 'configure-agents') {
+    if (args.length > 1 && (args[1] === '--help' || args[1] === '-h')) {
+      printConfigureAgentsHelp();
+      return 0;
+    }
+
+    if (args.length > 1) {
+      process.stderr.write(`Unsupported configure-agents option: ${args.slice(1).join(' ')}\n`);
+      return 1;
+    }
+
+    return await runConfigureAgents({
+      cwd: process.cwd(),
+      stdin: process.stdin,
+      stdout: process.stdout,
+      stderr: process.stderr
+    });
+  }
+
+  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.

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

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

package/docs/npm-publish-checklist.md

@@ -0,0 +1,93 @@
+# npm Publish Checklist
+
+This checklist is for maintainers preparing a manual Dflow npm release.
+Contributors do not need to run these steps for ordinary pull requests.
+
+Replace `<version>` with the version being published, for example `0.1.2`.
+
+## Pre-Publish
+
+- [ ] Confirm the release scope and expected version impact.
+- [ ] Update `package.json` version.
+- [ ] Update `CHANGELOG.md`.
+- [ ] Confirm `README.md` installation instructions match the release.
+- [ ] Confirm Greenfield and Brownfield common flow changes are synchronized.
+- [ ] Confirm generated templates match skill source where applicable.
+- [ ] Run:
+
+```bash
+npm test
+npm pack --dry-run
+git diff --check
+```
+
+- [ ] Inspect `npm pack --dry-run` output for unexpected files or missing files.
+- [ ] Commit the release preparation changes.
+
+## Publish
+
+- [ ] Confirm npm authentication:
+
+```bash
+npm whoami
+```
+
+- [ ] Publish:
+
+```bash
+npm publish
+```
+
+Use npm Security Key / WebAuthn 2FA when prompted. Do not assume a TOTP
+`--otp` flow is available for maintainer accounts.
+
+## Post-Publish Smoke
+
+Run the smoke checks against the public registry package:
+
+```bash
+npx dflow-sdd-ddd@<version> --version
+npx dflow-sdd-ddd@<version> --help
+npx dflow-sdd-ddd@<version> init
+npx dflow-sdd-ddd@<version> configure-agents
+```
+
+Verify:
+
+- [ ] `--version` prints `<version>`.
+- [ ] `--help` lists the expected commands.
+- [ ] `init` creates the expected `dflow/specs/` workspace.
+- [ ] `init` creates or preserves selected AI-agent instruction files correctly.
+- [ ] `configure-agents` adds later selected AI-agent shims in an initialized
+      project.
+
+## Tags and GitHub Release
+
+- [ ] Tag the development repo:
+
+```bash
+git tag v<version>
+git push origin v<version>
+```
+
+- [ ] Export or sync the dist repo if this release includes public source
+      changes.
+- [ ] Run release verification in the dist repo.
+- [ ] Tag the dist repo:
+
+```bash
+git tag v<version>
+git push origin v<version>
+```
+
+- [ ] Create the GitHub Release for `v<version>`.
+- [ ] Include user-facing changes, verification summary, and migration notes if
+      any.
+
+## Closeout
+
+- [ ] Verify the npm registry shows `<version>` as `latest` when intended.
+- [ ] Record post-publish smoke results in the release handoff or closeout note.
+- [ ] Move implemented or rejected proposals out of the active proposal
+      workspace.
+- [ ] Leave the development repo clean except for intentional next-work notes.