create-quiver 0.9.0 → 0.10.0

package/src/create-quiver/index.js

@@ -3,16 +3,27 @@ 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 { collectDoctorReport } = require('./lib/doctor');
+const { runDoctor: runAiDoctor, runExecuteSlice: runAiExecuteSlice, runOnboard, runPlan: runAiPlan, runPr: runAiPr } = require('./commands/ai');
 const { runGraph } = require('./commands/graph');
 const { runNext } = require('./commands/next');
 const { runPlan } = require('./commands/plan');
+const { buildInitLayout, formatInitLayoutPlan } = require('./lib/init-layout');
 const { initializeProjectDocs, installSelfAsDevDep } = 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 {
+  CURRENT_SCAN_RELATIVE_PATH,
+  PROJECT_MAP_RELATIVE_PATH,
+  hasProjectScanArtifact,
+  projectScanPaths,
+  writeProjectScanJson,
+} = require('./lib/project-scan');
+const { resolveTemplateRoot } = require('./lib/template-resolver');
 const {
   hasQuiverInitializationEvidence,
+  inspectLegacyMigrationLayout,
   readState,
   updateStateForAnalyze,
   updateStateForMigrate,
@@ -27,8 +38,10 @@ function formatError(message) {
 function printUsage() {
   console.log(`Usage:
   npx create-quiver [options]
+  npx create-quiver init [options]
   npx create-quiver analyze [options]
   npx create-quiver plan [options]
+  npx create-quiver ai <task> [options]
   npx create-quiver graph [options]
   npx create-quiver next [options]
   npx create-quiver migrate [options]
@@ -54,14 +67,26 @@ Options:
       --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
+      --minimal               Plan or run the minimal init profile
+      --full                  Plan or run the full compatibility init profile
+      --legacy-scripts        Include legacy Bash wrappers in init profile
+      --include-templates     Export packaged templates in init profile
+      --dry-run               Preview init or AI work without executing writes/providers
   -y, --yes                   Skip prompts and use the provided inputs
   -h, --help                  Show this help message
 
 Examples:
+  npx create-quiver init --name "My Project"
+  npx create-quiver init --name "My Project" --dry-run
   npx create-quiver --name "My Project"
   npx create-quiver --name "My Project" --dir ./my-project
   cd ./my-project && npx create-quiver analyze
   cd ./my-project && npx create-quiver plan --json
+  cd ./my-project && npx create-quiver ai onboard --dry-run
+  cd ./my-project && npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
+  cd ./my-project && npx create-quiver ai execute-slice --slice specs/my-project/slices/slice-01/slice.json --dry-run
+  cd ./my-project && npx create-quiver ai doctor --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+  cd ./my-project && npx create-quiver ai pr --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
   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
@@ -86,6 +111,7 @@ function parseArgs(argv) {
   const result = {
     help: false,
     force: false,
+    explicitInit: false,
     mode: 'init',
     allowDraft: false,
     closeBaseline: false,
@@ -105,12 +131,28 @@ function parseArgs(argv) {
     showConflicts: false,
     level: null,
     unicode: false,
+    aiCommand: '',
+    aiPhase: 'acceptance',
+    aiProvider: 'codex',
+    aiRole: '',
+    aiContext: '',
+    aiInput: '',
+    aiSlice: '',
+    aiTimeout: null,
+    aiSshHostAlias: '',
+    aiIdentityFile: '',
+    aiRemote: 'origin',
+    initFull: false,
+    initIncludeTemplates: false,
+    initLegacyScripts: false,
+    initMinimal: false,
   };
 
   const args = [...argv];
-  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']);
+  const commandModes = new Set(['init', 'plan', 'graph', 'next', 'doctor', 'analyze', 'migrate', 'start-slice', 'check-slice', 'check-pr', 'check-handoff', 'new-handoff', 'cleanup-slice', 'check-scope', 'refresh-active-slices', 'ai']);
   if (commandModes.has(args[0])) {
     result.mode = args[0];
+    result.explicitInit = args[0] === 'init';
     args.shift();
   } else if (args[0] === '--analyze') {
     result.mode = 'analyze';
@@ -189,6 +231,26 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--minimal') {
+      result.initMinimal = true;
+      continue;
+    }
+
+    if (arg === '--full') {
+      result.initFull = true;
+      continue;
+    }
+
+    if (arg === '--legacy-scripts') {
+      result.initLegacyScripts = true;
+      continue;
+    }
+
+    if (arg === '--include-templates') {
+      result.initIncludeTemplates = true;
+      continue;
+    }
+
     if (arg === '--strict') {
       result.strict = true;
       continue;
@@ -251,6 +313,100 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--provider') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --provider'));
+      }
+      result.aiProvider = value;
+      continue;
+    }
+
+    if (arg === '--role') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --role'));
+      }
+      result.aiRole = value;
+      continue;
+    }
+
+    if (arg === '--context') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --context'));
+      }
+      result.aiContext = value;
+      continue;
+    }
+
+    if (arg === '--input') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --input'));
+      }
+      result.aiInput = value;
+      continue;
+    }
+
+    if (arg === '--slice') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --slice'));
+      }
+      result.aiSlice = value;
+      continue;
+    }
+
+    if (arg === '--timeout') {
+      const value = args[++index];
+      if (typeof value === 'undefined') {
+        throw new Error(formatError('missing value for --timeout'));
+      }
+      const parsed = Number.parseInt(value, 10);
+      if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(formatError('invalid value for --timeout'));
+      }
+      result.aiTimeout = parsed;
+      continue;
+    }
+
+    if (arg === '--ssh-host-alias') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --ssh-host-alias'));
+      }
+      result.aiSshHostAlias = value;
+      continue;
+    }
+
+    if (arg === '--identity-file') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --identity-file'));
+      }
+      result.aiIdentityFile = value;
+      continue;
+    }
+
+    if (arg === '--remote') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --remote'));
+      }
+      result.aiRemote = value;
+      continue;
+    }
+
+    if (arg === '--phase') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --phase'));
+      }
+      result.aiPhase = value;
+      continue;
+    }
+
     if (arg === '--spec') {
       const value = args[++index];
       if (!value) {
@@ -306,6 +462,13 @@ function parseArgs(argv) {
     if (positional.length > 0) {
       throw new Error(formatError('plan does not accept positional arguments; use --spec <slug>'));
     }
+  } else if (result.mode === 'ai') {
+    if (!result.aiCommand && positional.length > 0) {
+      result.aiCommand = positional.shift();
+    }
+    if (positional.length > 0) {
+      throw new Error(formatError('ai does not accept extra positional arguments'));
+    }
   } else if (result.mode === 'refresh-active-slices') {
     if (positional.length > 0) {
       throw new Error(formatError('refresh-active-slices does not accept positional arguments'));
@@ -340,6 +503,43 @@ function runCommand(command, args, options = {}) {
   });
 }
 
+function copyPackageFallback(packageRoot, tempRoot) {
+  const fallbackDir = path.join(tempRoot, 'package-fallback');
+  const ignoredRoots = new Set([
+    '.git',
+    '.worktrees',
+    'examples',
+    'package-lock.json',
+    'tests',
+  ]);
+  const ignoredPrefixes = [
+    'scripts/ci',
+    'specs/quiver-v01',
+    'specs/quiver-v02-bootstrap-hardening',
+    'specs/quiver-v03-adoption-verification',
+    'specs/quiver-v04-zero-friction-installation',
+  ];
+
+  fs.cpSync(packageRoot, fallbackDir, {
+    recursive: true,
+    filter: (sourcePath) => {
+      const relativePath = relativePosixPath(packageRoot, sourcePath);
+      if (!relativePath || relativePath === '.') {
+        return true;
+      }
+
+      const firstSegment = relativePath.split('/')[0];
+      if (ignoredRoots.has(firstSegment) || ignoredRoots.has(relativePath)) {
+        return false;
+      }
+
+      return !ignoredPrefixes.some((prefix) => relativePath === prefix || relativePath.startsWith(`${prefix}/`));
+    },
+  });
+
+  return fallbackDir;
+}
+
 function packTemplate(packageRoot, tempRoot) {
   const packDir = path.join(tempRoot, 'pack');
   const extractDir = path.join(tempRoot, 'extract');
@@ -349,24 +549,32 @@ function packTemplate(packageRoot, tempRoot) {
   fs.mkdirSync(extractDir, { recursive: true });
   fs.mkdirSync(npmCache, { recursive: true });
 
-  const packOutput = runCommand('npm', ['pack', '--json', '--pack-destination', packDir], {
-    cwd: packageRoot,
-    env: {
-      ...process.env,
-      npm_config_cache: npmCache,
-    },
-  });
+  try {
+    const packOutput = runCommand('npm', ['pack', '--json', '--pack-destination', packDir], {
+      cwd: packageRoot,
+      env: {
+        ...process.env,
+        npm_config_cache: npmCache,
+      },
+    });
 
-  const packInfo = JSON.parse(packOutput.trim());
-  const tarballPath = path.join(packDir, packInfo[0].filename);
+    const packInfo = JSON.parse(packOutput.trim());
+    const tarballPath = path.join(packDir, packInfo[0].filename);
 
-  if (!fs.existsSync(tarballPath)) {
-    throw new Error(formatError(`pack output not found at ${tarballPath}`));
-  }
+    if (!fs.existsSync(tarballPath)) {
+      throw new Error(formatError(`pack output not found at ${tarballPath}`));
+    }
+
+    runCommand('tar', ['-xzf', tarballPath, '-C', extractDir]);
 
-  runCommand('tar', ['-xzf', tarballPath, '-C', extractDir]);
+    return path.join(extractDir, 'package');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return copyPackageFallback(packageRoot, tempRoot);
+    }
 
-  return path.join(extractDir, 'package');
+    throw error;
+  }
 }
 
 function ensureDir(dirPath) {
@@ -385,6 +593,10 @@ function copyTemplate(templateRoot, targetDir) {
   return docsTemplateDir;
 }
 
+function exportTemplatesToLegacyRoot(templateRoot, targetDir) {
+  return copyTemplate(templateRoot, targetDir);
+}
+
 function mergeDirectoryTree(sourceDir, targetDir) {
   if (!fs.existsSync(sourceDir)) {
     return;
@@ -399,12 +611,22 @@ function mergeDirectoryTree(sourceDir, targetDir) {
   });
 }
 
-function runInitDocs(repoRoot, projectName) {
+function runInitDocs(repoRoot, projectName, options = {}) {
+  const templateRoot = options.templateRoot
+    ? { path: options.templateRoot }
+    : resolveTemplateRoot(repoRoot, {
+      packageRoot: path.resolve(__dirname, '../..'),
+    });
+
   initializeProjectDocs({
     projectRoot: repoRoot,
     projectName,
     cliVersion: CLI_VERSION,
+    includeTemplates: options.includeTemplates === true,
+    legacyScripts: options.legacyScripts === true,
     migrateMode: false,
+    profile: options.profile || 'default',
+    templateRoot: templateRoot.path,
   });
 }
 
@@ -426,6 +648,10 @@ function assertFilesExist(root, relativePaths) {
 }
 
 function assertExecutablesExist(root, relativePaths) {
+  if (process.platform === 'win32') {
+    return [];
+  }
+
   return relativePaths.filter((relativePath) => {
     const absolutePath = path.join(root, relativePath);
 
@@ -931,8 +1157,8 @@ function renderProjectMap(scan) {
     'docs/INDEX.md',
     'docs/AI_CONTEXT.md',
     'docs/DECISIONS.md',
-    'docs/PROJECT_SCAN.json',
-    'docs/PROJECT_MAP.md',
+    CURRENT_SCAN_RELATIVE_PATH,
+    PROJECT_MAP_RELATIVE_PATH,
     'docs/AI_ONBOARDING_PROMPT.md',
     'docs/CONTEXTO.md',
     'docs/WORKFLOW.md',
@@ -952,8 +1178,7 @@ function renderProjectMap(scan) {
     'README.md',
     'docs/INDEX.md',
     'docs/AI_CONTEXT.md',
-    'docs/PROJECT_SCAN.json',
-    'docs/PROJECT_MAP.md',
+    PROJECT_MAP_RELATIVE_PATH,
     hasDecisionLog ? 'docs/DECISIONS.md' : 'docs/DECISIONS.md (create with migrate if missing)',
     'docs/CONTEXTO.md',
     'docs/WORKFLOW.md',
@@ -993,7 +1218,7 @@ function renderProjectMap(scan) {
   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(`- Analysis outputs: ${CURRENT_SCAN_RELATIVE_PATH}, ${PROJECT_MAP_RELATIVE_PATH}`);
   lines.push(`- Workflow contract: docs/WORKFLOW.md`);
   lines.push(`- Spec contract: specs/${projectSlug}/SPEC.md`);
   if (sourceDirs.length > 0) {
@@ -1108,16 +1333,13 @@ function renderProjectMap(scan) {
 }
 
 function writeProjectScanArtifacts(projectRoot, scan) {
-  const docsDir = path.join(projectRoot, 'docs');
-  ensureDir(docsDir);
-
-  const jsonPath = path.join(docsDir, 'PROJECT_SCAN.json');
-  const mdPath = path.join(docsDir, 'PROJECT_MAP.md');
+  const scanPaths = projectScanPaths(projectRoot);
+  ensureDir(path.dirname(scanPaths.projectMapPath));
 
-  fs.writeFileSync(jsonPath, `${JSON.stringify(scan, null, 2)}\n`);
-  fs.writeFileSync(mdPath, `${renderProjectMap(scan)}\n`);
+  const jsonPath = writeProjectScanJson(projectRoot, scan);
+  fs.writeFileSync(scanPaths.projectMapPath, `${renderProjectMap(scan)}\n`);
 
-  return { jsonPath, mdPath };
+  return { jsonPath, mdPath: scanPaths.projectMapPath };
 }
 
 function runAnalyze(targetDir) {
@@ -1138,7 +1360,7 @@ function runAnalyze(targetDir) {
   console.log(`Detected package manager: ${scan.project.package_manager}`);
 }
 
-function runMigrate(targetDir) {
+function runMigrate(targetDir, options = {}) {
   const projectRoot = resolveTargetRoot(process.cwd(), targetDir);
 
   if (!fs.existsSync(projectRoot)) {
@@ -1153,6 +1375,7 @@ function runMigrate(targetDir) {
   const projectName = packageJson.name || path.basename(projectRoot) || 'Quiver Project';
   const packageRoot = path.resolve(__dirname, '../..');
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-migrate-'));
+  const legacyLayout = inspectLegacyMigrationLayout(projectRoot);
 
   try {
     const templateRoot = packTemplate(packageRoot, tempRoot);
@@ -1161,11 +1384,14 @@ function runMigrate(targetDir) {
       projectRoot,
       projectName,
       cliVersion: CLI_VERSION,
+      legacyScripts: true,
       migrateMode: true,
+      profile: 'full',
+      templateRoot,
     });
     updateStateForMigrate(projectRoot, projectName, CLI_VERSION);
 
-    if (!args.skipInstall) {
+    if (!options.skipInstall) {
       const installResult = installSelfAsDevDep(projectRoot, CLI_VERSION);
       if (installResult === 'installed') {
         console.log(`Added create-quiver@${CLI_VERSION} as dev dependency`);
@@ -1176,6 +1402,9 @@ function runMigrate(targetDir) {
 
     console.log(`Quiver migration completed for ${projectRoot}`);
     console.log('Missing workflow files were restored without overwriting existing project files.');
+    if (legacyLayout.hasLegacyLayout) {
+      console.log(`Legacy layout detected and preserved: ${legacyLayout.legacyPaths.join(', ')}`);
+    }
   } finally {
     fs.rmSync(tempRoot, { recursive: true, force: true });
   }
@@ -1192,47 +1421,42 @@ function runDoctor(targetDir) {
     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}`));
-  }
-
-  const projectSlug = generatedSpecs[0];
-  const requiredFiles = [
+  const doctorReport = collectDoctorReport(projectRoot);
+  const specSlugs = doctorReport.specSlugs;
+  const specRequiredFiles = specSlugs.flatMap((projectSlug) => [
+    `specs/${projectSlug}/SPEC.md`,
+    `specs/${projectSlug}/STATUS.md`,
+    `specs/${projectSlug}/EVIDENCE_REPORT.md`,
+  ]);
+  const newLayoutRequiredFiles = [
     'AGENTS.md',
     'README.md',
-    'docs/INDEX.md',
     'docs/AI_CONTEXT.md',
     'docs/AI_ONBOARDING_PROMPT.md',
-    'docs/CONTEXTO.md',
+    'docs/COMMANDS.md',
     'docs/WORKFLOW.md',
-    'docs/SUPPORT_MATRIX.md',
-    'docs/TROUBLESHOOTING.md',
-    'docs/TESTING_GUIDE_FOR_AI.md',
-    'docs/ai/PRINCIPLES.md',
-    'docs/ai/RULES.yaml',
-    'docs/ai/LESSONS.md',
-    `specs/${projectSlug}/SPEC.md`,
-    `specs/${projectSlug}/STATUS.md`,
-    `specs/${projectSlug}/EVIDENCE_REPORT.md`,
     'package.json',
-    '.github/pull_request_template.md',
-    '.github/ISSUE_TEMPLATE/bug_report.md',
-    '.github/ISSUE_TEMPLATE/feature_request.md',
-    '.github/workflows/ci.yml',
+    '.quiver/state.json',
+    '.quiver/config.json',
+    '.quiver/.gitignore',
+    ...specRequiredFiles,
   ];
-
-  const requiredExecutables = [
-    'tools/scripts/start-slice.sh',
-    'tools/scripts/check-slice-readiness.sh',
-    'tools/scripts/check-pr-readiness.sh',
-    'tools/scripts/cleanup-slice.sh',
-    'tools/scripts/check-scope.sh',
-  ];
-
+  const requiredFiles = doctorReport.layout === 'legacy'
+    ? ['package.json', ...specRequiredFiles]
+    : newLayoutRequiredFiles;
+  const legacyScriptsDir = path.join(projectRoot, 'tools', 'scripts');
+  const requiredExecutables = fs.existsSync(legacyScriptsDir)
+    ? [
+        'tools/scripts/start-slice.sh',
+        'tools/scripts/check-slice-readiness.sh',
+        'tools/scripts/check-pr-readiness.sh',
+        'tools/scripts/cleanup-slice.sh',
+        'tools/scripts/check-scope.sh',
+      ]
+    : [];
   const missingFiles = assertFilesExist(projectRoot, requiredFiles);
   const nonExecutableScripts = assertExecutablesExist(projectRoot, requiredExecutables);
-  const pkg = loadPackageJson(projectRoot);
+  const pkg = fs.existsSync(path.join(projectRoot, 'package.json')) ? loadPackageJson(projectRoot) : {};
   const workflowScriptGroups = [
     { label: 'migrate', node: 'quiver:migrate', legacy: 'migrate' },
     { label: 'start-slice', node: 'quiver:start-slice', legacy: 'start:slice' },
@@ -1250,8 +1474,15 @@ function runDoctor(targetDir) {
     .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 missingAiScripts = [
+    'quiver:ai:onboard',
+    'quiver:ai:plan',
+    'quiver:ai:execute-slice',
+    'quiver:ai:pr',
+    'quiver:ai:doctor',
+  ].filter((name) => typeof pkg.scripts?.[name] !== 'string');
+  const hasScanArtifacts = hasProjectScanArtifact(projectRoot)
+    && fs.existsSync(path.join(projectRoot, PROJECT_MAP_RELATIVE_PATH));
   const quiverState = readState(projectRoot);
   const hasQuiverState = Boolean(quiverState);
   const stateWarnings = hasQuiverState ? [] : ['missing Quiver state metadata: .quiver/state.json'];
@@ -1260,21 +1491,35 @@ function runDoctor(targetDir) {
     ...nonExecutableScripts.map((file) => `missing executable bit: ${file}`),
     ...missingScripts.map((name) => `missing package.json script: ${name}`),
   ];
-  const softWarnings = collectDoctorWarnings(projectRoot);
+  const softWarnings = doctorReport.warnings;
 
   if (migrationProblems.length > 0) {
     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}`);
-  console.log(`Generated project slug: ${projectSlug}`);
+  console.log(`Layout: ${doctorReport.layout}`);
+  if (specSlugs.length > 0) {
+    console.log(`Specs: ${specSlugs.join(', ')}`);
+  } else {
+    console.log('Specs: none yet');
+  }
+  if (doctorReport.legacySignals.length > 0) {
+    console.log(`Legacy signals: ${doctorReport.legacySignals.join(', ')}`);
+  }
   console.log('Next steps:');
+  for (const recommendation of doctorReport.recommendations) {
+    console.log(`- ${recommendation}`);
+  }
   for (const warning of stateWarnings) {
     console.log(`- Warning: ${warning}`);
   }
   for (const scriptName of missingNodeNativeScripts) {
     console.log(`- Warning: missing Node-native script: ${scriptName}`);
   }
+  for (const scriptName of missingAiScripts) {
+    console.log(`- Warning: missing AI orchestration 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.`);
   }
@@ -1289,20 +1534,23 @@ function runDoctor(targetDir) {
     console.log('- Ask your AI agent: Read AGENTS.md, then docs/AI_ONBOARDING_PROMPT.md and execute it.');
   }
   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`);
+  if (specSlugs.length > 0) {
+    const projectSlug = specSlugs[0];
+    console.log(`- Start a slice: npx create-quiver start-slice specs/${projectSlug}/slices/<slice-id>/slice.json`);
+    console.log(`- Validate a slice: npx create-quiver check-slice specs/${projectSlug}/slices/<slice-id>/slice.json`);
+    console.log(`- Validate the PR gate: npx create-quiver check-pr specs/${projectSlug}/slices/<slice-id>/slice.json`);
+  } else {
+    console.log('- Create real specs and slices only after acceptance criteria and the technical plan are approved.');
+  }
 }
 
 function printInitNextSteps(targetDir, projectName) {
-  const projectSlug = toProjectSlug(projectName);
-
   console.log('');
   console.log('Next steps:');
-  console.log(`- Review AGENTS.md, then ${path.join(targetDir, 'docs', 'INDEX.md')}`);
+  console.log(`- Review AGENTS.md, then ${path.join(targetDir, 'docs', 'AI_ONBOARDING_PROMPT.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 npx create-quiver start-slice specs/${projectSlug}/slices/slice-template/slice.json`);
+  console.log('- Analyze the project with npx create-quiver analyze');
+  console.log('- Create real specs and slices after acceptance criteria and the technical plan are approved.');
 }
 
 async function run(argv) {
@@ -1328,6 +1576,72 @@ async function run(argv) {
     return;
   }
 
+  if (args.mode === 'ai') {
+    if (!args.aiCommand) {
+      throw new Error(formatError('missing ai subcommand. Use: npx create-quiver ai onboard | plan | execute-slice | doctor | pr'));
+    }
+
+    if (args.aiCommand === 'onboard') {
+      await runOnboard(process.cwd(), {
+        context: args.aiContext || undefined,
+        dryRun: args.dryRun,
+        input: args.aiInput || undefined,
+        provider: args.aiProvider,
+        role: args.aiRole,
+        timeout: args.aiTimeout,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'plan') {
+      await runAiPlan(process.cwd(), {
+        context: args.aiContext || undefined,
+        dryRun: args.dryRun,
+        input: args.aiInput || undefined,
+        phase: args.aiPhase,
+        provider: args.aiProvider,
+        role: args.aiRole,
+        specSlug: args.specSlug || undefined,
+        timeout: args.aiTimeout,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'execute-slice') {
+      await runAiExecuteSlice(process.cwd(), {
+        context: args.aiContext || undefined,
+        dryRun: args.dryRun,
+        provider: args.aiProvider,
+        role: args.aiRole,
+        slice: args.aiSlice || undefined,
+        timeout: args.aiTimeout,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'doctor') {
+      await runAiDoctor(process.cwd(), {
+        dryRun: args.dryRun,
+        remote: args.aiRemote || undefined,
+        sshHostAlias: args.aiSshHostAlias || undefined,
+        identityFile: args.aiIdentityFile || undefined,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'pr') {
+      await runAiPr(process.cwd(), {
+        dryRun: args.dryRun,
+        remote: args.aiRemote || undefined,
+        sshHostAlias: args.aiSshHostAlias || undefined,
+        identityFile: args.aiIdentityFile || undefined,
+      });
+      return;
+    }
+
+    throw new Error(formatError(`unsupported ai subcommand: ${args.aiCommand}. Supported tasks: onboard, plan, execute-slice, doctor, pr`));
+  }
+
   if (args.mode === 'graph') {
     runGraph(process.cwd(), {
       format: args.format,
@@ -1350,7 +1664,7 @@ async function run(argv) {
   }
 
   if (args.mode === 'migrate') {
-    runMigrate(args.targetDir);
+    runMigrate(args.targetDir, { skipInstall: args.skipInstall });
     return;
   }
 
@@ -1360,12 +1674,12 @@ async function run(argv) {
   }
 
   if (args.mode === 'start-slice') {
-    startSlice(path.resolve(process.cwd(), args.targetDir), { allowDraft: args.allowDraft });
+    startSlice(args.targetDir, { allowDraft: args.allowDraft });
     return;
   }
 
   if (args.mode === 'check-slice') {
-    checkSliceReadiness(path.resolve(process.cwd(), args.targetDir), {
+    checkSliceReadiness(args.targetDir, {
       gate: args.gate,
       strictOverlap: args.strictOverlap,
     });
@@ -1373,7 +1687,7 @@ async function run(argv) {
   }
 
   if (args.mode === 'check-pr') {
-    checkPrReadiness(path.resolve(process.cwd(), args.targetDir));
+    checkPrReadiness(args.targetDir);
     return;
   }
 
@@ -1397,7 +1711,7 @@ async function run(argv) {
   }
 
   if (args.mode === 'cleanup-slice') {
-    cleanupSlice(path.resolve(process.cwd(), args.targetDir), {
+    cleanupSlice(args.targetDir, {
       closeBaseline: args.closeBaseline,
       discard: args.discard,
       dryRun: args.dryRun,
@@ -1407,7 +1721,7 @@ async function run(argv) {
   }
 
   if (args.mode === 'check-scope') {
-    checkScope(path.resolve(process.cwd(), args.targetDir), { strict: args.strict });
+    checkScope(args.targetDir, { strict: args.strict });
     return;
   }
 
@@ -1420,14 +1734,37 @@ async function run(argv) {
   const packageRoot = path.resolve(__dirname, '../..');
   const targetDir = resolveTargetRoot(process.cwd(), args.targetDir);
   const projectName = args.projectName || path.basename(targetDir) || 'Quiver Project';
+  const initLayout = buildInitLayout(targetDir, {
+    compatibilityAlias: !args.explicitInit,
+    dryRun: args.dryRun,
+    full: args.initFull,
+    includeTemplates: args.initIncludeTemplates,
+    legacyScripts: args.initLegacyScripts,
+    minimal: args.initMinimal,
+    projectName,
+    skipInstall: args.skipInstall,
+  });
+
+  if (args.dryRun) {
+    console.log(formatInitLayoutPlan(initLayout));
+    return;
+  }
+
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-create-'));
 
   try {
     ensureDir(targetDir);
 
     const templateRoot = packTemplate(packageRoot, tempRoot);
-    copyTemplate(templateRoot, targetDir);
-    runInitDocs(targetDir, projectName);
+    if (initLayout.profile === 'full') {
+      exportTemplatesToLegacyRoot(templateRoot, targetDir);
+    }
+    runInitDocs(targetDir, projectName, {
+      includeTemplates: args.initIncludeTemplates,
+      legacyScripts: args.initLegacyScripts,
+      profile: initLayout.profile,
+      templateRoot,
+    });
 
     if (!args.skipInstall) {
       const installResult = installSelfAsDevDep(targetDir, CLI_VERSION);