create-quiver 0.6.0 → 0.8.0

package/src/create-quiver/index.js

@@ -2,6 +2,21 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const { checkHandoff, scaffoldHandoff } = require('./lib/handoff');
+const { collectDoctorWarnings } = require('./lib/doctor');
+const { runGraph } = require('./commands/graph');
+const { runNext } = require('./commands/next');
+const { runPlan } = require('./commands/plan');
+const { initializeProjectDocs } = require('./lib/init-docs');
+const { checkPrReadiness, checkScope, checkSliceReadiness } = require('./lib/readiness');
+const { cleanupSlice, refreshActiveSlicesBoard, startSlice } = require('./lib/lifecycle');
+const { relativePosixPath, resolveTargetRoot } = require('./lib/paths');
+const {
+  hasQuiverInitializationEvidence,
+  readState,
+  updateStateForAnalyze,
+  updateStateForMigrate,
+} = require('./lib/state');
 const cliPackageJson = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../..', 'package.json'), 'utf8'));
 const CLI_VERSION = cliPackageJson.version || '0.0.0';
 
@@ -13,21 +28,56 @@ function printUsage() {
   console.log(`Usage:
   npx create-quiver [options]
   npx create-quiver analyze [options]
+  npx create-quiver plan [options]
+  npx create-quiver graph [options]
+  npx create-quiver next [options]
   npx create-quiver migrate [options]
   npx create-quiver doctor [options]
+  npx create-quiver start-slice [options] <slice.json>
+  npx create-quiver check-slice [options] <slice.json>
+  npx create-quiver check-pr <slice.json>
+  npx create-quiver check-handoff <handoff.md>
+  npx create-quiver new-handoff <spec-slug>
+  npx create-quiver cleanup-slice [options] <slice.json>
+  npx create-quiver check-scope [options] <slice.json>
+  npx create-quiver refresh-active-slices
 
 Options:
   -n, --name <project-name>   Project name to generate
   -d, --dir <target-dir>      Target directory to scaffold into or inspect
+      --spec <slug>           Restrict plan output to one spec
+      --format <name>         Graph output format (tree, mermaid, dot)
+      --show-conflicts        Show shared file paths in graph output
+      --level <n>             Restrict graph output to one level
+      --json                  Emit machine-readable JSON
+      --only-ready            Show only slices with no pending dependencies
+      --all-ready             List every ready slice returned by next
+      --auto-start            Prompt for confirmation and run start-slice on next
+      --unicode               Prefer Unicode output when supported
   -y, --yes                   Skip prompts and use the provided inputs
   -h, --help                  Show this help message
 
 Examples:
   npx create-quiver --name "My Project"
   npx create-quiver --name "My Project" --dir ./my-project
-  npx create-quiver analyze --dir ./my-project
-  npx create-quiver migrate --dir ./my-project
-  npx create-quiver doctor --dir ./my-project
+  cd ./my-project && npx create-quiver analyze
+  cd ./my-project && npx create-quiver plan --json
+  cd ./my-project && npx create-quiver graph --show-conflicts
+  cd ./my-project && npx create-quiver graph --format mermaid
+  cd ./my-project && npx create-quiver graph --format dot
+  cd ./my-project && npx create-quiver next
+  cd ./my-project && npx create-quiver next --all-ready
+  cd ./my-project && npx create-quiver next --auto-start
+  cd ./my-project && npx create-quiver migrate
+  cd ./my-project && npx create-quiver doctor
+  cd ./my-project && npx create-quiver start-slice specs/my-project/slices/slice-01/slice.json
+  cd ./my-project && npx create-quiver check-slice specs/my-project/slices/slice-01/slice.json
+  cd ./my-project && npx create-quiver check-pr specs/my-project/slices/slice-01/slice.json
+  cd ./my-project && npx create-quiver check-handoff specs/my-project/HANDOFF.md
+  cd ./my-project && npx create-quiver new-handoff my-spec
+  cd ./my-project && npx create-quiver cleanup-slice specs/my-project/slices/slice-01/slice.json
+  cd ./my-project && npx create-quiver check-scope specs/my-project/slices/slice-01/slice.json
+  cd ./my-project && npx create-quiver refresh-active-slices
   node bin/create-quiver.js doctor --dir ./my-project
 `);
 }
@@ -37,12 +87,29 @@ function parseArgs(argv) {
     help: false,
     force: false,
     mode: 'init',
+    allowDraft: false,
+    closeBaseline: false,
+    discard: false,
+    dryRun: false,
+    gate: 'execution',
     projectName: '',
     targetDir: '.',
+    strict: false,
+    strictOverlap: false,
+    json: false,
+    onlyReady: false,
+    allReady: false,
+    autoStart: false,
+    specSlug: '',
+    format: 'tree',
+    showConflicts: false,
+    level: null,
+    unicode: false,
   };
 
   const args = [...argv];
-  if (args[0] === 'doctor' || args[0] === 'analyze' || args[0] === 'migrate') {
+  const commandModes = new Set(['plan', 'graph', 'next', 'doctor', 'analyze', 'migrate', 'start-slice', 'check-slice', 'check-pr', 'check-handoff', 'new-handoff', 'cleanup-slice', 'check-scope', 'refresh-active-slices']);
+  if (commandModes.has(args[0])) {
     result.mode = args[0];
     args.shift();
   } else if (args[0] === '--analyze') {
@@ -54,6 +121,12 @@ function parseArgs(argv) {
   } else if (args[0] === '--doctor') {
     result.mode = 'doctor';
     args.shift();
+  } else if (args[0] === '--check-handoff') {
+    result.mode = 'check-handoff';
+    args.shift();
+  } else if (args[0] === '--new-handoff') {
+    result.mode = 'new-handoff';
+    args.shift();
   }
 
   const positional = [];
@@ -81,6 +154,116 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--check-handoff') {
+      result.mode = 'check-handoff';
+      continue;
+    }
+
+    if (arg === '--new-handoff') {
+      result.mode = 'new-handoff';
+      continue;
+    }
+
+    if (arg === '--allow-draft') {
+      result.allowDraft = true;
+      continue;
+    }
+
+    if (arg === '--close-baseline') {
+      result.closeBaseline = true;
+      continue;
+    }
+
+    if (arg === '--discard') {
+      result.discard = true;
+      continue;
+    }
+
+    if (arg === '--dry-run') {
+      result.dryRun = true;
+      continue;
+    }
+
+    if (arg === '--strict') {
+      result.strict = true;
+      continue;
+    }
+
+    if (arg === '--strict-overlap') {
+      result.strictOverlap = true;
+      continue;
+    }
+
+    if (arg === '--json') {
+      result.json = true;
+      continue;
+    }
+
+    if (arg === '--show-conflicts') {
+      result.showConflicts = true;
+      continue;
+    }
+
+    if (arg === '--format') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --format'));
+      }
+      result.format = value;
+      continue;
+    }
+
+    if (arg === '--level') {
+      const value = args[++index];
+      if (typeof value === 'undefined') {
+        throw new Error(formatError('missing value for --level'));
+      }
+      const parsed = Number.parseInt(value, 10);
+      if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new Error(formatError('invalid value for --level'));
+      }
+      result.level = parsed;
+      continue;
+    }
+
+    if (arg === '--only-ready') {
+      result.onlyReady = true;
+      continue;
+    }
+
+    if (arg === '--all-ready') {
+      result.allReady = true;
+      continue;
+    }
+
+    if (arg === '--auto-start') {
+      result.autoStart = true;
+      continue;
+    }
+
+    if (arg === '--unicode') {
+      result.unicode = true;
+      continue;
+    }
+
+    if (arg === '--spec') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --spec'));
+      }
+      result.specSlug = value;
+      continue;
+    }
+
+    if (arg === '--gate') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --gate'));
+      }
+      result.gate = value;
+      continue;
+    }
+
     if (arg === '-n' || arg === '--name' || arg === '--project-name') {
       const value = args[++index];
       if (!value) {
@@ -114,6 +297,14 @@ function parseArgs(argv) {
     if (positional.length > 0) {
       result.targetDir = positional.shift();
     }
+  } else if (result.mode === 'plan') {
+    if (positional.length > 0) {
+      throw new Error(formatError('plan does not accept positional arguments; use --spec <slug>'));
+    }
+  } else if (result.mode === 'refresh-active-slices') {
+    if (positional.length > 0) {
+      throw new Error(formatError('refresh-active-slices does not accept positional arguments'));
+    }
   } else {
     if (positional.length > 0) {
       result.targetDir = positional.shift();
@@ -204,84 +395,14 @@ function mergeDirectoryTree(sourceDir, targetDir) {
 }
 
 function runInitDocs(repoRoot, projectName) {
-  runCommand('bash', ['docs-template/scripts/init-docs.sh', projectName], {
-    cwd: repoRoot,
+  initializeProjectDocs({
+    projectRoot: repoRoot,
+    projectName,
+    cliVersion: CLI_VERSION,
+    migrateMode: false,
   });
 }
 
-function runInitDocsWithMode(repoRoot, projectName, mode) {
-  return runCommand('bash', ['docs-template/scripts/init-docs.sh', projectName], {
-    cwd: repoRoot,
-    env: {
-      ...process.env,
-      QUIVER_PROJECT_NAME: projectName,
-      QUIVER_MIGRATE: mode === 'migrate' ? '1' : '0',
-      QUIVER_VERSION: CLI_VERSION,
-    },
-  });
-}
-
-function writeQuiverState(projectRoot, nextState) {
-  const stateDir = path.join(projectRoot, '.quiver');
-  const statePath = path.join(stateDir, 'state.json');
-  fs.mkdirSync(stateDir, { recursive: true });
-  fs.writeFileSync(statePath, `${JSON.stringify(nextState, null, 2)}\n`);
-  return statePath;
-}
-
-function readQuiverState(projectRoot) {
-  return readJsonIfExists(path.join(projectRoot, '.quiver', 'state.json'));
-}
-
-function createInitialQuiverState(projectName) {
-  const now = new Date().toISOString();
-
-  return {
-    project_name: projectName,
-    quiver_version: CLI_VERSION,
-    initialized_version: CLI_VERSION,
-    migrated_version: null,
-    last_initialized_at: now,
-    last_migration_at: null,
-    last_analysis_at: null,
-  };
-}
-
-function updateQuiverStateForAnalyze(projectRoot) {
-  const currentState = readQuiverState(projectRoot);
-
-  if (!currentState) {
-    return null;
-  }
-
-  const nextState = {
-    ...currentState,
-    quiver_version: CLI_VERSION,
-    last_analysis_at: new Date().toISOString(),
-  };
-
-  writeQuiverState(projectRoot, nextState);
-  return nextState;
-}
-
-function updateQuiverStateForMigrate(projectRoot, projectName) {
-  const currentState = readQuiverState(projectRoot);
-  const now = new Date().toISOString();
-  const nextState = {
-    ...(currentState || {}),
-    project_name: projectName,
-    quiver_version: CLI_VERSION,
-    initialized_version: currentState?.initialized_version ?? null,
-    migrated_version: CLI_VERSION,
-    last_initialized_at: currentState?.last_initialized_at ?? null,
-    last_migration_at: now,
-    last_analysis_at: currentState?.last_analysis_at ?? null,
-  };
-
-  writeQuiverState(projectRoot, nextState);
-  return nextState;
-}
-
 function listGeneratedSpecDirs(projectRoot) {
   const specsDir = path.join(projectRoot, 'specs');
 
@@ -791,6 +912,49 @@ function buildProjectScan(projectRoot) {
 
 function renderProjectMap(scan) {
   const lines = [];
+  const projectSlug = scan.project.name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'project';
+  const docsFiles = new Set(scan.docs.files);
+  const hasDecisionLog = docsFiles.has('docs/DECISIONS.md');
+  const hasAiPrompt = docsFiles.has('docs/AI_ONBOARDING_PROMPT.md');
+  const sourceDirs = scan.structure.source_directories.length > 0 ? scan.structure.source_directories : [];
+  const configFiles = scan.structure.config_files.length > 0 ? scan.structure.config_files : [];
+  const highSignalFiles = [
+    'README.md',
+    'docs/INDEX.md',
+    'docs/AI_CONTEXT.md',
+    'docs/DECISIONS.md',
+    'docs/PROJECT_SCAN.json',
+    'docs/PROJECT_MAP.md',
+    'docs/AI_ONBOARDING_PROMPT.md',
+    'docs/CONTEXTO.md',
+    'docs/WORKFLOW.md',
+    'docs/SUPPORT_MATRIX.md',
+    'docs/TROUBLESHOOTING.md',
+    'package.json',
+    ...configFiles,
+  ].filter((value, index, array) => array.indexOf(value) === index);
+  const likelyTestCommands = [
+    ['Install', scan.commands.install || 'npm install'],
+    ['dev', scan.commands.common.dev || 'not defined'],
+    ['build', scan.commands.common.build || 'not defined'],
+    ['test', scan.commands.common.test || 'not defined'],
+    ['lint', scan.commands.common.lint || 'not defined'],
+  ];
+  const readingOrder = [
+    'README.md',
+    'docs/INDEX.md',
+    'docs/AI_CONTEXT.md',
+    'docs/PROJECT_SCAN.json',
+    'docs/PROJECT_MAP.md',
+    hasDecisionLog ? 'docs/DECISIONS.md' : 'docs/DECISIONS.md (create with migrate if missing)',
+    'docs/CONTEXTO.md',
+    'docs/WORKFLOW.md',
+    'docs/SUPPORT_MATRIX.md',
+    'docs/TROUBLESHOOTING.md',
+  ];
 
   lines.push('# Project Map');
   lines.push('');
@@ -804,37 +968,83 @@ function renderProjectMap(scan) {
   }
 
   lines.push('');
-  lines.push('## Stack');
-  lines.push(`- Primary: ${scan.stack.primary}`);
-  lines.push(`- Frameworks: ${scan.stack.frameworks.length > 0 ? scan.stack.frameworks.join(', ') : 'none detected'}`);
-  lines.push(`- Languages: ${scan.stack.languages.length > 0 ? scan.stack.languages.join(', ') : 'none detected'}`);
+  lines.push('## Suggested Reading Order');
+  for (const item of readingOrder) {
+    lines.push(`- ${item}`);
+  }
 
-  if (scan.stack.evidence.length > 0) {
-    lines.push('');
-    lines.push('### Evidence');
-    for (const item of scan.stack.evidence) {
-      lines.push(`- ${item.framework}: ${item.signals.join(', ')}`);
+  if (hasAiPrompt) {
+    lines.push('- docs/AI_ONBOARDING_PROMPT.md');
+  }
+
+  lines.push(`- specs/${projectSlug}/SPEC.md`);
+  if (sourceDirs.length > 0) {
+    for (const sourceDir of sourceDirs) {
+      lines.push(`- ${sourceDir}/...`);
+    }
+  }
+
+  lines.push('');
+  lines.push('## Entry Points');
+  lines.push(`- Project overview: ${scan.docs.has_readme ? 'README.md' : 'docs/CONTEXTO.md'}`);
+  lines.push(`- AI context: ${hasDecisionLog ? 'docs/AI_CONTEXT.md + docs/DECISIONS.md' : 'docs/AI_CONTEXT.md'}`);
+  lines.push('- Analysis outputs: docs/PROJECT_SCAN.json, docs/PROJECT_MAP.md');
+  lines.push(`- Workflow contract: docs/WORKFLOW.md`);
+  lines.push(`- Spec contract: specs/${projectSlug}/SPEC.md`);
+  if (sourceDirs.length > 0) {
+    lines.push(`- Source roots: ${sourceDirs.join(', ')}`);
+  } else {
+    lines.push('- Source roots: none detected');
+  }
+
+  lines.push('');
+  lines.push('## Primary Config Files');
+  if (configFiles.length > 0) {
+    for (const configFile of configFiles) {
+      lines.push(`- ${configFile}`);
     }
+  } else {
+    lines.push('- none detected');
   }
 
   lines.push('');
   lines.push('## Commands');
+  lines.push('See **Likely Test Commands** for the current read-friendly command summary.');
+
+  lines.push('');
+  lines.push('## Likely Test Commands');
   lines.push('| Command | Value |');
   lines.push('|---------|-------|');
-  lines.push(`| Install | ${escapeMarkdownCell(scan.commands.install || 'npm install')} |`);
-  lines.push(`| dev | ${escapeMarkdownCell(scan.commands.common.dev || 'not defined')} |`);
-  lines.push(`| build | ${escapeMarkdownCell(scan.commands.common.build || 'not defined')} |`);
-  lines.push(`| test | ${escapeMarkdownCell(scan.commands.common.test || 'not defined')} |`);
-  lines.push(`| lint | ${escapeMarkdownCell(scan.commands.common.lint || 'not defined')} |`);
+  for (const [name, value] of likelyTestCommands) {
+    lines.push(`| ${name} | ${escapeMarkdownCell(value)} |`);
+  }
+
+  const relevantScripts = Object.entries(scan.commands.scripts)
+    .filter(([name]) => /(^|:)(analyze|doctor|migrate|test|build|lint|dev|start|check)(:|$)|analyze|doctor|migrate|test|build|lint|dev|start|check/i.test(name))
+    .slice(0, 12);
 
-  if (Object.keys(scan.commands.scripts).length > 0) {
+  if (relevantScripts.length > 0) {
     lines.push('');
     lines.push('### package.json scripts');
-    for (const [name, command] of Object.entries(scan.commands.scripts)) {
+    for (const [name, command] of relevantScripts) {
       lines.push(`- ${name}: \`${command}\``);
     }
   }
 
+  lines.push('');
+  lines.push('## Stack');
+  lines.push(`- Primary: ${scan.stack.primary}`);
+  lines.push(`- Frameworks: ${scan.stack.frameworks.length > 0 ? scan.stack.frameworks.join(', ') : 'none detected'}`);
+  lines.push(`- Languages: ${scan.stack.languages.length > 0 ? scan.stack.languages.join(', ') : 'none detected'}`);
+
+  if (scan.stack.evidence.length > 0) {
+    lines.push('');
+    lines.push('### Evidence');
+    for (const item of scan.stack.evidence) {
+      lines.push(`- ${item.framework}: ${item.signals.join(', ')}`);
+    }
+  }
+
   lines.push('');
   lines.push('## Structure');
   lines.push(`- Top-level directories: ${scan.structure.top_level_directories.length > 0 ? scan.structure.top_level_directories.join(', ') : 'none detected'}`);
@@ -849,6 +1059,14 @@ function renderProjectMap(scan) {
   lines.push('## Docs');
   lines.push(`- README present: ${scan.docs.has_readme ? 'yes' : 'no'}`);
   lines.push(`- Docs files: ${scan.docs.files.length > 0 ? scan.docs.files.join(', ') : 'none detected'}`);
+  lines.push(`- Decision log: ${hasDecisionLog ? 'present' : 'missing'}`);
+  lines.push(`- AI onboarding prompt: ${hasAiPrompt ? 'present' : 'missing'}`);
+
+  lines.push('');
+  lines.push('## High-Signal Files');
+  for (const file of highSignalFiles) {
+    lines.push(`- ${file}`);
+  }
 
   lines.push('');
   lines.push('## Risks');
@@ -870,6 +1088,16 @@ function renderProjectMap(scan) {
     lines.push('- None');
   }
 
+  lines.push('');
+  lines.push('## Do Not Read First');
+  if (scan.skipped_paths.length > 0) {
+    for (const skippedPath of scan.skipped_paths) {
+      lines.push(`- ${skippedPath}`);
+    }
+  } else {
+    lines.push('- None detected, but still prioritize docs and config files before source trees.');
+  }
+
   lines.push('');
   return lines.join('\n');
 }
@@ -888,7 +1116,7 @@ function writeProjectScanArtifacts(projectRoot, scan) {
 }
 
 function runAnalyze(targetDir) {
-  const projectRoot = path.resolve(process.cwd(), targetDir);
+  const projectRoot = resolveTargetRoot(process.cwd(), targetDir);
 
   if (!fs.existsSync(projectRoot)) {
     throw new Error(formatError(`target directory does not exist: ${projectRoot}`));
@@ -896,22 +1124,26 @@ function runAnalyze(targetDir) {
 
   const scan = buildProjectScan(projectRoot);
   const artifacts = writeProjectScanArtifacts(projectRoot, scan);
-  updateQuiverStateForAnalyze(projectRoot);
+  updateStateForAnalyze(projectRoot, CLI_VERSION);
 
   console.log(`Project analysis completed for ${projectRoot}`);
-  console.log(`Wrote ${path.relative(projectRoot, artifacts.jsonPath)}`);
-  console.log(`Wrote ${path.relative(projectRoot, artifacts.mdPath)}`);
+  console.log(`Wrote ${relativePosixPath(projectRoot, artifacts.jsonPath)}`);
+  console.log(`Wrote ${relativePosixPath(projectRoot, artifacts.mdPath)}`);
   console.log(`Detected primary stack: ${scan.stack.primary}`);
   console.log(`Detected package manager: ${scan.project.package_manager}`);
 }
 
 function runMigrate(targetDir) {
-  const projectRoot = path.resolve(process.cwd(), targetDir);
+  const projectRoot = resolveTargetRoot(process.cwd(), targetDir);
 
   if (!fs.existsSync(projectRoot)) {
     throw new Error(formatError(`target directory does not exist: ${projectRoot}`));
   }
 
+  if (!hasQuiverInitializationEvidence(projectRoot)) {
+    throw new Error(formatError('migrate requires a project previously initialized by Quiver.\nRun: npx create-quiver --name "Project Name"'));
+  }
+
   const packageJson = loadPackageJson(projectRoot);
   const projectName = packageJson.name || path.basename(projectRoot) || 'Quiver Project';
   const packageRoot = path.resolve(__dirname, '../..');
@@ -920,15 +1152,13 @@ function runMigrate(targetDir) {
   try {
     const templateRoot = packTemplate(packageRoot, tempRoot);
     mergeDirectoryTree(templateRoot, path.join(projectRoot, 'docs-template'));
-    const migrationOutput = runInitDocsWithMode(projectRoot, projectName, 'migrate');
-    updateQuiverStateForMigrate(projectRoot, projectName);
-
-    if (migrationOutput.trim().length > 0) {
-      process.stdout.write(migrationOutput);
-      if (!migrationOutput.endsWith('\n')) {
-        process.stdout.write('\n');
-      }
-    }
+    initializeProjectDocs({
+      projectRoot,
+      projectName,
+      cliVersion: CLI_VERSION,
+      migrateMode: true,
+    });
+    updateStateForMigrate(projectRoot, projectName, CLI_VERSION);
 
     console.log(`Quiver migration completed for ${projectRoot}`);
     console.log('Missing workflow files were restored without overwriting existing project files.');
@@ -938,12 +1168,16 @@ function runMigrate(targetDir) {
 }
 
 function runDoctor(targetDir) {
-  const projectRoot = path.resolve(process.cwd(), targetDir);
+  const projectRoot = resolveTargetRoot(process.cwd(), targetDir);
 
   if (!fs.existsSync(projectRoot)) {
     throw new Error(formatError(`target directory does not exist: ${projectRoot}`));
   }
 
+  if (!hasQuiverInitializationEvidence(projectRoot)) {
+    throw new Error(formatError('doctor requires a project previously initialized by Quiver.\nRun init first: npx create-quiver --name "Project Name"'));
+  }
+
   const generatedSpecs = listGeneratedSpecDirs(projectRoot);
   if (generatedSpecs.length !== 1) {
     throw new Error(formatError(`expected exactly one generated spec directory, found ${generatedSpecs.length || 0}`));
@@ -951,6 +1185,7 @@ function runDoctor(targetDir) {
 
   const projectSlug = generatedSpecs[0];
   const requiredFiles = [
+    'AGENTS.md',
     'README.md',
     'docs/INDEX.md',
     'docs/AI_CONTEXT.md',
@@ -984,11 +1219,26 @@ function runDoctor(targetDir) {
   const missingFiles = assertFilesExist(projectRoot, requiredFiles);
   const nonExecutableScripts = assertExecutablesExist(projectRoot, requiredExecutables);
   const pkg = loadPackageJson(projectRoot);
-  const requiredScripts = ['check:slice', 'check:pr', 'start:slice', 'cleanup:slice', 'migrate'];
-  const missingScripts = requiredScripts.filter((name) => typeof pkg.scripts?.[name] !== 'string');
+  const workflowScriptGroups = [
+    { label: 'migrate', node: 'quiver:migrate', legacy: 'migrate' },
+    { label: 'start-slice', node: 'quiver:start-slice', legacy: 'start:slice' },
+    { label: 'check-slice', node: 'quiver:check-slice', legacy: 'check:slice' },
+    { label: 'check-pr', node: 'quiver:check-pr', legacy: 'check:pr' },
+    { label: 'cleanup-slice', node: 'quiver:cleanup-slice', legacy: 'cleanup:slice' },
+    { label: 'check-scope', node: 'quiver:check-scope', legacy: 'check:scope' },
+    { label: 'refresh-active-slices', node: 'quiver:refresh-active-slices', legacy: 'refresh:active-slices' },
+  ];
+  const missingScripts = workflowScriptGroups
+    .filter((group) => typeof pkg.scripts?.[group.node] !== 'string' && typeof pkg.scripts?.[group.legacy] !== 'string')
+    .map((group) => `${group.node} (or legacy ${group.legacy})`);
+  const legacyOnlyScripts = workflowScriptGroups
+    .filter((group) => typeof pkg.scripts?.[group.node] !== 'string' && typeof pkg.scripts?.[group.legacy] === 'string')
+    .map((group) => group.label);
+  const missingNodeNativeScripts = ['quiver:migrate', 'quiver:analyze', 'quiver:doctor']
+    .filter((name) => typeof pkg.scripts?.[name] !== 'string');
   const hasScanArtifacts = fs.existsSync(path.join(projectRoot, 'docs', 'PROJECT_SCAN.json'))
     && fs.existsSync(path.join(projectRoot, 'docs', 'PROJECT_MAP.md'));
-  const quiverState = readQuiverState(projectRoot);
+  const quiverState = readState(projectRoot);
   const hasQuiverState = Boolean(quiverState);
   const stateWarnings = hasQuiverState ? [] : ['missing Quiver state metadata: .quiver/state.json'];
   const migrationProblems = [
@@ -996,9 +1246,10 @@ function runDoctor(targetDir) {
     ...nonExecutableScripts.map((file) => `missing executable bit: ${file}`),
     ...missingScripts.map((name) => `missing package.json script: ${name}`),
   ];
+  const softWarnings = collectDoctorWarnings(projectRoot);
 
   if (migrationProblems.length > 0) {
-    throw new Error(formatError(`doctor failed:\n- ${migrationProblems.join('\n- ')}\n- Run migration first: npx create-quiver migrate --dir .`));
+    throw new Error(formatError(`doctor failed:\n- ${migrationProblems.join('\n- ')}\n- Run migration first: npx create-quiver migrate`));
   }
 
   console.log(`Quiver doctor passed for ${projectRoot}`);
@@ -1007,16 +1258,26 @@ function runDoctor(targetDir) {
   for (const warning of stateWarnings) {
     console.log(`- Warning: ${warning}`);
   }
+  for (const scriptName of missingNodeNativeScripts) {
+    console.log(`- Warning: missing Node-native script: ${scriptName}`);
+  }
+  if (legacyOnlyScripts.length > 0) {
+    console.log(`- Warning: legacy Bash workflow scripts detected for ${legacyOnlyScripts.join(', ')}. Run npx create-quiver migrate to add quiver:* npm scripts.`);
+  }
+  for (const warning of softWarnings) {
+    console.log(`- Warning: ${warning}`);
+  }
   if (!hasQuiverState) {
-    console.log('- Run migration first: npx create-quiver migrate --dir .');
+    console.log('- Run migration first: npx create-quiver migrate');
   } else if (!hasScanArtifacts) {
-    console.log('- Analyze the project first: npx create-quiver analyze --dir .');
+  console.log('- Analyze the project first: npx create-quiver analyze');
   } else {
-    console.log('- Ask your AI agent: Read docs/AI_ONBOARDING_PROMPT.md and execute it.');
+    console.log('- Ask your AI agent: Read AGENTS.md, then docs/AI_ONBOARDING_PROMPT.md and execute it.');
   }
-  console.log(`- Start a slice: bash tools/scripts/start-slice.sh specs/${projectSlug}/slices/slice-template/slice.json`);
-  console.log('- Validate a slice: bash tools/scripts/check-slice-readiness.sh');
-  console.log('- Validate the PR gate: bash tools/scripts/check-pr-readiness.sh');
+  console.log('- Check the next ready slice: npx create-quiver next');
+  console.log(`- Start a slice: npx create-quiver start-slice specs/${projectSlug}/slices/slice-template/slice.json`);
+  console.log(`- Validate a slice: npx create-quiver check-slice specs/${projectSlug}/slices/slice-template/slice.json`);
+  console.log(`- Validate the PR gate: npx create-quiver check-pr specs/${projectSlug}/slices/slice-template/slice.json`);
 }
 
 function printInitNextSteps(targetDir, projectName) {
@@ -1024,10 +1285,10 @@ function printInitNextSteps(targetDir, projectName) {
 
   console.log('');
   console.log('Next steps:');
-  console.log(`- Review ${path.join(targetDir, 'docs', 'INDEX.md')}`);
+  console.log(`- Review AGENTS.md, then ${path.join(targetDir, 'docs', 'INDEX.md')}`);
   console.log(`- Review ${path.join(targetDir, 'docs', 'WORKFLOW.md')}`);
   console.log(`- Create your first slice from ${path.join(targetDir, 'specs', projectSlug, 'slices', 'slice-template', 'slice.json')}`);
-  console.log(`- Launch slice work with ${path.join(targetDir, 'tools', 'scripts', 'start-slice.sh')}`);
+  console.log(`- Launch slice work with npx create-quiver start-slice specs/${projectSlug}/slices/slice-template/slice.json`);
 }
 
 async function run(argv) {
@@ -1043,6 +1304,37 @@ async function run(argv) {
     return;
   }
 
+  if (args.mode === 'plan') {
+    runPlan(process.cwd(), {
+      json: args.json,
+      onlyReady: args.onlyReady,
+      specSlug: args.specSlug,
+      unicode: args.unicode,
+    });
+    return;
+  }
+
+  if (args.mode === 'graph') {
+    runGraph(process.cwd(), {
+      format: args.format,
+      json: args.json,
+      level: args.level,
+      showConflicts: args.showConflicts,
+      unicode: args.unicode,
+    });
+    return;
+  }
+
+  if (args.mode === 'next') {
+    await runNext(process.cwd(), {
+      allReady: args.allReady,
+      autoStart: args.autoStart,
+      json: args.json,
+      specSlug: args.specSlug,
+    });
+    return;
+  }
+
   if (args.mode === 'migrate') {
     runMigrate(args.targetDir);
     return;
@@ -1053,8 +1345,66 @@ async function run(argv) {
     return;
   }
 
+  if (args.mode === 'start-slice') {
+    startSlice(path.resolve(process.cwd(), args.targetDir), { allowDraft: args.allowDraft });
+    return;
+  }
+
+  if (args.mode === 'check-slice') {
+    checkSliceReadiness(path.resolve(process.cwd(), args.targetDir), {
+      gate: args.gate,
+      strictOverlap: args.strictOverlap,
+    });
+    return;
+  }
+
+  if (args.mode === 'check-pr') {
+    checkPrReadiness(path.resolve(process.cwd(), args.targetDir));
+    return;
+  }
+
+  if (args.mode === 'check-handoff') {
+    const repoRoot = process.cwd();
+    const handoffInput = args.targetDir;
+    if (!handoffInput || handoffInput === '.') {
+      throw new Error(formatError('missing handoff path. Use: npx create-quiver check-handoff specs/<spec-slug>/HANDOFF.md'));
+    }
+    const resolved = checkHandoff(handoffInput, repoRoot);
+    console.log(`PASS: Handoff validated at ${resolved.relativePath}`);
+    return;
+  }
+
+  if (args.mode === 'new-handoff') {
+    const repoRoot = process.cwd();
+    const handoffSlug = args.targetDir;
+    const resolved = scaffoldHandoff(handoffSlug, repoRoot);
+    console.log(`PASS: Handoff scaffolded at ${resolved.relativePath}`);
+    return;
+  }
+
+  if (args.mode === 'cleanup-slice') {
+    cleanupSlice(path.resolve(process.cwd(), args.targetDir), {
+      closeBaseline: args.closeBaseline,
+      discard: args.discard,
+      dryRun: args.dryRun,
+      force: args.force,
+    });
+    return;
+  }
+
+  if (args.mode === 'check-scope') {
+    checkScope(path.resolve(process.cwd(), args.targetDir), { strict: args.strict });
+    return;
+  }
+
+  if (args.mode === 'refresh-active-slices') {
+    const outputPath = refreshActiveSlicesBoard(path.resolve(process.cwd(), '.'));
+    console.log(`Active slices refreshed: ${outputPath}`);
+    return;
+  }
+
   const packageRoot = path.resolve(__dirname, '../..');
-  const targetDir = path.resolve(process.cwd(), args.targetDir);
+  const targetDir = resolveTargetRoot(process.cwd(), args.targetDir);
   const projectName = args.projectName || path.basename(targetDir) || 'Quiver Project';
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-create-'));
 
@@ -1073,5 +1423,8 @@ async function run(argv) {
 }
 
 module.exports = {
+  runAnalyze,
+  runDoctor,
+  runMigrate,
   run,
 };