create-quiver 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -6,6 +6,22 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- Implemented v30 interactive CLI UX and agent selection under `specs/quiver-v30-interactive-cli-ux-agent-selection/`.
+- Multiple named agent profiles for Planner, Executor, Reviewer, and Doctor, including display names, defaults, selectors, and model labels.
+- Visible progress output for planner, reviewer, executor, execution-plan, and PR flows in human TTY mode.
+- `doctor --json` with a stable parseable diagnostics contract, backed by the same findings as the human `Quiver Doctor` output.
+- `init --interactive`, `spec create --interactive`, and `--methodology wdd-sdd` for guarded human choices.
+
+### Changed
+
+- Provider model selection now affects real provider invocations when supported, and blocks safely when a selected model cannot be applied.
+- CLI output now follows the shared Quiver palette and hierarchy while keeping `--json`, CI, no-TTY, and `--no-color` output clean.
+- Command docs now cover human-vs-machine output, selectors, Doctor output, and cross-platform usage.
+
+## [0.14.1] - 2026-05-26
+
+### Added
+
 - v29 planner-assisted context and CLI UX standard under `specs/quiver-v29-planner-prepare-context-cli-ux/`.
 - Shared Quiver-branded CLI UX helpers, color tokens, editor review support, and guarded UX flag matrix.
 - Optional `ai prepare-context --with-planner` flow with prompt printing, review, interactive approval, and docs-only proposal validation.

package/README.md

@@ -149,9 +149,11 @@ Usá la guía que corresponda al estado de tu proyecto:
 | `npx --yes create-quiver@latest --help` | Muestra la lista pública de comandos. |
 | `npx --yes create-quiver@latest --version` | Muestra la versión del CLI. |
 | `npx --yes create-quiver@latest init --name "Proyecto"` | Inicializa Quiver en un proyecto. |
+| `npx --yes create-quiver@latest init --interactive` | Abre una guía humana para elegir modo, metodología `wdd-sdd`, perfil inicial y próximos pasos de agentes. |
 | `npx --yes create-quiver@latest migrate --dry-run` | Previsualiza la migración de un proyecto Quiver anterior. |
 | `npx --yes create-quiver@latest analyze` | Genera el mapa del proyecto usado por humanos y agentes. |
 | `npx --yes create-quiver@latest doctor` | Revisa si el contrato de Quiver está sano. |
+| `npx --yes create-quiver@latest doctor --json` | Devuelve el diagnóstico como JSON para automatizaciones. |
 | `npx --yes create-quiver@latest flow` | Indica el próximo paso seguro. |
 | `npx --yes create-quiver@latest ai prepare-context --dry-run` | Previsualiza contexto de onboarding para IA sin tocar código de producto. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run` | Previsualiza una propuesta de contexto generada por el planner. |
@@ -159,6 +161,7 @@ Usá la guía que corresponda al estado de tu proyecto:
 | `npx --yes create-quiver@latest ai plan --phase technical-plan` | Genera un borrador de plan técnico. |
 | `npx --yes create-quiver@latest ai review-plan` | Revisa el plan técnico antes de aprobarlo. |
 | `npx --yes create-quiver@latest spec create` | Crea spec, slices, briefs, plan de ejecución y cuerpo del PR. |
+| `npx --yes create-quiver@latest spec create --interactive` | Guía la selección de metodología, input aprobado y revisión antes de escribir la spec. |
 | `npx --yes create-quiver@latest spec start specs/<spec>` | Crea o reutiliza el worktree de una spec. |
 | `npx --yes create-quiver@latest next --all-ready --spec <spec>` | Lista los slices listos para ejecutar. |
 | `npx --yes create-quiver@latest ai execute-slice --slice <slice.json> --commit` | Ejecuta un slice aprobado y lo commitea después de validar. |
@@ -176,6 +179,7 @@ Quiver usa un estándar único para que los comandos sean claros tanto para huma
 - `--with-planner` activa un modo asistido por planner solo en comandos que lo soportan.
 - `--review` abre o prepara una revisión humana antes de escrituras persistentes.
 - `--interactive` habilita confirmaciones explícitas cuando el comando puede cambiar estado.
+- `--methodology wdd-sdd` declara la metodología soportada por los flujos guiados.
 - `--json` mantiene salida legible por máquinas y no se combina con `--interactive` ni `--review`.
 - `--no-color` desactiva colores cuando el entorno no los necesita.
 

package/README_FOR_AI.md

@@ -10,6 +10,8 @@ Do not recommend global installation; use `npx` or a project-local devDependency
 The package also exposes `quiver` as a binary alias to the same CLI. Treat it as a local installed shortcut, not as a replacement for the bootstrap command `npx create-quiver`.
 The root `README.md` is the public landing/onboarding page: keep it concise, Spanish-first, AI-first, and focused on what Quiver is, what problem it solves, the WDD + SDD flow, core commands, and links to deeper guides. Long step-by-step instructions live in `docs/getting-started/`, `docs/workflows/`, and `docs/reference/commands.md`; do not duplicate every procedural detail in the root README.
 The post-init contract is validated with `npx create-quiver doctor` from the project root. Use `npx create-quiver doctor --fix --dry-run` to preview safe non-destructive repairs, then `npx create-quiver doctor --fix` only after reviewing the plan.
+`doctor` must render the human hierarchy `Quiver Doctor` -> `Checks` -> `Suggested fixes`, and `doctor --json` must emit the same diagnostics as stable parseable JSON without colors, prompts, or human prose.
+`init --interactive` and `spec create --interactive` are explicit human-only wrappers. They must not run in CI/no-TTY/JSON, must show only the real methodology `WDD + SDD` (`--methodology wdd-sdd`), and must summarize choices before persistent writes.
 If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate` before `analyze` from the project root.
 If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver init --name "Project Name"` first.
 Use `npx create-quiver evidence run -- <command>` to capture validation evidence with command, exit code, duration, truncated output, and best-effort redaction. The safe default output is `.quiver/evidence/`; use `--output <file>` when a slice needs a specific evidence artifact.
@@ -20,11 +22,15 @@ The v25 spec is implemented under `specs/quiver-v25-ai-first-lifecycle-orchestra
 The v26 hotfix spec is implemented under `specs/quiver-v26-0121-smoke-hardening/` and shipped in `create-quiver@0.12.1`; it covers smoke hardening for CLI help/version output, generated doc links, AI approval/review guidance, local validation, slice brief validation, demo readiness, scoped plan/graph performance, and release smoke coverage.
 The v27 spec is implemented under `specs/quiver-v27-reliability-ai-workflow-hardening/` and shipped in `create-quiver@0.13.0`; it captures Pixel Quiver dogfooding findings (`QP-001` to `QP-019`, `QIS-001` to `QIS-022`) and includes shared state resolution, canonical statuses, schema v2 exports, structured spec creation, AI artifact cleanup, worktree locks, validation gates, context diagnostics, cross-platform DX, fixtures, smoke suites, and package/tarball release readiness.
 The v28 spec is implemented under `specs/quiver-v28-pixel-quiver-feedback-reconciliation/` and shipped in `create-quiver@0.14.0`; it captures the Pixel Quiver follow-up reconciliation with active-slice reconciliation, stale `ai inspect` recovery, structured review closure, stricter technical-plan approval, spec/worktree validation hardening, agent-safe commands, GitHub auth/alias guidance, and package-readiness evidence.
-The v29 spec is implemented under `specs/quiver-v29-planner-prepare-context-cli-ux/` and is pending package publication; it adds shared CLI UX primitives, Quiver palette usage, guarded UX flags, planner-assisted `ai prepare-context`, and review/interactive adoption for selected planner/spec/PR commands.
+The v29 spec is implemented under `specs/quiver-v29-planner-prepare-context-cli-ux/` and shipped in `create-quiver@0.14.1`; it adds shared CLI UX primitives, Quiver palette usage, guarded UX flags, planner-assisted `ai prepare-context`, and review/interactive adoption for selected planner/spec/PR commands.
+The v30 spec is implemented under `specs/quiver-v30-interactive-cli-ux-agent-selection/` and is release-ready pending package publication; it adds production-grade interactive CLI UX with visible IA progress, Quiver-branded output, configured Planner/Executor/Reviewer/Doctor selectors, real provider model-selection contracts, Doctor human/JSON parity, guided init/spec-create selectors, and cross-platform release readiness.
 Guided AI workflow behavior is available: prepare, approvals, production-readiness plan review, spec worktrees, executor commits, execution waves, PR creation, spec close, and package safety.
 Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:flow` for the read-only guided entrypoint, `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, `quiver:next` for the next ready slice, `quiver:evidence` for local command evidence, `quiver:spec:create` for real spec generation, `quiver:spec:validate` for full spec validation, and the AI family `quiver:ai:agent`, `quiver:ai:inspect`, `quiver:ai:export`, `quiver:ai:specs`, `quiver:ai:slices`, `quiver:ai:trace`, `quiver:ai:onboard`, `quiver:ai:prepare-context`, `quiver:ai:plan`, `quiver:ai:review-plan`, `quiver:ai:approve`, `quiver:ai:prompt-slice`, `quiver:ai:execute-slice`, `quiver:ai:execute-plan`, `quiver:ai:pr`, and `quiver:ai:doctor`. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
 `quiver:ai:execute-plan` supports `--mode manual` for paste-ready executor prompts and `--mode delegated` for temporary worktrees on parallel-ready waves; unsafe waves fall back to sequential execution.
-Agent profiles live in `.quiver/agents/profiles.json`; they store role, provider, model label, context label, and display label only. Do not store API keys, tokens, or credentials there.
+Agent profiles live in `.quiver/agents/profiles.json`; they store role, provider, model label, context label, display label, profile id, and default profile only. Do not store API keys, tokens, or credentials there.
+Provider/model selection must be honest: dry-runs can preview a selected model without provider auth, but live IA execution must pass the selected model through the provider adapter or fail with actionable guidance instead of silently ignoring it.
+Planner-oriented live IA commands must show visible TTY progress with the selected profile/model name, completed preparation checks, and a provider-running spinner. `--dry-run`, `--print-prompt`, CI, JSON, and non-TTY output must remain clean and automation-safe.
+Executor and PR live commands follow the same standard: show truthful TTY progress for slice execution, validation, commits, GitHub preflight, and PR creation while preserving scope gates, provider errors, `gh` errors, and clean machine output.
 Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; review the technical-plan draft with `npx create-quiver ai review-plan --dry-run` before approving it, then approve a concrete version with `npx create-quiver ai approve --phase <phase> --version <n>` when reviewing iterations.
 `ai review-plan` stores structured closure metadata under `.quiver/approvals/plan-review/meta.json`: `approval_recommendation` is `approve`, `approve-with-risk`, or `revise`; required fixes block technical-plan approval, while optional hardening does not.
 AI lifecycle runs are persisted under `.quiver/runs/<run-id>/`; use `npx create-quiver ai run create --input <requirements.md>` to start one explicitly, `npx create-quiver ai status` to inspect it, `npx create-quiver ai resume` to continue from the last valid phase without relying on chat memory, and `npx create-quiver ai export --format json|markdown` when another agent, PR, or dashboard needs the current specs/slices/runs state.

package/ROADMAP.md

@@ -80,10 +80,15 @@
 - Published package `0.14.0`.
 - **v28** — Follow-up hardening from Pixel Quiver dogfooding: active-slice reconciliation, spec-aware `ai inspect` recovery, structured plan-review closure, safer technical-plan approval, stronger spec/worktree validation, agent-safe command examples, GitHub auth/alias guidance, and final release-readiness evidence live in `specs/quiver-v28-pixel-quiver-feedback-reconciliation/`.
 
-## v0.15 — Planner Context and CLI UX Standard (in progress)
+## v0.14.1 — Planner Context and CLI UX Standard (shipped 2026-05-26)
 
+- Published package `0.14.1`.
 - **v29** — Planner-assisted context preparation and CLI UX standard: shared output helpers, Quiver palette, guarded `--with-planner` / `--interactive` / `--review` flags, optional planner-generated `ai prepare-context`, review/interactive adoption for selected commands, docs, tests, and smoke readiness live in `specs/quiver-v29-planner-prepare-context-cli-ux/`.
 
+## v0.15 — Interactive CLI UX and Agent Selection (release-ready, pending package publication)
+
+- **v30** — Interactive CLI UX and agent selection: visible progress for long-running IA commands, selected Planner/Executor/Reviewer/Doctor display names, profile/spec/slice/methodology selectors, provider model-selection correctness, Doctor human/JSON parity, cross-platform automation safety, and release-readiness evidence live in `specs/quiver-v30-interactive-cli-ux-agent-selection/`.
+
 ## Post-Checkpoint Plan (do not execute before validating v14)
 
 > This section now records the follow-up line from the v14-era plan.
@@ -101,7 +106,8 @@
 - **v26 — 0.12.1 Smoke Hardening** (shipped in `0.12.1`): first-use hardening from clean npm smoke testing, covering CLI help/version output, generated doc links, AI approval/review guidance, local validation, slice brief validation, demo readiness, scoped plan/graph performance, and release smoke coverage live in `specs/quiver-v26-0121-smoke-hardening/`.
 - **v27 — Reliability and AI Workflow Hardening** (shipped in `0.13.0`): Pixel Quiver dogfooding follow-up covering resolver/export/spec-create/AI-artifact/worktree/validation/context/DX hardening lives in `specs/quiver-v27-reliability-ai-workflow-hardening/`.
 - **v28 — Pixel Quiver Feedback Reconciliation** (shipped in `0.14.0`): active-slice reconciliation, stale inspect recovery, structured review closure, validation/worktree hardening, agent-safe commands, GitHub auth guidance, and release-readiness evidence live in `specs/quiver-v28-pixel-quiver-feedback-reconciliation/`.
-- **v29 — Planner Context and CLI UX Standard** (in progress): planner-assisted `ai prepare-context`, CLI UX primitives, guarded UX flags, human review/interactive flows, and final docs/smoke readiness live in `specs/quiver-v29-planner-prepare-context-cli-ux/`.
+- **v29 — Planner Context and CLI UX Standard** (shipped in `0.14.1`): planner-assisted `ai prepare-context`, CLI UX primitives, guarded UX flags, human review/interactive flows, and final docs/smoke readiness live in `specs/quiver-v29-planner-prepare-context-cli-ux/`.
+- **v30 — Interactive CLI UX and Agent Selection** (release-ready, pending package publication): visible IA progress, Quiver-branded output, profile/spec/slice selectors, provider model-selection correctness, Doctor human/JSON parity, and cross-platform release readiness live in `specs/quiver-v30-interactive-cli-ux-agent-selection/`.
 
 The shipped v20/v21/v22/v23 work is no longer pending. The older context-diagnostics and slice-archaeology ideas remain deferred until real demand justifies them.
 

package/docs/CLI_UX_GUIDE.md

@@ -36,6 +36,7 @@ Reglas:
 | `--with-planner` | Activa comportamiento asistido por planner cuando el comando lo soporta. | No debe ser decorativo. Si no cambia el comportamiento o contrato del comando, debe rechazarse. |
 | `--interactive` | Habilita prompts humanos de confirmacion o eleccion. | Nunca se activa por defecto. Debe tener alternativa no interactiva. |
 | `--review` | Abre o prepara revision humana antes de escrituras persistentes. | Debe usar `$VISUAL`, `$EDITOR` o dejar un artefacto revisable cuando no haya TTY. |
+| `--methodology <name>` | Selecciona metodologia cuando el comando necesita exponer esa decision. | Hoy solo se acepta `wdd-sdd`; no listar metodologias no soportadas. |
 | `--dry-run` | Previsualiza sin escribir ni ejecutar acciones irreversibles. | Debe ser seguro y no requerir credenciales salvo que el comando lo documente. |
 | `--print-prompt` | Imprime el prompt exacto sin ejecutar proveedor. | Debe evitar auth/provider execution. |
 | `--json` | Emite salida machine-readable. | Incompatible con `--interactive` y `--review`. |
@@ -45,10 +46,14 @@ Reglas:
 
 | Comando | `--with-planner` | `--interactive` | `--review` | Notas |
 |---|---:|---:|---:|---|
+| `init` | no | si | no | Interactive guia modo de proyecto, metodologia `wdd-sdd`, perfil inicial y proximo paso de perfiles de agentes. |
 | `ai prepare-context` | si | si | si | Modo deterministico por defecto; planner opcional con contrato docs-only. |
 | `ai plan` | si | si | si | El planner ya es implicito; `--with-planner` se acepta por consistencia. |
 | `spec create` | si | si | si | Consume un plan tecnico aprobado del planner; no vuelve a ejecutar proveedor. Review previsualiza el paquete antes de escribir. |
 | `ai pr` | no | si | si | Review edita `pr.md`; interactive confirma `gh pr create`. |
+| `ai execute-slice` | no | si | no | Interactive puede seleccionar un slice listo y un executor configurado. |
+| `ai execute-plan` | no | si | no | Interactive queda reservado para estrategia/seleccion; JSON sigue limpio. |
+| `doctor` | no | no | no | Renderiza `Quiver Doctor`, `Checks` y `Suggested fixes`; `--json` usa el mismo modelo de hallazgos. |
 | `flow`, `next`, `graph` | no | no | no | Lectura/inspeccion; no deben exponer flags decorativas. |
 | `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, `ai trace report` | no | no | no | Superficies read-only o machine-readable. |
 
@@ -71,15 +76,46 @@ npx create-quiver ai prepare-context --with-planner --review --interactive
 
 El planner debe devolver una propuesta validable. Quiver solo acepta cambios en documentación/contexto permitida y rechaza rutas de producto, dependencias, build, runtime, lockfiles, salidas generadas, rutas absolutas y traversal.
 
+## Seleccion de agentes, proveedores y modelos
+
+Los perfiles de agente son configuracion de DX, no almacenamiento de credenciales. Deben guardar solo rol, proveedor, etiqueta de modelo, contexto, nombre visible y perfil por defecto.
+
+Reglas:
+
+- Si un comando usa un perfil con modelo, el dry-run debe mostrar proveedor, modelo, comando y si el adapter puede aplicar ese modelo.
+- En ejecucion real, Quiver debe pasar el modelo al CLI del proveedor cuando el adapter lo soporta.
+- Si un adapter no puede aplicar el modelo seleccionado, la ejecucion real debe bloquearse con un proximo paso claro.
+- `--print-prompt` y `--dry-run` no deben exigir autenticacion del proveedor.
+- Si no hay modelo seleccionado, los comandos existentes deben conservar su comportamiento anterior.
+
+## Init y spec create interactivos
+
+`init --interactive` debe ser un wrapper opt-in sobre flags existentes:
+
+- modo de proyecto: proyecto existente, proyecto nuevo o solo validar estructura;
+- metodologia: solo `WDD + SDD`;
+- perfil inicial: default, minimal o full compatibility;
+- guia opcional de comandos `ai agent set` sin guardar credenciales ni ejecutar proveedores;
+- resumen antes de escribir.
+
+`spec create --interactive` debe:
+
+- seleccionar la metodologia real soportada: `WDD + SDD`;
+- mostrar el input aprobado que se usara para generar la spec;
+- permitir elegir confirmacion directa o `--review`;
+- mostrar resumen antes de escribir;
+- bloquearse en no-TTY/CI/JSON con mensaje accionable en lugar de abrir prompts.
+
 ## Loaders y prompts
 
 Usar loaders solo cuando aportan claridad:
 
 ```text
-Analizando estructura del proyecto...
-Leyendo contexto base...
-Preparando prompt para planner...
-Ejecutando agente...
+◇ Ejecutando onboarding con GPT 5.5
+✓ Leyendo docs base
+✓ Detectando estructura
+✓ Preparando prompt
+⠋ Ejecutando agente...
 ```
 
 Usar prompts interactivos cuando hay una decision humana real:
@@ -92,6 +128,30 @@ Usar prompts interactivos cuando hay una decision humana real:
 
 No usar prompts para informacion que ya se pueda expresar con flags.
 
+## Salida de Doctor
+
+`doctor` debe mostrar una jerarquia estable para humanos:
+
+```text
+◆ Quiver Doctor
+
+Checks
+  ✓ Layout: new
+  ✓ Specs: none yet
+  ! Warning: project analysis artifacts not found; run analyze when you need the visible project map
+
+Suggested fixes
+  • Analyze the project first: npx create-quiver analyze
+  • Check the next ready slice: npx create-quiver next
+```
+
+Reglas:
+
+- La salida humana debe incluir siempre `Quiver Doctor`, `Checks` y `Suggested fixes`.
+- `doctor --json` debe emitir solo JSON parseable, sin colores, prompts ni texto humano.
+- La salida humana y JSON deben salir del mismo modelo de checks, warnings, errors y suggested fixes.
+- Warnings no deben romper automatizacion; errores bloqueantes deben usar `exit_code: 1` y `process.exitCode = 1`.
+
 ## Revision con editor
 
 Los comandos con `--review` deben:

package/docs/COMMANDS.md.template

@@ -10,6 +10,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | Command | Purpose | OS | Since | Example |
 |---------|---------|----|-------|---------|
 | `npx create-quiver init --name "<project>"` | Creates the default AI-first Quiver contract for a project | macOS, Linux, Windows | current | `npx create-quiver init --name "{{PROJECT_NAME}}"` |
+| `npx create-quiver init --interactive` | Guides project mode, methodology `wdd-sdd`, init profile, and agent-profile next steps without running providers | macOS, Linux, Windows | next | `npx create-quiver init --interactive` |
 | `npx create-quiver --name "<project>"` | Compatibility alias for the recommended init flow | macOS, Linux, Windows | current | `npx create-quiver --name "{{PROJECT_NAME}}"` |
 | `npx create-quiver --version` | Prints the installed CLI version | macOS, Linux, Windows | current | `npx create-quiver --version` |
 | `npx create-quiver --help` | Lists all public commands with descriptions, key options, and recommended examples | macOS, Linux, Windows | current | `npx create-quiver --help` |
@@ -21,6 +22,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `quiver:flow` | Runs the guided flow entrypoint through the generated npm script | macOS, Linux, Windows | v0.11 | `npm run quiver:flow` |
 | `quiver:prepare` | Runs guided setup diagnostics and context preparation | macOS, Linux, Windows | v0.10 | `npm run quiver:prepare -- --dry-run --provider codex` |
 | `quiver:doctor` | Validates the Quiver contract and reports layout or migration guidance | macOS, Linux, Windows | v0.8 | `npm run quiver:doctor` |
+| `quiver:doctor -- --json` | Emits the Doctor checks and suggested fixes as stable machine-readable JSON | macOS, Linux, Windows | next | `npm run quiver:doctor -- --json` |
 | `quiver:doctor -- --fix --dry-run` | Previews safe non-destructive repairs without writing files | macOS, Linux, Windows | v0.11 | `npm run quiver:doctor -- --fix --dry-run` |
 | `quiver:doctor -- --fix` | Applies safe idempotent repairs after review | macOS, Linux, Windows | v0.11 | `npm run quiver:doctor -- --fix` |
 | `quiver:evidence -- run -- <command>` | Captures command validation evidence with exit code, duration, redacted/truncated output, and a local Markdown record | macOS, Linux, Windows | v0.11 | `npm run quiver:evidence -- run -- npm test` |
@@ -66,6 +68,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `quiver:ai:pr` | Validates `gh`, reads `pr.md`, prints a PR plan, and creates a PR only with `--create` | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:pr -- --dry-run --input specs/<spec>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
 | `quiver:ai:pr -- --review` | Opens `pr.md` for human review and rebuilds the PR plan from the edited body | macOS, Linux, Windows | next | `npm run quiver:ai:pr -- --review --dry-run --input specs/<spec>/pr.md` |
 | `quiver:spec:create` | Creates the real spec tree from the reviewed approved technical plan | macOS, Linux, Windows | v0.11 | `npm run quiver:spec:create -- --dry-run` |
+| `quiver:spec:create -- --interactive` | Guides methodology `wdd-sdd`, approved technical-plan input, and direct-vs-review mode before writing | macOS, Linux, Windows | next | `npm run quiver:spec:create -- --interactive` |
 | `quiver:spec:create -- --review --interactive` | Reviews the generated spec package preview and asks before writing files | macOS, Linux, Windows | next | `npm run quiver:spec:create -- --review --interactive` |
 | `quiver:spec:start` | Creates or reuses the dedicated worktree for one spec | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:start -- specs/<spec>` |
 | `quiver:spec:status` | Shows spec worktree, branch, `slice-00`, and pending slices | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:status -- specs/<spec>` |
@@ -99,8 +102,9 @@ This document is the canonical command reference for the orchestration roadmap.
 | `--label <label>` | `ai agent set` | Store a display label for the profile |
 | `--dry-run` | init, analyze, migrate, prepare, spec, demo, AI, PR, worktree, and repair commands that support preview | Preview planned actions without writes, provider execution, PR creation, or irreversible changes |
 | `--with-planner` | `ai prepare-context`, `ai plan`, `spec create` | Enable planner-assisted behavior only on commands that explicitly support it |
-| `--interactive` | `ai prepare-context`, `ai plan`, `spec create`, `ai pr` | Enable human prompts for confirmation or choices |
+| `--interactive` | `init`, `ai prepare-context`, `ai plan`, `spec create`, `ai pr`, `ai execute-slice`, `ai execute-plan` | Enable human prompts for confirmation or choices |
 | `--review` | `ai prepare-context`, `ai plan`, `spec create`, `ai pr` | Open or prepare human review before persistent writes |
+| `--methodology wdd-sdd` | `init`, `spec create` | Select the only supported methodology exposed by guided flows |
 | `--no-color` | all human-output commands | Disable ANSI color in human output |
 | `--print-prompt` | `ai onboard`, `ai prepare-context`, `ai plan`, `ai revise`, `ai review-plan` | Print the exact provider prompt and exit without executing provider CLIs or requiring provider auth |
 | `--role <planner\|executor\|reviewer\|doctor>` | `ai onboard`, `ai plan`, `ai revise`, `ai execute-slice`, `ai execute-plan` | Select an AI role; execution requires executor |
@@ -132,6 +136,8 @@ This document is the canonical command reference for the orchestration roadmap.
 - `quiver:ai:prepare-context -- --dry-run` previews deterministic docs-only context drafts, diff snippets, assumptions, risks, contradictions, and omitted paths. Write mode stores snapshots under `.quiver/runs/<run-id>/snapshots/` and preserves human-authored content by appending or refreshing a Quiver-managed block.
 - `quiver:ai:prepare-context -- --with-planner` invokes a planner provider and only accepts a validated docs-only proposal. Use `--print-prompt` for external planners, `--review` to inspect the proposal before writing, and `--interactive` to require confirmation.
 - UX flags are centralized: `--with-planner`, `--interactive`, and `--review` are accepted only by commands where they add real behavior. Read-only inspection commands reject them with an actionable next step. `spec create --with-planner` consumes an already approved planner output and does not call a provider again. `--json` is incompatible with `--interactive` and `--review`.
+- `doctor --json` emits the same checks and suggested fixes as human `Quiver Doctor` output without colors, prompts, spinners, or prose.
+- `init --interactive` and `spec create --interactive` are human-only wrappers. They fail in no-TTY/CI/JSON and always keep `WDD + SDD` as the only methodology option.
 - Quiver human output uses the palette `#86C8F2`, `#6BADEB`, `#7F9EE8`, `#9B82E6`, and `#D56AB0`; respect `--no-color`, `NO_COLOR`, CI, and no-TTY environments.
 - `quiver:flow` reports the detected package manager and the matching generated project script, for example `npm run quiver:flow`, `pnpm run quiver:flow`, `yarn run quiver:flow`, or `bun run quiver:flow`.
 - `quiver:ai:agent -- set ... --dry-run` previews provider/model profile changes without writing `.quiver/agents/profiles.json`.

package/docs/reference/commands.md

@@ -9,10 +9,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
@@ -42,6 +44,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,6 +73,7 @@ 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. |
 | `--commit` | Permite que Quiver commitee trabajo validado del slice. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "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`