dflow-sdd-ddd 0.5.0 → 0.7.0

package/lib/init.js

@@ -10,6 +10,8 @@ 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 COMMAND_ADAPTER_GENERATED_MARKER = '<!-- dflow-generated: command-adapter -->';
+const SKILL_ADAPTER_GENERATED_MARKER = '<!-- dflow-generated: skill-adapter -->';
 const EXPECTED_COMMAND_IDS = [
   'new-feature',
   'modify-existing',
@@ -23,6 +25,28 @@ const EXPECTED_COMMAND_IDS = [
   'next',
   'cancel'
 ];
+const LEGACY_COMMAND_ADAPTERS = [
+  {
+    version: '0.5.0',
+    agent: 'claude',
+    source: 'generated:legacy-claude-command-adapter-v0.5.0',
+    pathPattern: '.claude/commands/dflow/dflow-<id>.md',
+    fingerprint: 'v0.5.0 buildThinCommandWrapper',
+    commands: [
+      { id: 'new-feature', label: '/dflow:new-feature', argHint: 'feature request' },
+      { id: 'modify-existing', label: '/dflow:modify-existing', argHint: 'change request' },
+      { id: 'bug-fix', label: '/dflow:bug-fix', argHint: 'expected vs actual' },
+      { id: 'new-phase', label: '/dflow:new-phase', argHint: 'feature id or phase goal' },
+      { id: 'finish-feature', label: '/dflow:finish-feature', argHint: 'feature id' },
+      { id: 'verify', label: '/dflow:verify', argHint: 'area or feature id' },
+      { id: 'pr-review', label: '/dflow:pr-review', argHint: 'change or branch' },
+      { id: 'report-dflow-feedback', label: '/dflow:report-dflow-feedback', argHint: 'issue or improvement' },
+      { id: 'status', label: '/dflow:status', argHint: '-' },
+      { id: 'next', label: '/dflow:next', argHint: '-' },
+      { id: 'cancel', label: '/dflow:cancel', argHint: '-' }
+    ]
+  }
+];
 
 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}))*$/;
@@ -262,10 +286,12 @@ async function runConfigureAgents(options = {}) {
     const plan = await buildConfigureAgentsPlan(cwd, {
       ...projectContext,
       aiAgents,
-      commandAdapters: Boolean(options.commandAdapters)
+      commandAdapters: Boolean(options.commandAdapters),
+      skills: Boolean(options.skills)
     });
 
-    renderPreview(stdout, plan, []);
+    const warnings = plan.warnings || [];
+    renderPreview(stdout, plan, warnings);
     const confirmed = await askConfirmation(rl, 'Create these files? (y/N) ');
 
     if (!confirmed) {
@@ -276,6 +302,7 @@ async function runConfigureAgents(options = {}) {
     rl = undefined;
 
     const result = await writeFilePlan(cwd, plan);
+    result.warnings.unshift(...warnings);
     result.warnings.push(...collectUnresolvedPlaceholderWarnings(plan, result.created));
 
     printResultReport(stdout, result, plan.deferred);
@@ -1000,6 +1027,7 @@ async function buildConfigureAgentsPlan(cwd, answers) {
     optionalFiles: answers.optionalFiles || []
   });
   const items = [];
+  const warnings = [];
 
   let content = await readPackagedTemplate(answers.edition, 'scaffolding/AI-AGENT-GUIDE.md');
   content = substitutePlaceholders(content, substitution);
@@ -1022,9 +1050,16 @@ async function buildConfigureAgentsPlan(cwd, answers) {
 
   await finalizePlanItems(cwd, items);
 
+  if (answers.commandAdapters) {
+    await addLegacyCommandAdapterCleanupItems(cwd, items, answers.aiAgents, warnings);
+  }
+
+  await addSkillAdapterItems(cwd, items, answers.aiAgents, answers.skills, warnings);
+
   return {
     items,
     deferred: [],
+    warnings,
     unresolvedInitPlaceholders: Array.from(substitution.entries())
       .filter(([placeholder, value]) => placeholder === value)
       .map(([placeholder]) => placeholder)
@@ -1134,10 +1169,10 @@ function addCommandAdapterItems(items, aiAgents, commandRegistry) {
   if (aiAgents.includes('claude')) {
     for (const command of commandRegistry) {
       items.push({
-        relativePath: `.claude/commands/dflow/dflow-${command.id}.md`,
+        relativePath: `.claude/commands/dflow/${command.id}.md`,
         source: 'generated:claude-command-adapter',
         notes: 'command adapter, derived from dflow command registry',
-        content: buildThinCommandWrapper(command),
+        content: buildThinCommandWrapper(command, `/dflow:${command.id}`),
         overwrite: true
       });
     }
@@ -1149,13 +1184,165 @@ function addCommandAdapterItems(items, aiAgents, commandRegistry) {
         relativePath: `.github/prompts/dflow-${command.id}.prompt.md`,
         source: 'generated:copilot-command-adapter',
         notes: 'command adapter, derived from dflow command registry',
-        content: buildThinCommandWrapper(command),
+        content: buildThinCommandWrapper(command, `/dflow-${command.id}`),
         overwrite: true
       });
     }
   }
 }
 
+async function addLegacyCommandAdapterCleanupItems(cwd, items, aiAgents, warnings) {
+  for (const legacy of LEGACY_COMMAND_ADAPTERS) {
+    if (!aiAgents.includes(legacy.agent)) {
+      continue;
+    }
+
+    for (const command of legacy.commands) {
+      const relativePath = legacy.pathPattern.replace('<id>', command.id);
+      const targetPath = path.join(cwd, relativePath);
+      let stats;
+
+      try {
+        stats = await fs.stat(targetPath);
+      } catch (error) {
+        if (error.code === 'ENOENT') {
+          continue;
+        }
+        throw error;
+      }
+
+      if (!stats.isFile()) {
+        warnings.push(`Found legacy Dflow command adapter path but it is not a file; not removed: ${relativePath}`);
+        continue;
+      }
+
+      const content = await fs.readFile(targetPath, 'utf8');
+      const expectedContent = buildLegacyCommandAdapterFingerprint(legacy, command);
+      if (normalizeCommandAdapterFingerprint(content) !== normalizeCommandAdapterFingerprint(expectedContent)) {
+        warnings.push(`Found legacy Dflow command adapter with non-generated content; not removed: ${relativePath}. Inspect it manually before deleting.`);
+        continue;
+      }
+
+      items.push({
+        relativePath,
+        source: legacy.source,
+        notes: `stale dflow adapter generated by Dflow ${legacy.version}`,
+        action: 'remove',
+        size: Buffer.byteLength(content, 'utf8'),
+        expectedContent
+      });
+    }
+  }
+}
+
+function buildDflowSkillAdapter() {
+  return `---
+name: dflow
+description: >
+  Dflow SDD/DDD workflow guardian for this project. PRIMARY: the canonical
+  /dflow:* commands (/dflow:new-feature, /dflow:modify-existing, /dflow:bug-fix,
+  /dflow:new-phase, /dflow:finish-feature, /dflow:pr-review, /dflow:verify,
+  /dflow:report-dflow-feedback, /dflow:status, /dflow:next, /dflow:cancel).
+  SECONDARY (auto-trigger safety net) — engage ONLY for: adding or changing
+  product/domain behavior, new requirements, a feature or bug-fix workflow, or
+  spec-impacting architecture/domain-model decisions. Do NOT engage for pure
+  refactors, infrastructure chores, formatting, or general code questions.
+  When engaged by natural language, DO NOT auto-enter a workflow: judge the
+  intent, suggest the matching /dflow: command, and wait for confirmation.
+---
+
+${SKILL_ADAPTER_GENERATED_MARKER}
+
+# Dflow SDD/DDD Workflow Guardian
+
+This project uses Dflow for spec-first AI-assisted development. The canonical
+workflow contract, command registry, spec locations, and SDD/DDD rules live in:
+
+- \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+
+When this skill engages, read that guide and follow the matching \`/dflow:\`
+workflow or control command defined there. Do not duplicate or invent workflow
+steps here — the guide is the single source of truth.
+
+If engaged by natural language (not an explicit \`/dflow:\` command): identify
+which \`/dflow:\` command fits, suggest it, and wait for the developer to confirm
+before entering any workflow.
+`;
+}
+
+async function addSkillAdapterItems(cwd, items, aiAgents, skills, warnings) {
+  if (!skills) {
+    return;
+  }
+
+  if (!aiAgents.includes('claude')) {
+    warnings.push(
+      'The --skills flag currently supports Claude Code only; no skill adapter was generated because Claude Code was not a selected target.'
+    );
+    return;
+  }
+
+  const relativePath = '.claude/skills/dflow/SKILL.md';
+  const targetPath = path.join(cwd, relativePath);
+
+  // The thin skill is edition-neutral (it only points to the per-edition guide),
+  // so there is nothing edition-specific to go stale — re-running just rewrites
+  // the same marker-guarded file (idempotent). No LEGACY skill set exists yet
+  // (skills are new in PROPOSAL-038); future skill cleanup would extend the same
+  // LEGACY_* / addLegacyCommandAdapterCleanupItems marker-fingerprint pattern.
+  let existingContent;
+  try {
+    existingContent = await fs.readFile(targetPath, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+    existingContent = undefined;
+  }
+
+  if (existingContent !== undefined && !existingContent.includes(SKILL_ADAPTER_GENERATED_MARKER)) {
+    warnings.push(
+      'Existing .claude/skills/dflow/SKILL.md is not a Dflow-generated skill; left unchanged. Remove or rename it to let Dflow manage this skill.'
+    );
+    return;
+  }
+
+  items.push({
+    relativePath,
+    source: 'generated:claude-skill-adapter',
+    notes: 'skill adapter, thin skill pointing to AI-AGENT-GUIDE.md',
+    content: buildDflowSkillAdapter(),
+    overwrite: true
+  });
+}
+
+function buildLegacyCommandAdapterFingerprint(legacy, command) {
+  if (legacy.version === '0.5.0' && legacy.fingerprint === 'v0.5.0 buildThinCommandWrapper') {
+    return buildLegacyV050ThinCommandWrapper(command);
+  }
+
+  throw new InitError(`Internal error: unsupported legacy command adapter fingerprint: ${legacy.version}`);
+}
+
+function buildLegacyV050ThinCommandWrapper(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 normalizeCommandAdapterFingerprint(content) {
+  return String(content).replace(/\r\n/g, '\n');
+}
+
 function buildCodexCommandTriggerSection(commandRegistry) {
   const triggers = commandRegistry
     .map((command) => {
@@ -1172,18 +1359,25 @@ 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.
 
+If the CLI intercepts a slash-prefixed Dflow name such as \`/dflow:status\` as
+an unknown command, the developer may resend it without the slash, for example
+\`dflow:status\`. Treat that as the same Dflow text trigger, read the guide,
+and execute it.
+
 Recognized canonical triggers:
 
 ${triggers}
 `;
 }
 
-function buildThinCommandWrapper(command) {
+function buildThinCommandWrapper(command, displayName = command.label) {
   const argHint = command.argHint === '-'
     ? 'Argument hint: none.'
     : `Argument hint: ${command.argHint}.`;
 
-  return `# /dflow-${command.id}
+  return `# ${displayName}
+
+${COMMAND_ADAPTER_GENERATED_MARKER}
 
 Execute the canonical \`${command.label}\` Dflow workflow or control command.
 
@@ -1646,6 +1840,7 @@ async function writeFilePlan(cwd, plan) {
   const result = {
     created: [],
     updated: [],
+    removed: [],
     skipped: [],
     warnings: []
   };
@@ -1654,6 +1849,37 @@ async function writeFilePlan(cwd, plan) {
     const targetPath = path.join(cwd, item.relativePath);
 
     try {
+      if (item.action === 'remove') {
+        let stats;
+        try {
+          stats = await fs.stat(targetPath);
+        } catch (error) {
+          if (error.code === 'ENOENT') {
+            result.skipped.push(item.relativePath);
+            result.warnings.push(`Skipped missing stale adapter: ${item.relativePath}`);
+            continue;
+          }
+          throw error;
+        }
+
+        if (!stats.isFile()) {
+          result.skipped.push(item.relativePath);
+          result.warnings.push(`Skipped stale adapter removal because target is not a file: ${item.relativePath}`);
+          continue;
+        }
+
+        const currentContent = await fs.readFile(targetPath, 'utf8');
+        if (normalizeCommandAdapterFingerprint(currentContent) !== normalizeCommandAdapterFingerprint(item.expectedContent || '')) {
+          result.skipped.push(item.relativePath);
+          result.warnings.push(`Skipped stale adapter removal because content changed after preview: ${item.relativePath}`);
+          continue;
+        }
+
+        await fs.unlink(targetPath);
+        result.removed.push(item.relativePath);
+        continue;
+      }
+
       if (await pathExists(targetPath)) {
         if (item.overwrite) {
           await fs.mkdir(path.dirname(targetPath), { recursive: true });
@@ -1705,9 +1931,11 @@ async function writeFilePlan(cwd, plan) {
         );
       }
 
-      const message = error.code === 'ENOTDIR' || error.code === 'EEXIST'
-        ? `Cannot create parent directory for ${item.relativePath}: a parent path is a file.`
-        : `Write failed while creating ${item.relativePath}: ${error.message}`;
+      const message = item.action === 'remove'
+        ? `Write failed while removing ${item.relativePath}: ${error.message}`
+        : error.code === 'ENOTDIR' || error.code === 'EEXIST'
+          ? `Cannot create parent directory for ${item.relativePath}: a parent path is a file.`
+          : `Write failed while creating ${item.relativePath}: ${error.message}`;
       throw new WritePhaseError(message, result);
     }
   }
@@ -1751,6 +1979,9 @@ function printResultReport(stdout, result, deferred) {
   stdout.write('\nUpdated:\n');
   printList(stdout, result.updated);
 
+  stdout.write('\nRemoved:\n');
+  printList(stdout, result.removed);
+
   stdout.write('\nSkipped:\n');
   printList(stdout, result.skipped);
 
@@ -1777,7 +2008,7 @@ Recommended next steps:
 
 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'
+    ? '- Command adapters use tool-specific invocation names: Claude Code `/dflow:<id>`; GitHub Copilot prompt menu `/dflow-<id>` or canonical `/dflow:<id>` as text; Codex CLI plain text without a slash, such as `dflow:status`. Canonical `/dflow:*` names remain defined in dflow/specs/shared/AI-AGENT-GUIDE.md. If upgrading from Dflow 0.5.0, stale `.claude/commands/dflow/dflow-*.md` files generated by 0.5.0 are detected and listed for removal in the confirmation preview, so Claude Code does not show both old and new command names; edited or non-Dflow files are kept with a warning.\n'
     : '';
 
   stdout.write(`

package/package.json

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