create-quiver 0.13.0 → 0.14.1

package/docs/getting-started/linux.md

@@ -0,0 +1,84 @@
+# Configurar Quiver en Linux
+
+Usá esta guía para preparar una máquina Linux antes de usar Quiver en un proyecto.
+
+## 1. Revisar herramientas requeridas
+
+```bash
+node --version
+npm --version
+git --version
+gh --version
+```
+
+Qué hace:
+
+- confirma que Node.js y npm pueden ejecutar el CLI de 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 y npm con el package manager de tu distribución o con un version manager.
+
+Instalá GitHub CLI con el paquete oficial para tu distribución.
+
+Después de instalar:
+
+```bash
+gh --version
+```
+
+Qué hace:
+
+- confirma que el ejecutable `gh` está disponible.
+
+## 3. Autenticar GitHub CLI
+
+```bash
+gh auth login
+gh auth status
+```
+
+Qué hace:
+
+- inicia sesión en GitHub;
+- confirma cuenta, permisos y host.
+
+## 4. Preparar alias SSH
+
+Ejemplo de configuración SSH:
+
+```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 Git puede autenticarse con el alias que Quiver va a validar.
+
+## 5. Verificar Quiver
+
+```bash
+npx --yes create-quiver@latest --version
+npx --yes create-quiver@latest doctor --help
+```
+
+Qué hace:
+
+- confirma que la última versión publicada de Quiver puede ejecutarse.
+
+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/macos.md

@@ -0,0 +1,85 @@
+# Configurar Quiver en macOS
+
+Usá esta guía para preparar una Mac antes de usar Quiver en un proyecto.
+
+## 1. Revisar herramientas requeridas
+
+```bash
+node --version
+npm --version
+git --version
+gh --version
+```
+
+Qué hace:
+
+- confirma que Node.js y npm pueden ejecutar el CLI de Quiver;
+- confirma que Git está disponible para ramas y worktrees;
+- confirma que GitHub CLI está disponible para crear PRs.
+
+## 2. Instalar herramientas faltantes
+
+Si falta Node.js o npm, instalá Node.js desde el instalador oficial o con tu version manager preferido.
+
+Si falta GitHub CLI y usás Homebrew:
+
+```bash
+brew install gh
+```
+
+Qué hace:
+
+- instala el comando `gh`, que Quiver usa para validar y crear PRs.
+
+## 3. Autenticar GitHub CLI
+
+```bash
+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
+
+Quiver recibe el alias SSH y el archivo de identidad como valores separados.
+
+Ejemplo de configuración SSH:
+
+```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 `github-personal` resuelve a GitHub usando la clave esperada.
+
+## 5. Verificar Quiver
+
+```bash
+npx --yes create-quiver@latest --version
+npx --yes create-quiver@latest --help
+```
+
+Qué hace:
+
+- descarga y ejecuta la última versión publicada de Quiver;
+- confirma que los comandos principales están disponibles.
+
+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-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)