create-quiver 0.15.4 → 0.16.0

package/src/create-quiver/index.js

@@ -35,6 +35,7 @@ const {
   runSpecsList: runAiSpecsList,
   runTraceReport: runAiTraceReport,
 } = require('./commands/ai');
+const { runChangelog } = require('./commands/changelog');
 const { runConfig } = require('./commands/config');
 const { runDashboard } = require('./commands/dashboard');
 const { runDemo } = require('./commands/demo');
@@ -58,6 +59,15 @@ const { cleanupSlice, refreshActiveSlicesBoard, startSlice } = require('./lib/li
 const { buildSpecStatus, closeSpecWorktree, formatSpecCloseResult, formatSpecStartResult, formatSpecStatus, startSpecWorktree } = require('./lib/spec-worktrees');
 const { getContextPathExclusionReason } = require('./lib/ai/safety');
 const { selectOption } = require('./lib/cli/selectors');
+const {
+  SUPPORTED_AI_COMMANDS,
+  SUPPORTED_COMMAND_MODES,
+  SUPPORTED_CONFIG_LANGUAGE_COMMANDS,
+  SUPPORTED_CONFIG_SECTIONS,
+  SUPPORTED_DEMO_COMMANDS,
+  SUPPORTED_SPEC_COMMANDS,
+} = require('./lib/cli/command-registry');
+const { parseCliArgs } = require('./lib/cli/parser');
 const { createUx } = require('./lib/cli/ux');
 const { validateUxFlags } = require('./lib/cli/ux-flags');
 const {
@@ -145,65 +155,38 @@ function formatLanguageWarningForCli(warning, language = DEFAULT_LANGUAGE) {
   }));
 }
 
-const SUPPORTED_COMMAND_MODES = new Set([
-  'init',
-  'version',
-  'flow',
-  'dashboard',
-  'plan',
-  'graph',
-  'next',
-  'doctor',
-  'prepare',
-  'analyze',
-  'migrate',
-  'start-slice',
-  'check-slice',
-  'check-pr',
-  'check-handoff',
-  'new-handoff',
-  'cleanup-slice',
-  'check-scope',
-  'config',
-  'refresh-active-slices',
-  'spec',
-  'evidence',
-  'demo',
-  'ai',
-]);
+const SLICE_NAMESPACE_COMMANDS = Object.freeze({
+  start: 'start-slice',
+  check: 'check-slice',
+  pr: 'check-pr',
+  scope: 'check-scope',
+  cleanup: 'cleanup-slice',
+  'refresh-active': 'refresh-active-slices',
+});
 
-const SUPPORTED_AI_COMMANDS = new Set([
-  'active-slice',
-  'agent',
-  'approve',
-  'approval-status',
-  'approvals',
-  'doctor',
-  'execute-plan',
-  'execute-slice',
-  'executor-prompt',
-  'export',
-  'inspect',
-  'onboard',
-  'plan',
-  'prepare-context',
-  'pr',
-  'prompt-slice',
-  'repair-plan',
-  'review-plan',
-  'revise',
-  'resume',
-  'run',
-  'slices',
-  'specs',
-  'status',
-  'trace',
-]);
+const HANDOFF_NAMESPACE_COMMANDS = Object.freeze({
+  check: 'check-handoff',
+  new: 'new-handoff',
+});
+
+const LEGACY_NAMESPACE_ALIASES = Object.freeze({
+  'start-slice': 'slice start',
+  'check-slice': 'slice check',
+  'check-pr': 'slice pr',
+  'check-scope': 'slice scope',
+  'cleanup-slice': 'slice cleanup',
+  'refresh-active-slices': 'slice refresh-active',
+  'check-handoff': 'handoff check',
+  'new-handoff': 'handoff new',
+});
+
+function legacyNamespaceAliasFor(mode) {
+  return LEGACY_NAMESPACE_ALIASES[mode] || '';
+}
 
-const SUPPORTED_SPEC_COMMANDS = new Set(['close', 'create', 'start', 'status', 'validate']);
-const SUPPORTED_DEMO_COMMANDS = new Set(['create']);
-const SUPPORTED_CONFIG_SECTIONS = new Set(['language']);
-const SUPPORTED_CONFIG_LANGUAGE_COMMANDS = new Set(['show', 'set']);
+function formatLegacyNamespaceWarning(mode, canonicalCommand) {
+  return `create-quiver: ${mode} is a legacy alias; use npx create-quiver ${canonicalCommand}.`;
+}
 
 function unsupportedCommandMessage(commandName) {
   const translator = createTranslator(currentErrorLanguage);
@@ -225,6 +208,7 @@ const COMMAND_HELP_GROUPS = [
       ['flow', 'Show the read-only guided workflow stage, blockers, and next safe command.'],
       ['dashboard', 'Show compact read-only project, spec, slice, run, approval, and agent status.'],
       ['version', 'Show a Quiver-branded version report; use --json for metadata.'],
+      ['changelog', 'Show recent local CHANGELOG.md release entries; use --json for metadata.'],
       ['config language show|set', 'Inspect or update the effective Quiver language without editing JSON by hand.'],
       ['prepare', 'Run setup diagnostics for providers, GitHub, SSH, and project readiness.'],
       ['migrate', 'Upgrade an already initialized Quiver project to the current contract.'],
@@ -280,6 +264,8 @@ const COMMAND_HELP_GROUPS = [
       ['spec status', 'Show spec worktree, branch, slice-00 state, and pending slices.'],
       ['spec validate', 'Validate spec docs, slices, briefs, evidence, status, dependencies, and safe paths.'],
       ['spec close', 'Close a merged clean spec worktree and guide local sync.'],
+      ['slice start|check|pr|scope|cleanup|refresh-active', 'Canonical namespace for slice lifecycle, validation, scope, and board commands.'],
+      ['handoff check|new', 'Canonical namespace for validating or scaffolding handoff artifacts.'],
       ['start-slice', 'Start work on one slice and mark it active.'],
       ['check-slice', 'Validate slice structure, dependencies, scope, and readiness.'],
       ['check-pr', 'Validate PR readiness for a slice/spec workflow.'],
@@ -294,6 +280,8 @@ const COMMAND_HELP_GROUPS = [
     title: 'Evidence and demos',
     commands: [
       ['evidence run', 'Run a command and record exit code, duration, redacted output, and Markdown evidence.'],
+      ['evidence list', 'List local evidence records; use --json for automation.'],
+      ['evidence show', 'Show one local evidence record; use --json for automation.'],
       ['demo create spec-viewer', 'Create or preview the optional static Quiver Spec Viewer demo scaffold.'],
     ],
   },
@@ -329,6 +317,7 @@ function printUsage(language = DEFAULT_LANGUAGE) {
   npx create-quiver flow [options]
   npx create-quiver dashboard [options]
   npx create-quiver version [--json]
+  npx create-quiver changelog [--json]
   npx create-quiver config language show [--json]
   npx create-quiver config language set <en|es> [--global]
   npx create-quiver plan [options]
@@ -366,7 +355,9 @@ function printUsage(language = DEFAULT_LANGUAGE) {
   npx create-quiver spec status <spec-dir>
   npx create-quiver spec validate <spec-dir>
   npx create-quiver spec close <spec-dir>
-  npx create-quiver evidence run [options] -- <command>
+  npx create-quiver slice <start|check|pr|scope|cleanup|refresh-active> [options]
+  npx create-quiver handoff <check|new> [options]
+  npx create-quiver evidence <run|list|show> [options]
   npx create-quiver demo create spec-viewer [options]
 
 ${formatCommandHelpGroups(language)}
@@ -415,11 +406,11 @@ ${helpText(help, 'headings', 'options', 'Options:')}
       --ssh-host-alias <name> ${optionDescription(help, 'SSH host alias to validate for prepare or AI commands')}
       --identity-file <path>  ${optionDescription(help, 'SSH identity file to validate for prepare or AI commands')}
       --remote <name>         ${optionDescription(help, 'Git remote name for check-slice or AI PR checks')}
-      --base <branch>         ${optionDescription(help, 'Base branch for check-slice, check-scope, ai pr, or spec close (default: main)')}
+      --base <branch>         ${optionDescription(help, 'Base branch override for check-slice, check-scope, check-pr, ai pr, spec start, or spec close')}
       --output <file>         ${optionDescription(help, 'Output file for evidence run')}
       --max-output <n>        ${optionDescription(help, 'Maximum stdout/stderr chars per evidence section')}
       --title <text>          ${optionDescription(help, 'Override PR title for ai pr create')}
-  -y, --yes                   ${optionDescription(help, 'Skip prompts and use the provided inputs')}
+  -y, --yes                   ${optionDescription(help, 'Skip prompts and confirm write prompts such as migrate')}
   -V, --version               ${optionDescription(help, 'Show the installed create-quiver version')}
   -h, --help                  ${optionDescription(help, 'Show this help message')}
 
@@ -435,6 +426,8 @@ ${helpText(help, 'headings', 'examples', 'Examples:')}
   cd ./my-project && npx create-quiver dashboard --json
   cd ./my-project && npx create-quiver version
   cd ./my-project && npx create-quiver version --json
+  cd ./my-project && npx create-quiver changelog
+  cd ./my-project && npx create-quiver changelog --json
   cd ./my-project && npx create-quiver config language show
   cd ./my-project && npx create-quiver config language set es
   npx create-quiver config language set en --global
@@ -499,6 +492,8 @@ ${helpText(help, 'headings', 'examples', 'Examples:')}
   cd ./my-project && npx create-quiver spec status specs/my-project
   cd ./my-project && npx create-quiver spec validate specs/my-project
   cd ./my-project && npx create-quiver spec close specs/my-project --dry-run
+  cd ./my-project && npx create-quiver slice check --local specs/my-project/slices/slice-01/slice.json
+  cd ./my-project && npx create-quiver handoff check specs/my-project/slices/slice-01/EXECUTION_BRIEF.md
   cd ./my-project && npx create-quiver evidence run -- npm test
   cd ./my-project && npx create-quiver demo create spec-viewer --dry-run
   node bin/create-quiver.js doctor --dir ./my-project
@@ -584,22 +579,33 @@ function parseArgs(argv, options = {}) {
     initLegacyScripts: false,
     initMinimal: false,
     specCommand: '',
+    sliceCommand: '',
+    handoffCommand: '',
+    legacyAliasCommand: '',
     demoCommand: '',
     demoName: '',
     evidenceCommand: '',
     evidenceArgs: [],
     evidenceOutput: '',
     evidenceMaxOutput: null,
+    evidenceTarget: '',
   };
 
   const args = [...argv];
   if (SUPPORTED_COMMAND_MODES.has(args[0])) {
     result.mode = args[0];
+    result.legacyAliasCommand = legacyNamespaceAliasFor(result.mode);
     result.explicitInit = args[0] === 'init';
     args.shift();
     if (result.mode === 'spec') {
       result.specCommand = args.shift() || '';
     }
+    if (result.mode === 'slice') {
+      result.sliceCommand = args.shift() || '';
+    }
+    if (result.mode === 'handoff') {
+      result.handoffCommand = args.shift() || '';
+    }
     if (result.mode === 'evidence') {
       result.evidenceCommand = args.shift() || '';
     }
@@ -618,9 +624,11 @@ function parseArgs(argv, options = {}) {
     args.shift();
   } else if (args[0] === '--check-handoff') {
     result.mode = 'check-handoff';
+    result.legacyAliasCommand = legacyNamespaceAliasFor(result.mode);
     args.shift();
   } else if (args[0] === '--new-handoff') {
     result.mode = 'new-handoff';
+    result.legacyAliasCommand = legacyNamespaceAliasFor(result.mode);
     args.shift();
   } else if (args[0] && !args[0].startsWith('-')) {
     throw new Error(formatError(unsupportedCommandMessage(args[0])));
@@ -671,11 +679,13 @@ function parseArgs(argv, options = {}) {
 
     if (arg === '--check-handoff') {
       result.mode = 'check-handoff';
+      result.legacyAliasCommand = legacyNamespaceAliasFor(result.mode);
       continue;
     }
 
     if (arg === '--new-handoff') {
       result.mode = 'new-handoff';
+      result.legacyAliasCommand = legacyNamespaceAliasFor(result.mode);
       continue;
     }
 
@@ -1197,13 +1207,17 @@ function parseArgs(argv, options = {}) {
       result.configSection = positional.shift();
     }
     if (!SUPPORTED_CONFIG_SECTIONS.has(result.configSection)) {
-      throw new Error(formatError(`unsupported config section: ${result.configSection || '(missing)'}. Supported sections: language`));
+      throw new Error(formatError(translate(currentErrorLanguage, 'config.error.unsupported_section', {
+        section: result.configSection || '(missing)',
+      })));
     }
     if (!result.configCommand && positional.length > 0) {
       result.configCommand = positional.shift();
     }
     if (!SUPPORTED_CONFIG_LANGUAGE_COMMANDS.has(result.configCommand)) {
-      throw new Error(formatError(`unsupported config language command: ${result.configCommand || '(missing)'}. Supported commands: show, set`));
+      throw new Error(formatError(translate(currentErrorLanguage, 'config.error.unsupported_language_command', {
+        command: result.configCommand || '(missing)',
+      })));
     }
     if (result.configCommand === 'set') {
       if (positional.length === 0) {
@@ -1252,6 +1266,38 @@ function parseArgs(argv, options = {}) {
     if (positional.length > 0) {
       throw new Error(formatError('refresh-active-slices does not accept positional arguments'));
     }
+  } else if (result.mode === 'slice') {
+    if (!result.sliceCommand && positional.length > 0) {
+      result.sliceCommand = positional.shift();
+    }
+    const mappedMode = SLICE_NAMESPACE_COMMANDS[result.sliceCommand];
+    if (!mappedMode) {
+      throw new Error(formatError(`unsupported slice subcommand: ${result.sliceCommand || '(missing)'}. Supported tasks: start, check, pr, scope, cleanup, refresh-active`));
+    }
+    result.mode = mappedMode;
+    if (mappedMode === 'refresh-active-slices') {
+      if (positional.length > 0) {
+        throw new Error(formatError('slice refresh-active does not accept positional arguments'));
+      }
+    } else {
+      result.targetDir = positional.shift() || '';
+      if (!result.targetDir) {
+        throw new Error(formatError(`slice ${result.sliceCommand} requires a slice.json path`));
+      }
+    }
+  } else if (result.mode === 'handoff') {
+    if (!result.handoffCommand && positional.length > 0) {
+      result.handoffCommand = positional.shift();
+    }
+    const mappedMode = HANDOFF_NAMESPACE_COMMANDS[result.handoffCommand];
+    if (!mappedMode) {
+      throw new Error(formatError(`unsupported handoff subcommand: ${result.handoffCommand || '(missing)'}. Supported tasks: check, new`));
+    }
+    result.mode = mappedMode;
+    result.targetDir = positional.shift() || '';
+    if (!result.targetDir) {
+      throw new Error(formatError(`handoff ${result.handoffCommand} requires ${result.handoffCommand === 'new' ? 'a spec slug' : 'a handoff or brief path'}`));
+    }
   } else if (result.mode === 'spec') {
     if (!result.specCommand && positional.length > 0) {
       result.specCommand = positional.shift();
@@ -1270,14 +1316,26 @@ function parseArgs(argv, options = {}) {
       result.evidenceCommand = positional.shift();
     }
     if (!result.evidenceCommand) {
-      throw new Error(formatError('missing evidence subcommand. Use: npx create-quiver evidence run -- <command>'));
+      throw new Error(formatError('missing evidence subcommand. Use: npx create-quiver evidence <run|list|show>'));
     }
-    if (result.evidenceCommand !== 'run') {
-      throw new Error(formatError(`unsupported evidence subcommand: ${result.evidenceCommand}. Supported tasks: run`));
+    if (!['run', 'list', 'show'].includes(result.evidenceCommand)) {
+      throw new Error(formatError(`unsupported evidence subcommand: ${result.evidenceCommand}. Supported tasks: run, list, show`));
     }
-    if (positional.length > 0) {
+    if (result.evidenceCommand === 'run' && positional.length > 0) {
       throw new Error(formatError('evidence run does not accept positional arguments before --'));
     }
+    if (result.evidenceCommand === 'list' && positional.length > 0) {
+      throw new Error(formatError('evidence list does not accept positional arguments'));
+    }
+    if (result.evidenceCommand === 'show') {
+      result.evidenceTarget = positional.shift() || '';
+      if (!result.evidenceTarget) {
+        throw new Error(formatError('evidence show requires an evidence file path'));
+      }
+      if (positional.length > 0) {
+        throw new Error(formatError('evidence show accepts exactly one evidence file path'));
+      }
+    }
   } else if (result.mode === 'demo') {
     if (!result.demoCommand && positional.length > 0) {
       result.demoCommand = positional.shift();
@@ -2321,15 +2379,46 @@ function writeProjectScanArtifacts(projectRoot, scan) {
   return { jsonPath, mdPath: scanPaths.projectMapPath };
 }
 
-function runAnalyze(targetDir, options = {}) {
+function createCommandProgressUx(options = {}) {
+  return createUx({
+    env: options.env || process.env,
+    error: options.error,
+    input: options.input,
+    interactive: false,
+    json: options.json,
+    noColor: options.noColor,
+    output: options.output,
+    prompts: options.prompts,
+    spinner: options.noColor === true ? false : options.spinner,
+    stderrIsTTY: options.stderrIsTTY,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    write: options.write,
+  });
+}
+
+async function runProgress(ux, message, task, successMessage = message) {
+  return ux.withSpinner(message, task, {
+    echo: false,
+    successMessage,
+  });
+}
+
+async function runAnalyze(targetDir, options = {}) {
   const projectRoot = resolveTargetRoot(process.cwd(), targetDir);
   const translator = createTranslator(options.language);
+  const progress = createCommandProgressUx(options);
 
   if (!fs.existsSync(projectRoot)) {
     throw new Error(formatError(`target directory does not exist: ${projectRoot}`));
   }
 
-  const scan = buildProjectScan(projectRoot);
+  const scan = await runProgress(
+    progress,
+    translator.t('analyze.progress.scanning'),
+    () => buildProjectScan(projectRoot),
+    translator.t('analyze.progress.scanned'),
+  );
 
   if (options.dryRun) {
     console.log(translator.t('analyze.dry_run_for', { path: projectRoot }));
@@ -2350,9 +2439,24 @@ function runAnalyze(targetDir, options = {}) {
     };
   }
 
-  const artifacts = writeProjectScanArtifacts(projectRoot, scan);
-  const aiContextPath = refreshAiContextDoc(projectRoot, scan);
-  updateStateForAnalyze(projectRoot, CLI_VERSION);
+  const artifacts = await runProgress(
+    progress,
+    translator.t('analyze.progress.writing_artifacts'),
+    () => writeProjectScanArtifacts(projectRoot, scan),
+    translator.t('analyze.progress.artifacts_written'),
+  );
+  const aiContextPath = await runProgress(
+    progress,
+    translator.t('analyze.progress.refreshing_context'),
+    () => refreshAiContextDoc(projectRoot, scan),
+    translator.t('analyze.progress.context_refreshed'),
+  );
+  await runProgress(
+    progress,
+    translator.t('analyze.progress.updating_state'),
+    () => updateStateForAnalyze(projectRoot, CLI_VERSION),
+    translator.t('analyze.progress.state_updated'),
+  );
 
   console.log(translator.t('analyze.completed_for', { path: projectRoot }));
   console.log(translator.t('analyze.wrote', { path: relativePosixPath(projectRoot, artifacts.jsonPath) }));
@@ -2369,7 +2473,39 @@ function runAnalyze(targetDir, options = {}) {
   };
 }
 
-function runMigrate(targetDir, options = {}) {
+async function confirmMigrateWrite(projectRoot, options, translator) {
+  if (options.force === true) {
+    return;
+  }
+
+  const ux = createUx({
+    env: options.env,
+    error: options.error,
+    input: options.input,
+    interactive: true,
+    json: options.json,
+    noColor: options.noColor,
+    output: options.output,
+    promptConfirm: options.promptConfirm,
+    stderrIsTTY: options.stderrIsTTY,
+    stdinIsTTY: options.stdinIsTTY,
+    stdoutIsTTY: options.stdoutIsTTY,
+    write: options.write,
+  });
+
+  if (!ux.mode.usePrompts) {
+    throw new Error(formatError(translator.t('migrate.confirm.required')));
+  }
+
+  const confirmed = await ux.promptConfirm(translator.t('migrate.confirm.prompt', { path: projectRoot }), {
+    initialValue: false,
+  });
+  if (!confirmed) {
+    throw new Error(formatError(translator.t('migrate.confirm.declined')));
+  }
+}
+
+async function runMigrate(targetDir, options = {}) {
   const projectRoot = resolveTargetRoot(process.cwd(), targetDir);
   const translator = createTranslator(options.language);
 
@@ -2410,6 +2546,8 @@ function runMigrate(targetDir, options = {}) {
     return;
   }
 
+  await confirmMigrateWrite(projectRoot, options, translator);
+
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-migrate-'));
 
   try {
@@ -3158,8 +3296,9 @@ async function run(argv) {
     return;
   }
 
-  const args = parseArgs(normalizedArgv, {
+  const args = parseCliArgs(normalizedArgv, {
     language: languageArgs.language,
+    legacyParseArgs: parseArgs,
   });
   args.languageResolution = languageResolution;
   args.language = args.languageResolution.language;
@@ -3180,12 +3319,20 @@ async function run(argv) {
     for (const warning of args.languageResolution.warnings || []) {
       process.stderr.write(`${formatLanguageWarningForCli(warning, args.language)}\n`);
     }
+    if (args.legacyAliasCommand) {
+      process.stderr.write(`${formatLegacyNamespaceWarning(args.mode, args.legacyAliasCommand)}\n`);
+    }
   }
 
   if (args.mode === 'analyze') {
-    runAnalyze(args.targetDir, {
+    await runAnalyze(args.targetDir, {
       dryRun: args.dryRun,
+      json: args.json,
       language: args.language,
+      noColor: args.noColor,
+      stderrIsTTY: Boolean(process.stderr.isTTY),
+      stdinIsTTY: Boolean(process.stdin.isTTY),
+      stdoutIsTTY: Boolean(process.stdout.isTTY),
     });
     return;
   }
@@ -3231,11 +3378,17 @@ async function run(argv) {
     return;
   }
 
+  if (args.mode === 'changelog') {
+    runChangelog({ json: args.json });
+    return;
+  }
+
   if (args.mode === 'config') {
     runConfig(process.cwd(), {
       command: args.configCommand,
       global: args.configGlobal,
       json: args.json,
+      language: args.language,
       languageResolution: args.languageResolution,
       section: args.configSection,
       value: args.configValue,
@@ -3570,7 +3723,7 @@ async function run(argv) {
 
     if (args.aiCommand === 'pr') {
       await runAiPr(process.cwd(), {
-        baseBranch: args.aiBaseBranch,
+        baseBranch: args.baseBranchExplicit ? args.aiBaseBranch : '',
         create: args.aiCreate,
         dryRun: args.dryRun,
         input: args.aiInput || undefined,
@@ -3620,7 +3773,9 @@ async function run(argv) {
       language: args.language,
       maxOutput: args.evidenceMaxOutput || undefined,
       output: args.evidenceOutput || undefined,
+      json: args.json,
       subcommand: args.evidenceCommand,
+      target: args.evidenceTarget,
     });
     process.exitCode = result.exitCode;
     return;
@@ -3639,10 +3794,16 @@ async function run(argv) {
   }
 
   if (args.mode === 'migrate') {
-    runMigrate(args.targetDir, {
+    await runMigrate(args.targetDir, {
       dryRun: args.dryRun,
+      force: args.force,
+      json: args.json,
       language: args.language,
+      noColor: args.noColor,
       skipInstall: args.skipInstall,
+      stderrIsTTY: Boolean(process.stderr.isTTY),
+      stdinIsTTY: Boolean(process.stdin.isTTY),
+      stdoutIsTTY: Boolean(process.stdout.isTTY),
     });
     return;
   }
@@ -3680,7 +3841,11 @@ async function run(argv) {
   }
 
   if (args.mode === 'check-pr') {
-    checkPrReadiness(args.targetDir, { language: args.language });
+    checkPrReadiness(args.targetDir, {
+      baseBranch: args.baseBranchExplicit ? args.aiBaseBranch : '',
+      language: args.language,
+      remote: args.aiRemote,
+    });
     return;
   }
 
@@ -3751,11 +3916,12 @@ async function run(argv) {
     }
 
     if (!args.targetDir || args.targetDir === '.') {
-      throw new Error(formatError('missing spec directory. Use: npx create-quiver spec <start|status|validate|close> <spec-dir>'));
+      throw new Error(formatError(createTranslator(args.language).t('spec.error.missing_directory_command')));
     }
 
     if (args.specCommand === 'start') {
       const report = startSpecWorktree(process.cwd(), args.targetDir, {
+        baseBranch: args.baseBranchExplicit ? args.aiBaseBranch : '',
         dryRun: args.dryRun,
       });
       process.stdout.write(formatSpecStartResult(report, { language: args.language }));
@@ -3778,7 +3944,7 @@ async function run(argv) {
 
     if (args.specCommand === 'close') {
       const report = closeSpecWorktree(process.cwd(), args.targetDir, {
-        baseBranch: args.aiBaseBranch,
+        baseBranch: args.baseBranchExplicit ? args.aiBaseBranch : '',
         discard: args.discard,
         dryRun: args.dryRun,
         force: args.force,
@@ -3824,25 +3990,60 @@ async function run(argv) {
   }
 
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-create-'));
+  const translator = createTranslator(args.language);
+  const progress = createCommandProgressUx({
+    json: args.json,
+    noColor: args.noColor,
+    stderrIsTTY: Boolean(process.stderr.isTTY),
+    stdinIsTTY: Boolean(process.stdin.isTTY),
+    stdoutIsTTY: Boolean(process.stdout.isTTY),
+  });
 
   try {
-    ensureDir(targetDir);
-
-    const templateRoot = packTemplate(packageRoot, tempRoot);
+    let templateRoot = '';
+    await runProgress(
+      progress,
+      translator.t('init.progress.preparing_templates'),
+      () => {
+        ensureDir(targetDir);
+        templateRoot = packTemplate(packageRoot, tempRoot);
+        return templateRoot;
+      },
+      translator.t('init.progress.templates_ready'),
+    );
     if (initLayout.profile === 'full') {
-      exportTemplatesToLegacyRoot(templateRoot, targetDir);
-    }
-    runInitDocs(targetDir, initOptions.projectName, {
-      includeTemplates: initOptions.includeTemplates,
-      language: initLanguage.docsLanguage,
-      legacyScripts: initOptions.legacyScripts,
-      profile: initLayout.profile,
-      templateRoot,
-    });
-    const languageWrite = persistInitLanguage(targetDir, { language: initLanguage.configLanguage });
+      await runProgress(
+        progress,
+        translator.t('init.progress.exporting_templates'),
+        () => exportTemplatesToLegacyRoot(templateRoot, targetDir),
+        translator.t('init.progress.templates_exported'),
+      );
+    }
+    let languageWrite = null;
+    await runProgress(
+      progress,
+      translator.t('init.progress.writing_docs'),
+      () => {
+        runInitDocs(targetDir, initOptions.projectName, {
+          includeTemplates: initOptions.includeTemplates,
+          language: initLanguage.docsLanguage,
+          legacyScripts: initOptions.legacyScripts,
+          profile: initLayout.profile,
+          templateRoot,
+        });
+        languageWrite = persistInitLanguage(targetDir, { language: initLanguage.configLanguage });
+        return languageWrite;
+      },
+      translator.t('init.progress.docs_written'),
+    );
 
     if (!args.skipInstall) {
-      const installResult = installSelfAsDevDep(targetDir, CLI_VERSION);
+      const installResult = await runProgress(
+        progress,
+        translator.t('init.progress.installing_package'),
+        () => installSelfAsDevDep(targetDir, CLI_VERSION),
+        translator.t('init.progress.install_checked'),
+      );
       if (installResult === 'installed') {
         console.log(`Added create-quiver@${CLI_VERSION} as dev dependency`);
       } else if (installResult === 'failed') {
@@ -3850,7 +4051,6 @@ async function run(argv) {
       }
     }
 
-    const translator = createTranslator(args.language);
     console.log(translator.t('init.installed', { path: targetDir }));
     if (languageWrite) {
       console.log(translator.t('init.language.saved', { language: languageWrite.language }));