create-quiver 0.10.0 → 0.12.1

package/docs/TROUBLESHOOTING.md.template

@@ -44,6 +44,56 @@ Use this guide when a first-run bootstrap or gate check fails. The recovery path
 2. Re-add the remote only if the workflow genuinely needs it.
 3. Prefer the local base branch path when validating first-run behavior.
 
+## Local Slice Validation In A New Repo
+
+### Symptom
+
+- `check-slice` asks for a remote/base branch while the repo is still local-only
+
+### Recovery
+
+1. Run `npx create-quiver check-slice --local <slice.json>` for structural validation.
+2. Before PR readiness, run normal `check-slice <slice.json>` with a local base branch, `--base <branch>`, or a configured remote.
+3. Treat `--local` as a first-use validation mode, not as a replacement for PR checks.
+
+## Context Preparation Overwrites Docs
+
+### Symptom
+
+- `ai prepare-context` wrote generated context docs and you expected only a preview
+
+### Recovery
+
+1. Use `npx create-quiver ai prepare-context --dry-run` first.
+2. Review assumptions, risks, files considered, and omitted paths.
+3. Commit or preserve any manual edits before running write mode.
+4. Write mode is intentionally limited to approved docs/context files and does not touch product code.
+
+## Evidence Contains Sensitive Output
+
+### Symptom
+
+- `evidence run` captured output that may include secrets
+
+### Recovery
+
+1. Treat redaction as best effort, not a secret scanner.
+2. Avoid running commands that intentionally print credentials.
+3. Delete or rewrite the local evidence file before sharing it if sensitive output remains.
+4. Prefer `--max-output <n>` for noisy commands.
+
+## Demo Scaffold Conflict
+
+### Symptom
+
+- `demo create spec-viewer` reports preserved files in the target directory
+
+### Recovery
+
+1. Re-run with `--dry-run` and inspect the planned preserve/create list.
+2. Use `--dir <empty-target>` when you want a clean demo.
+3. Existing files are preserved; Quiver does not overwrite them for the demo.
+
 ## Generated File Conflicts
 
 ### Symptom

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,39 @@ 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>`. Use `--dry-run` first when you want to inspect the planned branch/path without changing Git state.
+2. Inspect lifecycle state with `npx create-quiver ai inspect`, or export it with `npx create-quiver ai export --format json` for dashboards/agents and `--format markdown` for PRs/docs.
+3. 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`.
+4. 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.
+5. 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.
+6. Implement only what the slice declares.
+7. Make one commit for that slice, or let `ai execute-slice --commit` / `ai execute-plan --execute --commit --mode delegated` create it after provider, branch/worktree, scope, and validation pass.
+   - `ai execute-slice` updates `CLOSURE_BRIEF.md`, `EVIDENCE_REPORT.md`, `COMMAND_LOG.md`, `STATUS.md`, and `slice.json` only after the provider changes in-scope files and validation passes.
+8. Validate with `npx create-quiver check-slice <slice.json>` or `npm run quiver:check-slice -- <slice.json>`.
+9. Write evidence. Prefer `npx create-quiver evidence run -- <command>` when you need a compact local Markdown record of validation output.
+10. Repeat for the next slice until the spec is complete.
+11. Open one PR for the spec. Use `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md --ssh-host-alias <alias> ...` first, then add `--create` only after review. Quiver blocks PR creation while slices in that spec remain open.
+12. 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.1",
   "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,39 @@
     "start:slice": "bash tools/scripts/start-slice.sh",
     "cleanup:slice": "bash tools/scripts/cleanup-slice.sh",
     "migrate": "bash tools/scripts/migrate-project.sh",
-    "quiver:plan": "npx create-quiver plan",
-    "quiver:graph": "npx create-quiver graph",
+    "quiver:analyze": "npx create-quiver analyze",
+    "quiver:flow": "npx create-quiver flow",
+    "quiver:prepare": "npx create-quiver prepare",
+    "quiver:plan": "node bin/create-quiver.js plan",
+    "quiver:graph": "node bin/create-quiver.js 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:inspect": "npx create-quiver ai inspect",
+    "quiver:ai:export": "npx create-quiver ai export",
+    "quiver:ai:specs": "npx create-quiver ai specs list",
+    "quiver:ai:slices": "npx create-quiver ai slices list",
+    "quiver:ai:trace": "npx create-quiver ai trace report",
     "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:doctor-fixtures": "node scripts/ci/smoke-doctor-fixtures.js",
     "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.