create-quiver 0.14.0 → 0.15.0

package/specs/quiver-v29-planner-prepare-context-cli-ux/EXECUTION_PLAN.md

@@ -0,0 +1,72 @@
+# Execution Plan - Quiver v29 Planner Prepare Context CLI UX
+
+## Execution Order
+
+```mermaid
+flowchart TD
+    S00[slice-00: CLI UX spec foundation]
+    S01[slice-01: CLI UX primitives, theme, and dependencies]
+    S02[slice-02: Planner context proposal contract]
+    S03[slice-03: Planner-assisted prepare-context review flow]
+    S04[slice-04: UX flag matrix and compatibility guardrails]
+    S05[slice-05: Progressive command adoption]
+    S06[slice-06: Docs, tests, smoke, and release readiness]
+
+    S00 --> S01
+    S01 --> S02
+    S01 --> S04
+    S02 --> S03
+    S04 --> S03
+    S03 --> S05
+    S04 --> S05
+    S02 --> S06
+    S03 --> S06
+    S04 --> S06
+    S05 --> S06
+```
+
+## Waves
+
+### Wave 0 - Sequential
+
+1. `slice-00-cli-ux-spec-foundation`
+
+This slice must run first. It establishes the approved UX standard, command/flag matrix, and documentation contract.
+
+### Wave 1 - Sequential
+
+1. `slice-01-cli-ux-primitives-theme`
+
+This slice adds shared UX infrastructure and dependencies. Other implementation slices depend on this common layer.
+
+### Wave 2 - Parallel after slice-01
+
+- `slice-02-planner-context-proposal-contract`
+- `slice-04-ux-flag-matrix-compatibility`
+
+These can run in parallel if their write scopes stay separated: proposal validation under AI libs, flag/output guardrails under CLI parsing and UX helpers.
+
+### Wave 3 - Sequential
+
+1. `slice-03-prepare-context-planner-review-flow`
+
+This slice depends on the proposal contract and UX compatibility rules.
+
+### Wave 4 - Sequential
+
+1. `slice-05-progressive-command-adoption`
+
+This slice applies the standard to selected commands after `ai prepare-context` proves the pattern.
+
+### Wave 5 - Sequential close
+
+1. `slice-06-docs-tests-smoke-readiness`
+
+This slice closes docs, generated templates, validation coverage, package smoke, and release readiness.
+
+## Parallel Safety Notes
+
+- Do not run `slice-03` before `slice-02` and `slice-04` are complete.
+- Do not run `slice-05` before `slice-03`; progressive adoption should reuse the proven prepare-context pattern.
+- `slice-06` is never parallel-safe because it validates all previous slices and updates final documentation.
+- If `slice-02` or `slice-04` both need to modify central CLI parsing, run `slice-04` first, then rebase `slice-02`.

package/specs/quiver-v29-planner-prepare-context-cli-ux/SPEC.md

@@ -0,0 +1,173 @@
+# Quiver v29 - Planner-Assisted Prepare Context and CLI UX Standard
+
+**Date:** 2026-05-26
+**Status:** Planned
+**Source:** User-approved requirement to improve `ai prepare-context` with optional planner IA and standardize CLI UX across Quiver.
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+`npx create-quiver ai prepare-context` is currently safe and deterministic: it prepares docs-only context using templates and project signals. That behavior must remain, but Quiver also needs an explicit planner-assisted mode where a configured planner IA can analyze project context and propose richer onboarding documentation.
+
+At the same time, Quiver's CLI UX has grown command by command. It needs a shared standard for loaders, prompts, visual hierarchy, review flows, flags, color usage, non-interactive execution, CI, `--json`, agents, and errors. Without a standard, each new AI command risks solving UX differently.
+
+## Objective
+
+Create a CLI UX standard for Quiver and implement the first high-value application of it:
+
+- keep `ai prepare-context` deterministic by default;
+- add explicit planner-assisted preparation;
+- add safe interactive/review flows;
+- validate planner output before writes;
+- standardize output modes, colors, prompts, loaders, and flags;
+- apply the standard progressively to selected commands.
+
+## Scope
+
+### Included
+
+- UX standard documentation for Quiver CLI commands.
+- Shared CLI UX/theme/editor helpers.
+- Quiver color tokens for human-mode output.
+- Optional `--with-planner` mode for `ai prepare-context`.
+- Optional `--interactive` and `--review` flows where they add value.
+- `--print-prompt`, `--dry-run`, `--json`, CI, no-TTY, no-color compatibility.
+- Planner proposal contract validated with a structured schema.
+- Docs-only allowlist for context writes.
+- `$EDITOR` review before applying AI-generated documentation.
+- Progressive adoption plan for `ai plan`, `spec create`, and `ai pr`.
+- Tests, fixtures, documentation, and package smoke readiness.
+
+### Excluded
+
+- Replacing the whole CLI parser with `commander`, `yargs`, or `oclif`.
+- Adding terminal dashboards with `ink`, `blessed`, or `neo-blessed`.
+- Adding image output protocols.
+- Migrating tests from `node:test` to `vitest`.
+- Storing provider credentials.
+- Allowing planner IA to modify product code.
+- Making interactive prompts mandatory.
+
+## Approved Acceptance Criteria
+
+### Prepare-context modes
+
+1. Given a project with Quiver initialized, when `npx create-quiver ai prepare-context --dry-run` runs, then Quiver keeps the current deterministic behavior, invokes no provider, writes no files, and shows the proposed docs plan.
+2. Given a user runs `npx create-quiver ai prepare-context` without new flags, when the command finishes, then it writes only allowed context docs and does not modify product code.
+3. Given a planner profile or explicit provider is available, when `npx create-quiver ai prepare-context --with-planner --dry-run` runs, then Quiver shows provider invocation, context inputs, candidate docs, and no writes.
+4. Given the user has reviewed dry-run output, when `npx create-quiver ai prepare-context --with-planner` runs, then Quiver invokes the planner, validates the output, and applies only allowed docs-only changes.
+5. Given the user wants to use another AI environment, when `--with-planner --print-prompt` is used, then Quiver prints the exact prompt and exits without provider auth or writes.
+6. Given planner output suggests docs updates, when Quiver evaluates it, then only allowed context docs can be written.
+7. Given planner output attempts product-code, dependency, build, test, lockfile, runtime, absolute, traversal, or outside-repo writes, when Quiver validates it, then the command blocks those writes and reports why.
+8. Given the command writes docs, when it completes, then it snapshots touched docs under `.quiver/runs/<run-id>/snapshots/` and reports files, assumptions, risks, and generation source.
+9. Given provider CLI fails, is missing, or is unauthenticated, when planner mode runs, then Quiver shows an actionable error and writes no partial changes.
+10. Given planner output is incomplete, ambiguous, or invalid, when Quiver processes it, then Quiver does not write files automatically and reports the next safe step.
+
+### CLI UX standard
+
+11. Given the new behavior, when docs are reviewed, then README, command reference, templates, and `README_FOR_AI.md` explain deterministic mode, planner-assisted mode, and safe usage.
+12. Given the new command surface, when tests run, then there is coverage for deterministic mode, planner dry-run, prompt printing, provider failure, invalid output, path blocking, docs-only writes, TTY/no-TTY, CI, and `--json`.
+13. Given any command uses UX output, when it runs, then it clearly indicates whether it is deterministic, planner-assisted, interactive, review, dry-run, or machine mode.
+14. Given multiple docs or checks are proposed, when human output is shown, then Quiver groups files, actions, risks, and next steps with clear visual hierarchy.
+15. Given `--json`, CI, or stdout/stderr redirection, when output is produced, then no spinners, prompts, colors, or decorative symbols appear in machine-readable output.
+16. Given a command supports `--review`, when a proposal exists, then Quiver opens `$VISUAL` or `$EDITOR`; if neither is available, it leaves an artifact path and gives a manual next step.
+17. Given a command supports prompts, when `--interactive` is not used, then it must not block for interactive choices except already documented confirmations.
+18. Given a prompt is added, when automation is needed, then equivalent non-interactive flags must exist.
+19. Given a command uses loaders, when it runs in human TTY mode, then loaders appear only for slow stages and never hide errors.
+20. Given an output uses colors, when colors are disabled or unsupported, then the output remains readable.
+
+### Standard flags and visual identity
+
+21. Given the UX standard, when docs are reviewed, then `--with-planner`, `--interactive`, and `--review` are defined with purpose, rules, and applicable commands.
+22. Given a command is evaluated for those flags, when there is no generation, human decision, review, or planner value, then the command must not expose decorative flags.
+23. Given `--with-planner --review` runs on a command that writes persistent AI-generated docs, then Quiver generates, validates, opens for human review, revalidates, and applies only allowed changes after approval.
+24. Given unsupported UX flags are used on a command, then Quiver fails early with a clear explanation and an alternative command.
+25. Given the Quiver CLI uses loaders, states, badges, or highlighted sections, when colors are enabled, then it uses the Quiver palette consistently:
+    - `quiver.sky` `#86C8F2`
+    - `quiver.blue` `#6BADEB`
+    - `quiver.periwinkle` `#7F9EE8`
+    - `quiver.violet` `#9B82E6`
+    - `quiver.magenta` `#D56AB0`
+26. Given semantic status output is needed, then success/error/warning semantics remain clear and are not replaced blindly by brand colors.
+27. Given a migrated command shows output, then colors and symbols come from centralized helpers, not command-local hardcoding.
+
+## Approved Technical Plan
+
+1. Keep the current no-IA `ai prepare-context` behavior as the default.
+2. Add shared CLI UX helpers behind a small internal abstraction before command adoption.
+3. Add Quiver theme tokens and no-color/CI/no-TTY detection.
+4. Add `$EDITOR` review support with safe fallback.
+5. Add a planner context proposal contract and schema validation.
+6. Add planner-assisted `ai prepare-context` flow with `--with-planner`, `--print-prompt`, `--dry-run`, `--review`, and `--interactive`.
+7. Add strict docs-only allowlist and path safety for planner-generated writes.
+8. Improve human output with loaders and hierarchy only where safe.
+9. Preserve clean JSON output and automation behavior.
+10. Apply the UX flag standard first to `ai prepare-context`, then selected parts of `ai plan`, `spec create`, and `ai pr`.
+11. Document the standard and update generated templates.
+12. Add tests and package/tarball smoke coverage.
+
+## Command/Flag Matrix
+
+| Command | `--with-planner` | `--interactive` | `--review` | Scope in this spec |
+|---|---:|---:|---:|---|
+| `ai prepare-context` | yes | yes | yes | Full implementation |
+| `ai plan` | yes | yes | yes | Progressive adoption and contract alignment |
+| `spec create` | yes | yes | yes | Progressive adoption and guardrails |
+| `ai pr` | no | yes | yes | Review/edit PR body and interactive inputs |
+| `ai onboard` | implicit planner | future | future | Documented follow-up |
+| `ai revise` | future | future | future | Documented follow-up |
+| `ai review-plan` | no planner flag | future | future | Documented follow-up |
+| `doctor` | no | future for fixes | no | Documented follow-up |
+| `flow`, `next`, `graph`, `ai inspect`, `ai export`, list commands | no | no | no | Must remain read-only/scriptable |
+
+## Tools and Dependency Decisions
+
+- Adopt `zod` for validating planner proposal contracts.
+- Adopt `@clack/prompts` behind internal helpers for interactive prompts and human-mode spinners.
+- Use Node native process spawning for `$EDITOR`.
+- Do not adopt `commander`, `yargs`, or `oclif` in this spec.
+- Do not adopt `ink`, `blessed`, `neo-blessed`, terminal image protocols, or `vitest` in this spec.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|---|---|---|---|
+| slice-00 | CLI UX spec foundation | completed | none |
+| slice-01 | CLI UX primitives, theme, and dependencies | completed | slice-00 |
+| slice-02 | Planner context proposal contract | completed | slice-01 |
+| slice-03 | Planner-assisted prepare-context review flow | completed | slice-01, slice-02 |
+| slice-04 | UX flag matrix and compatibility guardrails | completed | slice-01 |
+| slice-05 | Progressive command adoption | completed | slice-03, slice-04 |
+| slice-06 | Docs, tests, smoke, and release readiness | completed | slice-02, slice-03, slice-04, slice-05 |
+
+## Validation Strategy
+
+- `node --test tests/**/*.test.js`
+- focused command tests for `ai prepare-context`
+- focused tests for UX mode detection and theme fallback
+- focused tests for planner proposal schema/path validation
+- focused tests for editor review cancellation and invalid edit fallback
+- `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 check-handoff` for all slice briefs
+- JSON parse validation for all `slice.json` files
+
+## Risks
+
+- New dependencies may affect startup time, CJS/ESM compatibility, and package size.
+- Visual output can break automation unless strictly disabled for `--json`, CI, no-TTY, and pipes.
+- Planner output can be useful but invalid; the validation path must be strict.
+- `$EDITOR` behavior differs across macOS, Linux, Windows PowerShell, Git Bash, and WSL.
+- `--review` can become ambiguous unless consistently defined as "review before persistent writes".
+- Progressive adoption can create inconsistent UX if the matrix is not documented and enforced.
+
+## Resolved Decisions
+
+- No-color behavior uses both `--no-color` and environment detection (`NO_COLOR`, CI, and no-TTY).
+- `ai plan --with-planner` is accepted for UX consistency because planner behavior is already implicit.
+- `spec create --with-planner` is accepted because the command consumes an already reviewed and approved planner output; it does not execute a provider again.

package/specs/quiver-v29-planner-prepare-context-cli-ux/STATUS.md

@@ -0,0 +1,34 @@
+# Quiver v29 Status
+
+**Spec:** `quiver-v29-planner-prepare-context-cli-ux`
+**Status:** Completed
+**Created:** 2026-05-26
+
+## Current State
+
+- Acceptance criteria approved.
+- Technical plan approved.
+- Spec package prepared for execution.
+- `slice-00` completed as the documentary foundation.
+- `slice-01` completed with shared CLI UX primitives, Quiver theme tokens, editor helper, and focused tests.
+- `slice-02` completed with planner proposal schema, parser, docs-only allowlist, unsafe path rejection, and redacted invalid-output artifacts.
+- `slice-04` completed with centralized UX flag support, unsupported/incompatible flag guardrails, and CLI contract tests.
+- `slice-03` completed with explicit planner-assisted `ai prepare-context`, dry-run, prompt printing, provider execution, review, interactive approval, docs-only snapshots, and tests.
+- `slice-05` completed with progressive UX adoption for `ai plan`, `spec create`, and `ai pr`.
+- `slice-06` completed with documentation sync, CLI UX guide, generated template updates, full tests, smoke, package, tarball dry-run, and release readiness evidence.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-cli-ux-spec-foundation | completed | Spec package validated and ready as foundation commit. |
+| slice-01-cli-ux-primitives-theme | completed | Added shared CLI theme/UX/editor helpers and focused unit tests; package smoke passed. |
+| slice-02-planner-context-proposal-contract | completed | Added zod proposal contract, parser, path safety, fixtures, and tests. |
+| slice-03-prepare-context-planner-review-flow | completed | Implemented planner-assisted prepare-context while preserving deterministic default behavior. |
+| slice-04-ux-flag-matrix-compatibility | completed | Added flag matrix, early validation, help entries, and tests for unsupported/incompatible UX flags. |
+| slice-05-progressive-command-adoption | completed | Added review/interactive paths for selected planner/spec/PR commands and tests. |
+| slice-06-docs-tests-smoke-readiness | completed | Final docs, templates, full tests, smoke, package, and tarball readiness passed. |
+
+## Next Step
+
+Open the PR for `quiver-v29-planner-prepare-context-cli-ux`, merge after review, and publish only after the package release process is explicitly requested.

package/specs/quiver-v29-planner-prepare-context-cli-ux/pr.md

@@ -0,0 +1,95 @@
+## Title
+
+Quiver v29: planner-assisted prepare-context and CLI UX standard
+
+## Summary
+
+- Adds a shared UX standard for Quiver CLI commands.
+- Keeps `ai prepare-context` deterministic by default.
+- Adds an explicit planner-assisted prepare-context mode.
+- Adds review and interactive patterns with safe non-interactive alternatives.
+- Standardizes color tokens, loaders, prompts, JSON/CI/no-TTY behavior, and command flag applicability.
+
+## Scope
+
+- CLI UX infrastructure and docs.
+- Planner proposal validation for context documentation.
+- `ai prepare-context` planner-assisted mode.
+- Progressive UX adoption for selected commands.
+- Tests, generated docs, and package readiness.
+
+## Files
+
+Expected areas:
+
+- `src/create-quiver/index.js`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/commands/spec.js`
+- `src/create-quiver/lib/cli/**`
+- `src/create-quiver/lib/ai/**`
+- `docs/**`
+- `README.md`
+- `README_FOR_AI.md`
+- `tests/**`
+- `package.json`
+- `package-lock.json`
+- `specs/quiver-v29-planner-prepare-context-cli-ux/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm.
+- Git.
+- Local provider CLI only for provider-backed tests/manual smoke.
+
+### Worktree Access
+
+- One spec worktree dedicated to `quiver-v29-planner-prepare-context-cli-ux`.
+- 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 deterministic `ai prepare-context`.
+- Run planner-assisted dry-run.
+- Print planner prompt without provider auth.
+- Review planner proposal with `$EDITOR`.
+- Confirm JSON/no-TTY/CI output stays clean.
+- Confirm unsupported UX flags fail with actionable guidance.
+
+### 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-v29-planner-prepare-context-cli-ux`
+
+## Evidence
+
+- Focused command/UX tests passed with 87 tests.
+- Full suite passed with 426 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:doctor-fixtures` passed with 13 fixture states.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed.
+- `npm pack --dry-run` passed for `create-quiver@0.14.0`.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v29-planner-prepare-context-cli-ux` passed.
+
+## Rollback
+
+Revert the slice commits in reverse order. The deterministic `ai prepare-context` default must remain available throughout rollback.
+
+## Risks / Notes
+
+- Dependencies must be validated for CJS/ESM compatibility and package size.
+- Human-mode visual output must never leak into JSON or CI output.
+- Planner output must be treated as untrusted until validated.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-00-cli-ux-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-00 CLI UX spec foundation
+
+## Summary
+
+Created and validated the Quiver v29 spec package for planner-assisted `ai prepare-context` and the shared CLI UX standard.
+
+## Validation Against Acceptance Criteria
+
+- Spec root includes `SPEC.md`, `EXECUTION_PLAN.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, and `pr.md`.
+- Every slice folder includes `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Every `slice.json` parsed successfully.
+- Every brief passed `check-handoff`.
+- `spec validate` passed.
+- `git diff --check` passed.
+
+## Relevant Changes
+
+- Added `specs/quiver-v29-planner-prepare-context-cli-ux/**`.
+- Added 7 planned slices with dependencies and execution waves.
+- Captured approved acceptance criteria, technical plan, UX flag matrix, Quiver color tokens, and validation strategy.
+
+## Pending Work
+
+- Execute implementation slices after this documentation foundation commit.
+
+## Remaining Risks
+
+- Implementation still needs to validate dependency impact, terminal compatibility, planner output safety, and docs sync.
+
+## Future Recommendations
+
+- Keep this slice as the scope anchor for Quiver v29 and update later closure briefs with evidence rather than changing approved scope.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-00-cli-ux-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,45 @@
+# EXECUTION_BRIEF - slice-00 CLI UX spec foundation
+
+## Context
+
+Quiver v29 introduces planner-assisted `ai prepare-context` and a shared CLI UX standard. This slice establishes the documentation foundation only.
+
+## Objective
+
+Commit the approved spec package so later implementation slices have a stable contract.
+
+## Scope
+
+- Review `SPEC.md`, `EXECUTION_PLAN.md`, `STATUS.md`, `pr.md`, and every slice contract.
+- Ensure each slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Validate JSON and Markdown hygiene.
+
+## Acceptance Criteria
+
+- No product code changes.
+- All slice JSON files parse.
+- `git diff --check` passes.
+- Slice dependencies and allowed write paths are explicit.
+
+## Suggested Steps
+
+1. Inspect the spec package.
+2. Validate every `slice.json`.
+3. Run `git diff --check`.
+4. Commit only the spec package.
+
+## Restrictions
+
+- Do not modify `src/`, tests, package files, or generated templates in this slice.
+- Do not implement CLI behavior.
+
+## Risks
+
+- If this slice is skipped, implementation agents may work from inconsistent scope.
+
+## Completion Checklist
+
+- [ ] Spec package reviewed.
+- [ ] JSON validation passed.
+- [ ] Whitespace validation passed.
+- [ ] Documentation foundation committed.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-00-cli-ux-spec-foundation/slice.json

@@ -0,0 +1,58 @@
+{
+  "slice_id": "slice-00-cli-ux-spec-foundation",
+  "ticket": "QUIVER-29-00",
+  "type": "docs",
+  "title": "CLI UX spec foundation",
+  "objective": "Commit the approved spec package, UX standard, execution plan, and slice contracts before implementation begins.",
+  "description": "Creates the documentary foundation for Quiver v29, including the approved acceptance criteria, technical plan, command/flag matrix, execution waves, PR body, and slice handoffs.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-cli-ux-spec-foundation",
+    "branch_name": "feature/QUIVER-29-00-v29-cli-ux-spec-foundation"
+  },
+  "files": [
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "README.md",
+    "docs/reference/commands.md",
+    "specs/quiver-v28-pixel-quiver-feedback-reconciliation/**"
+  ],
+  "allowed_write_paths": [
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This documentation foundation must land before any implementation slice starts.",
+  "must": [
+    "Capture approved acceptance criteria and technical plan.",
+    "Define the UX flag matrix and Quiver color tokens.",
+    "Create EXECUTION_BRIEF.md and CLOSURE_BRIEF.md for every slice.",
+    "Include an execution plan that identifies sequential and parallel-safe waves."
+  ],
+  "not_included": [
+    "Product code changes.",
+    "Dependency installation.",
+    "CLI behavior changes."
+  ],
+  "acceptance": [
+    "The spec root includes SPEC.md, EXECUTION_PLAN.md, STATUS.md, and pr.md.",
+    "Every slice folder includes slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Every slice has explicit dependencies and allowed write paths.",
+    "The documentation package validates as Markdown/JSON and is ready for commit."
+  ],
+  "tests": [
+    "find specs/quiver-v29-planner-prepare-context-cli-ux -name 'slice.json' -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Run this slice first.",
+    "Do not start code implementation before this slice is committed."
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "completed_at": "2026-05-26",
+  "status": "completed"
+}

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-01-cli-ux-primitives-theme/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE_BRIEF - slice-01 CLI UX primitives, theme, and dependencies
+
+## Summary
+
+Completed the shared CLI UX foundation required by later v29 slices.
+
+## Validation Against Acceptance Criteria
+
+- Theme tokens are centralized in `src/create-quiver/lib/cli/theme.js` and tested against the approved Quiver palette.
+- UX mode detection disables prompts, spinners, colors, and decorative output for `--json`, CI, and no-TTY modes.
+- `@clack/prompts` is wrapped behind internal helpers and loaded lazily so command code does not couple to it directly.
+- `$VISUAL`/`$EDITOR` resolution, fallback behavior, shell-free execution, and cancellation paths are tested.
+- `npm run package:quiver` passed after adding dependencies.
+
+## Relevant Changes
+
+- Added runtime dependencies: `@clack/prompts` and `zod`.
+- Added `theme.js`, `ux.js`, and `editor.js` under `src/create-quiver/lib/cli/`.
+- Added focused `node:test` coverage for theme, UX mode/spinner/prompt behavior, and editor resolution/execution.
+
+## Pending Work
+
+- Later slices must adopt these helpers instead of duplicating output logic.
+- `zod` is intentionally added now and will be used by `slice-02` for planner proposal validation.
+
+## Remaining Risks
+
+- `@clack/prompts` is ESM-only; it is loaded through dynamic import and covered by tests, but later command adoption must keep this boundary.
+- Windows editor behavior is covered through injected platform/runner tests; real terminal coverage remains part of final smoke/manual validation.
+
+## Future Recommendations
+
+- Keep UX helpers minimal and command-owned: command behavior should stay testable without a real TTY.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-01-cli-ux-primitives-theme/EXECUTION_BRIEF.md

@@ -0,0 +1,49 @@
+# EXECUTION_BRIEF - slice-01 CLI UX primitives, theme, and dependencies
+
+## Context
+
+Quiver currently has no runtime dependencies and uses direct string output. This slice adds a shared UX layer carefully so later command changes stay consistent and script-safe.
+
+## Objective
+
+Create internal helpers for Quiver-branded human output, prompts, spinners, mode detection, and editor review.
+
+## Scope
+
+- Add `@clack/prompts` and `zod` only if required by the approved implementation path.
+- Add `src/create-quiver/lib/cli/theme.js`.
+- Add `src/create-quiver/lib/cli/ux.js`.
+- Add `src/create-quiver/lib/cli/editor.js`.
+- Add focused unit tests.
+
+## Acceptance Criteria
+
+- Existing commands keep current behavior unless using new helpers internally without visible behavior changes.
+- No output decoration in CI/no-TTY/JSON/no-color modes.
+- Quiver color tokens match the approved palette.
+- `$VISUAL`/`$EDITOR` fallback is tested.
+
+## Suggested Steps
+
+1. Add dependencies and lockfile updates.
+2. Implement theme tokens and symbol fallbacks.
+3. Implement mode detection and human-output helpers.
+4. Implement editor helper with cancellation handling.
+5. Add unit tests.
+6. Run package smoke.
+
+## Restrictions
+
+- Do not migrate CLI parsing in this slice.
+- Do not modify `ai prepare-context` behavior yet.
+
+## Risks
+
+- Dependency ESM/CJS compatibility can break `npx`.
+- Decoration can leak into tests if mode detection is weak.
+
+## Completion Checklist
+
+- [ ] Dependencies justified and package smoke passes.
+- [ ] Theme/helper/editor tests pass.
+- [ ] No hardcoded Quiver colors outside the theme module.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-01-cli-ux-primitives-theme/slice.json

@@ -0,0 +1,75 @@
+{
+  "slice_id": "slice-01-cli-ux-primitives-theme",
+  "ticket": "QUIVER-29-01",
+  "type": "feature",
+  "title": "CLI UX primitives, theme, and dependencies",
+  "objective": "Add shared CLI UX primitives for human output, TTY/CI detection, Quiver colors, prompts, spinners, and editor support without changing command behavior yet.",
+  "description": "Introduces the reusable internal UX layer that later command slices can adopt safely.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-cli-ux-primitives-theme",
+    "branch_name": "feature/QUIVER-29-01-v29-cli-ux-primitives-theme"
+  },
+  "files": [
+    "package.json",
+    "package-lock.json",
+    "src/create-quiver/lib/cli/theme.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "src/create-quiver/lib/cli/editor.js",
+    "tests/lib/cli-theme.test.js",
+    "tests/lib/cli-ux.test.js",
+    "tests/lib/cli-editor.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/next.js",
+    "package.json",
+    "tests/**"
+  ],
+  "allowed_write_paths": [
+    "package.json",
+    "package-lock.json",
+    "src/create-quiver/lib/cli/**",
+    "tests/lib/cli-theme.test.js",
+    "tests/lib/cli-ux.test.js",
+    "tests/lib/cli-editor.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [
+    "slice-00-cli-ux-spec-foundation"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Must run before other implementation slices because it owns shared helpers and dependencies.",
+  "must": [
+    "Add Quiver color tokens in one shared module.",
+    "Detect TTY, CI, JSON, no-color, and machine-output modes.",
+    "Wrap @clack/prompts behind internal helpers so command code is not coupled directly.",
+    "Add editor helper using VISUAL, EDITOR, and safe fallback.",
+    "Keep existing command behavior unchanged."
+  ],
+  "not_included": [
+    "Planner proposal parsing.",
+    "prepare-context behavior changes.",
+    "Full parser migration to commander/yargs/oclif."
+  ],
+  "acceptance": [
+    "Theme tokens are centralized and tested.",
+    "UX helpers disable decoration for CI, no-TTY, --json, and no-color mode.",
+    "Editor helper handles missing editor and cancellation without writes.",
+    "Package smoke still passes after dependencies are added."
+  ],
+  "tests": [
+    "node --test tests/lib/cli-theme.test.js tests/lib/cli-ux.test.js tests/lib/cli-editor.test.js",
+    "npm run package:quiver"
+  ],
+  "validation_hints": [
+    "Prefer small wrappers over direct @clack usage in commands.",
+    "Do not hardcode color values outside theme.js."
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 3,
+  "status": "completed",
+  "completed_at": "2026-05-26"
+}