create-quiver 0.14.1 → 0.15.1

package/docs/getting-started/installation.md

@@ -0,0 +1,86 @@
+# Instalación y uso con npx
+
+Esta guía explica por qué Quiver normalmente se ejecuta con `npx`, cuándo aparece en `node_modules` y cuándo conviene instalarlo como dependencia del proyecto.
+
+## Uso recomendado
+
+Para usar la última versión publicada de Quiver, ejecutá:
+
+```bash
+npx --yes create-quiver@latest --help
+```
+
+Qué hace:
+
+- descarga o reutiliza `create-quiver` desde la caché de npm;
+- ejecuta el CLI sin agregarlo al `package.json`;
+- evita instalar una dependencia que la aplicación no necesita para correr.
+
+Este es el modo recomendado para inicializar, analizar, diagnosticar, preparar contexto, crear specs, ejecutar slices y abrir PRs.
+
+## Por qué no aparece en node_modules
+
+Si ejecutás Quiver con:
+
+```bash
+npx --yes create-quiver@latest ...
+```
+
+el paquete no se instala dentro del proyecto. npm lo ejecuta desde su caché temporal o global de ejecución. Por eso no vas a encontrarlo en:
+
+```text
+node_modules/create-quiver
+```
+
+Esto es normal para CLIs de bootstrap como `create-quiver`. Quiver organiza el workflow del proyecto, pero no es una librería que tu app importe en runtime.
+
+## Cuándo instalarlo como devDependency
+
+Instalalo localmente solo si el equipo quiere una versión fijada en el proyecto o scripts reproducibles sin depender de `@latest`:
+
+```bash
+npm install --save-dev create-quiver
+```
+
+Después podés usar:
+
+```bash
+npx create-quiver --help
+```
+
+O agregar scripts al `package.json`, por ejemplo:
+
+```json
+{
+  "scripts": {
+    "quiver:doctor": "create-quiver doctor",
+    "quiver:flow": "create-quiver flow"
+  }
+}
+```
+
+Qué cambia:
+
+- `create-quiver` aparece en `devDependencies`;
+- npm lo instala dentro de `node_modules`;
+- los scripts del proyecto usan la versión fijada por `package-lock.json`.
+
+## Qué opción elegir
+
+| Necesidad | Recomendación |
+|---|---|
+| Probar Quiver rápidamente | `npx --yes create-quiver@latest` |
+| Inicializar un proyecto nuevo | `npx --yes create-quiver@latest init --name "Mi Proyecto"` |
+| Usar siempre la última versión publicada | `npx --yes create-quiver@latest` |
+| Fijar una versión para el equipo | `npm install --save-dev create-quiver` |
+| Evitar dependencia local de workflow | Usar `npx` |
+
+## Qué no hace Quiver
+
+Quiver no se instala globalmente por defecto, no modifica credenciales de npm y no agrega una dependencia runtime a tu app salvo que lo pidas explícitamente con npm.
+
+## Siguiente paso
+
+- [Proyecto nuevo desde cero](../workflows/new-project.md)
+- [Proyecto existente sin Quiver](../workflows/existing-project.md)
+- [Referencia de comandos](../reference/commands.md)

package/docs/reference/commands.md

@@ -2,6 +2,25 @@
 
 Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos soportados por la versión instalada.
 
+## npx vs instalación local
+
+Quiver está pensado para ejecutarse principalmente con `npx`:
+
+```bash
+npx --yes create-quiver@latest <comando>
+```
+
+En ese modo npm descarga o reutiliza el CLI desde su caché y no lo instala en `node_modules`. Eso es normal: `create-quiver` es una herramienta de workflow, no una dependencia runtime de la app.
+
+Instalalo como dependencia de desarrollo solo si querés fijar una versión para el equipo:
+
+```bash
+npm install --save-dev create-quiver
+npx create-quiver <comando>
+```
+
+Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
+
 ## Configuración inicial
 
 | Comando | Para qué sirve |
@@ -9,10 +28,12 @@ Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos
 | `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 init --interactive` | Abre una guía interactiva para elegir modo de proyecto, metodología `wdd-sdd`, perfil inicial y próximos pasos de agentes. |
 | `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 doctor --json` | Emite el mismo diagnóstico de Doctor como JSON parseable para automatización. |
 | `npx --yes create-quiver@latest flow` | Muestra el próximo paso seguro. |
 
 ## Planificación con IA
@@ -24,7 +45,15 @@ Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos
 | `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 models list` | Lista proveedores y modelos conocidos por Quiver sin afirmar disponibilidad en la cuenta. |
+| `npx --yes create-quiver@latest ai models list --provider codex` | Filtra el catálogo local por proveedor. |
+| `npx --yes create-quiver@latest ai models list --json` | Emite el catálogo local en JSON parseable. |
+| `npx --yes create-quiver@latest ai agent set <role>` | En TTY, guía la selección de proveedor, modelo conocido por Quiver o modelo custom. |
+| `npx --yes create-quiver@latest ai agent set <role> --provider <provider> --model <model-id>` | Guarda un perfil de agente sin secretos en modo script/no-TTY. |
+| `npx --yes create-quiver@latest ai agent set planner --provider codex --model gpt-5.5 --dry-run` | Previsualiza la escritura del perfil sin modificar `.quiver/agents/profiles.json`. |
+| `npx --yes create-quiver@latest ai agent doctor` | Diagnostica perfiles de agentes, alias visuales, proveedores faltantes y modelos custom no validados. |
+| `npx --yes create-quiver@latest ai agent doctor --json` | Emite el diagnóstico de perfiles como JSON parseable. |
+| `npx --yes create-quiver@latest ai agent repair --dry-run` | Previsualiza reparaciones seguras de perfiles, como normalizar `model: "GPT 5.5"` a `model: "gpt-5.5"` y `displayName: "GPT 5.5"`. |
 | `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. |
@@ -42,6 +71,7 @@ Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos
 | `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 create --interactive` | Guía la selección de metodología `wdd-sdd`, input aprobado y modo de revisió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. |
@@ -70,8 +100,10 @@ Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos
 | `--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. |
+| `--methodology wdd-sdd` | Declara la metodología soportada por comandos interactivos o automatizados. |
 | `--no-color` | Desactiva colores ANSI en salida humana. |
 | `--provider codex\|claude\|gemini` | Selecciona CLI local de proveedor. |
+| `--model <model-id>` | Selecciona el identificador técnico del modelo para `ai agent set` o ejecución de proveedor. Quiver normaliza alias conocidos, pero no garantiza acceso en la cuenta del 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. |

package/package.json

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

package/specs/quiver-v30-interactive-cli-ux-agent-selection/EVIDENCE_REPORT.md

@@ -0,0 +1,213 @@
+# Evidence Report - Quiver v30 Interactive CLI UX and Agent Selection
+
+## Summary
+
+This report records the evidence for every v30 slice, from the documentation foundation through final release readiness.
+
+## slice-00 - Spec foundation
+
+### Completed
+
+- Create v30 spec folder.
+- Create `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, `EXECUTION_PLAN.md`, and `pr.md`.
+- Create every slice folder with `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Sync source-of-truth planning docs with v29 release status and v30 planned scope.
+
+### Validation
+
+- `find specs/quiver-v30-interactive-cli-ux-agent-selection -name 'slice.json' -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8')); console.log('ok', process.argv[1])" {} \;` passed for 9 slice files.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v30-interactive-cli-ux-agent-selection` passed and reported 9 slices.
+
+### Risks Observed During Validation
+
+- None for the documentation package.
+
+## Later Slices
+
+Each implementation slice appended:
+
+- commands executed;
+- tests or smokes run;
+- files changed;
+- validation result;
+- UX/machine-output evidence;
+- remaining risks;
+- evidence location.
+
+## slice-01 - CLI UX runtime and progress engine
+
+### Completed
+
+- Extended `src/create-quiver/lib/cli/theme.js` with section, success, warning, and error semantics while keeping the approved Quiver palette centralized.
+- Extended `src/create-quiver/lib/cli/ux.js` with helpers for sections, checks, warnings, errors, summaries, next steps, and task groups.
+- Hardened spinner stop behavior so a spinner is stopped once on success or failure.
+- Added tests for branded human hierarchy, plain no-TTY fallback, JSON suppression, and real stage execution through `taskGroup`.
+
+### Validation
+
+- `node --test tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js` passed: 15 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- Command adoption is intentionally deferred to later slices; this slice only adds the runtime.
+
+## slice-02 - Agent profile selection and selectors
+
+### Completed
+
+- Added backward-compatible multiple named agent profiles per role.
+- Kept legacy single-profile behavior by preserving the default profile under `profiles.<role>`.
+- Added profile sets under `profile_sets.<role>s`.
+- Added display-name resolution order for profile output.
+- Added CLI flags for profile identity and future selectors: `--id`, `--display-name`, `--default`, `--planner`, `--executor`, `--reviewer`, `--doctor`, and `--methodology`.
+- Added `src/create-quiver/lib/cli/selectors.js` for reusable interactive/non-interactive selection.
+- Extended `ai agent set/list/show` for named profiles.
+
+### Validation
+
+- `node --test tests/lib/agent-profiles.test.js tests/lib/cli-selectors.test.js tests/commands/ai-agent.test.js` passed: 16 tests.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v30-interactive-cli-ux-agent-selection` passed.
+
+### Risks
+
+- Command flows do not yet consume the new profile selector flags; that adoption belongs to later slices.
+- Provider model correctness is not enforced until slice-03.
+
+## slice-03 - Provider model selection contract
+
+### Completed
+
+- Added provider adapter metadata for model selection support and model argument construction.
+- Added model-selection metadata to provider invocations and dry-run results.
+- Added live execution enforcement so selected models are passed to provider adapters or block with actionable guidance when unsupported.
+- Wired planner/reviewer profile model selection into `ai onboard`, `ai prepare-context --with-planner`, `ai plan`, `ai review-plan`, `ai repair-plan`, and `ai revise`.
+- Added command flag propagation for `--model`, `--planner`, and `--reviewer` in planner/reviewer flows.
+- Documented the model-selection contract in `docs/CLI_UX_GUIDE.md` and synchronized `README_FOR_AI.md`.
+
+### Validation
+
+- `node --test tests/lib/ai-providers.test.js tests/commands/ai-agent.test.js tests/commands/ai-onboard.test.js tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js tests/commands/ai-prepare-context-planner.test.js` passed: 72 tests.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v30-interactive-cli-ux-agent-selection` passed.
+
+### Risks
+
+- Provider model flags are implemented through the current adapter contract. Installed provider CLIs can still vary by version, so later release validation should dogfood dry-run and live commands with available local CLIs.
+- Executor provider/model propagation remains for slice-05.
+
+## slice-04 - Planner IA progress flows
+
+### Completed
+
+- Added a shared command UX bridge for planner-oriented IA commands.
+- Added visible TTY progress for `ai onboard`, `ai prepare-context --with-planner`, `ai plan`, `ai review-plan`, `ai repair-plan`, and `ai revise`.
+- Progress headings use the selected profile/model display name when available.
+- Provider execution now runs inside a spinner in human TTY mode and stops on both success and provider failure.
+- `--dry-run`, `--print-prompt`, CI, and non-TTY output remain free of progress noise.
+- Updated `docs/CLI_UX_GUIDE.md` and `README_FOR_AI.md` with the progress-output standard.
+
+### Validation
+
+- `node --test tests/commands/ai-prepare-context-planner.test.js tests/commands/ai-onboard.test.js tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js tests/lib/cli-ux.test.js` passed: 65 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- Some direct unit tests run with a TTY can display clack spinner artifacts in the test log, although captured no-TTY output remains clean. Slice-08 should include a final full-suite check and adjust test harness mode if needed.
+- Executor and PR command progress remains for slice-05.
+
+## slice-05 - Executor, execution-plan, and PR progress flows
+
+### Completed
+
+- Added executor runtime profile/model resolution and provider model enforcement to `ai execute-slice`.
+- Added interactive ready-slice selection for `ai execute-slice --interactive` when `--slice` is omitted.
+- Added interactive executor profile selection when multiple executor profiles are configured.
+- Added TTY progress for executor provider execution, validation commands, slice commits, execution-plan waves, GitHub preflight, and PR creation.
+- Added model visibility to execute-slice and execute-plan dry-runs.
+- Extended UX flag support to `ai execute-slice` and `ai execute-plan` for `--interactive`.
+- Preserved clean JSON/no-TTY behavior and existing PR/gh error propagation.
+
+### Validation
+
+- `node --test tests/lib/ai-executor.test.js tests/commands/ai-execute-slice.test.js tests/lib/ai-execution-plan.test.js tests/commands/ai-execute-plan.test.js tests/commands/ai-pr.test.js tests/commands/ux-flags.test.js` passed: 54 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- `ai execute-plan --interactive` is now accepted for strategy UX consistency, but this slice does not yet add a full strategy selector. Future UX work can add it without changing the safety contract.
+- Direct TTY unit runs can still show spinner artifacts in logs; final suite validation should decide whether to force test I/O to no-TTY.
+
+## slice-06 - Doctor visual and JSON contract
+
+### Completed
+
+- Added a shared Doctor command report with stable fields for `schema_version`, `status`, `exit_code`, `checks`, `suggested_fixes`, `warnings`, and `errors`.
+- Rendered human Doctor output with the required `Quiver Doctor`, `Checks`, and `Suggested fixes` hierarchy.
+- Added `doctor --json` output that is parseable, machine-clean, and backed by the same checks as human output.
+- Preserved deterministic exit-code behavior: warnings remain exit code 0 and blocking layout errors set exit code 1.
+- Kept `doctor --fix --dry-run` behavior and added clean JSON behavior for `doctor --fix --dry-run --json`.
+- Updated Doctor documentation in `docs/CLI_UX_GUIDE.md`, `docs/reference/commands.md`, and `README_FOR_AI.md`.
+
+### Validation
+
+- `node --test tests/commands/doctor.test.js tests/lib/doctor.test.js tests/lib/cli-ux.test.js` passed: 29 tests.
+- `npm run smoke:doctor-fixtures` passed: 13 fixture states.
+- `git diff --check` passed.
+
+### Risks
+
+- Local environment checks can still add host-dependent warnings, for example `gh auth` status. That behavior existed before this slice and remains visible through the shared check model.
+- Downstream JSON consumers should pin to `schema_version: 1` and avoid parsing human text.
+
+## slice-07 - Interactive init and spec create flows
+
+### Completed
+
+- Added guarded `init --interactive` flow for project mode, methodology, init profile, and optional agent-profile guidance.
+- Added `--methodology wdd-sdd` validation and documented that no other methodology is currently supported.
+- Added `spec create --interactive` selectors for methodology, approved plan input, and direct-vs-review mode.
+- Added summaries before persistent writes for interactive init/spec-create flows.
+- Added explicit no-TTY failure for interactive init/spec-create so CI and scripts do not hang.
+- Extended UX flag support to `init --interactive`.
+- Updated help text, CLI UX guide, command reference, and `README_FOR_AI.md`.
+
+### Validation
+
+- `node --test tests/commands/init-profiles.test.js tests/commands/spec-create.test.js tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js` passed: 39 tests.
+- `node bin/create-quiver.js --help` showed the updated interactive init example and methodology flag.
+- `git diff --check` passed.
+
+### Risks
+
+- The `init --interactive` validation-only path delegates to `doctor`, which still requires Quiver initialization evidence in the target project.
+- The spec-create approved-input selector currently exposes the resolved approved technical-plan input. Wider selection across historical approved inputs is intentionally deferred until the approval store defines that as a stable contract.
+
+## slice-08 - Tests, docs, cross-platform smokes, and release readiness
+
+### Completed
+
+- Synchronized release-facing documentation for the v30 CLI UX behavior.
+- Updated command templates with `init --interactive`, `doctor --json`, `spec create --interactive`, `--methodology wdd-sdd`, and interactive human-output guidance.
+- Updated `README.md`, `README_FOR_AI.md`, `ROADMAP.md`, and `CHANGELOG.md` with the implemented v30 behavior.
+- Closed the v30 spec metadata and PR body with final validation evidence.
+- Confirmed release readiness without publishing to npm.
+
+### Validation
+
+- `node --test tests/**/*.test.js` passed: 449 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:guided-workflow` passed.
+- `npm run smoke:doctor-fixtures` passed: 13 fixture states.
+- `npm run package:quiver` passed and produced package-smoke evidence for `create-quiver-0.14.1.tgz`.
+- `npm pack --dry-run` passed.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v30-interactive-cli-ux-agent-selection` passed.
+
+### Risks
+
+- Live provider smoke tests were not executed against every external IA CLI because those checks depend on local provider installation and authentication.
+- Cross-platform behavior is covered by documented script-safe modes and automated command contracts, but final human terminal rendering should still be dogfooded on Windows PowerShell, Git Bash, WSL, macOS, and Linux before broad announcement.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/EXECUTION_PLAN.md

@@ -0,0 +1,85 @@
+# Execution Plan - Quiver v30 Interactive CLI UX and Agent Selection
+
+## Execution Order
+
+```mermaid
+flowchart TD
+    S00[slice-00: Spec foundation and source-of-truth sync]
+    S01[slice-01: CLI UX runtime and progress engine]
+    S02[slice-02: Agent profile selection and selectors]
+    S03[slice-03: Provider model selection contract]
+    S04[slice-04: Planner IA progress flows]
+    S05[slice-05: Executor, execution-plan, and PR progress flows]
+    S06[slice-06: Doctor visual and JSON contract]
+    S07[slice-07: Interactive init and spec create flows]
+    S08[slice-08: Tests, docs, cross-platform smokes, and release readiness]
+
+    S00 --> S01
+    S01 --> S02
+    S02 --> S03
+    S01 --> S06
+    S01 --> S07
+    S02 --> S07
+    S03 --> S04
+    S03 --> S05
+    S04 --> S08
+    S05 --> S08
+    S06 --> S08
+    S07 --> S08
+```
+
+## Waves
+
+### Wave 0 - Sequential
+
+1. `slice-00-spec-foundation`
+
+This slice must run first. It commits the approved spec, all slices, handoffs, execution plan, PR body, and source-of-truth documentation sync.
+
+### Wave 1 - Sequential
+
+1. `slice-01-cli-ux-runtime-progress-engine`
+
+Shared UX runtime and progress lifecycle must exist before command adoption.
+
+### Wave 2 - Sequential Core Selection
+
+1. `slice-02-agent-profile-selection-selectors`
+2. `slice-03-provider-model-selection-contract`
+
+Profile selectors must land before provider model execution semantics so selected models and display names map to real provider invocations.
+
+### Wave 3 - Parallel after slice-03
+
+- `slice-04-planner-ia-progress-flows`
+- `slice-05-executor-pr-progress-flows`
+- `slice-06-doctor-visual-json-contract`
+- `slice-07-interactive-init-spec-create`
+
+These can run in parallel if their write scopes stay separated. Resolve conflicts in `src/create-quiver/commands/ai.js` by landing planner flows before executor/PR flows if needed.
+
+### Wave 4 - Sequential Close
+
+1. `slice-08-tests-docs-cross-platform-release`
+
+This slice validates all previous work, updates final docs/templates, and prepares package release evidence.
+
+## Parallel Safety Notes
+
+- Do not run any implementation slice before `slice-00`.
+- Do not adopt command progress before `slice-01`.
+- Do not show profile/model display names in live IA flows before `slice-03` proves selected models map to real provider invocations.
+- `slice-04` and `slice-05` may both touch `commands/ai.js`; if conflicts are likely, run `slice-04` first.
+- `slice-08` is never parallel-safe because it closes docs, tests, smokes, and release readiness.
+
+## Recommended Commit Order
+
+1. `docs: add v30 interactive cli ux spec`
+2. `feat: add cli ux progress runtime`
+3. `feat: add agent profile selectors`
+4. `feat: add provider model selection contract`
+5. `feat: add planner progress flows`
+6. `feat: add executor and pr progress flows`
+7. `feat: add doctor visual json contract`
+8. `feat: add interactive init and spec create`
+9. `docs: close v30 cli ux release readiness`