create-quiver 0.10.0 → 0.12.1

package/specs/quiver-v23-guided-flow-productization/EVIDENCE_REPORT.md

@@ -0,0 +1,80 @@
+# Evidence Report - Quiver v23 Guided Flow Productization
+
+## Status
+
+Spec foundation is created. `slice-00` through `slice-10` are completed.
+
+## Slice Evidence
+
+| Slice | Evidence |
+|-------|----------|
+| slice-00 | Spec foundation files created. All `slice.json` files parse successfully and `git diff --check` passed. |
+| slice-01 | Added `quiver` as a package binary alias, added read-only `flow` command, generated `quiver:flow` script, docs, and command tests. |
+| slice-02 | Expanded `flow` into a status wizard that reports uninitialized, context-needed, criteria approval, technical-plan approval, spec generation, slice execution, blocked slice graph, and PR-ready states. |
+| slice-03 | Added `.quiver/agents/profiles.json`, `ai agent set/list/show`, provider validation, free-form model labels, profile-backed provider defaults, docs, and tests. |
+| slice-04 | Added a packaged planner onboarding template, shared context plan, prepare report selected docs/debt/omissions, index-first generated prompt, and tests. |
+| slice-05 | Added versioned drafts under `.quiver/approvals/<phase>/drafts/`, `ai approve --version`, status history output, and approval blocking against stale versions. |
+| slice-06 | Added `ai review-plan`, review prompt metadata, persisted `.quiver/approvals/plan-review/` artifacts, flow guidance before technical-plan approval, and a spec-generation gate that requires the reviewed technical-plan version to be approved. |
+| slice-07 | Added `npx create-quiver spec create`, generated `quiver:spec:create` scripts, dry-run preview, collision checks, next safe commands, and docs/tests for creating specs from reviewed approved technical plans. |
+| slice-08 | Added `npx create-quiver ai prompt-slice`, generated `quiver:ai:prompt-slice` scripts, minimal SPEC excerpts, required closure brief handling, final report format, docs/templates, and tests for manual executor prompts. |
+| slice-09 | Added `--mode manual` and `--mode delegated` for `ai execute-plan`, dry-run prompt/execute commands, delegated temporary worktrees for parallel-ready waves, sequential fallback for unsafe scopes, one-commit integration, recovery guidance, docs, and tests. |
+| slice-10 | Updated README, README_FOR_AI, CHANGELOG, ROADMAP, BACKLOG, generated docs/templates, smoke coverage, release readiness checklist, final status/evidence, and confirmed no npm publish was performed. |
+
+## Validation Log
+
+- 2026-05-21: `find specs/quiver-v23-guided-flow-productization -name "slice.json" -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `node --test tests/commands/flow.test.js tests/commands/init-profiles.test.js tests/commands/prepare.test.js`
+- 2026-05-21: `node bin/create-quiver.js flow --json`
+- 2026-05-21: `node --test tests/commands/flow.test.js tests/lib/doctor.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `node --test tests/lib/agent-profiles.test.js tests/commands/ai-agent.test.js tests/commands/flow.test.js tests/commands/ai-onboard.test.js tests/commands/ai-plan.test.js tests/commands/ai-execute-slice.test.js tests/commands/ai-execute-plan.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `node --test tests/commands/prepare.test.js tests/commands/ai-onboard.test.js tests/lib/ai-safety.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `node --test tests/lib/approvals.test.js tests/commands/ai-plan.test.js tests/commands/ai-plan-spec-phase.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `node --test tests/commands/ai-review-plan.test.js`
+- 2026-05-21: `node --test tests/commands/doctor.test.js tests/lib/init-docs.test.js tests/lib/init-layout.test.js tests/lib/package-safety.test.js tests/commands/flow.test.js tests/commands/ai-review-plan.test.js tests/commands/ai-plan-spec-phase.test.js tests/commands/ai-plan.test.js`
+- 2026-05-21: `node --test tests/**/*.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `find specs/quiver-v23-guided-flow-productization -name slice.json -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;`
+- 2026-05-21: `npm run smoke:create-quiver`
+- 2026-05-21: `npm run smoke:tiered-pack`
+- 2026-05-21: `npm run smoke:guided-workflow`
+- 2026-05-21: `npm run smoke:create-quiver`
+- 2026-05-21: `npm pack --dry-run` failed because the user npm cache under `~/.npm` contains root-owned files.
+- 2026-05-21: `npm --cache /private/tmp/quiver-npm-cache pack --dry-run`
+- 2026-05-21: `npm run smoke:tiered-pack`
+
+## Release Readiness Checklist
+
+- [x] Root README documents the guided flow as available behavior.
+- [x] Generated docs mention flow status, profiles, onboarding, review-plan, spec create, executor prompts, delegated execution, PR creation, and cleanup.
+- [x] Guided workflow smoke covers flow status, profiles, onboarding, planner iterations, review-plan, spec create, executor prompt dry-run, delegated execution dry-run, PR dry-run, cleanup dry-run, and package safety.
+- [x] Package dry-run succeeded with an isolated npm cache.
+- [x] No npm publish was performed in this slice.
+- 2026-05-21: `node --test tests/lib/ai-execution-plan.test.js tests/commands/ai-execute-plan.test.js tests/commands/ai-execute-slice.test.js`
+- 2026-05-21: `node --test tests/lib/ai-execution-plan.test.js tests/commands/ai-execute-plan.test.js tests/commands/ai-execute-slice.test.js tests/lib/init-docs.test.js tests/lib/init-layout.test.js`
+- 2026-05-21: `node --test tests/**/*.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `find specs/quiver-v23-guided-flow-productization -name slice.json -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;`
+- 2026-05-21: `npm run smoke:create-quiver`
+- 2026-05-21: `npm run smoke:tiered-pack`
+- 2026-05-21: `node --test tests/commands/ai-execute-slice.test.js tests/lib/ai-executor.test.js tests/lib/init-docs.test.js tests/lib/init-layout.test.js`
+- 2026-05-21: `node --test tests/**/*.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `find specs/quiver-v23-guided-flow-productization -name slice.json -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;`
+- 2026-05-21: `npm run smoke:create-quiver`
+- 2026-05-21: `npm run smoke:tiered-pack`
+- 2026-05-21: `node --test tests/commands/spec-create.test.js tests/commands/flow.test.js tests/commands/ai-plan-spec-phase.test.js tests/lib/ai-spec-generator.test.js tests/lib/init-layout.test.js`
+- 2026-05-21: `node --test tests/commands/spec-create.test.js tests/commands/flow.test.js tests/lib/ai-spec-generator.test.js tests/commands/ai-plan-spec-phase.test.js tests/lib/init-docs.test.js tests/lib/init-layout.test.js`
+- 2026-05-21: `node --test tests/**/*.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `find specs/quiver-v23-guided-flow-productization -name slice.json -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;`
+- 2026-05-21: `npm run smoke:create-quiver`
+- 2026-05-21: `npm run smoke:tiered-pack`
+
+## Notes
+
+This report must be updated by each slice executor with commands run, results, risks, and follow-up work.

package/specs/quiver-v23-guided-flow-productization/EXECUTION_PLAN.md

@@ -0,0 +1,80 @@
+# Execution Plan - Quiver v23 Guided Flow Productization
+
+## Rule
+
+`slice-00` is mandatory and must be committed first. It establishes the spec foundation in the repo.
+
+## Recommended Wave Plan
+
+This is the safe default plan. It favors reliable integration over speed because several slices will touch command routing, docs, and shared AI workflow state.
+
+| Wave | Mode | Slices | Why |
+|------|------|--------|-----|
+| 0 | Sequential | `slice-00-spec-foundation` | Publishes the spec foundation, handoffs, execution plan, and PR body. |
+| 1 | Sequential | `slice-01-short-command-and-flow-entrypoint` | Establishes the command surface before adding higher-level flow behavior. |
+| 2 | Sequential | `slice-02-flow-status-wizard` | Adds the next-step guide that later slices can extend. |
+| 3 | Sequential | `slice-03-agent-profiles` | Adds planner/executor/reviewer profile state before using those profiles in prompts. |
+| 4 | Sequential | `slice-04-context-preparation-onboarding` | Productizes onboarding prompts after profiles and flow status exist. |
+| 5 | Sequential | `slice-05-planner-iteration-history` | Adds versioned drafts and approvals before plan review and spec creation. |
+| 6 | Sequential | `slice-06-production-plan-review` | Adds the production-readiness review gate before spec generation. |
+| 7 | Sequential | `slice-07-spec-create-experience` | Builds on approved and reviewed plans to create specs predictably. |
+| 8 | Sequential | `slice-08-executor-prompt-generation` | Generates minimal manual executor prompts after spec/slice shape is stable. |
+| 9 | Sequential | `slice-09-delegated-slice-execution` | Adds the highest-risk delegated execution behavior after all prerequisites exist. |
+| 10 | Sequential | `slice-10-docs-smokes-release-readiness` | Final docs and smokes must run last. |
+
+## Parallelization Assessment
+
+Default recommendation: execute sequentially.
+
+Optional parallel work is possible only after `slice-03` if file ownership is split:
+
+| Optional Wave | Mode | Slices | Condition |
+|---------------|------|--------|-----------|
+| 4A | Parallel | `slice-04-context-preparation-onboarding` + `slice-05-planner-iteration-history` | Only if command routing changes are isolated and shared state files are not edited by both slices. |
+| 8A | Parallel | `slice-08-executor-prompt-generation` + docs draft work for `slice-10` | Only if docs work does not depend on final delegated behavior. |
+
+If file scopes overlap or are unknown, fall back to sequential execution.
+
+## Dependency Graph
+
+```mermaid
+flowchart TD
+    S00[slice-00 spec foundation] --> S01[slice-01 short command and flow entrypoint]
+    S01 --> S02[slice-02 flow status wizard]
+    S02 --> S03[slice-03 agent profiles]
+    S03 --> S04[slice-04 context preparation onboarding]
+    S04 --> S05[slice-05 planner iteration history]
+    S05 --> S06[slice-06 production plan review]
+    S06 --> S07[slice-07 spec create experience]
+    S07 --> S08[slice-08 executor prompt generation]
+    S08 --> S09[slice-09 delegated slice execution]
+    S09 --> S10[slice-10 docs smokes release readiness]
+```
+
+## Suggested Commit Order
+
+1. `docs(spec): add guided flow productization spec`
+2. `feat(cli): add quiver flow entrypoint`
+3. `feat(flow): show next safe workflow step`
+4. `feat(ai): persist agent profiles`
+5. `feat(ai): productize context onboarding`
+6. `feat(ai): version planner drafts and approvals`
+7. `feat(ai): review technical plans for production readiness`
+8. `feat(spec): create specs from reviewed approved plans`
+9. `feat(ai): generate minimal executor prompts`
+10. `feat(ai): delegate slice execution safely`
+11. `docs(ai): document guided flow and add smokes`
+
+## Executor Assignment
+
+- Keep `slice-00`, `slice-01`, `slice-02`, `slice-06`, `slice-09`, and `slice-10` with a stronger planner/reviewer because they affect user flow, safety, or integration.
+- `slice-03`, `slice-04`, `slice-05`, `slice-07`, and `slice-08` can be executed by cheaper code-focused agents if their file scopes are clear.
+- Do not delegate parallel slices unless write sets are disjoint.
+
+## Integration Notes
+
+- Do not start implementation slices before `slice-00` is committed.
+- Keep provider calls mocked in automated tests.
+- Keep real provider CLI checks manual or dry-run only.
+- Preserve existing `npx create-quiver` commands.
+- Treat `quiver` as an alias unless a deliberate package decision changes that.

package/specs/quiver-v23-guided-flow-productization/SPEC.md

@@ -0,0 +1,203 @@
+# Quiver v23 - Guided Flow Productization
+
+**Date:** 2026-05-21
+**Status:** Completed
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Quiver already has the core AI workflow pieces: project preparation, analysis, planner phases, approvals, spec generation, slice execution, execution waves, PR creation, and worktree cleanup.
+
+The remaining friction is product experience. Users still need to remember the sequence, paste long prompts, choose planner/executor agents manually, know when to approve or iterate, and decide how to delegate slices safely.
+
+The desired product experience is a guided flow:
+
+1. Run one Quiver command.
+2. Prepare project context for AI onboarding.
+3. Configure planner and executor agents.
+4. Let the planner onboard from generated docs.
+5. Generate, revise, and approve acceptance criteria.
+6. Generate, revise, production-review, and approve the technical plan.
+7. Generate spec, slices, handoffs, execution plan, and `pr.md`.
+8. Execute `slice-00` first.
+9. Execute later slices sequentially or in parallel when safe.
+10. Create one commit per slice.
+11. Open one PR per spec.
+12. Close the spec worktree after merge and pull the main checkout.
+
+## Objective
+
+Turn Quiver from a set of capable commands into a guided AI-first product flow that reduces prompt pasting, saves tokens, preserves human approvals, and makes the next safe step obvious.
+
+## Core Decisions
+
+- `README_FOR_AI.md` remains the source of truth for Quiver workflow guidance in this repo.
+- The canonical package remains `create-quiver`; this spec may introduce a `quiver` binary alias only if it forwards to the same CLI behavior.
+- `.quiver/` stores local workflow state, drafts, approvals, agent profiles, and runs.
+- `docs/` stores visible project context.
+- `specs/` stores durable spec, slice, handoff, execution plan, and PR artifacts.
+- Planner agents use broad context and do not modify product code.
+- Executor agents use slice-bounded context and may modify product code only inside the approved slice scope.
+- Human approval remains mandatory for acceptance criteria, technical plans, and PR merge.
+- `slice-00` is mandatory for every spec and must land before implementation slices.
+- One spec maps to one worktree and one PR.
+- One slice maps to one commit.
+
+## Scope
+
+### Included
+
+- Add a short `quiver` command experience or a documented alias that does not contradict `npx create-quiver`.
+- Add a guided flow/status command that tells the user the current stage and next safe command.
+- Add planner, executor, reviewer, and optional researcher agent profiles.
+- Add setup and validation for provider CLI choices without silently installing tools.
+- Add a context-preparation command focused on token-efficient AI onboarding.
+- Convert the user's long onboarding, planning, review, executor, delegation, and PR prompts into maintained Quiver prompt templates.
+- Persist planner drafts, revised versions, approved artifacts, and review results.
+- Add a production-readiness plan review phase before spec generation.
+- Improve spec creation UX so approved inputs generate spec artifacts predictably.
+- Generate minimal executor prompts for manual slice assignment.
+- Add a delegated slice execution mode that uses safe waves, cheap executor profiles, isolated worktrees where needed, and one commit per slice.
+- Add final PR and cleanup guidance around the generated `pr.md`, `gh`, SSH aliases, and spec worktrees.
+- Add docs and smokes that demonstrate the full guided flow.
+
+### Excluded
+
+- Fully autonomous PR merge.
+- Silent installation of `gh`, provider CLIs, or SSH keys.
+- Direct provider API integrations.
+- Guaranteeing provider-specific sub-agent spawning when the local CLI does not support it.
+- Running real paid provider calls in CI.
+- Replacing human approval for criteria, plans, or PR review.
+
+## Acceptance Criteria
+
+1. Given a user installs or runs Quiver, when they request the guided flow, then Quiver exposes a clear short command path or documented alias without contradicting `npx create-quiver`.
+2. Given a project has Quiver state, when the flow status command runs, then it reports the current stage, blockers, and next safe command.
+3. Given a project is not initialized, when the flow status command runs, then it recommends initialization instead of failing with low-level errors.
+4. Given the user wants token-efficient onboarding, when context preparation runs, then Quiver refreshes project docs, reports assumptions and risks, and excludes secrets, generated files, dependency folders, and local AI state.
+5. Given the user has preferred planner and executor models, when agent profiles are configured, then Quiver persists planner, executor, reviewer, and optional researcher choices under `.quiver/`.
+6. Given a configured provider CLI is missing or unauthenticated, when diagnostics run, then Quiver prints OS-aware guidance and does not modify credentials silently.
+7. Given a planner onboarding command runs in dry-run mode, then Quiver prints provider, role, context pack, prompt source, and token-relevant metadata without calling the provider.
+8. Given requirements input exists, when acceptance criteria generation runs, then Quiver stores the output as a draft and does not advance until approved.
+9. Given the user revises criteria multiple times, when drafts are listed, then Quiver shows the available versions and which one is approved.
+10. Given acceptance criteria are approved, when technical planning starts, then Quiver uses the approved criteria by default.
+11. Given a technical plan is generated, when production review runs, then Quiver reports fragile assumptions, ambiguous criteria, missing cases, and recommended fixes without changing product code.
+12. Given a reviewed technical plan is not approved, when spec generation is requested, then Quiver blocks and explains the missing approval.
+13. Given a reviewed plan is approved, when spec creation runs, then Quiver creates `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, `EXECUTION_PLAN.md`, `pr.md`, mandatory `slice-00`, and per-slice handoffs.
+14. Given a spec has generated slices, when execution planning runs, then `slice-00` is first and later slices are blocked until `slice-00` is committed.
+15. Given a slice is assigned manually, when executor prompt generation runs, then Quiver outputs only the slice objective, minimal context, allowed files, constraints, acceptance criteria, validation commands, and final report format.
+16. Given a delegated execution plan is requested, when slices have overlapping or unknown file scopes, then Quiver falls back to sequential execution.
+17. Given delegated execution runs later slices in parallel, when it writes code, then each executor works in an isolated safe workspace or otherwise cannot overlap writes.
+18. Given a slice passes provider, scope, and validation checks with commit enabled, then Quiver creates exactly one commit for that slice.
+19. Given all required slices are complete, when PR creation runs, then Quiver validates `gh`, auth, branch, remote, clean state, SSH alias, identity file, and generated `pr.md`.
+20. Given the PR is merged and the spec worktree is clean, when cleanup runs, then Quiver removes the spec worktree and pulls the main checkout.
+21. Given docs and generated templates are updated, when smokes run, then the full guided flow is covered without real paid provider calls.
+
+## Approved Technical Plan
+
+### Objective
+
+Add a productized flow layer on top of the v22 command foundation.
+
+### Approach
+
+Prefer thin orchestration wrappers over replacing proven commands. The new flow layer should call or reuse the existing command libraries for analysis, provider execution, approvals, spec generation, execution plans, PR creation, and cleanup.
+
+Recommended areas:
+
+```text
+bin/quiver.js
+src/create-quiver/commands/flow.js
+src/create-quiver/commands/agent.js
+src/create-quiver/lib/flow-state.js
+src/create-quiver/lib/agent-profiles.js
+src/create-quiver/lib/prompt-templates.js
+src/create-quiver/lib/planner-history.js
+src/create-quiver/lib/plan-review.js
+src/create-quiver/lib/executor-prompts.js
+src/create-quiver/lib/delegation.js
+```
+
+Exact file names may change if existing modules provide a better fit.
+
+### Product Flow
+
+The desired command experience should be understandable without reading long prompts:
+
+```bash
+quiver init --name "Project Name"
+quiver flow
+quiver prepare
+quiver ai agent set planner --provider claude --model opus
+quiver ai agent set executor --provider codex --model gpt-5.4-mini
+quiver ai onboard
+quiver ai criteria --input requirements.md
+quiver ai approve criteria
+quiver ai plan
+quiver ai review-plan
+quiver ai approve plan
+quiver spec create
+quiver spec start
+quiver slices plan
+quiver slices run --mode manual
+quiver slices run --mode delegated
+quiver pr create
+quiver spec close
+```
+
+The existing `npx create-quiver ...` commands must continue working.
+
+### Prompt Strategy
+
+- Keep README snippets short.
+- Store detailed prompt contracts as templates in the package.
+- Generate task-specific prompts from state and slice artifacts.
+- Do not send full specs to executor agents unless the slice explicitly needs it.
+- Record assumptions, risks, and files read in outputs where relevant.
+
+### Safety Rules
+
+- Dry-run first for provider and PR operations.
+- No product code changes before approved slice execution.
+- No spec generation before approved and reviewed plan.
+- No parallel execution when scopes conflict or are unknown.
+- No commit before validation.
+- No cleanup before merge confirmation.
+- No silent credential, SSH, or tool installation.
+
+## Slicing Strategy
+
+`slice-00` lands first and only publishes this spec foundation. Later slices are ordered from user-facing command clarity to higher-risk delegated execution. Delegated parallel execution is intentionally late because it depends on command routing, agent profiles, prompt generation, slice status, and scope safety.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|-------|-------|--------|--------------|
+| slice-00 | Spec foundation and guided flow planning artifacts | Completed | none |
+| slice-01 | Short command and guided flow entrypoint | Completed | slice-00 |
+| slice-02 | Flow status and next-step wizard | Completed | slice-01 |
+| slice-03 | Agent profiles for planner, executor, reviewer, and researcher | Completed | slice-02 |
+| slice-04 | Context preparation and onboarding prompt productization | Completed | slice-03 |
+| slice-05 | Planner iteration history for criteria and plans | Completed | slice-04 |
+| slice-06 | Production-readiness plan review phase | Completed | slice-05 |
+| slice-07 | Spec creation experience from approved plans | Completed | slice-06 |
+| slice-08 | Executor prompt generation for manual slice assignment | Completed | slice-07 |
+| slice-09 | Delegated slice execution with safe workspaces | Completed | slice-08 |
+| slice-10 | Final docs, smokes, and release readiness | Completed | slice-09 |
+
+## Risks
+
+- A short `quiver` command can create package naming confusion if not documented carefully.
+- Agent model names are provider-specific and may change over time.
+- Delegated parallel execution can corrupt work if isolation and conflict checks are weak.
+- Storing too much prompt history can add noise and token cost.
+- Provider CLIs may not support true sub-agent delegation; manual prompt generation must remain a first-class fallback.
+- Over-automation can hide important human approval points.
+
+## Open Questions
+
+- Should reviewed technical plans require a separate approval artifact, or can the approved plan include the review result?
+- Should delegated execution create temporary worktrees per slice by default, even for sequential slices?
+- Should final PR creation be owned by the planner profile, the default CLI, or a dedicated reviewer profile?

package/specs/quiver-v23-guided-flow-productization/STATUS.md

@@ -0,0 +1,39 @@
+# Quiver v23 - Guided Flow Productization Status
+
+**Status:** Completed
+**Created:** 2026-05-21
+
+## Summary
+
+This spec productizes the user's current prompt-driven workflow into first-class Quiver commands and templates. The goal is to reduce prompt pasting, preserve WDD/SDD approvals, guide the user through the next safe step, and support planner/executor agent roles with lower token cost.
+
+## Current State
+
+- Requirements and product direction: approved in conversation.
+- Spec and slice handoffs: created in this documentation pass.
+- `slice-00`: completed.
+- `slice-01`: completed. Added the `quiver` binary alias, read-only `flow` command, docs, generated script, and tests.
+- `slice-02`: completed. Expanded `flow` into a read-only wizard that reads context docs, approvals, specs, slices, and blockers.
+- `slice-03`: completed. Added reusable planner, executor, reviewer, and researcher agent profiles under `.quiver/agents/profiles.json`.
+- `slice-04`: completed. Added packaged index-first onboarding prompt generation and context preparation reporting.
+- `slice-05`: completed. Added versioned planner draft history and explicit approval by draft version.
+- `slice-06`: completed. Added `ai review-plan`, persisted plan review state, flow guidance, and spec-generation gating for reviewed and approved technical plans.
+- `slice-07`: completed. Added explicit `spec create` command, generated `quiver:spec:create` script, next-command output, docs, and tests.
+- `slice-08`: completed. Added `ai prompt-slice` / `executor-prompt` to print minimal manual executor prompts from slice artifacts without calling providers.
+- `slice-09`: completed. Added manual/delegated execution modes, prompt commands in dry-runs, delegated temporary worktrees for parallel-ready waves, and commit integration back into the active checkout.
+- `slice-10`: completed. Updated root docs, generated docs/templates, roadmap/backlog/changelog, smoke coverage, release readiness evidence, and no-publish release checklist.
+
+## Execution Rules
+
+- `slice-00` must be executed and committed first.
+- Every later slice depends on `slice-00`.
+- One slice equals one commit.
+- One spec equals one worktree and one PR.
+- Planner phases cannot modify product code.
+- Executor phases can modify product code only inside approved slice scope.
+- Parallel slices may run only when dependencies and file scopes are safe.
+
+## Open Items
+
+- Decide whether future UX should add a dedicated `ai approve --phase plan-review` command, or keep the current model where the reviewed technical-plan draft is approved by version.
+- Validate provider-specific model argument handling for Codex, Claude, and Gemini before model labels are used as invocation arguments.

package/specs/quiver-v23-guided-flow-productization/pr.md

@@ -0,0 +1,119 @@
+## Title
+
+Quiver v23 - Guided flow productization
+
+## Summary
+
+Productizes the current prompt-driven Quiver workflow into a guided AI-first flow. The goal is to reduce long prompt pasting, guide users through the next safe step, persist planner/executor profiles, version criteria and plan iterations, generate minimal executor prompts, and support safe delegated slice execution.
+
+## Scope
+
+- Short `quiver` command path or documented alias
+- Guided flow/status command
+- Planner, executor, reviewer, and researcher profiles
+- Token-efficient context preparation and onboarding prompt templates
+- Versioned criteria and technical-plan drafts
+- Production-readiness plan review
+- Spec creation from reviewed approved plans
+- Minimal executor prompt generation
+- Delegated slice execution with safe workspaces
+- PR and cleanup flow polish
+- Docs, templates, and smoke coverage
+
+## Files
+
+- `specs/quiver-v23-guided-flow-productization/SPEC.md`
+- `specs/quiver-v23-guided-flow-productization/STATUS.md`
+- `specs/quiver-v23-guided-flow-productization/EVIDENCE_REPORT.md`
+- `specs/quiver-v23-guided-flow-productization/EXECUTION_PLAN.md`
+- `specs/quiver-v23-guided-flow-productization/pr.md`
+- `specs/quiver-v23-guided-flow-productization/slices/**`
+
+Future implementation slices are expected to touch CLI routing, AI commands, provider/profile helpers, prompt templates, approval state, flow status, delegated execution, docs, tests, and smoke scripts as declared by each slice.
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js compatible with the current repo setup. The CI line uses Node 22.
+- npm available locally.
+- Git worktree on `feature/QUIVER-22-guided-ai-workflow`.
+- No real paid provider calls are required for the automated checks.
+
+### Worktree Access
+
+Run from the repo root:
+
+```bash
+git status --short
+git branch --show-current
+```
+
+Expected:
+
+- Worktree is clean before PR creation.
+- Current branch is `feature/QUIVER-22-guided-ai-workflow`.
+
+### Run the Project
+
+Quiver is a CLI package. Use the local binary for inspection:
+
+```bash
+node bin/create-quiver.js --help
+node bin/create-quiver.js flow --json
+```
+
+### Use Cases
+
+- A user asks Quiver what step comes next.
+- A user configures planner and executor agent profiles.
+- A planner onboards from generated context without reading unnecessary docs.
+- A planner generates and revises acceptance criteria.
+- A reviewer checks the technical plan for production readiness.
+- A reviewed approved plan creates spec/slices/handoffs/execution plan/PR body.
+- An executor receives a minimal slice prompt.
+- Quiver delegates or prints safe execution commands for slices.
+- Quiver opens the PR from `pr.md` after checks pass.
+- Quiver closes the spec worktree after merge.
+
+### Technical Verification
+
+Documentation-only `slice-00`:
+
+```bash
+git diff --check
+find specs/quiver-v23-guided-flow-productization -name "slice.json" -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;
+```
+
+Full validation:
+
+```bash
+node --test tests/**/*.test.js
+npm run smoke:create-quiver
+npm run smoke:guided-workflow
+npm run smoke:tiered-pack
+npm run package:quiver
+npm --cache /private/tmp/quiver-npm-cache pack --dry-run
+```
+
+## Evidence
+
+- `node --test tests/**/*.test.js` passed with 223 tests.
+- `git diff --check` passed.
+- All `slice.json` files under `specs/quiver-v23-guided-flow-productization/` parse successfully.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:guided-workflow` passed.
+- `npm run smoke:tiered-pack` passed.
+- `npm --cache /private/tmp/quiver-npm-cache pack --dry-run` passed.
+- Plain `npm pack --dry-run` was blocked by root-owned files in the user's global npm cache; the package was validated with an isolated temporary cache.
+
+## Rollback
+
+Revert the smallest failing slice commit. Since the spec requires one slice per commit, rollback should target the affected slice commit rather than the full PR when possible.
+
+## Risks / Notes
+
+- This spec does not automate PR merge.
+- Real provider CLIs are not called in CI.
+- `quiver` command naming must not confuse package installation.
+- Delegated parallel execution must remain conservative until isolation is proven.

package/specs/quiver-v23-guided-flow-productization/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE BRIEF - slice-00: Spec foundation
+
+## Resumen de lo realizado
+
+- Se creo la base documental de Quiver v23.
+- Se agregaron spec, status, evidencia, plan de ejecucion, cuerpo de PR y handoffs por slice.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Spec folder creado.
+- [x] `slice-00` creado.
+- [x] Todos los slices tienen `slice.json`, `EXECUTION_BRIEF.md` y `CLOSURE_BRIEF.md`.
+- [x] JSON validado.
+- [x] No se modifico codigo de producto.
+
+## Cambios relevantes
+
+- Nueva carpeta `specs/quiver-v23-guided-flow-productization/`.
+
+## Pendientes
+
+- Implementar `slice-01` en adelante.
+
+## Riesgos remanentes
+
+- Las decisiones sobre el binario corto `quiver` y perfiles de modelo se resolveran en slices posteriores.
+
+## Recomendaciones futuras
+
+- Ejecutar los slices en el orden recomendado por `EXECUTION_PLAN.md`.

package/specs/quiver-v23-guided-flow-productization/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,61 @@
+# EXECUTION BRIEF - slice-00: Spec foundation
+
+**Spec:** quiver-v23-guided-flow-productization
+**Slice:** slice-00-spec-foundation
+**Tipo:** docs
+
+## Contexto
+
+Esta slice sube al repo la base documental del flujo guiado productizado. Es obligatoria y debe ejecutarse antes de cualquier slice de implementacion.
+
+## Objetivo
+
+Crear y validar la estructura completa de spec, slices, handoffs, plan de ejecucion y cuerpo de PR para Quiver v23.
+
+## Alcance
+
+- Crear `SPEC.md`.
+- Crear `STATUS.md`.
+- Crear `EVIDENCE_REPORT.md`.
+- Crear `EXECUTION_PLAN.md`.
+- Crear `pr.md`.
+- Crear `slice.json`, `EXECUTION_BRIEF.md` y `CLOSURE_BRIEF.md` para cada slice.
+
+## Criterios de aceptacion
+
+- La carpeta `specs/quiver-v23-guided-flow-productization/` existe.
+- `slice-00` existe y precede al resto.
+- Cada slice tiene `slice.json`, `EXECUTION_BRIEF.md` y `CLOSURE_BRIEF.md`.
+- Todos los JSON parsean correctamente.
+- No se modifica codigo de producto.
+
+## Plan tecnico resumido
+
+Crear artefactos documentales siguiendo el patron real del repo bajo `specs/`. Mantener `slice-00` como base documental y declarar dependencias para las slices posteriores.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `README_FOR_AI.md`.
+2. Crear estructura `specs/quiver-v23-guided-flow-productization/`.
+3. Agregar archivos top-level de spec.
+4. Agregar cada slice y handoff.
+5. Validar JSON y whitespace.
+6. Preparar commit unico de slice-00.
+
+## Restricciones
+
+- No tocar codigo de producto.
+- No resolver implementacion en esta slice.
+- No abrir PR todavia.
+
+## Riesgos
+
+- Diseñar una spec demasiado amplia sin dependencias claras.
+- Dejar handoffs incompletos para agentes executor.
+
+## Checklist de finalizacion
+
+- [ ] `git diff --check` pasa.
+- [ ] Todos los `slice.json` parsean.
+- [ ] No hay cambios fuera de `specs/quiver-v23-guided-flow-productization/`.
+- [ ] El commit representa solo slice-00.