create-quiver 0.7.0 → 0.9.0

package/src/create-quiver/index.js

@@ -2,12 +2,17 @@ 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 { initializeProjectDocs } = require('./lib/init-docs');
+const { runGraph } = require('./commands/graph');
+const { runNext } = require('./commands/next');
+const { runPlan } = require('./commands/plan');
+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 {
+  hasQuiverInitializationEvidence,
   readState,
   updateStateForAnalyze,
   updateStateForMigrate,
@@ -23,11 +28,16 @@ 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
@@ -35,6 +45,15 @@ function printUsage() {
 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
 
@@ -42,11 +61,20 @@ Examples:
   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 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
@@ -68,10 +96,19 @@ function parseArgs(argv) {
     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];
-  const commandModes = new Set(['doctor', 'analyze', 'migrate', 'start-slice', 'check-slice', 'check-pr', 'cleanup-slice', 'check-scope', 'refresh-active-slices']);
+  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();
@@ -84,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 = [];
@@ -101,6 +144,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--skip-install') {
+      result.skipInstall = true;
+      continue;
+    }
+
     if (arg === '--doctor') {
       result.mode = 'doctor';
       continue;
@@ -111,6 +159,16 @@ 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;
@@ -141,6 +199,67 @@ function parseArgs(argv) {
       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) {
@@ -183,6 +302,10 @@ 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'));
@@ -1022,6 +1145,10 @@ function runMigrate(targetDir) {
     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, '../..');
@@ -1038,6 +1165,15 @@ function runMigrate(targetDir) {
     });
     updateStateForMigrate(projectRoot, projectName, CLI_VERSION);
 
+    if (!args.skipInstall) {
+      const installResult = installSelfAsDevDep(projectRoot, CLI_VERSION);
+      if (installResult === 'installed') {
+        console.log(`Added create-quiver@${CLI_VERSION} as dev dependency`);
+      } else if (installResult === 'failed') {
+        console.warn(`Warning: could not install create-quiver automatically. Run: npm install -D create-quiver@${CLI_VERSION}`);
+      }
+    }
+
     console.log(`Quiver migration completed for ${projectRoot}`);
     console.log('Missing workflow files were restored without overwriting existing project files.');
   } finally {
@@ -1052,6 +1188,10 @@ function runDoctor(targetDir) {
     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}`));
@@ -1144,10 +1284,11 @@ function runDoctor(targetDir) {
   if (!hasQuiverState) {
     console.log('- Run migration first: npx create-quiver migrate');
   } else if (!hasScanArtifacts) {
-    console.log('- Analyze the project first: npx create-quiver analyze');
+  console.log('- Analyze the project first: npx create-quiver analyze');
   } else {
     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`);
@@ -1177,6 +1318,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;
@@ -1205,6 +1377,25 @@ async function run(argv) {
     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,
@@ -1238,6 +1429,15 @@ async function run(argv) {
     copyTemplate(templateRoot, targetDir);
     runInitDocs(targetDir, projectName);
 
+    if (!args.skipInstall) {
+      const installResult = installSelfAsDevDep(targetDir, CLI_VERSION);
+      if (installResult === 'installed') {
+        console.log(`Added create-quiver@${CLI_VERSION} as dev dependency`);
+      } else if (installResult === 'failed') {
+        console.warn(`Warning: could not install create-quiver automatically. Run: npm install -D create-quiver@${CLI_VERSION}`);
+      }
+    }
+
     console.log(`Installed Quiver into ${targetDir}`);
     printInitNextSteps(targetDir, projectName);
   } finally {

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

@@ -0,0 +1,104 @@
+const fs = require('fs');
+const path = require('path');
+
+const REQUIRED_HEADINGS = [
+  '## Background',
+  '## What you will change',
+  '## Validation checklist',
+  '## Out of scope',
+  '## Expected deliverable',
+  '## Constraints',
+];
+
+const HANDOFF_TEMPLATE_PATH = path.resolve(__dirname, '..', '..', '..', 'specs', '[project-name]', 'HANDOFF.md.template');
+
+function normalizePosixPath(filePath, pathLib = path) {
+  return filePath.split(pathLib.sep).join('/');
+}
+
+function resolveHandoffPath(repoRoot, handoffInput, pathLib = path) {
+  const absolutePath = pathLib.resolve(repoRoot, handoffInput);
+  const relativePath = normalizePosixPath(pathLib.relative(repoRoot, absolutePath), pathLib);
+
+  if (relativePath.startsWith('..') || pathLib.isAbsolute(relativePath)) {
+    throw new Error(`create-quiver: handoff must live at specs/<spec-slug>/HANDOFF.md (got ${normalizePosixPath(handoffInput, pathLib)})`);
+  }
+
+  const match = relativePath.match(/^specs\/([^/]+)\/HANDOFF\.md$/);
+  if (!match) {
+    throw new Error(`create-quiver: handoff must live at specs/<spec-slug>/HANDOFF.md (got ${relativePath})`);
+  }
+
+  return {
+    absolutePath,
+    relativePath,
+    specSlug: match[1],
+  };
+}
+
+function readHandoffSections(text) {
+  return String(text || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('## '))
+    .map((line) => line.replace(/\s+$/, ''));
+}
+
+function validateHandoffSections(text) {
+  const sections = new Set(readHandoffSections(text));
+  return REQUIRED_HEADINGS.filter((heading) => !sections.has(heading));
+}
+
+function checkHandoff(handoffInput, repoRoot = process.cwd()) {
+  const resolved = resolveHandoffPath(repoRoot, handoffInput);
+
+  if (!fs.existsSync(resolved.absolutePath)) {
+    throw new Error(`create-quiver: missing handoff file: ${resolved.relativePath}`);
+  }
+
+  const text = fs.readFileSync(resolved.absolutePath, 'utf8');
+  const missingSections = validateHandoffSections(text);
+  if (missingSections.length > 0) {
+    throw new Error(`create-quiver: handoff is missing required sections: ${missingSections.join(', ')}`);
+  }
+
+  return resolved;
+}
+
+function scaffoldHandoff(specSlug, repoRoot = process.cwd()) {
+  const trimmedSlug = String(specSlug || '').trim();
+  if (!trimmedSlug) {
+    throw new Error('create-quiver: missing handoff slug. Use: npx create-quiver new-handoff <spec-slug>');
+  }
+
+  if (!fs.existsSync(HANDOFF_TEMPLATE_PATH)) {
+    throw new Error('create-quiver: missing handoff template at specs/[project-name]/HANDOFF.md.template');
+  }
+
+  const resolved = resolveHandoffPath(repoRoot, path.join('specs', trimmedSlug, 'HANDOFF.md'));
+  if (fs.existsSync(resolved.absolutePath)) {
+    throw new Error(`create-quiver: handoff already exists at ${resolved.relativePath}`);
+  }
+
+  const templateText = fs.readFileSync(HANDOFF_TEMPLATE_PATH, 'utf8');
+  const projectName = trimmedSlug.replace(/-/g, ' ');
+  const currentDate = new Date().toISOString().slice(0, 10);
+  const renderedText = templateText
+    .replace(/{{PROJECT_NAME}}/g, projectName)
+    .replace(/{{PROJECT_SLUG}}/g, trimmedSlug)
+    .replace(/{{FECHA}}/g, currentDate);
+
+  fs.mkdirSync(path.dirname(resolved.absolutePath), { recursive: true });
+  fs.writeFileSync(resolved.absolutePath, renderedText);
+
+  return checkHandoff(resolved.relativePath, repoRoot);
+}
+
+module.exports = {
+  REQUIRED_HEADINGS,
+  checkHandoff,
+  readHandoffSections,
+  scaffoldHandoff,
+  resolveHandoffPath,
+  validateHandoffSections,
+};

package/src/create-quiver/lib/init-docs.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const { execSync } = require('child_process');
 const { writeState } = require('./state');
 
 function ensureDir(dirPath) {
@@ -61,6 +62,9 @@ function renderTemplate(text, replacements) {
     .replace(/{{PRIMARY_DEV}}/g, replacements.primaryDev || 'not defined')
     .replace(/{{PRIMARY_TEST}}/g, replacements.primaryTest || 'not defined')
     .replace(/{{ANALYZE_COMMAND}}/g, replacements.analyzeCommand || 'npx create-quiver analyze')
+    .replace(/{{PLAN_COMMAND}}/g, replacements.planCommand || 'npx create-quiver plan')
+    .replace(/{{GRAPH_COMMAND}}/g, replacements.graphCommand || 'npx create-quiver graph')
+    .replace(/{{NEXT_COMMAND}}/g, replacements.nextCommand || 'npx create-quiver next')
     .replace(/{{DOCTOR_COMMAND}}/g, replacements.doctorCommand || 'npx create-quiver doctor')
     .replace(/{{START_SLICE_COMMAND}}/g, replacements.startSliceCommand || 'npx create-quiver start-slice <slice.json>')
     .replace(/{{CHECK_SLICE_COMMAND}}/g, replacements.checkSliceCommand || 'npx create-quiver check-slice <slice.json>')
@@ -227,12 +231,22 @@ function buildReadme(projectName, projectSlug) {
 
 ## Quick Start
 
-Run Quiver from this project root. Do not install it globally.
+  Run Quiver from this project root. Do not install it globally.
 
 \`\`\`bash
 npm install
-npx create-quiver analyze
-npx create-quiver doctor
+{{ANALYZE_COMMAND}}
+{{PLAN_COMMAND}}
+{{GRAPH_COMMAND}}
+{{DOCTOR_COMMAND}}
+{{NEXT_COMMAND}}
+\`\`\`
+
+Exportable graph formats are available when you need a PR-ready Mermaid block or Graphviz source:
+
+\`\`\`bash
+{{GRAPH_COMMAND}} --format mermaid
+{{GRAPH_COMMAND}} --format dot
 \`\`\`
 
 If this project needs a pinned Quiver version, install it as a devDependency:
@@ -251,17 +265,28 @@ The generated project includes \`quiver:*\` npm scripts that call the Node CLI a
 
 \`\`\`bash
 npm run quiver:analyze
+npm run quiver:plan
+npm run quiver:graph
+npm run quiver:next
 npm run quiver:doctor
 npm run quiver:migrate
 npm run quiver:start-slice -- specs/${projectSlug}/slices/slice-01/slice.json
 npm run quiver:check-slice -- specs/${projectSlug}/slices/slice-01/slice.json
 npm run quiver:check-pr -- specs/${projectSlug}/slices/slice-01/slice.json
+npm run quiver:check-handoff -- specs/${projectSlug}/HANDOFF.md
 npm run quiver:cleanup-slice -- specs/${projectSlug}/slices/slice-01/slice.json
 npm run quiver:check-scope -- specs/${projectSlug}/slices/slice-01/slice.json
 npm run quiver:refresh-active-slices
 \`\`\`
 
+The \`quiver:graph\` script prints the tree view by default; use \`npx create-quiver graph --format mermaid\` for PR-ready Markdown and \`--format dot\` when you want Graphviz source.
+The \`quiver:next\` script points to the next ready slice and can auto-start it behind a confirmation prompt.
+Use \`npx create-quiver next --all-ready\` when you want the full ready level instead of a single suggestion.
 The legacy Bash wrappers remain in \`tools/scripts/\` for compatibility, but new project-level automation should prefer the \`quiver:*\` scripts and the direct \`npx create-quiver ...\` commands below.
+\`npm run quiver:migrate\` is only for projects that were already initialized by Quiver.
+\`npm run check-handoff -- specs/${projectSlug}/HANDOFF.md\` is available as a legacy-friendly alias for the handoff validator.
+If a new bounded transfer is needed, scaffold \`specs/${projectSlug}/HANDOFF.md\` with \`npx create-quiver new-handoff ${projectSlug}\` and validate it with \`npx create-quiver check-handoff specs/${projectSlug}/HANDOFF.md\`.
+For exceptional context transfers between agents or phases, a dedicated \`HANDOFF.md\` can live alongside the usual spec and docs files.
 
 ## Cross-Platform Support
 
@@ -274,8 +299,19 @@ If the project already existed before this Quiver version, upgrade it from the p
 \`\`\`bash
 cd /path/to/your-project
 npx create-quiver migrate
-npx create-quiver analyze
-npx create-quiver doctor
+{{ANALYZE_COMMAND}}
+{{PLAN_COMMAND}}
+{{GRAPH_COMMAND}}
+{{NEXT_COMMAND}}
+{{DOCTOR_COMMAND}}
+\`\`\`
+
+Use \`{{GRAPH_COMMAND}} --format mermaid\` for GitHub-friendly graph embeds or \`{{GRAPH_COMMAND}} --format dot\` for Graphviz pipelines.
+
+If the project never ran Quiver initialization before, do not use \`migrate\` as bootstrap. Run:
+
+\`\`\`bash
+npx create-quiver --name "Project Name"
 \`\`\`
 
 If your team prefers a pinned local dependency, update the package first and then run the same flow:
@@ -283,10 +319,15 @@ If your team prefers a pinned local dependency, update the package first and the
 \`\`\`bash
 npm install --save-dev create-quiver@latest
 npx create-quiver migrate
-npx create-quiver analyze
-npx create-quiver doctor
+{{ANALYZE_COMMAND}}
+{{PLAN_COMMAND}}
+{{GRAPH_COMMAND}}
+{{NEXT_COMMAND}}
+{{DOCTOR_COMMAND}}
 \`\`\`
 
+The tree output remains the default, but Mermaid and DOT are available on demand for exported docs and slide decks.
+
 ## AI Context Onboarding
 
 Read \`AGENTS.md\` first, then open \`docs/AI_ONBOARDING_PROMPT.md\` after analysis.
@@ -300,6 +341,7 @@ Prepare the project context docs and report assumptions, risks, and files change
 \`\`\`
 
 Review the AI changes to docs/AI_CONTEXT.md, docs/CONTEXTO.md, docs/STATUS.md, and specs/${projectSlug}/SPEC.md before starting implementation work. Use \`docs/PROJECT_MAP.md\` for stack and command details.
+If the work was explicitly transferred through a handoff artifact, read \`specs/${projectSlug}/HANDOFF.md\` before implementation.
 
 ## Decision Log
 
@@ -309,15 +351,21 @@ Record durable decisions in \`docs/DECISIONS.md\` so future AI agents do not re-
 
 1. Review or refine specs/${projectSlug}/SPEC.md.
 2. Create the first slice from specs/${projectSlug}/slices/slice-template/slice.json.
-3. Start work with \`npx create-quiver start-slice <slice.json>\` or \`npm run quiver:start-slice -- <slice.json>\`.
-4. Make one commit per slice.
-5. Open one PR per spec.
+3. Review the plan with \`{{PLAN_COMMAND}}\` or \`npm run quiver:plan\`.
+4. Inspect parallel lots with \`{{GRAPH_COMMAND}}\` or \`npm run quiver:graph\`.
+5. Check the next ready slice with \`{{NEXT_COMMAND}}\` or \`npm run quiver:next\`.
+6. Start work with \`{{START_SLICE_COMMAND}}\` or \`npm run quiver:start-slice -- <slice.json>\`.
+7. Make one commit per slice.
+8. Open one PR per spec.
 
 ## Verification Checklist
 
 - [ ] npm install completes
-- [ ] npx create-quiver analyze completes
-- [ ] npx create-quiver doctor completes
+- [ ] {{ANALYZE_COMMAND}} completes
+- [ ] {{PLAN_COMMAND}} completes
+- [ ] {{GRAPH_COMMAND}} completes
+- [ ] {{NEXT_COMMAND}} completes
+- [ ] {{DOCTOR_COMMAND}} completes
 - [ ] AI agent executed docs/AI_ONBOARDING_PROMPT.md
 - [ ] Context docs were reviewed before the first slice
 
@@ -326,6 +374,9 @@ Record durable decisions in \`docs/DECISIONS.md\` so future AI agents do not re-
 - [AI Context](./docs/AI_CONTEXT.md) - Contexto resumido para IA
 - [Decision Log](./docs/DECISIONS.md) - Decisiones durables del proyecto
 - [AI Onboarding Prompt](./docs/AI_ONBOARDING_PROMPT.md) - Handoff exacto para agentes después del análisis
+- [Handoff](./specs/${projectSlug}/HANDOFF.md) - Transferencia excepcional entre agentes o fases
+- [Check Handoff](./docs/WORKFLOW.md) - Valida el handoff con \`npx create-quiver check-handoff\`
+- [Commands](./docs/COMMANDS.md) - Tabla canónica de comandos de orquestación
 - [Contexto](./docs/CONTEXTO.md) - Qué es ${projectName}
 - [Workflow](./docs/WORKFLOW.md) - Cómo implementar
 - [Support Matrix](./docs/SUPPORT_MATRIX.md) - Qué entornos están soportados
@@ -382,6 +433,7 @@ function initializeProjectDocs(options) {
   });
   const templateCopies = [
     ['docs/INDEX.md.template', 'docs/INDEX.md'],
+    ['docs/COMMANDS.md.template', 'docs/COMMANDS.md'],
     ['docs/DECISIONS.md.template', 'docs/DECISIONS.md'],
     ['docs/AI_CONTEXT.md.template', 'docs/AI_CONTEXT.md', frontMatterFor('Agent-facing project context pack', 'onboarding, implementation, review')],
     ['docs/AI_ONBOARDING_PROMPT.md.template', 'docs/AI_ONBOARDING_PROMPT.md', frontMatterFor('AI onboarding handoff prompt', 'onboarding after analysis')],
@@ -398,6 +450,7 @@ function initializeProjectDocs(options) {
     ['docs/TESTING_GUIDE_FOR_AI.md.template', 'docs/TESTING_GUIDE_FOR_AI.md'],
     ['docs/ai/LESSONS.md.template', 'docs/ai/LESSONS.md', frontMatterFor('Slice learnings log', 'after slice completion')],
     ['specs/[project-name]/SPEC.md.template', `specs/${replacements.projectSlug}/SPEC.md`],
+    ['specs/[project-name]/HANDOFF.md.template', `specs/${replacements.projectSlug}/HANDOFF.md`],
     ['specs/[project-name]/STATUS.md.template', `specs/${replacements.projectSlug}/STATUS.md`],
     ['specs/[project-name]/EVIDENCE_REPORT.md.template', `specs/${replacements.projectSlug}/EVIDENCE_REPORT.md`],
     ['specs/[project-name]/slices/slice-template/slice.json', `specs/${replacements.projectSlug}/slices/slice-template/slice.json`],
@@ -479,6 +532,9 @@ function initializeProjectDocs(options) {
     primaryDev: packageScripts.dev || packageScripts.start || 'not defined',
     primaryTest: packageScripts.test || 'not defined',
     analyzeCommand: 'npx create-quiver analyze',
+    planCommand: 'npx create-quiver plan',
+    graphCommand: 'npx create-quiver graph',
+    nextCommand: 'npx create-quiver next',
     doctorCommand: 'npx create-quiver doctor',
     startSliceCommand: 'npx create-quiver start-slice <slice.json>',
     checkSliceCommand: 'npx create-quiver check-slice <slice.json>',
@@ -492,6 +548,9 @@ function initializeProjectDocs(options) {
     ['docs/QUICK.md.template', 'docs/ai/QUICK.md'],
     ['docs/STANDARD.md.template', 'docs/ai/STANDARD.md'],
     ['docs/DEEP.md.template', 'docs/ai/DEEP.md'],
+    ['docs/examples/plan.md.template', 'docs/examples/plan.md'],
+    ['docs/examples/graph.md.template', 'docs/examples/graph.md'],
+    ['docs/examples/next.md.template', 'docs/examples/next.md'],
   ];
 
   for (const [source, destination] of tierCopies) {
@@ -597,7 +656,7 @@ function initializeProjectDocs(options) {
 
   const readmePath = path.join(projectRoot, 'README.md');
   if (!fs.existsSync(readmePath)) {
-    fs.writeFileSync(readmePath, `${buildReadme(projectName, replacements.projectSlug)}\n`);
+    fs.writeFileSync(readmePath, `${renderTemplate(buildReadme(projectName, replacements.projectSlug), replacements)}\n`);
     operations.push({ source: 'README.md template', destination: 'README.md', result: 'created' });
   } else {
     operations.push({ source: 'README.md template', destination: 'README.md', result: 'skipped' });
@@ -609,8 +668,44 @@ function initializeProjectDocs(options) {
   };
 }
 
+function detectPackageManager(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, 'bun.lockb'))) return 'bun';
+  if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+function installSelfAsDevDep(projectRoot, version) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    return 'skipped-no-package-json';
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  if (pkg.devDependencies && pkg.devDependencies['create-quiver']) {
+    return 'skipped-already-present';
+  }
+
+  const pm = detectPackageManager(projectRoot);
+  const commands = {
+    npm: `npm install -D create-quiver@${version}`,
+    yarn: `yarn add -D create-quiver@${version}`,
+    pnpm: `pnpm add -D create-quiver@${version}`,
+    bun: `bun add -d create-quiver@${version}`,
+  };
+
+  try {
+    execSync(commands[pm], { cwd: projectRoot, stdio: 'inherit' });
+    return 'installed';
+  } catch {
+    return 'failed';
+  }
+}
+
 module.exports = {
   initializeProjectDocs,
   writeFrontMatter,
   toProjectSlug,
+  detectPackageManager,
+  installSelfAsDevDep,
 };