create-quiver 0.9.0 → 0.9.1

package/README.md

@@ -1,190 +1,427 @@
 # Quiver
 
-Quiver is a CLI-first documentation workflow for projects that use specs, slices, and AI-assisted implementation.
+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.
 
-It gives a project a repeatable structure for planning work, starting focused implementation slices, validating readiness, and keeping human and AI contributors aligned.
+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.
 
-## Developer Onboarding Flow
+## ¿Qué es Quiver?
 
-Use this flow when adopting Quiver in an existing project or starting a new one.
+Quiver es un workflow de documentación para proyectos de software.
 
-### 1. Install Quiver
+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.
 
-Run Quiver from the project where the workflow will live:
+Ayuda a:
 
-```bash
-cd /path/to/your-project
-npx create-quiver --name "Project Name"
-```
+- 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
 
-Do not install Quiver globally. Running it with `npx` from the project root keeps the generated docs, specs, and scripts in the right repository.
+Usá este camino cuando estás empezando un proyecto y querés sumar Quiver desde el principio.
 
-If your team wants to pin the Quiver version in the project, install it as a devDependency:
+1. Creá o entrá a la carpeta del proyecto.
 
 ```bash
-npm install --save-dev create-quiver
-npx create-quiver --name "Project Name"
+mkdir mi-proyecto
+cd mi-proyecto
 ```
 
-To initialize a different directory from outside the project, pass `--dir` explicitly. Quote paths that contain spaces:
+2. Inicializá Quiver con el nombre del proyecto.
 
 ```bash
-npx create-quiver --name "Project Name" --dir "/Users/me/My Project"
+npx create-quiver --name "Mi Proyecto"
 ```
 
-### 2. Analyze And Validate
+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.
 
-Run the local analyzer and then validate the generated contract from the project root:
+3. Analizá el proyecto.
 
 ```bash
 npx create-quiver analyze
-npx create-quiver graph
+```
+
+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 next
 ```
 
-Use `npx create-quiver graph --format mermaid` for PR-ready Markdown or `npx create-quiver graph --format dot` for Graphviz source.
+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.
+
+No modifiques código de producto salvo autorización explícita. Puedes crear o actualizar documentación de contexto si el onboarding lo requiere.
 
-If you need to target another directory from outside the project, pass `--dir` explicitly. For the current project root, omit it.
+Usa solo la documentación del repositorio como fuente de verdad. Si encuentras información faltante, ambigua o contradictoria, documenta el supuesto, el riesgo y continúa por el camino más seguro.
+
+Responde en español y finaliza con un reporte breve de archivos leídos, archivos modificados, estado del código de producto, supuestos, riesgos y próximos pasos.
+```
 
-The analyzer creates `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md`. These files give the AI agent a deterministic project map before it edits context docs.
+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.
 
-The doctor checks the generated project contract and prints the next workflow steps. If the scan artifacts are missing, it recommends `npx create-quiver analyze` first.
-`npx create-quiver next` prints the next ready slice and can auto-start it behind a confirmation prompt.
+### Caso 2: Proyecto ya comenzado
 
-### Project NPM Scripts
+Usá este camino cuando el proyecto ya existe, pero nunca fue inicializado con Quiver.
 
-Generated projects include `quiver:*` npm scripts that call the Node CLI and are the preferred repeatable workflow:
+1. Revisá el estado actual antes de tocar nada.
 
 ```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: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
+git status --short
 ```
 
-`npm run quiver:graph` prints the tree view by default. Pass `--format mermaid` or `--format dot` when you need an exportable graph artifact.
-`npm run quiver:next` points to the next ready slice and can auto-start it behind a confirmation prompt.
-`npx create-quiver next --all-ready` shows the full ready level when you want the whole queue instead of one slice.
+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.
 
-The legacy Bash wrappers remain in `tools/scripts/` for compatibility, but new project-level automation should prefer the `quiver:*` scripts and the direct `npx create-quiver ...` commands.
-`npm run quiver:migrate` is only for projects that were already initialized by Quiver.
+```bash
+npx create-quiver --name "Nombre del Proyecto"
+```
 
-### 3. Upgrade Existing Projects
+No uses `migrate` si el proyecto nunca tuvo Quiver. `migrate` es solo para proyectos ya inicializados por una versión anterior.
 
-If the project already had Quiver from an older version, upgrade it from the project root:
+3. Analizá el repo real.
 
 ```bash
-cd /path/to/your-project
-npx create-quiver migrate
 npx create-quiver analyze
-npx create-quiver graph
+```
+
+Esto detecta stack, package manager, comandos y archivos relevantes.
+
+4. Corré el doctor.
+
+```bash
 npx create-quiver doctor
-npx create-quiver next
 ```
 
-Use `npx create-quiver graph --format mermaid` for GitHub-friendly graph embeds or `npx create-quiver graph --format dot` for Graphviz pipelines.
+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
+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.
+
+### Caso 3: Proyecto ya comenzado con una versión vieja de Quiver
+
+Usá este camino cuando el proyecto ya tiene archivos de Quiver, pero pueden estar desactualizados.
+
+1. Buscá señales de una instalación previa.
 
-If the project never ran Quiver initialization before, do not use `migrate` as bootstrap. Run:
+Revisá si existen archivos como:
+
+- `.quiver/state.json`
+- `docs/AI_CONTEXT.md`
+- `docs/PROJECT_MAP.md`
+- `docs-template/`
+- `tools/scripts/`
+- scripts `quiver:*` en `package.json`
+
+2. Ejecutá el doctor para conocer el estado.
 
 ```bash
-npx create-quiver --name "Project Name"
+npx create-quiver doctor
 ```
 
-If your team prefers a pinned local dependency, update the package first and then run the same flow:
+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
-npm install --save-dev create-quiver@latest
 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 graph
 npx create-quiver doctor
 ```
 
-The tree output remains the default, but Mermaid and DOT are available on demand for exported docs and slide decks.
+5. Revisá el diff antes de continuar con slices.
+
+```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.
 
-### 4. Ask The AI To Prepare Context
+## Flujo de trabajo recomendado con WDD y SDD
 
-Open your AI agent in the target project and run this short handoff:
+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:
 
-```text
-Read docs/AI_ONBOARDING_PROMPT.md and execute it.
-Do not modify product code unless I explicitly authorize it.
-Prepare the project context docs and report assumptions, risks, and files changed.
+- **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]
 ```
 
-The AI should use the scan artifacts to prepare `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md`, `docs/STATUS.md`, and the initial project spec. The developer should review those documentation changes before implementation work starts.
+### 1. Instalar o migrar Quiver
 
-### 5. Start The First Slice
+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.
 
-After the context docs are reviewed:
+### 2. Analizar el proyecto
 
-1. Define or refine `specs/<project-slug>/SPEC.md`.
-2. Create the first slice from `specs/<project-slug>/slices/slice-template/slice.json`.
-3. Start work with `npx create-quiver start-slice <slice.json>` or `npm run quiver:start-slice -- <slice.json>`.
-4. Make one commit per slice.
-5. Open one PR per spec.
+Ejecutá:
 
-Slice numbering is local to each spec: every new spec starts at `slice-01`.
+```bash
+npx create-quiver analyze
+```
+
+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
 
-## Requirements
+Antes de implementar, revisá y completá la documentación de contexto:
 
-- Node.js and npm for the installer
-- Git for slice branches, worktrees, and PR workflow checks
-- macOS, Linux, and Windows PowerShell/CMD are the target developer environments for the cross-platform runtime work
+- `AGENTS.md`
+- `docs/AI_CONTEXT.md`
+- `docs/AI_ONBOARDING_PROMPT.md`
+- `docs/CONTEXTO.md`
+- `docs/WORKFLOW.md`
+- `docs/STATUS.md`
+- `docs/DECISIONS.md`
 
-Windows native support is verified only when the cross-platform CI matrix is green. Bash remains a legacy compatibility path until the runtime slices land.
+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.
 
-See the generated `docs/SUPPORT_MATRIX.md` for the detailed support contract.
+### 4. Definir o revisar spec SDD
 
-## Cross-Platform Support
+Trabajá sobre `specs/<project-slug>/SPEC.md`.
 
-Quiver is targeting native support on macOS, Linux, and Windows PowerShell/CMD. Bash is a legacy compatibility path until the runtime slices land, so the long-term contract is a Node-first workflow rather than a Bash-first one. The CI matrix must be green before Windows is considered fully verified.
+La spec debe explicar:
 
-## What Gets Generated
+- 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.
 
-Quiver generates a project-local workflow under:
+### 5. Elegir el próximo slice
 
-- `docs/` for project context, workflow, support, troubleshooting, and AI guidance
-- `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md` after `create-quiver analyze`
-- `docs/AI_ONBOARDING_PROMPT.md` as the generated handoff prompt for the AI agent
-- `specs/<project-slug>/HANDOFF.md` as the exceptional transfer artifact between agents or phases
-- `npx create-quiver new-handoff <spec-slug>` to scaffold an optional handoff artifact when work needs to move between agents or phases
-- `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md` to validate a transferred handoff before execution
-- `docs/COMMANDS.md` as the canonical command reference table for orchestration
-- `specs/<project-slug>/` for the project spec, status, evidence, and slice contracts
-- `tools/scripts/` for slice lifecycle and readiness gates
-- `.github/` for default PR, issue, and CI templates
-- `package.json` scripts for the workflow commands
+Usá los comandos de orquestación:
 
-For the detailed support contract, read `docs/SUPPORT_MATRIX.md` in the generated project. For recovery paths, read `docs/TROUBLESHOOTING.md`.
+```bash
+npx create-quiver plan
+npx create-quiver graph
+npx create-quiver next
+```
 
-## Manual Template Use
+`plan` muestra el orden sugerido. `graph` muestra dependencias. `next` señala el próximo slice listo.
 
-Use the manual flow only when developing Quiver locally or testing a template checkout. From a target project where this repository was copied as `docs-template/`, run:
+### 6. Empezar el slice
+
+Cuando el slice esté definido:
 
 ```bash
-./docs-template/scripts/init-docs.sh "Project Name"
+npx create-quiver start-slice specs/<project-slug>/slices/slice-01/slice.json
 ```
 
-The CLI path is the supported adoption path for users.
-For analyzed projects, the agent handoff prompt lives at `docs/AI_ONBOARDING_PROMPT.md` in the generated project. If a bounded transfer between agents or phases is needed, scaffold `specs/<project-slug>/HANDOFF.md` with `npx create-quiver new-handoff <spec-slug>` and validate it with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md`.
+Cada spec vuelve a empezar en `slice-01`. El número del slice es local a esa spec, no global del repo.
 
-## For AI Agents
+### 7. Implementar y validar
 
-Read `README_FOR_AI.md` before working in this repository or in a generated project. In generated projects, `docs/AI_CONTEXT.md` is the first agent context file to read, followed by `docs/AI_ONBOARDING_PROMPT.md`, `docs/CONTEXTO.md`, and `docs/WORKFLOW.md`.
+Durante la implementación, leé primero el `slice.json`, los archivos declarados, pruebas cercanas y código directamente relacionado.
 
-## For Maintainers
+Validá el slice y el PR:
 
-Release preflight:
+```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
+```
+
+Si querés validar que los archivos tocados respetan el alcance declarado:
+
+```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
+```
+
+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:
 
 ```bash
 npm whoami
@@ -194,33 +431,30 @@ npm run smoke:create-quiver
 npm run release:quiver
 ```
 
-Current-version publish:
+Publicar la versión actual:
 
 ```bash
 bash scripts/release-quiver.sh --publish-current
 ```
 
-Versioned publish:
+Publicar con bump de versión:
 
 ```bash
 bash scripts/release-quiver.sh patch --publish
 ```
 
-The release helper stays explicit on purpose: `--publish-current` publishes the current version, and `--publish` follows a normal version bump flow.
-
-If `npm whoami` or `npm view create-quiver version` fails, fix npm auth or registry reachability before publishing.
-
-For a first release, prefer `--publish-current` so the published package stays at `0.4.0`.
+Si `npm whoami` o `npm view create-quiver version` falla, primero resolvé autenticación o conectividad con npm.
 
-## References
+## Referencias
 
-- [AI guide](./README_FOR_AI.md)
-- [AI context template](./docs/AI_CONTEXT.md.template)
-- [Support matrix template](./docs/SUPPORT_MATRIX.md.template)
-- [Troubleshooting template](./docs/TROUBLESHOOTING.md.template)
+- [Guía para IA](./README_FOR_AI.md)
 - [Changelog](./CHANGELOG.md)
 - [Roadmap](./ROADMAP.md)
+- [Backlog](./BACKLOG.md)
+- [Template customization](./TEMPLATE.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Security](./SECURITY.md)
 
-## License
+## Licencia
 
 MIT

package/README_FOR_AI.md

@@ -17,6 +17,7 @@ The project map is the single source of truth for stack, package manager, comman
 The universal router for generated projects is `AGENTS.md`; read it before `docs/AI_CONTEXT.md` and `docs/AI_ONBOARDING_PROMPT.md`.
 Generated projects also get `docs/DECISIONS.md`; use it for durable choices that should not be re-litigated.
 If a generated project has been analyzed, the exact agent handoff prompt is `docs/AI_ONBOARDING_PROMPT.md`.
+Keep README copy-paste prompts short; the detailed onboarding contract lives in `docs/AI_ONBOARDING_PROMPT.md` generated from `docs/AI_ONBOARDING_PROMPT.md.template`.
 If a new bounded transfer is needed, scaffold `specs/<project-slug>/HANDOFF.md` with `npx create-quiver new-handoff <spec-slug>` and validate it with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md`.
 Use `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md` to validate a transferred handoff before execution.
 During onboarding, after reading `ROADMAP.md`, also read `BACKLOG.md` in the repository root: it tracks emerging patterns that are not yet scoped as specs. Before proposing a new spec, confirm the idea is not already parked or emerging there.
@@ -25,8 +26,8 @@ During onboarding, after reading `ROADMAP.md`, also read `BACKLOG.md` in the rep
 
 Use the smallest context that still answers the current task.
 
-- **Onboarding:** start from `docs/PROJECT_MAP.md`, `docs/PROJECT_SCAN.json`, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before opening source files.
-- **Onboarding router:** start from `AGENTS.md` first, then the onboarding files above.
+- **Onboarding:** start from `README.md`, `AGENTS.md` when present, `docs/PROJECT_MAP.md`, `docs/PROJECT_SCAN.json`, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before opening source files.
+- **Onboarding router:** start from `README.md` and `AGENTS.md` first, then the onboarding files above.
 - **Implementation:** start from `docs/ai/ACTIVE_SLICE.md` when it exists; otherwise start from `specs/<project-slug>/slices/<slice-id>/slice.json`, then read only the declared files, nearby tests, and directly related source.
 - **Handoff:** start from `specs/<project-slug>/HANDOFF.md` when the work was explicitly transferred through a handoff artifact.
 - **Handoff scaffold:** if no handoff exists yet and the work needs one, use `npx create-quiver new-handoff <spec-slug>` first.

package/ROADMAP.md

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

package/docs/AI_ONBOARDING_PROMPT.md.template

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

package/docs/COMMANDS.md.template

@@ -4,22 +4,33 @@
 **Last updated:** {{FECHA}}
 
 This document is the canonical command reference for the orchestration roadmap.
-It is intentionally small at v0.18: only the plan and graph rows are reserved for now, but `quiver:graph` already supports tree, Mermaid, and DOT output modes.
 
 ## Command Table
 
 | Command | Purpose | OS | Since | Example |
 |---------|---------|----|-------|---------|
-| `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.18 | [docs/examples/plan.md](./examples/plan.md) |
-| `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.18 | [docs/examples/graph.md](./examples/graph.md) |
-| `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.18 | [docs/examples/next.md](./examples/next.md) |
+| `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.8 | [docs/examples/plan.md](./examples/plan.md) |
+| `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.8 | [docs/examples/graph.md](./examples/graph.md) |
+| `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.8 | [docs/examples/next.md](./examples/next.md) |
+
+## CLI Flags
+
+| Flag | Applies to | Purpose |
+|------|------------|---------|
+| `--skip-install` | `init`, `migrate` | Skip auto-install of `create-quiver` as dev dependency (useful for CI) |
+| `--json` | `plan`, `graph`, `next` | Emit machine-readable JSON |
+| `--format <tree\|mermaid\|dot>` | `graph` | Output format |
+| `--all-ready` | `next` | List all ready slices instead of just the next one |
+| `--only-ready` | `plan` | Show only slices with no pending dependencies |
+| `--spec <slug>` | `plan`, `graph` | Restrict output to one spec |
 
 ## Notes
 
 - Add new rows here only when a command is officially shipped.
 - Keep the table concise and cross-platform.
 - Shared graph library: `src/create-quiver/lib/slice-graph.js`.
-- `quiver:graph --format mermaid` is the PR-friendly export; `--format dot` is for Graphviz consumers.
+- `quiver:graph --format mermaid` is the PR-friendly Mermaid export; `--format dot` is for Graphviz/DOT consumers.
 - `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
-- `check-slice` now validates optional `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is set to `never`.
+- `check-slice` validates `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is `never`.
+- After `init` or `migrate`, Quiver auto-installs itself as a dev dependency. Use `--skip-install` to suppress.
 - Cross-platform authoring rules live in `docs/SUPPORT_MATRIX.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",

package/scripts/init-docs.sh

@@ -587,9 +587,15 @@ Lee \`AGENTS.md\` primero y después \`docs/AI_ONBOARDING_PROMPT.md\` tras el an
 After analysis and doctor validation, open your AI agent in this project and run:
 
 \`\`\`text
-Read docs/AI_ONBOARDING_PROMPT.md and execute it.
-Do not modify product code unless I explicitly authorize it.
-Prepare the project context docs and report assumptions, risks, and files changed.
+Lee \`docs/AI_ONBOARDING_PROMPT.md\` y ejecútalo como fuente principal de verdad para incorporarte a este repositorio.
+
+Actúa como asistente de onboarding de IA. Prepara el contexto del proyecto para trabajar de forma segura con el workflow documentado, specs y slices.
+
+No modifiques código de producto salvo autorización explícita. Puedes crear o actualizar documentación de contexto si el onboarding lo requiere.
+
+Usa solo la documentación del repositorio como fuente de verdad. Si encuentras información faltante, ambigua o contradictoria, documenta el supuesto, el riesgo y continúa por el camino más seguro.
+
+Responde en español y finaliza con un reporte breve de archivos leídos, archivos modificados, estado del código de producto, supuestos, riesgos y próximos pasos.
 \`\`\`
 
 Review the AI changes to docs/AI_CONTEXT.md, docs/CONTEXTO.md, docs/STATUS.md, and specs/$PROJECT_SLUG/SPEC.md before starting implementation work.

package/specs/quiver-v19-self-install-dev-dep/EVIDENCE_REPORT.md

@@ -2,13 +2,13 @@
 
 **Spec:** quiver-v19-self-install-dev-dep
 **Date:** 2026-05-14
-**Status:** In Progress
+**Status:** Completed
 
 ## Slice Evidence
 
 | Slice | Status | Evidence |
 |-------|--------|----------|
-| slice-01 | Ready | — |
+| slice-01 | Completed | PR #60 merged 2026-05-14. 40/40 tests pass. Smoke: `--skip-install` no instala, sin flag instala `create-quiver@0.9.0` + `devDependencies: {"create-quiver":"^0.9.0"}`. `npx create-quiver plan` exit 0 sin `@version`. Published as `create-quiver@0.9.0`. |
 
 ## Required Final Evidence
 

package/specs/quiver-v19-self-install-dev-dep/STATUS.md

@@ -7,14 +7,14 @@
 
 | Slice | Title | Status | PR | Estimated hours | Actual hours |
 |-------|-------|--------|----|-----------------|--------------|
-| slice-01 | Auto-install create-quiver as dev dependency | Ready | — | 1.5 | — |
+| slice-01 | Auto-install create-quiver as dev dependency | Completed | #60 | 1.5 | 1.0 |
 
 ## Progress
 
-- Completed slices: 0 / 1
+- Completed slices: 1 / 1
 - Estimated hours: 1.5
-- Actual hours: —
+- Actual hours: 1.0
 
 ## Blockers
 
-None.
+None — spec complete.

package/specs/quiver-v19-self-install-dev-dep/slices/slice-01-auto-install-dev-dep/slice.json

@@ -47,10 +47,10 @@
     "npx create-quiver --skip-install --name test --dir /tmp/quiver-test-skip && ls /tmp/quiver-test-skip/node_modules/create-quiver 2>/dev/null && echo FAIL || echo OK"
   ],
   "estimated_hours": 1.5,
-  "actual_hours": null,
-  "status": "ready",
+  "actual_hours": 1,
+  "status": "completed",
   "blocked_reason": null,
   "ready_at": "2026-05-14T00:00:00Z",
-  "started_at": null,
-  "completed_at": null
+  "started_at": "2026-05-14T00:00:00Z",
+  "completed_at": "2026-05-14T00:00:00Z"
 }

package/src/create-quiver/index.js

@@ -1138,7 +1138,7 @@ function runAnalyze(targetDir) {
   console.log(`Detected package manager: ${scan.project.package_manager}`);
 }
 
-function runMigrate(targetDir) {
+function runMigrate(targetDir, options = {}) {
   const projectRoot = resolveTargetRoot(process.cwd(), targetDir);
 
   if (!fs.existsSync(projectRoot)) {
@@ -1165,7 +1165,7 @@ function runMigrate(targetDir) {
     });
     updateStateForMigrate(projectRoot, projectName, CLI_VERSION);
 
-    if (!args.skipInstall) {
+    if (!options.skipInstall) {
       const installResult = installSelfAsDevDep(projectRoot, CLI_VERSION);
       if (installResult === 'installed') {
         console.log(`Added create-quiver@${CLI_VERSION} as dev dependency`);
@@ -1350,7 +1350,7 @@ async function run(argv) {
   }
 
   if (args.mode === 'migrate') {
-    runMigrate(args.targetDir);
+    runMigrate(args.targetDir, { skipInstall: args.skipInstall });
     return;
   }
 

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

@@ -335,9 +335,15 @@ Read \`AGENTS.md\` first, then open \`docs/AI_ONBOARDING_PROMPT.md\` after analy
 After analysis and doctor validation, open your AI agent in this project and run:
 
 \`\`\`text
-Read docs/AI_ONBOARDING_PROMPT.md and execute it.
-Do not modify product code unless I explicitly authorize it.
-Prepare the project context docs and report assumptions, risks, and files changed.
+Lee \`docs/AI_ONBOARDING_PROMPT.md\` y ejecútalo como fuente principal de verdad para incorporarte a este repositorio.
+
+Actúa como asistente de onboarding de IA. Prepara el contexto del proyecto para trabajar de forma segura con el workflow documentado, specs y slices.
+
+No modifiques código de producto salvo autorización explícita. Puedes crear o actualizar documentación de contexto si el onboarding lo requiere.
+
+Usa solo la documentación del repositorio como fuente de verdad. Si encuentras información faltante, ambigua o contradictoria, documenta el supuesto, el riesgo y continúa por el camino más seguro.
+
+Responde en español y finaliza con un reporte breve de archivos leídos, archivos modificados, estado del código de producto, supuestos, riesgos y próximos pasos.
 \`\`\`
 
 Review the AI changes to docs/AI_CONTEXT.md, docs/CONTEXTO.md, docs/STATUS.md, and specs/${projectSlug}/SPEC.md before starting implementation work. Use \`docs/PROJECT_MAP.md\` for stack and command details.

package/.claude/settings.local.json

@@ -1,52 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git fetch *)",
-      "Bash(git checkout *)",
-      "Bash(git add *)",
-      "Bash(git commit -m ' *)",
-      "Bash(git cherry-pick *)",
-      "Bash(git reset *)",
-      "Bash(gh pr create --title 'docs: register v17-v22 orchestration plan and park web console idea' --base main --head docs/register-orchestration-plan-park-web-console --body ' *)",
-      "Bash(gh auth *)",
-      "Bash(gh pr *)",
-      "Bash(node -e \"const g=require\\('./src/create-quiver/lib/slice-graph'\\); const slices=g.readAllSlices\\('.'\\); console.log\\('Total slices:', slices.length\\); const graph=g.buildGraph\\(slices\\); const levels=g.computeLevels\\(graph\\); console.log\\('Levels:', levels.length\\);\")",
-      "Bash(npx . plan)",
-      "Bash(git pull *)",
-      "Read(//Users/fabrijk/Documents/Work/Proyectos Personales/nika/frameworks/.worktrees/quiver/bugfix-QUIVER-01-fix-legacy-dependency-resolution/**)",
-      "Bash(node --test tests/)",
-      "Bash(node --test tests/**/*.test.js)",
-      "Bash(node bin/create-quiver.js plan)",
-      "Bash(echo \"EXIT_$?\")",
-      "Bash(node bin/create-quiver.js plan --json)",
-      "Bash(node -e \"const d=JSON.parse\\(require\\('fs'\\).readFileSync\\('/dev/stdin','utf8'\\)\\); console.log\\('plan items:', Array.isArray\\(d.plan\\) ? d.plan.length : 'NOT ARRAY'\\); console.log\\('critical_path:', Array.isArray\\(d.critical_path\\)\\); console.log\\('total_hours:', typeof d.total_hours\\); process.exit\\(Array.isArray\\(d.plan\\) && Array.isArray\\(d.critical_path\\) && typeof d.total_hours === 'number' ? 0 : 1\\)\")",
-      "Bash(grep -v \"^\\\\-\\\\-$\")",
-      "Bash(echo \"EXIT:$?\")",
-      "Bash(node -e \"const d=JSON.parse\\(require\\('fs'\\).readFileSync\\('/tmp/plan_json.txt','utf8'\\)\\); console.log\\('plan:', Array.isArray\\(d.plan\\) ? d.plan.length + ' items' : 'INVALID'\\); console.log\\('critical_path:', Array.isArray\\(d.critical_path\\)\\); console.log\\('total_hours:', typeof d.total_hours\\)\")",
-      "Bash(xargs git branch -d)",
-      "Bash(git branch *)",
-      "Read(//private/tmp/**)",
-      "Read(//Users/fabrijk/Documents/Work/Proyectos Personales/nika/frameworks/quiver-v18-slice02/**)",
-      "Bash(git worktree *)",
-      "Bash(git ls-remote *)",
-      "Bash(node *)",
-      "Bash(npm view *)",
-      "Bash(bash scripts/release-quiver.sh)",
-      "Bash(git stash *)",
-      "Bash(npm whoami *)",
-      "Bash(bash scripts/release-quiver.sh --publish-current)",
-      "Bash(npm pkg *)",
-      "Bash(NPM_TOKEN=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 npm publish --access public)",
-      "Bash(NPM_TOKEN=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 npm publish --access public)",
-      "Bash(npm info *)",
-      "Bash(npm publish *)",
-      "Bash(rm -rf /tmp/quiver-skip-test)",
-      "Bash(mkdir -p /tmp/quiver-skip-test)",
-      "Bash(echo '{\"name\":\"test\",\"scripts\":{}}')",
-      "Bash(ls /tmp/quiver-skip-test/node_modules/create-quiver)",
-      "Bash(rm -rf /tmp/quiver-install-test)",
-      "Bash(mkdir -p /tmp/quiver-install-test)",
-      "Bash(npm config *)"
-    ]
-  }
-}