create-quiver 0.9.1 → 0.12.0

package/README.md

@@ -1,459 +1,548 @@
 # Quiver
 
-Quiver es una herramienta de línea de comandos para ordenar proyectos que trabajan con documentación, especificaciones, slices y ayuda de agentes de IA.
+Quiver es un framework para trabajar con **WDD + SDD asistido por IA** en proyectos de software.
+Ayuda a transformar un repositorio en un entorno donde humanos y agentes pueden entender el contexto, planificar por specs, ejecutar slices y revisar cambios con evidencia.
+Está pensado para equipos que quieren usar IA de forma ordenada: primero workflow, después specs, después implementación.
 
-Su objetivo es simple: que una persona o un agente puedan llegar a un repo, entender qué está pasando, elegir el próximo trabajo correcto y avanzar sin romper el flujo del equipo.
+## 🚀 Inicio rápido
 
-## ¿Qué es Quiver?
+### Usar Quiver con IA en un proyecto
 
-Quiver es un workflow de documentación para proyectos de software.
+Ejecutá Quiver desde la raíz del proyecto donde querés instalar el workflow:
 
-Sirve para preparar un proyecto antes de implementar: crea una estructura de documentos, comandos y convenciones para que el trabajo no dependa de memoria, chats perdidos o instrucciones sueltas.
-
-Ayuda a:
-
-- desarrolladores que quieren trabajar por piezas pequeñas y revisables;
-- equipos que usan IA para analizar, planificar o implementar;
-- maintainers que necesitan que cada cambio tenga contexto, alcance y evidencia;
-- agentes de IA que necesitan saber por dónde empezar sin leer todo el repo.
+```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
+```
 
-Quiver existe porque el caos también compila. A veces. Pero después alguien tiene que entenderlo.
+Después de eso, revisá:
 
-## ¿Qué problema resuelve?
+- `AGENTS.md`
+- `docs/PROJECT_MAP.md`
+- `docs/AI_CONTEXT.md`
+- `docs/AI_ONBOARDING_PROMPT.md`
 
-En muchos proyectos, el trabajo empieza con una pregunta sencilla: "¿por dónde arranco?"
+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 problema es que la respuesta suele estar repartida en demasiados lugares:
+El flujo normal con IA continúa así:
 
-- un README que no está actualizado;
-- tickets con contexto incompleto;
-- decisiones tomadas en conversaciones;
-- comandos que solo una persona conoce;
-- agentes de IA leyendo archivos de más o tocando archivos de menos;
-- PRs grandes donde es difícil saber qué se intentó hacer.
+```bash
+npx create-quiver flow
+npx create-quiver ai plan --phase acceptance --input requirements.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-plan --dry-run --commit --mode manual
+npx create-quiver ai execute-plan --dry-run --commit --mode delegated
+```
 
-Quiver busca reducir esa fricción. No intenta reemplazar al equipo ni decidir por él. Lo que hace es ordenar el terreno para que el siguiente paso sea claro.
+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.
 
-## ¿Cómo lo resuelve?
+### Compatibilidad: macOS, Linux y Windows
 
-Quiver agrega una estructura de trabajo al proyecto.
+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.
 
-Esa estructura separa tres cosas que suelen mezclarse:
+Reglas prácticas por sistema:
 
-- **Contexto:** qué es el proyecto, cómo se trabaja y qué comandos existen.
-- **Plan:** qué problema se quiere resolver y en qué partes se divide.
-- **Ejecución:** qué slice se está trabajando, qué archivos puede tocar y cómo se valida.
+- 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:*`.
 
-Al inicializarse, Quiver genera documentos y comandos para que el proyecto tenga un contrato de trabajo repetible.
+Cuando uses GitHub o PRs:
 
-Los conceptos principales son:
+- `--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`.
 
-- **Spec:** documento que describe un objetivo de trabajo. Define el problema, alcance, estado y evidencia esperada.
-- **Slice:** parte pequeña de una spec. Un slice debe ser lo bastante acotado como para implementarse, validarse y revisarse sin mezclar temas.
-- **Project map:** resumen generado por Quiver con stack, package manager, comandos y pistas del repo. Vive en `docs/PROJECT_MAP.md`.
-- **AI context:** paquete de contexto para agentes de IA. Vive en `docs/AI_CONTEXT.md`.
-- **Handoff:** documento excepcional para transferir contexto entre agentes o fases. Vive en `specs/<spec-slug>/HANDOFF.md`.
+### Desarrollar este repositorio
 
-La regla práctica es: primero contexto, después plan, después código.
+```bash
+git clone <repo-url>
+cd quiver
+npm install
+node bin/create-quiver.js --help
+node --test tests/**/*.test.js
+```
 
-## Primeros pasos
+> El remote local detectado usa un alias SSH (`git@github-personal:FabriJuncal/quiver.git`). Si no tenés ese alias configurado, cloná con la URL que use tu equipo.
 
-Quiver se usa desde la raíz del proyecto donde querés instalar el workflow. No se recomienda instalarlo globalmente. Usá `npx create-quiver` o, si el equipo necesita fijar versión, una dev dependency local.
+## 🧠 Workflow principal: WDD + SDD con IA
 
-### Caso 1: Proyecto nuevo desde cero
+Quiver asume que la mayoría de los equipos lo van a usar para coordinar trabajo con agentes de IA. Por eso el flujo principal no empieza por código: empieza por contexto, workflow y planificación.
 
-Usá este camino cuando estás empezando un proyecto y querés sumar Quiver desde el principio.
+| Etapa | Qué significa | Artefactos principales |
+|---|---|---|
+| 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 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` |
 
-1. Creá o entrá a la carpeta del proyecto.
+Flujo recomendado:
 
 ```bash
-mkdir mi-proyecto
-cd mi-proyecto
+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 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 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
 ```
 
-2. Inicializá Quiver con el nombre del proyecto.
+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`.
 
-```bash
-npx create-quiver --name "Mi Proyecto"
-```
+## 🛠️ Empezar a usar Quiver según tu caso
 
-Esto crea la estructura base de documentación y workflow. Después de inicializar, Quiver intenta instalarse como dev dependency del proyecto para que los comandos futuros resuelvan a la versión local.
+### 1. Proyecto nuevo desde cero
 
-3. Analizá el proyecto.
+Usá este camino cuando todavía no existe el proyecto o estás arrancando una carpeta nueva y querés que Quiver acompañe el workflow desde el primer commit.
 
 ```bash
+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
-```
-
-Esto genera `docs/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md`. Esos archivos ayudan a humanos y agentes a entender el repo sin adivinar.
-
-4. Validá el contrato generado.
-
-```bash
 npx create-quiver doctor
+npx create-quiver ai prepare-context --dry-run
+npx create-quiver ai onboard --dry-run
 ```
 
-El doctor revisa si falta algo importante y muestra los próximos pasos recomendados.
-
-5. Leé el onboarding para agentes antes de pedir implementación.
-
-```text
-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.
+Qué esperar:
 
-No modifiques código de producto salvo autorización explícita. Puedes crear o actualizar documentación de contexto si el onboarding lo requiere.
+- 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 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.
 
-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.
+Después del bootstrap, revisá:
 
-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.
+```bash
+npx create-quiver ai plan --phase acceptance --input requirements.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
 ```
 
-Resultado esperado: el proyecto queda con `docs/`, `specs/<project-slug>/`, scripts `quiver:*` en `package.json`, archivos de soporte y una primera base para planificar trabajo.
+### 2. Proyecto ya iniciado sin Quiver
 
-### Caso 2: Proyecto ya comenzado
+Usá este camino cuando el repo ya tiene código, pero nunca fue inicializado con Quiver.
 
-Usá este camino cuando el proyecto ya existe, pero nunca fue inicializado con Quiver.
-
-1. Revisá el estado actual antes de tocar nada.
+Primero revisá el estado actual:
 
 ```bash
 git status --short
 ```
 
-Si hay cambios pendientes, conviene commitearlos, guardarlos o crear una rama dedicada para incorporar Quiver. La idea es que el diff de onboarding sea fácil de revisar.
-
-2. Inicializá Quiver desde la raíz del proyecto.
-
-```bash
-npx create-quiver --name "Nombre del Proyecto"
-```
-
-No uses `migrate` si el proyecto nunca tuvo Quiver. `migrate` es solo para proyectos ya inicializados por una versión anterior.
+Si hay cambios pendientes, conviene guardarlos, commitearlos o crear una rama dedicada para que el diff de onboarding sea fácil de revisar.
 
-3. Analizá el repo real.
+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
-```
-
-Esto detecta stack, package manager, comandos y archivos relevantes.
-
-4. Corré el doctor.
-
-```bash
 npx create-quiver doctor
-```
-
-El doctor indica si falta completar contexto, si conviene revisar el onboarding de IA o si hay pasos pendientes.
-
-5. Revisá el diff antes de seguir.
-
-```bash
+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
 ```
 
-Resultado esperado: Quiver agrega o actualiza archivos de workflow y documentación. No debería ser el momento de cambiar código de producto; primero se estabiliza el contexto.
+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 `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.
 
-### Caso 3: Proyecto ya comenzado con una versión vieja de Quiver
+Importante: no uses `migrate` para un proyecto que nunca tuvo Quiver. `migrate` es solo para proyectos previamente inicializados.
 
-Usá este camino cuando el proyecto ya tiene archivos de Quiver, pero pueden estar desactualizados.
+### 3. Proyecto iniciado con una versión vieja de Quiver
 
-1. Buscá señales de una instalación previa.
+Usá este camino cuando el repo ya tiene señales de Quiver, pero querés actualizarlo al contrato actual.
 
-Revisá si existen archivos como:
+Señales típicas de una instalación previa:
 
 - `.quiver/state.json`
+- `AGENTS.md`
 - `docs/AI_CONTEXT.md`
 - `docs/PROJECT_MAP.md`
-- `docs-template/`
-- `tools/scripts/`
-- scripts `quiver:*` en `package.json`
+- `docs-template/` como señal legacy u opcional
+- `tools/scripts/` como señal legacy u opcional
+- scripts `quiver:*` o scripts legacy en `package.json`
 
-2. Ejecutá el doctor para conocer el estado.
+Desde la raíz del proyecto:
 
 ```bash
 npx create-quiver doctor
-```
-
-Si el proyecto necesita migración, el doctor debería indicarlo.
-
-3. Migrá solo si el proyecto ya había sido inicializado por Quiver.
-
-```bash
 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
 ```
 
-La migración actualiza el contrato de Quiver y agrega scripts o archivos faltantes de forma aditiva. Si estás en CI, offline o no querés instalar dependencias durante la migración, podés usar:
+Si estás en CI, offline o no querés que la migración instale dependencias automáticamente:
 
 ```bash
 npx create-quiver migrate --skip-install
 ```
 
-4. Volvé a analizar y validar.
+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 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.
+
+## ✨ Qué hace
+
+Quiver instala una estructura de trabajo para que un proyecto pueda usar IA sin improvisar contexto en cada tarea:
+
+- documentación base para humanos y agentes;
+- contexto AI-first con roles de planner y executor;
+- specs y slices para dividir trabajo en partes revisables;
+- comandos para planificar, ejecutar y validar trabajo asistido por IA;
+- checks de readiness, PR, handoff y scope;
+- plantillas de contribución, soporte, seguridad, changelog y GitHub Actions.
+
+La idea práctica: primero contexto, después plan, después código.
+
+## 🧱 Stack tecnológico
+
+| Área | Tecnología detectada |
+|---|---|
+| Runtime | Node.js CLI |
+| Lenguaje | JavaScript CommonJS |
+| Package manager | npm (`package-lock.json`) |
+| 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` |
+| Base de datos | No detectada |
+| Docker / Compose | No detectado |
+| Prisma / Supabase / migrations / seeders | No detectados |
+
+## 📦 Requisitos
+
+- Node.js 22.x recomendado. La CI usa Node 22, aunque `package.json` todavía no declara `engines`.
+- npm.
+- Git, especialmente para ramas y worktrees.
+- `shellcheck` si querés replicar localmente el job de CI que valida scripts Bash.
+- Opcional: `gh` para preflight de PR con GitHub.
+- CLI local de `codex`, `claude` o `gemini` si vas a ejecutar comandos de IA sin `--dry-run`.
+
+No se detectaron archivos `.env`; Quiver no requiere variables de entorno para el flujo básico.
+
+## 📁 Estructura del proyecto
+
+| Ruta | Propósito |
+|---|---|
+| `bin/create-quiver.js` | Entry point ejecutable del CLI. |
+| `src/create-quiver/` | Código fuente del CLI y comandos principales. |
+| `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 `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. |
+| `i18n/es/` | Documentación y plantillas en español. |
+| `.github/` | Workflows, templates de issues y PR. |
+
+## ⚙️ Configuración
+
+### Variables opcionales
+
+| Variable | Uso |
+|---|---|
+| `SLICE_WORKTREES_DIR` | Cambia la carpeta donde `start-slice` crea worktrees. |
+| `ALLOW_DRAFT_SLICE=1` | Permite iniciar slices en estado `draft`. Equivale a usar `--allow-draft`. |
+| `QUIVER_VERSION` | Usada por scripts legacy de inicialización. |
+| `QUIVER_MIGRATE` | Activa modo migración en scripts legacy. |
+| `QUIVER_PROJECT_NAME` | Define nombre de proyecto en scripts legacy. |
+
+Para IA sin `--dry-run`, la autenticación depende del proveedor local que uses (`codex`, `claude` o `gemini`). Para PR preflight, Quiver espera que `gh` y tu configuración SSH ya existan; no instala ni modifica credenciales.
+
+## 🧭 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 analyze
-npx create-quiver doctor
+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 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 --input specs/<project-slug>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 ```
 
-5. Revisá el diff antes de continuar con slices.
+Providers soportados: `codex`, `claude` y `gemini`, siempre vía CLI local.
+Usá `--dry-run` primero para revisar provider, rol, context pack, prompt y paths sin ejecutar el modelo.
 
-```bash
-git status --short
-```
-
-Resultado esperado: el proyecto queda alineado con el contrato actual de Quiver sin mezclar migración con implementación de producto.
+Orden recomendado:
 
-## Flujo de trabajo recomendado con WDD y SDD
+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.
 
-El repositorio no define formalmente las siglas WDD y SDD como comandos propios. En esta guía las usamos para nombrar dos prácticas que Quiver ya promueve:
+## 🧪 Cómo probar que funciona
 
-- **WDD, Workflow-Driven Development:** primero se documenta cómo se trabaja. El workflow, comandos, contexto y reglas quedan escritos antes de pedir cambios de producto.
-- **SDD, Spec-Driven Development:** el trabajo se define en specs y slices antes de implementar. La spec explica el objetivo; el slice limita el alcance.
+Validación rápida del repo:
 
-```mermaid
-flowchart TD
-    A[1. Instalar o migrar Quiver] --> B[2. Analizar el proyecto]
-    B --> C[3. Completar contexto WDD]
-    C --> D[4. Definir o revisar spec SDD]
-    D --> E[5. Elegir el próximo slice]
-    E --> F[6. Empezar el slice]
-    F --> G[7. Implementar y validar]
-    G --> H[8. Abrir PR con evidencia]
+```bash
+node bin/create-quiver.js --help
+node --test tests/**/*.test.js
+npm run package:quiver
+npm pack --dry-run
 ```
 
-### 1. Instalar o migrar Quiver
-
-Usá `npx create-quiver --name "Proyecto"` para proyectos nuevos o nunca inicializados. Usá `npx create-quiver migrate` solo cuando el proyecto ya tenía Quiver.
-
-### 2. Analizar el proyecto
-
-Ejecutá:
+Validaciones adicionales disponibles:
 
 ```bash
-npx create-quiver analyze
+npm run smoke:create-quiver
+npm run smoke:guided-workflow
+npm run smoke:tiered-pack
 ```
 
-El resultado importante es `docs/PROJECT_MAP.md`, que debe tratarse como fuente de verdad para stack, package manager, comandos y pistas de archivos.
-
-### 3. Completar contexto WDD
-
-Antes de implementar, revisá y completá la documentación de contexto:
-
-- `AGENTS.md`
-- `docs/AI_CONTEXT.md`
-- `docs/AI_ONBOARDING_PROMPT.md`
-- `docs/CONTEXTO.md`
-- `docs/WORKFLOW.md`
-- `docs/STATUS.md`
-- `docs/DECISIONS.md`
-
-Si un agente de IA participa, primero debe preparar contexto y reportar supuestos. No debería tocar código de producto sin autorización explícita.
-
-### 4. Definir o revisar spec SDD
-
-Trabajá sobre `specs/<project-slug>/SPEC.md`.
-
-La spec debe explicar:
-
-- qué problema se quiere resolver;
-- qué entra y qué queda afuera;
-- qué evidencia va a demostrar que el trabajo terminó;
-- cómo se divide en slices.
-
-### 5. Elegir el próximo slice
-
-Usá los comandos de orquestación:
+Para dejar evidencia resumida de una validación sin pegar logs completos:
 
 ```bash
-npx create-quiver plan
-npx create-quiver graph
-npx create-quiver next
+npx create-quiver evidence run -- npm test
 ```
 
-`plan` muestra el orden sugerido. `graph` muestra dependencias. `next` señala el próximo slice listo.
+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>`.
 
-### 6. Empezar el slice
-
-Cuando el slice esté definido:
+Para probar Quiver sin inventar una app desde cero:
 
 ```bash
-npx create-quiver start-slice specs/<project-slug>/slices/slice-01/slice.json
+npx create-quiver demo create spec-viewer --dry-run
+npx create-quiver demo create spec-viewer --dir ./quiver-spec-viewer
 ```
 
-Cada spec vuelve a empezar en `slice-01`. El número del slice es local a esa spec, no global del repo.
-
-### 7. Implementar y validar
-
-Durante la implementación, leé primero el `slice.json`, los archivos declarados, pruebas cercanas y código directamente relacionado.
-
-Validá el slice y el PR:
+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: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 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. |
+
+`package.json` también contiene scripts legacy como `check:slice`, `check:pr`, `start:slice`, `cleanup:slice` y `migrate` que apuntan a `tools/scripts/*`. En proyectos generados esos wrappers aparecen solo cuando se pide compatibilidad con `--legacy-scripts` o el perfil amplio `--full`; en este repo fuente requieren revisión antes de usarse directamente.
+
+## 🔁 Flujo recomendado
+
+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. 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
+
+1. Abrí un issue describiendo el problema o propuesta.
+2. Acordá el alcance antes de implementar si hace falta.
+3. Trabajá en un slice pequeño y revisable.
+4. Incluí evidencia de validación en el PR.
+5. Mantené una relación clara: un slice, un commit; una spec, un PR.
+
+## 🚢 Release
+
+Release dry-run:
 
 ```bash
-npx create-quiver check-slice specs/<project-slug>/slices/slice-01/slice.json
-npx create-quiver check-pr specs/<project-slug>/slices/slice-01/slice.json
+npm run release:quiver
 ```
 
-Si querés validar que los archivos tocados respetan el alcance declarado:
+Publicar la versión actual:
 
 ```bash
-npx create-quiver check-scope specs/<project-slug>/slices/slice-01/slice.json
+bash scripts/release-quiver.sh --publish-current
 ```
 
-### 8. Abrir PR con evidencia
-
-La regla del workflow es:
-
-- un slice = un commit;
-- una spec = un PR;
-- cada PR debe incluir evidencia de validación;
-- las decisiones durables van en `docs/DECISIONS.md`;
-- los aprendizajes reutilizables pueden registrarse en `docs/ai/LESSONS.md`.
-
-## Comandos disponibles
-
-Los comandos principales se ejecutan con `npx create-quiver ...`. En proyectos generados, también quedan disponibles scripts `npm run quiver:*` que llaman al CLI Node.
-
-### Inicialización y mantenimiento del workflow
-
-| Comando | Para qué sirve | Cuándo usarlo |
-|---|---|---|
-| `npx create-quiver --name "Proyecto"` | Inicializa Quiver en el proyecto actual. | Proyecto nuevo o proyecto existente que nunca tuvo Quiver. |
-| `npx create-quiver --name "Proyecto" --dir ./ruta` | Inicializa o inspecciona otra carpeta explícitamente. | Cuando no estás parado en la raíz del proyecto destino. |
-| `npx create-quiver migrate` | Actualiza una instalación previa de Quiver. | Solo en proyectos que ya fueron inicializados por Quiver. |
-| `npx create-quiver migrate --skip-install` | Migra sin instalar `create-quiver` como dev dependency. | CI, entornos offline o migraciones donde no querés tocar dependencias. |
-| `npx create-quiver doctor` | Valida el contrato generado y muestra pasos siguientes. | Después de init, migrate o analyze. |
-
-### Análisis y contexto
-
-| Comando | Para qué sirve | Resultado esperado |
-|---|---|---|
-| `npx create-quiver analyze` | Escanea el proyecto y genera contexto técnico. | `docs/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md`. |
-| `npx create-quiver check-handoff specs/<spec-slug>/HANDOFF.md` | Valida que un handoff exista en la ubicación correcta y tenga secciones requeridas. | Confirmación o errores accionables. |
-| `npx create-quiver new-handoff <spec-slug>` | Crea un `HANDOFF.md` para una transferencia excepcional. | `specs/<spec-slug>/HANDOFF.md`. |
-
-### Planificación y orquestación de slices
-
-| Comando | Para qué sirve | Flags útiles |
-|---|---|---|
-| `npx create-quiver plan` | Lista slices pendientes en orden de ejecución y calcula camino crítico. | `--json`, `--only-ready`, `--spec <slug>` |
-| `npx create-quiver graph` | Muestra el grafo de dependencias entre slices. | `--format mermaid`, `--format dot`, `--show-conflicts`, `--level <n>` |
-| `npx create-quiver next` | Muestra el próximo slice listo para trabajar. | `--all-ready`, `--json`, `--auto-start` |
-
-### Ejecución y validación
-
-| Comando | Para qué sirve | Cuándo usarlo |
-|---|---|---|
-| `npx create-quiver start-slice <slice.json>` | Prepara el trabajo de un slice. | Al comenzar una unidad de trabajo. |
-| `npx create-quiver start-slice --allow-draft <slice.json>` | Permite iniciar un slice en estado draft intencionalmente. | Solo cuando el equipo decide trabajar sobre un draft. |
-| `npx create-quiver check-slice <slice.json>` | Valida readiness del slice. | Antes o durante la ejecución. |
-| `npx create-quiver check-slice --gate validation <slice.json>` | Valida el slice en modo cierre. | Antes de marcarlo como completado. |
-| `npx create-quiver check-pr <slice.json>` | Valida que el PR tenga la estructura esperada. | Antes de abrir o pedir review. |
-| `npx create-quiver check-scope <slice.json>` | Revisa que los archivos tocados estén dentro del alcance declarado. | Antes de cerrar el slice. |
-| `npx create-quiver cleanup-slice <slice.json>` | Limpia estado local asociado a un slice. | Al terminar o descartar trabajo local. |
-| `npx create-quiver refresh-active-slices` | Regenera el tablero local de slices activos. | Cuando querés ver o refrescar actividad local. |
-
-### Scripts npm generados
-
-Después de inicializar o migrar, los proyectos quedan con scripts equivalentes:
+Publicar con bump:
 
 ```bash
-npm run quiver:analyze
-npm run quiver:plan
-npm run quiver:graph
-npm run quiver:next
-npm run quiver:doctor
-npm run quiver:migrate
-npm run quiver:start-slice -- specs/<project-slug>/slices/slice-01/slice.json
-npm run quiver:check-slice -- specs/<project-slug>/slices/slice-01/slice.json
-npm run quiver:check-pr -- specs/<project-slug>/slices/slice-01/slice.json
-npm run quiver:check-handoff -- specs/<project-slug>/HANDOFF.md
-npm run quiver:cleanup-slice -- specs/<project-slug>/slices/slice-01/slice.json
-npm run quiver:check-scope -- specs/<project-slug>/slices/slice-01/slice.json
-npm run quiver:refresh-active-slices
+bash scripts/release-quiver.sh patch --publish
 ```
 
-Los wrappers Bash en `tools/scripts/` existen por compatibilidad en proyectos generados. Para automatización nueva, preferí `npx create-quiver ...` o los scripts `quiver:*`.
-
-## Qué genera Quiver
-
-Según el estado del proyecto y el modo usado, Quiver puede generar o actualizar:
-
-- `AGENTS.md`
-- `docs/`
-- `docs/ai/`
-- `docs/AI_CONTEXT.md`
-- `docs/AI_ONBOARDING_PROMPT.md`
-- `docs/PROJECT_SCAN.json`
-- `docs/PROJECT_MAP.md`
-- `docs/DECISIONS.md`
-- `docs/COMMANDS.md`
-- `specs/<project-slug>/`
-- `specs/<project-slug>/HANDOFF.md`
-- `tools/scripts/`
-- `.github/`
-- scripts `quiver:*` en `package.json`
-
-No todos los proyectos necesitan todos los archivos opcionales. Si un archivo no existe, no lo des por hecho: crealo desde la plantilla o registrá que falta.
-
-## Requisitos
-
-- Node.js y npm para ejecutar el instalador.
-- Git para branches, worktrees y validaciones de PR.
-- macOS, Linux o Windows PowerShell/CMD como entornos objetivo del runtime Node.
-
-Bash queda como camino de compatibilidad legacy para algunos wrappers. El contrato de largo plazo es Node-first.
-
-## Para agentes de IA
-
-Si estás trabajando como agente dentro de este repo, leé primero `README_FOR_AI.md`.
-
-Si estás trabajando en un proyecto generado con Quiver, el orden recomendado es:
-
-1. `AGENTS.md`
-2. `docs/PROJECT_MAP.md`
-3. `docs/PROJECT_SCAN.json`
-4. `docs/AI_CONTEXT.md`
-5. `docs/AI_ONBOARDING_PROMPT.md`
-
-Para implementar, no abras todo el repo por costumbre. Empezá por el `slice.json`, los archivos declarados, pruebas cercanas y código directamente relacionado.
-
-## Para maintainers de Quiver
-
-Comandos útiles para preparar releases del paquete:
+Antes de publicar, verificá autenticación y estado del paquete:
 
 ```bash
 npm whoami
 npm view create-quiver version
-npm run package:quiver
-npm run smoke:create-quiver
-npm run release:quiver
 ```
 
-Publicar la versión actual:
+Checklist de release:
 
-```bash
-bash scripts/release-quiver.sh --publish-current
-```
-
-Publicar con bump de versión:
+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.
 
-```bash
-bash scripts/release-quiver.sh patch --publish
-```
+## 📚 Documentación útil
 
-Si `npm whoami` o `npm view create-quiver version` falla, primero resolvé autenticación o conectividad con npm.
-
-## Referencias
-
-- [Guía para IA](./README_FOR_AI.md)
+- [README para agentes de IA](./README_FOR_AI.md)
 - [Changelog](./CHANGELOG.md)
 - [Roadmap](./ROADMAP.md)
 - [Backlog](./BACKLOG.md)
-- [Template customization](./TEMPLATE.md)
-- [Contributing](./CONTRIBUTING.md)
-- [Security](./SECURITY.md)
+- [Guía de templates](./TEMPLATE.md)
+- [Contribución](./CONTRIBUTING.md)
+- [Seguridad](./SECURITY.md)
+
+## 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.
+- 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