create-quiver 0.10.0 → 0.12.0

package/docs/WORKFLOW.md.template

@@ -9,7 +9,7 @@ This document is the canonical implementation workflow for the project.
 - Do not implement without a slice.
 - One slice maps to one commit.
 - One spec maps to one PR.
-- Slice numbering is local to each spec. Every spec starts at `slice-01`.
+- Slice numbering is local to each spec. Every spec starts with mandatory `slice-00` as the documentary foundation; `slice-01` is the first implementation slice.
 - The spec defines the plan; the slice defines the execution.
 - No slice should enter execution until it is `ready`.
 - The documentation PR establishes the workflow files before the first slice executes.
@@ -32,29 +32,37 @@ Use maps, metadata, diffs, and summaries first. Open full files only when the sm
 
 ## Planning
 
-1. Triage the request.
-2. Decide whether to create a new spec or reuse an existing one.
-3. Split the work into slices.
-4. Mark each slice `ready` before execution.
-5. Open and merge the documentation PR before running the first slice bootstrap.
-6. Read the AI context pack, support matrix, and troubleshooting guide before the first slice if the environment is new or uncertain.
-7. If the project already existed before this Quiver version, run `migrate` before `analyze`.
-8. If the project was analyzed, read `AI_ONBOARDING_PROMPT.md` before making documentation updates.
-9. Prefer the generated `quiver:*` npm scripts for repeatable project workflows once the package has been initialized or migrated.
+1. Run `npx create-quiver flow` when the next safe command is unclear.
+2. Triage the request.
+3. Save reusable planner/executor provider choices with `ai agent set` when the team has preferred local AI CLIs.
+4. Use `ai plan --phase acceptance` to draft criteria, then save the approved version with `ai approve --phase acceptance`.
+5. Use `ai plan --phase technical-plan` to draft the plan.
+6. Use `ai review-plan` to review the technical-plan draft for production readiness without changing product code.
+7. Save the reviewed plan version with `ai approve --phase technical-plan --version <n>`.
+8. Use `spec create` to generate the spec, mandatory `slice-00`, implementation slices, handoffs, execution plan, and `pr.md`.
+9. Open and merge the documentation PR or commit that establishes `slice-00` before running implementation slices.
+10. Read the AI context pack, support matrix, and troubleshooting guide before the first slice if the environment is new or uncertain.
+11. If the project already existed before this Quiver version, run `migrate` before `analyze`.
+12. If the project was analyzed, read `AI_ONBOARDING_PROMPT.md` before making documentation updates.
+13. Prefer the generated `quiver:*` npm scripts for repeatable project workflows once the package has been initialized or migrated.
 
 ## Execution
 
-1. Bootstrap the slice with `npx create-quiver start-slice <slice.json>` or `npm run quiver:start-slice -- <slice.json>`.
+1. Create or reuse the spec worktree with `npx create-quiver spec start specs/<spec-slug>` or `npm run quiver:spec:start -- specs/<spec-slug>`.
+2. Inspect manual prompts with `npx create-quiver ai execute-plan --dry-run --commit --mode manual` or delegated waves with `npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated`.
+3. Print a minimal manual executor prompt with `npx create-quiver ai prompt-slice --slice <slice.json> --dry-run` when assigning the slice to another agent.
+4. Bootstrap a single slice with `npx create-quiver start-slice <slice.json>` or `npm run quiver:start-slice -- <slice.json>` when manual execution is preferred.
    - The bootstrap step should work with canonical paths and a local base branch when `origin` is absent.
    - Draft slices require `--allow-draft`; otherwise `npx create-quiver start-slice` exits before execution.
    - Legacy Bash wrappers remain available for compatibility, but generated projects should prefer the Node CLI and `quiver:*` npm scripts.
    - `start-slice` generates `docs/ai/ACTIVE_SLICE.md` and `WORKTREE_CONTEXT.md`; use the active slice brief as the source of truth for execution.
-2. Implement only what the slice declares.
-3. Make one commit for that slice.
-4. Validate with `npx create-quiver check-slice <slice.json>` or `npm run quiver:check-slice -- <slice.json>`.
-5. Write evidence.
-6. Repeat for the next slice until the spec is complete.
-7. Open one PR for the spec and use `npx create-quiver check-pr <slice.json>` or `npm run quiver:check-pr -- <slice.json>` as the pre-merge gate.
+5. Implement only what the slice declares.
+6. Make one commit for that slice, or let `ai execute-slice --commit` / `ai execute-plan --execute --commit --mode delegated` create it after provider, scope, and validation pass.
+7. Validate with `npx create-quiver check-slice <slice.json>` or `npm run quiver:check-slice -- <slice.json>`.
+8. Write evidence. Prefer `npx create-quiver evidence run -- <command>` when you need a compact local Markdown record of validation output.
+9. Repeat for the next slice until the spec is complete.
+10. Open one PR for the spec. Use `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md ...` first, then add `--create` only after review.
+11. After the PR is merged and the spec worktree is clean, close it with `npx create-quiver spec close specs/<spec-slug>`.
 
 ## Support Contract
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "create-quiver",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
   "bin": {
-    "create-quiver": "bin/create-quiver.js"
+    "create-quiver": "bin/create-quiver.js",
+    "quiver": "bin/create-quiver.js"
   },
   "scripts": {
     "check:slice": "bash tools/scripts/check-slice-readiness.sh",
@@ -13,17 +14,33 @@
     "start:slice": "bash tools/scripts/start-slice.sh",
     "cleanup:slice": "bash tools/scripts/cleanup-slice.sh",
     "migrate": "bash tools/scripts/migrate-project.sh",
+    "quiver:analyze": "npx create-quiver analyze",
+    "quiver:flow": "npx create-quiver flow",
+    "quiver:prepare": "npx create-quiver prepare",
     "quiver:plan": "npx create-quiver plan",
     "quiver:graph": "npx create-quiver graph",
     "quiver:next": "npx create-quiver next",
+    "quiver:doctor": "npx create-quiver doctor",
+    "quiver:evidence": "npx create-quiver evidence",
+    "quiver:ai:agent": "npx create-quiver ai agent",
     "quiver:ai:onboard": "npx create-quiver ai onboard",
+    "quiver:ai:prepare-context": "npx create-quiver ai prepare-context",
     "quiver:ai:plan": "npx create-quiver ai plan",
+    "quiver:ai:review-plan": "npx create-quiver ai review-plan",
+    "quiver:ai:approve": "npx create-quiver ai approve",
+    "quiver:ai:prompt-slice": "npx create-quiver ai prompt-slice",
     "quiver:ai:execute-slice": "npx create-quiver ai execute-slice",
+    "quiver:ai:execute-plan": "npx create-quiver ai execute-plan",
     "quiver:ai:pr": "npx create-quiver ai pr",
     "quiver:ai:doctor": "npx create-quiver ai doctor",
+    "quiver:spec:create": "npx create-quiver spec create",
+    "quiver:spec:start": "npx create-quiver spec start",
+    "quiver:spec:status": "npx create-quiver spec status",
+    "quiver:spec:close": "npx create-quiver spec close",
     "package:quiver": "bash scripts/package-quiver.sh",
     "smoke:create-quiver": "bash scripts/ci/smoke-create-quiver.sh",
     "smoke:tiered-pack": "bash scripts/ci/smoke-tiered-pack.sh",
+    "smoke:guided-workflow": "bash scripts/ci/smoke-guided-workflow.sh",
     "release:quiver": "bash scripts/release-quiver.sh"
   }
 }

package/package.template.json

@@ -1,18 +1,30 @@
 {
-  "name": "quiver-docs-template",
+  "name": "quiver-project",
   "private": true,
   "scripts": {
     "quiver:migrate": "npx create-quiver migrate",
     "quiver:analyze": "npx create-quiver analyze",
+    "quiver:flow": "npx create-quiver flow",
     "quiver:plan": "npx create-quiver plan",
     "quiver:graph": "npx create-quiver graph",
     "quiver:next": "npx create-quiver next",
     "quiver:doctor": "npx create-quiver doctor",
+    "quiver:evidence": "npx create-quiver evidence",
+    "quiver:ai:agent": "npx create-quiver ai agent",
     "quiver:ai:onboard": "npx create-quiver ai onboard",
+    "quiver:ai:prepare-context": "npx create-quiver ai prepare-context",
     "quiver:ai:plan": "npx create-quiver ai plan",
+    "quiver:ai:review-plan": "npx create-quiver ai review-plan",
+    "quiver:ai:approve": "npx create-quiver ai approve",
+    "quiver:ai:prompt-slice": "npx create-quiver ai prompt-slice",
     "quiver:ai:execute-slice": "npx create-quiver ai execute-slice",
+    "quiver:ai:execute-plan": "npx create-quiver ai execute-plan",
     "quiver:ai:pr": "npx create-quiver ai pr",
     "quiver:ai:doctor": "npx create-quiver ai doctor",
+    "quiver:spec:create": "npx create-quiver spec create",
+    "quiver:spec:start": "npx create-quiver spec start",
+    "quiver:spec:status": "npx create-quiver spec status",
+    "quiver:spec:close": "npx create-quiver spec close",
     "quiver:start-slice": "npx create-quiver start-slice",
     "quiver:check-slice": "npx create-quiver check-slice",
     "quiver:check-pr": "npx create-quiver check-pr",

package/scripts/init-docs.sh

@@ -522,8 +522,12 @@ Start with dry-runs so you can inspect the provider, role, context pack, and inv
 \`\`\`bash
 npm run quiver:ai:onboard -- --dry-run
 npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
-npm run quiver:ai:plan -- --phase technical-plan --input acceptance-approved.md --dry-run
-npm run quiver:ai:plan -- --phase spec --input technical-plan-approved.md --dry-run
+npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:plan -- --phase technical-plan --dry-run
+npm run quiver:ai:review-plan -- --dry-run
+npm run quiver:ai:approve -- --phase technical-plan --version <n>
+npm run quiver:spec:create -- --dry-run
+npm run quiver:ai:prompt-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
 npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 \`\`\`
 
@@ -532,7 +536,9 @@ Remove \`--dry-run\` only after the phase output is approved and the local provi
 When a real spec exists, execute one approved slice at a time:
 
 \`\`\`bash
+npm run quiver:ai:prompt-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
 npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
 \`\`\`
 
 ## Project NPM Scripts
@@ -547,6 +553,7 @@ npm run quiver:next
 npm run quiver:doctor
 npm run quiver:ai:onboard -- --dry-run
 npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
+npm run quiver:ai:prompt-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
 npm run quiver:ai:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
 npm run quiver:ai:doctor -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
 npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
@@ -645,7 +652,7 @@ Record durable decisions in \`docs/DECISIONS.md\` so future AI agents do not re-
 
 ## First Slice Workflow
 
-Use this section only for the legacy/full scaffold that includes a placeholder spec. In the default AI-first layout, create real specs and slices with \`npx create-quiver ai plan --phase spec\` after acceptance criteria and the technical plan are approved.
+Use this section only for the legacy/full scaffold that includes a placeholder spec. In the default AI-first layout, create real specs and slices with \`npx create-quiver spec create\` after acceptance criteria are approved and the technical plan is reviewed and approved.
 
 1. Review or refine specs/$PROJECT_SLUG/SPEC.md.
 2. Create the first slice from specs/$PROJECT_SLUG/slices/slice-template/slice.json.
@@ -700,7 +707,7 @@ echo "📝 Próximos pasos:"
 echo "   1. Editar docs/AI_CONTEXT.md con el contexto resumido para IA"
 echo "   2. Editar docs/CONTEXTO.md con la información de tu proyecto"
 echo "   3. Editar docs/STATUS.md con el estado actual"
-echo "   4. Para el flujo recomendado, crear specs reales con: npx create-quiver ai plan --phase spec"
+echo "   4. Para el flujo recomendado, crear specs reales con: npx create-quiver spec create"
 echo "   5. Usar tools/scripts solo si necesitás compatibilidad legacy"
 echo ""
 echo "📖 Más información:"

package/scripts/package-quiver.sh

@@ -34,10 +34,26 @@ contents="$(
   tar -tzf "$tarball_path"
 )"
 
+cd "$repo_root"
+# shellcheck disable=SC2016
+printf '%s\n' "$contents" | node -e '
+  const fs = require("node:fs");
+  const { assertPackageSafety } = require("./src/create-quiver/lib/package-safety");
+
+  const paths = fs.readFileSync(0, "utf8").split(/\r?\n/).filter(Boolean);
+
+  try {
+    assertPackageSafety(paths);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+'
+
 require_present() {
   local path="$1"
 
-  if ! printf '%s\n' "$contents" | grep -Fxq "$path"; then
+  if ! grep -Fxq "$path" <<<"$contents"; then
     echo "FAIL: falta '$path' en el paquete" >&2
     exit 1
   fi
@@ -46,7 +62,7 @@ require_present() {
 require_absent() {
   local path="$1"
 
-  if printf '%s\n' "$contents" | grep -Fxq "$path"; then
+  if grep -Fxq "$path" <<<"$contents"; then
     echo "FAIL: '$path' no debería publicarse en el paquete" >&2
     exit 1
   fi

package/specs/quiver-v22-guided-ai-workflow/EVIDENCE_REPORT.md

@@ -0,0 +1,58 @@
+# Evidence Report - Quiver v22 Guided AI Workflow
+
+## Status
+
+Implementation is completed. Slices `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 | Documentation source-of-truth sync completed. README no longer claims `package.json`/CHANGELOG are at 0.9.0, CHANGELOG includes 0.10.0, ROADMAP/BACKLOG distinguish shipped v20/v21 work from the then-active v22 implementation line, and targeted tests passed. |
+| slice-02 | Prepare command implemented with dry-run diagnostics, GitHub CLI guidance, provider CLI guidance, SSH identity/auth recovery steps, and next safe command output. Targeted tests passed. |
+| slice-03 | Analyze now refreshes `docs/AI_CONTEXT.md`, keeps `docs/PROJECT_MAP.md` visible, keeps raw scan under `.quiver/scans/PROJECT_SCAN.json`, summarizes missing/assumed context, and excludes secret/noisy paths from AI-facing context. Targeted tests passed. |
+| slice-04 | Planner approval state implemented under `.quiver/approvals`, with draft persistence, explicit approvals, default use of approved acceptance/technical-plan inputs, `ai approvals` status, and blocking of unapproved/stale inputs. Targeted tests passed. |
+| slice-05 | Spec-level worktree lifecycle implemented with `spec start/status`, safe main/develop base selection, dirty worktree protection, and `slice-00` completion guard for later `start-slice` executions. Targeted tests passed. |
+| slice-06 | `ai execute-slice` now keeps executor context bounded, validates scope, runs declared validation commands, reports retry/abort guidance on failure, and creates exactly one commit when `--commit` is enabled after successful provider, scope, and validation stages. Targeted tests passed. |
+| slice-07 | Execution waves now distinguish parallel-ready groups from sequential fallback, block parallel suggestions on unknown or overlapping file scopes, print dry-run executor commands without provider calls, and support explicit `ai execute-plan --execute --commit` with stop-on-failure behavior. Targeted tests passed. |
+| slice-08 | `ai pr` now validates setup, reads generated `pr.md`, prints a dry-run `gh pr create` plan, and creates the PR only with explicit `--create`. Missing gh/auth/guide/identity/body/dirty state still blocks with guidance. Tests mock gh and real PR creation is not required. |
+| slice-09 | `spec close` now blocks unmerged or dirty spec worktrees, removes merged clean worktrees, and pulls the main checkout when a remote base exists. Package safety now checks npm tarball contents for env files, npm credentials, AI local state, worktree state, and local worktree context before package smoke passes. Targeted tests and package smoke passed. |
+| slice-10 | Final docs and generated templates now present the guided AI workflow as available behavior. Smokes cover prepare, approvals, execution waves, PR dry-run/create mocks, cleanup, package safety, generated project scripts, post-analyze AI context front matter, and mandatory `slice-00` fixtures. Full tests, smokes, JSON validation, diff check, and npm pack dry-run passed. |
+
+## Validation Log
+
+- 2026-05-21: `find specs/quiver-v22-guided-ai-workflow -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/analyze.test.js tests/commands/ai-plan.test.js tests/commands/ai-pr.test.js`
+- 2026-05-21: `node --test tests/commands/prepare.test.js tests/lib/ai-github.test.js tests/lib/ai-providers.test.js tests/lib/doctor.test.js`
+- 2026-05-21: `node --test tests/commands/analyze.test.js tests/lib/ai-context-packs.test.js tests/lib/ai-safety.test.js`
+- 2026-05-21: `node --test tests/commands/ai-plan.test.js tests/commands/ai-plan-spec-phase.test.js tests/lib/approvals.test.js`
+- 2026-05-21: `node --test tests/lib/lifecycle.test.js tests/commands/spec-worktree.test.js`
+- 2026-05-21: `node --test tests/lib/check-slice.test.js tests/commands/next.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `node --test tests/commands/ai-execute-slice.test.js tests/lib/ai-executor.test.js tests/lib/scope.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `node --test tests/lib/ai-execution-plan.test.js tests/commands/ai-execute-plan.test.js`
+- 2026-05-21: `node --test tests/commands/ai-execute-slice.test.js tests/lib/ai-executor.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `node --test tests/commands/ai-pr.test.js tests/lib/ai-github.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `node --test tests/commands/spec-close.test.js tests/lib/package-safety.test.js`
+- 2026-05-21: `bash scripts/package-quiver.sh`
+- 2026-05-21: `node --test tests/commands/spec-worktree.test.js tests/lib/lifecycle.test.js tests/commands/spec-close.test.js tests/lib/package-safety.test.js`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `node --test tests/lib/init-layout.test.js tests/lib/init-docs.test.js tests/commands/init-profiles.test.js`
+- 2026-05-21: `node --test tests/commands/analyze.test.js tests/lib/init-docs.test.js`
+- 2026-05-21: `npm run smoke:guided-workflow`
+- 2026-05-21: `node --test tests/**/*.test.js`
+- 2026-05-21: `npm run smoke:create-quiver`
+- 2026-05-21: `npm run smoke:tiered-pack`
+- 2026-05-21: `npm --cache /private/tmp/quiver-npm-cache pack --dry-run`
+- 2026-05-21: `git diff --check`
+- 2026-05-21: `find specs/quiver-v22-guided-ai-workflow -name slice.json -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;`
+
+## Notes
+
+- `npm pack --dry-run` failed once against the global npm cache because `~/.npm` contains root-owned files. Re-running with `npm --cache /private/tmp/quiver-npm-cache pack --dry-run` passed.
+- No npm publish was performed by this slice.

package/specs/quiver-v22-guided-ai-workflow/EXECUTION_PLAN.md

@@ -0,0 +1,88 @@
+# Execution Plan - Quiver v22 Guided AI Workflow
+
+## 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 optimizes for low merge risk and production-readiness over speed.
+
+| Wave | Mode | Slices | Why |
+|------|------|--------|-----|
+| 0 | Sequential | `slice-00-spec-foundation` | Publishes the spec foundation, handoffs, execution plan, and PR body. Nothing else should start before this commit exists. |
+| 1 | Sequential | `slice-01-docs-source-of-truth-sync` | Fixes current documentation drift so later agents read reliable guidance. |
+| 2 | Sequential | `slice-02-prepare-command-diagnostics` | Adds the safe project preparation entrypoint used by later workflow steps. |
+| 3 | Sequential | `slice-03-context-doc-refresh` | Improves AI context generation after the preparation command exists. |
+| 4 | Sequential | `slice-04-planner-approval-state` | Adds persisted approvals; spec/worktree automation should not run before approved inputs are traceable. |
+| 5 | Sequential | `slice-05-spec-worktree-lifecycle` | Establishes one spec per worktree before executor, PR, and cleanup automation. |
+| 6 | Sequential | `slice-06-executor-commit-recovery` | Makes single-slice execution safe and recoverable before multi-slice execution. |
+| 7 | Sequential | `slice-07-execution-waves-delegation` | Builds on the executor to coordinate waves and delegation. |
+| 8 | Sequential | `slice-08-pr-create-gh-ssh` | Adds PR creation after command-router changes from execution slices are stable. |
+| 9 | Sequential | `slice-09-post-merge-cleanup-release-safety` | Requires execution-wave and PR behavior to be known. |
+| 10 | Sequential | `slice-10-docs-smokes-release-readiness` | Final docs and smokes must run last. |
+
+## Parallelization Assessment
+
+No slice should run in parallel before `slice-05`.
+
+After `slice-05`, `slice-06-executor-commit-recovery` and `slice-08-pr-create-gh-ssh` are conceptually independent, but the declared file scopes overlap in command-router files such as `src/create-quiver/commands/ai.js`. Because of that, the default recommendation is sequential execution.
+
+Parallel execution is allowed only if the executor changes are split so file ownership is disjoint:
+
+| Optional Wave | Mode | Slices | Condition |
+|---------------|------|--------|-----------|
+| 6A | Parallel | `slice-06-executor-commit-recovery` + `slice-08-pr-create-gh-ssh` | Only if one slice owns executor internals and the other owns PR internals without both editing the same command-router files. |
+| 6B | Sequential integration | Router wiring or conflict resolution | Required if 6A was used and both features need command registration. |
+| 7 | Sequential | `slice-07-execution-waves-delegation` | Starts only after executor behavior from `slice-06` is integrated. |
+
+If the file scopes are not split before execution, do not use the optional parallel wave.
+
+## Dependency Graph
+
+```mermaid
+flowchart TD
+    S00[slice-00 spec foundation] --> S01[slice-01 docs sync]
+    S01 --> S02[slice-02 prepare diagnostics]
+    S02 --> S03[slice-03 context doc refresh]
+    S03 --> S04[slice-04 planner approvals]
+    S04 --> S05[slice-05 spec worktree lifecycle]
+    S05 --> S06[slice-06 executor commit recovery]
+    S06 --> S07[slice-07 execution waves]
+    S05 --> S08[slice-08 PR creation]
+    S07 --> S09[slice-09 cleanup and release safety]
+    S08 --> S09
+    S09 --> S10[slice-10 docs smokes release readiness]
+```
+
+## Suggested Commit Order
+
+1. `docs(spec): add guided ai workflow spec foundation`
+2. `docs(ai): sync source of truth for guided workflow`
+3. `feat(cli): add guided prepare diagnostics`
+4. `feat(analyze): refresh ai context docs safely`
+5. `feat(ai): persist planner approvals`
+6. `feat(spec): manage spec worktree lifecycle`
+7. `feat(ai): commit validated executor slices`
+8. `feat(ai): execute slices by safe waves`
+9. `feat(ai): create prs with gh and ssh guidance`
+10. `feat(spec): close merged specs and guard releases`
+11. `docs(ai): document guided workflow and add smokes`
+
+## Executor Assignment
+
+Recommended executor model:
+
+- Use the planner agent for `slice-00`, high-level review, and final integration checks.
+- Use cheaper executor agents for `slice-01` through `slice-08` only after the owning slice and file scope are clear.
+- Keep `slice-09` with a stronger reviewer because it includes cleanup and release-safety behavior.
+- Keep `slice-10` with the planner or a docs/test-focused executor because it validates the full user-facing story.
+
+## Integration Notes
+
+- Do not start implementation slices before `slice-00` is committed.
+- Do not enable parallel execution before file-scope conflict checks exist.
+- If two slices declare the same source file, execute them sequentially or split ownership before delegation.
+- Keep provider and `gh` tests mocked.
+- Treat real provider CLIs as optional manual checks.
+- Keep one spec PR branch/worktree for final integration.

package/specs/quiver-v22-guided-ai-workflow/SPEC.md

@@ -0,0 +1,228 @@
+# Quiver v22 - Guided AI Workflow
+
+**Date:** 2026-05-21
+**Status:** Completed
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Quiver already has an AI-first foundation: it can initialize a project, analyze it, generate context artifacts, run planner phases, generate specs/slices/handoffs, execute one slice with reduced context, and run GitHub PR preflight checks.
+
+The current experience still requires too much manual coordination. A user must remember which command comes next, manually preserve approved criteria and plans, decide when a worktree is safe, decide when parallel execution is safe, create slice commits by hand, and open or close the PR outside the guided flow.
+
+The desired workflow is a guided AI delivery line:
+
+1. Install or run Quiver.
+2. Prepare the project for AI onboarding.
+3. Choose a planner agent.
+4. Run planner onboarding with generated context.
+5. Turn requirements into acceptance criteria.
+6. Iterate criteria until approved.
+7. Turn approved criteria into a development plan.
+8. Iterate the plan until approved.
+9. Generate spec, slices, handoffs, and `pr.md`.
+10. Build an execution plan with sequential and parallel slices.
+11. Execute slices through cheaper executor agents, one slice per commit.
+12. Open the PR from the generated body.
+13. Let the human review and merge.
+14. Close the worktree and pull merged changes back into the main local checkout.
+
+## Objective
+
+Make Quiver guide the full AI-assisted workflow from project preparation to post-merge cleanup while preserving human approvals, one spec per worktree, one slice per commit, token-efficient executor context, and safe defaults.
+
+## Core Decisions
+
+- `README_FOR_AI.md` remains the source of truth for Quiver workflow guidance in this repo.
+- This repo uses `specs/quiver-vNN-*` as the real spec location, even though some reusable skills mention `docs/specs/`.
+- `slice-00` is mandatory and only establishes the spec foundation.
+- One spec maps to one dedicated worktree and one PR.
+- One slice maps to one commit.
+- Planner agents use broad context and do not modify product code while creating criteria or plans.
+- Executor agents may modify product code only inside the approved slice scope.
+- AI outputs that influence implementation must be saved and explicitly approved before they become inputs for the next phase.
+- Parallel slice execution is allowed only when dependencies and touched files make it safe.
+- Quiver validates or guides setup for `gh`, SSH aliases, provider CLIs, and auth. It must not silently rewrite credentials.
+- PR creation is allowed after checks pass, but PR merge remains a human decision.
+- Worktree cleanup is allowed only after the PR merge is confirmed and no local changes would be lost.
+
+## Scope
+
+### Included
+
+- Sync documentation that drifted after `0.10.0`.
+- Define the official command experience for guided workflows, including whether a short `quiver` command exists or commands remain under `npx create-quiver`.
+- Add a safe project preparation command that combines analysis, diagnostics, context refresh, and setup guidance.
+- Improve project analysis so it produces useful AI onboarding context without exposing secrets or noisy generated files.
+- Persist planner outputs and approvals for acceptance criteria and technical plans.
+- Generate specs, slices, handoffs, execution plans, and `pr.md` only from approved inputs.
+- Formalize one spec per worktree.
+- Add status, retry, abort, and recovery surfaces for slices.
+- Add optional commit automation after slice validation.
+- Add execution waves for sequential and parallel slices.
+- Add safe delegation guidance for cheap executor agents.
+- Create PRs with `gh` from generated `pr.md` after preflight passes.
+- Add post-merge cleanup that removes the spec worktree and pulls the main local checkout.
+- Add release/package safety checks so local settings or secrets are not published.
+- Cover macOS, Linux, and Windows guidance for `gh`, SSH, providers, and paths.
+
+### Excluded
+
+- Fully autonomous PR merge.
+- Silent installation of tools without explicit user approval.
+- Silent SSH config rewriting.
+- Direct provider API integrations.
+- Guaranteeing identical behavior across Codex, Claude, and Gemini CLIs.
+- Running real paid AI providers in CI.
+- Replacing human approval for acceptance criteria, plans, or PR review.
+
+## Acceptance Criteria
+
+1. Given the root docs drift from the published package version, when the docs-sync slice runs, then README, CHANGELOG, ROADMAP, BACKLOG, and AI guidance no longer contradict the current package state.
+2. Given a user wants to start safely, when the preparation command runs in dry-run mode, then it reports planned checks and writes nothing.
+3. Given a user runs preparation for real, when the repo is valid, then Quiver refreshes project context docs and reports assumptions, risks, missing tools, and next commands.
+4. Given a project has secrets, env files, generated files, large artifacts, or dependency folders, when context is prepared, then those files are excluded from AI-facing context.
+5. Given `gh`, provider CLIs, auth, or SSH aliases are missing, when diagnostics run, then Quiver gives OS-specific guidance for macOS, Linux, and Windows.
+6. Given a planner produces acceptance criteria, when the user does not approve them, then Quiver keeps them as draft and does not create a technical plan or spec.
+7. Given acceptance criteria are approved, when the next phase starts, then Quiver uses the approved criteria as the source input.
+8. Given a planner produces a technical plan, when the user does not approve it, then Quiver keeps it as draft and does not create spec artifacts.
+9. Given a technical plan is approved, when the spec phase runs, then Quiver creates `SPEC.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, `EXECUTION_PLAN.md`, `pr.md`, mandatory `slice-00`, and per-slice handoffs.
+10. Given generated slices, when the execution plan is built, then `slice-00` is first and every later slice is blocked until `slice-00` is committed.
+11. Given a spec starts, when Quiver creates or selects its worktree, then it uses one dedicated worktree/branch for that spec.
+12. Given a slice executor runs, when it receives context, then it receives only the slice, handoff, allowed files, criteria, and validation commands.
+13. Given a slice executor modifies files outside scope, when validation runs, then Quiver stops and reports the scope violation.
+14. Given a slice passes validation and commit automation is enabled, when the slice completes, then Quiver creates exactly one commit for that slice.
+15. Given a slice fails validation, when the command exits, then Quiver leaves a clear report and supports retry or abort without hiding local changes.
+16. Given multiple slices are ready, when execution waves are requested, then Quiver only runs slices in parallel if dependencies and file scopes do not conflict.
+17. Given execution waves include conflicts or unknown file scopes, when Quiver plans execution, then it falls back to sequential execution.
+18. Given all required slices are complete, when PR creation runs, then Quiver validates `gh`, auth, remote, branch, worktree, identity file, SSH alias, clean state, and generated `pr.md`.
+19. Given PR checks pass, when the user confirms PR creation, then Quiver creates the PR with `gh` using `pr.md`.
+20. Given a PR is not merged, when cleanup is requested, then Quiver refuses normal cleanup and explains the safe options.
+21. Given a PR is merged and the worktree is clean, when cleanup runs, then Quiver removes the spec worktree and pulls the merged changes into the main local checkout.
+22. Given package release validation runs, when local settings, env files, npm credentials, or AI tool local state would be included, then Quiver fails before packaging or publishing.
+
+## Approved Technical Plan
+
+### Objective
+
+Turn Quiver's current AI commands into a guided workflow that is safer, more recoverable, and easier to use end to end.
+
+### Architecture
+
+Add a lightweight workflow state layer under `.quiver/` and keep versioned project contracts under visible docs and `specs/`.
+
+Recommended areas:
+
+```text
+src/create-quiver/commands/prepare.js
+src/create-quiver/commands/ai.js
+src/create-quiver/commands/spec.js
+src/create-quiver/lib/workflow-state.js
+src/create-quiver/lib/context-writer.js
+src/create-quiver/lib/approvals.js
+src/create-quiver/lib/spec-worktrees.js
+src/create-quiver/lib/slice-runner.js
+src/create-quiver/lib/pr-create.js
+src/create-quiver/lib/package-safety.js
+```
+
+The exact file names can change during implementation if the existing codebase points to a better local pattern.
+
+### Workflow State
+
+Persist workflow progress in `.quiver/`:
+
+- selected provider and role;
+- current spec;
+- current worktree;
+- draft and approved acceptance criteria;
+- draft and approved technical plan;
+- generated spec path;
+- slice statuses;
+- execution wave status;
+- PR status;
+- cleanup status.
+
+Only durable team contracts belong in visible docs or `specs/`.
+
+### Command Experience
+
+The command surface should be simple for humans:
+
+```bash
+npx create-quiver prepare
+npx create-quiver ai planner onboard
+npx create-quiver ai planner acceptance
+npx create-quiver ai approve acceptance
+npx create-quiver ai planner technical-plan
+npx create-quiver ai approve technical-plan
+npx create-quiver ai planner spec
+npx create-quiver spec start
+npx create-quiver ai execute-plan
+npx create-quiver ai pr create
+npx create-quiver spec close
+```
+
+If a short `quiver` binary is introduced, it must be documented as an alias or project-local script and must not contradict the canonical `npx create-quiver` entrypoint until that decision is made.
+
+### Safety Rules
+
+- Dry-run support comes before write support.
+- No product code changes before an approved slice.
+- No commit before validation.
+- No parallel execution when files or dependencies are unclear.
+- No PR creation with dirty worktree or missing generated PR body.
+- No cleanup before merge confirmation.
+- No publishing if local settings or secrets enter the package tarball.
+
+### Validation Strategy
+
+- Unit tests for state persistence and approval transitions.
+- Unit tests for context exclusion and secret/path filters.
+- Unit tests for missing tools and cross-platform install guidance.
+- Unit tests for spec worktree lifecycle and cleanup guardrails.
+- Unit tests for slice commit success/failure behavior.
+- Unit tests for execution wave grouping and conflict fallback.
+- Unit tests for PR creation command construction with mocked `gh`.
+- Smoke tests for `prepare`, planner approval flow, executor dry-run, PR dry-run, and release/package safety.
+- Existing tests for `ai plan`, `ai execute-slice`, `plan`, `graph`, and `next` must remain green.
+
+## Slicing Strategy
+
+`slice-00` lands first and only publishes this spec foundation. The rest of the work is split so Quiver becomes useful earlier while high-risk automation, such as parallel execution and cleanup, is introduced after state, approvals, and single-slice execution are reliable.
+
+## Slice Roadmap
+
+| Slice | Title | Status | Dependencies |
+|-------|-------|--------|--------------|
+| slice-00 | Spec foundation and guided workflow planning artifacts | Completed | none |
+| slice-01 | Documentation source-of-truth sync | Completed | slice-00 |
+| slice-02 | Prepare command and setup diagnostics | Completed | slice-01 |
+| slice-03 | Context documentation refresh and safe analyzer output | Completed | slice-02 |
+| slice-04 | Planner approval state for criteria and technical plans | Completed | slice-03 |
+| slice-05 | Spec worktree lifecycle | Completed | slice-04 |
+| slice-06 | Executor validation, recovery, and commit per slice | Completed | slice-05 |
+| slice-07 | Execution waves and safe delegation | Completed | slice-06 |
+| slice-08 | PR creation with gh and SSH guidance | Completed | slice-05 |
+| slice-09 | Post-merge cleanup and release safety | Completed | slice-07, slice-08 |
+| slice-10 | Final docs, smokes, and release readiness | Completed | slice-09 |
+
+## Risks
+
+- A short `quiver` command can confuse users if it is introduced before the canonical command decision is documented.
+- Persisted approval state can drift from visible spec artifacts if not validated.
+- More automation increases the cost of recovering from failed provider runs.
+- Parallel executor runs can create conflicts or overlapping edits.
+- Cross-platform setup guidance can become stale if it is duplicated in several files.
+- PR creation can target the wrong account if `gh` auth and SSH alias point to different identities.
+- Cleanup can delete useful local work if merge and cleanliness checks are incomplete.
+- Packaging can leak local tool state unless tarball checks are enforced.
+
+## Open Questions
+
+- Should the short command be `quiver`, a project-local npm script, or only documented as future sugar over `npx create-quiver`?
+- Should approval artifacts be versioned in `specs/` or stored internally in `.quiver/` until the spec is generated?
+- Should commit automation default to confirmation prompts or require an explicit `--commit` flag?
+- Should execution waves initially print commands for manual execution before running multiple providers automatically?
+- Should `gh` installation remain guidance-only or include optional installer helpers behind explicit approval?