create-quiver 0.14.1 → 0.15.0

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-02-agent-profile-selection-selectors/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE_BRIEF - slice-02 Agent profile selection and selectors
+
+## Summary
+
+Added backward-compatible named agent profiles per role and a reusable selector helper with non-interactive fallback behavior.
+
+## Validation Against Acceptance Criteria
+
+- [x] Multiple profiles per role validated.
+- [x] Backward compatibility validated.
+- [x] Selectors use configured data only.
+- [x] No-TTY/CI/JSON fallback validated.
+
+## Relevant Changes
+
+- Updated `src/create-quiver/lib/agent-profiles.js`.
+- Added `src/create-quiver/lib/cli/selectors.js`.
+- Updated parser support in `src/create-quiver/index.js`.
+- Updated `ai agent` output in `src/create-quiver/commands/ai.js`.
+- Added `tests/lib/cli-selectors.test.js`.
+- Updated agent profile command/library tests.
+
+## Pending
+
+- Provider model execution mapping is handled by slice-03.
+
+## Remaining Risks
+
+- New selector flags are parsed but not fully consumed by every command until later slices.
+
+## Future Recommendations
+
+Keep selector choices observable in dry-run output so humans can debug defaults before live execution.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-02-agent-profile-selection-selectors/EXECUTION_BRIEF.md

@@ -0,0 +1,56 @@
+# EXECUTION_BRIEF - slice-02 Agent profile selection and selectors
+
+## Context
+
+The user wants commands that need Planners or Executors to show selectors such as `GPT 5.5` and `OPUS 4.7`, sourced from real configured profiles. The same selection must be scriptable through flags.
+
+## Objective
+
+Add the selection contract for agents, specs, slices, methodology, and execution modes.
+
+## Scope
+
+- Multiple named profiles per role.
+- Display-name resolution.
+- Interactive selectors behind `--interactive`.
+- Non-interactive flags.
+- Spec/slice selector data using stable internal values.
+- Methodology selector with only `WDD + SDD` for now.
+
+## Acceptance Criteria
+
+- Selectors use configured data only.
+- Display name appears instead of raw provider when configured.
+- No prompt opens in CI/no-TTY/JSON.
+- Missing default choices fail with actionable guidance.
+- Existing configs remain compatible.
+
+## Plan tecnico resumido
+
+Build selectors as reusable infrastructure, not command-specific prompt code. Keep prompts opt-in and flags authoritative for automation.
+
+## Suggested Steps
+
+1. Extend profile read/write helpers for named arrays per role.
+2. Add display-name resolver.
+3. Add selector helpers with injectable prompt implementation.
+4. Add command-line args for role/spec/slice choices.
+5. Add tests for old and new profile shapes.
+
+## Restrictions
+
+- Do not execute providers in this slice.
+- Do not invent model options.
+- Do not add unsupported methodologies.
+
+## Risks
+
+- Config migration can break existing users if not backward compatible.
+- Labels can become ambiguous if internal selector values are not unique.
+
+## Completion Checklist
+
+- [ ] Multiple profile shape supported.
+- [ ] Display-name resolution tested.
+- [ ] Selectors tested in TTY and no-TTY paths.
+- [ ] Non-interactive flags documented.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-02-agent-profile-selection-selectors/slice.json

@@ -0,0 +1,81 @@
+{
+  "slice_id": "slice-02-agent-profile-selection-selectors",
+  "ticket": "QUIVER-30-02",
+  "type": "feature",
+  "title": "Agent profile selection and selectors",
+  "objective": "Support multiple named IA profiles per role and reusable interactive selectors with non-interactive equivalents.",
+  "description": "Adds role-specific profile selection for Planner, Executor, Reviewer, and Doctor plus selectors for specs, slices, methodology, modes, verbosity, and execution strategy.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v30-agent-profile-selection-selectors",
+    "branch_name": "feature/QUIVER-30-02-v30-agent-profile-selection-selectors"
+  },
+  "files": [
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/cli/**",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/index.js",
+    "tests/lib/agent-profiles.test.js",
+    "tests/commands/ai-agent.test.js",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/ai/export-state.js",
+    "src/create-quiver/lib/slice-graph.js",
+    "src/create-quiver/commands/spec.js",
+    "tests/commands/ai-agent.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/cli/**",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/index.js",
+    "tests/lib/agent-profiles.test.js",
+    "tests/lib/cli-*.test.js",
+    "tests/commands/ai-agent.test.js",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-ux-runtime-progress-engine"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Selector work depends on UX runtime but can precede provider model mapping.",
+  "must": [
+    "Support multiple named profiles per role while keeping existing profile config backward compatible.",
+    "Resolve display name from displayName, model, provider, then role.",
+    "Add selectors only when --interactive is used.",
+    "Add non-interactive flags for planner, executor, reviewer, doctor, spec, slice, and methodology selections.",
+    "Fail actionably when multiple options exist and no default or flag is available.",
+    "Use unique values internally for specs and slices."
+  ],
+  "not_included": [
+    "Passing model arguments to provider commands.",
+    "Adopting selectors in every command.",
+    "Adding methodologies beyond WDD + SDD."
+  ],
+  "acceptance": [
+    "Configured profiles populate selector options.",
+    "No hardcoded model choices appear unless configured by the user.",
+    "Display names are used in headings and summaries.",
+    "CI/no-TTY/JSON modes never open selectors.",
+    "Equivalent flags exist for selector decisions.",
+    "Existing single-profile configurations continue to work."
+  ],
+  "tests": [
+    "node --test tests/lib/agent-profiles.test.js tests/commands/ai-agent.test.js tests/lib/cli-*.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Treat old .quiver/agents/profiles.json shape as backward-compatible input.",
+    "Keep selector labels human-friendly but values path/id stable."
+  ],
+  "estimated_hours": 10,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 4,
+  "completed_at": "2026-05-26"
+}

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-03-provider-model-selection-contract/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-03 Provider model selection contract
+
+## Summary
+
+Implemented the provider/model selection contract for planner and reviewer IA flows.
+
+## Validation Against Acceptance Criteria
+
+- [x] Model support metadata validated.
+- [x] Supported model invocation validated.
+- [x] Unsupported model blocking validated.
+- [x] Existing provider compatibility validated.
+
+## Relevant Changes
+
+- Added `supportsModelSelection`, model arg builders, model-selection metadata, and enforcement to provider adapters.
+- Added dry-run visibility for selected provider models.
+- Wired selected profile models into planner/reviewer command flows.
+- Added targeted provider and command tests.
+- Documented the model-selection contract in `docs/CLI_UX_GUIDE.md` and synchronized `README_FOR_AI.md`.
+
+## Pending
+
+- Executor command flows must use the same provider/model contract in slice-05.
+
+## Remaining Risks
+
+- Provider CLI model flags can vary by installed CLI version; release validation should include local dry-run/live smoke tests where CLIs are available.
+
+## Future Recommendations
+
+Keep provider adapter docs explicit about which model selectors are enforced by CLI flags and which require provider-side configuration.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-03-provider-model-selection-contract/EXECUTION_BRIEF.md

@@ -0,0 +1,54 @@
+# EXECUTION_BRIEF - slice-03 Provider model selection contract
+
+## Context
+
+The UX must not show `GPT 5.5` or `OPUS 4.7` as selected if the real provider command cannot receive or enforce that model choice.
+
+## Objective
+
+Make provider/model selection honest, testable, and safe.
+
+## Scope
+
+- Provider adapter metadata for model support.
+- Model argument construction where supported.
+- Live-mode blocking for unsupported model selection.
+- Dry-run visibility for provider/profile/model behavior.
+- Tests around provider invocations and unsupported combinations.
+
+## Acceptance Criteria
+
+- Selected models affect real provider invocation when supported.
+- Unsupported model selection blocks live execution with next steps.
+- Prompt-only and dry-run flows stay provider-auth-free where applicable.
+- Existing provider usage without model remains compatible.
+
+## Plan tecnico resumido
+
+Extend provider definitions with model support metadata and validate selected profiles before spawning provider CLIs.
+
+## Suggested Steps
+
+1. Inspect provider CLI capabilities already assumed by Quiver.
+2. Add adapter metadata and model arg builder.
+3. Wire selected profiles into provider invocation.
+4. Add blocking error for unsupported model selection.
+5. Add tests for supported, unsupported, dry-run, and prompt-only paths.
+
+## Restrictions
+
+- Do not add credentials or secret storage.
+- Do not add unsupported providers.
+- Do not silently ignore configured models in live mode.
+
+## Risks
+
+- Provider CLI model flags can differ by installed version.
+- Over-blocking can frustrate users if a provider supports model selection through config but not CLI flags.
+
+## Completion Checklist
+
+- [ ] Provider metadata implemented.
+- [ ] Model invocation tests pass.
+- [ ] Unsupported model blocking tested.
+- [ ] Docs explain provider/model limits.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-03-provider-model-selection-contract/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-03-provider-model-selection-contract",
+  "ticket": "QUIVER-30-03",
+  "type": "feature",
+  "title": "Provider model selection contract",
+  "objective": "Ensure selected profile/model values either affect real provider invocations or block live execution with clear guidance.",
+  "description": "Adds provider adapter metadata for model selection support, model argument mapping, display-only restrictions, and validation before live IA execution.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v30-provider-model-selection-contract",
+    "branch_name": "feature/QUIVER-30-03-v30-provider-model-selection-contract"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/lib/ai-providers.test.js",
+    "tests/commands/ai-*.test.js",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/lib/ai-providers.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/lib/ai-providers.test.js",
+    "tests/commands/ai-*.test.js",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-02-agent-profile-selection-selectors"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Depends on selected profile shape and display-name semantics.",
+  "must": [
+    "Add provider adapter metadata for supportsModelSelection.",
+    "Add model argument builder per supported provider where safe.",
+    "Validate selected profile model before live provider execution.",
+    "Block live execution if model selection is unsupported and the selected model would be misleading.",
+    "Expose clear dry-run output showing command, provider, profile, model, and whether model selection is enforced."
+  ],
+  "not_included": [
+    "Adding new providers.",
+    "Storing credentials.",
+    "Changing profile selector UI."
+  ],
+  "acceptance": [
+    "Provider invocation includes model args when adapter support exists.",
+    "Unsupported model selection blocks live mode with an actionable message.",
+    "Dry-run makes model support status visible.",
+    "Prompt-only mode does not require provider auth.",
+    "Existing provider behavior without model profiles remains compatible."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-providers.test.js tests/commands/ai-onboard.test.js tests/commands/ai-plan.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Do not claim support for a provider model flag unless the actual CLI supports it.",
+    "Prefer explicit blocking over display-only ambiguity in live mode."
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 5,
+  "completed_at": "2026-05-26"
+}

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-04-planner-ia-progress-flows/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-04 Planner IA progress flows
+
+## Summary
+
+Implemented visible TTY progress for planner-oriented IA commands.
+
+## Validation Against Acceptance Criteria
+
+- [x] Planner command progress validated.
+- [x] Display-name headings validated.
+- [x] Provider-running spinner validated.
+- [x] Failure/cancel cleanup validated.
+- [x] Machine output cleanliness validated.
+
+## Relevant Changes
+
+- Added command-level UX helpers for progress headings, checks, and provider spinners.
+- Wrapped planner/reviewer provider execution in progress lifecycle handling.
+- Preserved clean output for dry-run, prompt-only, CI, and non-TTY flows.
+- Added tests for successful progress and provider-failure spinner cleanup.
+
+## Pending
+
+- Executor, PR, doctor, init, and spec create adoption remain in later slices.
+
+## Remaining Risks
+
+- Direct test runs in TTY mode can show clack spinner artifacts in logs; final release validation should decide if command tests should force non-TTY by default.
+
+## Future Recommendations
+
+Keep the progress-stage list close to command behavior so future command changes update UX and tests together.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-04-planner-ia-progress-flows/EXECUTION_BRIEF.md

@@ -0,0 +1,57 @@
+# EXECUTION_BRIEF - slice-04 Planner IA progress flows
+
+## Context
+
+The observed bug is in a planner flow: `ai prepare-context --with-planner` can run silently while waiting for provider output.
+
+## Objective
+
+Apply the new UX runtime to planner-oriented IA commands so users see real progress and selected profile/model names.
+
+## Scope
+
+- `ai onboard`
+- `ai prepare-context --with-planner`
+- `ai plan`
+- `ai review-plan`
+- Planner/Reviewer display names.
+- Provider-running spinner.
+- Failure/cancel cleanup.
+
+## Acceptance Criteria
+
+- `ai prepare-context --with-planner` shows progress and does not look frozen.
+- Headings use selected profile/model names, not provider fallback when a better label exists.
+- `--print-prompt` stays clean and copyable.
+- `--json`, CI, no-TTY, and no-color output stay clean.
+- Provider failures stop spinners and produce actionable errors.
+
+## Plan tecnico resumido
+
+Wrap real command stages with the progress runtime and use profile/provider validation before provider execution.
+
+## Suggested Steps
+
+1. Define real stages for each planner command.
+2. Add heading/display name resolution.
+3. Wrap provider execution in spinner lifecycle.
+4. Add failure/cancel handling.
+5. Add tests with injected slow and failing providers.
+
+## Restrictions
+
+- Do not fake progress checks.
+- Do not add selectors without `--interactive`.
+- Do not change deterministic `ai prepare-context` behavior unless adopting clearer output safely.
+
+## Risks
+
+- `commands/ai.js` is shared and can conflict with executor/PR changes.
+- Provider stderr can be noisy and must be summarized safely.
+
+## Completion Checklist
+
+- [ ] Planner commands show real progress.
+- [ ] Display names are correct.
+- [ ] Failure/cancel paths tested.
+- [ ] Machine output stays clean.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-04-planner-ia-progress-flows/slice.json

@@ -0,0 +1,85 @@
+{
+  "slice_id": "slice-04-planner-ia-progress-flows",
+  "ticket": "QUIVER-30-04",
+  "type": "feature",
+  "title": "Planner IA progress flows",
+  "objective": "Apply the UX runtime, selectors, display names, and provider model contract to planner-oriented IA commands.",
+  "description": "Adds visible real-stage progress to ai onboard, ai prepare-context --with-planner, ai plan, and ai review-plan.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v30-planner-ia-progress-flows",
+    "branch_name": "feature/QUIVER-30-04-v30-planner-ia-progress-flows"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/**",
+    "src/create-quiver/lib/cli/**",
+    "tests/commands/ai-onboard.test.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/ai-review-plan.test.js",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/context-packs.js",
+    "src/create-quiver/lib/ai/context-proposal.js",
+    "src/create-quiver/lib/ai/plan-review.js",
+    "src/create-quiver/lib/ai/providers.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/**",
+    "src/create-quiver/lib/cli/**",
+    "tests/commands/ai-onboard.test.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/ai-review-plan.test.js",
+    "tests/commands/ai-prepare-context*.test.js",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "README.md",
+    "README_FOR_AI.md",
+    "specs/quiver-v30-interactive-cli-ux-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-ux-runtime-progress-engine",
+    "slice-02-agent-profile-selection-selectors",
+    "slice-03-provider-model-selection-contract"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run after core profile/provider contracts, but may conflict with slice-05 in commands/ai.js.",
+  "must": [
+    "Show selected Planner or Reviewer display name in headings.",
+    "Add real progress stages for ai onboard.",
+    "Add real progress stages for ai prepare-context --with-planner.",
+    "Add real progress stages for ai plan and ai review-plan.",
+    "Show spinner while provider is running.",
+    "Stop spinner and persist failure/cancel state on errors.",
+    "Keep --print-prompt copyable and free of spinners."
+  ],
+  "not_included": [
+    "Executor slice execution progress.",
+    "PR progress.",
+    "Doctor output."
+  ],
+  "acceptance": [
+    "ai prepare-context --with-planner no longer appears frozen in human TTY mode.",
+    "Headings use configured profile/model display names.",
+    "Dry-run and print-prompt remain safe and clear.",
+    "Provider failure stops spinner and reports actionable next steps.",
+    "JSON/CI/no-TTY outputs stay clean."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-onboard.test.js tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use injected provider runners for slow/failing provider tests.",
+    "Do not mark a stage successful before its corresponding action has completed."
+  ],
+  "estimated_hours": 12,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 5,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-05-executor-pr-progress-flows/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE_BRIEF - slice-05 Executor, execution-plan, and PR progress flows
+
+## Summary
+
+Implemented executor, execution-plan, and PR progress flows with selector-safe execution.
+
+## Validation Against Acceptance Criteria
+
+- [x] Executor heading/display validated.
+- [x] Spec/slice selector behavior validated.
+- [x] Dependency-safe slice recommendations validated.
+- [x] PR progress and `gh` error visibility validated.
+
+## Relevant Changes
+
+- Added executor profile/model propagation and dry-run model visibility.
+- Added interactive ready-slice and executor profile selection.
+- Added progress for executor provider execution, validations, commits, execution-plan waves, GitHub preflight, and PR creation.
+- Extended UX flag support for executor commands.
+- Added focused tests for selectors and PR progress.
+
+## Pending
+
+- Final cross-command docs and smoke evidence belong in slice-08.
+
+## Remaining Risks
+
+- `ai execute-plan --interactive` is accepted for UX consistency, but a full execution-strategy selector remains a future enhancement.
+- Direct TTY unit runs can still show spinner artifacts in logs.
+
+## Future Recommendations
+
+Use real dogfooding command logs to decide whether `--verbose` should be added as a separate follow-up.

package/specs/quiver-v30-interactive-cli-ux-agent-selection/slices/slice-05-executor-pr-progress-flows/EXECUTION_BRIEF.md

@@ -0,0 +1,57 @@
+# EXECUTION_BRIEF - slice-05 Executor, execution-plan, and PR progress flows
+
+## Context
+
+Execution and PR commands are sensitive because they can modify files, create commits, create worktrees, and open PRs. Their UX must show progress without hiding scope or validation failures.
+
+## Objective
+
+Apply the UX/progress/profile-selector contract to executor and PR flows.
+
+## Scope
+
+- `ai execute-slice`
+- `ai execute-plan`
+- relevant `ai prompt-slice` output constraints
+- `ai pr`
+- Executor/spec/slice/strategy selectors in interactive mode
+- Progress stages and machine-output fallback
+
+## Acceptance Criteria
+
+- Executor display name appears in execution headings.
+- Spec/slice selectors use stable values and dependency-aware recommendations.
+- Blocked slices are not silently selected.
+- PR creation shows preflight and creation progress.
+- `gh` errors remain visible and actionable.
+- Machine output remains clean.
+
+## Plan tecnico resumido
+
+Adopt the shared runtime in execution and PR commands while preserving existing safety gates, scope validation, one-commit-per-slice behavior, and dry-run-first patterns.
+
+## Suggested Steps
+
+1. Define real stages for execution and PR commands.
+2. Add spec/slice/executor selection points behind `--interactive`.
+3. Wrap provider and gh execution with progress lifecycle.
+4. Preserve validation and scope gates.
+5. Add focused tests for human and no-TTY output.
+
+## Restrictions
+
+- Do not weaken write-scope validation.
+- Do not bypass existing PR open-slice blockers.
+- Do not add provider execution to prompt-only commands.
+
+## Risks
+
+- `commands/ai.js` conflicts with planner-flow adoption.
+- PR progress can obscure `gh` auth errors if not surfaced cleanly.
+
+## Completion Checklist
+
+- [ ] Execution command progress validated.
+- [ ] PR progress validated.
+- [ ] Selector dependencies validated.
+- [ ] Machine output cleanliness validated.