create-quiver 0.6.0 → 0.7.0

package/src/create-quiver/index.js

@@ -2,6 +2,16 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const { collectDoctorWarnings } = require('./lib/doctor');
+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 {
+  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';
 
@@ -15,6 +25,12 @@ function printUsage() {
   npx create-quiver analyze [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 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
@@ -25,9 +41,15 @@ Options:
 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 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 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 +59,20 @@ 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,
   };
 
   const args = [...argv];
-  if (args[0] === 'doctor' || args[0] === 'analyze' || args[0] === 'migrate') {
+  const commandModes = new Set(['doctor', 'analyze', 'migrate', 'start-slice', 'check-slice', 'check-pr', 'cleanup-slice', 'check-scope', 'refresh-active-slices']);
+  if (commandModes.has(args[0])) {
     result.mode = args[0];
     args.shift();
   } else if (args[0] === '--analyze') {
@@ -81,6 +111,45 @@ function parseArgs(argv) {
       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 === '--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 +183,10 @@ function parseArgs(argv) {
     if (positional.length > 0) {
       result.targetDir = positional.shift();
     }
+  } 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 +277,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 +794,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 +850,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)} |`);
+  }
 
-  if (Object.keys(scan.commands.scripts).length > 0) {
+  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 (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 +941,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 +970,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 +998,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,17 +1006,17 @@ 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}`));
@@ -920,15 +1030,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,7 +1046,7 @@ 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}`));
@@ -951,6 +1059,7 @@ function runDoctor(targetDir) {
 
   const projectSlug = generatedSpecs[0];
   const requiredFiles = [
+    'AGENTS.md',
     'README.md',
     'docs/INDEX.md',
     'docs/AI_CONTEXT.md',
@@ -984,11 +1093,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 +1120,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 +1132,25 @@ 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(`- 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 +1158,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) {
@@ -1053,8 +1187,47 @@ 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 === '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 +1246,8 @@ async function run(argv) {
 }
 
 module.exports = {
+  runAnalyze,
+  runDoctor,
+  runMigrate,
   run,
 };

package/src/create-quiver/lib/analyze.js

@@ -0,0 +1,9 @@
+const { runAnalyze } = require('../index');
+
+function analyzeProject(targetDir) {
+  return runAnalyze(targetDir);
+}
+
+module.exports = {
+  analyzeProject,
+};