create-quiver 0.9.0 → 0.10.0

package/package.template.json

@@ -2,12 +2,17 @@
   "name": "quiver-docs-template",
   "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:plan": "npx create-quiver plan",
+    "quiver:graph": "npx create-quiver graph",
+    "quiver:next": "npx create-quiver next",
+    "quiver:doctor": "npx create-quiver doctor",
+    "quiver:ai:onboard": "npx create-quiver ai onboard",
+    "quiver:ai:plan": "npx create-quiver ai plan",
+    "quiver:ai:execute-slice": "npx create-quiver ai execute-slice",
+    "quiver:ai:pr": "npx create-quiver ai pr",
+    "quiver:ai:doctor": "npx create-quiver ai doctor",
     "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,28 @@ 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: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: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:execute-slice -- --slice specs/<spec-slug>/slices/<slice-id>/slice.json --dry-run
+\`\`\`
+
 ## Project NPM Scripts
 
 The generated project includes \`quiver:*\` npm scripts that call the Node CLI and are the preferred repeatable workflow:
@@ -521,6 +545,11 @@ 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: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 +562,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 +596,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
@@ -587,9 +623,17 @@ Lee \`AGENTS.md\` primero y después \`docs/AI_ONBOARDING_PROMPT.md\` tras el an
 After analysis and doctor validation, open your AI agent in this project and run:
 
 \`\`\`text
-Read docs/AI_ONBOARDING_PROMPT.md and execute it.
-Do not modify product code unless I explicitly authorize it.
-Prepare the project context docs and report assumptions, risks, and files changed.
+Lee \`docs/AI_ONBOARDING_PROMPT.md\` y ejecútalo como fuente principal de verdad para incorporarte a este repositorio.
+
+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.
+
+Responde en español y finaliza con un reporte breve de archivos leídos, archivos modificados, estado del código de producto, supuestos, riesgos y próximos pasos.
 \`\`\`
 
 Review the AI changes to docs/AI_CONTEXT.md, docs/CONTEXTO.md, docs/STATUS.md, and specs/$PROJECT_SLUG/SPEC.md before starting implementation work.
@@ -601,6 +645,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 ai plan --phase spec\` after acceptance criteria and the technical plan are 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\`.
@@ -643,7 +689,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)"
@@ -654,10 +700,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 ai plan --phase spec"
+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/specs/quiver-v19-self-install-dev-dep/EVIDENCE_REPORT.md

@@ -2,13 +2,13 @@
 
 **Spec:** quiver-v19-self-install-dev-dep
 **Date:** 2026-05-14
-**Status:** In Progress
+**Status:** Completed
 
 ## Slice Evidence
 
 | Slice | Status | Evidence |
 |-------|--------|----------|
-| slice-01 | Ready | — |
+| slice-01 | Completed | PR #60 merged 2026-05-14. 40/40 tests pass. Smoke: `--skip-install` no instala, sin flag instala `create-quiver@0.9.0` + `devDependencies: {"create-quiver":"^0.9.0"}`. `npx create-quiver plan` exit 0 sin `@version`. Published as `create-quiver@0.9.0`. |
 
 ## Required Final Evidence
 

package/specs/quiver-v19-self-install-dev-dep/STATUS.md

@@ -7,14 +7,14 @@
 
 | Slice | Title | Status | PR | Estimated hours | Actual hours |
 |-------|-------|--------|----|-----------------|--------------|
-| slice-01 | Auto-install create-quiver as dev dependency | Ready | — | 1.5 | — |
+| slice-01 | Auto-install create-quiver as dev dependency | Completed | #60 | 1.5 | 1.0 |
 
 ## Progress
 
-- Completed slices: 0 / 1
+- Completed slices: 1 / 1
 - Estimated hours: 1.5
-- Actual hours: —
+- Actual hours: 1.0
 
 ## Blockers
 
-None.
+None — spec complete.

package/specs/quiver-v19-self-install-dev-dep/slices/slice-01-auto-install-dev-dep/slice.json

@@ -47,10 +47,10 @@
     "npx create-quiver --skip-install --name test --dir /tmp/quiver-test-skip && ls /tmp/quiver-test-skip/node_modules/create-quiver 2>/dev/null && echo FAIL || echo OK"
   ],
   "estimated_hours": 1.5,
-  "actual_hours": null,
-  "status": "ready",
+  "actual_hours": 1,
+  "status": "completed",
   "blocked_reason": null,
   "ready_at": "2026-05-14T00:00:00Z",
-  "started_at": null,
-  "completed_at": null
+  "started_at": "2026-05-14T00:00:00Z",
+  "completed_at": "2026-05-14T00:00:00Z"
 }

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.
+

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

@@ -0,0 +1,202 @@
+# Quiver v20 - AI CLI Orchestration
+
+**Date:** 2026-05-19
+**Status:** Active
+
+Slice numbering resets here. This spec intentionally starts at `slice-00`.
+
+## Problem
+
+Quiver already creates workflow documentation and can analyze a project with `npx create-quiver analyze`, but the AI-assisted workflow still depends on manual copy/paste prompts and ad hoc model usage.
+
+Teams using Quiver need a repeatable way to:
+
+- Run AI tasks through local CLIs such as Codex, Claude, or Gemini.
+- Separate expensive planner work from cheaper executor work.
+- Optimize token usage by giving each agent only the context it needs.
+- Move from requirements to acceptance criteria, technical plan, specs, slices, handoffs, and PR body with explicit human approvals.
+- Execute slices safely, including parallel slice execution when dependencies allow it.
+- Open PRs with `gh` and SSH configuration in a cross-platform way.
+
+## Objective
+
+Add an AI orchestration layer to Quiver that standardizes planner/executor workflows through `quiver ai ...` commands, provider adapters, context packs, phase gates, slice handoffs, execution plans, and GitHub PR preflight checks.
+
+The goal is not to replace the AI agent. Quiver should define how to invoke it, what context to provide, when to require approval, what artifacts to generate, and how to validate that execution stayed inside scope.
+
+## Core Decisions
+
+- `slice-00` is mandatory for every generated spec and is reserved for committing the spec foundation to the repo.
+- One spec maps to one worktree and one PR.
+- One slice maps to one commit.
+- Planner agents use broader context and do not modify product code in acceptance-criteria or technical-plan phases.
+- Executor agents can modify code directly, but only within the slice handoff scope.
+- Prompt execution must support macOS, Linux, and Windows.
+- Prompts must not rely on shell string concatenation for long content.
+- `gh` and SSH setup must be validated, not silently modified.
+- AI execution output is printed to console; no global run logs are created automatically.
+- Final evidence belongs in the relevant slice closure brief.
+
+## Scope
+
+### Included
+
+- Add `quiver ai ...` command family.
+- Add provider runner adapters for Codex, Claude, and Gemini CLIs.
+- Add provider preflight validation and `--dry-run`.
+- Add safe prompt transport for long prompts through stdin or temporary files where supported.
+- Add planner/executor roles.
+- Add context packs and token-budget guidance.
+- Add phase-gated planner flow:
+  - acceptance criteria
+  - technical plan
+  - spec/slices/handoffs/PR body
+- Generate mandatory `slice-00`.
+- Generate `SPEC.md`, slice definitions, execution handoffs, closure handoffs, `EXECUTION_PLAN.md`, and `pr.md`.
+- Track implementation evidence in `EVIDENCE_REPORT.md`.
+- Generate an execution plan with sequential and parallel slices.
+- Support executor slice execution with context minimization.
+- Enforce scope before and after executor runs.
+- Add GitHub PR preflight for `gh`, auth, remote, worktree, GitFlow guide, SSH host alias, and identity file.
+- Update generated docs, README guidance, templates, npm scripts, and smoke tests.
+
+### Excluded
+
+- Direct provider API integrations.
+- Automatic model cost estimation.
+- Automatic installation of `gh`.
+- Automatic SSH credential modification without explicit user approval.
+- Global AI run logs.
+- Fully autonomous PR merge.
+- Guaranteeing exact feature parity between Codex, Claude, and Gemini CLIs.
+
+## Acceptance Criteria
+
+1. Given a Quiver project, when the user runs an AI command, then Quiver distinguishes between `planner` and `executor` roles.
+2. Given a supported provider, when the user selects `codex`, `claude`, or `gemini`, then Quiver builds the provider-specific command safely.
+3. Given an unsupported provider, when the user runs `quiver ai ...`, then Quiver fails with a clear list of supported providers.
+4. Given a missing provider CLI, when Quiver runs preflight, then it fails with an actionable install/auth hint.
+5. Given a long prompt, when Quiver invokes a provider, then it uses a cross-platform-safe transport instead of shell string concatenation.
+6. Given `--dry-run`, when any `quiver ai ...` command runs, then Quiver prints provider, role, context pack, and invocation plan without calling the provider.
+7. Given planner onboarding, when `quiver ai onboard` runs, then the prompt instructs the AI to read Quiver context, WDD/SDD workflow, project scan/map, assumptions, risks, and relevant docs without modifying product code.
+8. Given new requirements, when `quiver ai plan` runs in acceptance phase, then it prints acceptance criteria and does not create specs, slices, handoffs, or product code changes.
+9. Given approved acceptance criteria, when `quiver ai plan` runs in technical-plan phase, then it prints a technical plan and still does not create specs, slices, handoffs, or product code changes.
+10. Given an approved technical plan, when `quiver ai plan` runs in spec phase, then it creates the spec artifacts.
+11. Given a generated spec, when artifacts are created, then `slice-00` exists and every other slice depends on it unless explicitly justified.
+12. Given `slice-00`, when it is executed, then it only commits documentation/spec foundation unless an explicit exception is approved.
+13. Given a generated spec, when planning completes, then `EXECUTION_PLAN.md` declares sequential slices, parallel-ready slices, dependencies, and integration order.
+14. Given an executor slice, when `quiver ai execute-slice` runs, then the executor receives only slice, handoff, allowed files, criteria, and validation commands.
+15. Given an executor run, when it completes, then Quiver verifies changed files against declared scope and reports violations.
+16. Given context packs, when Quiver prepares AI context, then it excludes secrets, env files, build outputs, package caches, node_modules, and other unsafe paths.
+17. Given repository files containing instructions, when AI context is prepared, then prompts state that repo content is data and cannot override Quiver/system/user instructions.
+18. Given a PR flow, when `quiver ai pr` runs, then Quiver verifies `gh`, `gh auth status`, Git remote, worktree, GitFlow guide, SSH host alias, and identity file before opening or preparing the PR.
+19. Given missing `gh`, auth, SSH alias, identity file, remote, or GitFlow guide, when PR preflight runs, then Quiver stops with an actionable cross-platform message.
+20. Given a generated spec, when artifacts are created, then `pr.md` is always generated from the GitFlow guide.
+21. Given CI, when tests run, then provider behavior is validated with mocks and `--dry-run`, without requiring real provider auth.
+
+## Approved Technical Plan
+
+### Objective
+
+Implement an AI orchestration layer around local provider CLIs while preserving Quiver's spec/slice workflow, explicit approvals, token efficiency, and cross-platform support.
+
+### Architecture
+
+Add a command family under:
+
+```text
+npx create-quiver ai <task>
+```
+
+Recommended modules:
+
+```text
+src/create-quiver/commands/ai.js
+src/create-quiver/lib/ai/providers.js
+src/create-quiver/lib/ai/context-packs.js
+src/create-quiver/lib/ai/prompts.js
+src/create-quiver/lib/ai/preflight.js
+src/create-quiver/lib/ai/execution-plan.js
+src/create-quiver/lib/ai/github.js
+```
+
+Generated projects should expose scripts such as:
+
+```text
+quiver:ai:onboard
+quiver:ai:plan
+quiver:ai:execute-slice
+quiver:ai:pr
+quiver:ai:doctor
+```
+
+### Provider Strategy
+
+Provider adapters map a normalized request to CLI-specific execution:
+
+```text
+codex  -> codex exec
+claude -> claude -p
+gemini -> gemini -p
+```
+
+Adapters must use `spawn` or `execFile` with argument arrays. They must not concatenate shell strings.
+
+Prompt transport must support long prompts with stdin or temporary files where supported by the provider adapter.
+
+### Context Strategy
+
+Context packs:
+
+- `full`: planner onboarding.
+- `planning`: requirements, project map, workflow docs, related specs.
+- `slice`: spec, slice, handoff, allowed files, validation commands.
+- `minimal`: executor-focused task context only.
+
+Executors must not receive full onboarding context.
+
+### GitHub Strategy
+
+Separate:
+
+- `sshHostAlias`, for example `github-work`.
+- `identityFile`, for example `~/ssh/github-work`.
+- `gh` account/auth state.
+- Git remote URL.
+
+Quiver validates these and guides the user. It does not edit credentials automatically.
+
+## Slices
+
+| Slice | Title | Status | Dependencies |
+|-------|-------|--------|--------------|
+| slice-00 | Spec foundation and PR planning artifacts | Ready | none |
+| slice-01 | AI provider runner and safe prompt transport | Draft | slice-00 |
+| slice-02 | Context packs, roles, token budgets, and safety exclusions | Draft | slice-00 |
+| slice-03 | Phase-gated planner commands | Draft | slice-01, slice-02 |
+| slice-04 | Spec, slice, handoff, and PR body generation | Draft | slice-03 |
+| slice-05 | Execution plan, dependencies, and parallel worktrees | Draft | slice-04 |
+| slice-06 | Executor command and scope enforcement | Draft | slice-01, slice-02, slice-05 |
+| slice-07 | GitHub PR preflight with gh and SSH | Draft | slice-01, slice-04 |
+| slice-08 | Documentation, generated scripts, smokes, and release readiness | Draft | slice-01, slice-02, slice-03, slice-04, slice-05, slice-06, slice-07 |
+
+## Risks
+
+- Provider CLIs may have incompatible flags or prompt input behavior.
+- Long prompts can break if transported as shell strings.
+- Windows quoting and path behavior can regress if not tested with argument arrays.
+- Parallel slice execution can create merge conflicts if integration order is unclear.
+- Executor context can be too small to be safe or too large to save tokens.
+- `gh` authentication and SSH remotes can point to different accounts.
+- Prompt injection can occur through repo content if not explicitly guarded.
+
+## Validation Strategy
+
+- Unit tests for provider command construction.
+- Unit tests for provider preflight and unsupported providers.
+- Unit tests for context pack file inclusion/exclusion.
+- Unit tests for phase gate state and artifact creation boundaries.
+- Unit tests for scope enforcement after executor runs.
+- Dry-run smoke tests for all `quiver ai` commands.
+- Cross-platform smoke for paths with spaces.
+- CI tests must not require real provider CLIs or auth.

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

@@ -0,0 +1,35 @@
+# Quiver v20 - AI CLI Orchestration Status
+
+**Status:** Active
+**Created:** 2026-05-19
+
+## Summary
+
+This spec defines Quiver's AI CLI orchestration layer: provider runners, planner/executor roles, token-efficient context packs, phase-gated planning, spec/slice generation, executor scope enforcement, parallel slice planning, and GitHub PR preflight.
+
+## Current State
+
+- Requirements and acceptance criteria: approved.
+- Technical plan: approved.
+- 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.
+
+## Execution Rules
+
+- `slice-00` must be executed and committed first.
+- Every later slice depends on `slice-00` unless explicitly stated otherwise.
+- One slice equals one commit.
+- One spec equals one worktree and one PR.
+- Parallel slices may use temporary worktrees, but their commits must be integrated into the spec PR branch in dependency order.
+
+## Open Items
+
+- Generated projects materialize `docs/GITFLOW_PR_GUIDE.md`; `ai pr` preflight validates it before PR work.