create-quiver 0.10.0 → 0.12.0

package/BACKLOG.md

@@ -40,25 +40,24 @@
 ### Slice Orchestration and Tooling Commands
 
 - **Observed:** 2026-04-23
-- **Status:** planned
-- **Evidence so far:** 0 real cases. Drafted by the maintainer anticipating multi-model coordination (Opus/GPT-5.4 planning, Sonnet/GPT-5.4 Mini/Qwen Code execution) and visibility pain once specs accumulate.
-- **Problem it solves:** Today coordinating multiple agents across pending slices requires ad-hoc grep, ls, and git commands. There is no canonical way to ask "what runs next", "what can run in parallel", "what is this repo's state", or "how expensive is this slice to load".
+- **Status:** promoted
+- **Evidence so far:** The core orchestration line shipped through v18, v20, v21, v22, and v23. Guided workflow is implemented in `specs/quiver-v22-guided-ai-workflow/` and productized in `specs/quiver-v23-guided-flow-productization/`.
+- **Problem it solves:** Coordinating multiple agents across slices needs canonical answers for what runs next, what can run in parallel, what context each agent needs, and when work is ready for PR.
 - **Proposed shape:**
-  - v17 Orchestration Foundation (CI matrix, `lib/slice-graph.js`, `depends_on` validation)
-  - v18 Slice Orchestration (`plan`, `graph`, `next`)
-  - v19 Project Visibility (`status`, `estimate`, `lint-spec`)
-  - v20 Context Diagnostics (`cost`, `diff-pack`, `replay`)
-  - v21 Slice Archaeology (`archive`, `blame-slice`)
-  - v22 Deferred Tooling (`fork-slice`, `squash-spec`, `share`, evidence-gated per slice)
-- **Cost to formalize:** ~55h across 15 slices in 4 specs (v19–v22). Spec/slice files drafted under `drafts/v19-v22-orchestration-followups`.
-- **Reasons to wait:** v17 and v18 shipped. v18 must pass its validation checkpoint (≥1 week real use) before v19 starts. Building orchestration before validating the existing commands risks reinforcing a design that does not earn its place.
-- **Trigger to promote (per spec):**
-  - v19: immediately after v18 checkpoint passes (≥1 week real use of `plan`, `graph`, `next`)
-  - v20–v21: previous spec validation checkpoint passed (≥1 week real use)
-  - v22 per slice: explicit occurrence recorded in this file for each of `fork-slice`, `squash-spec`, `share`
+  - v18 Slice Orchestration (`plan`, `graph`, `next`) shipped.
+  - v20 AI CLI Orchestration shipped.
+  - v21 AI-First Layout shipped.
+  - v22 Guided AI Workflow shipped in this branch.
+  - v23 Guided Flow Productization shipped in this branch.
+- **Cost to formalize:** Completed in `specs/quiver-v22-guided-ai-workflow/` and `specs/quiver-v23-guided-flow-productization/`, both with mandatory `slice-00`.
+- **Reasons to wait:** No wait for the guided workflow; it has been implemented. Deferred tooling such as `fork-slice`, `squash-spec`, and `share` still requires real demand before separate implementation.
+- **Trigger to promote:** Fulfilled for guided workflow on 2026-05-21.
 - **Related:**
-  - `drafts/v19-v22-orchestration-followups` (parked spec drafts)
-  - `ROADMAP.md` Orchestration and Tooling section
+  - `specs/quiver-v18-slice-orchestration/`
+  - `specs/quiver-v20-ai-cli-orchestration/`
+  - `specs/quiver-v21-ai-first-layout/`
+  - `specs/quiver-v22-guided-ai-workflow/`
+  - `specs/quiver-v23-guided-flow-productization/`
 
 ### Handoff Contract
 

package/CHANGELOG.md

@@ -4,6 +4,40 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Guided AI workflow commands: `prepare`, agent profiles, planner onboarding, approval persistence, `review-plan`, `spec create`, executor prompt generation, delegated execution waves, PR creation with `gh`, spec worktree start/status/close, and package safety.
+- `quiver:prepare`, `quiver:flow`, `quiver:ai:agent`, `quiver:ai:review-plan`, `quiver:ai:prompt-slice`, `quiver:ai:execute-plan`, `quiver:spec:create`, `quiver:spec:start`, `quiver:spec:status`, and `quiver:spec:close` npm scripts for generated projects.
+- Guided workflow smoke coverage for flow status, profiles, onboarding, approvals, review-plan, spec create, executor prompts, delegated execution dry-runs, PR dry-run/create mocks, cleanup, and package safety.
+- DX onboarding hardening for generated projects: `doctor --fix`, `check-slice --local`, `plan|graph|next --include-completed`, `ai prepare-context`, `evidence run`, and `demo create spec-viewer`.
+- Generated scripts for `quiver:evidence` and `quiver:ai:prepare-context`.
+
+### Changed
+
+- Root and generated docs now present Quiver as AI-first guided workflow tooling, not only scaffolding.
+- `ai execute-plan` now documents manual prompt mode and delegated worktree mode.
+- Refreshed AI context docs keep front matter after `analyze`.
+- Package smoke now fails when local AI/tool state, env files, npm credentials, or worktree state would enter the npm tarball.
+- `init`, `doctor`, `prepare`, and `analyze` now produce clearer first-use guidance, safer repairs, better generated metadata, and better command maps.
+
+### Fixed
+
+- Unknown top-level commands now fail clearly instead of being treated as legacy project names.
+- Generated docs and scripts are kept aligned with the selected init profile and supported command surface.
+- Local-only repositories can run structural slice validation without a remote/base branch by using `check-slice --local`.
+
+## [0.10.0] - 2026-05-21
+
+### Added
+
+- AI CLI orchestration commands for provider dry-runs, planner phases, executor slice runs, and GitHub PR preflight.
+- AI-first default project layout with visible onboarding docs and internal `.quiver/` machinery.
+- Generated spec/slice/handoff/PR artifacts with mandatory `slice-00`.
+
+### Changed
+
+- Published `create-quiver` 0.10.0 and aligned the root docs with the current release line.
+
 ## [0.9.0] - 2026-05-14
 
 ### Added

package/README.md

@@ -12,8 +12,13 @@ Ejecutá Quiver desde la raíz del proyecto donde querés instalar el workflow:
 
 ```bash
 npx create-quiver init --name "Mi Proyecto"
+npx create-quiver flow
+npx create-quiver prepare --dry-run
 npx create-quiver analyze
 npx create-quiver doctor
+npx create-quiver ai agent set planner --provider codex --model "planner-model"
+npx create-quiver ai agent set executor --provider codex --model "executor-model"
+npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
 ```
 
@@ -24,19 +29,43 @@ Después de eso, revisá:
 - `docs/AI_CONTEXT.md`
 - `docs/AI_ONBOARDING_PROMPT.md`
 
-La maquinaria interna queda en `.quiver/`. Las specs reales no se crean durante el init: aparecen cuando el planner genera y aprueba una spec con `ai plan --phase spec`.
+La maquinaria interna queda en `.quiver/`. Las specs reales no se crean durante el init: aparecen cuando el plan técnico ya fue revisado y aprobado, usando `spec create`.
 
 El flujo normal con IA continúa así:
 
 ```bash
+npx create-quiver flow
 npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
-npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run
-npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
+npx create-quiver ai approve --phase acceptance --input acceptance-approved.md
+npx create-quiver ai approvals
+npx create-quiver ai plan --phase technical-plan --dry-run
+npx create-quiver ai review-plan --dry-run
+npx create-quiver ai approve --phase technical-plan --version <n>
+npx create-quiver spec create --dry-run
+npx create-quiver spec start specs/<project-slug>
 npx create-quiver next
-npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+npx create-quiver ai execute-plan --dry-run --commit --mode manual
+npx create-quiver ai execute-plan --dry-run --commit --mode delegated
 ```
 
-Usá `--dry-run` para validar provider, rol, contexto y paths sin ejecutar el modelo. Cuando el output esté revisado y aprobado, quitá `--dry-run`.
+Usá `--dry-run` para validar provider, rol, contexto, paths y olas sin ejecutar el modelo. `--mode manual` imprime prompts para asignar slices a mano; `--mode delegated` prepara la ejecución con workspaces seguros cuando hay paralelismo.
+
+### Compatibilidad: macOS, Linux y Windows
+
+El camino principal de Quiver está pensado para ser portable: usa `npx create-quiver ...`, `npm run quiver:*` y `node ...`. Esos comandos funcionan en macOS, Linux y Windows siempre que tengas Node.js, npm y Git instalados.
+
+Reglas prácticas por sistema:
+
+- macOS y Linux: podés copiar los ejemplos tal como están. Las rutas SSH suelen verse como `~/.ssh/github-work`.
+- Windows con PowerShell: usá los mismos comandos `npx`, `npm` y `node`, pero adaptá rutas a formato Windows, por ejemplo `C:\Users\<usuario>\ssh\github-work`.
+- Windows con Git Bash o WSL: podés usar rutas tipo Unix, por ejemplo `~/.ssh/github-work`.
+- Los wrappers Bash bajo `tools/scripts/` son compatibilidad legacy u opcional. Para trabajo nuevo, preferí el CLI Node y los scripts `quiver:*`.
+
+Cuando uses GitHub o PRs:
+
+- `--ssh-host-alias` recibe el alias del host en tu configuración SSH, por ejemplo `github-work` o `github-personal`.
+- `--identity-file` recibe la ruta al archivo de clave, que cambia según el sistema operativo.
+- `gh` debe estar instalado y autenticado; Quiver lo valida con `ai doctor` o `ai pr --dry-run`.
 
 ### Desarrollar este repositorio
 
@@ -58,21 +87,30 @@ Quiver asume que la mayoría de los equipos lo van a usar para coordinar trabajo
 |---|---|---|
 | WDD | Workflow-Driven Development: dejar claro cómo se trabaja antes de implementar. | `AGENTS.md`, `docs/WORKFLOW.md`, `docs/AI_CONTEXT.md`, `docs/PROJECT_MAP.md` |
 | SDD | Spec-Driven Development: definir el trabajo en specs y slices antes de tocar código. | `specs/<project-slug>/SPEC.md`, `slice.json`, `EXECUTION_BRIEF.md`, `pr.md` |
-| IA planner | Agente que lee contexto amplio y propone criterios, plan técnico, spec y slices. | `ai onboard`, `ai plan` |
-| IA executor | Agente que recibe un slice aprobado y trabaja con contexto mínimo. | `ai execute-slice`, `check-scope`, `check-slice` |
+| IA planner | Agente que lee contexto amplio y propone criterios, plan técnico, spec y slices. | `ai prepare-context`, `ai onboard`, `ai plan` |
+| IA executor | Agente que recibe un slice aprobado y trabaja con contexto mínimo. | `ai prompt-slice`, `ai execute-slice`, `check-scope`, `check-slice` |
 
 Flujo recomendado:
 
 ```bash
 npx create-quiver analyze
+npx create-quiver flow
 npx create-quiver doctor
+npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
 npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
-npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run
-npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
+npx create-quiver ai approve --phase acceptance --input acceptance-approved.md
+npx create-quiver ai plan --phase technical-plan --dry-run
+npx create-quiver ai review-plan --dry-run
+npx create-quiver ai approve --phase technical-plan --version <n>
+npx create-quiver spec create --dry-run
+npx create-quiver spec start specs/<project-slug>
 npx create-quiver graph
 npx create-quiver next
-npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+npx create-quiver ai prompt-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run --commit
+npx create-quiver ai execute-plan --dry-run --commit --mode delegated
+npx create-quiver ai pr --dry-run --input specs/<project-slug>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 ```
 
 Regla práctica: el planner no modifica código de producto; el executor solo trabaja sobre un slice aprobado y dentro de los archivos declarados en `slice.json`.
@@ -87,25 +125,31 @@ Usá este camino cuando todavía no existe el proyecto o estás arrancando una c
 mkdir mi-proyecto
 cd mi-proyecto
 npx create-quiver init --name "Mi Proyecto"
+npx create-quiver flow
+npx create-quiver prepare --dry-run
 npx create-quiver analyze
 npx create-quiver doctor
+npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
 ```
 
 Qué esperar:
 
-- Quiver crea un contrato visible chico: `AGENTS.md`, `docs/`, scripts `quiver:*` en `package.json` y configuración interna en `.quiver/`.
+- Quiver crea un contrato visible chico: `AGENTS.md`, `docs/`, `.gitignore`, scripts `quiver:*` en `package.json` y configuración interna en `.quiver/`.
 - No crea `docs-template/`, `tools/scripts/` ni una spec placeholder en el flujo default.
 - `analyze` crea el scan crudo en `.quiver/scans/PROJECT_SCAN.json` y el mapa legible en `docs/PROJECT_MAP.md`.
 - `doctor` valida que el contrato inicial esté completo.
-- `ai onboard --dry-run` muestra cómo se incorporaría un agente planner sin ejecutar el provider todavía.
+- `ai prepare-context --dry-run` muestra borradores y supuestos sin escribir; `ai onboard --dry-run` muestra cómo se incorporaría un agente planner sin ejecutar el provider todavía.
 
 Después del bootstrap, revisá:
 
 ```bash
 npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
-npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run
-npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
+npx create-quiver ai approve --phase acceptance --input acceptance-approved.md
+npx create-quiver ai plan --phase technical-plan --dry-run
+npx create-quiver ai review-plan --dry-run
+npx create-quiver ai approve --phase technical-plan --version <n>
+npx create-quiver spec create --dry-run
 npx create-quiver plan
 npx create-quiver graph
 npx create-quiver next
@@ -127,8 +171,12 @@ Luego inicializá Quiver desde la raíz del proyecto:
 
 ```bash
 npx create-quiver init --name "Nombre del Proyecto"
+npx create-quiver flow
 npx create-quiver analyze
 npx create-quiver doctor
+npx create-quiver ai agent set planner --provider codex --model "planner-model"
+npx create-quiver ai agent set executor --provider codex --model "executor-model"
+npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
 git status --short
 ```
@@ -138,7 +186,7 @@ Qué esperar:
 - Quiver agrega documentación, scripts `quiver:*` y archivos internos de soporte en `.quiver/`.
 - No deberías mezclar este paso con cambios de producto.
 - `docs/PROJECT_MAP.md` queda como fuente de verdad para stack, package manager, comandos y rutas importantes.
-- Las specs y slices reales se crean después, con `ai plan --phase spec`, cuando ya existen criterios y plan técnico aprobados.
+- Las specs y slices reales se crean después, con `spec create`, cuando ya existen criterios aprobados y un plan técnico revisado y aprobado.
 - El primer trabajo de IA debería ser preparar contexto y planificación, no implementar.
 
 Importante: no uses `migrate` para un proyecto que nunca tuvo Quiver. `migrate` es solo para proyectos previamente inicializados.
@@ -164,6 +212,7 @@ npx create-quiver doctor
 npx create-quiver migrate
 npx create-quiver analyze
 npx create-quiver doctor
+npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
 git status --short
 ```
@@ -179,7 +228,7 @@ Qué esperar:
 - La migración restaura o agrega archivos faltantes de forma aditiva.
 - No debería sobrescribir archivos existentes de proyecto sin necesidad.
 - Después de migrar, `analyze` actualiza el mapa técnico y `doctor` confirma los próximos pasos.
-- `ai onboard --dry-run` ayuda a validar que el contexto viejo quedó entendible para un agente planner.
+- `ai prepare-context --dry-run` ayuda a revisar supuestos del contexto migrado; `ai onboard --dry-run` valida que el contexto viejo quedó entendible para un agente planner.
 
 Si `doctor` falla indicando que el proyecto no fue inicializado por Quiver, usá el flujo del caso 2.
 
@@ -203,7 +252,7 @@ La idea práctica: primero contexto, después plan, después código.
 | Runtime | Node.js CLI |
 | Lenguaje | JavaScript CommonJS |
 | Package manager | npm (`package-lock.json`) |
-| Binario npm | `create-quiver` -> `bin/create-quiver.js` |
+| Binario npm | `create-quiver` y alias `quiver` -> `bin/create-quiver.js` |
 | Tests | Node built-in test runner (`node:test`) |
 | CI/CD | GitHub Actions |
 | Distribución | Paquete npm público `create-quiver` |
@@ -231,7 +280,7 @@ No se detectaron archivos `.env`; Quiver no requiere variables de entorno para e
 | `src/create-quiver/commands/` | Comandos `ai`, `graph`, `next` y `plan`. |
 | `src/create-quiver/lib/` | Lógica de análisis, doctor, slices, lifecycle, IA, Git y renderers. |
 | `docs/` | Plantillas que Quiver copia a proyectos destino. |
-| `specs/` | Specs internas del desarrollo de Quiver y templates usados cuando `ai plan --phase spec` crea una spec real. |
+| `specs/` | Specs internas del desarrollo de Quiver y templates usados cuando `spec create` crea una spec real. |
 | `scripts/` | Scripts de packaging, release, CI smoke y wrappers legacy. |
 | `tests/` | Tests unitarios y fixtures. |
 | `examples/` | Ejemplo mínimo de spec/slice. |
@@ -255,40 +304,73 @@ Para IA sin `--dry-run`, la autenticación depende del proveedor local que uses
 ## 🧭 Comandos principales
 
 Los comandos reales del CLI se ejecutan con `npx create-quiver ...` o, durante desarrollo local, con `node bin/create-quiver.js ...`.
+El paquete también publica el alias binario `quiver`, que apunta al mismo CLI. Usalo cuando el paquete ya esté instalado localmente; para bootstrap remoto, seguí usando `npx create-quiver`.
 
 | Comando | Para qué sirve |
 |---|---|
 | `npx create-quiver init --name "Proyecto"` | Inicializa Quiver en un proyecto nuevo o nunca inicializado. |
 | `npx create-quiver --name "Proyecto"` | Alias compatible del flujo de init recomendado. |
+| `npx create-quiver flow` | Muestra el estado inicial del flujo guiado y el próximo comando seguro sin escribir estado ni llamar providers. |
+| `npx create-quiver ai agent set <role> --provider <provider> --model <label>` | Guarda perfiles reutilizables para planner, executor, reviewer o researcher sin guardar secretos. |
+| `npx create-quiver ai agent list` | Lista los perfiles configurados. |
+| `npx create-quiver ai agent show <role>` | Muestra un perfil específico. |
+| `npx create-quiver ai approvals` | Muestra drafts versionados y aprobados por fase. |
+| `npx create-quiver ai approve --phase acceptance --version <n>` | Aprueba una versión concreta de un draft guardado. |
 | `npx create-quiver init --minimal` | Crea solo el contrato esencial de onboarding. |
 | `npx create-quiver init --full` | Crea el layout amplio de compatibilidad. |
 | `npx create-quiver init --legacy-scripts` | Agrega wrappers Bash legacy bajo `tools/scripts/`. |
 | `npx create-quiver init --include-templates` | Exporta templates empaquetados bajo `.quiver/templates/`. |
 | `npx create-quiver analyze` | Genera `.quiver/scans/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md`. |
 | `npx create-quiver doctor` | Valida que el contrato de Quiver esté completo. |
+| `npx create-quiver doctor --fix --dry-run` | Muestra reparaciones seguras sin escribir archivos. |
+| `npx create-quiver doctor --fix` | Aplica reparaciones no destructivas e idempotentes. |
+| `npx create-quiver prepare --dry-run` | Ejecuta diagnóstico guiado de preparación sin escribir archivos. |
+| `npx create-quiver prepare` | Refresca contexto y muestra riesgos, supuestos y próximos comandos. |
+| `npx create-quiver ai prepare-context --dry-run` | Previsualiza borradores de contexto IA, supuestos, riesgos, archivos considerados y rutas omitidas sin escribir. |
 | `npx create-quiver migrate` | Actualiza proyectos que ya fueron inicializados con Quiver. |
 | `npx create-quiver plan` | Lista slices pendientes en orden y calcula camino crítico. |
 | `npx create-quiver graph` | Muestra el grafo de dependencias (`tree`, `mermaid` o `dot`). |
 | `npx create-quiver next` | Sugiere el próximo slice listo para trabajar. |
+| `npx create-quiver plan --include-completed` | Muestra slices completados para auditoría o demos. |
+| `npx create-quiver graph --include-completed` | Incluye slices completados en el grafo histórico. |
+| `npx create-quiver next --include-completed` | Mantiene la recomendación accionable y agrega historial completado. |
+| `npx create-quiver spec create` | Crea la spec real desde el plan técnico revisado y aprobado. |
+| `npx create-quiver spec start <spec-dir>` | Crea o reutiliza el worktree dedicado de una spec. |
+| `npx create-quiver spec status <spec-dir>` | Muestra branch, path, `slice-00` y slices pendientes. |
+| `npx create-quiver spec close <spec-dir>` | Cierra un worktree de spec ya mergeado y limpio. |
 | `npx create-quiver start-slice <slice.json>` | Prepara worktree y contexto para ejecutar un slice. |
 | `npx create-quiver check-slice <slice.json>` | Valida readiness del slice. |
+| `npx create-quiver check-slice --local <slice.json>` | Valida estructura local sin exigir remoto/base. |
 | `npx create-quiver check-pr <slice.json>` | Valida estructura esperada para PR. |
 | `npx create-quiver check-scope <slice.json>` | Verifica que los archivos modificados estén dentro del alcance declarado. |
 | `npx create-quiver cleanup-slice <slice.json>` | Limpia worktree/branch local asociado a un slice. |
 | `npx create-quiver refresh-active-slices` | Regenera el tablero local `ACTIVE_SLICES.md`. |
 | `npx create-quiver check-handoff <handoff.md>` | Valida un handoff. |
 | `npx create-quiver new-handoff <spec-slug>` | Crea un handoff para una transferencia excepcional. |
+| `npx create-quiver evidence run -- <comando>` | Ejecuta un comando y guarda evidencia local con exit code, duración y salida redactada/truncada. |
+| `npx create-quiver demo create spec-viewer --dry-run` | Previsualiza el demo opcional Quiver Spec Viewer sin escribir archivos. |
+| `npx create-quiver demo create spec-viewer --dir <target>` | Crea el demo estático con app, spec, slices, handoffs y validación. |
 
 ### Comandos de IA para WDD + SDD
 
 ```bash
+npx create-quiver ai prepare-context --dry-run
 npx create-quiver ai onboard --dry-run
+npx create-quiver ai agent set planner --provider codex --model "planner-model"
+npx create-quiver ai agent set executor --provider codex --model "executor-model"
+npx create-quiver ai agent list
 npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
-npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run
-npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
-npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+npx create-quiver ai approve --phase acceptance --input acceptance-approved.md
+npx create-quiver ai plan --phase technical-plan --dry-run
+npx create-quiver ai review-plan --dry-run
+npx create-quiver ai approve --phase technical-plan --version <n>
+npx create-quiver spec create --dry-run
+npx create-quiver ai prompt-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run --commit
+npx create-quiver ai execute-plan --dry-run --commit --mode manual
+npx create-quiver ai execute-plan --dry-run --commit --mode delegated
 npx create-quiver ai doctor --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
-npx create-quiver ai pr --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npx create-quiver ai pr --dry-run --input specs/<project-slug>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 ```
 
 Providers soportados: `codex`, `claude` y `gemini`, siempre vía CLI local.
@@ -296,12 +378,18 @@ Usá `--dry-run` primero para revisar provider, rol, context pack, prompt y path
 
 Orden recomendado:
 
-1. `ai onboard`: el planner entiende el repo y el workflow.
-2. `ai plan --phase acceptance`: convierte requerimientos en criterios de aceptación.
-3. `ai plan --phase technical-plan`: propone el plan técnico.
-4. `ai plan --phase spec`: genera spec, slices, handoffs y PR body.
-5. `ai execute-slice`: ejecuta un slice aprobado con rol executor.
-6. `ai doctor` / `ai pr`: valida preflight de GitHub y PR.
+1. `ai prepare-context --dry-run`: revisa borradores de contexto, supuestos y riesgos antes de escribir docs.
+2. `ai onboard`: el planner entiende el repo y el workflow.
+3. `ai plan --phase acceptance`: convierte requerimientos en criterios de aceptación.
+4. `ai plan --phase technical-plan`: propone el plan técnico.
+5. `ai review-plan`: revisa el plan como si fuera a producción, sin tocar código ni cuestionar el alcance aprobado.
+6. `ai approve`: guarda criterios o la versión revisada del plan técnico.
+7. `spec create`: genera spec, slices, handoffs y PR body desde el plan revisado y aprobado.
+8. `spec start`: prepara un worktree por spec.
+9. `ai prompt-slice`: imprime el prompt mínimo para asignar un slice manualmente.
+10. `ai execute-slice` / `ai execute-plan`: ejecuta slices aprobados, con commit opt-in. Usá `--mode manual` para prompts y `--mode delegated` para worktrees temporales en olas paralelas.
+11. `ai doctor` / `ai pr`: valida GitHub y crea el PR solo con `--create`.
+12. `spec close`: cierra el worktree después del merge.
 
 ## 🧪 Cómo probar que funciona
 
@@ -311,35 +399,70 @@ Validación rápida del repo:
 node bin/create-quiver.js --help
 node --test tests/**/*.test.js
 npm run package:quiver
+npm pack --dry-run
 ```
 
 Validaciones adicionales disponibles:
 
 ```bash
 npm run smoke:create-quiver
+npm run smoke:guided-workflow
 npm run smoke:tiered-pack
 ```
 
+Para dejar evidencia resumida de una validación sin pegar logs completos:
+
+```bash
+npx create-quiver evidence run -- npm test
+```
+
+Por defecto la evidencia queda en `.quiver/evidence/`. También podés elegir destino con `--output <archivo>` y limitar stdout/stderr con `--max-output <n>`.
+
+Para probar Quiver sin inventar una app desde cero:
+
+```bash
+npx create-quiver demo create spec-viewer --dry-run
+npx create-quiver demo create spec-viewer --dir ./quiver-spec-viewer
+```
+
+El demo genera una app estática pequeña, specs/slices de ejemplo y scripts de validación. No forma parte de `init`; se crea solo cuando lo pedís.
+
 Notas reales del estado actual:
 
 - No hay script `npm test`; el comando verificado para tests es `node --test tests/**/*.test.js`.
 - `npm run package:quiver` valida el contenido del paquete npm generado.
-- `npm run smoke:tiered-pack` existe, pero revisar la sección "Información pendiente de confirmar" antes de usarlo como gate obligatorio.
+- `npm run smoke:guided-workflow` cubre el flujo guiado con IA sin llamadas reales pagas a providers.
 
 ## 📜 Scripts npm
 
 | Script | Uso |
 |---|---|
+| `npm run quiver:analyze` | Ejecuta `npx create-quiver analyze`. |
+| `npm run quiver:flow` | Ejecuta `npx create-quiver flow`. |
 | `npm run quiver:plan` | Ejecuta `npx create-quiver plan`. |
+| `npm run quiver:prepare` | Ejecuta preparación guiada y diagnósticos. |
 | `npm run quiver:graph` | Ejecuta `npx create-quiver graph`. |
 | `npm run quiver:next` | Ejecuta `npx create-quiver next`. |
+| `npm run quiver:doctor` | Ejecuta `npx create-quiver doctor`. |
+| `npm run quiver:evidence` | Ejecuta `npx create-quiver evidence`; usalo como `npm run quiver:evidence -- run -- <comando>`. |
+| `npm run quiver:ai:agent` | Ejecuta `npx create-quiver ai agent`. |
 | `npm run quiver:ai:onboard` | Ejecuta onboarding de IA. |
+| `npm run quiver:ai:prepare-context` | Prepara borradores de contexto IA solo en documentación; usalo primero con `-- --dry-run`. |
 | `npm run quiver:ai:plan` | Ejecuta planificación IA por fases. |
+| `npm run quiver:ai:review-plan` | Revisa el plan técnico antes de aprobarlo y crear la spec. |
+| `npm run quiver:ai:approve` | Guarda criterios o planes aprobados. |
+| `npm run quiver:ai:prompt-slice` | Imprime un prompt mínimo para asignar un slice a un executor. |
 | `npm run quiver:ai:execute-slice` | Ejecuta un slice con rol executor. |
+| `npm run quiver:ai:execute-plan` | Imprime o ejecuta olas de slices; soporta `--mode manual` y `--mode delegated`. |
 | `npm run quiver:ai:doctor` | Ejecuta preflight IA/GitHub. |
-| `npm run quiver:ai:pr` | Ejecuta preflight de PR. |
+| `npm run quiver:ai:pr` | Ejecuta preflight de PR y crea PR con `--create`. |
+| `npm run quiver:spec:create` | Ejecuta `npx create-quiver spec create`. |
+| `npm run quiver:spec:start` | Ejecuta `npx create-quiver spec start`. |
+| `npm run quiver:spec:status` | Ejecuta `npx create-quiver spec status`. |
+| `npm run quiver:spec:close` | Ejecuta `npx create-quiver spec close`. |
 | `npm run package:quiver` | Empaqueta y valida el tarball npm. |
 | `npm run smoke:create-quiver` | Smoke del instalador `create-quiver`. |
+| `npm run smoke:guided-workflow` | Smoke del flujo guiado con IA, PR, cleanup y package safety. |
 | `npm run smoke:tiered-pack` | Smoke de context packs y lifecycle. |
 | `npm run release:quiver` | Release dry-run o publish, según flags. |
 
@@ -350,12 +473,15 @@ Notas reales del estado actual:
 1. Inicializá Quiver o migrá si el proyecto ya lo tenía.
 2. Corré `analyze` para generar el mapa técnico.
 3. Corré `doctor` para validar el contrato.
-4. Incorporá al planner con `ai onboard --dry-run`.
-5. Convertí requerimientos en criterios, plan técnico y spec con `ai plan`.
-6. Revisá dependencias con `graph` y elegí el próximo trabajo con `next`.
-7. Ejecutá el slice con `ai execute-slice` o con tu agente usando el handoff generado.
-8. Validá con `check-slice`, `check-scope` y `check-pr`.
-9. Cerrá el trabajo con evidencia en el PR.
+4. Prepará contexto IA con `ai prepare-context --dry-run` y revisá los supuestos antes de escribir.
+5. Incorporá al planner con `ai onboard --dry-run`.
+6. Convertí requerimientos en criterios, plan técnico y spec con `ai plan`; revisá el plan con `ai review-plan` antes de aprobarlo.
+7. Creá la spec real con `spec create` y prepará su worktree con `spec start`.
+8. Revisá dependencias con `graph`, `next` o `ai execute-plan --dry-run --mode manual`.
+9. Para ejecución manual, generá el prompt con `ai prompt-slice --slice <slice.json> --dry-run`.
+10. Ejecutá slices con `ai execute-slice --commit` o `ai execute-plan --execute --commit --mode delegated`.
+11. Abrí el PR con `ai pr --create` después de revisar el dry-run.
+12. Después del merge, cerrá el worktree con `spec close`.
 
 ## 🤝 Contribuir
 
@@ -392,6 +518,15 @@ npm whoami
 npm view create-quiver version
 ```
 
+Checklist de release:
+
+1. `node --test tests/**/*.test.js`
+2. `npm run smoke:create-quiver`
+3. `npm run smoke:guided-workflow`
+4. `npm run smoke:tiered-pack`
+5. `npm pack --dry-run`
+6. Confirmar que el PR esta aprobado antes de publicar.
+
 ## 📚 Documentación útil
 
 - [README para agentes de IA](./README_FOR_AI.md)
@@ -402,11 +537,11 @@ npm view create-quiver version
 - [Contribución](./CONTRIBUTING.md)
 - [Seguridad](./SECURITY.md)
 
-## Información pendiente de confirmar
+## Información confirmada y pendiente
 
+- `package.json` está en `0.10.0` y `CHANGELOG.md` reconoce `0.10.0`.
 - `package.json` no declara `engines`; la versión mínima real de Node queda pendiente. La CI usa Node 22.
-- `package.json` está en `0.9.0`, igual que `CHANGELOG.md`.
-- `docs/COMMANDS.md.template` marca algunos comandos de IA como `v0.10`, aunque `package.json` todavía está en `0.9.0`; la próxima publicación debe alinear versión y changelog.
+- Si aparece alguna referencia vieja a `0.9.0`, hay que actualizarla al contrato actual antes de seguir.
 - Los scripts legacy de `package.json` que apuntan a `tools/scripts/*` deben confirmarse para este repo fuente o separarse de los scripts pensados para proyectos generados con `--legacy-scripts` o `--full`.
 
 ## Licencia