create-quiver 0.10.0 → 0.12.0

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.

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

@@ -0,0 +1,51 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-23-00",
+  "type": "docs",
+  "title": "Spec foundation and guided flow planning artifacts",
+  "objective": "Create the complete documentation foundation for the guided flow productization spec.",
+  "description": "Publish the spec, status, evidence report, execution plan, PR body, slice definitions, and handoffs before product implementation starts.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "guided-flow-productization-spec-foundation",
+    "branch_name": "feature/QUIVER-23-00-guided-flow-productization-spec-foundation"
+  },
+  "files": [
+    "specs/quiver-v23-guided-flow-productization/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "slice-00 must land before every other slice.",
+  "must": [
+    "Create SPEC.md.",
+    "Create STATUS.md.",
+    "Create EVIDENCE_REPORT.md.",
+    "Create EXECUTION_PLAN.md.",
+    "Create pr.md.",
+    "Create slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md for every slice.",
+    "Avoid product code changes."
+  ],
+  "not_included": [
+    "Implementing commands.",
+    "Changing package behavior.",
+    "Running AI providers.",
+    "Opening a PR."
+  ],
+  "acceptance": [
+    "Spec folder exists under specs/quiver-v23-guided-flow-productization.",
+    "Mandatory slice-00 exists.",
+    "Every slice has slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Every slice.json parses successfully.",
+    "No product code is modified."
+  ],
+  "tests": [
+    "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'))\" {} \\;"
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-21T00:00:00-0300"
+}

package/specs/quiver-v23-guided-flow-productization/slices/slice-01-short-command-and-flow-entrypoint/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE BRIEF - slice-01: Short command and flow entrypoint
+
+## Resumen de lo realizado
+
+Se agrego la superficie inicial del flujo guiado: el paquete publica `quiver` como alias del mismo binario `create-quiver`, el CLI acepta `flow`, y el comando imprime el estado inicial y el proximo comando seguro sin escribir archivos ni llamar proveedores.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Compatibilidad `create-quiver`.
+- [x] Decision `quiver` documentada.
+- [x] Entry point seguro.
+- [x] Tests pasan.
+
+## Cambios relevantes
+
+- `package.json` y `package-lock.json`: alias binario `quiver` y script `quiver:flow`.
+- `src/create-quiver/commands/flow.js`: comando read-only con salida texto y JSON.
+- `src/create-quiver/index.js`: routing, usage y export del comando `flow`.
+- `src/create-quiver/lib/init-layout.js` y `package.template.json`: script generado `quiver:flow`.
+- `README.md`, `README_FOR_AI.md` y `docs/COMMANDS.md.template`: decision de alias y uso de `flow`.
+- `tests/commands/flow.test.js`: cobertura del alias, script generado, read-only behavior y JSON.
+
+## Pendientes
+
+Ninguno para este slice.
+
+## Riesgos remanentes
+
+El alias `quiver` es un shortcut local/publicado por el paquete; el bootstrap remoto sigue siendo `npx create-quiver`, porque `npx quiver` podria resolver otro paquete si no existe una instalacion local.
+
+## Recomendaciones futuras
+
+Extender `flow` en `slice-02` para mostrar estado mas completo, blockers y wizard de siguiente paso.

package/specs/quiver-v23-guided-flow-productization/slices/slice-01-short-command-and-flow-entrypoint/EXECUTION_BRIEF.md

@@ -0,0 +1,35 @@
+# EXECUTION BRIEF - slice-01: Short command and flow entrypoint
+
+## Contexto
+
+Quiver actualmente se ejecuta como `npx create-quiver`. El objetivo de producto es que el usuario pueda pensar en `quiver` como la experiencia principal sin romper compatibilidad.
+
+## Objetivo
+
+Crear la superficie inicial de comando corto y flujo guiado.
+
+## Alcance
+
+- Revisar `package.json` y `bin/`.
+- Agregar o documentar el alias `quiver`.
+- Agregar entrypoint inicial de `flow`.
+- Actualizar docs y tests.
+
+## Criterios de aceptacion
+
+- `create-quiver` sigue funcionando.
+- La decision sobre `quiver` queda documentada.
+- El nuevo entrypoint no llama proveedores ni escribe estado inesperado.
+- Tests y `git diff --check` pasan.
+
+## Restricciones
+
+- No implementar perfiles de agentes.
+- No introducir breaking changes.
+
+## Checklist de finalizacion
+
+- [ ] Comando probado.
+- [ ] Docs actualizadas.
+- [ ] Tests actualizados.
+- [ ] Evidencia registrada.

package/specs/quiver-v23-guided-flow-productization/slices/slice-01-short-command-and-flow-entrypoint/slice.json

@@ -0,0 +1,56 @@
+{
+  "slice_id": "slice-01-short-command-and-flow-entrypoint",
+  "ticket": "QUIVER-23-01",
+  "type": "feature",
+  "title": "Short command and guided flow entrypoint",
+  "objective": "Expose a user-friendly guided flow entrypoint while preserving the existing create-quiver CLI.",
+  "description": "Add or document a `quiver` command path and introduce the first flow command surface without changing existing behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "short-command-flow-entrypoint",
+    "branch_name": "feature/QUIVER-23-01-short-command-flow-entrypoint"
+  },
+  "files": [
+    "package.json",
+    "bin/**",
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/**",
+    "docs/COMMANDS.md.template",
+    "README.md",
+    "README_FOR_AI.md",
+    "tests/commands/*.test.js",
+    "scripts/ci/*.sh"
+  ],
+  "depends_on": [
+    "slice-00-spec-foundation"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Establishes the user-facing command surface and likely touches shared CLI routing.",
+  "must": [
+    "Preserve all existing `npx create-quiver` commands.",
+    "Define whether `quiver` is a binary alias or generated local script.",
+    "Add a flow entrypoint with dry-run-safe behavior.",
+    "Document the command decision clearly."
+  ],
+  "not_included": [
+    "Agent profile storage.",
+    "Planner iteration history.",
+    "Delegated execution."
+  ],
+  "acceptance": [
+    "Existing `create-quiver` CLI tests remain green.",
+    "The short command path is documented and tested.",
+    "The flow entrypoint prints clear guidance without requiring provider auth.",
+    "README_FOR_AI.md does not contradict the command decision."
+  ],
+  "tests": [
+    "node --test tests/commands/init-profiles.test.js tests/commands/prepare.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-21T14:42:19-0300"
+}

package/specs/quiver-v23-guided-flow-productization/slices/slice-02-flow-status-wizard/CLOSURE_BRIEF.md

@@ -0,0 +1,31 @@
+# CLOSURE BRIEF - slice-02: Flow status and next-step wizard
+
+## Resumen de lo realizado
+
+Se extendio `npx create-quiver flow` para funcionar como wizard read-only: detecta estado de inicializacion, contexto, approvals, specs y slices, reporta blockers y muestra el proximo comando seguro.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Estado detectado.
+- [x] Bloqueos reportados.
+- [x] Proximo comando sugerido.
+- [x] Tests pasan.
+
+## Cambios relevantes
+
+- `src/create-quiver/commands/flow.js`: agrega lectura segura de approvals, docs, specs y slice graph.
+- `tests/commands/flow.test.js`: cubre proyecto no inicializado, contexto faltante, criterios draft, slices listos y salida JSON.
+- `docs/WORKFLOW.md.template`: recomienda `flow` cuando el siguiente paso seguro no esta claro.
+- `SPEC.md`, `STATUS.md` y `EVIDENCE_REPORT.md`: estado del slice actualizado.
+
+## Pendientes
+
+Ninguno para este slice.
+
+## Riesgos remanentes
+
+El wizard usa heuristicas conservadoras; si el grafo de slices esta roto, bloquea y deriva a `spec status`/`plan` en vez de intentar continuar.
+
+## Recomendaciones futuras
+
+Conectar perfiles de agentes en `slice-03` para que el wizard pueda mostrar provider/model configurados sin pedirlos en cada comando.