create-quiver 0.9.1 → 0.10.0

package/README_FOR_AI.md

@@ -1,6 +1,6 @@
-# AI Guide for Quiver Docs Template
+# AI Guide for Quiver
 
-Use this guide when initializing a new project from the template or when explaining the workflow to another agent.
+Use this guide when initializing a new project with Quiver or when explaining the workflow to another agent.
 
 The first AI job in a generated project is context preparation, not product implementation.
 
@@ -9,11 +9,12 @@ The canonical installer entrypoint is `npx create-quiver` run from the target pr
 Do not recommend global installation; use `npx` or a project-local devDependency when the team needs a pinned version.
 The post-init contract is validated with `npx create-quiver doctor` from the project root.
 If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate` before `analyze` from the project root.
-If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver --name "Project Name"` first.
-Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, and `quiver:next` for the next ready slice. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
+If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver init --name "Project Name"` first.
+Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, `quiver:next` for the next ready slice, and the AI family `quiver:ai:onboard`, `quiver:ai:plan`, `quiver:ai:execute-slice`, `quiver:ai:pr`, and `quiver:ai:doctor`. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
 Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 The primary generated project context for agents is `docs/AI_CONTEXT.md`.
 The project map is the single source of truth for stack, package manager, commands, and file hints: `docs/PROJECT_MAP.md`.
+The raw analyzer output is internal machinery at `.quiver/scans/PROJECT_SCAN.json`; read it only when the visible map is not enough.
 The universal router for generated projects is `AGENTS.md`; read it before `docs/AI_CONTEXT.md` and `docs/AI_ONBOARDING_PROMPT.md`.
 Generated projects also get `docs/DECISIONS.md`; use it for durable choices that should not be re-litigated.
 If a generated project has been analyzed, the exact agent handoff prompt is `docs/AI_ONBOARDING_PROMPT.md`.
@@ -26,7 +27,7 @@ During onboarding, after reading `ROADMAP.md`, also read `BACKLOG.md` in the rep
 
 Use the smallest context that still answers the current task.
 
-- **Onboarding:** start from `README.md`, `AGENTS.md` when present, `docs/PROJECT_MAP.md`, `docs/PROJECT_SCAN.json`, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before opening source files.
+- **Onboarding:** start from `README.md`, `AGENTS.md` when present, `docs/PROJECT_MAP.md`, `.quiver/scans/PROJECT_SCAN.json` when it exists, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before opening source files.
 - **Onboarding router:** start from `README.md` and `AGENTS.md` first, then the onboarding files above.
 - **Implementation:** start from `docs/ai/ACTIVE_SLICE.md` when it exists; otherwise start from `specs/<project-slug>/slices/<slice-id>/slice.json`, then read only the declared files, nearby tests, and directly related source.
 - **Handoff:** start from `specs/<project-slug>/HANDOFF.md` when the work was explicitly transferred through a handoff artifact.
@@ -38,12 +39,12 @@ Prefer maps, metadata, diffs, and summaries over full file reads when they are e
 
 ## Core Rules
 
-- Never customize `docs-template/` for a specific project.
-- Always use `init-docs.sh` instead of copying files by hand.
-- Treat `docs-template/` as generic and `docs/` as generated project-specific output.
+- Do not treat `docs-template/` as part of the default project contract. It is legacy or exported only when explicitly requested.
+- Use `npx create-quiver init` or `npx create-quiver --name "Project Name"` instead of copying templates by hand.
+- Treat `.quiver/` as Quiver internal machinery and `docs/` as the visible project-specific contract.
 - Not every project needs every optional file.
 - The AI context pack lives in `docs/AI_CONTEXT.md`; `docs/CONTEXTO.md` is the broader project overview; `docs/PROJECT_MAP.md` owns stack and command facts.
-- The onboarding prompt lives in `docs/AI_ONBOARDING_PROMPT.md` and should reference the analyzer outputs.
+- The onboarding prompt lives in `docs/AI_ONBOARDING_PROMPT.md` and should reference `docs/PROJECT_MAP.md`; raw scan details live in `.quiver/scans/PROJECT_SCAN.json`.
 - `specs/<project-slug>/HANDOFF.md` is reserved for exceptional context transfers between agents or phases.
 - Initial onboarding should complete context docs and report assumptions before any feature work starts.
 - The normal workflow runs from the project root without `--dir`; use `--dir` only when targeting another directory explicitly.
@@ -56,47 +57,58 @@ Prefer maps, metadata, diffs, and summaries over full file reads when they are e
 
 ## Initialization Flow
 
-1. Copy the template folder into the target project as `docs-template/`.
-2. Run:
+1. From the target project root, run the default AI-first initializer:
 
 ```bash
-./docs-template/scripts/init-docs.sh "Project Name"
+npx create-quiver init --name "Project Name"
 ```
 
-3. Tell the user to edit:
+The compatibility alias is still valid:
+
+```bash
+npx create-quiver --name "Project Name"
+```
+
+2. Analyze and validate the project contract:
+
+```bash
+npx create-quiver analyze
+npx create-quiver doctor
+```
+
+3. Tell the user to review or complete:
   - `docs/AI_CONTEXT.md`
   - `docs/AI_ONBOARDING_PROMPT.md`
   - `docs/CONTEXTO.md`
   - `docs/STATUS.md`
-  - `docs/SUPPORT_MATRIX.md`
-  - `docs/TROUBLESHOOTING.md`
-  - `specs/{{PROJECT_SLUG}}/SPEC.md`
+  - `docs/PROJECT_MAP.md`
+
+## What Init Creates
 
-## What the Script Creates
+Default init creates the visible AI-first contract and Quiver internal state:
 
+- `AGENTS.md`
 - `docs/`
 - `docs/ai/`
 - `docs/AI_CONTEXT.md`
 - `docs/AI_ONBOARDING_PROMPT.md`
-- `specs/{{PROJECT_SLUG}}/`
-- `tools/scripts/`
-- `docs/SEARCH.md`
-- a merged or copied `package.json` with the required npm scripts
-- the default OSS baseline when those files are missing:
-- `LICENSE`
-- `CONTRIBUTING.md`
-- `CODE_OF_CONDUCT.md`
-- `SECURITY.md`
-- `CHANGELOG.md`
-- `ROADMAP.md`
 - `docs/SUPPORT_MATRIX.md`
 - `docs/TROUBLESHOOTING.md`
-- `.github/pull_request_template.md`
-- `.github/ISSUE_TEMPLATE/bug_report.md`
-- `.github/ISSUE_TEMPLATE/feature_request.md`
-- `.github/workflows/ci.yml`
+- `.quiver/config.json`
+- `.quiver/state.json`
+- `.quiver/.gitignore`
+- a merged or copied `package.json` with `quiver:*` scripts
+
+Default init does not create `docs-template/`, `tools/scripts/`, or a placeholder spec.
+
+Optional compatibility profiles:
+
+- `--minimal` creates only the essential onboarding contract.
+- `--full` preserves the broad legacy-compatible layout, including placeholder spec assets and OSS/community files.
+- `--legacy-scripts` adds Bash wrappers under `tools/scripts/`.
+- `--include-templates` exports packaged templates under `.quiver/templates/`, not root `docs-template/`.
 
-`init-docs.sh` preserves any existing target files and reports skipped copies instead of overwriting them.
+Init preserves existing target files and reports skipped copies instead of overwriting them.
 
 ## Required Follow-Up
 
@@ -106,20 +118,21 @@ After initialization, the user should:
 2. Fill in `docs/AI_ONBOARDING_PROMPT.md`
 3. Fill in `docs/CONTEXTO.md`
 4. Fill in `docs/STATUS.md`
-5. Run `npx create-quiver analyze` if scan artifacts are missing
+5. Run `npx create-quiver analyze` if `docs/PROJECT_MAP.md` or `.quiver/scans/PROJECT_SCAN.json` is missing
 6. If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate`
-7. If the project was never initialized by Quiver, run `npx create-quiver --name "Project Name"` instead of `migrate`
+7. If the project was never initialized by Quiver, run `npx create-quiver init --name "Project Name"` instead of `migrate`
 8. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
 9. Review context docs before creating the first implementation slice
 10. Open and merge the documentation PR that establishes the workflow files
-11. Create the first slice in `specs/{{PROJECT_SLUG}}/slices/[slice-id]/`
-12. Add `ticket` and `git.*`
-13. Run `npx create-quiver plan` or `npm run quiver:plan`
-14. Run `npx create-quiver next` or `npm run quiver:next`
-14. Run `npx create-quiver start-slice [--allow-draft] <slice.json>` or `npm run quiver:start-slice -- [--allow-draft] <slice.json>`
-15. Make one commit per slice
-16. Open one PR per spec
-17. Validate the slice and the final PR with the workflow gates
+11. Use `npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run`
+12. After human approval, use `npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run`
+13. After human approval, use `npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run` to create the real spec, slices, handoffs, execution plan, and PR body
+14. Run `npx create-quiver plan` or `npm run quiver:plan`
+15. Run `npx create-quiver next` or `npm run quiver:next`
+16. Run `npx create-quiver start-slice [--allow-draft] <slice.json>` or `npm run quiver:start-slice -- [--allow-draft] <slice.json>`
+17. Make one commit per slice
+18. Open one PR per spec
+19. Validate the slice and the final PR with the workflow gates
 
 Bootstrap note: `start-slice` should resolve paths canonically, prefer a local `develop` or `main` base branch before reaching for `origin`, and reject `draft` slices unless `--allow-draft` is passed intentionally.
 
@@ -130,7 +143,7 @@ Bootstrap note: `start-slice` should resolve paths canonically, prefer a local `
 - `docs/GITFLOW_PR_GUIDE.md` if the team wants a stricter branch workflow
 - `docs/SUPPORT_MATRIX.md` and `docs/TROUBLESHOOTING.md` for first-run support
 - `docs/ai/LESSONS.md` after each slice
-- `docs/AI_ONBOARDING_PROMPT.md` after analysis
+- `.quiver/templates/` only when the team explicitly exports packaged templates
 
 ## Good Defaults
 

package/docs/AI_ONBOARDING_PROMPT.md.template

@@ -13,8 +13,8 @@ Actúa como asistente de onboarding de IA para este proyecto. Tu objetivo es com
    - `README.md`
    - `AGENTS.md`, si existe
    - `docs/AI_ONBOARDING_PROMPT.md`
-   - `docs/PROJECT_SCAN.json`
    - `docs/PROJECT_MAP.md`
+   - `.quiver/scans/PROJECT_SCAN.json`, si existe y el mapa visible no alcanza
    - `docs/AI_CONTEXT.md`
    - `docs/CONTEXTO.md`
    - `docs/WORKFLOW.md`
@@ -66,13 +66,23 @@ Actúa como asistente de onboarding de IA para este proyecto. Tu objetivo es com
 
 Usa el menor contexto que todavía permita resolver la tarea:
 
-- **Onboarding:** usa mapas y metadatos primero. Lee `docs/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md` antes de abrir archivos fuente. Después usa `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md` y `docs/WORKFLOW.md` para completar vacíos.
+- **Onboarding:** usa mapas y metadatos primero. Lee `docs/PROJECT_MAP.md` antes de abrir archivos fuente. Si necesitás el scan crudo, usá `.quiver/scans/PROJECT_SCAN.json`. Después usa `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md` y `docs/WORKFLOW.md` para completar vacíos.
+- **Planner:** usa contexto amplio solo para onboarding y planificación. El planner genera criterios de aceptación, plan técnico, specs, slices, handoffs y cuerpo de PR con aprobación humana entre fases.
+- **Executor:** usa contexto mínimo del slice. El executor parte de `slice.json` y `EXECUTION_BRIEF.md`, puede modificar código solo cuando el usuario lo autoriza y debe mantenerse dentro de `slice.json.files`.
 - **Implementación:** no implementes durante onboarding salvo autorización explícita. Si el usuario autoriza implementación, empieza por `specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json`, archivos declarados, pruebas cercanas y código directamente relacionado.
 - **Review:** empieza por `git diff` y el alcance del slice antes de abrir archivos completos.
 - **Debug:** empieza por el comando, exit code, primer error relevante, stacktrace y código más cercano al cambio.
 
 Prefiere resúmenes, deltas y metadatos antes que lecturas completas cuando sean suficientes.
 
+Si usás los comandos de IA de Quiver, empezá con `--dry-run` para revisar provider, rol, context pack y transporte de prompt antes de ejecutar:
+
+```bash
+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/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json --dry-run
+```
+
 ## Tareas
 
 1. Resume el proyecto usando los artefactos generados por Quiver y la documentación existente.
@@ -86,7 +96,7 @@ Prefiere resúmenes, deltas y metadatos antes que lecturas completas cuando sean
 
 ## Validación
 
-- Cita `docs/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md` cuando hagas afirmaciones sobre stack, comandos o estructura.
+- Cita `docs/PROJECT_MAP.md` cuando hagas afirmaciones sobre stack, comandos o estructura. Si usás datos del scan crudo, cita `.quiver/scans/PROJECT_SCAN.json`.
 - Indica rutas omitidas o señales faltantes.
 - Mantén la respuesta enfocada en documentación y contexto de onboarding salvo que el usuario haya autorizado cambios de código de producto.
 - No cambies reglas del workflow de Quiver salvo que el usuario lo pida explícitamente.

package/docs/COMMANDS.md.template

@@ -9,20 +9,41 @@ This document is the canonical command reference for the orchestration roadmap.
 
 | Command | Purpose | OS | Since | Example |
 |---------|---------|----|-------|---------|
+| `npx create-quiver init --name "<project>"` | Creates the default AI-first Quiver contract for a project | macOS, Linux, Windows | current | `npx create-quiver init --name "{{PROJECT_NAME}}"` |
+| `npx create-quiver --name "<project>"` | Compatibility alias for the recommended init flow | macOS, Linux, Windows | current | `npx create-quiver --name "{{PROJECT_NAME}}"` |
+| `quiver:analyze` | Writes raw analyzer data to `.quiver/scans/PROJECT_SCAN.json` and the visible project map to `docs/PROJECT_MAP.md` | macOS, Linux, Windows | v0.8 | `npm run quiver:analyze` |
+| `quiver:doctor` | Validates the Quiver contract and reports layout or migration guidance | macOS, Linux, Windows | v0.8 | `npm run quiver:doctor` |
 | `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.8 | [docs/examples/plan.md](./examples/plan.md) |
 | `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.8 | [docs/examples/graph.md](./examples/graph.md) |
 | `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.8 | [docs/examples/next.md](./examples/next.md) |
+| `quiver:ai:onboard` | Runs AI onboarding prompt through a supported local provider CLI | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:onboard -- --dry-run` |
+| `quiver:ai:plan` | Runs phase-gated AI planning for acceptance criteria, technical plan, or spec generation | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run` |
+| `quiver:ai:execute-slice` | Runs an executor agent against one slice handoff with scope checks | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:execute-slice -- --slice specs/<spec>/slices/<slice>/slice.json --dry-run` |
+| `quiver:ai:doctor` | Runs GitHub PR preflight checks without opening a PR | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:doctor -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
+| `quiver:ai:pr` | Validates `gh`, GitFlow docs, branch/worktree state, and SSH inputs before PR work | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
 
 ## CLI Flags
 
 | Flag | Applies to | Purpose |
 |------|------------|---------|
+| `--minimal` | `init` | Create only the essential onboarding contract |
+| `--full` | `init` | Create the broad legacy-compatible layout explicitly |
+| `--legacy-scripts` | `init` | Add legacy Bash wrappers under `tools/scripts/` |
+| `--include-templates` | `init` | Export packaged templates under `.quiver/templates/` |
 | `--skip-install` | `init`, `migrate` | Skip auto-install of `create-quiver` as dev dependency (useful for CI) |
 | `--json` | `plan`, `graph`, `next` | Emit machine-readable JSON |
 | `--format <tree\|mermaid\|dot>` | `graph` | Output format |
 | `--all-ready` | `next` | List all ready slices instead of just the next one |
 | `--only-ready` | `plan` | Show only slices with no pending dependencies |
 | `--spec <slug>` | `plan`, `graph` | Restrict output to one spec |
+| `--provider <codex\|claude\|gemini>` | `ai onboard`, `ai plan`, `ai execute-slice` | Select the local AI CLI adapter |
+| `--role <planner\|executor>` | `ai onboard`, `ai plan`, `ai execute-slice` | Select planner or executor role; `execute-slice` requires executor |
+| `--context <full\|planning\|slice\|minimal>` | `ai onboard`, `ai plan`, `ai execute-slice` | Select a token-budgeted context pack |
+| `--phase <acceptance\|technical-plan\|spec>` | `ai plan` | Select the gated planner phase |
+| `--input <file>` | `ai plan` | Read approved requirements, criteria, or technical plan from a file |
+| `--slice <slice.json>` | `ai execute-slice` | Select the slice handoff to execute |
+| `--ssh-host-alias <alias>` | `ai doctor`, `ai pr` | SSH host alias from the user's Git config, for example `github-work` |
+| `--identity-file <path>` | `ai doctor`, `ai pr` | SSH key path to validate separately from the host alias |
 
 ## Notes
 
@@ -32,5 +53,8 @@ This document is the canonical command reference for the orchestration roadmap.
 - `quiver:graph --format mermaid` is the PR-friendly Mermaid export; `--format dot` is for Graphviz/DOT consumers.
 - `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
 - `check-slice` validates `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is `never`.
+- `quiver:ai:onboard`, `quiver:ai:plan`, and `quiver:ai:execute-slice` support `codex`, `claude`, and `gemini` through local CLIs. Use `--dry-run` first to inspect the invocation without requiring provider auth.
+- `quiver:ai:execute-slice` uses executor context only and validates changed files against `slice.json.files` after provider execution.
+- `quiver:ai:pr -- --dry-run` validates GitHub CLI, auth, Git remote, current branch/worktree, `docs/GITFLOW_PR_GUIDE.md`, SSH host alias, and identity file without creating a PR.
 - After `init` or `migrate`, Quiver auto-installs itself as a dev dependency. Use `--skip-install` to suppress.
 - Cross-platform authoring rules live in `docs/SUPPORT_MATRIX.md`.

package/docs/GITFLOW_PR_GUIDE.md.template

@@ -11,11 +11,22 @@ This guide explains how to open and review spec PRs without breaking the canonic
 
 - One slice = one commit
 - One spec = one PR
+- One spec should be worked from one dedicated worktree/branch.
 - Slice numbers reset per spec. `slice-01` is the first slice in each spec.
 - Do not commit directly to `develop`
 - Open and merge the documentation PR before the first slice starts execution
 - Do not open the spec PR before the documentation PR is merged
 
+## AI PR Preflight
+
+Before asking an AI agent to prepare PR work, validate the local setup:
+
+```bash
+npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+```
+
+Use the SSH host alias from your Git remote separately from the key path. Quiver validates `gh`, `gh auth status`, the remote, branch/worktree state, this guide, and the identity file. It does not install `gh`, edit SSH config, or create a PR in dry-run mode.
+
 ## Review Guidance
 
 - Start with `git diff` and the slice scope before opening full files.

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/SUPPORT_MATRIX.md.template

@@ -16,6 +16,8 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 | 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
 

package/docs/TROUBLESHOOTING.md.template

@@ -48,7 +48,7 @@ Use this guide when a first-run bootstrap or gate check fails. The recovery path
 
 ### 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 +82,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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",
@@ -16,6 +16,11 @@
     "quiver:plan": "npx create-quiver plan",
     "quiver:graph": "npx create-quiver graph",
     "quiver:next": "npx create-quiver next",
+    "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",
     "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",

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
@@ -591,6 +627,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 +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\`.
@@ -649,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)"
@@ -660,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-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`.