dflow-sdd-ddd 0.6.0 → 0.8.0

package/lib/init.js

@@ -10,6 +10,12 @@ 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 WORKFLOW_BUNDLE_GENERATED_MARKER = '<!-- dflow-generated: workflow-bundle -->';
+const WORKFLOW_BUNDLE_DEST = 'dflow/specs/shared/dflow-workflows';
+const WORKFLOW_BUNDLE_MANIFEST_PATH = `${WORKFLOW_BUNDLE_DEST}/.dflow-bundle-manifest.json`;
+const COMMON_SKILL_SOURCE_REL = 'common/skill/SKILL.md';
 const EXPECTED_COMMAND_IDS = [
   'new-feature',
   'modify-existing',
@@ -23,6 +29,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}))*$/;
@@ -179,8 +207,8 @@ async function runInit(options = {}) {
 
     const detection = await detectProjectSignals(cwd);
     const answers = await promptForAnswers(rl, stdout, stderr, detection);
-    const warnings = [...preflight.warnings, ...buildDetectionWarnings(answers, detection)];
     const plan = await buildFilePlan(cwd, answers);
+    const warnings = [...preflight.warnings, ...buildDetectionWarnings(answers, detection), ...(plan.bundleWarnings || [])];
 
     renderPreview(stdout, plan, warnings);
     const confirmed = await askConfirmation(rl, 'Create these files? (y/N) ');
@@ -253,7 +281,8 @@ async function runConfigureAgents(options = {}) {
     await assertDflowInitialized(cwd);
 
     const projectContext = await inferProjectContext(cwd, rl, stdout, stderr);
-    const aiAgents = await askAiAgents(rl, stdout, stderr);
+    const detectedAgents = await detectConfiguredAgents(cwd);
+    const aiAgents = await askAiAgents(rl, stdout, stderr, detectedAgents);
 
     if (aiAgents.length === 0) {
       throw new UserAbort('No AI agents selected. Nothing changed.');
@@ -262,10 +291,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 +307,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);
@@ -461,10 +493,32 @@ async function detectProjectSignals(cwd) {
   return {
     hasSourceTree: hasSourceTree || relNames.has('src'),
     trackHint,
-    stackHints
+    stackHints,
+    configuredAgents: await detectConfiguredAgents(cwd)
   };
 }
 
+async function detectConfiguredAgents(cwd) {
+  // Surface agents this project already has configured so init / configure-agents
+  // can default to them instead of re-asking from scratch on every invocation.
+  // Order matches AI_AGENT_OPTIONS so the prompt numbering lines up.
+  const detected = [];
+  if (await pathExists(path.join(cwd, 'AGENTS.md'))) {
+    detected.push('agents');
+  }
+  if (
+    (await pathExists(path.join(cwd, 'CLAUDE.md'))) ||
+    (await pathExists(path.join(cwd, '.claude/commands/dflow'))) ||
+    (await pathExists(path.join(cwd, '.claude/skills/dflow')))
+  ) {
+    detected.push('claude');
+  }
+  if (await pathExists(path.join(cwd, '.github/copilot-instructions.md'))) {
+    detected.push('copilot');
+  }
+  return detected;
+}
+
 async function collectProjectFiles(cwd, maxDepth, maxFiles) {
   const results = [];
   const ignored = new Set(['.git', 'node_modules', 'bin', 'obj', 'dflow']);
@@ -508,8 +562,8 @@ async function collectProjectFiles(cwd, maxDepth, maxFiles) {
 function buildDetectionWarnings(answers, detection) {
   const warnings = [];
 
-  if (answers.projectType === 'greenfield' && detection.hasSourceTree) {
-    warnings.push('Warning: source-tree signals already exist, but project type is Greenfield. Continuing with your selected project type.');
+  if (answers.projectType === 'greenfield' && detection.hasSourceTree && !detection.trackHint) {
+    warnings.push('Note: existing source files were detected (e.g. a src/ directory or a build manifest). This is expected if you just scaffolded a fresh project — Dflow will continue as Greenfield. If this is actually an existing codebase, consider re-running and selecting Brownfield.');
   }
 
   if (detection.trackHint && answers.projectType !== detection.trackHint) {
@@ -559,7 +613,7 @@ async function promptForAnswers(rl, stdout, stderr, detection) {
   }
 
   const optionalFiles = await askOptionalFiles(rl, stdout, stderr);
-  const aiAgents = await askAiAgents(rl, stdout, stderr);
+  const aiAgents = await askAiAgents(rl, stdout, stderr, detection.configuredAgents || []);
 
   return {
     projectType,
@@ -744,17 +798,24 @@ async function askOptionalFiles(rl, stdout, stderr) {
   }
 }
 
-async function askAiAgents(rl, stdout, stderr) {
+async function askAiAgents(rl, stdout, stderr, defaultKeys = []) {
   let failedAttempts = 0;
+  const validDefaults = AI_AGENT_OPTIONS
+    .filter((option) => defaultKeys.includes(option.key))
+    .map((option) => option.key);
 
   while (true) {
     stdout.write('\nWhich AI coding agents should Dflow configure?\n');
     AI_AGENT_OPTIONS.forEach((option, index) => {
-      stdout.write(`  ${index + 1}. ${option.label}\n`);
+      const marker = validDefaults.includes(option.key) ? '  (currently configured)' : '';
+      stdout.write(`  ${index + 1}. ${option.label}${marker}\n`);
     });
 
-    const answer = await askLine(rl, 'Enter comma-separated choices or "none" (default: none): ');
-    const parsed = parseMultiselectAnswer(answer || 'none', AI_AGENT_OPTIONS, []);
+    const defaultHint = validDefaults.length > 0
+      ? validDefaults.map((key) => AI_AGENT_OPTIONS.findIndex((option) => option.key === key) + 1).join(',')
+      : 'none';
+    const answer = await askLine(rl, `Enter comma-separated choices or "none" (default: ${defaultHint}): `);
+    const parsed = parseMultiselectAnswer(answer, AI_AGENT_OPTIONS, validDefaults);
 
     if (!parsed.valid) {
       failedAttempts += 1;
@@ -985,9 +1046,14 @@ async function buildFilePlan(cwd, answers) {
 
   await finalizePlanItems(cwd, items);
 
+  // Always project the workflow bundle (required for /dflow:* workflows to be reachable).
+  const bundleWarnings = [];
+  await addWorkflowBundleItems(cwd, items, bundleWarnings, answers.edition);
+
   return {
     items,
     deferred: buildDeferredItems(answers.edition),
+    bundleWarnings,
     unresolvedInitPlaceholders: Array.from(substitution.entries())
       .filter(([placeholder, value]) => placeholder === value)
       .map(([placeholder]) => placeholder)
@@ -1000,6 +1066,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 +1089,24 @@ 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);
+
+  // Project the workflow bundle on configure-agents too, so pre-039 projects (no bundle)
+  // and edition-switch repairs get the runtime references/templates reachable. The function
+  // is idempotent: it skips fresh bundle files, updates Dflow-generated ones, and warns
+  // (without overwriting) on user-modified bundle files.
+  const bundleWarnings = [];
+  await addWorkflowBundleItems(cwd, items, bundleWarnings, answers.edition);
+  warnings.push(...bundleWarnings);
+
   return {
     items,
     deferred: [],
+    warnings,
     unresolvedInitPlaceholders: Array.from(substitution.entries())
       .filter(([placeholder, value]) => placeholder === value)
       .map(([placeholder]) => placeholder)
@@ -1043,6 +1125,183 @@ async function finalizePlanItems(cwd, items) {
   }
 }
 
+async function listBundleSourceFiles(edition) {
+  const bundleDirs = ['references', 'templates'];
+  const files = [];
+
+  for (const dir of bundleDirs) {
+    const sourceDir = path.join(TEMPLATE_ROOT, edition, dir);
+    let entries;
+    try {
+      entries = await fs.readdir(sourceDir);
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        continue;
+      }
+      throw error;
+    }
+    for (const entry of entries) {
+      const sourceRel = `${dir}/${entry}`;
+      const sourcePath = path.join(sourceDir, entry);
+      const stat = await fs.stat(sourcePath);
+      if (stat.isFile()) {
+        files.push({ sourceRel, dir, name: entry });
+      }
+    }
+  }
+
+  return files;
+}
+
+async function readCurrentBundleManifest(cwd) {
+  const manifestPath = path.join(cwd, WORKFLOW_BUNDLE_MANIFEST_PATH);
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function buildBundleManifest(edition, version, files) {
+  return {
+    edition,
+    version,
+    generatedBy: 'dflow-sdd-ddd',
+    files: files.map((f) => `${WORKFLOW_BUNDLE_DEST}/${f.sourceRel}`)
+  };
+}
+
+function injectBundleMarker(content) {
+  return `${WORKFLOW_BUNDLE_GENERATED_MARKER}\n\n${content}`;
+}
+
+async function addWorkflowBundleItems(cwd, items, warnings, edition) {
+  const bundleFiles = await listBundleSourceFiles(edition);
+
+  // Detect any previous manifest to handle edition-switch stale cleanup.
+  const existingManifest = await readCurrentBundleManifest(cwd);
+  const previousEdition = existingManifest ? existingManifest.edition : null;
+
+  // If the edition changed, schedule removal of stale generated files from prior edition.
+  if (previousEdition && previousEdition !== edition) {
+    const staleFiles = existingManifest.files || [];
+    for (const staleRelPath of staleFiles) {
+      const staleAbsPath = path.join(cwd, staleRelPath);
+      let staleExists = false;
+      try {
+        await fs.stat(staleAbsPath);
+        staleExists = true;
+      } catch {
+        staleExists = false;
+      }
+      if (!staleExists) {
+        continue;
+      }
+      const staleContent = await fs.readFile(staleAbsPath, 'utf8');
+      if (!staleContent.includes(WORKFLOW_BUNDLE_GENERATED_MARKER)) {
+        warnings.push(
+          `Edition changed from ${previousEdition} to ${edition}; skipped removal of user-modified bundle file: ${staleRelPath}`
+        );
+        continue;
+      }
+      // Check if this path is also in the new edition bundle — if so, it will be overwritten, not removed.
+      const newRelPaths = new Set(bundleFiles.map((f) => `${WORKFLOW_BUNDLE_DEST}/${f.sourceRel}`));
+      if (!newRelPaths.has(staleRelPath)) {
+        items.push({
+          relativePath: staleRelPath,
+          source: `stale-bundle:${previousEdition}`,
+          notes: `stale workflow bundle file from ${previousEdition} edition`,
+          action: 'remove',
+          size: Buffer.byteLength(staleContent, 'utf8'),
+          expectedContent: staleContent
+        });
+      }
+    }
+  }
+
+  // Build items for current edition bundle files.
+  for (const { sourceRel } of bundleFiles) {
+    const relativePath = `${WORKFLOW_BUNDLE_DEST}/${sourceRel}`;
+    const absolutePath = path.join(cwd, relativePath);
+    const sourceContent = await readPackagedBundleFile(edition, sourceRel);
+    const content = injectBundleMarker(sourceContent);
+
+    let action;
+    let notes = 'workflow bundle';
+    const targetExists = await pathExists(absolutePath);
+
+    if (targetExists) {
+      const existingContent = await fs.readFile(absolutePath, 'utf8');
+      if (existingContent.includes(WORKFLOW_BUNDLE_GENERATED_MARKER)) {
+        action = 'update';
+      } else {
+        action = 'skip';
+        notes = 'workflow bundle, user-modified — skipped; remove or rename to let Dflow manage';
+        warnings.push(
+          `Existing ${relativePath} is not a Dflow-generated bundle file; left unchanged. Remove or rename it to let Dflow manage this file.`
+        );
+      }
+    } else {
+      action = 'create';
+    }
+
+    items.push({
+      relativePath,
+      source: `packaged-bundle:${edition}/${sourceRel}`,
+      notes,
+      content,
+      action,
+      overwrite: action === 'update',
+      size: Buffer.byteLength(content, 'utf8')
+    });
+  }
+
+  // Add the manifest file.
+  const manifestContent = JSON.stringify(
+    buildBundleManifest(edition, pkg.version, bundleFiles),
+    null,
+    2
+  ) + '\n';
+  const manifestExists = await pathExists(path.join(cwd, WORKFLOW_BUNDLE_MANIFEST_PATH));
+
+  items.push({
+    relativePath: WORKFLOW_BUNDLE_MANIFEST_PATH,
+    source: `generated:workflow-bundle-manifest`,
+    notes: 'workflow bundle manifest',
+    content: manifestContent,
+    action: manifestExists ? 'update' : 'create',
+    overwrite: true,
+    size: Buffer.byteLength(manifestContent, 'utf8')
+  });
+}
+
+async function readPackagedBundleFile(edition, sourceRel) {
+  const filePath = path.join(TEMPLATE_ROOT, edition, sourceRel);
+  const normalizedRoot = path.resolve(TEMPLATE_ROOT, edition);
+  const normalizedFilePath = path.resolve(filePath);
+
+  if (!normalizedFilePath.startsWith(`${normalizedRoot}${path.sep}`)) {
+    throw new InitError(`Internal error: packaged bundle file not found: templates/${edition}/${sourceRel}`);
+  }
+
+  let buffer;
+  try {
+    buffer = await fs.readFile(normalizedFilePath);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new InitError(`Internal error: packaged bundle file not found: templates/${edition}/${sourceRel}`);
+    }
+    throw new InitError(`Internal error: cannot read packaged bundle file: templates/${edition}/${sourceRel}`);
+  }
+
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+  } catch {
+    throw new InitError(`Internal error: invalid UTF-8 packaged bundle file: templates/${edition}/${sourceRel}`);
+  }
+}
+
 async function addAiAgentShim(cwd, items, agent, substitution, options = {}) {
   const target = getAiAgentTarget(agent);
   const targetPath = path.join(cwd, target.relativePath);
@@ -1122,10 +1381,11 @@ 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\`
+- \`dflow/specs/shared/AI-AGENT-GUIDE.md\` — command registry, routing rules, and project context.
+- \`dflow/specs/shared/dflow-workflows/\` — vendored workflow bundle with executable step definitions.
 
-Keep tool-specific instruction files small. The Dflow guide above is the
-single source of truth for project workflow rules, slash-command behavior,
+Keep tool-specific instruction files small. The guide and workflow bundle are
+the authoritative sources for Dflow workflow rules, slash-command behavior,
 spec locations, and SDD/DDD constraints.${commandTriggerHint}${importHint}
 `;
 }
@@ -1156,6 +1416,134 @@ function addCommandAdapterItems(items, aiAgents, commandRegistry) {
   }
 }
 
+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
+      });
+    }
+  }
+}
+
+// Edition-agnostic thin shell: a single canonical source at
+// templates/common/skill/SKILL.md (PROPOSAL-041 C1). Returns the file
+// verbatim — frontmatter, marker, and body all live in the source file so
+// the skill content can be edited without touching JS.
+async function buildDflowSkillAdapter() {
+  const sourcePath = path.join(TEMPLATE_ROOT, COMMON_SKILL_SOURCE_REL);
+  return fs.readFile(sourcePath, 'utf8');
+}
+
+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;
+  }
+
+  const skillContent = await buildDflowSkillAdapter();
+  items.push({
+    relativePath,
+    source: 'generated:claude-skill-adapter',
+    notes: 'skill adapter, thin skill pointing to AI-AGENT-GUIDE.md',
+    content: skillContent,
+    size: Buffer.byteLength(skillContent, 'utf8'),
+    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) => {
@@ -1190,9 +1578,12 @@ function buildThinCommandWrapper(command, displayName = command.label) {
 
   return `# ${displayName}
 
+${COMMAND_ADAPTER_GENERATED_MARKER}
+
 Execute the canonical \`${command.label}\` Dflow workflow or control command.
 
-Definition: \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+Registry and rules: \`dflow/specs/shared/AI-AGENT-GUIDE.md\`
+Workflow steps: \`dflow/specs/shared/dflow-workflows/\`
 
 ${argHint}
 `;
@@ -1651,6 +2042,7 @@ async function writeFilePlan(cwd, plan) {
   const result = {
     created: [],
     updated: [],
+    removed: [],
     skipped: [],
     warnings: []
   };
@@ -1659,6 +2051,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 });
@@ -1710,9 +2133,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);
     }
   }
@@ -1729,14 +2154,17 @@ function collectUnresolvedPlaceholderWarnings(plan, createdPaths) {
     return [];
   }
 
+  const placeholderFiles = new Set();
   for (const item of plan.items) {
     if (!createdSet.has(item.relativePath)) {
       continue;
     }
     const matches = item.content.match(/{[^{}\n]+}/g) || [];
-    matches
-      .filter((match) => unresolvedInitPlaceholders.has(match))
-      .forEach((match) => placeholders.add(match));
+    const hits = matches.filter((match) => unresolvedInitPlaceholders.has(match));
+    hits.forEach((match) => placeholders.add(match));
+    if (hits.length > 0) {
+      placeholderFiles.add(item.relativePath);
+    }
   }
 
   if (placeholders.size === 0) {
@@ -1746,7 +2174,10 @@ function collectUnresolvedPlaceholderWarnings(plan, createdPaths) {
   const sorted = Array.from(placeholders).sort();
   const shown = sorted.slice(0, 25).join(', ');
   const suffix = sorted.length > 25 ? `, and ${sorted.length - 25} more` : '';
-  return [`Unresolved placeholders remain for later SDD workflows: ${shown}${suffix}.`];
+  const files = Array.from(placeholderFiles).sort();
+  const filesShown = files.slice(0, 10).join(', ');
+  const filesSuffix = files.length > 10 ? `, and ${files.length - 10} more` : '';
+  return [`Unresolved placeholders remain for later SDD workflows: ${shown}${suffix}. Fill them in (or leave for the workflow to resolve) in: ${filesShown}${filesSuffix}.`];
 }
 
 function printResultReport(stdout, result, deferred) {
@@ -1756,6 +2187,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);
 
@@ -1782,7 +2216,7 @@ Recommended next steps:
 
 function printConfigureAgentsNextSteps(stdout, commandAdapters = false) {
   const commandAdapterStep = commandAdapters
-    ? '- 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, manually remove stale `.claude/commands/dflow/dflow-*.md` files so Claude Code does not show both old and new command names.\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(`
@@ -1860,6 +2294,9 @@ function normalizePath(value) {
 }
 
 function formatBytes(bytes) {
+  if (!Number.isFinite(bytes)) {
+    return '—';
+  }
   if (bytes < 1024) {
     return `${bytes} B`;
   }

package/package.json

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