create-quiver 0.14.0 → 0.14.1

package/docs/getting-started/windows-git-bash-wsl.md

@@ -0,0 +1,78 @@
+# Configurar Quiver en Windows Git Bash o WSL
+
+Usá esta guía si ejecutás Quiver desde Git Bash o WSL en Windows.
+
+## 1. Revisar herramientas requeridas
+
+```bash
+node --version
+npm --version
+git --version
+gh --version
+```
+
+Qué hace:
+
+- confirma que Node.js y npm pueden ejecutar Quiver;
+- confirma que Git está disponible para ramas y worktrees;
+- confirma que GitHub CLI está disponible para crear PRs.
+
+## 2. Instalar herramientas faltantes
+
+Instalá Node.js, Git y GitHub CLI en el entorno que realmente vas a usar.
+
+Importante:
+
+- Git Bash y WSL pueden tener instalaciones distintas;
+- si vas a ejecutar Quiver en WSL, instalá `node`, `npm`, `git` y `gh` dentro de WSL.
+
+## 3. Autenticar GitHub CLI
+
+```bash
+gh auth login
+gh auth status
+```
+
+Qué hace:
+
+- inicia sesión en GitHub desde la misma terminal donde vas a usar Quiver.
+
+## 4. Preparar alias SSH
+
+Git Bash y WSL normalmente soportan rutas estilo Unix.
+
+Ejemplo:
+
+```sshconfig
+Host github-personal
+  HostName github.com
+  User git
+  IdentityFile ~/.ssh/github-personal
+  IdentitiesOnly yes
+```
+
+Verificalo:
+
+```bash
+ssh -T github-personal
+```
+
+Qué hace:
+
+- confirma que el alias SSH funciona desde la misma terminal que usará Quiver.
+
+## 5. Verificar Quiver
+
+```bash
+npx --yes create-quiver@latest --version
+npx --yes create-quiver@latest --help
+```
+
+Qué hace:
+
+- ejecuta la última versión de Quiver desde npm.
+
+Siguiente paso:
+
+- [Usar Quiver en un proyecto existente](../workflows/existing-project.md)
+- [Ejecutar el flujo completo de spec a PR con IA](../workflows/full-ai-spec-to-pr.md)

package/docs/getting-started/windows-powershell.md

@@ -0,0 +1,96 @@
+# Configurar Quiver en Windows PowerShell
+
+Usá esta guía para preparar Windows PowerShell antes de usar Quiver.
+
+## 1. Revisar herramientas requeridas
+
+```powershell
+node --version
+npm --version
+git --version
+gh --version
+```
+
+Qué hace:
+
+- confirma que Node.js y npm pueden ejecutar Quiver;
+- confirma que Git está disponible para ramas y worktrees;
+- confirma que GitHub CLI está disponible para crear PRs.
+
+## 2. Instalar herramientas faltantes
+
+Instalá:
+
+- Node.js para Windows;
+- Git for Windows;
+- GitHub CLI para Windows.
+
+Después cerrá y abrí PowerShell de nuevo, y ejecutá:
+
+```powershell
+node --version
+npm --version
+git --version
+gh --version
+```
+
+## 3. Autenticar GitHub CLI
+
+```powershell
+gh auth login
+gh auth status
+```
+
+Qué hace:
+
+- inicia sesión en GitHub desde `gh`;
+- confirma la cuenta activa y los permisos.
+
+## 4. Preparar alias SSH
+
+Tu configuración SSH normalmente está en:
+
+```powershell
+$HOME\.ssh\config
+```
+
+Ejemplo:
+
+```sshconfig
+Host github-personal
+  HostName github.com
+  User git
+  IdentityFile C:\Users\<user>\ssh\github-personal
+  IdentitiesOnly yes
+```
+
+Verificalo:
+
+```powershell
+ssh -T github-personal
+```
+
+Qué hace:
+
+- confirma que el alias funciona con tu clave SSH.
+
+## 5. Verificar Quiver
+
+```powershell
+npx --yes create-quiver@latest --version
+npx --yes create-quiver@latest --help
+```
+
+Qué hace:
+
+- ejecuta la última versión publicada de Quiver sin instalarla globalmente.
+
+Nota sobre rutas:
+
+- usá comillas cuando una ruta tenga espacios;
+- pasá `--identity-file` con ruta de Windows al crear PRs.
+
+Siguiente paso:
+
+- [Usar Quiver en un proyecto existente](../workflows/existing-project.md)
+- [Ejecutar el flujo completo de spec a PR con IA](../workflows/full-ai-spec-to-pr.md)

package/docs/reference/commands.md

@@ -0,0 +1,94 @@
+# Referencia de comandos de Quiver
+
+Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos soportados por la versión instalada.
+
+## Configuración inicial
+
+| Comando | Para qué sirve |
+|---|---|
+| `npx --yes create-quiver@latest --version` | Muestra la versión del CLI. |
+| `npx --yes create-quiver@latest --help` | Muestra los comandos soportados. |
+| `npx --yes create-quiver@latest init --name "Proyecto"` | Inicializa Quiver en un proyecto. |
+| `npx --yes create-quiver@latest migrate --dry-run` | Previsualiza migración de un proyecto Quiver anterior. |
+| `npx --yes create-quiver@latest migrate` | Aplica la migración. |
+| `npx --yes create-quiver@latest analyze` | Genera mapa del proyecto y datos de escaneo. |
+| `npx --yes create-quiver@latest doctor` | Valida la salud de Quiver. |
+| `npx --yes create-quiver@latest flow` | Muestra el próximo paso seguro. |
+
+## Planificación con IA
+
+| Comando | Para qué sirve |
+|---|---|
+| `npx --yes create-quiver@latest ai prepare-context --dry-run` | Previsualiza actualizaciones documentales de contexto para IA. |
+| `npx --yes create-quiver@latest ai prepare-context` | Escribe actualizaciones documentales de contexto para IA. |
+| `npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run` | Previsualiza una propuesta docs-only generada por el planner sin escribir archivos. |
+| `npx --yes create-quiver@latest ai prepare-context --with-planner --print-prompt` | Imprime el prompt exacto para ejecutar el planner en otro entorno. |
+| `npx --yes create-quiver@latest ai prepare-context --with-planner --review --interactive` | Ejecuta planner, abre revisión humana y pide confirmación antes de escribir docs permitidos. |
+| `npx --yes create-quiver@latest ai agent set <role> --provider <provider> --model "<label>"` | Guarda un perfil de agente sin secretos. |
+| `npx --yes create-quiver@latest ai run create --input <file>` | Inicia una ejecución persistente de IA. |
+| `npx --yes create-quiver@latest ai status` | Muestra el estado de la ejecución actual. |
+| `npx --yes create-quiver@latest ai plan --phase acceptance --input <file>` | Genera criterios de aceptación. |
+| `npx --yes create-quiver@latest ai plan --phase acceptance --review --interactive --input <file>` | Permite revisar y confirmar el borrador del planner antes de guardarlo. |
+| `npx --yes create-quiver@latest ai revise --phase acceptance --input <file>` | Crea una nueva versión de criterios. |
+| `npx --yes create-quiver@latest ai approve --phase acceptance --version <n>` | Aprueba criterios. |
+| `npx --yes create-quiver@latest ai plan --phase technical-plan` | Genera plan técnico. |
+| `npx --yes create-quiver@latest ai review-plan` | Revisa el plan técnico. |
+| `npx --yes create-quiver@latest ai approve --phase technical-plan --version <n>` | Aprueba el plan técnico revisado. |
+
+## Specs y slices
+
+| Comando | Para qué sirve |
+|---|---|
+| `npx --yes create-quiver@latest spec create --dry-run` | Previsualiza archivos de spec generados. |
+| `npx --yes create-quiver@latest spec create` | Genera spec, slices, briefs, plan de ejecución y cuerpo del PR. |
+| `npx --yes create-quiver@latest spec create --review --interactive` | Abre una revisión del paquete a generar y pide confirmación antes de escribir. |
+| `npx --yes create-quiver@latest spec validate specs/<spec> --strict` | Valida el paquete de spec. |
+| `npx --yes create-quiver@latest spec start specs/<spec>` | Crea o reutiliza el worktree de una spec. |
+| `npx --yes create-quiver@latest plan --spec <spec>` | Muestra el orden de ejecución de slices. |
+| `npx --yes create-quiver@latest graph --spec <spec>` | Muestra dependencias entre slices. |
+| `npx --yes create-quiver@latest next --all-ready --spec <spec>` | Lista slices listos para ejecutar. |
+| `npx --yes create-quiver@latest ai prompt-slice --slice <slice.json> --dry-run` | Imprime un prompt mínimo para el ejecutor. |
+| `npx --yes create-quiver@latest ai execute-slice --slice <slice.json> --commit` | Ejecuta un slice y commitea después de validar. |
+| `npx --yes create-quiver@latest ai execute-plan --execute --commit --mode delegated` | Ejecuta slices delegados por olas. |
+
+## PR y cierre
+
+| Comando | Para qué sirve |
+|---|---|
+| `npx --yes create-quiver@latest ai pr --dry-run --input specs/<spec>/pr.md` | Previsualiza creación de PR y readiness de GitHub. |
+| `npx --yes create-quiver@latest ai pr --review --dry-run --input specs/<spec>/pr.md` | Abre `pr.md` para revisión y vuelve a armar el plan de PR sin crear el PR. |
+| `npx --yes create-quiver@latest ai pr --create --input specs/<spec>/pr.md` | Crea el PR usando `gh`. |
+| `npx --yes create-quiver@latest spec close specs/<spec> --dry-run` | Previsualiza limpieza del worktree después del merge. |
+| `npx --yes create-quiver@latest spec close specs/<spec>` | Cierra el worktree de la spec mergeada. |
+
+## Opciones útiles
+
+| Opción | Para qué sirve |
+|---|---|
+| `--dry-run` | Previsualiza sin escribir archivos ni ejecutar proveedores. |
+| `--print-prompt` | Imprime el prompt del proveedor sin ejecutarlo. |
+| `--with-planner` | Activa comportamiento asistido por planner solo en comandos que lo soportan. |
+| `--interactive` | Habilita prompts humanos de confirmación o elección. |
+| `--review` | Abre o prepara revisión humana antes de escrituras persistentes. |
+| `--no-color` | Desactiva colores ANSI en salida humana. |
+| `--provider codex\|claude\|gemini` | Selecciona CLI local de proveedor. |
+| `--commit` | Permite que Quiver commitee trabajo validado del slice. |
+| `--mode manual` | Imprime prompts para asignación manual de ejecutores. |
+| `--mode delegated` | Usa ejecución delegada con worktrees temporales cuando es seguro. |
+| `--ssh-host-alias <alias>` | Alias SSH de GitHub para validaciones de PR. |
+| `--identity-file <path>` | Ruta de la clave SSH para validaciones de PR. |
+
+## Matriz de flags UX
+
+| Comando | `--with-planner` | `--interactive` | `--review` |
+|---|---:|---:|---:|
+| `ai prepare-context` | sí | sí | sí |
+| `ai plan` | sí | sí | sí |
+| `spec create` | sí | sí | sí |
+| `ai pr` | no | sí | sí |
+| `flow`, `next`, `graph` | no | no | no |
+| `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, `ai trace report` | no | no | no |
+
+`--json` no se puede combinar con `--interactive` ni `--review`, porque la salida debe mantenerse legible por máquinas. El estándar completo vive en [docs/CLI_UX_GUIDE.md](../CLI_UX_GUIDE.md).
+
+Nota: `spec create --with-planner` no ejecuta un proveedor nuevo; indica que el comando consume el plan técnico aprobado generado por el planner.

package/docs/workflows/existing-project.md

@@ -0,0 +1,131 @@
+# Flujo para proyecto existente
+
+Usá este flujo cuando el proyecto ya tiene código, pero todavía no usa Quiver.
+
+## 1. Entrar al proyecto
+
+```bash
+cd /ruta/al/proyecto
+git status -sb
+```
+
+Qué hace:
+
+- entra a la raíz del proyecto;
+- muestra si hay cambios pendientes.
+
+Recomendado:
+
+- empezar desde una rama limpia;
+- no mezclar el onboarding de Quiver con trabajo de producto no relacionado.
+
+## 2. Verificar la versión publicada de Quiver
+
+```bash
+npx --yes create-quiver@latest --version
+npx --yes create-quiver@latest --help
+```
+
+Qué hace:
+
+- confirma que npm puede resolver Quiver;
+- muestra los comandos disponibles.
+
+## 3. Inicializar Quiver
+
+```bash
+npx --yes create-quiver@latest init --name "Nombre del Proyecto"
+```
+
+Qué hace:
+
+- agrega documentación de Quiver y estado interno;
+- todavía no crea una spec;
+- preserva archivos existentes.
+
+## 4. Inspeccionar el estado del workflow
+
+```bash
+npx --yes create-quiver@latest flow
+```
+
+Qué hace:
+
+- informa qué ve Quiver;
+- recomienda el próximo comando seguro.
+
+## 5. Analizar el proyecto existente
+
+```bash
+npx --yes create-quiver@latest analyze --dry-run
+npx --yes create-quiver@latest analyze
+```
+
+Qué hace:
+
+- previsualiza actualizaciones del mapa del proyecto;
+- escribe `docs/PROJECT_MAP.md`;
+- guarda el escaneo crudo en `.quiver/scans/`.
+
+## 6. Validar el contrato
+
+```bash
+npx --yes create-quiver@latest doctor
+```
+
+Qué hace:
+
+- revisa documentación requerida;
+- revisa salud de la estructura;
+- reporta herramientas faltantes o estados riesgosos.
+
+## 7. Preparar contexto de onboarding 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, recomendado cuando querés que una IA complete el contexto inicial:
+
+```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 actualizaciones documentales;
+- escribe contexto para IA después de revisar;
+- registra supuestos, riesgos y rutas omitidas.
+
+## 8. Configurar agentes
+
+```bash
+npx --yes create-quiver@latest ai agent set planner --provider codex --model "planner-model" --dry-run
+npx --yes create-quiver@latest ai agent set planner --provider codex --model "planner-model"
+npx --yes create-quiver@latest ai agent set executor --provider codex --model "executor-model"
+```
+
+Qué hace:
+
+- guarda perfiles reutilizables por rol;
+- no guarda credenciales ni API keys.
+
+## 9. Commit de documentación inicial
+
+```bash
+git status -sb
+git add AGENTS.md docs .quiver .gitignore package.json package-lock.json
+git commit -m "docs: initialize quiver workflow"
+```
+
+Qué hace:
+
+- crea una base limpia antes de empezar a planificar features.
+
+Ajustá los paths de `git add` según los archivos que Quiver haya creado realmente.
+
+Siguiente paso:
+
+- [Ejecutar el flujo completo de spec a PR con IA](./full-ai-spec-to-pr.md)

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.