create-quiver 0.9.1 → 0.12.0

package/docs/STANDARD.md.template

@@ -25,7 +25,7 @@ This is the default context pack for everyday AI work.
 
 ## Workflow Overview
 
-- Onboarding starts from `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md`.
+- Onboarding starts from `docs/PROJECT_MAP.md`; use `.quiver/scans/PROJECT_SCAN.json` only when raw analyzer data is needed.
 - Implementation starts from `specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json`.
 - Review starts from `git diff` and the slice scope.
 - Debugging starts from the command, exit code, first relevant error, and stacktrace.

package/docs/STATUS.md.template

@@ -24,3 +24,4 @@ This page tracks progress, blockers, and the current slice. Stack and command de
 
 - Update this file after each completed slice.
 - Keep stack and command changes in `docs/PROJECT_MAP.md`, not here.
+- Record uncertainty with `TODO`, `Assumption`, or `Pending confirmation` instead of treating it as product debt.

package/docs/SUPPORT_MATRIX.md.template

@@ -9,13 +9,15 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 
 | Area | Supported | Notes |
 |------|-----------|-------|
-| Operating systems | macOS, Linux, and Windows | Windows native support is verified only when the cross-platform CI matrix is green. |
+| Operating systems | macOS, Linux, and Windows | Primary runtime is the Node CLI and generated `quiver:*` npm scripts. |
 | Shells | Terminal, bash-compatible shells, PowerShell, and CMD | Bash is a legacy compatibility path, not a required runtime dependency. |
 | Git | Git 2.40+ | Must support worktrees and standard branch refs on every supported OS. |
 | Node.js | Node 22.x LTS | Required on every supported OS. |
 | Base branches | `develop` or `main` | Local base branches are preferred; `origin` is optional. |
 | Worktree state | Clean worktree | Slice execution and PR checks expect no unrelated local changes. |
 | Path handling | Canonical filesystem paths | Use the physical path to the repo and slice files, not a symlinked alias. |
+| AI providers | Local `codex`, `claude`, or `gemini` CLI | Required only for non-dry-run AI commands. Dry-run smokes do not require provider auth. |
+| GitHub PR preflight | `gh` plus user-managed SSH config | Quiver validates `gh`, auth, host alias, identity file, branch, worktree, and `docs/GITFLOW_PR_GUIDE.md`; it does not install or edit credentials. |
 
 ## Cross-Platform Authoring Rules
 
@@ -25,6 +27,8 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 - `--json` is the primary contract; human output is courtesy and may vary.
 - Colors are TTY-aware and suppressed with `NO_COLOR`; Unicode is opt-in unless UTF-8 is available.
 - Optional external tools such as `gh` and `graphviz` should be probed and skipped gracefully if missing.
+- Long AI prompts must be sent through stdin or another safe transport, never shell string concatenation.
+- `sshHostAlias` and `identityFile` are separate values. The alias is the host entry used by Git; the identity file is the key path to validate.
 
 ## Remote Modes
 
@@ -36,7 +40,7 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 
 ## What This Means
 
-- You can bootstrap and run Quiver on macOS, Linux, and Windows native shells once the runtime slices land and the CI matrix is green.
+- You can bootstrap and run Quiver on macOS, Linux, and Windows native shells with the Node CLI.
 - Windows native usage should target PowerShell or CMD instead of Bash.
 - Quiver should not auto-install Bash, Git Bash, MSYS2, or WSL.
 - You do not need a remote to begin work if a local base branch already exists.

package/docs/TROUBLESHOOTING.md.template

@@ -44,11 +44,61 @@ 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
 
-- `init-docs.sh` or a slice bootstrap stops because a file already exists
+- `npx create-quiver init` or a slice bootstrap stops because a file already exists
 - The generated project has a partially initialized docs tree
 
 ### Recovery
@@ -82,3 +132,31 @@ Use this guide when a first-run bootstrap or gate check fails. The recovery path
 2. If you are using an intermediate build and need a temporary bridge, use WSL2 or Git Bash manually.
 3. Do not expect Quiver to install Bash, WSL, or MSYS2 for you.
 4. Re-run the command after the cross-platform support slices are merged and the CI matrix is green.
+
+## AI Provider CLI Missing
+
+### Symptom
+
+- `quiver:ai:onboard`, `quiver:ai:plan`, or `quiver:ai:execute-slice` fails before calling the model
+- The error mentions a missing `codex`, `claude`, or `gemini` command
+
+### Recovery
+
+1. Re-run the command with `--dry-run` to validate role, context pack, prompt transport, and paths without provider auth.
+2. Install or authenticate the selected provider CLI outside Quiver.
+3. Use `--provider codex`, `--provider claude`, or `--provider gemini` explicitly if your default is unclear.
+4. Re-run the command from a clean worktree when using `ai execute-slice`.
+
+## GitHub PR Preflight Failure
+
+### Symptom
+
+- `quiver:ai:pr` or `quiver:ai:doctor` reports missing `gh`, failed `gh auth status`, missing `docs/GITFLOW_PR_GUIDE.md`, unsafe branch, dirty worktree, or missing SSH identity file
+
+### Recovery
+
+1. Install `gh` for your OS and run `gh auth login`.
+2. Confirm `docs/GITFLOW_PR_GUIDE.md` exists in the project.
+3. Commit or stash unrelated changes before PR preflight.
+4. Pass the SSH host alias and key path separately, for example `--ssh-host-alias github-work --identity-file ~/.ssh/github-work`.
+5. Re-run with `--dry-run`; Quiver validates the setup but does not open a PR in dry-run mode.

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.
@@ -21,7 +21,7 @@ This document is the canonical implementation workflow for the project.
 
 ## Mode-Aware Context Selection
 
-- **Onboarding:** read `PROJECT_SCAN.json`, `PROJECT_MAP.md`, `AI_CONTEXT.md`, and `AI_ONBOARDING_PROMPT.md` before source files.
+- **Onboarding:** read `docs/PROJECT_MAP.md`, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before source files. Use `.quiver/scans/PROJECT_SCAN.json` only when the visible project map is not enough.
 - **Implementation:** read `docs/ai/ACTIVE_SLICE.md` first when it exists; otherwise read `slice.json`, declared files, nearby tests, and only then adjacent source.
 - **Handoff:** read `specs/<project-slug>/HANDOFF.md` when the work was explicitly transferred through a handoff artifact.
 - Validate a received handoff with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md` before starting execution.
@@ -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.9.1",
+  "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,12 +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,13 +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:plan": "npx create-quiver plan",
-  "quiver:graph": "npx create-quiver graph",
-  "quiver:next": "npx create-quiver next",
-  "quiver:doctor": "npx create-quiver doctor",
+    "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/check-pr-readiness.sh

@@ -39,7 +39,6 @@ slice_input="$1"
 command -v git >/dev/null 2>&1 || fail "git no esta disponible en PATH."
 command -v node >/dev/null 2>&1 || fail "node no esta disponible en PATH."
 
-repo_root="$(git rev-parse --show-toplevel)"
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 [[ -f "$slice_input" ]] || fail "No existe el slice '$slice_input'."
@@ -127,6 +126,7 @@ pass "Al menos un caso de uso documentado."
 grep -Eq 'git revert ' "$pr_abs" || fail "Rollback debe incluir al menos un comando git revert."
 pass "Rollback incluye comando git revert."
 
+# shellcheck disable=SC2016
 grep -Eiq '^\s*-\s*`manual review`$|^\s*-\s*`visual check`$|^\s*-\s*`screen test`$|^\s*-\s*`visual validation`$' "$pr_abs" && fail "How to Test cannot rely only on generic phrases."
 
 node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" "$slice_abs" >/dev/null

package/scripts/check-scope.sh

@@ -59,7 +59,6 @@ done
 command -v git >/dev/null 2>&1 || fail "git no esta disponible en PATH."
 command -v node >/dev/null 2>&1 || fail "node no esta disponible en PATH."
 
-repo_root="$(git rev-parse --show-toplevel)"
 [[ -f "$slice_input" ]] || fail "No existe el slice '$slice_input'."
 slice_abs="$(cd "$(dirname "$slice_input")" && pwd)/$(basename "$slice_input")"
 

package/scripts/check-slice-readiness.sh

@@ -77,7 +77,7 @@ repo_root="$(git rev-parse --show-toplevel)"
 [[ -f "$slice_input" ]] || fail "No existe el slice '$slice_input'."
 
 slice_abs="$(cd "$(dirname "$slice_input")" && pwd)/$(basename "$slice_input")"
-slice_rel="${slice_abs#$repo_root/}"
+slice_rel="${slice_abs#"$repo_root"/}"
 
 slice_meta=()
 while IFS= read -r line; do
@@ -143,11 +143,8 @@ NODE
 
 [[ ${#slice_meta[@]} -eq 10 ]] || fail "No se pudo leer la metadata del slice."
 
-slice_id="${slice_meta[0]}"
-ticket="${slice_meta[1]}"
 branch_name="${slice_meta[2]}"
 slice_status="${slice_meta[3]}"
-is_baseline="${slice_meta[4]}"
 spec_dir_rel="${slice_meta[5]}"
 files_b64="${slice_meta[6]}"
 actual_hours="${slice_meta[7]}"
@@ -161,6 +158,8 @@ pass "El spec local tiene SPEC.md, STATUS.md y EVIDENCE_REPORT.md."
 
 if git cat-file -e "origin/develop:$slice_rel" 2>/dev/null; then
   pass "El slice ya existe en origin/develop (PR base documental mergeado)."
+elif git cat-file -e "develop:$slice_rel" 2>/dev/null; then
+  pass "El slice ya existe en develop local (modo sin origin)."
 else
   if [[ "$gate" == "validation" ]]; then
     warn "El slice no existe todavia en origin/develop. El PR base documental sigue pendiente de merge. Podes abrir el PR del slice igual — el humano mergea en orden."

package/scripts/init-docs.sh

@@ -3,6 +3,7 @@
 # Script de Inicialización de Documentación
 # Uso: ./init-docs.sh "Nombre del Proyecto"
 
+# shellcheck disable=SC2016
 set -e
 
 # Colores para output
@@ -62,6 +63,7 @@ CHECK_SCOPE_COMMAND="npx create-quiver check-scope <slice.json>"
 REFRESH_ACTIVE_SLICES_COMMAND="npx create-quiver refresh-active-slices"
 
 print_info "Inicializando documentación para: $PROJECT_NAME"
+print_warning "Este script es compatibilidad legacy. Para el flujo AI-first default usá: npx create-quiver init --name \"$PROJECT_NAME\""
 print_info "Project slug: $PROJECT_SLUG"
 print_info "Fecha: $CURRENT_DATE"
 
@@ -92,7 +94,7 @@ copy_template() {
     
     if [ -f "$src" ]; then
         # Remover .template del nombre si existe
-        dest=$(echo "$dest" | sed 's/\.template$//')
+        dest="${dest%.template}"
 
         if [ "$MIGRATE_MODE" = "1" ] && [ -f "$dest" ]; then
             print_info "Saltado: $dest ya existe"
@@ -511,6 +513,34 @@ npm install --save-dev create-quiver
 
 If you need to target another directory from outside the project, pass \`--dir\` explicitly. Quote paths that contain spaces.
 
+## AI-First Workflow
+
+Quiver is designed for an AI-first workflow: a planner agent reads the project context and prepares acceptance criteria, technical plans, specs, slices, and PR notes; executor agents then work one approved slice at a time with minimal context.
+
+Start with dry-runs so you can inspect the provider, role, context pack, and invocation before spending model tokens:
+
+\`\`\`bash
+npm run quiver:ai:onboard -- --dry-run
+npm run quiver:ai:plan -- --phase acceptance --input requirements.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
+\`\`\`
+
+Remove \`--dry-run\` only after the phase output is approved and the local provider CLI is ready.
+
+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
 
 The generated project includes \`quiver:*\` npm scripts that call the Node CLI and are the preferred repeatable workflow:
@@ -521,6 +551,12 @@ npm run quiver:plan
 npm run quiver:graph
 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
 npm run quiver:migrate
 npm run quiver:start-slice -- specs/$PROJECT_SLUG/slices/slice-01/slice.json
 npm run quiver:check-slice -- specs/$PROJECT_SLUG/slices/slice-01/slice.json
@@ -533,6 +569,7 @@ npm run quiver:refresh-active-slices
 
 The \`quiver:graph\` script prints the tree view by default; use \`npx create-quiver graph --format mermaid\` for PR-ready Markdown and \`--format dot\` when you want Graphviz source.
 The \`quiver:next\` script points to the next ready slice and can auto-start it behind a confirmation prompt.
+The \`quiver:ai:*\` scripts standardize planner/executor AI flows. Use dry-run first: onboarding and planning dry-runs do not require provider auth, while \`quiver:ai:pr -- --dry-run\` validates \`gh\`, GitFlow docs, branch/worktree state, and SSH inputs without creating a PR.
 Use \`npx create-quiver next --all-ready\` when you want the full ready level instead of a single suggestion.
 The legacy Bash wrappers remain in \`tools/scripts/\` for compatibility, but new project-level automation should prefer the \`quiver:*\` scripts and the direct \`npx create-quiver ...\` commands below.
 \`npm run check-handoff -- specs/$PROJECT_SLUG/HANDOFF.md\` is available as a legacy-friendly alias for the handoff validator.
@@ -566,6 +603,12 @@ $GRAPH_COMMAND --format mermaid
 $GRAPH_COMMAND --format dot
 \`\`\`
 
+If the project never ran Quiver initialization before, do not use \`migrate\` as bootstrap. Run:
+
+\`\`\`bash
+npx create-quiver init --name "Project Name"
+\`\`\`
+
 If your team prefers a pinned local dependency, update the package first and then run the same flow:
 
 \`\`\`bash
@@ -591,6 +634,8 @@ Lee \`docs/AI_ONBOARDING_PROMPT.md\` y ejecútalo como fuente principal de verda
 
 Actúa como asistente de onboarding de IA. Prepara el contexto del proyecto para trabajar de forma segura con el workflow documentado, specs y slices.
 
+Usa el rol planner para onboarding, criterios de aceptación, plan técnico y generación de specs/slices. Usa el rol executor solo cuando exista un slice aprobado y debas ejecutar su handoff con contexto mínimo.
+
 No modifiques código de producto salvo autorización explícita. Puedes crear o actualizar documentación de contexto si el onboarding lo requiere.
 
 Usa solo la documentación del repositorio como fuente de verdad. Si encuentras información faltante, ambigua o contradictoria, documenta el supuesto, el riesgo y continúa por el camino más seguro.
@@ -607,6 +652,8 @@ 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 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.
 3. Review the plan with \`$PLAN_COMMAND\` or \`npm run quiver:plan\`.
@@ -649,7 +696,7 @@ fi
 echo ""
 print_success "¡Inicialización completada!"
 echo ""
-echo "📁 Estructura creada:"
+echo "📁 Estructura legacy/full creada:"
 echo "   docs/                    ← Documentación core"
 echo "   docs/ai/                 ← Configuración de IA"
 echo "   docs/tools/              ← Herramientas (vacío)"
@@ -660,10 +707,10 @@ 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. Crear el primer directorio de slice en specs/$PROJECT_SLUG/slices/[slice-id]/"
-echo "   5. Actualizar docs/SEARCH.md con temas específicos"
+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:"
-echo "   - Ver docs-template/TEMPLATE.md para guía de personalización"
-echo "   - Ver docs-template/README.md para documentación del template"
+echo "   - Ver README.md y README_FOR_AI.md para el flujo AI-first actual"
+echo "   - docs-template/ aplica solo a compatibilidad legacy o templates exportados"
 echo ""

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-v20-ai-cli-orchestration/EVIDENCE_REPORT.md

@@ -0,0 +1,23 @@
+# Evidence Report - Quiver v20 AI CLI Orchestration
+
+## Status
+
+Slice 08 implemented.
+
+## Slice Evidence
+
+| Slice | Evidence |
+|-------|----------|
+| slice-00 | Spec foundation files created and JSON validation completed. |
+| slice-01 | Implemented provider runner, prompt transport, provider preflight, dry-run, timeout handling, and provider tests. |
+| slice-02 | Implemented AI roles, context packs, token-budget hints, safety exclusions, prompt-injection guard text, and tests. |
+| slice-03 | Implemented phase-gated planner commands, dry-run display, phase blocking for spec, and command tests. |
+| slice-04 | Implemented spec-phase generation, safe collision handling, JSON validation, and command/tests coverage. |
+| slice-05 | Implemented execution plan graphing, slice-00 foundation barriers, ready levels, temporary worktree strategy, and cycle/missing dependency diagnostics. |
+| slice-06 | Implemented `ai execute-slice`, executor prompts, dry-run, provider failure handling, pre/post diff capture, clean-worktree guard, and scope enforcement tests. |
+| slice-07 | Implemented GitHub PR preflight, gh auth checks, worktree/branch validation, GitFlow guide checks, SSH identity handling, and CLI/tests coverage. |
+| slice-08 | Updated README, AI onboarding/commands/support/troubleshooting/GitFlow templates, generated npm scripts, init docs, doctor script warnings, and dry-run smoke coverage. |
+
+## Final Validation
+
+Validated for slice-08 with `node --test tests/**/*.test.js`, `npm run smoke:create-quiver`, `node scripts/ci/smoke-cross-platform.js`, package JSON parsing, shell/Node syntax checks, and `git diff --check`.

package/specs/quiver-v20-ai-cli-orchestration/EXECUTION_PLAN.md

@@ -0,0 +1,57 @@
+# Execution Plan - Quiver v20 AI CLI Orchestration
+
+## Rule
+
+`slice-00` is mandatory and must be committed first. It establishes the spec foundation in the repo.
+
+## Sequential Foundation
+
+1. `slice-00-spec-foundation`
+   - Commit the spec, slice definitions, handoffs, execution plan, and PR body.
+
+2. `slice-01-ai-provider-runner`
+   - Build the provider abstraction and safe prompt transport.
+
+3. `slice-02-context-packs-token-budget`
+   - Can run after `slice-00`.
+   - Can run in parallel with `slice-01` only if it does not modify provider-runner files.
+
+4. `slice-03-ai-phase-gated-planner`
+   - Requires `slice-01` and `slice-02`.
+
+5. `slice-04-spec-slice-handoff-pr-generation`
+   - Requires `slice-03`.
+
+## Parallelizable Work
+
+After `slice-04`, these can be developed in parallel if each uses a separate worktree and respects declared files:
+
+- `slice-05-execution-plan-parallel-worktrees`
+- `slice-07-github-pr-preflight`
+
+After `slice-05`, this can start:
+
+- `slice-06-ai-execute-slice-scope-enforcement`
+
+## Final Integration
+
+`slice-08-docs-smokes-release-readiness` must run last because it updates docs, generated scripts, templates, and smoke coverage across the completed feature.
+
+## Suggested Commit Order
+
+1. `docs(spec): add ai cli orchestration spec foundation`
+2. `feat(ai): add provider runner and safe prompt transport`
+3. `feat(ai): add context packs and token budgets`
+4. `feat(ai): add phase gated planner commands`
+5. `feat(ai): generate spec slices handoffs and pr body`
+6. `feat(ai): add slice execution plan and parallel worktree support`
+7. `feat(ai): execute slices with scope enforcement`
+8. `feat(ai): add github pr preflight`
+9. `docs(ai): document orchestration workflow and add smokes`
+
+## Integration Notes
+
+- Do not merge parallel slice outputs before their dependencies are committed.
+- If two slices touch the same template, integrate the earlier dependency first and rebase the later worktree.
+- Keep provider tests mocked. Real provider CLIs are optional local checks only.
+