create-quiver 0.9.1 → 0.10.0

package/README.md

@@ -1,433 +1,375 @@
 # 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.
-
-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.
-
-Quiver existe porque el caos también compila. A veces. Pero después alguien tiene que entenderlo.
-
-## ¿Qué problema resuelve?
-
-En muchos proyectos, el trabajo empieza con una pregunta sencilla: "¿por dónde arranco?"
-
-El problema es que la respuesta suele estar repartida en demasiados lugares:
-
-- 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.
-
-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.
-
-## ¿Cómo lo resuelve?
-
-Quiver agrega una estructura de trabajo al proyecto.
-
-Esa estructura separa tres cosas que suelen mezclarse:
-
-- **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.
-
-Al inicializarse, Quiver genera documentos y comandos para que el proyecto tenga un contrato de trabajo repetible.
-
-Los conceptos principales son:
-
-- **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`.
-
-La regla práctica es: primero contexto, después plan, después código.
-
-## Primeros pasos
-
-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.
-
-### Caso 1: Proyecto nuevo desde cero
-
-Usá este camino cuando estás empezando un proyecto y querés sumar Quiver desde el principio.
-
-1. Creá o entrá a la carpeta del proyecto.
+Ejecutá Quiver desde la raíz del proyecto donde querés instalar el workflow:
 
 ```bash
-mkdir mi-proyecto
-cd mi-proyecto
+npx create-quiver init --name "Mi Proyecto"
+npx create-quiver analyze
+npx create-quiver doctor
+npx create-quiver ai onboard --dry-run
 ```
 
-2. Inicializá Quiver con el nombre del proyecto.
+Después de eso, revisá:
 
-```bash
-npx create-quiver --name "Mi Proyecto"
-```
+- `AGENTS.md`
+- `docs/PROJECT_MAP.md`
+- `docs/AI_CONTEXT.md`
+- `docs/AI_ONBOARDING_PROMPT.md`
 
-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.
+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`.
 
-3. Analizá el proyecto.
+El flujo normal con IA continúa así:
 
 ```bash
-npx create-quiver analyze
+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 next
+npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
 ```
 
-Esto genera `docs/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md`. Esos archivos ayudan a humanos y agentes a entender el repo sin adivinar.
+Usá `--dry-run` para validar provider, rol, contexto y paths sin ejecutar el modelo. Cuando el output esté revisado y aprobado, quitá `--dry-run`.
 
-4. Validá el contrato generado.
+### Desarrollar este repositorio
 
 ```bash
-npx create-quiver doctor
+git clone <repo-url>
+cd quiver
+npm install
+node bin/create-quiver.js --help
+node --test tests/**/*.test.js
 ```
 
-El doctor revisa si falta algo importante y muestra los próximos pasos recomendados.
+> 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.
 
-5. Leé el onboarding para agentes antes de pedir implementación.
+## 🧠 Workflow principal: WDD + SDD con IA
 
-```text
-Lee `docs/AI_ONBOARDING_PROMPT.md` y ejecútalo como fuente principal de verdad para incorporarte a este repositorio.
+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.
 
-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.
-
-No modifiques código de producto salvo autorización explícita. Puedes crear o actualizar documentación de contexto si el onboarding lo requiere.
+| 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 onboard`, `ai plan` |
+| IA executor | Agente que recibe un slice aprobado y trabaja con contexto mínimo. | `ai execute-slice`, `check-scope`, `check-slice` |
 
-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.
+Flujo recomendado:
 
-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 analyze
+npx create-quiver doctor
+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 graph
+npx create-quiver next
+npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
 ```
 
-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.
+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`.
 
-### Caso 2: Proyecto ya comenzado
+## 🛠️ Empezar a usar Quiver según tu caso
 
-Usá este camino cuando el proyecto ya existe, pero nunca fue inicializado con Quiver.
+### 1. Proyecto nuevo desde cero
 
-1. Revisá el estado actual antes de tocar nada.
+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
-git status --short
+mkdir mi-proyecto
+cd mi-proyecto
+npx create-quiver init --name "Mi Proyecto"
+npx create-quiver analyze
+npx create-quiver doctor
+npx create-quiver ai onboard --dry-run
 ```
 
-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"
-```
+Qué esperar:
 
-No uses `migrate` si el proyecto nunca tuvo Quiver. `migrate` es solo para proyectos ya inicializados por una versión anterior.
+- Quiver crea un contrato visible chico: `AGENTS.md`, `docs/`, 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.
 
-3. Analizá el repo real.
+Después del bootstrap, revisá:
 
 ```bash
-npx create-quiver analyze
+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 plan
+npx create-quiver graph
+npx create-quiver next
 ```
 
-Esto detecta stack, package manager, comandos y archivos relevantes.
+### 2. Proyecto ya iniciado sin Quiver
+
+Usá este camino cuando el repo ya tiene código, pero nunca fue inicializado con Quiver.
 
-4. Corré el doctor.
+Primero revisá el estado actual:
 
 ```bash
-npx create-quiver doctor
+git status --short
 ```
 
-El doctor indica si falta completar contexto, si conviene revisar el onboarding de IA o si hay pasos pendientes.
+Si hay cambios pendientes, conviene guardarlos, commitearlos o crear una rama dedicada para que el diff de onboarding sea fácil de revisar.
 
-5. Revisá el diff antes de seguir.
+Luego inicializá Quiver desde la raíz del proyecto:
 
 ```bash
+npx create-quiver init --name "Nombre del Proyecto"
+npx create-quiver analyze
+npx create-quiver doctor
+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 `ai plan --phase spec`, cuando ya existen criterios y plan técnico aprobados.
+- 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
-```
-
-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:
-
-```bash
-npx create-quiver migrate --skip-install
-```
-
-4. Volvé a analizar y validar.
-
-```bash
 npx create-quiver analyze
 npx create-quiver doctor
-```
-
-5. Revisá el diff antes de continuar con slices.
-
-```bash
+npx create-quiver ai onboard --dry-run
 git status --short
 ```
 
-Resultado esperado: el proyecto queda alineado con el contrato actual de Quiver sin mezclar migración con implementación de producto.
-
-## Flujo de trabajo recomendado con WDD y SDD
-
-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:
-
-- **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.
-
-```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]
-```
-
-### 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á:
+Si estás en CI, offline o no querés que la migración instale dependencias automáticamente:
 
 ```bash
-npx create-quiver analyze
+npx create-quiver migrate --skip-install
 ```
 
-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:
+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.
+
+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` -> `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 `ai plan --phase spec` 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 ...`.
+
+| 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 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 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 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-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. |
+
+### Comandos de IA para WDD + SDD
 
 ```bash
-npx create-quiver plan
-npx create-quiver graph
-npx create-quiver next
+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 execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+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
 ```
 
-`plan` muestra el orden sugerido. `graph` muestra dependencias. `next` señala el próximo slice listo.
+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.
 
-### 6. Empezar el slice
+Orden recomendado:
 
-Cuando el slice esté definido:
+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.
 
-```bash
-npx create-quiver start-slice specs/<project-slug>/slices/slice-01/slice.json
-```
-
-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
+## 🧪 Cómo probar que funciona
 
-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:
+Validación rápida del repo:
 
 ```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
+node bin/create-quiver.js --help
+node --test tests/**/*.test.js
+npm run package:quiver
 ```
 
-Si querés validar que los archivos tocados respetan el alcance declarado:
+Validaciones adicionales disponibles:
 
 ```bash
-npx create-quiver check-scope specs/<project-slug>/slices/slice-01/slice.json
-```
-
-### 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:
-
-```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
+npm run smoke:create-quiver
+npm run smoke:tiered-pack
 ```
 
-Los wrappers Bash en `tools/scripts/` existen por compatibilidad en proyectos generados. Para automatización nueva, preferí `npx create-quiver ...` o los scripts `quiver:*`.
+Notas reales del estado actual:
 
-## Qué genera Quiver
+- 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.
 
-Según el estado del proyecto y el modo usado, Quiver puede generar o actualizar:
+## 📜 Scripts npm
 
-- `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.
+| Script | Uso |
+|---|---|
+| `npm run quiver:plan` | Ejecuta `npx create-quiver plan`. |
+| `npm run quiver:graph` | Ejecuta `npx create-quiver graph`. |
+| `npm run quiver:next` | Ejecuta `npx create-quiver next`. |
+| `npm run quiver:ai:onboard` | Ejecuta onboarding de IA. |
+| `npm run quiver:ai:plan` | Ejecuta planificación IA por fases. |
+| `npm run quiver:ai:execute-slice` | Ejecuta un slice con rol executor. |
+| `npm run quiver:ai:doctor` | Ejecuta preflight IA/GitHub. |
+| `npm run quiver:ai:pr` | Ejecuta preflight de PR. |
+| `npm run package:quiver` | Empaqueta y valida el tarball npm. |
+| `npm run smoke:create-quiver` | Smoke del instalador `create-quiver`. |
+| `npm run smoke:tiered-pack` | Smoke de context packs y lifecycle. |
+| `npm run release:quiver` | Release dry-run o publish, según flags. |
 
-## Requisitos
+`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.
 
-- 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.
+## 🔁 Flujo recomendado
 
-Bash queda como camino de compatibilidad legacy para algunos wrappers. El contrato de largo plazo es Node-first.
+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.
 
-## Para agentes de IA
+## 🤝 Contribuir
 
-Si estás trabajando como agente dentro de este repo, leé primero `README_FOR_AI.md`.
+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.
 
-Si estás trabajando en un proyecto generado con Quiver, el orden recomendado es:
+## 🚢 Release
 
-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:
+Release dry-run:
 
 ```bash
-npm whoami
-npm view create-quiver version
-npm run package:quiver
-npm run smoke:create-quiver
 npm run release:quiver
 ```
 
@@ -437,23 +379,35 @@ Publicar la versión actual:
 bash scripts/release-quiver.sh --publish-current
 ```
 
-Publicar con bump de versión:
+Publicar con bump:
 
 ```bash
 bash scripts/release-quiver.sh patch --publish
 ```
 
-Si `npm whoami` o `npm view create-quiver version` falla, primero resolvé autenticación o conectividad con npm.
+Antes de publicar, verificá autenticación y estado del paquete:
 
-## Referencias
+```bash
+npm whoami
+npm view create-quiver version
+```
+
+## 📚 Documentación útil
 
-- [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 pendiente de confirmar
+
+- `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.
+- 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