dflow-sdd-ddd 0.4.0 → 0.5.0

package/lib/init.js

@@ -8,6 +8,21 @@ 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');
+const COMMAND_REGISTRY_START = '<!-- dflow-command-registry:start -->';
+const COMMAND_REGISTRY_END = '<!-- dflow-command-registry:end -->';
+const EXPECTED_COMMAND_IDS = [
+  'new-feature',
+  'modify-existing',
+  'bug-fix',
+  'new-phase',
+  'finish-feature',
+  'verify',
+  'pr-review',
+  'report-dflow-feedback',
+  'status',
+  'next',
+  'cancel'
+];
 
 const PROSE_LANGUAGE_PATTERN =
   /^[A-Za-z]{2,3}(?:-[A-Za-z]{4})?(?:-(?:[A-Za-z]{2}|[0-9]{3}))?(?:-(?:[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*$/;
@@ -91,11 +106,6 @@ const AI_AGENT_OPTIONS = [
     label: 'CLAUDE.md - Claude Code',
     aliases: ['claude', 'claude.md']
   },
-  {
-    key: 'gemini',
-    label: 'GEMINI.md - Gemini CLI',
-    aliases: ['gemini', 'gemini.md']
-  },
   {
     key: 'copilot',
     label: '.github/copilot-instructions.md - GitHub Copilot',
@@ -251,7 +261,8 @@ async function runConfigureAgents(options = {}) {
 
     const plan = await buildConfigureAgentsPlan(cwd, {
       ...projectContext,
-      aiAgents
+      aiAgents,
+      commandAdapters: Boolean(options.commandAdapters)
     });
 
     renderPreview(stdout, plan, []);
@@ -268,7 +279,7 @@ async function runConfigureAgents(options = {}) {
     result.warnings.push(...collectUnresolvedPlaceholderWarnings(plan, result.created));
 
     printResultReport(stdout, result, plan.deferred);
-    printConfigureAgentsNextSteps(stdout);
+    printConfigureAgentsNextSteps(stdout, Boolean(options.commandAdapters));
     return 0;
   } catch (error) {
     if (rl) {
@@ -999,8 +1010,14 @@ async function buildConfigureAgentsPlan(cwd, answers) {
     content
   });
 
+  const commandRegistry = answers.commandAdapters ? parseDflowCommandRegistry(content) : [];
+
   for (const agent of answers.aiAgents) {
-    await addAiAgentShim(cwd, items, agent, substitution);
+    await addAiAgentShim(cwd, items, agent, substitution, { commandRegistry });
+  }
+
+  if (answers.commandAdapters) {
+    addCommandAdapterItems(items, answers.aiAgents, commandRegistry);
   }
 
   await finalizePlanItems(cwd, items);
@@ -1017,7 +1034,8 @@ async function buildConfigureAgentsPlan(cwd, answers) {
 async function finalizePlanItems(cwd, items) {
   for (const item of items) {
     const absolute = path.join(cwd, item.relativePath);
-    item.action = (await pathExists(absolute)) ? 'skip' : 'create';
+    const targetExists = await pathExists(absolute);
+    item.action = targetExists ? (item.overwrite ? 'update' : 'skip') : 'create';
     if (item.action === 'skip') {
       item.notes = item.notes ? `${item.notes}, already exists` : 'already exists';
     }
@@ -1025,15 +1043,23 @@ async function finalizePlanItems(cwd, items) {
   }
 }
 
-async function addAiAgentShim(cwd, items, agent, substitution) {
+async function addAiAgentShim(cwd, items, agent, substitution, options = {}) {
   const target = getAiAgentTarget(agent);
   const targetPath = path.join(cwd, target.relativePath);
   const targetExists = await pathExists(targetPath);
   const targetConfigured = targetExists && await fileReferencesAiAgentGuide(targetPath);
-  const relativePath = targetExists && !targetConfigured ? target.snippetPath : target.relativePath;
-  const content = substitutePlaceholders(buildAiAgentShim(target.relativePath), substitution);
+  const commandRegistry = options.commandRegistry || [];
+  const codexCommandAdapterSnippet = target.relativePath === 'AGENTS.md' && commandRegistry.length > 0 && targetExists;
+  const relativePath = codexCommandAdapterSnippet
+    ? (targetConfigured ? 'dflow/specs/shared/AGENTS-md-command-adapters-snippet.md' : target.snippetPath)
+    : (targetExists && !targetConfigured ? target.snippetPath : target.relativePath);
+  const content = substitutePlaceholders(buildAiAgentShim(target.relativePath, options.commandRegistry), substitution);
   let notes = 'selected, tool-specific shim';
-  if (targetConfigured) {
+  if (codexCommandAdapterSnippet && targetConfigured) {
+    notes = `selected, ${target.relativePath} already points to AI-AGENT-GUIDE.md; merge this command trigger snippet manually`;
+  } else if (codexCommandAdapterSnippet) {
+    notes = `selected, ${target.relativePath} already exists; merge this command trigger snippet manually`;
+  } else if (targetConfigured) {
     notes = `selected, ${target.relativePath} already points to AI-AGENT-GUIDE.md`;
   } else if (targetExists) {
     notes = `selected, ${target.relativePath} already exists; merge this snippet manually`;
@@ -1043,7 +1069,8 @@ async function addAiAgentShim(cwd, items, agent, substitution) {
     relativePath,
     source: `generated:${agent}-shim`,
     notes,
-    content
+    content,
+    overwrite: codexCommandAdapterSnippet
   });
 }
 
@@ -1067,10 +1094,6 @@ function getAiAgentTarget(agent) {
       relativePath: 'CLAUDE.md',
       snippetPath: 'dflow/specs/shared/CLAUDE-md-snippet.md'
     },
-    gemini: {
-      relativePath: 'GEMINI.md',
-      snippetPath: 'dflow/specs/shared/GEMINI-md-snippet.md'
-    },
     copilot: {
       relativePath: '.github/copilot-instructions.md',
       snippetPath: 'dflow/specs/shared/copilot-instructions-snippet.md'
@@ -1080,12 +1103,16 @@ function getAiAgentTarget(agent) {
   return targets[agent];
 }
 
-function buildAiAgentShim(targetPath) {
+function buildAiAgentShim(targetPath, commandRegistry = []) {
   const title = targetPath === '.github/copilot-instructions.md'
     ? 'GitHub Copilot Repository Instructions'
     : `${targetPath} - Dflow Project Instructions`;
 
-  const importHint = targetPath === 'CLAUDE.md' || targetPath === 'GEMINI.md'
+  const commandTriggerHint = targetPath === 'AGENTS.md' && commandRegistry.length > 0
+    ? buildCodexCommandTriggerSection(commandRegistry)
+    : '';
+
+  const importHint = targetPath === 'CLAUDE.md'
     ? '\nIf your tool supports Markdown imports, the canonical guide is imported below:\n\n@dflow/specs/shared/AI-AGENT-GUIDE.md\n'
     : '';
 
@@ -1099,10 +1126,195 @@ Before planning or editing code, read and follow:
 
 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.${importHint}
+spec locations, and SDD/DDD constraints.${commandTriggerHint}${importHint}
 `;
 }
 
+function addCommandAdapterItems(items, aiAgents, commandRegistry) {
+  if (aiAgents.includes('claude')) {
+    for (const command of commandRegistry) {
+      items.push({
+        relativePath: `.claude/commands/dflow/dflow-${command.id}.md`,
+        source: 'generated:claude-command-adapter',
+        notes: 'command adapter, derived from dflow command registry',
+        content: buildThinCommandWrapper(command),
+        overwrite: true
+      });
+    }
+  }
+
+  if (aiAgents.includes('copilot')) {
+    for (const command of commandRegistry) {
+      items.push({
+        relativePath: `.github/prompts/dflow-${command.id}.prompt.md`,
+        source: 'generated:copilot-command-adapter',
+        notes: 'command adapter, derived from dflow command registry',
+        content: buildThinCommandWrapper(command),
+        overwrite: true
+      });
+    }
+  }
+}
+
+function buildCodexCommandTriggerSection(commandRegistry) {
+  const triggers = commandRegistry
+    .map((command) => {
+      const commandKind = command.scope === 'control' ? 'command' : 'workflow';
+      return `- \`${command.label}\` as text, or "Run the Dflow ${command.label} ${commandKind}."`;
+    })
+    .join('\n');
+
+  return `
+
+## Dflow Text Triggers
+
+Codex does not install Dflow command files. When the developer asks for a
+canonical Dflow command, treat it as a text trigger, read the canonical guide,
+and execute the matching workflow or control command.
+
+Recognized canonical triggers:
+
+${triggers}
+`;
+}
+
+function buildThinCommandWrapper(command) {
+  const argHint = command.argHint === '-'
+    ? 'Argument hint: none.'
+    : `Argument hint: ${command.argHint}.`;
+
+  return `# /dflow-${command.id}
+
+Execute the canonical \`${command.label}\` Dflow workflow or control command.
+
+Definition: \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+
+${argHint}
+`;
+}
+
+function parseDflowCommandRegistry(content) {
+  const start = content.indexOf(COMMAND_REGISTRY_START);
+  const end = content.indexOf(COMMAND_REGISTRY_END);
+
+  if (start === -1 || end === -1 || end <= start) {
+    throw new InitError('Internal error: dflow command registry markers not found in packaged AI-AGENT-GUIDE.md.');
+  }
+
+  const registryContent = content.slice(start + COMMAND_REGISTRY_START.length, end);
+  const tableLines = registryContent
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('|') && line.endsWith('|'));
+
+  if (tableLines.length < 3) {
+    throw new InitError('Internal error: dflow command registry table is empty.');
+  }
+
+  const header = parseMarkdownTableRow(tableLines[0]).map((cell) => cell.toLowerCase());
+  const expectedHeader = ['id', 'label', 'description', 'arg-hint', 'scope'];
+  if (header.length !== expectedHeader.length || !expectedHeader.every((cell, index) => header[index] === cell)) {
+    throw new InitError('Internal error: dflow command registry header must be: id, label, description, arg-hint, scope.');
+  }
+
+  const delimiter = parseMarkdownTableRow(tableLines[1]);
+  if (delimiter.length !== expectedHeader.length || !delimiter.every((cell) => /^:?-{3,}:?$/.test(cell))) {
+    throw new InitError('Internal error: dflow command registry delimiter row is invalid.');
+  }
+
+  const commands = [];
+  const seen = new Set();
+
+  for (const line of tableLines.slice(2)) {
+    const cells = parseMarkdownTableRow(line);
+    if (cells.length !== expectedHeader.length) {
+      throw new InitError(`Internal error: invalid dflow command registry row: ${line}`);
+    }
+
+    const command = {
+      id: stripInlineCode(cells[0]),
+      label: stripInlineCode(cells[1]),
+      description: stripInlineCode(cells[2]),
+      argHint: stripInlineCode(cells[3]),
+      scope: stripInlineCode(cells[4])
+    };
+
+    validateDflowCommandRegistryRow(command, seen);
+    commands.push(command);
+  }
+
+  const actualIds = commands.map((command) => command.id);
+  const missingIds = EXPECTED_COMMAND_IDS.filter((id) => !actualIds.includes(id));
+  const extraIds = actualIds.filter((id) => !EXPECTED_COMMAND_IDS.includes(id));
+  if (missingIds.length > 0 || extraIds.length > 0 || commands.length !== EXPECTED_COMMAND_IDS.length) {
+    throw new InitError(
+      `Internal error: dflow command registry must contain exactly these command ids: ${EXPECTED_COMMAND_IDS.join(', ')}.`
+    );
+  }
+
+  return commands;
+}
+
+function parseMarkdownTableRow(line) {
+  const trimmed = line.trim();
+  const inner = trimmed.slice(1, -1);
+  const cells = [];
+  let current = '';
+
+  for (let index = 0; index < inner.length; index += 1) {
+    const char = inner[index];
+    const next = inner[index + 1];
+
+    if (char === '\\' && next === '|') {
+      current += '|';
+      index += 1;
+      continue;
+    }
+
+    if (char === '|') {
+      cells.push(current.trim());
+      current = '';
+      continue;
+    }
+
+    current += char;
+  }
+
+  cells.push(current.trim());
+  return cells;
+}
+
+function stripInlineCode(value) {
+  const trimmed = String(value || '').trim();
+  if (trimmed.startsWith('`') && trimmed.endsWith('`') && trimmed.length >= 2) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function validateDflowCommandRegistryRow(command, seen) {
+  if (!/^[a-z][a-z0-9-]*$/.test(command.id)) {
+    throw new InitError(`Internal error: invalid dflow command id: ${command.id}`);
+  }
+  if (seen.has(command.id)) {
+    throw new InitError(`Internal error: duplicate dflow command id: ${command.id}`);
+  }
+  seen.add(command.id);
+
+  if (command.label !== `/dflow:${command.id}`) {
+    throw new InitError(`Internal error: dflow command label must be /dflow:${command.id}.`);
+  }
+  if (!command.description) {
+    throw new InitError(`Internal error: dflow command ${command.id} is missing a description.`);
+  }
+  if (!command.argHint) {
+    throw new InitError(`Internal error: dflow command ${command.id} is missing an arg-hint.`);
+  }
+  if (!command.scope) {
+    throw new InitError(`Internal error: dflow command ${command.id} is missing a scope.`);
+  }
+}
+
 function buildDeferredItems(edition) {
   const deferred = [...DEFERRED_COMMON];
   if (edition === 'greenfield') {
@@ -1433,6 +1645,7 @@ function renderPreview(stdout, plan, warnings) {
 async function writeFilePlan(cwd, plan) {
   const result = {
     created: [],
+    updated: [],
     skipped: [],
     warnings: []
   };
@@ -1442,6 +1655,13 @@ async function writeFilePlan(cwd, plan) {
 
     try {
       if (await pathExists(targetPath)) {
+        if (item.overwrite) {
+          await fs.mkdir(path.dirname(targetPath), { recursive: true });
+          await fs.writeFile(targetPath, item.content);
+          result.updated.push(item.relativePath);
+          continue;
+        }
+
         result.skipped.push(item.relativePath);
         result.warnings.push(`Skipped existing target: ${item.relativePath}`);
         if (item.relativePath === 'dflow/specs/shared/_conventions.md') {
@@ -1528,6 +1748,9 @@ function printResultReport(stdout, result, deferred) {
   stdout.write('\nCreated:\n');
   printList(stdout, result.created);
 
+  stdout.write('\nUpdated:\n');
+  printList(stdout, result.updated);
+
   stdout.write('\nSkipped:\n');
   printList(stdout, result.skipped);
 
@@ -1552,7 +1775,11 @@ Recommended next steps:
 `);
 }
 
-function printConfigureAgentsNextSteps(stdout) {
+function printConfigureAgentsNextSteps(stdout, commandAdapters = false) {
+  const commandAdapterStep = commandAdapters
+    ? '- Command adapters use adapter-native names such as `/dflow-new-feature`; canonical `/dflow:*` names remain defined in dflow/specs/shared/AI-AGENT-GUIDE.md.\n'
+    : '';
+
   stdout.write(`
 Dflow AI agent configuration complete.
 
@@ -1560,6 +1787,7 @@ Recommended next steps:
 - Keep AI-agent-specific root files small.
 - Put durable workflow changes in dflow/specs/shared/AI-AGENT-GUIDE.md.
 - If a merge snippet was created, review it and merge the pointer into the existing tool instruction file.
+${commandAdapterStep}
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {

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

@@ -31,6 +31,45 @@ are not available in the current AI tool:
 | `/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. |
+| `/dflow:status` | You need the current workflow state, current step, completed work, in-progress work, remaining work, pending decision, and next valid action. |
+| `/dflow:next` | An active workflow is waiting at a step gate and the developer confirms continuing to the next step. |
+| `/dflow:cancel` | The developer wants to abort the current workflow and return to free conversation without rollback. |
+
+Machine-readable source for rendering tool-specific thin wrappers:
+
+<!-- dflow-command-registry:start -->
+| id | label | description | arg-hint | scope |
+|---|---|---|---|---|
+| new-feature | /dflow:new-feature | Start a new user-visible feature or business behavior. | feature request | workflow |
+| modify-existing | /dflow:modify-existing | Change existing behavior. | change request | workflow |
+| bug-fix | /dflow:bug-fix | Investigate a defect described by expected vs actual behavior. | expected vs actual | workflow |
+| new-phase | /dflow:new-phase | Add another implementation slice to an active feature. | feature id or phase goal | workflow |
+| finish-feature | /dflow:finish-feature | Close implementation with drift checks and archived feature state. | feature id | workflow |
+| verify | /dflow:verify | Check specs, domain docs, implementation, and tests for consistency. | area or feature id | workflow |
+| pr-review | /dflow:pr-review | Review a ready change for SDD/DDD alignment. | change or branch | workflow |
+| report-dflow-feedback | /dflow:report-dflow-feedback | Draft sanitized upstream feedback about Dflow. | issue or improvement | workflow |
+| status | /dflow:status | Report current workflow state and next valid action. | - | control |
+| next | /dflow:next | Confirm the active step gate and continue. | - | control |
+| cancel | /dflow:cancel | Abort the active workflow and return to free conversation. | - | control |
+<!-- dflow-command-registry:end -->
+
+## Status / Control Commands
+
+`/dflow:status` reports active workflow state. Include these fields: workflow,
+step, completed, in-progress, remaining, pending decision, and next valid action.
+If no workflow is active, say that no workflow is active and list valid flow-entry
+or standalone commands.
+
+`/dflow:next` is valid only at a step gate in an active workflow. Treat it as
+developer confirmation equivalent to "OK" or "continue", then move to the next
+workflow step.
+
+`/dflow:cancel` aborts the current workflow and returns to free conversation.
+Do not rollback changes, delete artifacts, or rewrite specs merely because the
+workflow was cancelled.
+
+When no workflow is active, `/dflow:next` and `/dflow:cancel` must report that
+there is no active workflow to advance or cancel.
 
 ## Source of Truth
 
@@ -85,9 +124,9 @@ review is required.
 ## Tool-Specific Notes
 
 This file is the canonical Dflow guide. Root-level files such as
-`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `.github/copilot-instructions.md`
+`AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`
 should stay thin and point back here.
 
 If a tool does not support Dflow slash commands, treat the command names as
-plain workflow names and execute the matching process from the Dflow skill
-source in this repository.
+plain workflow names. This guide contains the installed runtime behavior
+contract; execute the workflow semantics defined here directly.

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

@@ -31,6 +31,45 @@ are not available in the current AI tool:
 | `/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. |
+| `/dflow:status` | You need the current workflow state, current step, completed work, in-progress work, remaining work, pending decision, and next valid action. |
+| `/dflow:next` | An active workflow is waiting at a step gate and the developer confirms continuing to the next step. |
+| `/dflow:cancel` | The developer wants to abort the current workflow and return to free conversation without rollback. |
+
+Machine-readable source for rendering tool-specific thin wrappers:
+
+<!-- dflow-command-registry:start -->
+| id | label | description | arg-hint | scope |
+|---|---|---|---|---|
+| new-feature | /dflow:new-feature | Start a new user-visible feature or business behavior. | feature request | workflow |
+| modify-existing | /dflow:modify-existing | Change existing behavior. | change request | workflow |
+| bug-fix | /dflow:bug-fix | Investigate a defect described by expected vs actual behavior. | expected vs actual | workflow |
+| new-phase | /dflow:new-phase | Add another implementation slice to an active feature. | feature id or phase goal | workflow |
+| finish-feature | /dflow:finish-feature | Close implementation with drift checks and archived feature state. | feature id | workflow |
+| verify | /dflow:verify | Check specs, domain docs, implementation, and tests for consistency. | area or feature id | workflow |
+| pr-review | /dflow:pr-review | Review a ready change for SDD/DDD alignment. | change or branch | workflow |
+| report-dflow-feedback | /dflow:report-dflow-feedback | Draft sanitized upstream feedback about Dflow. | issue or improvement | workflow |
+| status | /dflow:status | Report current workflow state and next valid action. | - | control |
+| next | /dflow:next | Confirm the active step gate and continue. | - | control |
+| cancel | /dflow:cancel | Abort the active workflow and return to free conversation. | - | control |
+<!-- dflow-command-registry:end -->
+
+## Status / Control Commands
+
+`/dflow:status` reports active workflow state. Include these fields: workflow,
+step, completed, in-progress, remaining, pending decision, and next valid action.
+If no workflow is active, say that no workflow is active and list valid flow-entry
+or standalone commands.
+
+`/dflow:next` is valid only at a step gate in an active workflow. Treat it as
+developer confirmation equivalent to "OK" or "continue", then move to the next
+workflow step.
+
+`/dflow:cancel` aborts the current workflow and returns to free conversation.
+Do not rollback changes, delete artifacts, or rewrite specs merely because the
+workflow was cancelled.
+
+When no workflow is active, `/dflow:next` and `/dflow:cancel` must report that
+there is no active workflow to advance or cancel.
 
 ## Source of Truth
 
@@ -85,9 +124,9 @@ review is required.
 ## Tool-Specific Notes
 
 This file is the canonical Dflow guide. Root-level files such as
-`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `.github/copilot-instructions.md`
+`AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`
 should stay thin and point back here.
 
 If a tool does not support Dflow slash commands, treat the command names as
-plain workflow names and execute the matching process from the Dflow skill
-source in this repository.
+plain workflow names. This guide contains the installed runtime behavior
+contract; execute the workflow semantics defined here directly.

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

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