dflow-sdd-ddd 0.1.0 → 0.1.1

package/lib/init.js

@@ -37,19 +37,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 +75,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 +216,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');
@@ -309,16 +403,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 +463,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 +481,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 +490,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 +498,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 +510,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 +652,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 +674,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 +695,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 +840,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 +884,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 +905,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 +926,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 +985,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;
@@ -892,14 +1170,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 +1386,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 +1467,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) {
@@ -1199,6 +1480,7 @@ function dedupe(values) {
 }
 
 module.exports = {
+  runConfigureAgents,
   runInit,
   validateProseLanguage,
   ensureProseLanguageSection,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dflow-sdd-ddd",
-  "version": "0.1.0",
-  "description": "Dflow SDD/DDD project scaffolding CLI",
+  "version": "0.1.1",
+  "description": "Spec-first SDD/DDD workflow kit for AI-assisted development",
   "type": "commonjs",
   "bin": {
     "dflow": "bin/dflow.js",
@@ -12,6 +12,7 @@
   },
   "files": [
     "bin/",
+    "docs/",
     "lib/",
     "templates/",
     "README.md"
@@ -21,17 +22,18 @@
     "ddd",
     "specification-driven-development",
     "domain-driven-design",
-    "codex",
-    "claude-code"
+    "spec-first",
+    "ai-assisted-development",
+    "ai-coding-agent"
   ],
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/weilung/AI-Guided-SDD-DDD-Development-Skills.git"
+    "url": "git+ssh://git@github.com/weilung/dflow-sdd-ddd.git"
   },
   "bugs": {
-    "url": "https://github.com/weilung/AI-Guided-SDD-DDD-Development-Skills/issues"
+    "url": "https://github.com/weilung/dflow-sdd-ddd/issues"
   },
-  "homepage": "https://github.com/weilung/AI-Guided-SDD-DDD-Development-Skills#readme",
+  "homepage": "https://github.com/weilung/dflow-sdd-ddd#readme",
   "scripts": {
     "test": "node test/smoke.mjs"
   },

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

@@ -0,0 +1,64 @@
+# Dflow AI Agent Guide
+
+This project uses Dflow for spec-first AI-assisted development.
+
+## Project Context
+
+| Field | Value |
+|---|---|
+| Project | {System Name} |
+| Dflow track | {edition} |
+| Project type | {project-type} |
+| Tech stack | {tech-stack-summary} |
+| Migration / legacy context | {migration-context} |
+| Prose language | {prose-language} |
+
+## Before Editing Code
+
+Do not jump from a request directly to code. First identify the matching
+Dflow workflow and confirm the intended path with the developer.
+
+Use these workflow entry points as plain chat instructions if slash commands
+are not available in the current AI tool:
+
+| 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. |
+
+## Source of Truth
+
+Dflow-owned project documents live under `dflow/specs/`.
+
+| Area | Path |
+|---|---|
+| Shared conventions | `dflow/specs/shared/_conventions.md` |
+| System overview | `dflow/specs/shared/_overview.md` |
+| Domain glossary | `dflow/specs/domain/glossary.md` |
+| Context map | `dflow/specs/domain/context-map.md` |
+| Active feature specs | `dflow/specs/features/active/` |
+| Completed feature snapshots | `dflow/specs/features/completed/` |
+| Technical debt | `dflow/specs/architecture/tech-debt.md` or `dflow/specs/migration/tech-debt.md` |
+
+## Core Rules
+
+1. Spec before code: meaningful behavior changes need a spec or lightweight bug spec before implementation.
+2. Keep domain language explicit: update glossary, rules, models, and behavior snapshots when domain meaning changes.
+3. Keep phase delta, feature snapshot, and system state separate.
+4. Check drift before calling work complete.
+5. Follow `dflow/specs/shared/_conventions.md`, especially `## Prose Language`.
+
+## 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`
+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.