dflow-sdd-ddd 0.1.0 → 0.2.0

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');
@@ -37,19 +39,6 @@ const PROJECT_TYPE_OPTIONS = [
   }
 ];
 
-const EDITION_OPTIONS = [
-  {
-    key: 'core',
-    label: 'ASP.NET Core - Clean Architecture + DDD',
-    aliases: ['core', 'asp.net core', 'aspnet core']
-  },
-  {
-    key: 'webforms',
-    label: 'ASP.NET WebForms - progressive domain extraction',
-    aliases: ['webforms', 'asp.net webforms', 'aspnet webforms']
-  }
-];
-
 const PROSE_LANGUAGE_OPTIONS = [
   {
     key: 'zh-TW',
@@ -88,11 +77,29 @@ const OPTIONAL_FILE_OPTIONS = [
     key: 'git-flow',
     label: 'Git principles - Git Flow',
     aliases: ['git principles - git flow', 'git flow', 'gitflow']
+  }
+];
+
+const AI_AGENT_OPTIONS = [
+  {
+    key: 'agents',
+    label: 'AGENTS.md - Codex / Copilot coding agent',
+    aliases: ['agents', 'agents.md', 'codex', 'copilot agent', 'copilot coding agent']
   },
   {
     key: 'claude',
-    label: 'CLAUDE.md snippet / project AI guide',
+    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',
+    aliases: ['copilot', 'github copilot', 'copilot-instructions', 'copilot-instructions.md']
   }
 ];
 
@@ -211,6 +218,95 @@ async function runInit(options = {}) {
   }
 }
 
+async function runConfigureAgents(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const stdin = options.stdin || process.stdin;
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+
+  let rl;
+
+  try {
+    rl = readline.createInterface({
+      input: stdin,
+      output: stdout,
+      terminal: Boolean(stdin.isTTY && stdout.isTTY)
+    });
+    rl._dflowOutput = stdout;
+    getLinePrompter(rl);
+
+    if (compareVersions(process.versions.node, MIN_NODE_VERSION) < 0) {
+      throw new InitError(`Dflow configure-agents requires Node.js ${MIN_NODE_VERSION}+.`, 1);
+    }
+
+    await assertWritableProjectRoot(cwd);
+    await assertDflowInitialized(cwd);
+
+    const projectContext = await inferProjectContext(cwd, rl, stdout, stderr);
+    const aiAgents = await askAiAgents(rl, stdout, stderr);
+
+    if (aiAgents.length === 0) {
+      throw new UserAbort('No AI agents selected. Nothing changed.');
+    }
+
+    const plan = await buildConfigureAgentsPlan(cwd, {
+      ...projectContext,
+      aiAgents
+    });
+
+    renderPreview(stdout, plan, []);
+    const confirmed = await askConfirmation(rl, 'Create these files? (y/N) ');
+
+    if (!confirmed) {
+      throw new UserAbort();
+    }
+
+    rl.close();
+    rl = undefined;
+
+    const result = await writeFilePlan(cwd, plan);
+    result.warnings.push(...collectUnresolvedPlaceholderWarnings(plan, result.created));
+
+    printResultReport(stdout, result, plan.deferred);
+    printConfigureAgentsNextSteps(stdout);
+    return 0;
+  } catch (error) {
+    if (rl) {
+      rl.close();
+    }
+
+    if (error instanceof UserAbort) {
+      stdout.write(`${error.message}\n`);
+      return error.exitCode;
+    }
+
+    if (error instanceof WritePhaseError) {
+      stderr.write(`${error.message}\n`);
+      stderr.write('Files already created were kept; clean up partial output manually if needed.\n');
+      if (error.result) {
+        printResultReport(stdout, error.result, []);
+      }
+      return error.exitCode;
+    }
+
+    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 assertDflowInitialized(cwd) {
+  const dflowSpecsPath = path.join(cwd, 'dflow', 'specs');
+
+  if (!(await pathExists(dflowSpecsPath)) || !(await containsInitializedContent(dflowSpecsPath))) {
+    throw new InitError('Dflow is not initialized in this project. Run `dflow init` first.');
+  }
+}
+
 async function runPreflight(cwd) {
   const warnings = [];
   const dflowSpecsPath = path.join(cwd, 'dflow', 'specs');
@@ -226,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.'
     );
   }
 
@@ -309,16 +405,16 @@ async function detectProjectSignals(cwd) {
     }
   }
 
-  let editionHint = null;
+  let trackHint = null;
   if (coreSignal && !webFormsSignal) {
-    editionHint = 'core';
+    trackHint = 'greenfield';
   } else if (webFormsSignal && !coreSignal) {
-    editionHint = 'webforms';
+    trackHint = 'brownfield';
   }
 
   return {
     hasSourceTree: hasSourceTree || relNames.has('src'),
-    editionHint
+    trackHint
   };
 }
 
@@ -369,9 +465,9 @@ function buildDetectionWarnings(answers, detection) {
     warnings.push('Warning: source-tree signals already exist, but project type is Greenfield. Continuing with your selected project type.');
   }
 
-  if (detection.editionHint && answers.edition !== detection.editionHint) {
+  if (detection.trackHint && answers.projectType !== detection.trackHint) {
     warnings.push(
-      `Warning: project signals look like ${formatEdition(detection.editionHint)}, but selected edition is ${formatEdition(answers.edition)}. Continuing with your selected edition.`
+      `Warning: project signals look like ${formatTrack(detection.trackHint)}, but selected track is ${formatTrack(answers.projectType)}. Continuing with your selected track.`
     );
   }
 
@@ -387,15 +483,8 @@ async function promptForAnswers(rl, stdout, stderr, detection) {
     defaultKey: projectTypeDefault
   });
 
-  const edition = await askSelect(rl, stdout, stderr, {
-    id: 'Q2',
-    question: 'Which Dflow edition should initialize this project?',
-    options: EDITION_OPTIONS,
-    defaultKey: detection.editionHint
-  });
-
   const techStackSummary = await askText(rl, stderr, {
-    id: 'Q3',
+    id: 'Q2',
     question: 'Confirm the main tech stack details for placeholders.',
     required: true,
     maxLength: 1000,
@@ -403,7 +492,7 @@ async function promptForAnswers(rl, stdout, stderr, detection) {
   });
 
   const migrationContext = await askText(rl, stderr, {
-    id: 'Q4',
+    id: 'Q3',
     question: 'Is there migration or legacy context Dflow should note?',
     required: false,
     maxLength: 1000,
@@ -411,7 +500,7 @@ async function promptForAnswers(rl, stdout, stderr, detection) {
   });
 
   const proseLanguageSelection = await askSelect(rl, stdout, stderr, {
-    id: 'Q5',
+    id: 'Q4',
     question: 'Project prose language for generated spec content?',
     options: PROSE_LANGUAGE_OPTIONS,
     defaultKey: null
@@ -423,17 +512,76 @@ async function promptForAnswers(rl, stdout, stderr, detection) {
   }
 
   const optionalFiles = await askOptionalFiles(rl, stdout, stderr);
+  const aiAgents = await askAiAgents(rl, stdout, stderr);
 
   return {
     projectType,
-    edition,
+    edition: projectType,
     techStackSummary,
     migrationContext,
     proseLanguage,
-    optionalFiles
+    optionalFiles,
+    aiAgents
+  };
+}
+
+async function inferProjectContext(cwd, rl, stdout, stderr) {
+  let edition = await inferExistingEdition(cwd);
+
+  if (!edition) {
+    stderr.write('Could not infer the Dflow track from dflow/specs/. Please choose it explicitly.\n');
+    edition = await askSelect(rl, stdout, stderr, {
+      id: 'track',
+      question: 'Which Dflow track is this project using?',
+      options: PROJECT_TYPE_OPTIONS,
+      defaultKey: null
+    });
+  }
+
+  return {
+    projectType: edition,
+    edition,
+    techStackSummary: await inferTechStackSummary(cwd),
+    migrationContext: await inferMigrationContext(cwd),
+    proseLanguage: await inferProseLanguage(cwd),
+    optionalFiles: []
   };
 }
 
+async function inferExistingEdition(cwd) {
+  if (await pathExists(path.join(cwd, 'dflow/specs/architecture/tech-debt.md'))) {
+    return 'greenfield';
+  }
+  if (await pathExists(path.join(cwd, 'dflow/specs/migration/tech-debt.md'))) {
+    return 'brownfield';
+  }
+  if (await pathExists(path.join(cwd, 'dflow/specs/domain/context-map.md'))) {
+    return 'greenfield';
+  }
+  return null;
+}
+
+async function inferProseLanguage(cwd) {
+  const conventionsPath = path.join(cwd, 'dflow/specs/shared/_conventions.md');
+  const content = await fs.readFile(conventionsPath, 'utf8').catch(() => '');
+  const match = content.match(/Project prose language:\s*`([^`]+)`/);
+  return match ? match[1] : 'unknown';
+}
+
+async function inferTechStackSummary(cwd) {
+  const overviewPath = path.join(cwd, 'dflow/specs/shared/_overview.md');
+  const content = await fs.readFile(overviewPath, 'utf8').catch(() => '');
+  const match = content.match(/\|\s*Tech stack\s*\|\s*([^|\n]+?)\s*\|/i);
+  return match ? match[1].trim() : 'unknown';
+}
+
+async function inferMigrationContext(cwd) {
+  const overviewPath = path.join(cwd, 'dflow/specs/shared/_overview.md');
+  const content = await fs.readFile(overviewPath, 'utf8').catch(() => '');
+  const match = content.match(/\|\s*Migration \/ legacy context\s*\|\s*([^|\n]+?)\s*\|/i);
+  return match ? match[1].trim() : 'none';
+}
+
 async function askSelect(rl, stdout, stderr, config) {
   let failedAttempts = 0;
 
@@ -506,7 +654,7 @@ async function askCustomProseLanguage(rl, stderr) {
 
     failedAttempts += 1;
     if (failedAttempts >= 3) {
-      throw new InitError('Too many invalid attempts for Q5a. Dflow init aborted.');
+      throw new InitError('Too many invalid attempts for Q4a. Dflow init aborted.');
     }
     stderr.write(`${validation.message} (${3 - failedAttempts} attempts left)\n`);
   }
@@ -528,7 +676,7 @@ async function askOptionalFiles(rl, stdout, stderr) {
     if (!parsed.valid) {
       failedAttempts += 1;
       if (failedAttempts >= 3) {
-        throw new InitError('Too many invalid attempts for Q6. Dflow init aborted.');
+        throw new InitError('Too many invalid attempts for Q5. Dflow init aborted.');
       }
       stderr.write(`${parsed.message} (${3 - failedAttempts} attempts left)\n`);
       continue;
@@ -549,6 +697,31 @@ async function askOptionalFiles(rl, stdout, stderr) {
   }
 }
 
+async function askAiAgents(rl, stdout, stderr) {
+  let failedAttempts = 0;
+
+  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 answer = await askLine(rl, 'Enter comma-separated choices or "none" (default: none): ');
+    const parsed = parseMultiselectAnswer(answer || 'none', AI_AGENT_OPTIONS, []);
+
+    if (!parsed.valid) {
+      failedAttempts += 1;
+      if (failedAttempts >= 3) {
+        throw new InitError('Too many invalid attempts for Q6. Dflow init aborted.');
+      }
+      stderr.write(`${parsed.message} (${3 - failedAttempts} attempts left)\n`);
+      continue;
+    }
+
+    return parsed.values;
+  }
+}
+
 function askLine(rl, prompt) {
   return getLinePrompter(rl).ask(prompt);
 }
@@ -669,7 +842,7 @@ function parseMultiselectAnswer(answer, options, defaultKeys) {
   for (const token of tokens) {
     const selectedKey = parseSelectAnswer(token, options, null);
     if (!selectedKey) {
-      return { valid: false, message: `Invalid optional file selection: ${token}` };
+      return { valid: false, message: `Invalid selection: ${token}` };
     }
     if (!selected.includes(selectedKey)) {
       selected.push(selectedKey);
@@ -713,9 +886,6 @@ async function buildFilePlan(cwd, answers) {
 
   const addTemplate = async (relativePath, sourceRel, notes, options = {}) => {
     let content = await readPackagedTemplate(answers.edition, sourceRel);
-    if (options.extractClaudeSnippetBody) {
-      content = extractClaudeSnippetBody(content, sourceRel);
-    }
     content = substitutePlaceholders(content, substitution);
     if (options.injectProseLanguage) {
       content = ensureProseLanguageSection(content, answers.proseLanguage);
@@ -737,7 +907,7 @@ async function buildFilePlan(cwd, answers) {
   });
   await addTemplate('dflow/specs/domain/glossary.md', 'templates/glossary.md', 'mandatory');
 
-  if (answers.edition === 'core') {
+  if (answers.edition === 'greenfield') {
     await addTemplate('dflow/specs/domain/context-map.md', 'templates/context-map.md', 'mandatory');
     await addTemplate('dflow/specs/architecture/tech-debt.md', 'templates/tech-debt.md', 'mandatory');
     await addTemplate(
@@ -758,17 +928,57 @@ async function buildFilePlan(cwd, answers) {
   if (answers.optionalFiles.includes('git-flow')) {
     await addTemplate('dflow/specs/shared/Git-principles-gitflow.md', 'scaffolding/Git-principles-gitflow.md', 'selected');
   }
-  if (answers.optionalFiles.includes('claude')) {
-    const rootClaudePath = path.join(cwd, 'CLAUDE.md');
-    if (await pathExists(rootClaudePath)) {
-      await addTemplate('dflow/specs/shared/CLAUDE-md-snippet.md', 'scaffolding/CLAUDE-md-snippet.md', 'selected, root CLAUDE.md already exists');
-    } else {
-      await addTemplate('CLAUDE.md', 'scaffolding/CLAUDE-md-snippet.md', 'selected, snippet body only', {
-        extractClaudeSnippetBody: true
-      });
+
+  if (answers.aiAgents.length > 0) {
+    await addTemplate('dflow/specs/shared/AI-AGENT-GUIDE.md', 'scaffolding/AI-AGENT-GUIDE.md', 'selected, canonical AI agent guide');
+    for (const agent of answers.aiAgents) {
+      await addAiAgentShim(cwd, items, agent, substitution);
     }
   }
 
+  await finalizePlanItems(cwd, items);
+
+  return {
+    items,
+    deferred: buildDeferredItems(answers.edition),
+    unresolvedInitPlaceholders: Array.from(substitution.entries())
+      .filter(([placeholder, value]) => placeholder === value)
+      .map(([placeholder]) => placeholder)
+  };
+}
+
+async function buildConfigureAgentsPlan(cwd, answers) {
+  const substitution = buildSubstitutionMap(cwd, {
+    ...answers,
+    optionalFiles: answers.optionalFiles || []
+  });
+  const items = [];
+
+  let content = await readPackagedTemplate(answers.edition, 'scaffolding/AI-AGENT-GUIDE.md');
+  content = substitutePlaceholders(content, substitution);
+  items.push({
+    relativePath: 'dflow/specs/shared/AI-AGENT-GUIDE.md',
+    source: `packaged:${answers.edition}/scaffolding/AI-AGENT-GUIDE.md`,
+    notes: 'canonical AI agent guide',
+    content
+  });
+
+  for (const agent of answers.aiAgents) {
+    await addAiAgentShim(cwd, items, agent, substitution);
+  }
+
+  await finalizePlanItems(cwd, items);
+
+  return {
+    items,
+    deferred: [],
+    unresolvedInitPlaceholders: Array.from(substitution.entries())
+      .filter(([placeholder, value]) => placeholder === value)
+      .map(([placeholder]) => placeholder)
+  };
+}
+
+async function finalizePlanItems(cwd, items) {
   for (const item of items) {
     const absolute = path.join(cwd, item.relativePath);
     item.action = (await pathExists(absolute)) ? 'skip' : 'create';
@@ -777,22 +987,92 @@ async function buildFilePlan(cwd, answers) {
     }
     item.size = Buffer.byteLength(item.content, 'utf8');
   }
+}
 
-  return {
-    items,
-    deferred: buildDeferredItems(answers.edition),
-    unresolvedInitPlaceholders: Array.from(substitution.entries())
-      .filter(([placeholder, value]) => placeholder === value)
-      .map(([placeholder]) => placeholder)
+async function addAiAgentShim(cwd, items, agent, substitution) {
+  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);
+  let notes = 'selected, tool-specific shim';
+  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`;
+  }
+
+  items.push({
+    relativePath,
+    source: `generated:${agent}-shim`,
+    notes,
+    content
+  });
+}
+
+async function fileReferencesAiAgentGuide(targetPath) {
+  try {
+    const content = await fs.readFile(targetPath, 'utf8');
+    return content.includes('dflow/specs/shared/AI-AGENT-GUIDE.md') ||
+      content.includes('dflow\\specs\\shared\\AI-AGENT-GUIDE.md');
+  } catch {
+    return false;
+  }
+}
+
+function getAiAgentTarget(agent) {
+  const targets = {
+    agents: {
+      relativePath: 'AGENTS.md',
+      snippetPath: 'dflow/specs/shared/AGENTS-md-snippet.md'
+    },
+    claude: {
+      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'
+    }
   };
+
+  return targets[agent];
+}
+
+function buildAiAgentShim(targetPath) {
+  const title = targetPath === '.github/copilot-instructions.md'
+    ? 'GitHub Copilot Repository Instructions'
+    : `${targetPath} - Dflow Project Instructions`;
+
+  const importHint = targetPath === 'CLAUDE.md' || targetPath === 'GEMINI.md'
+    ? '\nIf your tool supports Markdown imports, the canonical guide is imported below:\n\n@dflow/specs/shared/AI-AGENT-GUIDE.md\n'
+    : '';
+
+  return `# ${title}
+
+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.${importHint}
+`;
 }
 
 function buildDeferredItems(edition) {
   const deferred = [...DEFERRED_COMMON];
-  if (edition === 'core') {
+  if (edition === 'greenfield') {
     deferred.splice(3, 0, {
       relativePath: 'dflow/specs/domain/{context}/events.md',
-      reason: 'Core only, but still needs a real bounded context.'
+      reason: 'Greenfield only, but still needs a real bounded context.'
     });
   }
   return deferred;
@@ -839,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}'],
@@ -892,14 +1173,6 @@ function extractTestFramework(text) {
   return null;
 }
 
-function extractClaudeSnippetBody(content, sourceRel) {
-  const match = content.match(/## Snippet to merge into `CLAUDE\.md`[\s\S]*?```markdown\r?\n([\s\S]*?)\r?\n```/);
-  if (!match) {
-    throw new InitError(`Internal error: CLAUDE.md snippet body not found in packaged template: ${sourceRel}`);
-  }
-  return `${match[1].trimEnd()}\n`;
-}
-
 function ensureProseLanguageSection(content, proseLanguage) {
   const section = buildProseLanguageSection(proseLanguage);
   let stripped = stripProseLanguageSections(content);
@@ -1116,6 +1389,17 @@ Recommended next steps:
 `);
 }
 
+function printConfigureAgentsNextSteps(stdout) {
+  stdout.write(`
+Dflow AI agent configuration complete.
+
+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.
+`);
+}
+
 function printList(stdout, values) {
   if (!values || values.length === 0) {
     stdout.write('- (none)\n');
@@ -1186,8 +1470,8 @@ function formatBytes(bytes) {
   return `${(bytes / 1024).toFixed(1)} KB`;
 }
 
-function formatEdition(edition) {
-  return edition === 'core' ? 'ASP.NET Core' : 'ASP.NET WebForms';
+function formatTrack(track) {
+  return track === 'greenfield' ? 'Greenfield' : 'Brownfield';
 }
 
 function escapeTableCell(value) {
@@ -1198,7 +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,