create-quiver 0.14.0 → 0.15.0

package/docs/workflows/full-ai-spec-to-pr.md

@@ -0,0 +1,311 @@
+# Flujo completo de IA: de requerimiento a PR
+
+Esta guía cubre el flujo completo de Quiver desde un requerimiento hasta un pull request abierto.
+
+Ejecutá los comandos desde la raíz del proyecto.
+
+## 1. Confirmar estado del proyecto
+
+```bash
+git status -sb
+npx --yes create-quiver@latest flow
+npx --yes create-quiver@latest doctor
+```
+
+Qué hace:
+
+- revisa el estado local de Git;
+- le pide a Quiver el próximo paso seguro;
+- valida el contrato del proyecto.
+
+## 2. Crear un archivo de requerimiento
+
+```bash
+mkdir -p requirements
+$EDITOR requirements/mi-requerimiento.md
+```
+
+Qué hace:
+
+- crea una entrada durable para el planner;
+- evita perder el requerimiento en el historial del chat.
+
+## 3. Crear una ejecución de IA
+
+```bash
+npx --yes create-quiver@latest ai run create --input requirements/mi-requerimiento.md
+npx --yes create-quiver@latest ai status
+```
+
+Qué hace:
+
+- crea estado persistente en `.quiver/runs/`;
+- muestra la fase actual y el próximo comando seguro.
+
+## 4. Generar criterios de aceptación
+
+```bash
+npx --yes create-quiver@latest ai plan --phase acceptance --input requirements/mi-requerimiento.md --dry-run
+npx --yes create-quiver@latest ai plan --phase acceptance --input requirements/mi-requerimiento.md
+```
+
+Si querés revisar y confirmar el borrador antes de guardarlo:
+
+```bash
+npx --yes create-quiver@latest ai plan --phase acceptance --input requirements/mi-requerimiento.md --review --interactive
+```
+
+Qué hace:
+
+- previsualiza la invocación al proveedor;
+- le pide al planner un borrador de criterios de aceptación.
+
+Revisar borradores:
+
+```bash
+npx --yes create-quiver@latest ai approvals
+```
+
+Aprobar una versión:
+
+```bash
+npx --yes create-quiver@latest ai approve --phase acceptance --version <n>
+```
+
+Qué hace:
+
+- guarda los criterios aprobados como entrada para el plan técnico.
+
+## 5. Iterar criterios cuando haga falta
+
+```bash
+npx --yes create-quiver@latest ai revise --phase acceptance --input feedback.md --dry-run
+npx --yes create-quiver@latest ai revise --phase acceptance --input feedback.md
+```
+
+Qué hace:
+
+- crea un nuevo borrador sin aprobarlo automáticamente;
+- mantiene explícita la compuerta de aprobación humana.
+
+## 6. Generar el plan técnico
+
+```bash
+npx --yes create-quiver@latest ai plan --phase technical-plan --dry-run
+npx --yes create-quiver@latest ai plan --phase technical-plan
+```
+
+Si querés editar el borrador antes de guardarlo:
+
+```bash
+npx --yes create-quiver@latest ai plan --phase technical-plan --review --interactive
+```
+
+Qué hace:
+
+- genera un plan técnico desde los criterios aprobados;
+- exige información estructurada de slices para poder crear specs después.
+
+## 7. Revisar el plan técnico
+
+```bash
+npx --yes create-quiver@latest ai review-plan --dry-run
+npx --yes create-quiver@latest ai review-plan
+```
+
+Qué hace:
+
+- revisa el plan como si fuera a implementarse y probarse en producción;
+- guarda metadata de revisión con recomendación `approve`, `approve-with-risk` o `revise`;
+- bloquea la aprobación cuando hay fixes requeridos.
+
+Aprobar un plan revisado:
+
+```bash
+npx --yes create-quiver@latest ai approve --phase technical-plan --version <n>
+```
+
+## 8. Crear el paquete de spec
+
+```bash
+npx --yes create-quiver@latest spec create --dry-run
+npx --yes create-quiver@latest spec create
+```
+
+Si querés revisar el paquete antes de escribirlo:
+
+```bash
+npx --yes create-quiver@latest spec create --review --interactive
+```
+
+Qué hace:
+
+- crea `SPEC.md`;
+- crea el `slice-00` obligatorio;
+- crea slices de implementación;
+- crea `EXECUTION_BRIEF.md` y `CLOSURE_BRIEF.md`;
+- crea el plan de ejecución y `pr.md`.
+
+Validarlo:
+
+```bash
+npx --yes create-quiver@latest spec validate specs/<spec-slug> --strict
+```
+
+## 9. Crear o reutilizar el worktree de la spec
+
+```bash
+npx --yes create-quiver@latest spec start specs/<spec-slug> --dry-run
+npx --yes create-quiver@latest spec start specs/<spec-slug>
+```
+
+Qué hace:
+
+- prepara la rama y el worktree dedicados a esta spec;
+- mantiene una spec aislada de otros trabajos.
+
+## 10. Inspeccionar el orden de slices
+
+```bash
+npx --yes create-quiver@latest plan --spec <spec-slug>
+npx --yes create-quiver@latest graph --spec <spec-slug>
+npx --yes create-quiver@latest next --all-ready --spec <spec-slug>
+```
+
+Qué hace:
+
+- muestra el orden de ejecución;
+- muestra dependencias;
+- lista slices listos para ejecutar.
+
+## 11. Ejecutar slices manualmente
+
+Generá un prompt para un agente ejecutor de menor costo:
+
+```bash
+npx --yes create-quiver@latest ai prompt-slice --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+```
+
+Qué hace:
+
+- imprime el contexto mínimo que necesita el ejecutor;
+- evita enviar la spec completa salvo que sea necesario.
+
+## 12. Ejecutar un slice con Quiver
+
+```bash
+npx --yes create-quiver@latest ai execute-slice --slice specs/<spec-slug>/slices/<slice-id>/slice.json --commit --dry-run
+npx --yes create-quiver@latest ai execute-slice --slice specs/<spec-slug>/slices/<slice-id>/slice.json --commit
+```
+
+Qué hace:
+
+- ejecuta el slice con el ejecutor configurado;
+- valida rama y worktree;
+- valida archivos modificados contra el alcance del slice;
+- corre comandos de validación declarados;
+- actualiza cierre, evidencia, estado y `slice.json`;
+- crea un commit para el slice.
+
+## 13. Ejecutar slices por olas
+
+Modo manual:
+
+```bash
+npx --yes create-quiver@latest ai execute-plan --dry-run --commit --mode manual
+```
+
+Qué hace:
+
+- imprime prompts de slices en orden de ejecución;
+- no llama proveedores.
+
+Modo delegado:
+
+```bash
+npx --yes create-quiver@latest ai execute-plan --dry-run --commit --mode delegated
+npx --yes create-quiver@latest ai execute-plan --execute --commit --mode delegated
+```
+
+Qué hace:
+
+- previsualiza o ejecuta slices delegados;
+- usa worktrees temporales para slices paralelizables;
+- vuelve a ejecución secuencial cuando el alcance no es seguro.
+
+## 14. Validar antes del PR
+
+```bash
+npx --yes create-quiver@latest spec validate specs/<spec-slug> --strict
+npx --yes create-quiver@latest next --all-ready --spec <spec-slug>
+git diff --check
+```
+
+Qué hace:
+
+- confirma que el paquete de spec esté completo;
+- confirma que no queden slices listos sin ejecutar;
+- revisa whitespace.
+
+También corré validaciones propias del proyecto:
+
+```bash
+npm test
+npm run build
+npm run lint
+```
+
+Usá solo los scripts que existan en el proyecto.
+
+## 15. Previsualizar creación del PR
+
+```bash
+npx --yes create-quiver@latest ai pr \
+  --review \
+  --dry-run \
+  --input specs/<spec-slug>/pr.md \
+  --ssh-host-alias github-personal \
+  --identity-file ~/.ssh/github-personal
+```
+
+Qué hace:
+
+- valida `gh`;
+- valida autenticación de GitHub;
+- valida alias SSH y archivo de identidad;
+- verifica que exista el cuerpo del PR;
+- no crea el PR.
+
+Adaptá `--identity-file` a la ruta real de tu máquina, por ejemplo `~/ssh/github-personal`, `~/.ssh/github-personal` o una ruta de Windows.
+
+## 16. Crear el pull request
+
+```bash
+npx --yes create-quiver@latest ai pr \
+  --create \
+  --interactive \
+  --input specs/<spec-slug>/pr.md \
+  --ssh-host-alias github-personal \
+  --identity-file ~/.ssh/github-personal
+```
+
+Qué hace:
+
+- abre el PR usando `gh`;
+- usa el cuerpo generado en `pr.md`;
+- bloquea la creación si todavía quedan slices abiertos.
+
+## 17. Después del merge
+
+```bash
+npx --yes create-quiver@latest spec close specs/<spec-slug> --dry-run
+npx --yes create-quiver@latest spec close specs/<spec-slug>
+git switch main
+git pull --ff-only origin main
+```
+
+Qué hace:
+
+- previsualiza y luego cierra el worktree de la spec;
+- vuelve al checkout principal;
+- trae localmente el resultado mergeado.

package/docs/workflows/legacy-quiver-project.md

@@ -0,0 +1,102 @@
+# Flujo para proyecto con Quiver anterior
+
+Usá este flujo cuando el proyecto ya tiene archivos de Quiver creados por una versión anterior.
+
+## 1. Entrar al proyecto
+
+```bash
+cd /ruta/al/proyecto
+git status -sb
+```
+
+Qué hace:
+
+- revisa la rama actual y los cambios pendientes.
+
+## 2. Ejecutar doctor
+
+```bash
+npx --yes create-quiver@latest doctor
+```
+
+Qué hace:
+
+- detecta si el proyecto está inicializado, incompleto, legacy, híbrido o sano.
+
+## 3. Previsualizar migración
+
+```bash
+npx --yes create-quiver@latest migrate --dry-run
+```
+
+Qué hace:
+
+- muestra qué actualizaría Quiver;
+- evita escribir archivos.
+
+## 4. Aplicar migración
+
+```bash
+npx --yes create-quiver@latest migrate
+```
+
+Qué hace:
+
+- actualiza documentación y estado interno de Quiver;
+- preserva archivos existentes del proyecto;
+- mantiene la migración lo más aditiva posible.
+
+Usá esta variante si no querés instalar dependencias:
+
+```bash
+npx --yes create-quiver@latest migrate --skip-install
+```
+
+## 5. Reconstruir contexto del proyecto
+
+```bash
+npx --yes create-quiver@latest analyze
+npx --yes create-quiver@latest doctor
+```
+
+Qué hace:
+
+- refresca `docs/PROJECT_MAP.md`;
+- confirma que la estructura migrada esté sana.
+
+## 6. Preparar contexto para IA
+
+```bash
+npx --yes create-quiver@latest ai prepare-context --dry-run
+npx --yes create-quiver@latest ai prepare-context
+```
+
+Modo asistido por planner, útil cuando el contexto anterior quedó desactualizado:
+
+```bash
+npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run
+npx --yes create-quiver@latest ai prepare-context --with-planner --review --interactive
+```
+
+Qué hace:
+
+- actualiza contexto de onboarding de forma segura;
+- reporta supuestos y contradicciones.
+
+## 7. Commit de migración
+
+```bash
+git status -sb
+git add AGENTS.md docs .quiver .gitignore package.json package-lock.json
+git commit -m "docs: migrate quiver workflow"
+```
+
+Qué hace:
+
+- crea una base estable antes de empezar specs nuevas.
+
+Ajustá los paths según lo que haya informado la migración.
+
+Siguiente paso:
+
+- [Ejecutar el flujo completo de spec a PR con IA](./full-ai-spec-to-pr.md)

package/docs/workflows/new-project.md

@@ -0,0 +1,76 @@
+# Flujo para proyecto nuevo
+
+Usá este flujo cuando el repositorio todavía no existe o la carpeta está vacía.
+
+## 1. Crear la carpeta del proyecto
+
+```bash
+mkdir mi-proyecto
+cd mi-proyecto
+git init
+```
+
+Qué hace:
+
+- crea una carpeta para el proyecto;
+- inicializa Git para que Quiver pueda razonar sobre cambios y worktrees.
+
+## 2. Inicializar Quiver
+
+```bash
+npx --yes create-quiver@latest init --name "Mi Proyecto"
+```
+
+Qué hace:
+
+- crea el contrato visible de Quiver;
+- crea el estado interno en `.quiver/`;
+- agrega scripts `quiver:*` cuando existe o se crea `package.json`.
+
+## 3. Revisar el próximo paso
+
+```bash
+npx --yes create-quiver@latest flow
+```
+
+Qué hace:
+
+- muestra el estado actual del workflow;
+- recomienda el próximo comando seguro.
+
+## 4. Analizar y validar
+
+```bash
+npx --yes create-quiver@latest analyze
+npx --yes create-quiver@latest doctor
+```
+
+Qué hace:
+
+- crea o actualiza `docs/PROJECT_MAP.md`;
+- refresca el contexto para IA;
+- valida que el contrato de Quiver esté sano.
+
+## 5. Preparar contexto para IA
+
+```bash
+npx --yes create-quiver@latest ai prepare-context --dry-run
+npx --yes create-quiver@latest ai prepare-context
+```
+
+Modo asistido por planner, si querés que una IA proponga el contexto:
+
+```bash
+npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run
+npx --yes create-quiver@latest ai prepare-context --with-planner --review --interactive
+```
+
+Qué hace:
+
+- previsualiza cambios documentales de onboarding;
+- escribe la documentación de contexto después de revisar;
+- evita cambios en código de producto.
+
+Siguiente paso:
+
+- [Ejecutar el flujo completo de spec a PR con IA](./full-ai-spec-to-pr.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
@@ -49,5 +49,9 @@
     "smoke:tiered-pack": "bash scripts/ci/smoke-tiered-pack.sh",
     "smoke:guided-workflow": "bash scripts/ci/smoke-guided-workflow.sh",
     "release:quiver": "bash scripts/release-quiver.sh"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "zod": "^4.4.3"
   }
 }

package/specs/quiver-v29-planner-prepare-context-cli-ux/EVIDENCE_REPORT.md

@@ -0,0 +1,163 @@
+# Evidence Report - Quiver v29 Planner Prepare Context CLI UX
+
+**Status:** Initial documentation package evidence
+**Date:** 2026-05-26
+
+## Scope
+
+This evidence report currently covers creation of the approved spec/slice package only. Implementation evidence must be appended by each execution slice.
+
+## Commands Run During Spec Creation
+
+```bash
+find specs/quiver-v29-planner-prepare-context-cli-ux -name 'slice.json' -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8')); console.log('ok ' + process.argv[1])" {} \;
+git diff --check
+for f in specs/quiver-v29-planner-prepare-context-cli-ux/slices/*/EXECUTION_BRIEF.md specs/quiver-v29-planner-prepare-context-cli-ux/slices/*/CLOSURE_BRIEF.md; do node bin/create-quiver.js check-handoff "$f" >/dev/null || exit 1; done; echo "handoff briefs ok"
+node bin/create-quiver.js spec validate specs/quiver-v29-planner-prepare-context-cli-ux
+```
+
+## Results
+
+- `slice-00-cli-ux-spec-foundation` completed as the documentation foundation slice.
+- Every `slice.json` parsed successfully.
+- `git diff --check` passed.
+- Every `EXECUTION_BRIEF.md` and `CLOSURE_BRIEF.md` passed `check-handoff` after normalizing the required `Acceptance Criteria` heading.
+- Initial `spec validate` reported this file as missing; this report was added to satisfy the spec validation contract.
+- `node bin/create-quiver.js spec validate specs/quiver-v29-planner-prepare-context-cli-ux` passed after adding this report.
+
+## Pending Evidence
+
+Implementation slices must append:
+
+- focused unit tests;
+- command integration tests;
+- CI/no-TTY/JSON validation;
+- package smoke;
+- tarball dry-run;
+- final docs sync validation.
+
+## slice-01-cli-ux-primitives-theme Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js tests/lib/cli-editor.test.js
+npm run package:quiver
+git diff --check
+```
+
+### Results
+
+- `node --test tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js tests/lib/cli-editor.test.js` passed with 18 tests.
+- `npm run package:quiver` passed and produced package smoke output for `create-quiver-0.14.0.tgz`.
+- `git diff --check` passed.
+- Dependencies were added through npm so `package-lock.json` records the resolved package metadata.
+
+## slice-02-planner-context-proposal-contract Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/lib/ai-context-proposal.test.js
+```
+
+### Results
+
+- `node --test tests/lib/ai-context-proposal.test.js` passed with 8 tests.
+- Fixtures cover valid JSON, fenced JSON, malformed output, product-code path, absolute path, and path traversal.
+- The slice did not invoke providers and did not modify `runPrepareContext` write behavior.
+
+## slice-04-ux-flag-matrix-compatibility Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js tests/lib/cli-ux.test.js
+```
+
+### Results
+
+- `node --test tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js tests/lib/cli-ux.test.js` passed with 22 tests.
+- Tests cover matrix support, unsupported flags, incompatible `--json` combinations, read-only commands, `ai pr --with-planner`, and parseable JSON output for existing commands.
+
+## slice-03-prepare-context-planner-review-flow Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/commands/ai-onboard.test.js tests/commands/ai-prepare-context-planner.test.js tests/lib/ai-context-proposal.test.js
+node --test tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js tests/lib/cli-ux.test.js
+git diff --check
+```
+
+### Results
+
+- `node --test tests/commands/ai-onboard.test.js tests/commands/ai-prepare-context-planner.test.js tests/lib/ai-context-proposal.test.js` passed with 25 tests.
+- `node --test tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js tests/lib/cli-ux.test.js` passed with 22 tests.
+- Tests cover deterministic compatibility, planner dry-run, prompt printing, provider success, provider failure, invalid planner output, review cancellation, review edit/revalidation, and interactive decline.
+- `git diff --check` passed.
+
+## slice-05-progressive-command-adoption Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/commands/ai-plan.test.js tests/commands/spec-create.test.js tests/commands/ai-pr.test.js tests/commands/ux-flags.test.js
+```
+
+### Results
+
+- `node --test tests/commands/ai-plan.test.js tests/commands/spec-create.test.js tests/commands/ai-pr.test.js tests/commands/ux-flags.test.js` passed with 46 tests.
+- Tests cover `ai plan` UX flags, draft review, interactive decline, `spec create --review`, `spec create --interactive`, `ai pr --review`, `ai pr --interactive`, and the central unsupported flag matrix.
+
+## slice-06-docs-tests-smoke-readiness Evidence
+
+**Date:** 2026-05-26
+**Status:** Passed
+
+### Commands
+
+```bash
+node --test tests/commands/ai-prepare-context-planner.test.js tests/commands/ai-plan.test.js tests/commands/spec-create.test.js tests/commands/ai-pr.test.js tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js tests/lib/cli-editor.test.js tests/lib/ai-context-proposal.test.js
+node bin/create-quiver.js --help >/tmp/quiver-help.txt && rg -- '--with-planner|--interactive|--review|--no-color' /tmp/quiver-help.txt
+node --test tests/**/*.test.js
+npm run smoke:create-quiver
+npm run smoke:doctor-fixtures
+npm run smoke:guided-workflow
+npm run package:quiver
+npm pack --dry-run
+git diff --check
+node bin/create-quiver.js spec validate specs/quiver-v29-planner-prepare-context-cli-ux
+```
+
+### Results
+
+- Focused command/UX validation passed with 87 tests and confirmed the public help includes `--with-planner`, `--interactive`, `--review`, and `--no-color`.
+- Full test suite passed with 426 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:doctor-fixtures` passed with 13 fixture states.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed and validated package safety.
+- `npm pack --dry-run` passed and produced a clean dry-run tarball report for `create-quiver@0.14.0`.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v29-planner-prepare-context-cli-ux` passed after closure metadata updates.
+
+### Notes
+
+- Npm printed a non-blocking update notice for npm `11.12.1 -> 11.15.0`.
+- Publishing and PR creation remain outside this slice.