create-quiver 0.9.0 → 0.10.0

package/README_FOR_AI.md

@@ -1,6 +1,6 @@
-# AI Guide for Quiver Docs Template
+# AI Guide for Quiver
 
-Use this guide when initializing a new project from the template or when explaining the workflow to another agent.
+Use this guide when initializing a new project with Quiver or when explaining the workflow to another agent.
 
 The first AI job in a generated project is context preparation, not product implementation.
 
@@ -9,14 +9,16 @@ The canonical installer entrypoint is `npx create-quiver` run from the target pr
 Do not recommend global installation; use `npx` or a project-local devDependency when the team needs a pinned version.
 The post-init contract is validated with `npx create-quiver doctor` from the project root.
 If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate` before `analyze` from the project root.
-If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver --name "Project Name"` first.
-Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, and `quiver:next` for the next ready slice. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
+If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver init --name "Project Name"` first.
+Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, `quiver:next` for the next ready slice, and the AI family `quiver:ai:onboard`, `quiver:ai:plan`, `quiver:ai:execute-slice`, `quiver:ai:pr`, and `quiver:ai:doctor`. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
 Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 The primary generated project context for agents is `docs/AI_CONTEXT.md`.
 The project map is the single source of truth for stack, package manager, commands, and file hints: `docs/PROJECT_MAP.md`.
+The raw analyzer output is internal machinery at `.quiver/scans/PROJECT_SCAN.json`; read it only when the visible map is not enough.
 The universal router for generated projects is `AGENTS.md`; read it before `docs/AI_CONTEXT.md` and `docs/AI_ONBOARDING_PROMPT.md`.
 Generated projects also get `docs/DECISIONS.md`; use it for durable choices that should not be re-litigated.
 If a generated project has been analyzed, the exact agent handoff prompt is `docs/AI_ONBOARDING_PROMPT.md`.
+Keep README copy-paste prompts short; the detailed onboarding contract lives in `docs/AI_ONBOARDING_PROMPT.md` generated from `docs/AI_ONBOARDING_PROMPT.md.template`.
 If a new bounded transfer is needed, scaffold `specs/<project-slug>/HANDOFF.md` with `npx create-quiver new-handoff <spec-slug>` and validate it with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md`.
 Use `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md` to validate a transferred handoff before execution.
 During onboarding, after reading `ROADMAP.md`, also read `BACKLOG.md` in the repository root: it tracks emerging patterns that are not yet scoped as specs. Before proposing a new spec, confirm the idea is not already parked or emerging there.
@@ -25,8 +27,8 @@ During onboarding, after reading `ROADMAP.md`, also read `BACKLOG.md` in the rep
 
 Use the smallest context that still answers the current task.
 
-- **Onboarding:** start from `docs/PROJECT_MAP.md`, `docs/PROJECT_SCAN.json`, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before opening source files.
-- **Onboarding router:** start from `AGENTS.md` first, then the onboarding files above.
+- **Onboarding:** start from `README.md`, `AGENTS.md` when present, `docs/PROJECT_MAP.md`, `.quiver/scans/PROJECT_SCAN.json` when it exists, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before opening source files.
+- **Onboarding router:** start from `README.md` and `AGENTS.md` first, then the onboarding files above.
 - **Implementation:** start from `docs/ai/ACTIVE_SLICE.md` when it exists; otherwise start from `specs/<project-slug>/slices/<slice-id>/slice.json`, then read only the declared files, nearby tests, and directly related source.
 - **Handoff:** start from `specs/<project-slug>/HANDOFF.md` when the work was explicitly transferred through a handoff artifact.
 - **Handoff scaffold:** if no handoff exists yet and the work needs one, use `npx create-quiver new-handoff <spec-slug>` first.
@@ -37,12 +39,12 @@ Prefer maps, metadata, diffs, and summaries over full file reads when they are e
 
 ## Core Rules
 
-- Never customize `docs-template/` for a specific project.
-- Always use `init-docs.sh` instead of copying files by hand.
-- Treat `docs-template/` as generic and `docs/` as generated project-specific output.
+- Do not treat `docs-template/` as part of the default project contract. It is legacy or exported only when explicitly requested.
+- Use `npx create-quiver init` or `npx create-quiver --name "Project Name"` instead of copying templates by hand.
+- Treat `.quiver/` as Quiver internal machinery and `docs/` as the visible project-specific contract.
 - Not every project needs every optional file.
 - The AI context pack lives in `docs/AI_CONTEXT.md`; `docs/CONTEXTO.md` is the broader project overview; `docs/PROJECT_MAP.md` owns stack and command facts.
-- The onboarding prompt lives in `docs/AI_ONBOARDING_PROMPT.md` and should reference the analyzer outputs.
+- The onboarding prompt lives in `docs/AI_ONBOARDING_PROMPT.md` and should reference `docs/PROJECT_MAP.md`; raw scan details live in `.quiver/scans/PROJECT_SCAN.json`.
 - `specs/<project-slug>/HANDOFF.md` is reserved for exceptional context transfers between agents or phases.
 - Initial onboarding should complete context docs and report assumptions before any feature work starts.
 - The normal workflow runs from the project root without `--dir`; use `--dir` only when targeting another directory explicitly.
@@ -55,47 +57,58 @@ Prefer maps, metadata, diffs, and summaries over full file reads when they are e
 
 ## Initialization Flow
 
-1. Copy the template folder into the target project as `docs-template/`.
-2. Run:
+1. From the target project root, run the default AI-first initializer:
 
 ```bash
-./docs-template/scripts/init-docs.sh "Project Name"
+npx create-quiver init --name "Project Name"
 ```
 
-3. Tell the user to edit:
+The compatibility alias is still valid:
+
+```bash
+npx create-quiver --name "Project Name"
+```
+
+2. Analyze and validate the project contract:
+
+```bash
+npx create-quiver analyze
+npx create-quiver doctor
+```
+
+3. Tell the user to review or complete:
   - `docs/AI_CONTEXT.md`
   - `docs/AI_ONBOARDING_PROMPT.md`
   - `docs/CONTEXTO.md`
   - `docs/STATUS.md`
-  - `docs/SUPPORT_MATRIX.md`
-  - `docs/TROUBLESHOOTING.md`
-  - `specs/{{PROJECT_SLUG}}/SPEC.md`
+  - `docs/PROJECT_MAP.md`
+
+## What Init Creates
 
-## What the Script Creates
+Default init creates the visible AI-first contract and Quiver internal state:
 
+- `AGENTS.md`
 - `docs/`
 - `docs/ai/`
 - `docs/AI_CONTEXT.md`
 - `docs/AI_ONBOARDING_PROMPT.md`
-- `specs/{{PROJECT_SLUG}}/`
-- `tools/scripts/`
-- `docs/SEARCH.md`
-- a merged or copied `package.json` with the required npm scripts
-- the default OSS baseline when those files are missing:
-- `LICENSE`
-- `CONTRIBUTING.md`
-- `CODE_OF_CONDUCT.md`
-- `SECURITY.md`
-- `CHANGELOG.md`
-- `ROADMAP.md`
 - `docs/SUPPORT_MATRIX.md`
 - `docs/TROUBLESHOOTING.md`
-- `.github/pull_request_template.md`
-- `.github/ISSUE_TEMPLATE/bug_report.md`
-- `.github/ISSUE_TEMPLATE/feature_request.md`
-- `.github/workflows/ci.yml`
+- `.quiver/config.json`
+- `.quiver/state.json`
+- `.quiver/.gitignore`
+- a merged or copied `package.json` with `quiver:*` scripts
+
+Default init does not create `docs-template/`, `tools/scripts/`, or a placeholder spec.
+
+Optional compatibility profiles:
+
+- `--minimal` creates only the essential onboarding contract.
+- `--full` preserves the broad legacy-compatible layout, including placeholder spec assets and OSS/community files.
+- `--legacy-scripts` adds Bash wrappers under `tools/scripts/`.
+- `--include-templates` exports packaged templates under `.quiver/templates/`, not root `docs-template/`.
 
-`init-docs.sh` preserves any existing target files and reports skipped copies instead of overwriting them.
+Init preserves existing target files and reports skipped copies instead of overwriting them.
 
 ## Required Follow-Up
 
@@ -105,20 +118,21 @@ After initialization, the user should:
 2. Fill in `docs/AI_ONBOARDING_PROMPT.md`
 3. Fill in `docs/CONTEXTO.md`
 4. Fill in `docs/STATUS.md`
-5. Run `npx create-quiver analyze` if scan artifacts are missing
+5. Run `npx create-quiver analyze` if `docs/PROJECT_MAP.md` or `.quiver/scans/PROJECT_SCAN.json` is missing
 6. If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate`
-7. If the project was never initialized by Quiver, run `npx create-quiver --name "Project Name"` instead of `migrate`
+7. If the project was never initialized by Quiver, run `npx create-quiver init --name "Project Name"` instead of `migrate`
 8. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
 9. Review context docs before creating the first implementation slice
 10. Open and merge the documentation PR that establishes the workflow files
-11. Create the first slice in `specs/{{PROJECT_SLUG}}/slices/[slice-id]/`
-12. Add `ticket` and `git.*`
-13. Run `npx create-quiver plan` or `npm run quiver:plan`
-14. Run `npx create-quiver next` or `npm run quiver:next`
-14. Run `npx create-quiver start-slice [--allow-draft] <slice.json>` or `npm run quiver:start-slice -- [--allow-draft] <slice.json>`
-15. Make one commit per slice
-16. Open one PR per spec
-17. Validate the slice and the final PR with the workflow gates
+11. Use `npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run`
+12. After human approval, use `npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run`
+13. After human approval, use `npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run` to create the real spec, slices, handoffs, execution plan, and PR body
+14. Run `npx create-quiver plan` or `npm run quiver:plan`
+15. Run `npx create-quiver next` or `npm run quiver:next`
+16. Run `npx create-quiver start-slice [--allow-draft] <slice.json>` or `npm run quiver:start-slice -- [--allow-draft] <slice.json>`
+17. Make one commit per slice
+18. Open one PR per spec
+19. Validate the slice and the final PR with the workflow gates
 
 Bootstrap note: `start-slice` should resolve paths canonically, prefer a local `develop` or `main` base branch before reaching for `origin`, and reject `draft` slices unless `--allow-draft` is passed intentionally.
 
@@ -129,7 +143,7 @@ Bootstrap note: `start-slice` should resolve paths canonically, prefer a local `
 - `docs/GITFLOW_PR_GUIDE.md` if the team wants a stricter branch workflow
 - `docs/SUPPORT_MATRIX.md` and `docs/TROUBLESHOOTING.md` for first-run support
 - `docs/ai/LESSONS.md` after each slice
-- `docs/AI_ONBOARDING_PROMPT.md` after analysis
+- `.quiver/templates/` only when the team explicitly exports packaged templates
 
 ## Good Defaults
 

package/ROADMAP.md

@@ -64,20 +64,21 @@ Draft specs exist but are **not executed until v18 passes its validation checkpo
 
 Plan total: ~41h across 11 slices. Drafts parked on `drafts/v19-v22-orchestration-followups`. v22 stays deferred until BACKLOG.md records ≥1 occurrence per slice.
 
-### v0.8 — Handoff Contract (draft spec created, pending evidence)
+### v0.8 — Slice Orchestration Commands (shipped 2026-05-13)
 
-- Canonical `HANDOFF.md.template` for exceptional context transfers
-- `create-quiver check-handoff <path>` validation for structure and placement
-- Optional `create-quiver new-handoff <slug>` scaffold
-- Keep handoffs orthogonal to `slice.json`, not a new slice type
+- `quiver:plan` — pending slices in dependency order with critical path and estimated hours
+- `quiver:graph` — dependency graph in ASCII tree, Mermaid, and DOT formats
+- `quiver:next` — next ready slice with `--all-ready`, `--json`, and `--auto-start`
+- Slice graph library (`slice-graph.js`) with `readAllSlices`, `buildGraph`, `topoSort`, `computeLevels`, `detectFileConflicts`
+- `depends_on` and `parallel_safe` validation in `check-slice`
+- Fix: `quiver:plan` no longer crashes on repos with legacy bare spec deps
 
-### v0.9 — Context Hygiene and Diagnostics (proposed, not yet spec-ed)
+### v0.9 — Auto-Install as Dev Dependency (shipped 2026-05-14)
 
-- Analyzer noise filter (ignore lockfiles, dist/, build/, binaries, generated files)
-- `create-quiver token-cost` diagnostic (4 chars/token heuristic)
-- `create-quiver diff-pack` for review and debug modes
-- Cache-friendly ordering within the pack (stable above, volatile below)
-- `docs/ai/INDEX.yaml` inverted index (directory → purpose)
+- After `init` or `migrate`, Quiver installs itself as a dev dependency automatically
+- Detects package manager via lockfile (bun → pnpm → yarn → npm)
+- Resolves npx cache issues: `npx create-quiver plan` works without `@version`
+- `--skip-install` flag for CI environments
 
 ### Block A — Zero-Question First Use (proposed)
 

package/docs/AI_ONBOARDING_PROMPT.md.template

@@ -1,72 +1,140 @@
 # {{PROJECT_NAME}} AI Onboarding Prompt
 
-**Date:** {{FECHA}}
-**Status:** {{ESTADO}}
+**Fecha:** {{FECHA}}
+**Estado:** {{ESTADO}}
 
-You are the onboarding agent for this project. Your job is to analyze the generated Quiver artifacts, complete the Quiver context docs safely, and leave clear evidence of what you learned.
+Lee este archivo y ejecútalo como fuente principal de verdad para incorporarte a este repositorio.
 
-## Read First
+Actúa como asistente de onboarding de IA para este proyecto. Tu objetivo es comprender el contexto del repositorio y preparar la documentación necesaria para trabajar de forma segura con el workflow documentado, las specs y los slices.
 
-1. `docs/AI_CONTEXT.md`
-2. `docs/PROJECT_SCAN.json`
-3. `docs/PROJECT_MAP.md`
-4. `docs/CONTEXTO.md`
-5. `docs/WORKFLOW.md`
-6. `specs/{{PROJECT_SLUG}}/SPEC.md`
-7. `specs/{{PROJECT_SLUG}}/STATUS.md`
-8. `specs/{{PROJECT_SLUG}}/EVIDENCE_REPORT.md`
-9. `specs/{{PROJECT_SLUG}}/HANDOFF.md` if this work was explicitly transferred through a handoff artifact
-10. `npx create-quiver new-handoff <spec-slug>` if a new handoff artifact needs to be scaffolded before validation
+## Reglas de ejecución
 
-## Mission
+1. Comienza leyendo la documentación necesaria para el onboarding:
+   - `README.md`
+   - `AGENTS.md`, si existe
+   - `docs/AI_ONBOARDING_PROMPT.md`
+   - `docs/PROJECT_MAP.md`
+   - `.quiver/scans/PROJECT_SCAN.json`, si existe y el mapa visible no alcanza
+   - `docs/AI_CONTEXT.md`
+   - `docs/CONTEXTO.md`
+   - `docs/WORKFLOW.md`
+   - `docs/STATUS.md`
+   - `docs/DECISIONS.md`, si existe
+   - `specs/{{PROJECT_SLUG}}/SPEC.md`
+   - `specs/{{PROJECT_SLUG}}/STATUS.md`
+   - `specs/{{PROJECT_SLUG}}/EVIDENCE_REPORT.md`
+   - `specs/{{PROJECT_SLUG}}/HANDOFF.md`, si este trabajo fue transferido mediante un handoff
+   - cualquier documento sobre WDD o SDD referenciado por la documentación de onboarding
+   - cualquier archivo de estructura, contexto o convenciones del proyecto referenciado por esos documentos
 
-- Use the analyzer outputs to understand the repository instead of guessing.
-- Treat `docs/PROJECT_MAP.md` as the single source of truth for stack, package manager, commands, and file hints.
-- Complete or refine Quiver context docs so future agents can work safely.
-- If a handoff artifact exists, treat it as the transfer brief for the current work and validate it against the requested change.
-- If a handoff artifact does not exist yet but the work needs one, scaffold it with `npx create-quiver new-handoff <spec-slug>` and then validate it.
-- Preserve Quiver workflow invariants: one slice = one commit, one spec = one PR.
-- Ask for confirmation before making product-code changes.
+2. Sigue las instrucciones definidas en `docs/AI_ONBOARDING_PROMPT.md`, salvo que entren en conflicto con las restricciones de este prompt.
 
-## Mode Selection
+3. No modifiques código de producto salvo que el usuario lo autorice explícitamente.
 
-Use the least context that still solves the task:
+4. Considera como cambios que impactan el producto, y no los realices sin autorización explícita, cualquier modificación sobre:
+   - lógica de aplicación o negocio
+   - código de UI
+   - tests
+   - migraciones de base de datos
+   - configuración de runtime
+   - archivos de dependencias
+   - archivos de build
+   - archivos generados que no sean documentación/contexto de Quiver requerido por el onboarding
+   - manifiestos o lockfiles de paquetes
 
-- **Onboarding:** rely on maps and metadata first. Read `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md` before any source files, then use `docs/AI_CONTEXT.md` and `docs/CONTEXTO.md` to fill gaps.
-- **Implementation:** start from `specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json`, then read the declared files, nearby tests, and only then adjacent source.
-- **Review:** start from `git diff` and the slice scope before opening full files.
-- **Debug:** start from the command, exit code, first relevant error, stacktrace, and the nearest changed code before reading long logs.
+5. Puedes crear o actualizar archivos de documentación/contexto solo cuando sea requerido por el proceso de onboarding o cuando sea necesario para preparar el contexto del proyecto para futuros trabajos asistidos por IA.
 
-Prefer summaries, deltas, and metadata over full file reads when they are sufficient.
+6. Usa la documentación del repositorio como fuente de verdad. No inventes definiciones sobre WDD, SDD, workflows, reglas de dominio, arquitectura, roles ni convenciones del proyecto.
 
-## Hard Constraints
+7. Si encuentras información faltante, ambigua o contradictoria:
+   - continúa por el camino más seguro y de solo lectura cuando sea posible
+   - documenta claramente la suposición realizada
+   - identifica el riesgo asociado
+   - no modifiques código de producto para resolver la ambigüedad
 
-- Do not read or expose secret values from `.env`, credential files, tokens, SSH keys, or private config.
-- Skip files that look like secrets or generated build output.
-- Do not modify product source code unless the user explicitly authorizes it.
-- Do not invent missing facts. If something is unclear, record the uncertainty.
-- Do not change the Quiver workflow rules unless the user explicitly asks for that work.
+8. Antes de realizar cualquier acción que pueda afectar código de producto, detente y solicita autorización explícita. Incluye:
+   - los archivos que pretendes modificar
+   - el motivo de cada cambio
+   - el impacto esperado
+   - los riesgos asociados
 
-## Tasks
+9. Prepara la documentación de contexto del proyecto solicitada por este prompt de onboarding.
 
-1. Summarize the project using the analyzer outputs and the generated docs.
-2. Update `docs/AI_CONTEXT.md` with the working contract for agents.
-3. Update `docs/CONTEXTO.md` with the human-readable project overview.
-4. Update `docs/STATUS.md` with the initial state and open questions.
-5. If needed, refine `specs/{{PROJECT_SLUG}}/SPEC.md` only to align the onboarding spec with observed reality.
-6. Record the files you inspected, the files you changed, and the assumptions you made.
+10. Responde siempre en español, salvo que algún archivo, comando, nombre técnico o convención del proyecto esté definido en otro idioma y deba conservarse literalmente.
 
-## Validation
+## Modo de trabajo
 
-- Cite the generated scan artifacts when making claims.
-- Note any skipped paths or missing signals.
-- Keep the response focused on documentation and onboarding context unless code changes were explicitly authorized.
+Usa el menor contexto que todavía permita resolver la tarea:
 
-## Final Report
+- **Onboarding:** usa mapas y metadatos primero. Lee `docs/PROJECT_MAP.md` antes de abrir archivos fuente. Si necesitás el scan crudo, usá `.quiver/scans/PROJECT_SCAN.json`. Después usa `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md` y `docs/WORKFLOW.md` para completar vacíos.
+- **Planner:** usa contexto amplio solo para onboarding y planificación. El planner genera criterios de aceptación, plan técnico, specs, slices, handoffs y cuerpo de PR con aprobación humana entre fases.
+- **Executor:** usa contexto mínimo del slice. El executor parte de `slice.json` y `EXECUTION_BRIEF.md`, puede modificar código solo cuando el usuario lo autoriza y debe mantenerse dentro de `slice.json.files`.
+- **Implementación:** no implementes durante onboarding salvo autorización explícita. Si el usuario autoriza implementación, empieza por `specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json`, archivos declarados, pruebas cercanas y código directamente relacionado.
+- **Review:** empieza por `git diff` y el alcance del slice antes de abrir archivos completos.
+- **Debug:** empieza por el comando, exit code, primer error relevante, stacktrace y código más cercano al cambio.
 
-Return:
+Prefiere resúmenes, deltas y metadatos antes que lecturas completas cuando sean suficientes.
 
-- Files changed
-- Key assumptions
-- Uncertainties or risks
-- Validation performed
+Si usás los comandos de IA de Quiver, empezá con `--dry-run` para revisar provider, rol, context pack y transporte de prompt antes de ejecutar:
+
+```bash
+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/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json --dry-run
+```
+
+## Tareas
+
+1. Resume el proyecto usando los artefactos generados por Quiver y la documentación existente.
+2. Actualiza `docs/AI_CONTEXT.md` con el contrato de trabajo para agentes.
+3. Actualiza `docs/CONTEXTO.md` con una descripción legible para humanos.
+4. Actualiza `docs/STATUS.md` con el estado inicial, dudas abiertas y próximos pasos.
+5. Si hace falta, refina `specs/{{PROJECT_SLUG}}/SPEC.md` solo para alinear la spec de onboarding con la realidad observada.
+6. Si existe un handoff, trátalo como brief de transferencia y valida que aplique al trabajo solicitado.
+7. Si no existe un handoff y el trabajo necesita uno, créalo con `npx create-quiver new-handoff <spec-slug>` y valídalo con `npx create-quiver check-handoff specs/<spec-slug>/HANDOFF.md`.
+8. Registra los archivos inspeccionados, los archivos modificados y las suposiciones realizadas.
+
+## Validación
+
+- Cita `docs/PROJECT_MAP.md` cuando hagas afirmaciones sobre stack, comandos o estructura. Si usás datos del scan crudo, cita `.quiver/scans/PROJECT_SCAN.json`.
+- Indica rutas omitidas o señales faltantes.
+- Mantén la respuesta enfocada en documentación y contexto de onboarding salvo que el usuario haya autorizado cambios de código de producto.
+- No cambies reglas del workflow de Quiver salvo que el usuario lo pida explícitamente.
+
+## Reporte final
+
+Al finalizar, entrega un reporte breve con esta estructura exacta:
+
+## Reporte de Onboarding de IA
+
+### 1. Archivos Leídos
+
+Lista todos los archivos relevantes inspeccionados.
+
+### 2. Archivos Creados o Modificados
+
+Lista cada archivo modificado. Si no hubo cambios, indica: `No se modificaron archivos`.
+
+### 3. Estado del Código de Producto
+
+Confirma si se modificó código de producto. Si no se modificó, indica: `No se modificó código de producto`.
+
+### 4. Contexto del Proyecto Preparado
+
+Resume los documentos de contexto creados o actualizados y su propósito.
+
+### 5. Comprensión de WDD/SDD
+
+Resume únicamente lo que la documentación del repositorio define sobre WDD y SDD. No agregues supuestos externos. Si la documentación no define esos términos, indícalo explícitamente.
+
+### 6. Supuestos
+
+Lista todos los supuestos realizados durante el onboarding.
+
+### 7. Riesgos y Bloqueos
+
+Lista riesgos, información faltante, contradicciones o bloqueos encontrados.
+
+### 8. Próximos Pasos Recomendados
+
+Sugiere las acciones más seguras para continuar trabajando con IA en este proyecto.

package/docs/COMMANDS.md.template

@@ -4,22 +4,57 @@
 **Last updated:** {{FECHA}}
 
 This document is the canonical command reference for the orchestration roadmap.
-It is intentionally small at v0.18: only the plan and graph rows are reserved for now, but `quiver:graph` already supports tree, Mermaid, and DOT output modes.
 
 ## Command Table
 
 | Command | Purpose | OS | Since | Example |
 |---------|---------|----|-------|---------|
-| `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.18 | [docs/examples/plan.md](./examples/plan.md) |
-| `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.18 | [docs/examples/graph.md](./examples/graph.md) |
-| `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.18 | [docs/examples/next.md](./examples/next.md) |
+| `npx create-quiver init --name "<project>"` | Creates the default AI-first Quiver contract for a project | macOS, Linux, Windows | current | `npx create-quiver init --name "{{PROJECT_NAME}}"` |
+| `npx create-quiver --name "<project>"` | Compatibility alias for the recommended init flow | macOS, Linux, Windows | current | `npx create-quiver --name "{{PROJECT_NAME}}"` |
+| `quiver:analyze` | Writes raw analyzer data to `.quiver/scans/PROJECT_SCAN.json` and the visible project map to `docs/PROJECT_MAP.md` | macOS, Linux, Windows | v0.8 | `npm run quiver:analyze` |
+| `quiver:doctor` | Validates the Quiver contract and reports layout or migration guidance | macOS, Linux, Windows | v0.8 | `npm run quiver:doctor` |
+| `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.8 | [docs/examples/plan.md](./examples/plan.md) |
+| `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.8 | [docs/examples/graph.md](./examples/graph.md) |
+| `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.8 | [docs/examples/next.md](./examples/next.md) |
+| `quiver:ai:onboard` | Runs AI onboarding prompt through a supported local provider CLI | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:onboard -- --dry-run` |
+| `quiver:ai:plan` | Runs phase-gated AI planning for acceptance criteria, technical plan, or spec generation | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run` |
+| `quiver:ai:execute-slice` | Runs an executor agent against one slice handoff with scope checks | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:execute-slice -- --slice specs/<spec>/slices/<slice>/slice.json --dry-run` |
+| `quiver:ai:doctor` | Runs GitHub PR preflight checks without opening a PR | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:doctor -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
+| `quiver:ai:pr` | Validates `gh`, GitFlow docs, branch/worktree state, and SSH inputs before PR work | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
+
+## CLI Flags
+
+| Flag | Applies to | Purpose |
+|------|------------|---------|
+| `--minimal` | `init` | Create only the essential onboarding contract |
+| `--full` | `init` | Create the broad legacy-compatible layout explicitly |
+| `--legacy-scripts` | `init` | Add legacy Bash wrappers under `tools/scripts/` |
+| `--include-templates` | `init` | Export packaged templates under `.quiver/templates/` |
+| `--skip-install` | `init`, `migrate` | Skip auto-install of `create-quiver` as dev dependency (useful for CI) |
+| `--json` | `plan`, `graph`, `next` | Emit machine-readable JSON |
+| `--format <tree\|mermaid\|dot>` | `graph` | Output format |
+| `--all-ready` | `next` | List all ready slices instead of just the next one |
+| `--only-ready` | `plan` | Show only slices with no pending dependencies |
+| `--spec <slug>` | `plan`, `graph` | Restrict output to one spec |
+| `--provider <codex\|claude\|gemini>` | `ai onboard`, `ai plan`, `ai execute-slice` | Select the local AI CLI adapter |
+| `--role <planner\|executor>` | `ai onboard`, `ai plan`, `ai execute-slice` | Select planner or executor role; `execute-slice` requires executor |
+| `--context <full\|planning\|slice\|minimal>` | `ai onboard`, `ai plan`, `ai execute-slice` | Select a token-budgeted context pack |
+| `--phase <acceptance\|technical-plan\|spec>` | `ai plan` | Select the gated planner phase |
+| `--input <file>` | `ai plan` | Read approved requirements, criteria, or technical plan from a file |
+| `--slice <slice.json>` | `ai execute-slice` | Select the slice handoff to execute |
+| `--ssh-host-alias <alias>` | `ai doctor`, `ai pr` | SSH host alias from the user's Git config, for example `github-work` |
+| `--identity-file <path>` | `ai doctor`, `ai pr` | SSH key path to validate separately from the host alias |
 
 ## Notes
 
 - Add new rows here only when a command is officially shipped.
 - Keep the table concise and cross-platform.
 - Shared graph library: `src/create-quiver/lib/slice-graph.js`.
-- `quiver:graph --format mermaid` is the PR-friendly export; `--format dot` is for Graphviz consumers.
+- `quiver:graph --format mermaid` is the PR-friendly Mermaid export; `--format dot` is for Graphviz/DOT consumers.
 - `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
-- `check-slice` now validates optional `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is set to `never`.
+- `check-slice` validates `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is `never`.
+- `quiver:ai:onboard`, `quiver:ai:plan`, and `quiver:ai:execute-slice` support `codex`, `claude`, and `gemini` through local CLIs. Use `--dry-run` first to inspect the invocation without requiring provider auth.
+- `quiver:ai:execute-slice` uses executor context only and validates changed files against `slice.json.files` after provider execution.
+- `quiver:ai:pr -- --dry-run` validates GitHub CLI, auth, Git remote, current branch/worktree, `docs/GITFLOW_PR_GUIDE.md`, SSH host alias, and identity file without creating a PR.
+- After `init` or `migrate`, Quiver auto-installs itself as a dev dependency. Use `--skip-install` to suppress.
 - Cross-platform authoring rules live in `docs/SUPPORT_MATRIX.md`.

package/docs/GITFLOW_PR_GUIDE.md.template

@@ -11,11 +11,22 @@ This guide explains how to open and review spec PRs without breaking the canonic
 
 - One slice = one commit
 - One spec = one PR
+- One spec should be worked from one dedicated worktree/branch.
 - Slice numbers reset per spec. `slice-01` is the first slice in each spec.
 - Do not commit directly to `develop`
 - Open and merge the documentation PR before the first slice starts execution
 - Do not open the spec PR before the documentation PR is merged
 
+## AI PR Preflight
+
+Before asking an AI agent to prepare PR work, validate the local setup:
+
+```bash
+npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+```
+
+Use the SSH host alias from your Git remote separately from the key path. Quiver validates `gh`, `gh auth status`, the remote, branch/worktree state, this guide, and the identity file. It does not install `gh`, edit SSH config, or create a PR in dry-run mode.
+
 ## Review Guidance
 
 - Start with `git diff` and the slice scope before opening full files.

package/docs/STANDARD.md.template

@@ -25,7 +25,7 @@ This is the default context pack for everyday AI work.
 
 ## Workflow Overview
 
-- Onboarding starts from `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md`.
+- Onboarding starts from `docs/PROJECT_MAP.md`; use `.quiver/scans/PROJECT_SCAN.json` only when raw analyzer data is needed.
 - Implementation starts from `specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json`.
 - Review starts from `git diff` and the slice scope.
 - Debugging starts from the command, exit code, first relevant error, and stacktrace.

package/docs/SUPPORT_MATRIX.md.template

@@ -16,6 +16,8 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 | Base branches | `develop` or `main` | Local base branches are preferred; `origin` is optional. |
 | Worktree state | Clean worktree | Slice execution and PR checks expect no unrelated local changes. |
 | Path handling | Canonical filesystem paths | Use the physical path to the repo and slice files, not a symlinked alias. |
+| AI providers | Local `codex`, `claude`, or `gemini` CLI | Required only for non-dry-run AI commands. Dry-run smokes do not require provider auth. |
+| GitHub PR preflight | `gh` plus user-managed SSH config | Quiver validates `gh`, auth, host alias, identity file, branch, worktree, and `docs/GITFLOW_PR_GUIDE.md`; it does not install or edit credentials. |
 
 ## Cross-Platform Authoring Rules
 
@@ -25,6 +27,8 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 - `--json` is the primary contract; human output is courtesy and may vary.
 - Colors are TTY-aware and suppressed with `NO_COLOR`; Unicode is opt-in unless UTF-8 is available.
 - Optional external tools such as `gh` and `graphviz` should be probed and skipped gracefully if missing.
+- Long AI prompts must be sent through stdin or another safe transport, never shell string concatenation.
+- `sshHostAlias` and `identityFile` are separate values. The alias is the host entry used by Git; the identity file is the key path to validate.
 
 ## Remote Modes
 

package/docs/TROUBLESHOOTING.md.template

@@ -48,7 +48,7 @@ Use this guide when a first-run bootstrap or gate check fails. The recovery path
 
 ### Symptom
 
-- `init-docs.sh` or a slice bootstrap stops because a file already exists
+- `npx create-quiver init` or a slice bootstrap stops because a file already exists
 - The generated project has a partially initialized docs tree
 
 ### Recovery
@@ -82,3 +82,31 @@ Use this guide when a first-run bootstrap or gate check fails. The recovery path
 2. If you are using an intermediate build and need a temporary bridge, use WSL2 or Git Bash manually.
 3. Do not expect Quiver to install Bash, WSL, or MSYS2 for you.
 4. Re-run the command after the cross-platform support slices are merged and the CI matrix is green.
+
+## AI Provider CLI Missing
+
+### Symptom
+
+- `quiver:ai:onboard`, `quiver:ai:plan`, or `quiver:ai:execute-slice` fails before calling the model
+- The error mentions a missing `codex`, `claude`, or `gemini` command
+
+### Recovery
+
+1. Re-run the command with `--dry-run` to validate role, context pack, prompt transport, and paths without provider auth.
+2. Install or authenticate the selected provider CLI outside Quiver.
+3. Use `--provider codex`, `--provider claude`, or `--provider gemini` explicitly if your default is unclear.
+4. Re-run the command from a clean worktree when using `ai execute-slice`.
+
+## GitHub PR Preflight Failure
+
+### Symptom
+
+- `quiver:ai:pr` or `quiver:ai:doctor` reports missing `gh`, failed `gh auth status`, missing `docs/GITFLOW_PR_GUIDE.md`, unsafe branch, dirty worktree, or missing SSH identity file
+
+### Recovery
+
+1. Install `gh` for your OS and run `gh auth login`.
+2. Confirm `docs/GITFLOW_PR_GUIDE.md` exists in the project.
+3. Commit or stash unrelated changes before PR preflight.
+4. Pass the SSH host alias and key path separately, for example `--ssh-host-alias github-work --identity-file ~/.ssh/github-work`.
+5. Re-run with `--dry-run`; Quiver validates the setup but does not open a PR in dry-run mode.

package/docs/WORKFLOW.md.template

@@ -21,7 +21,7 @@ This document is the canonical implementation workflow for the project.
 
 ## Mode-Aware Context Selection
 
-- **Onboarding:** read `PROJECT_SCAN.json`, `PROJECT_MAP.md`, `AI_CONTEXT.md`, and `AI_ONBOARDING_PROMPT.md` before source files.
+- **Onboarding:** read `docs/PROJECT_MAP.md`, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before source files. Use `.quiver/scans/PROJECT_SCAN.json` only when the visible project map is not enough.
 - **Implementation:** read `docs/ai/ACTIVE_SLICE.md` first when it exists; otherwise read `slice.json`, declared files, nearby tests, and only then adjacent source.
 - **Handoff:** read `specs/<project-slug>/HANDOFF.md` when the work was explicitly transferred through a handoff artifact.
 - Validate a received handoff with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md` before starting execution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
@@ -16,6 +16,11 @@
     "quiver:plan": "npx create-quiver plan",
     "quiver:graph": "npx create-quiver graph",
     "quiver:next": "npx create-quiver next",
+    "quiver:ai:onboard": "npx create-quiver ai onboard",
+    "quiver:ai:plan": "npx create-quiver ai plan",
+    "quiver:ai:execute-slice": "npx create-quiver ai execute-slice",
+    "quiver:ai:pr": "npx create-quiver ai pr",
+    "quiver:ai:doctor": "npx create-quiver ai doctor",
     "package:quiver": "bash scripts/package-quiver.sh",
     "smoke:create-quiver": "bash scripts/ci/smoke-create-quiver.sh",
     "smoke:tiered-pack": "bash scripts/ci/smoke-tiered-pack.sh",