create-quiver 0.14.0 → 0.15.0

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

@@ -0,0 +1,213 @@
+# Quiver v30 - Interactive CLI UX and Agent Selection
+
+**Date:** 2026-05-26
+**Status:** Planned
+**Source:** User-approved production review for visible progress, Quiver colors, agent/model selectors, and consistent human/machine CLI output.
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Quiver has the first version of CLI UX primitives and planner-assisted `ai prepare-context`, but real dogfooding showed a critical UX gap: long-running IA commands can look frozen. `ai prepare-context --with-planner` starts provider execution without a visible loader, without Quiver-branded progress, and without a clear "this can take time" state.
+
+The issue is broader than one command. Quiver needs a production-grade CLI UX contract for commands that run Planners, Executors, Reviewers, Doctors, specs, slices, PRs, and diagnostics. The CLI must feel guided for humans while staying safe for automation.
+
+## Objective
+
+Implement a consistent, production-safe CLI UX layer for Quiver:
+
+- show real progress for long-running IA commands;
+- use Quiver colors and hierarchy in human TTY output;
+- let users choose configured Planner, Executor, Reviewer, Doctor, spec, slice, methodology, and execution mode through interactive selectors;
+- always provide equivalent non-interactive flags;
+- show selected agent display names such as `GPT 5.5`, not only provider names such as `codex`;
+- keep `--json`, CI, no-TTY, `NO_COLOR`, and Windows-safe output clean;
+- harden provider model selection so the selected model impacts the real provider invocation or blocks with an actionable error.
+
+## Scope
+
+### Included
+
+- Central CLI UX runtime for headings, sections, checks, warnings, errors, next steps, summaries, spinners, task groups, and fallbacks.
+- Quiver palette usage for human output: `#86C8F2`, `#6BADEB`, `#7F9EE8`, `#9B82E6`, `#D56AB0`.
+- Multiple named IA profiles per role: Planner, Executor, Reviewer, Doctor.
+- Interactive selectors for IA profiles, specs, slices, methodology, execution mode, review mode, verbosity, and execution strategy where appropriate.
+- Equivalent non-interactive flags for every selector.
+- Provider adapter contract for model selection support.
+- Visible progress stages for IA commands and diagnostics.
+- Doctor human output in a clear `Checks` / `Suggested fixes` format and stable JSON output.
+- Signal, cancellation, timeout, error, and child-process cleanup behavior for long-running tasks.
+- Tests, docs, generated templates, and package-readiness evidence.
+
+### Excluded
+
+- Replacing the CLI parser with `commander`, `oclif`, or `yargs`.
+- Adding a TUI with `ink`, `blessed`, or `neo-blessed`.
+- Adding image protocols or terminal graphics.
+- Adding new IA providers beyond the existing provider contract.
+- Storing provider credentials or API keys.
+- Making interactive prompts mandatory.
+- Changing WDD + SDD semantics.
+
+## Approved Acceptance Criteria
+
+### Long-running IA UX
+
+1. Given a project with Quiver initialized, when `npx create-quiver ai prepare-context --with-planner` runs in a human TTY, then Quiver shows an initial heading, selected Planner display name, visible progress, and a spinner while the provider is running.
+2. Given any IA command can take several seconds or minutes, when provider execution starts, then Quiver shows that it may take time and does not appear frozen.
+3. Given a provider fails, times out, or is canceled, when Quiver exits, then the spinner is stopped, provider output is summarized safely, and no partial success state is shown.
+4. Given `$EDITOR` or `$VISUAL` opens during a review flow, then any active spinner is stopped before opening the editor.
+5. Given `SIGINT` or `SIGTERM`, then Quiver stops spinners, terminates provider child processes, cleans temporary prompt files, and persists a canceled/failed run state when applicable.
+
+### Quiver visual identity
+
+6. Given human TTY output with color support, when Quiver prints headings, states, checks, warnings, errors, badges, loaders, or highlighted sections, then output uses centralized Quiver theme helpers and the approved palette.
+7. Given `--json`, `NO_COLOR=1`, `CI=true`, `TERM=dumb`, no-TTY, or `--ascii`, then Quiver emits clean, readable output without ANSI, spinners, decorative symbols, or prompts.
+8. Given a command outputs human text, then it uses a consistent hierarchy: title, checks/progress, results, warnings/risks, suggested fixes, and next commands.
+
+### Agent/profile selection
+
+9. Given a command requires a Planner and multiple configured Planner profiles exist, when `--interactive` is used, then Quiver shows a selector populated only from configured profiles.
+10. Given a Planner profile has `displayName: "GPT 5.5"`, when the command starts, then the heading says `Ejecutando <accion> con GPT 5.5` instead of `con Codex`, unless no more specific display name exists.
+11. Given a command requires an Executor, Reviewer, or Doctor, when multiple profiles exist and `--interactive` is used, then Quiver shows the corresponding role-specific selector.
+12. Given a command runs in CI, no-TTY, or `--json`, when a profile choice is required, then Quiver uses a configured default or fails with an actionable message showing the required flag.
+13. Given a selector exists, then an equivalent non-interactive flag exists: `--planner`, `--executor`, `--reviewer`, `--doctor`, `--spec`, `--slice`, `--methodology`, and command-specific mode flags.
+14. Given no profiles exist for a required role, then Quiver explains how to configure one with `ai agent set` and does not continue in live mode.
+
+### Provider/model correctness
+
+15. Given a profile selects a model, when the provider adapter supports model selection, then the real provider invocation receives the correct model argument or equivalent supported option.
+16. Given a profile selects a model but the provider adapter does not support model selection, then live execution blocks with a clear message unless an explicit override is provided.
+17. Given Quiver shows a model or profile as selected, then that value must either impact provider execution or be explicitly described as display-only.
+
+### Specs, slices, methodology, and execution choices
+
+18. Given multiple specs exist, when a command needs a spec and `--interactive` is used, then Quiver shows a spec selector using unique internal values and labels that include useful state.
+19. Given multiple slices exist under a selected spec, when a command needs a slice and `--interactive` is used, then Quiver shows slice state, dependencies, and next-ready recommendation.
+20. Given slice dependencies are incomplete, then Quiver does not silently select a blocked slice as the next executable slice.
+21. Given methodology is requested, then Quiver shows only supported methodology options. For now, `WDD + SDD` is the only real option.
+22. Given an action can write files, execute providers, create commits, or open PRs, then interactive mode shows a summary and confirmation before the sensitive action.
+
+### Command adoption
+
+23. Given `ai onboard` runs in human TTY mode, then it shows a heading with the selected Planner display name and real stages such as reading docs, detecting structure, preparing prompt, and executing agent.
+24. Given `ai prepare-context --with-planner` runs, then it shows real stages for structure analysis, docs detection, prompt preparation, provider execution, proposal validation, and docs-only write planning.
+25. Given `ai plan`, `ai review-plan`, `ai execute-slice`, `ai execute-plan`, and `ai pr` run, then each command uses command-specific real stages and never marks fake work as completed.
+26. Given `doctor` runs in human mode, then output follows the `Quiver Doctor` structure with `Checks` and `Suggested fixes`.
+27. Given `doctor --json` runs, then it emits a stable parseable schema with the same underlying findings as human output.
+
+### Automation and compatibility
+
+28. Given a command has a selector in human mode, when the same command runs with flags in automation, then it must be fully scriptable without prompts.
+29. Given output is redirected or run in no-TTY mode, then the user still sees plain progress lines for long work unless `--json` is requested.
+30. Given a command runs on Windows PowerShell, Git Bash, WSL, macOS, or Linux, then path examples, ASCII fallback, no-color behavior, and no-TTY behavior are documented and tested where possible.
+31. Given package publication, then `npx create-quiver@latest` exposes the same UX behavior after release.
+
+### Documentation and tests
+
+32. Given the UX standard changes, then `docs/CLI_UX_GUIDE.md`, README, command reference, generated templates, and `README_FOR_AI.md` document the standard and examples.
+33. Given the implementation is complete, then tests cover human output, machine output, no-color, CI, no-TTY, selector defaults, missing defaults, provider model support, provider failure, cancellation, doctor JSON, and package smoke.
+34. Given this spec is executed, then slice-00 lands first and every later slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+
+## Approved Technical Plan
+
+1. Extend the existing CLI UX layer instead of replacing the parser.
+2. Create a central human-output API for headings, sections, checks, warnings, errors, next steps, summaries, spinners, and task groups.
+3. Add a progress runner that declares real stages per command and prevents fake completed checks.
+4. Add multiple named IA profiles per role while keeping existing single-profile behavior backward compatible.
+5. Add display-name resolution order: `displayName`, `model`, `provider`, then role.
+6. Add interactive selectors only behind `--interactive`.
+7. Add equivalent non-interactive flags for every selector.
+8. Add provider adapter metadata for model selection support and invocation mapping.
+9. Block or require explicit override when a chosen model cannot impact live provider execution.
+10. Add signal, timeout, cancellation, spinner cleanup, temporary file cleanup, and run-state persistence for long-running IA flows.
+11. Apply the standard first to `ai prepare-context --with-planner`, `ai onboard`, `ai plan`, and `doctor`.
+12. Extend the standard to `ai review-plan`, `ai execute-slice`, `ai execute-plan`, `ai pr`, `init --interactive`, and `spec create --interactive`.
+13. Preserve clean output in `--json`, CI, no-TTY, `NO_COLOR`, `TERM=dumb`, and ASCII modes.
+14. Add tests and smoke coverage before package publication.
+
+## UX Examples
+
+### IA flow with selected Planner
+
+```text
+◇ Ejecutando onboarding con GPT 5.5
+
+✓ Leyendo docs base
+✓ Detectando estructura
+✓ Preparando prompt
+⠋ Ejecutando agente...
+```
+
+### Doctor
+
+```text
+◆ Quiver Doctor
+
+Checks
+  ✓ README encontrado
+  ✓ AI_ONBOARDING_PROMPT.md encontrado
+  ✓ Carpeta specs encontrada
+  ! Falta docs/WORKFLOW.md
+  ! Hay 2 slices sin CLOSURE_BRIEF.md
+
+Suggested fixes
+  npx create-quiver ai prepare-context --dry-run
+```
+
+### Planner selector
+
+```text
+? Que Planner queres usar?
+  ◉ GPT 5.5
+  ○ OPUS 4.7
+```
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | Spec foundation and source-of-truth sync | planned | none |
+| slice-01 | CLI UX runtime and progress engine | planned | slice-00 |
+| slice-02 | Agent profile selection and selectors | planned | slice-01 |
+| slice-03 | Provider model selection contract | planned | slice-02 |
+| slice-04 | Planner IA progress flows | planned | slice-01, slice-02, slice-03 |
+| slice-05 | Executor, execution-plan, and PR progress flows | planned | slice-01, slice-02, slice-03 |
+| slice-06 | Doctor visual and JSON contract | planned | slice-01 |
+| slice-07 | Interactive init and spec create flows | planned | slice-01, slice-02 |
+| slice-08 | Tests, docs, cross-platform smokes, and release readiness | planned | slice-04, slice-05, slice-06, slice-07 |
+
+## Validation Strategy
+
+- `node --test tests/**/*.test.js`
+- focused tests for CLI UX runtime, theme, progress runner, selectors, and profile display names
+- focused tests for provider model invocation and unsupported model blocking
+- focused tests for `ai onboard`, `ai prepare-context`, `ai plan`, `ai review-plan`, `ai execute-slice`, `ai execute-plan`, `ai pr`, and `doctor`
+- focused tests for `--json`, CI, no-TTY, `NO_COLOR`, `TERM=dumb`, and `--ascii`
+- signal/cancellation tests where feasible through injected process runners
+- `npm run smoke:create-quiver`
+- `npm run smoke:doctor-fixtures`
+- `npm run smoke:guided-workflow`
+- `npm run package:quiver`
+- `npm pack --dry-run`
+- `git diff --check`
+- JSON parse validation for all `slice.json` files
+- `npx create-quiver spec validate specs/quiver-v30-interactive-cli-ux-agent-selection`
+
+## Risks
+
+- UX improvements can break automation if spinners, colors, or prompts leak into machine output.
+- Model labels can become misleading if provider adapters do not pass models to real commands.
+- Interactive selectors can block CI unless opt-in and backed by non-interactive flags.
+- Signal cleanup is cross-platform and must avoid leaving child processes, locks, or temp files.
+- Doctor visual polish must not diverge from JSON diagnostics.
+- Windows terminals may need ASCII/no-color fallbacks for symbols and spinners.
+
+## Resolved Decisions
+
+- `--interactive` is required for selectors.
+- Every selector must have a non-interactive flag equivalent.
+- The selected agent/model display name is shown in headings.
+- Provider names are fallback labels only.
+- `WDD + SDD` is the only methodology option until another methodology is actually supported.
+- Do not add `ink`, `blessed`, `neo-blessed`, `oclif`, `commander`, or `yargs` in this spec.

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

@@ -0,0 +1,31 @@
+# Status - Quiver v30 Interactive CLI UX and Agent Selection
+
+**Overall status:** Release-ready
+**Created:** 2026-05-26
+**Current slice:** slice-08 completed; ready for PR/release publication
+
+## Summary
+
+This spec hardens Quiver's CLI UX after dogfooding showed that long-running IA commands can look frozen and that selector/model behavior needs a production-grade contract. The work adds visible progress, Quiver colors, role-specific agent selectors, non-interactive fallbacks, model invocation correctness, doctor output, interactive init/spec creation, and cross-platform release readiness.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-spec-foundation | Completed | Documentation package created, source-of-truth docs synchronized, validation passed. |
+| slice-01-cli-ux-runtime-progress-engine | Completed | Shared output/runtime/progress primitives added and tested. |
+| slice-02-agent-profile-selection-selectors | Completed | Multiple named role profiles and reusable selectors added. |
+| slice-03-provider-model-selection-contract | Completed | Provider model support, profile model propagation, dry-run visibility, and live blocking contract added. |
+| slice-04-planner-ia-progress-flows | Completed | Planner/reviewer live IA flows now show TTY progress with selected profile names and clean failure cleanup. |
+| slice-05-executor-pr-progress-flows | Completed | Executor/execute-plan/PR progress, executor selector, ready-slice selector, and executor model propagation added. |
+| slice-06-doctor-visual-json-contract | Completed | Doctor now renders `Quiver Doctor`/`Checks`/`Suggested fixes` from a shared JSON-compatible diagnostics model. |
+| slice-07-interactive-init-spec-create | Completed | `init --interactive` and `spec create --interactive` now use guarded selectors, methodology `wdd-sdd`, and summaries before writes. |
+| slice-08-tests-docs-cross-platform-release | Completed | Full tests, smokes, package dry-run, docs, evidence, and release readiness completed. |
+
+## Current Blockers
+
+- None.
+
+## Next Step
+
+Open the PR if requested, then publish the package only after explicit human release approval.

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

@@ -0,0 +1,103 @@
+## Title
+
+Quiver v30: interactive CLI UX, progress, and agent selection
+
+## Summary
+
+- Adds production-grade CLI UX for long-running IA commands.
+- Shows visible progress, Quiver colors, selected agent display names, and safe fallback output.
+- Adds interactive selectors for Planner, Executor, Reviewer, Doctor, specs, slices, methodology, and execution modes.
+- Hardens provider model selection so selected models affect real invocations or block safely.
+- Keeps `--json`, CI, no-TTY, no-color, and Windows-safe output clean.
+
+## Scope
+
+- CLI UX runtime and progress lifecycle.
+- Multiple named IA profiles and selectors.
+- Provider model support contract.
+- Planner, executor, PR, doctor, init, and spec-create command adoption.
+- Tests, docs, generated templates, smokes, and package readiness.
+
+## Files
+
+Expected areas:
+
+- `src/create-quiver/lib/cli/**`
+- `src/create-quiver/lib/agent-profiles.js`
+- `src/create-quiver/lib/ai/**`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/commands/spec.js`
+- `src/create-quiver/lib/doctor.js`
+- `src/create-quiver/index.js`
+- `docs/**`
+- `README.md`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `CHANGELOG.md`
+- `tests/**`
+- `scripts/ci/**`
+- `package.json`
+- `package-lock.json`
+- `specs/quiver-v30-interactive-cli-ux-agent-selection/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm.
+- Git.
+- Optional provider CLIs for manual live IA smoke tests.
+- `gh` only for PR flow validation.
+
+### Worktree Access
+
+- One dedicated worktree/branch for `quiver-v30-interactive-cli-ux-agent-selection`.
+- One commit per slice.
+
+### Run the Project
+
+This is a CLI framework change. Run command-level tests and smoke commands from the Quiver repo root.
+
+### Use Cases
+
+- Run `ai prepare-context --with-planner` and verify visible progress.
+- Run IA commands with configured profile display names and verify headings use the selected profile/model.
+- Run selectors with `--interactive`.
+- Run equivalent non-interactive flags in no-TTY/CI mode.
+- Run doctor in human mode and `--json`.
+- Run provider failure/cancellation tests.
+- Confirm `NO_COLOR`, `TERM=dumb`, `--ascii`, and `--json` stay clean.
+
+### Technical Verification
+
+- `node --test tests/**/*.test.js`
+- `npm run smoke:create-quiver`
+- `npm run smoke:doctor-fixtures`
+- `npm run smoke:guided-workflow`
+- `npm run package:quiver`
+- `npm pack --dry-run`
+- `git diff --check`
+- `npx create-quiver spec validate specs/quiver-v30-interactive-cli-ux-agent-selection`
+
+## Evidence
+
+- `node --test tests/**/*.test.js` passed: 449 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:doctor-fixtures` passed.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed.
+- `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.
+
+## Rollback
+
+Revert slice commits in reverse order. The existing deterministic and planner-assisted flows must remain usable during rollback.
+
+## Risks / Notes
+
+- Spinners and colors must not leak into machine-readable output.
+- Displayed model names must reflect real provider invocation semantics.
+- Interactive selectors must remain opt-in and script-safe.
+- Live provider smoke tests depend on installed/authenticated local provider CLIs and should be dogfooded before announcing a release broadly.
+- This PR prepares the package for release but does not publish to npm.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE_BRIEF - slice-00 Spec foundation and source-of-truth sync
+
+## Summary
+
+Created the v30 planning package for interactive CLI UX, visible IA progress, agent/model selectors, provider model correctness, Doctor output, and cross-platform release readiness.
+
+## Validation Against Acceptance Criteria
+
+- [x] Spec folder created.
+- [x] Every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- [x] Source-of-truth docs synchronized.
+- [x] JSON validation captured.
+- [x] `git diff --check` captured.
+- [x] No product code modified.
+
+## Relevant Changes
+
+- New folder: `specs/quiver-v30-interactive-cli-ux-agent-selection/`.
+- Updated `README_FOR_AI.md` to mark v29 shipped in `create-quiver@0.14.1` and v30 planned.
+- Updated `ROADMAP.md` with v0.14.1 shipped and v0.15/v30 planned.
+- Updated `CHANGELOG.md` to move v29 into `0.14.1` and add v30 under Unreleased.
+
+## Pending
+
+- Execute implementation slices from `slice-01` onward.
+
+## Remaining Risks
+
+- Cross-platform behavior and live provider behavior remain unimplemented until later slices.
+
+## Future Recommendations
+
+Follow `EXECUTION_PLAN.md` and keep one commit per slice.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION_BRIEF - slice-00 Spec foundation and source-of-truth sync
+
+## Context
+
+The user approved the production-reviewed plan for Quiver v30. This slice creates the documentary foundation before any product code changes.
+
+## Objective
+
+Create the full v30 spec package and synchronize source-of-truth docs so future agents know v29 shipped in `create-quiver@0.14.1` and v30 is planned work.
+
+## Scope
+
+- Create `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, `EXECUTION_PLAN.md`, and `pr.md`.
+- Create every planned slice with `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Update `README_FOR_AI.md`, `ROADMAP.md`, and `CHANGELOG.md` only for release/status synchronization.
+
+## Acceptance Criteria
+
+- Spec folder exists under `specs/quiver-v30-interactive-cli-ux-agent-selection`.
+- Every slice has the required three handoff files.
+- Every `slice.json` parses.
+- Source-of-truth docs no longer claim v29 is pending publication.
+- No product code changes are made.
+
+## Plan tecnico resumido
+
+Create the documentation package and validation evidence. Do not implement runtime behavior in this slice.
+
+## Suggested Steps
+
+1. Create v30 spec directory and top-level files.
+2. Create all slice directories and handoffs.
+3. Update source-of-truth release/planning docs.
+4. Run JSON parse validation.
+5. Run `git diff --check`.
+6. Run `spec validate` if the current CLI supports the new package.
+
+## Restrictions
+
+- Do not modify source code.
+- Do not update dependencies.
+- Do not publish npm.
+- Do not open a PR from this slice alone unless requested.
+
+## Risks
+
+- Source-of-truth docs can drift if v29 release status is not corrected.
+- Over-documenting implementation details can constrain later slices unnecessarily.
+
+## Completion Checklist
+
+- [ ] Spec files created.
+- [ ] Every slice handoff exists.
+- [ ] JSON parse validation passes.
+- [ ] `git diff --check` passes.
+- [ ] No product code modified.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-00-spec-foundation/slice.json

@@ -0,0 +1,71 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-30-00",
+  "type": "docs",
+  "title": "Spec foundation and source-of-truth sync",
+  "objective": "Create the v30 documentation package and synchronize source-of-truth planning docs before implementation starts.",
+  "description": "Publishes the approved spec, execution plan, PR body, status, evidence report, slice definitions, and handoffs. It also records that v29 shipped in 0.14.1 and v30 is planned work.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v30-interactive-cli-ux-spec-foundation",
+    "branch_name": "feature/QUIVER-30-00-v30-interactive-cli-ux-spec-foundation"
+  },
+  "files": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "BACKLOG.md",
+    "docs/CLI_UX_GUIDE.md",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "allowed_write_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 must land before every implementation slice.",
+  "must": [
+    "Create SPEC.md, STATUS.md, EVIDENCE_REPORT.md, EXECUTION_PLAN.md, and pr.md.",
+    "Create slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md for every slice.",
+    "Record v29 as shipped in 0.14.1 where source-of-truth docs were stale.",
+    "Record v30 as planned work only.",
+    "Avoid product code changes."
+  ],
+  "not_included": [
+    "Implementing CLI UX runtime.",
+    "Changing provider execution.",
+    "Changing command behavior.",
+    "Publishing a package."
+  ],
+  "acceptance": [
+    "Spec folder exists under specs/quiver-v30-interactive-cli-ux-agent-selection.",
+    "Mandatory slice-00 exists.",
+    "Every slice has slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Every slice.json parses successfully.",
+    "README_FOR_AI.md, ROADMAP.md, and CHANGELOG.md do not claim stale v29 publication status.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "git diff --check",
+    "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'))\" {} \\;",
+    "node bin/create-quiver.js spec validate specs/quiver-v30-interactive-cli-ux-agent-selection"
+  ],
+  "validation_hints": [
+    "Keep this slice documentation-only.",
+    "If source-of-truth docs mention v30, say planned, not implemented."
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-26"
+}

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-01-cli-ux-runtime-progress-engine/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE_BRIEF - slice-01 CLI UX runtime and progress engine
+
+## Summary
+
+Added shared CLI UX runtime helpers for branded hierarchy, checks, summaries, next steps, task groups, and safer spinner lifecycle.
+
+## Validation Against Acceptance Criteria
+
+- [x] Human TTY progress output validated.
+- [x] No-TTY fallback validated.
+- [x] JSON/CI/no-color cleanliness validated.
+- [x] Spinner cleanup validated.
+
+## Relevant Changes
+
+- Updated `src/create-quiver/lib/cli/theme.js`.
+- Updated `src/create-quiver/lib/cli/ux.js`.
+- Updated `tests/lib/cli-theme.test.js`.
+- Updated `tests/lib/cli-ux.test.js`.
+
+## Pending
+
+- Later slices must adopt the runtime in specific commands.
+
+## Remaining Risks
+
+- Signal and child-process cleanup for live providers remains for later provider/adoption slices.
+
+## Future Recommendations
+
+Keep command adoption incremental and test each command's human and machine output separately.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-01-cli-ux-runtime-progress-engine/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION_BRIEF - slice-01 CLI UX runtime and progress engine
+
+## Context
+
+v29 added initial UX primitives, but live provider calls still look frozen because commands do not consistently use a progress runtime.
+
+## Objective
+
+Build a reusable CLI UX runtime that makes human output clear and keeps machine output clean.
+
+## Scope
+
+- Extend `src/create-quiver/lib/cli/**`.
+- Add helpers for headings, sections, checks, warnings, errors, summaries, next steps, spinners, and task groups.
+- Add cleanup behavior for spinner lifecycle.
+- Add tests for human, no-color, CI, no-TTY, JSON, ASCII, success, and failure modes.
+
+## Acceptance Criteria
+
+- Human TTY mode can render Quiver-branded progress.
+- No-TTY mode does not appear frozen.
+- JSON/CI/no-color modes stay clean.
+- Spinner lifecycle is safe on success and failure.
+- No command-specific hardcoding of Quiver colors is introduced.
+
+## Plan tecnico resumido
+
+Keep the runtime internal and dependency-light. Use injected IO for testability and avoid direct command coupling to prompt libraries.
+
+## Suggested Steps
+
+1. Review existing `theme.js` and `ux.js`.
+2. Add missing output primitives.
+3. Add progress/task lifecycle helpers.
+4. Add cleanup hooks for error paths.
+5. Add focused unit tests.
+
+## Restrictions
+
+- Do not change IA command behavior in this slice.
+- Do not add a TUI dependency.
+- Do not replace the CLI parser.
+
+## Risks
+
+- Decoration can leak into automation if mode detection is weak.
+- Spinners can leave terminal artifacts if lifecycle cleanup is incomplete.
+
+## Completion Checklist
+
+- [ ] UX runtime helpers implemented.
+- [ ] Human/machine output modes tested.
+- [ ] Spinner cleanup tested.
+- [ ] `git diff --check` passes.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-01-cli-ux-runtime-progress-engine/slice.json

@@ -0,0 +1,69 @@
+{
+  "slice_id": "slice-01-cli-ux-runtime-progress-engine",
+  "ticket": "QUIVER-30-01",
+  "type": "feature",
+  "title": "CLI UX runtime and progress engine",
+  "objective": "Extend the shared CLI UX layer with production-safe headings, sections, checks, summaries, spinners, task groups, fallback output, and lifecycle cleanup.",
+  "description": "Creates the runtime foundation required by every later command-adoption slice so long-running IA commands show real progress without breaking automation.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v30-cli-ux-runtime-progress-engine",
+    "branch_name": "feature/QUIVER-30-01-v30-cli-ux-runtime-progress-engine"
+  },
+  "files": [
+    "src/create-quiver/lib/cli/**",
+    "tests/lib/cli-*.test.js",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/cli/theme.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "src/create-quiver/lib/ai/providers.js",
+    "docs/CLI_UX_GUIDE.md",
+    "tests/lib/**"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/cli/**",
+    "tests/lib/cli-*.test.js",
+    "docs/CLI_UX_GUIDE.md",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-00-spec-foundation"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Shared runtime must land before command adoption and selector work.",
+  "must": [
+    "Add reusable helpers for heading, section, check, warning, error, summary, next steps, and task groups.",
+    "Add spinner lifecycle that always stops on success, failure, timeout, cancellation, and editor review handoff.",
+    "Add plain progress fallback for no-TTY human mode.",
+    "Keep JSON, CI, no-color, TERM=dumb, and ASCII modes clean.",
+    "Use centralized Quiver theme tokens only."
+  ],
+  "not_included": [
+    "Adding role selectors.",
+    "Changing provider model invocation.",
+    "Adopting the runtime in every command."
+  ],
+  "acceptance": [
+    "Human TTY mode can render the approved Quiver heading/check/spinner format.",
+    "No-TTY mode prints readable plain progress without spinner control characters.",
+    "JSON and CI modes do not include colors, prompts, spinners, or decorative symbols.",
+    "Spinner cleanup is covered for success and failure paths.",
+    "Quiver colors remain centralized."
+  ],
+  "tests": [
+    "node --test tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Prefer injected streams and injected prompt/spinner implementations for tests.",
+    "Do not couple command code directly to @clack/prompts."
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 3,
+  "completed_at": "2026-05-26"
+}