create-quiver 0.9.1 → 0.12.0

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.

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

@@ -0,0 +1,100 @@
+## Title
+
+Quiver v20 - AI CLI orchestration
+
+## Summary
+
+Adds a spec for a Quiver AI orchestration layer that standardizes local AI CLI usage across planner and executor roles. The work introduces provider runners, token-efficient context packs, phase-gated planning, generated spec/slice/handoff artifacts, execution plans, executor scope enforcement, and GitHub PR preflight with `gh` and SSH validation.
+
+## Scope
+
+- `quiver ai ...` command family
+- Provider adapters for Codex, Claude, and Gemini CLIs
+- Planner/executor roles
+- Context packs and token budget rules
+- Phase gates for criteria, plan, and spec generation
+- Mandatory `slice-00`
+- Spec/slice/handoff/PR body generation
+- Execution plan with parallelization rules
+- Executor scope enforcement
+- `gh` and SSH preflight
+- Documentation, generated scripts, and smoke coverage
+
+## Files
+
+- `specs/quiver-v20-ai-cli-orchestration/SPEC.md`
+- `specs/quiver-v20-ai-cli-orchestration/STATUS.md`
+- `specs/quiver-v20-ai-cli-orchestration/EVIDENCE_REPORT.md`
+- `specs/quiver-v20-ai-cli-orchestration/EXECUTION_PLAN.md`
+- `specs/quiver-v20-ai-cli-orchestration/pr.md`
+- `specs/quiver-v20-ai-cli-orchestration/slices/**`
+
+Future implementation slices are expected to touch CLI source, AI library modules, 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 preflight slices
+- Optional local provider CLIs for manual checks:
+  - `codex`
+  - `claude`
+  - `gemini`
+
+### Worktree Access
+
+Use one worktree for this spec PR. Parallel slices may use temporary slice worktrees, but each slice must land as one commit in this PR branch.
+
+### Run the Project
+
+For documentation-only `slice-00`, validate files and JSON:
+
+```bash
+git diff --check
+find specs/quiver-v20-ai-cli-orchestration -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.
+
+### Use Cases
+
+- Planner onboarding via provider dry-run
+- Planner criteria phase without file writes
+- Planner technical-plan phase without file writes
+- Spec generation after approval
+- Executor slice execution with minimal context
+- Scope violation detection
+- PR preflight with missing and valid `gh`/SSH config
+
+### Technical Verification
+
+- Provider command construction uses argument arrays.
+- Long prompt transport avoids shell string concatenation.
+- Context packs exclude sensitive paths.
+- `slice-00` is mandatory and every later slice declares dependencies.
+- CI uses mocks or dry-run, not real provider auth.
+
+## Evidence
+
+- `node --test tests/**/*.test.js`
+- `npm run smoke:create-quiver`
+- `node scripts/ci/smoke-cross-platform.js`
+- `bash scripts/ci/smoke-init-docs.sh`
+- `git diff --check`
+- Provider behavior covered with mocks and dry-runs; no real provider auth required for CI.
+- GitHub PR preflight covered with fake `gh` in smoke coverage; no real PR is opened in tests.
+
+## Rollback
+
+Revert the spec PR or the affected slice commit. Since each slice maps to one commit, rollback should target the smallest failing slice commit.
+
+## Risks / Notes
+
+- Provider CLI behavior must be validated carefully during implementation.
+- Windows quoting and paths with spaces are a primary regression risk.
+- `gh` auth and SSH identity can point to different accounts; preflight must report that clearly.
+- `docs/GITFLOW_PR_GUIDE.md` is not present in this source repo; this PR followed `docs/GITFLOW_PR_GUIDE.md.template` as the available canonical guide. Generated projects do materialize `docs/GITFLOW_PR_GUIDE.md`.
+- This PR targets `main` because `develop` is behind `main` and would include unrelated historical commits in the diff.

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE BRIEF - slice-00: Spec foundation
+
+## Resumen de lo realizado
+
+Pendiente de completar al cerrar la slice.
+
+## Validacion contra criterios de aceptacion
+
+- [ ] Spec directory creado.
+- [ ] `slice-00` creado.
+- [ ] Todos los slices tienen `slice.json`, `EXECUTION_BRIEF.md` y `CLOSURE_BRIEF.md`.
+- [ ] Todos los `slice.json` parsean.
+- [ ] No se modifico codigo de producto.
+
+## Cambios relevantes
+
+Pendiente.
+
+## Pendientes
+
+Pendiente.
+
+## Riesgos remanentes
+
+Pendiente.
+
+## Recomendaciones futuras
+
+Ejecutar `slice-01` y `slice-02` despues de commitear esta base documental.
+

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,61 @@
+# EXECUTION BRIEF - slice-00: Spec foundation
+
+**Spec:** quiver-v20-ai-cli-orchestration
+**Slice:** slice-00-spec-foundation
+**Tipo:** docs
+
+## Contexto
+
+Esta slice sube al repo la base documental de la spec. Es obligatoria y debe ejecutarse antes de cualquier slice de implementacion. No modifica codigo de producto.
+
+## Objetivo
+
+Crear y validar la estructura completa de spec, slices, handoffs, plan de ejecucion y cuerpo de PR para el trabajo de AI CLI orchestration.
+
+## 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-v20-ai-cli-orchestration/` 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-v20-ai-cli-orchestration/`.
+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 tocar `specs/quiver-v21-cli-output-polish/`.
+- No resolver implementacion en esta slice.
+
+## 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-v20-ai-cli-orchestration/`.
+- [ ] El commit representa solo slice-00.

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-00-spec-foundation/slice.json

@@ -0,0 +1,54 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-20-00",
+  "type": "docs",
+  "title": "Commit AI CLI orchestration spec foundation",
+  "objective": "Create and commit the documentation foundation for the AI CLI orchestration spec before any implementation slice starts.",
+  "description": "Add the spec, status, execution plan, PR body, slice definitions, execution briefs, and closure briefs for the full Quiver v20 AI CLI orchestration work.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "ai-cli-orchestration",
+    "branch_name": "feature/QUIVER-20-ai-cli-orchestration"
+  },
+  "files": [
+    "specs/quiver-v20-ai-cli-orchestration/SPEC.md",
+    "specs/quiver-v20-ai-cli-orchestration/STATUS.md",
+    "specs/quiver-v20-ai-cli-orchestration/EVIDENCE_REPORT.md",
+    "specs/quiver-v20-ai-cli-orchestration/EXECUTION_PLAN.md",
+    "specs/quiver-v20-ai-cli-orchestration/pr.md",
+    "specs/quiver-v20-ai-cli-orchestration/slices/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "slice-00 is the mandatory documentation foundation and must land before every implementation slice.",
+  "must": [
+    "Create SPEC.md with approved requirements, acceptance criteria, scope, risks, and technical plan.",
+    "Create STATUS.md with execution rules and open items.",
+    "Create EVIDENCE_REPORT.md for slice-level evidence tracking.",
+    "Create EXECUTION_PLAN.md with sequential and parallel slice guidance.",
+    "Create pr.md following the repository GitFlow PR structure.",
+    "Create slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md for every planned slice.",
+    "Do not modify product code."
+  ],
+  "not_included": [
+    "Implementing quiver ai commands.",
+    "Changing CLI runtime code.",
+    "Changing package scripts or generated templates."
+  ],
+  "acceptance": [
+    "The spec directory exists under specs/quiver-v20-ai-cli-orchestration.",
+    "slice-00 exists and every later slice depends on it directly or indirectly.",
+    "Every slice has slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "pr.md exists for the spec.",
+    "All slice.json files parse as valid JSON.",
+    "No product code is modified by slice-00."
+  ],
+  "tests": [
+    "git diff --check",
+    "find specs/quiver-v20-ai-cli-orchestration -name 'slice.json' -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;"
+  ],
+  "estimated_hours": 1.5,
+  "status": "ready",
+  "blocked_reason": null
+}

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-01-ai-provider-runner/CLOSURE_BRIEF.md

@@ -0,0 +1,39 @@
+# CLOSURE BRIEF - slice-01: AI provider runner
+
+## Resumen de lo realizado
+
+Se agrego la base del provider runner para `codex`, `claude` y `gemini`, incluyendo transporte de prompt por stdin/temp-file, dry-run, preflight de CLI, timeout y resultados estructurados.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Proveedores `codex`, `claude`, `gemini` soportados.
+- [x] Proveedor invalido falla con mensaje claro.
+- [x] Dry-run no ejecuta procesos.
+- [x] Prompt largo no viaja como shell string unico.
+- [x] Tests no requieren CLIs reales.
+
+## Cambios relevantes
+
+- `src/create-quiver/lib/ai/providers.js`
+- `src/create-quiver/lib/ai/prompt-transport.js`
+- `src/create-quiver/lib/ai/preflight.js`
+- `tests/lib/ai-providers.test.js`
+- `tests/lib/ai-prompt-transport.test.js`
+
+## Pendientes
+
+- Confirmar manualmente opciones reales de ejecucion para cada CLI antes de documentarlas como estables.
+
+## Riesgos remanentes
+
+- `gemini` requiere `--prompt` con valor para entrar en modo headless; se usa un prompt vacio y el contenido real via stdin para evitar argumentos largos.
+- La autenticacion especifica de cada provider queda para una validacion posterior.
+
+## Recomendaciones futuras
+
+Validar manualmente cada CLI real fuera de CI antes de publicar la version.
+
+## Validacion ejecutada
+
+- `node --test tests/lib/ai-providers.test.js tests/lib/ai-prompt-transport.test.js tests/lib/ai-context-packs.test.js tests/lib/ai-safety.test.js`
+- `git diff --check`

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-01-ai-provider-runner/EXECUTION_BRIEF.md

@@ -0,0 +1,63 @@
+# EXECUTION BRIEF - slice-01: AI provider runner
+
+**Spec:** quiver-v20-ai-cli-orchestration
+**Slice:** slice-01-ai-provider-runner
+**Tipo:** feature
+
+## Contexto
+
+Quiver necesita ejecutar prompts mediante CLIs locales de IA sin depender de comandos shell fragiles. Esta slice crea la base reutilizable para Codex, Claude y Gemini.
+
+## Objetivo
+
+Implementar un provider runner mockeable, cross-platform y seguro para prompts largos.
+
+## Alcance
+
+- Agregar providers `codex`, `claude`, `gemini`.
+- Validar CLI instalado.
+- Soportar `--dry-run`.
+- Transportar prompts largos por stdin o archivo temporal segun adapter.
+- Devolver resultados estructurados.
+
+## Criterios de aceptacion
+
+- Proveedor no soportado falla con lista de proveedores validos.
+- Dry-run no ejecuta procesos.
+- No se concatenan strings shell para ejecutar providers.
+- Los tests no requieren CLIs reales.
+- Paths con espacios estan cubiertos.
+
+## Plan tecnico resumido
+
+Crear modulos `providers.js`, `prompt-transport.js` y `preflight.js` bajo `src/create-quiver/lib/ai/`. Usar `spawn`/`execFile` con arrays de argumentos. Permitir inyeccion de runner falso para tests.
+
+## Pasos sugeridos de ejecucion
+
+1. Crear `src/create-quiver/lib/ai/`.
+2. Implementar registry de providers.
+3. Implementar transporte seguro de prompt.
+4. Implementar preflight de CLI.
+5. Agregar tests unitarios.
+6. Validar sintaxis y diff.
+
+## Restricciones
+
+- No agregar comandos publicos `quiver ai` todavia.
+- No invocar providers reales en tests.
+- No requerir auth real de Codex/Claude/Gemini.
+
+## Riesgos
+
+- Diferencias entre CLIs reales.
+- Quoting roto en Windows si se usa shell implicito.
+- Prompts largos que exceden limites de argumentos.
+
+## Checklist de finalizacion
+
+- [ ] Tests unitarios pasan.
+- [ ] Dry-run cubierto.
+- [ ] Unsupported provider cubierto.
+- [ ] Missing CLI cubierto.
+- [ ] No hay shell concatenation.
+

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-01-ai-provider-runner/slice.json

@@ -0,0 +1,55 @@
+{
+  "slice_id": "slice-01-ai-provider-runner",
+  "ticket": "QUIVER-20-01",
+  "type": "feature",
+  "title": "Add AI provider runner and safe prompt transport",
+  "objective": "Add a provider abstraction for Codex, Claude, and Gemini CLIs with dry-run, command validation, and safe long-prompt transport.",
+  "description": "Implement the core provider runner used by future quiver ai commands. The runner must avoid shell string concatenation, support cross-platform argument arrays, validate missing CLIs, and allow mockable dry-run behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "ai-provider-runner",
+    "branch_name": "feature/QUIVER-20-01-ai-provider-runner"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/prompt-transport.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "tests/lib/ai-providers.test.js",
+    "tests/lib/ai-prompt-transport.test.js"
+  ],
+  "depends_on": [
+    "slice-00-spec-foundation"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run after slice-00. It owns provider modules and tests.",
+  "must": [
+    "Support provider ids: codex, claude, gemini.",
+    "Build provider invocations without shell concatenation.",
+    "Support dry-run output that includes provider, command, args, prompt transport, and timeout.",
+    "Validate missing provider CLIs with actionable errors.",
+    "Support prompt transport for long prompts through stdin or temporary files where supported.",
+    "Allow provider execution to be mocked in tests.",
+    "Return structured results with exit code, stdout, stderr, and error metadata."
+  ],
+  "not_included": [
+    "Adding public quiver ai commands.",
+    "Implementing context packs.",
+    "Calling real provider CLIs in CI."
+  ],
+  "acceptance": [
+    "Unsupported provider returns a clear error listing codex, claude, and gemini.",
+    "Dry-run does not invoke a child process.",
+    "Long prompts are not passed as a single shell command string.",
+    "Provider command construction handles paths with spaces.",
+    "Provider tests pass without Codex, Claude, or Gemini installed."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-providers.test.js tests/lib/ai-prompt-transport.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 4,
+  "status": "completed",
+  "blocked_reason": null
+}