create-quiver 0.14.0 → 0.15.0

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-02-planner-context-proposal-contract/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-02 Planner context proposal contract
+
+## Summary
+
+Completed a strict planner context proposal contract for future `ai prepare-context --with-planner` usage.
+
+## Validation Against Acceptance Criteria
+
+- Valid structured JSON and fenced JSON planner outputs parse into a normalized docs-only write plan.
+- Unsafe paths are rejected before writes, including product code, dependency/lockfiles, absolute paths, traversal paths, generated outputs, runtime/build config, `.quiver/`, and unapproved docs.
+- Schema validation uses `zod` and reports actionable issues with safe next steps.
+- Invalid raw output can be persisted as a redacted run artifact under `.quiver/runs/<run-id>/raw/`.
+
+## Relevant Changes
+
+- Added `src/create-quiver/lib/ai/context-proposal.schema.js`.
+- Added `src/create-quiver/lib/ai/context-proposal.js`.
+- Added valid, fenced, malformed, product-code, absolute-path, and traversal fixtures under `tests/fixtures/ai-context-proposals/`.
+- Added focused unit tests in `tests/lib/ai-context-proposal.test.js`.
+
+## Pending Work
+
+- `ai prepare-context` must consume this contract in a later slice.
+
+## Remaining Risks
+
+- Planner output compatibility must be tested with real provider transcripts later.
+- The allowlist intentionally matches current `prepare-context` docs; future docs must be added explicitly to avoid unsafe broadening.
+
+## Future Recommendations
+
+- Keep the schema versioned if external agents or dashboards start consuming it.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-02-planner-context-proposal-contract/EXECUTION_BRIEF.md

@@ -0,0 +1,47 @@
+# EXECUTION_BRIEF - slice-02 Planner context proposal contract
+
+## Context
+
+Planner-assisted `ai prepare-context` needs a strict contract before any provider output can affect project docs.
+
+## Objective
+
+Create a safe parser and schema for planner-generated documentation proposals.
+
+## Scope
+
+- Add proposal schema.
+- Add proposal parser/normalizer.
+- Add docs-only allowlist.
+- Add path safety checks.
+- Add valid and invalid fixtures.
+
+## Acceptance Criteria
+
+- Unsafe planner output is rejected before writes.
+- Valid planner output becomes a normalized docs-only plan.
+- Errors explain what failed and how to continue safely.
+
+## Suggested Steps
+
+1. Define proposal JSON shape.
+2. Add `zod` schema validation.
+3. Add path normalization and allowlist checks.
+4. Add fixtures for valid, invalid, product-code, absolute-path, traversal, and malformed outputs.
+5. Add unit tests.
+
+## Restrictions
+
+- Do not call providers in this slice.
+- Do not modify `runPrepareContext` write behavior yet.
+
+## Risks
+
+- Too-strict parsing can reject useful planner output; prefer clear repair guidance over unsafe fallback.
+
+## Completion Checklist
+
+- [ ] Valid fixtures parse.
+- [ ] Unsafe fixtures fail.
+- [ ] Proposal errors are actionable.
+- [ ] No docs are written by this slice.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-02-planner-context-proposal-contract/slice.json

@@ -0,0 +1,71 @@
+{
+  "slice_id": "slice-02-planner-context-proposal-contract",
+  "ticket": "QUIVER-29-02",
+  "type": "feature",
+  "title": "Planner context proposal contract",
+  "objective": "Define and validate the structured proposal format used when a planner IA suggests context documentation updates.",
+  "description": "Adds the parser, schema, path safety, allowlist checks, and diff-ready internal model for planner-generated context proposals.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-planner-context-proposal-contract",
+    "branch_name": "feature/QUIVER-29-02-v29-planner-context-proposal-contract"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/context-proposal.js",
+    "src/create-quiver/lib/ai/context-proposal.schema.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "tests/lib/ai-context-proposal.test.js",
+    "tests/fixtures/ai-context-proposals/**",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/lib/ai/safety.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/commands/ai-onboard.test.js",
+    "tests/lib/ai-context-packs.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/context-proposal.js",
+    "src/create-quiver/lib/ai/context-proposal.schema.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "tests/lib/ai-context-proposal.test.js",
+    "tests/fixtures/ai-context-proposals/**",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-ux-primitives-theme"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run in parallel with slice-04 if both avoid central CLI parser conflicts.",
+  "must": [
+    "Validate planner proposals with zod.",
+    "Accept structured JSON or fenced JSON output when safe.",
+    "Reject paths outside the repo, path traversal, absolute writes, product code, dependencies, lockfiles, build files, generated files, and runtime config.",
+    "Produce a normalized docs-only write plan that existing prepare-context logic can consume.",
+    "Persist invalid raw output as an artifact only when safe and redacted."
+  ],
+  "not_included": [
+    "Invoking provider CLIs.",
+    "Writing docs from planner proposals.",
+    "Interactive editor review."
+  ],
+  "acceptance": [
+    "Valid planner proposal fixtures parse into a normalized internal model.",
+    "Invalid or unsafe proposals fail before writes.",
+    "Allowed docs-only paths are explicit and tested.",
+    "The parser reports actionable errors with next safe commands."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-context-proposal.test.js"
+  ],
+  "validation_hints": [
+    "Treat planner output as untrusted input.",
+    "Keep schema and allowlist close to the proposal parser."
+  ],
+  "estimated_hours": 8,
+  "actual_hours": 3,
+  "status": "completed",
+  "completed_at": "2026-05-26"
+}

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-03-prepare-context-planner-review-flow/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE_BRIEF - slice-03 Planner-assisted prepare-context review flow
+
+## Summary
+
+Completed explicit planner-assisted context preparation for `ai prepare-context`.
+
+## Validation Against Acceptance Criteria
+
+- Default deterministic `ai prepare-context` behavior remains unchanged and existing tests still pass.
+- `--with-planner --dry-run` reports provider invocation, candidate docs, allowed paths, and writes nothing.
+- `--with-planner --print-prompt` prints the exact planner prompt without provider auth or writes.
+- Live `--with-planner` invokes the provider, validates the proposal contract, creates snapshots, and writes only allowed docs.
+- Provider failures, invalid planner output, review cancellation, and declined interactive approval leave docs untouched.
+- `--review` writes a proposal artifact, opens or uses the editor flow, and revalidates edited JSON before writing.
+
+## Relevant Changes
+
+- Extended `src/create-quiver/commands/ai.js` with planner prompt building, dry-run/prompt-only reports, provider execution, proposal review, interactive confirmation, and planner write integration.
+- Updated `src/create-quiver/index.js` to forward planner UX flags/options into `runPrepareContext`.
+- Added `tests/commands/ai-prepare-context-planner.test.js`.
+
+## Pending Work
+
+- Progressive command adoption should reuse this pattern.
+
+## Remaining Risks
+
+- Real provider outputs may need fixture updates after dogfooding.
+- Review mode uses a temporary JSON artifact; future UX can make this artifact easier to discover or persist under run state when useful.
+
+## Future Recommendations
+
+- Consider a future `ai describe-project` alias only if users still find `prepare-context --with-planner` unclear.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-03-prepare-context-planner-review-flow/EXECUTION_BRIEF.md

@@ -0,0 +1,52 @@
+# EXECUTION_BRIEF - slice-03 Planner-assisted prepare-context review flow
+
+## Context
+
+The deterministic `ai prepare-context` path must remain default. Planner-assisted mode is opt-in and must never bypass docs-only safety.
+
+## Objective
+
+Implement `ai prepare-context --with-planner` with dry-run, prompt printing, review, and interactive support.
+
+## Scope
+
+- Parse new flags for `ai prepare-context`.
+- Build planner prompt from context pack and current draft plan.
+- Invoke provider only when not dry-run/print-prompt.
+- Validate planner proposal.
+- Snapshot and write docs-only changes.
+- Add editor review flow.
+
+## Acceptance Criteria
+
+- Existing deterministic behavior stays compatible.
+- Planner mode is explicit.
+- No partial writes on provider, validation, editor, or snapshot failure.
+- Human output has clear next safe commands.
+
+## Suggested Steps
+
+1. Extend CLI args for `ai prepare-context`.
+2. Add planner prompt builder or reuse onboarding prompt pieces.
+3. Add dry-run and print-prompt paths.
+4. Add provider execution path.
+5. Add proposal validation and write integration.
+6. Add review flow and tests.
+
+## Restrictions
+
+- Do not allow product code writes.
+- Do not make planner mode default.
+- Do not require interactive prompts for automation.
+
+## Risks
+
+- Combining provider execution, review, and writes can create partial-state bugs unless staged carefully.
+
+## Completion Checklist
+
+- [ ] Default mode unchanged.
+- [ ] Planner dry-run and print-prompt tested.
+- [ ] Provider failure tested.
+- [ ] Review cancellation tested.
+- [ ] Snapshot and docs-only write tested.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-03-prepare-context-planner-review-flow/slice.json

@@ -0,0 +1,82 @@
+{
+  "slice_id": "slice-03-prepare-context-planner-review-flow",
+  "ticket": "QUIVER-29-03",
+  "type": "feature",
+  "title": "Planner-assisted prepare-context review flow",
+  "objective": "Implement `ai prepare-context --with-planner` with dry-run, print-prompt, review, interactive, docs-only writes, snapshots, and safe fallback.",
+  "description": "Extends the current deterministic prepare-context command while preserving its default behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-prepare-context-planner-review-flow",
+    "branch_name": "feature/QUIVER-29-03-v29-prepare-context-planner-review-flow"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/lib/ai/context-proposal.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "tests/commands/ai-onboard.test.js",
+    "tests/commands/ai-prepare-context-planner.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/**",
+    "tests/commands/ai-onboard.test.js",
+    "tests/commands/ai-plan.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/onboarding-template.js",
+    "src/create-quiver/lib/ai/context-proposal.js",
+    "src/create-quiver/lib/ai/artifacts.js",
+    "tests/commands/ai-onboard.test.js",
+    "tests/commands/ai-prepare-context-planner.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [
+    "slice-02-planner-context-proposal-contract",
+    "slice-04-ux-flag-matrix-compatibility"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Main command integration touches central AI command behavior and should run after contract/flag guardrails are stable.",
+  "must": [
+    "Keep current prepare-context behavior as default.",
+    "Add --with-planner as explicit planner-assisted mode.",
+    "Support --print-prompt without provider auth or writes.",
+    "Support --dry-run without provider execution or writes.",
+    "Support --review with editor review and revalidation.",
+    "Support --interactive only in TTY and with non-interactive flag equivalents.",
+    "Create snapshots before writes.",
+    "Fallback safely to deterministic mode guidance when planner fails."
+  ],
+  "not_included": [
+    "Applying UX flags to unrelated commands.",
+    "Allowing planner writes outside context docs.",
+    "Changing `analyze` behavior."
+  ],
+  "acceptance": [
+    "Default prepare-context tests still pass.",
+    "--with-planner --dry-run reports invocation and candidate docs without writes.",
+    "--with-planner --print-prompt prints exact prompt and exits without provider auth.",
+    "--with-planner --review opens/uses editor flow and revalidates edited proposal.",
+    "Provider failure and invalid planner output produce no partial writes.",
+    "Docs-only snapshots are created before live writes."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-onboard.test.js tests/commands/ai-prepare-context-planner.test.js",
+    "node --test tests/lib/ai-context-proposal.test.js"
+  ],
+  "validation_hints": [
+    "Use injected provider/editor functions in tests.",
+    "Verify no product-code writes through path allowlist tests."
+  ],
+  "estimated_hours": 10,
+  "actual_hours": 5,
+  "status": "completed",
+  "completed_at": "2026-05-26"
+}

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-04-ux-flag-matrix-compatibility/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE_BRIEF - slice-04 UX flag matrix and compatibility guardrails
+
+## Summary
+
+Completed centralized UX flag support and early compatibility validation.
+
+## Validation Against Acceptance Criteria
+
+- `--with-planner`, `--interactive`, and `--review` support is centralized in `src/create-quiver/lib/cli/ux-flags.js`.
+- Unsupported UX flags fail before command dispatch and before side effects.
+- Incompatible combinations such as `--json --interactive` and `--json --review` fail before command dispatch.
+- `ai pr` supports `--interactive` and `--review`, while rejecting `--with-planner`.
+- Read-only commands such as `flow`, `ai inspect`, and `ai export` reject unsupported UX flags.
+- Existing `plan --json` output remains parseable when UX flags are not requested.
+
+## Relevant Changes
+
+- Added `src/create-quiver/lib/cli/ux-flags.js`.
+- Updated `src/create-quiver/index.js` to parse UX flags, validate them early, document them in help, and forward supported values to future command handlers.
+- Added `tests/commands/ux-flags.test.js`.
+
+## Pending Work
+
+- Later slices should rely on this matrix instead of ad hoc flag behavior.
+- `slice-03` must implement actual `ai prepare-context --with-planner` behavior now that flags are accepted and forwarded.
+
+## Remaining Risks
+
+- Command help and docs must stay aligned with this matrix.
+- Some supported flags are forwarded before their command behavior exists; final release readiness depends on `slice-03` and `slice-05` completing before merge.
+
+## Future Recommendations
+
+- Consider generating docs/reference command flag tables from the matrix in a future spec.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-04-ux-flag-matrix-compatibility/EXECUTION_BRIEF.md

@@ -0,0 +1,46 @@
+# EXECUTION_BRIEF - slice-04 UX flag matrix and compatibility guardrails
+
+## Context
+
+Quiver needs standard UX flags without making every command accept every flag.
+
+## Objective
+
+Centralize and enforce command support for `--with-planner`, `--interactive`, and `--review`.
+
+## Scope
+
+- Add a command/flag matrix.
+- Add parser validation for UX flags.
+- Add incompatible-combination errors.
+- Add tests for CI/no-TTY/JSON behavior.
+
+## Acceptance Criteria
+
+- Unsupported flags fail before side effects.
+- Supported flags are discoverable in help/docs.
+- Machine modes are never decorated.
+
+## Suggested Steps
+
+1. Add central flag support matrix.
+2. Extend arg parsing for new flags.
+3. Validate unsupported and incompatible combinations early.
+4. Add command contract tests.
+5. Confirm existing commands keep passing.
+
+## Restrictions
+
+- Do not implement planner proposal writes here.
+- Do not add prompts to commands in this slice.
+
+## Risks
+
+- Over-strict validation can break existing scripts if flags were previously ignored. Make errors clear and only reject new UX flags.
+
+## Completion Checklist
+
+- [ ] Matrix exists in code.
+- [ ] Matrix is tested.
+- [ ] CI/no-TTY/JSON behavior is protected.
+- [ ] Unsupported flags produce actionable output.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-04-ux-flag-matrix-compatibility/slice.json

@@ -0,0 +1,73 @@
+{
+  "slice_id": "slice-04-ux-flag-matrix-compatibility",
+  "ticket": "QUIVER-29-04",
+  "type": "feature",
+  "title": "UX flag matrix and compatibility guardrails",
+  "objective": "Add centralized rules for UX flags, incompatible combinations, machine-output modes, and unsupported command guidance.",
+  "description": "Prevents inconsistent adoption of `--with-planner`, `--interactive`, and `--review` by making command support explicit and testable.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-ux-flag-matrix-compatibility",
+    "branch_name": "feature/QUIVER-29-04-v29-ux-flag-matrix-compatibility"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/cli/ux-flags.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/ux-flags.test.js",
+    "tests/lib/cli-ux.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/cli/**",
+    "tests/commands/cli-contract.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/cli/ux-flags.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "tests/commands/cli-contract.test.js",
+    "tests/commands/ux-flags.test.js",
+    "tests/lib/cli-ux.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [
+    "slice-01-cli-ux-primitives-theme"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run in parallel with slice-02 if central parser conflicts are avoided.",
+  "must": [
+    "Define which commands support --with-planner, --interactive, and --review.",
+    "Reject unsupported UX flags with actionable messages.",
+    "Reject incompatible combinations such as --json --interactive and --json --review.",
+    "Ensure CI/no-TTY/--json disables spinners, colors, prompts, and decorative output.",
+    "Keep machine-readable stdout parseable."
+  ],
+  "not_included": [
+    "Implementing planner mode itself.",
+    "Migrating all commands to interactive mode.",
+    "Changing existing command semantics beyond flag validation."
+  ],
+  "acceptance": [
+    "Command/flag matrix is enforced in code and documented.",
+    "Unsupported flags fail before side effects.",
+    "Incompatible flag combinations fail before side effects.",
+    "JSON output stays undecorated.",
+    "Human-mode helpers remain opt-in."
+  ],
+  "tests": [
+    "node --test tests/commands/ux-flags.test.js tests/commands/cli-contract.test.js",
+    "node --test tests/lib/cli-ux.test.js"
+  ],
+  "validation_hints": [
+    "Tests should cover both supported and unsupported commands.",
+    "Do not allow partial command execution after flag validation failure."
+  ],
+  "estimated_hours": 7,
+  "actual_hours": 2,
+  "status": "completed",
+  "completed_at": "2026-05-26"
+}

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-05-progressive-command-adoption/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE_BRIEF - slice-05 Progressive command adoption
+
+## Summary
+
+Completed progressive UX adoption for selected high-value commands.
+
+## Validation Against Acceptance Criteria
+
+- `ai plan` accepts the UX flags, reports planner/review/interactive intent in dry-run, supports editor review of provider drafts before saving, and can require interactive approval before saving.
+- `spec create` supports `--review` as a guarded preview review before writes and `--interactive` as explicit confirmation before generation.
+- `ai pr` supports review/edit of `pr.md` before creating the PR plan and interactive confirmation before `gh pr create`.
+- `ai pr` still rejects `--with-planner` through the centralized flag matrix.
+- Existing tests for the affected commands continue to pass.
+
+## Relevant Changes
+
+- Updated `src/create-quiver/commands/ai.js` for `ai plan` draft review/interactive confirmation and `ai pr` PR body review/interactive confirmation.
+- Updated `src/create-quiver/commands/spec.js` for `spec create` review/interactive guardrails.
+- Updated `src/create-quiver/index.js` to await async `spec create`.
+- Added command tests in `tests/commands/ai-plan.test.js`, `tests/commands/spec-create.test.js`, and `tests/commands/ai-pr.test.js`.
+
+## Pending Work
+
+- Final docs and command reference updates must document these supported flags.
+- Remaining commands should be migrated only through future scoped slices.
+
+## Remaining Risks
+
+- Command UX can drift unless docs and matrix are updated in the final slice.
+- `spec create --review` reviews the preview artifact and does not treat preview edits as source-of-truth changes; this is intentional guardrail behavior, but docs should explain it.
+
+## Future Recommendations
+
+- Consider future UX adoption for `doctor --interactive --fix`, `ai onboard`, and `ai revise`.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-05-progressive-command-adoption/EXECUTION_BRIEF.md

@@ -0,0 +1,46 @@
+# EXECUTION_BRIEF - slice-05 Progressive command adoption
+
+## Context
+
+After `ai prepare-context` implements the full pattern, selected commands should adopt the same standard where it clearly improves UX.
+
+## Objective
+
+Apply UX flags and review/interactive behavior to `ai plan`, `spec create`, and `ai pr` without redesigning unrelated commands.
+
+## Scope
+
+- `ai plan`: planner-related UX flags and optional review flow.
+- `spec create`: guarded review/interactive path.
+- `ai pr`: interactive PR inputs and review/edit of `pr.md`; no `--with-planner`.
+- Tests for supported and unsupported combinations.
+
+## Acceptance Criteria
+
+- No command becomes interactive by default.
+- Every interactive choice has a flag equivalent.
+- Machine output stays clean.
+- Unsupported flags fail clearly.
+
+## Suggested Steps
+
+1. Start with `ai pr --review` because it maps cleanly to existing `pr.md`.
+2. Add minimal `spec create --review` guardrails.
+3. Add `ai plan` UX flag compatibility.
+4. Add tests for each.
+
+## Restrictions
+
+- Do not apply the standard to all commands in this slice.
+- Do not add planner mode to `ai pr`.
+
+## Risks
+
+- Broad command changes can create regressions. Keep adoption narrow and test heavily.
+
+## Completion Checklist
+
+- [ ] `ai plan` compatibility tested.
+- [ ] `spec create` review/interactive behavior tested.
+- [ ] `ai pr` review/interactive behavior tested.
+- [ ] Existing command tests still pass.

package/specs/quiver-v29-planner-prepare-context-cli-ux/slices/slice-05-progressive-command-adoption/slice.json

@@ -0,0 +1,83 @@
+{
+  "slice_id": "slice-05-progressive-command-adoption",
+  "ticket": "QUIVER-29-05",
+  "type": "feature",
+  "title": "Progressive command adoption",
+  "objective": "Apply the new UX standard to selected high-value commands after `ai prepare-context` proves the pattern.",
+  "description": "Adds focused UX improvements to `ai plan`, `spec create`, and `ai pr` without redesigning the whole CLI.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v29-progressive-command-adoption",
+    "branch_name": "feature/QUIVER-29-05-v29-progressive-command-adoption"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/commands/spec.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/ai/spec-generator.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/spec-create.test.js",
+    "tests/commands/ai-pr.test.js",
+    "tests/commands/ux-flags.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/commands/spec.js",
+    "src/create-quiver/lib/ai/**",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/spec-create.test.js",
+    "tests/commands/ai-pr.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/commands/spec.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/ai/spec-generator.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/spec-create.test.js",
+    "tests/commands/ai-pr.test.js",
+    "tests/commands/ux-flags.test.js",
+    "specs/quiver-v29-planner-prepare-context-cli-ux/**"
+  ],
+  "depends_on": [
+    "slice-03-prepare-context-planner-review-flow",
+    "slice-04-ux-flag-matrix-compatibility"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Touches multiple command integrations and should run after the prepare-context pattern stabilizes.",
+  "must": [
+    "Apply the standard to `ai plan` only where planner semantics are already natural.",
+    "Apply the standard to `spec create` with safe review/interactive guardrails.",
+    "Apply `--interactive` and `--review` to `ai pr` without adding `--with-planner`.",
+    "Keep non-interactive flag equivalents for every prompt.",
+    "Avoid changing command outputs in --json and CI modes."
+  ],
+  "not_included": [
+    "Full UX migration for all commands.",
+    "TUI dashboards.",
+    "Planner behavior for ai pr."
+  ],
+  "acceptance": [
+    "`ai plan` supports documented UX flags without breaking existing planner drafts.",
+    "`spec create` supports documented review/interactive guardrails where safe.",
+    "`ai pr` can review/edit PR body and interactive inputs without planner mode.",
+    "Existing tests for those commands still pass.",
+    "New tests cover unsupported and compatible flag combinations."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-plan.test.js tests/commands/spec-create.test.js tests/commands/ai-pr.test.js tests/commands/ux-flags.test.js"
+  ],
+  "validation_hints": [
+    "Prefer minimal adoption over broad rewrites.",
+    "Keep generated artifacts backward compatible."
+  ],
+  "estimated_hours": 9,
+  "actual_hours": 4,
+  "status": "completed",
+  "completed_at": "2026-05-26"
+}