create-quiver 0.9.1 → 0.12.0

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?

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

@@ -0,0 +1,42 @@
+# Quiver v22 - Guided AI Workflow Status
+
+**Status:** Completed
+**Created:** 2026-05-21
+
+## Summary
+
+This spec implemented the guided AI workflow needed to move from project preparation to planner approvals, spec generation, slice execution, PR creation, and post-merge cleanup.
+
+## Current State
+
+- Requirements and acceptance criteria: approved in conversation.
+- Technical plan: approved in conversation after production-readiness review.
+- Spec and slice handoffs: created in this documentation pass.
+- `slice-00`: completed.
+- `slice-01`: completed.
+- `slice-02`: completed.
+- `slice-03`: completed.
+- `slice-04`: completed.
+- `slice-05`: completed.
+- `slice-06`: completed.
+- `slice-07`: completed.
+- `slice-08`: completed.
+- `slice-09`: completed.
+- `slice-10`: completed.
+
+## 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
+
+- The canonical executable remains `npx create-quiver`; a short `quiver` binary was not introduced in this spec.
+- Approved planner artifacts are persisted under `.quiver/approvals` until generated specs and slices become versioned repo artifacts.
+- Commit automation is opt-in through `--commit`; real execution waves also require `--execute`.
+- Package publication is intentionally outside this slice and should be handled by the release workflow after review.

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

@@ -0,0 +1,104 @@
+## Title
+
+Quiver v22 - Guided AI workflow
+
+## Summary
+
+Adds the plan for a guided AI workflow that takes Quiver from project preparation through planner approvals, spec generation, slice execution, PR creation, and post-merge cleanup.
+
+The goal is to make Quiver feel like an AI-first delivery assistant: the planner handles context and decisions, cheaper executors handle bounded slices, each slice becomes one commit, and the human remains responsible for approvals and PR merge.
+
+## Scope
+
+- Documentation source-of-truth sync
+- Guided project preparation command
+- AI context refresh with safe exclusions
+- Draft and approved planner artifact persistence
+- One spec per worktree lifecycle
+- Executor validation, recovery, and optional commit per slice
+- Execution waves for safe sequential and parallel slice work
+- PR creation with `gh` and SSH guidance
+- Post-merge cleanup
+- Package/release safety checks
+- Final docs, scripts, and smoke coverage
+
+## Files
+
+- `specs/quiver-v22-guided-ai-workflow/SPEC.md`
+- `specs/quiver-v22-guided-ai-workflow/STATUS.md`
+- `specs/quiver-v22-guided-ai-workflow/EVIDENCE_REPORT.md`
+- `specs/quiver-v22-guided-ai-workflow/EXECUTION_PLAN.md`
+- `specs/quiver-v22-guided-ai-workflow/pr.md`
+- `specs/quiver-v22-guided-ai-workflow/slices/**`
+
+Future implementation slices are expected to touch CLI source, AI orchestration modules, analyzer/context modules, worktree lifecycle code, PR helpers, tests, templates, generated docs, and smoke scripts as declared in each slice.
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js supported by Quiver
+- npm
+- Git
+- `gh` for PR creation slices
+- Optional local provider CLIs for manual checks:
+  - `codex`
+  - `claude`
+  - `gemini`
+
+### Worktree Access
+
+Use one dedicated worktree for this spec PR. Parallel slices may use temporary slice worktrees only when the execution plan marks them safe and their changed-file scopes do not conflict.
+
+### Run the Project
+
+For documentation-only `slice-00`, validate files and JSON:
+
+```bash
+git diff --check
+find specs/quiver-v22-guided-ai-workflow -name "slice.json" -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" {} \;
+```
+
+For implementation slices, run the validation commands declared in each `slice.json` and `EXECUTION_BRIEF.md`.
+
+### Use Cases
+
+- New user prepares a repo for AI-assisted work.
+- Planner creates and iterates acceptance criteria.
+- Planner creates and iterates the technical plan.
+- Approved plan generates spec, slices, handoffs, execution plan, and PR body.
+- Executor runs a bounded slice with reduced context.
+- Slice validation passes and one commit is created.
+- Failed slice leaves a recoverable report.
+- Ready slices are grouped into safe execution waves.
+- PR is created from `pr.md` after `gh` and SSH checks.
+- Merged spec worktree is closed and main local checkout is updated.
+
+### Technical Verification
+
+- Dry-run paths write nothing.
+- Approval transitions are explicit and persisted.
+- Context excludes secrets, env files, generated outputs, dependency folders, and local AI tool state.
+- Worktree cleanup refuses dirty or unmerged work.
+- PR creation uses `gh` without opening a PR in tests.
+- Release safety fails if unsafe local files would enter the npm package.
+
+## Evidence
+
+To be completed by implementation slices. Expected evidence includes:
+
+- `node --test tests/**/*.test.js`
+- `npm run smoke:create-quiver`
+- targeted smoke tests for guided prepare, approval flow, executor commit, execution waves, PR creation, cleanup, and release safety
+- `git diff --check`
+
+## 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 intentionally does not automate PR merge.
+- Short command naming must not conflict with the canonical `npx create-quiver` guidance.
+- Parallel execution must remain conservative until conflict detection is reliable.
+- Tool installation and SSH setup must require explicit user approval.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,35 @@
+# CLOSURE BRIEF - slice-00: Spec foundation
+
+## Resumen de lo realizado
+
+Se creo la base documental completa de `quiver-v22-guided-ai-workflow`, incluyendo spec, estado, evidencia, plan de ejecucion, cuerpo de PR y handoffs por slice.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Spec creada.
+- [x] `slice-00` creada.
+- [x] Handoffs creados para cada slice.
+- [x] `EXECUTION_PLAN.md` creado.
+- [x] `pr.md` creado.
+- [x] JSON validado.
+
+## Cambios relevantes
+
+- `specs/quiver-v22-guided-ai-workflow/SPEC.md`
+- `specs/quiver-v22-guided-ai-workflow/STATUS.md`
+- `specs/quiver-v22-guided-ai-workflow/EVIDENCE_REPORT.md`
+- `specs/quiver-v22-guided-ai-workflow/EXECUTION_PLAN.md`
+- `specs/quiver-v22-guided-ai-workflow/pr.md`
+- `specs/quiver-v22-guided-ai-workflow/slices/**`
+
+## Pendientes
+
+Ninguno para esta slice.
+
+## Riesgos remanentes
+
+El spec es amplio y debe ejecutarse en orden conservador. El plan marca paralelismo solo como opcional y condicionado a scopes disjuntos.
+
+## Recomendaciones futuras
+
+Ejecutar `slice-01-docs-source-of-truth-sync` antes de modificar comportamiento, para evitar que los proximos agentes lean documentacion desactualizada.

package/specs/quiver-v22-guided-ai-workflow/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,61 @@
+# EXECUTION BRIEF - slice-00: Spec foundation
+
+**Spec:** quiver-v22-guided-ai-workflow
+**Slice:** slice-00-spec-foundation
+**Tipo:** docs
+
+## Contexto
+
+Esta slice sube al repo la base documental del nuevo flujo guiado de IA. 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 el guided AI workflow.
+
+## 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-v22-guided-ai-workflow/` 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 todas las slices posteriores.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `README_FOR_AI.md`.
+2. Crear estructura `specs/quiver-v22-guided-ai-workflow/`.
+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 crear PR todavia.
+
+## Riesgos
+
+- Generar 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-v22-guided-ai-workflow/`.
+- [ ] El commit representa solo slice-00.