create-quiver 0.9.1 → 0.12.0

package/specs/quiver-v22-guided-ai-workflow/slices/slice-09-post-merge-cleanup-release-safety/slice.json

@@ -0,0 +1,59 @@
+{
+  "slice_id": "slice-09-post-merge-cleanup-release-safety",
+  "ticket": "QUIVER-22-09",
+  "type": "feature",
+  "title": "Post-merge cleanup and release safety",
+  "objective": "Safely close merged spec worktrees and prevent local AI/tool state from entering npm packages.",
+  "description": "Add post-merge lifecycle checks and release/package safety guards for secrets, env files, npm credentials, and local AI tool directories.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "post-merge-cleanup-release-safety",
+    "branch_name": "feature/QUIVER-22-09-post-merge-cleanup-release-safety"
+  },
+  "files": [
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/lifecycle.js",
+    "src/create-quiver/lib/git.js",
+    "src/create-quiver/lib/spec-worktrees.js",
+    "src/create-quiver/lib/package-safety.js",
+    "scripts/release-quiver.sh",
+    ".npmignore",
+    "tests/commands/spec-close.test.js",
+    "tests/lib/package-safety.test.js"
+  ],
+  "depends_on": [
+    "slice-07-execution-waves-delegation",
+    "slice-08-pr-create-gh-ssh"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Cleanup and release safety must integrate final workflow state and PR behavior.",
+  "must": [
+    "Refuse normal cleanup before PR merge is confirmed.",
+    "Refuse cleanup when the worktree is dirty unless explicit discard behavior is used.",
+    "Remove the spec worktree after safe confirmation.",
+    "Pull merged changes into the main local checkout.",
+    "Fail package/release safety if local settings, env files, npm credentials, or AI tool local state would enter the tarball.",
+    "Keep destructive operations explicit and recoverable."
+  ],
+  "not_included": [
+    "Merging PRs.",
+    "Deleting remote branches without explicit existing workflow support.",
+    "Publishing a new npm version."
+  ],
+  "acceptance": [
+    "Unmerged PR blocks normal spec cleanup.",
+    "Dirty worktree blocks normal spec cleanup.",
+    "Merged clean spec can be closed and main checkout can be pulled.",
+    "Release/package safety fails when unsafe local files would be packaged.",
+    "Release/package safety passes when unsafe paths are ignored or absent."
+  ],
+  "tests": [
+    "node --test tests/commands/spec-close.test.js tests/lib/package-safety.test.js",
+    "npm pack --dry-run",
+    "git diff --check"
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v22-guided-ai-workflow/slices/slice-10-docs-smokes-release-readiness/CLOSURE_BRIEF.md

@@ -0,0 +1,34 @@
+# CLOSURE BRIEF - slice-10: Final docs, smokes, and release readiness
+
+## Resumen de lo realizado
+
+- Se actualizaron README, README_FOR_AI, CHANGELOG, ROADMAP, BACKLOG y templates generados para presentar el guided AI workflow como disponible.
+- Se alinearon los snippets de onboarding con aprobaciones persistidas, `spec start`, ejecución por olas, PR con `pr.md` y cierre de worktree.
+- Se agregó `smoke:guided-workflow` y se reforzaron los smokes existentes para el contrato real post-`analyze`, scripts nuevos y `slice-00` obligatorio.
+- `docs/AI_CONTEXT.md` refrescado por `analyze` conserva front matter para mantener el contrato token-efficient.
+- Se actualizaron STATUS, EVIDENCE_REPORT y el estado del slice.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Docs finales listas.
+- [x] Smokes listas.
+- [x] STATUS/EVIDENCE actualizados.
+- [x] No se publico npm.
+
+## Cambios relevantes
+
+- Root docs y templates muestran `prepare`, `ai approve`, `ai execute-plan`, `ai pr --input`, `spec start/status/close` y commit opt-in.
+- Scripts de smoke cubren flujo guiado, creación/migración, package safety y fixtures con `slice-00`.
+- El package dry-run pasó usando cache temporal por permisos rotos en la cache global de npm.
+
+## Pendientes
+
+- Publicar una nueva version npm queda fuera de este slice y debe hacerse con el flujo de release.
+
+## Riesgos remanentes
+
+- La cache global `~/.npm` tiene archivos root-owned; `npm pack --dry-run` requiere cache temporal o corregir permisos localmente.
+
+## Recomendaciones futuras
+
+- Ejecutar `npm run release:quiver` o `bash scripts/release-quiver.sh ...` solo despues de revisar este PR y decidir el bump.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-10-docs-smokes-release-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,58 @@
+# EXECUTION BRIEF - slice-10: Final docs, smokes, and release readiness
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-10-docs-smokes-release-readiness
+**Tipo:** docs-test
+
+## Contexto
+
+Cuando todas las piezas existen, hay que actualizar la documentacion publica, templates generados, smokes y evidencia.
+
+## Objetivo
+
+Cerrar la feature con docs completas, pruebas y readiness de release sin publicar.
+
+## Alcance
+
+- README y guia IA.
+- Templates/docs generados.
+- Smoke tests.
+- STATUS/EVIDENCE_REPORT.
+- Checklist de release.
+
+## Criterios de aceptacion
+
+- Docs muestran el flujo como disponible.
+- Smokes cubren happy path y fallas principales.
+- Evidencia actualizada.
+- No se publica npm.
+
+## Plan tecnico resumido
+
+Actualizar docs y templates despues de terminar comportamiento, luego ejecutar suite amplia y registrar evidencia.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar todos los comandos implementados.
+2. Actualizar README y README_FOR_AI.
+3. Actualizar generated docs/templates.
+4. Agregar smokes.
+5. Ejecutar tests.
+6. Actualizar STATUS/EVIDENCE_REPORT.
+
+## Restricciones
+
+- No publicar npm.
+- No abrir PR si no se pidio.
+
+## Riesgos
+
+- Documentar comandos con nombres distintos a los implementados.
+- Smokes demasiado dependientes de herramientas reales.
+
+## Checklist de finalizacion
+
+- [ ] Docs finales actualizadas.
+- [ ] Templates actualizados.
+- [ ] Smokes agregados.
+- [ ] Evidencia final registrada.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-10-docs-smokes-release-readiness/slice.json

@@ -0,0 +1,60 @@
+{
+  "slice_id": "slice-10-docs-smokes-release-readiness",
+  "ticket": "QUIVER-22-10",
+  "type": "docs-test",
+  "title": "Final docs, smokes, and release readiness",
+  "objective": "Finish the guided workflow with updated user docs, generated templates, smoke coverage, and release readiness evidence.",
+  "description": "Update public docs and generated project templates, add end-to-end smoke coverage, and confirm the feature is ready for release without publishing.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "guided-workflow-release-readiness",
+    "branch_name": "feature/QUIVER-22-10-guided-workflow-release-readiness"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "CHANGELOG.md",
+    "src/create-quiver/lib/init-docs.js",
+    "src/create-quiver/lib/init-layout.js",
+    "tests/commands/*.test.js",
+    "scripts/ci/*.sh",
+    "specs/quiver-v22-guided-ai-workflow/STATUS.md",
+    "specs/quiver-v22-guided-ai-workflow/EVIDENCE_REPORT.md"
+  ],
+  "depends_on": [
+    "slice-09-post-merge-cleanup-release-safety"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final docs and smokes must run after all behavior slices are complete.",
+  "must": [
+    "Document the finished guided workflow in root docs.",
+    "Update generated project docs/templates where users see commands.",
+    "Add smoke coverage for the happy path and major failure paths.",
+    "Update STATUS and EVIDENCE_REPORT.",
+    "Run full relevant test suite.",
+    "Do not publish npm in this slice."
+  ],
+  "not_included": [
+    "Changing feature behavior after acceptance unless a blocking bug is found.",
+    "Publishing a release.",
+    "Merging PR."
+  ],
+  "acceptance": [
+    "README shows the guided AI workflow as available behavior.",
+    "Generated docs mention prepare, approvals, executor commits, PR creation, and cleanup.",
+    "Smoke tests cover dry-run preparation, approvals, execution waves, PR dry-run, cleanup dry-run, and package safety.",
+    "STATUS and EVIDENCE_REPORT reflect completed slices.",
+    "Release checklist is ready but no npm publish is performed."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "npm run smoke:tiered-pack",
+    "npm pack --dry-run",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "blocked_reason": null
+}

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.