create-quiver 0.9.0 → 0.10.0

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

@@ -1,7 +1,31 @@
 const fs = require('fs');
 const path = require('path');
+const { readAllSlices } = require('./slice-graph');
+const { hasGeneratedProjectSpec, hasInitializedStateMetadata, readState } = require('./state');
 const { worktreeList } = require('./git');
 
+const NEW_LAYOUT_REQUIRED_PATHS = [
+  'README.md',
+  'AGENTS.md',
+  'package.json',
+  'docs/AI_CONTEXT.md',
+  'docs/AI_ONBOARDING_PROMPT.md',
+  'docs/COMMANDS.md',
+  'docs/WORKFLOW.md',
+  '.quiver/state.json',
+  '.quiver/config.json',
+  '.quiver/.gitignore',
+];
+
+const LEGACY_LAYOUT_PROBES = [
+  'docs-template/',
+  'tools/scripts/start-slice.sh',
+  'tools/scripts/check-slice-readiness.sh',
+  'tools/scripts/check-pr-readiness.sh',
+  '.github/pull_request_template.md',
+  'docs/PROJECT_SCAN.json',
+];
+
 function readTextIfExists(filePath) {
   if (!fs.existsSync(filePath)) {
     return null;
@@ -30,6 +54,18 @@ function normalizeRelativePath(root, absolutePath) {
   return path.relative(root, absolutePath).split(path.sep).join('/');
 }
 
+function hasPath(projectRoot, relativePath) {
+  return fs.existsSync(path.join(projectRoot, relativePath));
+}
+
+function collectPresentPaths(projectRoot, relativePaths) {
+  return relativePaths.filter((relativePath) => hasPath(projectRoot, relativePath));
+}
+
+function collectMissingPaths(projectRoot, relativePaths) {
+  return relativePaths.filter((relativePath) => !hasPath(projectRoot, relativePath));
+}
+
 function collectAiMarkdownFiles(projectRoot) {
   const aiDir = path.join(projectRoot, 'docs', 'ai');
   if (!fs.existsSync(aiDir)) {
@@ -174,6 +210,82 @@ function countStackInfoLeaks(projectRoot) {
   return leaks;
 }
 
+function collectLayoutReport(projectRoot) {
+  const hasStateMetadata = hasInitializedStateMetadata(readState(projectRoot));
+  const realSlices = readAllSlices(projectRoot);
+  const specSlugs = Array.from(new Set(realSlices.map((slice) => slice.specSlug))).sort((left, right) => left.localeCompare(right));
+  const newLayoutFiles = collectPresentPaths(projectRoot, NEW_LAYOUT_REQUIRED_PATHS);
+  const missingNewLayoutFiles = collectMissingPaths(projectRoot, NEW_LAYOUT_REQUIRED_PATHS);
+  const legacySignals = collectPresentPaths(projectRoot, LEGACY_LAYOUT_PROBES);
+  const hasLegacyProjectSpec = hasGeneratedProjectSpec(projectRoot);
+
+  if (hasLegacyProjectSpec) {
+    legacySignals.push('specs/<project-slug>/SPEC.md');
+  }
+
+  const hasNewLayout = missingNewLayoutFiles.length === 0;
+  const hasLegacyLayout = legacySignals.length > 0;
+
+  let layout = 'incomplete';
+  if (hasNewLayout && hasLegacyLayout) {
+    layout = 'hybrid';
+  } else if (hasNewLayout) {
+    layout = 'new';
+  } else if (hasLegacyLayout) {
+    layout = 'legacy';
+  }
+
+  const recommendations = [];
+
+  if (layout === 'new') {
+    if (specSlugs.length === 0) {
+      recommendations.push('No specs yet. That is valid after the AI-first init flow.');
+    } else {
+      recommendations.push(`Specs found: ${specSlugs.join(', ')}.`);
+    }
+
+    if (!hasPath(projectRoot, 'docs/PROJECT_MAP.md')) {
+      recommendations.push('Run `npx create-quiver analyze` to generate docs/PROJECT_MAP.md when you want the visible project map.');
+    }
+  } else if (layout === 'legacy') {
+    recommendations.push('Legacy layout detected. Run `npx create-quiver migrate` to add the modern .quiver/ contract and AI-first docs.');
+  } else if (layout === 'hybrid') {
+    recommendations.push('Hybrid layout detected. Keep the new .quiver/ contract as the source of truth and plan cleanup of legacy roots.');
+    recommendations.push('Review any remaining docs-template/, tools/scripts/, or docs/PROJECT_SCAN.json paths and migrate them only if they are still needed.');
+  } else {
+    recommendations.push('Incomplete layout detected. Restore the missing AI-first contract files before relying on this project for onboarding.');
+    if (missingNewLayoutFiles.length > 0) {
+      recommendations.push(`Missing files: ${missingNewLayoutFiles.join(', ')}.`);
+    }
+    if (!hasStateMetadata && !hasLegacyLayout) {
+      recommendations.push('Run `npx create-quiver --name "Project Name"` or `npx create-quiver init` to create the Quiver contract first.');
+    }
+  }
+
+  return {
+    hasLegacyLayout,
+    hasNewLayout,
+    hasStateMetadata,
+    layout,
+    legacySignals,
+    missingNewLayoutFiles,
+    newLayoutFiles,
+    recommendations,
+    realSlices,
+    specSlugs,
+  };
+}
+
+function collectDoctorReport(projectRoot) {
+  const layout = collectLayoutReport(projectRoot);
+  const warnings = collectDoctorWarnings(projectRoot);
+
+  return {
+    ...layout,
+    warnings,
+  };
+}
+
 function collectDoctorWarnings(projectRoot) {
   const warnings = [];
 
@@ -208,5 +320,7 @@ function collectDoctorWarnings(projectRoot) {
 }
 
 module.exports = {
+  collectDoctorReport,
   collectDoctorWarnings,
+  collectLayoutReport,
 };

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

@@ -101,6 +101,23 @@ function statusPorcelain(repoRoot) {
   return tryGit(['status', '--porcelain'], repoRoot);
 }
 
+function remoteList(repoRoot) {
+  const output = tryGit(['remote'], repoRoot);
+  return output ? output.split('\n').map((line) => line.trim()).filter(Boolean) : [];
+}
+
+function hasRemote(repoRoot, remoteName = 'origin') {
+  return remoteList(repoRoot).includes(remoteName);
+}
+
+function isCleanWorktree(repoRoot) {
+  return statusPorcelain(repoRoot) === '';
+}
+
+function isDetachedHead(repoRoot) {
+  return currentBranch(repoRoot) === '';
+}
+
 function revListCount(repoRoot, range) {
   const output = tryGit(['rev-list', '--count', range], repoRoot);
   return Number(output || '0');
@@ -143,7 +160,11 @@ module.exports = {
   hasRemoteBranch,
   lsRemoteHeads,
   mergeBaseIsAncestor,
+  hasRemote,
+  isCleanWorktree,
+  isDetachedHead,
   revListCount,
+  remoteList,
   runGit,
   statusPorcelain,
   tryGit,

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

@@ -1,6 +1,12 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
+const {
+  buildQuiverConfig,
+  buildQuiverInternalGitignore,
+  quiverInternalPaths,
+  resolveInitPackageScripts,
+} = require('./init-layout');
 const { writeState } = require('./state');
 
 function ensureDir(dirPath) {
@@ -199,7 +205,7 @@ function writeFrontMatter(filePath, fields) {
   return nextContent;
 }
 
-function mergePackageJson(projectRoot, templateRoot, skipIfExists) {
+function mergePackageJson(projectRoot, templateRoot, options = {}) {
   const packageTemplate = path.join(templateRoot, 'package.template.json');
   const packageJsonPath = path.join(projectRoot, 'package.json');
 
@@ -207,8 +213,13 @@ function mergePackageJson(projectRoot, templateRoot, skipIfExists) {
     return 'missing';
   }
 
+  const profile = options.profile || 'default';
+  const scripts = resolveInitPackageScripts(profile, { legacyScripts: options.legacyScripts === true });
+
   if (!fs.existsSync(packageJsonPath)) {
-    fs.copyFileSync(packageTemplate, packageJsonPath);
+    const template = JSON.parse(fs.readFileSync(packageTemplate, 'utf8'));
+    template.scripts = scripts;
+    fs.writeFileSync(packageJsonPath, `${JSON.stringify(template, null, 2)}\n`);
     return 'created';
   }
 
@@ -217,14 +228,125 @@ function mergePackageJson(projectRoot, templateRoot, skipIfExists) {
 
   existing.scripts = {
     ...(existing.scripts || {}),
-    ...(template.scripts || {}),
+    ...scripts,
   };
 
   fs.writeFileSync(packageJsonPath, `${JSON.stringify(existing, null, 2)}\n`);
-  return skipIfExists ? 'merged' : 'updated';
+  return options.migrateMode ? 'merged' : 'updated';
 }
 
-function buildReadme(projectName, projectSlug) {
+function buildReadme(projectName, projectSlug, profile = 'default') {
+  if (profile === 'minimal') {
+    return `# ${projectName}
+
+[Descripción breve del proyecto]
+
+## Quick Start
+
+Run Quiver from this project root. Do not install it globally.
+
+\`\`\`bash
+npm install
+npx create-quiver analyze
+npx create-quiver plan
+npx create-quiver graph
+npx create-quiver doctor
+npx create-quiver next
+\`\`\`
+
+## AI Workflow
+
+Use \`AGENTS.md\` first, then \`docs/AI_CONTEXT.md\` and \`docs/AI_ONBOARDING_PROMPT.md\` for the working contract.
+
+\`\`\`bash
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:plan -- --phase technical-plan --input acceptance-approved.md --dry-run
+npm run quiver:ai:plan -- --phase spec --input technical-plan-approved.md --dry-run
+\`\`\`
+
+When a real spec exists, execute one approved slice at a time:
+
+\`\`\`bash
+npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+\`\`\`
+
+## Documentation
+
+- [AI Context](./docs/AI_CONTEXT.md)
+- [AI Onboarding Prompt](./docs/AI_ONBOARDING_PROMPT.md)
+- [Commands](./docs/COMMANDS.md)
+- [Workflow](./docs/WORKFLOW.md)
+`;
+  }
+
+  if (profile !== 'full') {
+    return `# ${projectName}
+
+[Descripción breve del proyecto]
+
+## Quick Start
+
+Run Quiver from this project root. Do not install it globally.
+
+\`\`\`bash
+npm install
+npx create-quiver analyze
+npx create-quiver plan
+npx create-quiver graph
+npx create-quiver doctor
+npx create-quiver next
+\`\`\`
+
+After \`analyze\`, use \`docs/PROJECT_MAP.md\` for the detected stack, package manager, and command surface.
+
+## AI-First Workflow
+
+Quiver keeps the visible contract small: start with \`README.md\`, \`AGENTS.md\`, and \`docs/\`. Specs and slices should be created only after a real requirement and an approved technical plan.
+
+Use dry-runs before spending model tokens:
+
+\`\`\`bash
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:plan -- --phase technical-plan --input acceptance-approved.md --dry-run
+npm run quiver:ai:plan -- --phase spec --input technical-plan-approved.md --dry-run
+\`\`\`
+
+When a real spec exists, execute one approved slice at a time:
+
+\`\`\`bash
+npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+\`\`\`
+
+## Project NPM Scripts
+
+The generated project includes \`quiver:*\` npm scripts that call the Node CLI:
+
+\`\`\`bash
+npm run quiver:analyze
+npm run quiver:plan
+npm run quiver:graph
+npm run quiver:next
+npm run quiver:doctor
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+\`\`\`
+
+## Documentation
+
+- [Agents](./AGENTS.md)
+- [AI Context](./docs/AI_CONTEXT.md)
+- [AI Onboarding Prompt](./docs/AI_ONBOARDING_PROMPT.md)
+- [Commands](./docs/COMMANDS.md)
+- [Workflow](./docs/WORKFLOW.md)
+- [GitFlow PR Guide](./docs/GITFLOW_PR_GUIDE.md)
+- [Support Matrix](./docs/SUPPORT_MATRIX.md)
+- [Troubleshooting](./docs/TROUBLESHOOTING.md)
+`;
+  }
+
   return `# ${projectName}
 
 [Descripción breve del proyecto]
@@ -259,6 +381,23 @@ If you need to target another directory from outside the project, pass \`--dir\`
 
 After you run \`analyze\`, open \`docs/PROJECT_MAP.md\` for the detected stack, package manager, and command surface.
 
+## AI-First Workflow
+
+Quiver is designed for an AI-first workflow: a planner agent reads the project context and prepares acceptance criteria, technical plans, specs, slices, and PR notes; executor agents then work one approved slice at a time with minimal context.
+
+Start with dry-runs so you can inspect the provider, role, context pack, and invocation before spending model tokens:
+
+\`\`\`bash
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:plan -- --phase technical-plan --input acceptance-approved.md --dry-run
+npm run quiver:ai:plan -- --phase spec --input technical-plan-approved.md --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run
+npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+\`\`\`
+
+Remove \`--dry-run\` only after the phase output is approved and the local provider CLI is ready.
+
 ## Project NPM Scripts
 
 The generated project includes \`quiver:*\` npm scripts that call the Node CLI and are the preferred repeatable workflow:
@@ -269,6 +408,11 @@ npm run quiver:plan
 npm run quiver:graph
 npm run quiver:next
 npm run quiver:doctor
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/${projectSlug}/slices/slice-01/slice.json --dry-run
+npm run quiver:ai:doctor -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 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
@@ -281,6 +425,7 @@ 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.
+The \`quiver:ai:*\` scripts standardize planner/executor AI flows. Use dry-run first: onboarding and planning dry-runs do not require provider auth, while \`quiver:ai:pr -- --dry-run\` validates \`gh\`, GitFlow docs, branch/worktree state, and SSH inputs without creating a PR.
 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.
@@ -311,7 +456,7 @@ Use \`{{GRAPH_COMMAND}} --format mermaid\` for GitHub-friendly graph embeds or \
 If the project never ran Quiver initialization before, do not use \`migrate\` as bootstrap. Run:
 
 \`\`\`bash
-npx create-quiver --name "Project Name"
+npx create-quiver init --name "Project Name"
 \`\`\`
 
 If your team prefers a pinned local dependency, update the package first and then run the same flow:
@@ -335,9 +480,17 @@ Read \`AGENTS.md\` first, then open \`docs/AI_ONBOARDING_PROMPT.md\` after analy
 After analysis and doctor validation, open your AI agent in this project and run:
 
 \`\`\`text
-Read docs/AI_ONBOARDING_PROMPT.md and execute it.
-Do not modify product code unless I explicitly authorize it.
-Prepare the project context docs and report assumptions, risks, and files changed.
+Lee \`docs/AI_ONBOARDING_PROMPT.md\` y ejecútalo como fuente principal de verdad para incorporarte a este repositorio.
+
+Actúa como asistente de onboarding de IA. Prepara el contexto del proyecto para trabajar de forma segura con el workflow documentado, specs y slices.
+
+Usa el rol planner para onboarding, criterios de aceptación, plan técnico y generación de specs/slices. Usa el rol executor solo cuando exista un slice aprobado y debas ejecutar su handoff con contexto mínimo.
+
+No modifiques código de producto salvo autorización explícita. Puedes crear o actualizar documentación de contexto si el onboarding lo requiere.
+
+Usa solo la documentación del repositorio como fuente de verdad. Si encuentras información faltante, ambigua o contradictoria, documenta el supuesto, el riesgo y continúa por el camino más seguro.
+
+Responde en español y finaliza con un reporte breve de archivos leídos, archivos modificados, estado del código de producto, supuestos, riesgos y próximos pasos.
 \`\`\`
 
 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.
@@ -349,6 +502,8 @@ Record durable decisions in \`docs/DECISIONS.md\` so future AI agents do not re-
 
 ## First Slice Workflow
 
+Use this section only for projects generated with the full compatibility layout. In the default AI-first layout, create real specs and slices with \`npx create-quiver ai plan --phase spec\` after acceptance criteria and the technical plan are approved.
+
 1. Review or refine specs/${projectSlug}/SPEC.md.
 2. Create the first slice from specs/${projectSlug}/slices/slice-template/slice.json.
 3. Review the plan with \`{{PLAN_COMMAND}}\` or \`npm run quiver:plan\`.
@@ -391,10 +546,15 @@ function initializeProjectDocs(options) {
     projectRoot,
     projectName,
     cliVersion,
+    includeTemplates = false,
+    legacyScripts = false,
     migrateMode = false,
+    profile = 'default',
+    templateRoot: providedTemplateRoot = '',
   } = options;
 
-  const templateRoot = path.join(projectRoot, 'docs-template');
+  const templateRoot = providedTemplateRoot || path.join(projectRoot, 'docs-template');
+  const internalPaths = quiverInternalPaths(projectRoot);
   const replacements = {
     projectName,
     projectSlug: toProjectSlug(projectName),
@@ -407,17 +567,48 @@ function initializeProjectDocs(options) {
   const dirs = [
     'docs',
     'docs/ai',
-    'docs/tools',
-    'docs/archive',
-    `specs/${replacements.projectSlug}/slices/slice-template`,
-    'tools/scripts',
+    '.quiver',
+    '.quiver/scans',
   ];
 
+  if (profile === 'full') {
+    dirs.push(
+      'docs/archive',
+      'docs/examples',
+      'docs/tools',
+      `specs/${replacements.projectSlug}/slices/slice-template`,
+      'tools/scripts',
+    );
+  } else if (legacyScripts) {
+    dirs.push('tools/scripts');
+  }
+
   for (const dir of dirs) {
     ensureDir(path.join(projectRoot, dir));
   }
 
   const operations = [];
+  if (!fs.existsSync(internalPaths.configPath)) {
+    fs.writeFileSync(internalPaths.configPath, `${JSON.stringify(buildQuiverConfig(), null, 2)}\n`);
+    operations.push({ source: 'Quiver config', destination: '.quiver/config.json', result: 'created' });
+  } else {
+    operations.push({ source: 'Quiver config', destination: '.quiver/config.json', result: 'skipped' });
+  }
+
+  fs.writeFileSync(internalPaths.gitignorePath, buildQuiverInternalGitignore());
+  operations.push({ source: 'Quiver internal gitignore', destination: '.quiver/.gitignore', result: 'updated' });
+
+  if (includeTemplates) {
+    fs.mkdirSync(internalPaths.templatesDir, { recursive: true });
+    fs.cpSync(templateRoot, internalPaths.templatesDir, {
+      recursive: true,
+      force: false,
+      errorOnExist: false,
+      preserveTimestamps: true,
+    });
+    operations.push({ source: 'packaged templates', destination: '.quiver/templates', result: 'merged' });
+  }
+
   const agentsSourcePath = path.join(templateRoot, 'AGENTS.md.template');
   if (fs.existsSync(agentsSourcePath)) {
     const agentsDestinationPath = path.join(projectRoot, 'AGENTS.md');
@@ -457,13 +648,45 @@ function initializeProjectDocs(options) {
     ['specs/[project-name]/slices/pr.md.template', `specs/${replacements.projectSlug}/slices/slice-template/pr.md.template`],
   ];
 
+  const minimalTemplateDestinations = new Set([
+    'docs/AI_CONTEXT.md',
+    'docs/AI_ONBOARDING_PROMPT.md',
+    'docs/COMMANDS.md',
+    'docs/WORKFLOW.md',
+  ]);
+  const defaultTemplateDestinations = new Set([
+    ...minimalTemplateDestinations,
+    'docs/CONTEXTO.md',
+    'docs/DECISIONS.md',
+    'docs/GITFLOW_PR_GUIDE.md',
+    'docs/INDEX.md',
+    'docs/STATUS.md',
+    'docs/SUPPORT_MATRIX.md',
+    'docs/TESTING_GUIDE_FOR_AI.md',
+    'docs/TROUBLESHOOTING.md',
+    'docs/ai/LESSONS.md',
+  ]);
+
   for (const [source, destination, frontMatterFactory] of templateCopies) {
+    if (profile === 'minimal' && !minimalTemplateDestinations.has(destination)) {
+      continue;
+    }
+
+    if (profile === 'default' && !defaultTemplateDestinations.has(destination)) {
+      continue;
+    }
+
     const sourcePath = path.join(templateRoot, source);
     if (!fs.existsSync(sourcePath)) {
       continue;
     }
 
     const destinationPath = path.join(projectRoot, destination);
+    if (!migrateMode && fs.existsSync(destinationPath)) {
+      operations.push({ source, destination, result: 'skipped' });
+      continue;
+    }
+
     const result = copyRenderedFile(sourcePath, destinationPath, replacements, migrateMode, frontMatterFactory);
     operations.push({ source, destination, result });
   }
@@ -491,31 +714,58 @@ function initializeProjectDocs(options) {
     ['scripts/migrate-project.sh', 'tools/scripts/migrate-project.sh'],
   ];
 
+  const alwaysBinaryDestinations = new Set([
+    'docs/ai/RULES.yaml',
+  ]);
+  const legacyScriptDestinations = new Set([
+    'tools/scripts/start-slice.sh',
+    'tools/scripts/refresh-active-slices.sh',
+    'tools/scripts/check-slice-readiness.sh',
+    'tools/scripts/check-pr-readiness.sh',
+    'tools/scripts/cleanup-slice.sh',
+    'tools/scripts/check-scope.sh',
+    'tools/scripts/migrate-project.sh',
+  ]);
+
   for (const [source, destination] of binaryCopies) {
+    if (
+      profile !== 'full'
+      && !alwaysBinaryDestinations.has(destination)
+      && !(legacyScripts && legacyScriptDestinations.has(destination))
+    ) {
+      continue;
+    }
+
     const sourcePath = path.join(templateRoot, source);
     const destinationPath = path.join(projectRoot, destination);
     if (!fs.existsSync(sourcePath)) {
       continue;
     }
 
-    const result = copyIfSourceExists(sourcePath, destinationPath, migrateMode);
+    const result = copyIfSourceExists(sourcePath, destinationPath, true);
     operations.push({ source, destination, result });
   }
 
   const aiPrinciplesSource = path.join(templateRoot, 'docs/ai/PRINCIPLES.md');
   if (fs.existsSync(aiPrinciplesSource)) {
     const aiPrinciplesDestination = path.join(projectRoot, 'docs/ai/PRINCIPLES.md');
-    const result = copyRenderedFile(
-      aiPrinciplesSource,
-      aiPrinciplesDestination,
-      replacements,
-      migrateMode,
-      frontMatterFor('AI operating principles', 'all AI work'),
-    );
+    const result = !migrateMode && fs.existsSync(aiPrinciplesDestination)
+      ? 'skipped'
+      : copyRenderedFile(
+        aiPrinciplesSource,
+        aiPrinciplesDestination,
+        replacements,
+        migrateMode,
+        frontMatterFor('AI operating principles', 'all AI work'),
+      );
     operations.push({ source: 'docs/ai/PRINCIPLES.md', destination: 'docs/ai/PRINCIPLES.md', result });
   }
 
-  const packageResult = mergePackageJson(projectRoot, templateRoot, migrateMode);
+  const packageResult = mergePackageJson(projectRoot, templateRoot, {
+    legacyScripts,
+    migrateMode,
+    profile,
+  });
   operations.push({ source: 'package.template.json', destination: 'package.json', result: packageResult });
 
   const mergedPackageJsonPath = path.join(projectRoot, 'package.json');
@@ -554,12 +804,21 @@ function initializeProjectDocs(options) {
   ];
 
   for (const [source, destination] of tierCopies) {
+    if (profile !== 'full') {
+      continue;
+    }
+
     const sourcePath = path.join(templateRoot, source);
     if (!fs.existsSync(sourcePath)) {
       continue;
     }
 
     const destinationPath = path.join(projectRoot, destination);
+    if (!migrateMode && fs.existsSync(destinationPath)) {
+      operations.push({ source, destination, result: 'skipped' });
+      continue;
+    }
+
     const result = copyRenderedFile(sourcePath, destinationPath, tierReplacements, migrateMode, ({
       body,
     }) => buildFrontMatterFields({
@@ -607,7 +866,9 @@ function initializeProjectDocs(options) {
   writeState(projectRoot, nextState);
 
   const searchPath = path.join(projectRoot, 'docs', 'SEARCH.md');
-  if (!(migrateMode && fs.existsSync(searchPath))) {
+  if (profile !== 'full') {
+    operations.push({ source: 'docs/SEARCH.md', destination: 'docs/SEARCH.md', result: 'skipped-profile' });
+  } else if (!fs.existsSync(searchPath)) {
     const searchContent = `# Búsqueda por Tema
 
 **Última actualización:** ${replacements.currentDate}
@@ -656,7 +917,7 @@ function initializeProjectDocs(options) {
 
   const readmePath = path.join(projectRoot, 'README.md');
   if (!fs.existsSync(readmePath)) {
-    fs.writeFileSync(readmePath, `${renderTemplate(buildReadme(projectName, replacements.projectSlug), replacements)}\n`);
+    fs.writeFileSync(readmePath, `${renderTemplate(buildReadme(projectName, replacements.projectSlug, profile), 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' });