dflow-sdd-ddd 0.1.1 → 0.2.0

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.

package/docs/release-versioning-policy.md

@@ -0,0 +1,99 @@
+# Release and Versioning Policy
+
+This document defines the lightweight release policy for Dflow while the project
+is in the `0.x` series. It is maintainer-facing; contributors can use it to
+describe expected version impact in a PR, but only maintainers publish releases.
+
+## Versioning During 0.x
+
+Dflow uses SemVer-style version numbers, with extra care in `0.x` because the
+workflow contract is still evolving.
+
+Use a patch release for:
+
+- Bug fixes.
+- Documentation corrections or clarifications.
+- Non-breaking template wording changes.
+- Release metadata fixes.
+- Internal cleanup that does not change generated output or workflow contracts.
+
+Use a minor release for:
+
+- A new CLI command.
+- A new generated file.
+- A materially changed generated file shape.
+- A new or expanded `/dflow:*` workflow contract.
+- A change that affects how Greenfield or Brownfield projects are initialized.
+- A migration-relevant template, scaffolding, or skill behavior change.
+
+Major versions are reserved for `1.0` and later. Before `1.0`, breaking changes
+may still appear in minor releases, but release notes must call them out clearly
+and describe the expected user action.
+
+## What Counts as Breaking
+
+A change is breaking when an existing Dflow user may need to adjust project
+files, scripts, AI-agent instructions, or workflow habits after upgrading.
+
+Examples:
+
+- Renaming generated paths.
+- Removing a generated file.
+- Changing required init prompts.
+- Changing the meaning of a template section.
+- Changing command behavior in a way that invalidates existing docs.
+- Replacing a workflow contract that AI agents rely on.
+
+## Release Ownership
+
+Dflow currently has four release surfaces:
+
+- Development repo: source of truth for design work, implementation, planning,
+  and release preparation.
+- Dist repo: clean public projection of selected source files.
+- npm package: executable CLI and packaged templates selected by
+  `package.json#files`.
+- GitHub Release: public release note and tag record.
+
+For now, npm publishing may remain a manual maintainer action. Release
+automation should be introduced only after the manual dist shape and release
+checklist remain stable across multiple releases.
+
+## Tags
+
+Use `v<version>` tags, for example `v0.1.1`.
+
+When both development and dist repos are maintained, tag both repos for the same
+published version after verification. The tags may point to different commits
+because the dist repo is a selected projection of the development repo.
+
+## Changelog and Release Notes
+
+Update `CHANGELOG.md` before publishing. Each release entry should state:
+
+- The version and date.
+- User-facing changes.
+- Changed files or affected areas when useful.
+- Verification performed.
+- Any breaking change or migration note.
+
+GitHub Release notes may summarize the changelog entry, but they should not be
+the only place where release history is recorded.
+
+## Greenfield and Brownfield Changes
+
+If a change touches a common SDD flow, update both Greenfield and Brownfield
+skill sources unless the release intentionally changes only one track.
+
+Common synchronized flow files include:
+
+- `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 changes should be named in the changelog and release notes.

package/docs/using-with-claude-code.md

@@ -0,0 +1,207 @@
+# Using Dflow with Claude Code
+
+A walk-through of what Dflow looks like when your AI coding agent is
+[Claude Code](https://claude.com/claude-code). About 10 minutes to read.
+
+This guide focuses on the Claude Code experience specifically. For the
+tool-neutral evaluation flow, see
+[`docs/evaluating-dflow.md`](evaluating-dflow.md). For the full Get Started
+and feature list, see [`README.md`](../README.md).
+
+## Who This Guide Is For
+
+You are using or evaluating Dflow with Claude Code as your AI coding agent.
+This guide covers what Claude Code sees after `init`, how Dflow's slash
+commands are recognized, and the small Claude-Code-specific patterns worth
+knowing.
+
+You do not need to read this before running `init`. It is most useful after
+you have run `init` once and want to understand what Claude Code is
+actually loading.
+
+## Prerequisites
+
+- Claude Code CLI installed (see [claude.ai/code](https://claude.com/claude-code)).
+- Node.js / npx available (Dflow ships through npm).
+- A project directory you are comfortable initializing in. A branch or a
+  disposable sample project is recommended for first contact; see the
+  [evaluator guide playbook](evaluating-dflow.md#a-30-minute-evaluation-playbook).
+
+You do not need a paid Claude Code plan to read this document. Running
+`/dflow:*` workflows requires Claude Code itself; the workflows are
+text-based and do not require additional API keys beyond Claude Code's own
+auth.
+
+## What Claude Code Sees After `init`
+
+Running `npx dflow-sdd-ddd init` and selecting Claude Code as a target tool
+creates a thin shim at the project root:
+
+```markdown
+# CLAUDE.md - Dflow Project Instructions
+
+This project uses Dflow for spec-first AI-assisted development.
+
+Before planning or editing code, read and follow:
+
+- `dflow/specs/shared/AI-AGENT-GUIDE.md`
+
+Keep tool-specific instruction files small. The Dflow guide above is the
+single source of truth for project workflow rules, slash-command behavior,
+spec locations, and SDD/DDD constraints.
+
+If your tool supports Markdown imports, the canonical guide is imported
+below:
+
+@dflow/specs/shared/AI-AGENT-GUIDE.md
+```
+
+Two things happen when Claude Code starts in this project:
+
+1. Claude Code automatically loads `CLAUDE.md` from the project root into
+   its context. This is Claude Code's standard project instructions
+   mechanism.
+2. The trailing `@dflow/specs/shared/AI-AGENT-GUIDE.md` line uses Claude
+   Code's Markdown import syntax to inline the canonical Dflow guide. So
+   Claude Code effectively reads both files as one set of instructions.
+
+The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is where the
+real workflow rules live: project context (track, tech stack, prose
+language), the `/dflow:*` workflow table, source-of-truth file paths, and
+core SDD/DDD rules. The `CLAUDE.md` shim stays small precisely so the
+canonical guide can evolve without Claude-Code-specific edits.
+
+If a `CLAUDE.md` already existed in the project, `init` does not overwrite
+it. Instead it writes a merge snippet under `dflow/specs/shared/` that you
+can paste into your existing `CLAUDE.md` manually. This avoids destroying
+custom project instructions you already had.
+
+## Using Dflow Slash Commands in Claude Code
+
+Dflow's `/dflow:*` slash commands are workflow names recognized by the AI
+through the workflow table in `AI-AGENT-GUIDE.md`, not Claude Code's
+built-in slash command system. You type them as plain chat:
+
+```text
+/dflow:new-feature
+```
+
+Claude Code treats this as input. Because it has the workflow table loaded
+via `CLAUDE.md` import, it recognizes the prefix and enters the matching
+workflow. A typical conversation looks like:
+
+```text
+You: /dflow:new-feature
+
+Claude Code: Entering new-feature workflow. Please describe the user-facing
+capability or business behavior you want to add.
+
+You: Allow expense submitters to attach a receipt image when filing an
+expense.
+
+Claude Code: I'll start by drafting a feature spec under
+dflow/specs/features/active/. Before I do, I need a short answer on:
+[clarifying questions about scope, owner, priority]
+```
+
+The workflow then walks you through spec drafting, behavior examples,
+implementation planning, and finish-feature drift checks. The exact
+sequence depends on which workflow you entered (`/dflow:new-feature`,
+`/dflow:modify-existing`, `/dflow:bug-fix`, etc.). All workflow definitions
+live under the Dflow skill source; Claude Code follows them by reading the
+skill files when needed.
+
+Available workflow entry points:
+
+| Command | Use when |
+|---|---|
+| `/dflow:new-feature` | A new user-visible capability or business behavior is requested. |
+| `/dflow:modify-existing` | Existing behavior needs to change. |
+| `/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: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. |
+
+If you forget a command name, ask Claude Code "what dflow workflows are
+available?" — the answer comes from the workflow table it already has
+loaded.
+
+## Differences vs Other AI Tools
+
+The canonical guide (`dflow/specs/shared/AI-AGENT-GUIDE.md`) is identical
+across tools. Only the root-level shim differs:
+
+| Tool | Generated shim | Loads canonical guide via |
+|---|---|---|
+| Claude Code | `CLAUDE.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| Codex / Copilot coding agent | `AGENTS.md` | Reads file content directly when starting |
+| Gemini CLI | `GEMINI.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| GitHub Copilot | `.github/copilot-instructions.md` | Reads file content directly |
+
+You can run `dflow configure-agents` later to add another tool's shim
+without re-running `init`. Multiple tools can be active in the same project
+and stay synchronized via the canonical guide.
+
+If your team uses both Claude Code and Codex CLI on the same project (a
+common setup), no extra coordination is needed. Both tools read the same
+canonical guide; only the shim file differs.
+
+## Common Patterns and Gotchas
+
+**Keep `CLAUDE.md` thin.** If you find yourself adding workflow rules,
+spec locations, or SDD constraints to `CLAUDE.md`, those belong in
+`dflow/specs/shared/AI-AGENT-GUIDE.md` instead. The shim stays small so
+that other tools' shims don't drift away from it.
+
+**`/dflow:*` is not a Claude Code Skill installation.** `init` does not
+install anything into Claude Code's skill system. The slash commands are
+plain text patterns the AI recognizes from the workflow table. You can use
+them immediately after `init` without any Claude Code configuration.
+
+**Permission gates and Dflow workflow gates are separate.** Claude Code may
+ask permission to run a tool (e.g., write a file). Dflow's workflows have
+their own approval gates (e.g., "I drafted the spec — do you want me to
+proceed to implementation?"). Both can fire on the same action; this is
+expected and not a sign of misconfiguration.
+
+**The `@` import is not recursive.** `CLAUDE.md` imports
+`AI-AGENT-GUIDE.md`, but if `AI-AGENT-GUIDE.md` references other files
+(e.g., feature specs), those are not auto-loaded — Claude Code reads them
+on demand when entering the relevant workflow. This keeps context usage
+proportional to active work.
+
+**A pre-existing `CLAUDE.md` is preserved.** `init` will not overwrite your
+existing project instructions. Look under `dflow/specs/shared/` for the
+merge snippet `init` wrote and paste the relevant sections into your
+existing `CLAUDE.md` manually.
+
+**Cross-machine projects work.** `dflow/specs/` is plain Markdown checked
+into your repo. Anyone cloning the repo and using Claude Code in it will
+see the same Dflow setup automatically through the committed `CLAUDE.md`
+shim and the canonical guide.
+
+## Where to Go Next
+
+If you have not run `init` yet:
+
+- Follow the [evaluator guide playbook](evaluating-dflow.md#a-30-minute-evaluation-playbook)
+  to try it on a disposable sample project.
+
+If you have run `init` and want to see end-to-end workflow examples:
+
+- Read [`tutorial/01-greenfield/`](../tutorial/01-greenfield/00-setup.md) or
+  [`tutorial/02-brownfield/`](../tutorial/02-brownfield/00-setup.md). The
+  tutorial walk-throughs show conversation flows and the resulting
+  `dflow/specs/` outputs.
+
+If you want to understand the design rationale:
+
+- Read [`docs/why-ddd-for-ai.md`](why-ddd-for-ai.md).
+
+If something does not work as described:
+
+- File a docs feedback issue (see [`CONTRIBUTING.md`](../CONTRIBUTING.md)).
+  Per-tool documentation is new and feedback specifically about Claude Code
+  behavior is valuable.