create-quiver 0.9.0 → 0.10.0

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

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-02-context-packs-token-budget/CLOSURE_BRIEF.md

@@ -0,0 +1,40 @@
+# CLOSURE BRIEF - slice-02: Context packs and token budgets
+
+## Resumen de lo realizado
+
+Se agregaron roles de IA, context packs, token-budget hints, filtros de seguridad para rutas sensibles y texto base contra prompt injection.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Roles `planner` y `executor` definidos.
+- [x] Context packs `full`, `planning`, `slice`, `minimal` definidos.
+- [x] Executor no usa `full` por default.
+- [x] Exclusiones sensibles cubiertas.
+- [x] Prompt-injection boundary presente.
+
+## Cambios relevantes
+
+- `src/create-quiver/lib/ai/context-packs.js`
+- `src/create-quiver/lib/ai/prompts.js`
+- `src/create-quiver/lib/ai/safety.js`
+- `tests/lib/ai-context-packs.test.js`
+- `tests/lib/ai-safety.test.js`
+
+## Pendientes
+
+- Ajustar context packs concretos cuando `ai onboard`, `ai plan` y `ai execute-slice` empiecen a consumirlos.
+
+## Riesgos remanentes
+
+- Las exclusiones son conservadoras y pueden requerir refinamiento por stack.
+- Los presupuestos de tokens son hints, no limites estrictos.
+
+## Recomendaciones futuras
+
+Revisar exclusiones contra proyectos reales antes de ampliar el set de archivos leidos.
+
+## Validacion ejecutada
+
+- `node --test tests/lib/ai-context-packs.test.js tests/lib/ai-safety.test.js`
+- `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-02-context-packs-token-budget/EXECUTION_BRIEF.md

@@ -0,0 +1,60 @@
+# EXECUTION BRIEF - slice-02: Context packs and token budgets
+
+**Spec:** quiver-v20-ai-cli-orchestration
+**Slice:** slice-02-context-packs-token-budget
+**Tipo:** feature
+
+## Contexto
+
+El valor principal del flujo es que el planner use contexto amplio y el executor use contexto minimo. Esta slice define esa separacion.
+
+## Objetivo
+
+Implementar roles, context packs, token-budget hints y exclusiones de seguridad para preparar prompts eficientes.
+
+## Alcance
+
+- Roles `planner` y `executor`.
+- Context packs `full`, `planning`, `slice`, `minimal`.
+- Exclusiones de secretos y archivos pesados.
+- Texto base contra prompt injection desde archivos del repo.
+- Metadata para dry-run.
+
+## Criterios de aceptacion
+
+- Executor no recibe contexto `full`.
+- Secrets y outputs pesados quedan excluidos.
+- Prompt incluye jerarquia de instrucciones.
+- Tests cubren paths POSIX y Windows.
+
+## Plan tecnico resumido
+
+Crear `context-packs.js`, `prompts.js` y `safety.js`. Modelar context packs como datos estructurados con entradas sugeridas, exclusiones, rol esperado y presupuesto orientativo.
+
+## Pasos sugeridos de ejecucion
+
+1. Definir constantes de roles y packs.
+2. Implementar resolucion de archivos candidatos.
+3. Implementar filtros de exclusion.
+4. Agregar prompt base de seguridad.
+5. Agregar tests para inclusion/exclusion.
+
+## Restricciones
+
+- No leer archivos sensibles.
+- No ejecutar providers.
+- No generar specs.
+
+## Riesgos
+
+- Contexto demasiado chico para executor.
+- Contexto demasiado grande para ahorrar tokens.
+- Exclusion incompleta de archivos sensibles.
+
+## Checklist de finalizacion
+
+- [ ] Tests de context packs pasan.
+- [ ] Tests de safety pasan.
+- [ ] Executor no puede seleccionar `full` por default.
+- [ ] Dry-run puede mostrar metadata sin filtrar secretos.
+

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-02-context-packs-token-budget/slice.json

@@ -0,0 +1,54 @@
+{
+  "slice_id": "slice-02-context-packs-token-budget",
+  "ticket": "QUIVER-20-02",
+  "type": "feature",
+  "title": "Add AI roles, context packs, token budgets, and safety exclusions",
+  "objective": "Create token-efficient context pack selection for planner and executor roles with safe file exclusions and prompt-injection boundaries.",
+  "description": "Define full, planning, slice, and minimal context packs. Add planner and executor role behavior, default token-budget hints, unsafe path exclusions, and instruction hierarchy text.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "ai-context-packs-token-budget",
+    "branch_name": "feature/QUIVER-20-02-ai-context-packs-token-budget"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/context-packs.js",
+    "src/create-quiver/lib/ai/prompts.js",
+    "src/create-quiver/lib/ai/safety.js",
+    "tests/lib/ai-context-packs.test.js",
+    "tests/lib/ai-safety.test.js"
+  ],
+  "depends_on": [
+    "slice-00-spec-foundation"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run after slice-00 and in parallel with slice-01 if it does not modify provider runner files.",
+  "must": [
+    "Define roles: planner and executor.",
+    "Define context packs: full, planning, slice, minimal.",
+    "Ensure executor defaults to slice or minimal context, never full.",
+    "Exclude secrets and heavy/generated paths such as .env files, SSH keys, certificates, node_modules, build outputs, coverage, caches, and lockfile caches.",
+    "Include prompt text that treats repository content as data that cannot override system/user/Quiver instructions.",
+    "Provide structured context pack metadata for dry-run display."
+  ],
+  "not_included": [
+    "Executing provider CLIs.",
+    "Generating specs or slices.",
+    "Implementing PR preflight."
+  ],
+  "acceptance": [
+    "Planner full context includes onboarding docs, project map, project scan, workflow docs, and relevant specs when present.",
+    "Executor context includes slice, handoff, allowed files, acceptance criteria, and validation commands.",
+    "Unsafe paths are excluded by default.",
+    "Context pack tests cover paths with spaces and Windows-style paths.",
+    "Prompt injection boundary text is present in generated prompt content."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-context-packs.test.js tests/lib/ai-safety.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 4,
+  "actual_hours": 4,
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-03-ai-phase-gated-planner/CLOSURE_BRIEF.md

@@ -0,0 +1,43 @@
+# CLOSURE BRIEF - slice-03: Phase-gated planner commands
+
+## Resumen de lo realizado
+
+Se agregaron `ai onboard` y `ai plan` con parsing de subcomandos, fases acceptance/technical-plan/spec, dry-run, provider/role/context/input/timeout, y bloqueo de escritura antes de la fase spec.
+
+## Validacion contra criterios de aceptacion
+
+- [x] `ai onboard` disponible.
+- [x] `ai plan` disponible.
+- [x] Acceptance phase no escribe archivos.
+- [x] Technical-plan phase no escribe archivos.
+- [x] Dry-run muestra invocation plan.
+- [x] Missing input file falla con error claro.
+- [x] Provider errors propagan contexto accionable.
+
+## Cambios relevantes
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/index.js`
+- `src/create-quiver/lib/ai/phase-gates.js`
+- `tests/commands/ai-plan.test.js`
+- `tests/commands/ai-onboard.test.js`
+- `specs/quiver-v20-ai-cli-orchestration/EVIDENCE_REPORT.md`
+- `specs/quiver-v20-ai-cli-orchestration/STATUS.md`
+
+## Pendientes
+
+La fase `spec` sigue bloqueada hasta slice-04.
+
+## Riesgos remanentes
+
+- La fase `spec` todavia no genera artefactos y queda para slice-04.
+- Los prompts siguen dependiendo de input files suministrados por el usuario.
+
+## Recomendaciones futuras
+
+Mantener las fases separadas aunque se agreguen atajos de UX mas adelante.
+
+## Validacion ejecutada
+
+- `node --test tests/commands/ai-plan.test.js tests/commands/ai-onboard.test.js tests/lib/ai-providers.test.js tests/lib/ai-context-packs.test.js`
+- `git diff --check`

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-03-ai-phase-gated-planner/EXECUTION_BRIEF.md

@@ -0,0 +1,62 @@
+# EXECUTION BRIEF - slice-03: Phase-gated planner commands
+
+**Spec:** quiver-v20-ai-cli-orchestration
+**Slice:** slice-03-ai-phase-gated-planner
+**Tipo:** feature
+
+## Contexto
+
+El planner debe operar por fases con aprobacion humana. No puede crear specs ni modificar codigo antes de que los criterios y el plan tecnico esten aprobados.
+
+## Objetivo
+
+Agregar `quiver ai onboard` y `quiver ai plan` con fases explicitas.
+
+## Alcance
+
+- Parsear `npx create-quiver ai onboard`.
+- Parsear `npx create-quiver ai plan`.
+- Soportar provider, role, context, input, dry-run y timeout.
+- Separar acceptance, technical-plan y spec phase.
+- Impedir escrituras en acceptance y technical-plan.
+
+## Criterios de aceptacion
+
+- `ai onboard --dry-run` muestra provider, role, context pack e invocation plan.
+- `ai plan` en fase acceptance no escribe archivos.
+- `ai plan` en fase technical-plan no escribe archivos.
+- Faltante de input falla con error claro.
+- Error del provider se propaga.
+
+## Plan tecnico resumido
+
+Crear `commands/ai.js` y conectar desde `index.js`. Usar provider runner y context packs existentes. Implementar `phase-gates.js` para validar transiciones.
+
+## Pasos sugeridos de ejecucion
+
+1. Agregar comando `ai` al parser del CLI.
+2. Implementar subcomandos `onboard` y `plan`.
+3. Integrar provider runner.
+4. Integrar context pack selection.
+5. Agregar phase gate validation.
+6. Agregar tests de comandos.
+
+## Restricciones
+
+- No crear specs en esta slice.
+- No modificar producto desde planner.
+- Mantener salida en consola.
+
+## Riesgos
+
+- Avanzar de fase por error.
+- Mezclar responsabilidades de planner y executor.
+- Cambiar parser global y romper comandos existentes.
+
+## Checklist de finalizacion
+
+- [ ] Tests de `ai onboard` pasan.
+- [ ] Tests de `ai plan` pasan.
+- [ ] Comandos existentes siguen funcionando.
+- [ ] Dry-run no ejecuta providers.
+