dflow-sdd-ddd 0.1.1 → 0.2.0

package/docs/using-with-codex.md

@@ -0,0 +1,244 @@
+# Using Dflow with Codex CLI
+
+A walk-through of what Dflow looks like when your AI coding agent is
+[Codex CLI](https://developers.openai.com/codex/cli). About 10 minutes to
+read.
+
+This guide focuses on the Codex CLI 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 Codex CLI as your AI coding agent.
+This guide covers what Codex sees after `init`, how the `AGENTS.md` shim
+points to the canonical Dflow guide, and the Codex-specific command and
+permission 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 Codex CLI is actually
+loading.
+
+## Prerequisites
+
+- Codex CLI installed and authenticated (see
+  [developers.openai.com/codex/cli](https://developers.openai.com/codex/cli)).
+- 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).
+- Codex started from the initialized project root, or with `codex --cd` set
+  to that root, so Codex's `AGENTS.md` discovery includes the Dflow shim.
+
+Running Dflow workflows does not require a separate Dflow service or API key.
+The workflows are Markdown-based instructions and project files.
+
+## What Codex CLI Sees After `init`
+
+Running `npx dflow-sdd-ddd init` and selecting
+`AGENTS.md - Codex / Copilot coding agent` as a target tool creates a thin
+shim at the project root:
+
+```markdown
+# AGENTS.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.
+```
+
+Two things matter when Codex starts in this project:
+
+1. Codex CLI reads `AGENTS.md` as project instructions. This is Codex's
+   standard repository-instruction mechanism.
+2. The Dflow shim does not include a Markdown import line. Unlike the
+   Claude Code and Gemini shims, generated `AGENTS.md` does not contain
+   `@dflow/specs/shared/AI-AGENT-GUIDE.md`.
+
+That means Codex sees the pointer immediately, but the canonical Dflow guide
+is not auto-inlined by the shim. Before planning or editing, Codex should
+follow the pointer and read `dflow/specs/shared/AI-AGENT-GUIDE.md`. If Codex
+starts answering a Dflow request without mentioning that file, steer it
+explicitly: "Before continuing, read and follow
+`dflow/specs/shared/AI-AGENT-GUIDE.md`."
+
+The canonical guide 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 `AGENTS.md` shim
+stays small so the same canonical guide can serve Codex CLI, Claude Code,
+Gemini CLI, GitHub Copilot, and other tools.
+
+If an `AGENTS.md` already existed in the project, `init` does not overwrite
+it. If the existing file does not already point to
+`dflow/specs/shared/AI-AGENT-GUIDE.md`, `init` writes a merge snippet under
+`dflow/specs/shared/AGENTS-md-snippet.md` that you can merge manually. This
+avoids destroying custom project instructions you already had.
+
+## Using Dflow Workflow Commands in Codex CLI
+
+Codex CLI has its own built-in slash command layer for controlling the CLI
+session. Commands such as `/permissions`, `/model`, `/status`, `/diff`,
+`/review`, and `/init` are Codex CLI controls, not Dflow workflows.
+
+Dflow's `/dflow:*` entries are workflow names recognized by the AI through
+`AI-AGENT-GUIDE.md`, not registered Codex CLI commands. Raw
+`/dflow:new-feature` passthrough behavior in Codex CLI should be verified
+with the maintainer for the supported Codex version. The reliable form is to
+name the workflow as a plain chat instruction:
+
+```text
+Run the Dflow /dflow:new-feature workflow.
+```
+
+If your Codex CLI version passes unknown slash-prefixed input through to the
+model, this shorter form may also work (verify with maintainer):
+
+```text
+/dflow:new-feature
+```
+
+If Codex reports an unknown slash command, re-send the request in prose:
+
+```text
+Treat /dflow:new-feature as a Dflow workflow name, not as a Codex CLI
+command. Read dflow/specs/shared/AI-AGENT-GUIDE.md and start that workflow.
+```
+
+A typical conversation looks like:
+
+```text
+You: Run the Dflow /dflow:new-feature workflow.
+
+Codex CLI: I'll read dflow/specs/shared/AI-AGENT-GUIDE.md first, then use the
+new-feature workflow. Please describe the user-visible capability or business
+behavior you want to add.
+
+You: Allow expense submitters to attach a receipt image when filing an
+expense.
+
+Codex CLI: I'll start by drafting a feature spec under
+dflow/specs/features/active/. Before I do, I have a few clarifying questions.
+```
+
+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.).
+
+Available workflow entry points:
+
+| Workflow | 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 workflow name, ask Codex to read
+`dflow/specs/shared/AI-AGENT-GUIDE.md` and list the available Dflow
+workflows.
+
+## 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` | Project instructions load the shim; Codex must follow the pointer and read the guide |
+| Gemini CLI | `GEMINI.md` | `@dflow/specs/shared/AI-AGENT-GUIDE.md` Markdown import |
+| GitHub Copilot | `.github/copilot-instructions.md` | Reads repository instructions 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.
+
+Codex also has its own project-instruction layering. It can read global
+instructions from Codex home and project instructions from `AGENTS.md` files
+between the project root and the current working directory. For Dflow, the
+important practical rule is simple: start Codex at the initialized project
+root, and keep the Dflow pointer in the nearest relevant `AGENTS.md`.
+
+If your team uses both Claude Code and Codex CLI on the same project, no
+extra Dflow coordination is needed. Both tools use the same canonical guide;
+only the shim file and loading mechanism differ.
+
+## Common Patterns and Gotchas
+
+**Keep `AGENTS.md` thin.** If you find yourself adding workflow rules, spec
+locations, or SDD constraints to `AGENTS.md`, those belong in
+`dflow/specs/shared/AI-AGENT-GUIDE.md` instead. The shim stays small so that
+other tools' shims do not drift away from it.
+
+**Codex does not inline the Dflow guide from `AGENTS.md`.** The generated
+Codex shim has a normal Markdown bullet pointing to the canonical guide, not
+an `@...` import. Ask Codex to read `AI-AGENT-GUIDE.md` if it appears to be
+working from the shim alone.
+
+**`/dflow:*` is not a Codex CLI built-in slash command.** Codex slash
+commands control the Codex session itself. Use Dflow workflow names as plain
+chat instructions when raw slash input is intercepted or rejected. Raw
+`/dflow:*` passthrough behavior should be verified with the maintainer for
+the supported Codex version.
+
+**Do not confuse Codex `/init` with Dflow `init`.** Codex `/init` creates a
+generic `AGENTS.md` scaffold for Codex. Dflow setup is `npx dflow-sdd-ddd
+init`, and adding later tool shims is `dflow configure-agents`.
+
+**Permission gates and Dflow workflow gates are separate.** Codex may ask
+permission to run a command, edit outside the workspace, or access network
+depending on its sandbox and approval settings. Dflow workflows have their
+own approval gates, such as confirming a spec before implementation. Both
+can appear in the same session; this is expected.
+
+**The common Codex local-work preset is workspace write plus on-request
+approvals.** In current Codex CLI terminology this is
+`--sandbox workspace-write --ask-for-approval on-request`. In that mode,
+Codex can work inside the project and asks before going beyond the sandbox,
+such as writing outside the workspace or accessing network.
+
+**Existing `AGENTS.md` files are preserved.** If Dflow cannot safely write
+the root shim because the file already exists, look under
+`dflow/specs/shared/` for the merge snippet and merge the Dflow pointer into
+your existing project instructions manually.
+
+**Nested `AGENTS.md` files can change what Codex sees.** Codex layers project
+instructions along the path to the current working directory. If a subfolder
+has its own `AGENTS.md` or `AGENTS.override.md`, make sure it does not hide
+or contradict the Dflow pointer you expect Codex to follow.
+
+## 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 Codex CLI
+  behavior is valuable.

package/lib/init.js

@@ -3,6 +3,8 @@ const path = require('node:path');
 const readline = require('node:readline');
 const { TextDecoder } = require('node:util');
 
+const pkg = require('../package.json');
+
 const MIN_NODE_VERSION = '22.0.0';
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TEMPLATE_ROOT = path.join(PACKAGE_ROOT, 'templates');
@@ -320,7 +322,7 @@ async function runPreflight(cwd) {
   const legacySpecsPath = path.join(cwd, 'specs');
   if ((await pathExists(legacySpecsPath)) && (await containsInitializedContent(legacySpecsPath))) {
     warnings.push(
-      'Detected legacy specs/. Dflow V1 will not migrate or modify it; new files will be created under dflow/specs/.'
+      'Detected legacy specs/. Dflow V1 will not migrate or modify it; new files will be created under dflow/specs/. See docs/migrating-to-dflow-v1.md for the manual migration checklist.'
     );
   }
 
@@ -1117,6 +1119,7 @@ function buildSubstitutionMap(cwd, answers) {
     ['{tech-stack-summary}', answers.techStackSummary],
     ['{migration-context}', answers.migrationContext],
     ['{prose-language}', answers.proseLanguage],
+    ['{dflow-version}', pkg.version],
     ['{ASP.NET Core version}', extracted.aspNetCoreVersion || '{ASP.NET Core version}'],
     ['{EF Core version}', extracted.efCoreVersion || '{EF Core version}'],
     ['{MediatR version}', extracted.mediatRVersion || '{MediatR version}'],
@@ -1479,8 +1482,101 @@ function dedupe(values) {
   return Array.from(new Set(values));
 }
 
+async function runDoctor(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+
+  try {
+    if (compareVersions(process.versions.node, MIN_NODE_VERSION) < 0) {
+      throw new InitError(`Dflow doctor requires Node.js ${MIN_NODE_VERSION}+.`, 1);
+    }
+
+    const findings = [];
+    await checkLegacyRootSpecsDir(cwd, findings);
+    await checkLegacySharedDir(cwd, findings);
+    await checkConventionsDflowVersion(cwd, findings);
+
+    printDoctorReport(stdout, cwd, findings);
+    return 0;
+  } catch (error) {
+    if (error instanceof InitError) {
+      stderr.write(`${error.message}\n`);
+      return error.exitCode;
+    }
+    stderr.write(`${error && error.message ? error.message : error}\n`);
+    return 1;
+  }
+}
+
+async function checkLegacyRootSpecsDir(cwd, findings) {
+  const legacyPath = path.join(cwd, 'specs');
+  if ((await pathExists(legacyPath)) && (await containsInitializedContent(legacyPath))) {
+    findings.push({
+      level: 'warn',
+      title: 'Legacy specs/ directory at project root',
+      detail: 'V1 layout uses dflow/specs/ instead. The CLI does not modify root specs/.',
+      action: 'See docs/migrating-to-dflow-v1.md (Step 1) for the manual migration steps.'
+    });
+  }
+}
+
+async function checkLegacySharedDir(cwd, findings) {
+  const candidates = [
+    path.join(cwd, 'dflow', 'specs', '_共用'),
+    path.join(cwd, 'specs', '_共用')
+  ];
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) {
+      const rel = normalizePath(path.relative(cwd, candidate));
+      findings.push({
+        level: 'warn',
+        title: `Legacy ${rel}/ directory`,
+        detail: 'V1 layout uses shared/ (canonical English directory name).',
+        action: 'See docs/migrating-to-dflow-v1.md (Step 2) for the rename steps.'
+      });
+    }
+  }
+}
+
+async function checkConventionsDflowVersion(cwd, findings) {
+  const conventionsPath = path.join(cwd, 'dflow', 'specs', 'shared', '_conventions.md');
+  if (!(await pathExists(conventionsPath))) return;
+  const content = await fs.readFile(conventionsPath, 'utf8').catch(() => '');
+  if (!/^> Dflow Version:/m.test(content)) {
+    findings.push({
+      level: 'info',
+      title: 'dflow/specs/shared/_conventions.md missing Dflow Version line',
+      detail: 'V1 init writes a `> Dflow Version: <x.y.z>` line in the front matter automatically. This project predates that convention.',
+      action: 'Optionally add the line manually so future migration / review can identify the spec convention version.'
+    });
+  }
+}
+
+function printDoctorReport(stdout, cwd, findings) {
+  stdout.write(`Dflow Doctor ${pkg.version}\n`);
+  stdout.write(`Project: ${cwd}\n\n`);
+
+  if (findings.length === 0) {
+    stdout.write('All checks passed. No legacy artifacts detected.\n');
+    return;
+  }
+
+  for (const finding of findings) {
+    stdout.write(`[${finding.level}] ${finding.title}\n`);
+    stdout.write(`        ${finding.detail}\n`);
+    stdout.write(`        ${finding.action}\n\n`);
+  }
+
+  const counts = { warn: 0, info: 0 };
+  for (const f of findings) counts[f.level] = (counts[f.level] || 0) + 1;
+  stdout.write(`${findings.length} finding(s): ${counts.warn} warn, ${counts.info} info.\n`);
+  stdout.write('Doctor is read-only and does not modify any files.\n');
+}
+
 module.exports = {
   runConfigureAgents,
+  runDoctor,
   runInit,
   validateProseLanguage,
   ensureProseLanguageSection,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {
@@ -12,8 +12,12 @@
   },
   "files": [
     "bin/",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "docs/",
     "lib/",
+    "TEMPLATE-COVERAGE.md",
+    "TEMPLATE-LANGUAGE-GLOSSARY.md",
     "templates/",
     "README.md"
   ],

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

@@ -30,6 +30,7 @@ are not available in the current AI tool:
 | `/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. |
 
 ## Source of Truth
 
@@ -53,6 +54,33 @@ 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 shell command `npx dflow-sdd-ddd init`).
+- 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.
+
 ## Tool-Specific Notes
 
 This file is the canonical Dflow guide. Root-level files such as

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

@@ -105,6 +105,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - `/dflow:finish-feature` — feature 收尾
 - `/dflow:pr-review` — PR 審查
 - `/dflow:verify` — rules.md ↔ behavior.md 漂移檢查
+- `/dflow:report-dflow-feedback` — 草擬給 Dflow upstream 的已清理回饋，不自動送出
 - `/dflow:status` / `/dflow:next` / `/dflow:cancel` — 狀態管理
 
 ### Project-Level Supplemental Rules

package/templates/brownfield/scaffolding/_conventions.md

@@ -3,6 +3,7 @@
 # Spec Writing Conventions — {System Name}
 
 > Created: {YYYY-MM-DD}
+> Dflow Version: {dflow-version}
 > Scope: how spec documents are authored and named in this project.
 > Audience: engineers writing specs; AI assistants producing spec drafts.
 

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

@@ -30,6 +30,7 @@ are not available in the current AI tool:
 | `/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. |
 
 ## Source of Truth
 
@@ -53,6 +54,33 @@ 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 shell command `npx dflow-sdd-ddd init`).
+- 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.
+
 ## Tool-Specific Notes
 
 This file is the canonical Dflow guide. Root-level files such as

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

@@ -108,6 +108,7 @@ AI 的完整決策樹、Workflow Transparency、Ceremony Scaling 三層判準
 - `/dflow:bug-fix` — Bug 修復
 - `/dflow:finish-feature` — Feature 收尾 + 整合摘要
 - `/dflow:pr-review` — PR 審查檢查點
+- `/dflow:report-dflow-feedback` — 草擬給 Dflow upstream 的已清理回饋，不自動送出
 
 ### Core Principles (Project Reaffirmed)
 

package/templates/greenfield/scaffolding/_conventions.md

@@ -3,6 +3,7 @@
 # Spec Writing Conventions — {System Name}
 
 > Created: {YYYY-MM-DD}
+> Dflow Version: {dflow-version}
 > Scope: how spec documents are authored and named in this project.
 > Audience: engineers writing specs; AI assistants producing spec drafts.