create-quiver 0.9.0 → 0.10.0

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-07-github-pr-preflight/slice.json

@@ -0,0 +1,63 @@
+{
+  "slice_id": "slice-07-github-pr-preflight",
+  "ticket": "QUIVER-20-07",
+  "type": "feature",
+  "title": "Add GitHub PR preflight with gh and SSH validation",
+  "objective": "Validate PR readiness across macOS, Linux, and Windows before Quiver opens or prepares a PR.",
+  "description": "Implement ai doctor and ai pr preflight checks for gh installation, gh authentication, Git remote, worktree branch, GitFlow guide, SSH host alias, identity file, and cross-platform setup guidance.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "ai-github-pr-preflight",
+    "branch_name": "feature/QUIVER-20-07-ai-github-pr-preflight"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/github.js",
+    "src/create-quiver/lib/ai/preflight.js",
+    "src/create-quiver/lib/git.js",
+    "tests/commands/ai-pr.test.js",
+    "tests/lib/ai-github.test.js"
+  ],
+  "depends_on": [
+    "slice-01-ai-provider-runner",
+    "slice-04-spec-slice-handoff-pr-generation"
+  ],
+  "parallel_safe": "after_dependencies",
+  "parallel_safe_reason": "Can run in parallel with slice-05 after slice-04 if command-file edits are coordinated.",
+  "must": [
+    "Add PR preflight checks for command -v gh.",
+    "Validate gh auth status.",
+    "Validate a Git remote exists.",
+    "Validate the current worktree/branch can be used for a spec PR.",
+    "Validate docs/GITFLOW_PR_GUIDE.md exists or provide a clear missing-guide error.",
+    "Separate sshHostAlias from identityFile.",
+    "Validate identityFile exists when provided.",
+    "Guide the user to create SSH config without modifying credentials automatically.",
+    "Provide macOS, Linux, and Windows install guidance for gh."
+  ],
+  "not_included": [
+    "Installing gh automatically.",
+    "Editing SSH config automatically.",
+    "Merging PRs.",
+    "Managing GitHub accounts beyond gh auth status."
+  ],
+  "acceptance": [
+    "Missing gh fails with cross-platform installation guidance.",
+    "Unauthenticated gh fails with gh auth login guidance.",
+    "Missing GitFlow guide fails before PR creation.",
+    "Missing identity file fails with the path that was checked.",
+    "sshHostAlias and identityFile are represented as separate options.",
+    "Dry-run prints what PR command would run without creating a PR."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-pr.test.js tests/lib/ai-github.test.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 5,
+  "actual_hours": 5,
+  "started_at": "2026-05-19T17:29:24-0300",
+  "completed_at": "2026-05-19T17:29:24-0300",
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-08-docs-smokes-release-readiness/CLOSURE_BRIEF.md

@@ -0,0 +1,35 @@
+# CLOSURE BRIEF - slice-08: Docs, smokes, and release readiness
+
+## Resumen de lo realizado
+
+Se actualizaron README, README_FOR_AI, templates generados, scripts npm, doctor warnings y smokes para reflejar la familia `quiver ai`: onboarding, planning por fases, execute-slice, PR preflight y doctor. Tambien se agregaron smokes dry-run que no dependen de providers reales ni de autenticacion real de GitHub.
+
+## Validacion contra criterios de aceptacion
+
+- [x] README actualizado.
+- [x] Templates actualizados.
+- [x] Scripts `quiver:ai:*` generados.
+- [x] Smokes dry-run agregados.
+- [x] Cross-platform smoke actualizado.
+- [x] Suite final documentada.
+
+## Cambios relevantes
+
+- `README.md` y `README_FOR_AI.md` documentan comandos AI reales y el flujo planner/executor.
+- `package.template.json` y `package.json` incluyen scripts `quiver:ai:*`.
+- `docs/COMMANDS.md.template`, `docs/AI_ONBOARDING_PROMPT.md.template`, `docs/SUPPORT_MATRIX.md.template`, `docs/TROUBLESHOOTING.md.template` y `docs/GITFLOW_PR_GUIDE.md.template` quedaron alineados con el comportamiento implementado.
+- `src/create-quiver/lib/init-docs.js` y `scripts/init-docs.sh` generan README con scripts AI y guidance planner/executor.
+- `scripts/ci/smoke-create-quiver.sh`, `scripts/ci/smoke-cross-platform.js` y `scripts/ci/smoke-init-docs.sh` validan scripts AI y dry-runs.
+
+## Pendientes
+
+Ninguno para esta slice.
+
+## Riesgos remanentes
+
+- `ai pr` sigue limitado a preflight en esta version; no abre PR real.
+- Los smokes usan dry-run y un `gh` falso para evitar dependencia de autenticacion real.
+
+## Recomendaciones futuras
+
+Preparar release patch/minor segun impacto final y actualizar changelog.

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-08-docs-smokes-release-readiness/EXECUTION_BRIEF.md

@@ -0,0 +1,64 @@
+# EXECUTION BRIEF - slice-08: Docs, smokes, and release readiness
+
+**Spec:** quiver-v20-ai-cli-orchestration
+**Slice:** slice-08-docs-smokes-release-readiness
+**Tipo:** docs
+
+## Contexto
+
+Esta slice cierra la feature. Debe alinear README, templates generados, scripts npm, prompts y smokes con el comportamiento real implementado.
+
+## Objetivo
+
+Documentar `quiver ai ...`, actualizar templates y agregar smokes dry-run sin depender de providers reales.
+
+## Alcance
+
+- README y README_FOR_AI.
+- Templates de onboarding, commands, support, troubleshooting y GitFlow.
+- Scripts generados en package templates.
+- Smokes create-quiver y cross-platform.
+- Verificacion de docs generadas.
+
+## Criterios de aceptacion
+
+- README generado menciona comandos AI.
+- COMMANDS generado incluye ejemplos `quiver ai`.
+- Onboarding prompt generado explica planner/executor.
+- Scripts `quiver:ai:*` existen.
+- Smokes cubren dry-run sin auth real.
+- Cross-platform cubre paths con espacios.
+
+## Plan tecnico resumido
+
+Actualizar documentacion y generadores despues de que los comandos existan. Los smokes deben usar dry-run/mocks para no requerir Codex, Claude, Gemini ni `gh` autenticado.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar comportamiento final implementado.
+2. Actualizar README.
+3. Actualizar templates.
+4. Actualizar init docs runtime.
+5. Agregar scripts npm generados.
+6. Agregar smokes.
+7. Correr suite completa.
+
+## Restricciones
+
+- No cambiar comportamiento funcional fuera de docs/smokes salvo ajuste necesario para generacion.
+- No publicar npm en esta slice.
+- No modificar specs antiguas.
+
+## Riesgos
+
+- Docs prometen mas de lo implementado.
+- Smokes requieren CLIs reales por accidente.
+- Drift entre README_FOR_AI y templates.
+
+## Checklist de finalizacion
+
+- [ ] Tests unitarios pasan.
+- [ ] Smoke create-quiver pasa.
+- [ ] Cross-platform smoke pasa.
+- [ ] README_FOR_AI no contradice README/templates.
+- [ ] No hay prompts obsoletos.

package/specs/quiver-v20-ai-cli-orchestration/slices/slice-08-docs-smokes-release-readiness/slice.json

@@ -0,0 +1,77 @@
+{
+  "slice_id": "slice-08-docs-smokes-release-readiness",
+  "ticket": "QUIVER-20-08",
+  "type": "docs",
+  "title": "Document AI orchestration and add smoke coverage",
+  "objective": "Update user-facing docs, generated templates, scripts, and smoke tests so the AI orchestration workflow is discoverable and release-ready.",
+  "description": "Finalize the feature by documenting commands, roles, context packs, token strategy, provider setup, gh/SSH preflight, and cross-platform behavior. Add dry-run smokes that do not require real provider authentication.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "ai-orchestration-docs-smokes",
+    "branch_name": "feature/QUIVER-20-08-ai-orchestration-docs-smokes"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "docs/AI_ONBOARDING_PROMPT.md.template",
+    "docs/COMMANDS.md.template",
+    "docs/GITFLOW_PR_GUIDE.md.template",
+    "docs/SUPPORT_MATRIX.md.template",
+    "docs/TROUBLESHOOTING.md.template",
+    "src/create-quiver/lib/init-docs.js",
+    "scripts/init-docs.sh",
+    "package.json",
+    "package.template.json",
+    "scripts/ci/smoke-create-quiver.sh",
+    "scripts/ci/smoke-cross-platform.js"
+  ],
+  "depends_on": [
+    "slice-01-ai-provider-runner",
+    "slice-02-context-packs-token-budget",
+    "slice-03-ai-phase-gated-planner",
+    "slice-04-spec-slice-handoff-pr-generation",
+    "slice-05-execution-plan-parallel-worktrees",
+    "slice-06-ai-execute-slice-scope-enforcement",
+    "slice-07-github-pr-preflight"
+  ],
+  "parallel_safe": "never",
+  "parallel_safe_reason": "Final integration slice touches shared docs, templates, package scripts, and smoke tests.",
+  "must": [
+    "Document quiver ai commands in README.",
+    "Document planner and executor roles.",
+    "Document token-efficient context packs.",
+    "Document phase-gated planning and approval rules.",
+    "Document mandatory slice-00.",
+    "Document one spec equals one PR/worktree and one slice equals one commit.",
+    "Document gh and SSH preflight guidance for macOS, Linux, and Windows.",
+    "Add generated npm scripts for quiver:ai:* commands.",
+    "Add smoke tests for dry-run flows without real provider auth.",
+    "Ensure docs/GITFLOW_PR_GUIDE.md is generated or the intended generation behavior is explicitly validated."
+  ],
+  "not_included": [
+    "Adding new provider APIs.",
+    "Publishing npm.",
+    "Changing unrelated docs or old specs."
+  ],
+  "acceptance": [
+    "Generated project README mentions quiver ai commands.",
+    "Generated COMMANDS.md includes ai commands and examples.",
+    "Generated onboarding prompt references planner/executor workflow safely.",
+    "Generated package scripts include quiver:ai:onboard, quiver:ai:plan, quiver:ai:execute-slice, quiver:ai:pr, and quiver:ai:doctor.",
+    "Smoke tests cover ai dry-run flows without requiring provider CLIs.",
+    "Cross-platform smoke validates path handling for ai commands."
+  ],
+  "tests": [
+    "node --test tests/**/*.test.js",
+    "npm run smoke:create-quiver",
+    "node scripts/ci/smoke-cross-platform.js",
+    "git diff --check"
+  ],
+  "estimated_hours": 6,
+  "actual_hours": 5,
+  "started_at": "2026-05-19T21:43:12-0300",
+  "completed_at": "2026-05-19T21:43:12-0300",
+  "status": "completed",
+  "blocked_reason": null
+}

package/specs/quiver-v21-ai-first-layout/EVIDENCE_REPORT.md

@@ -0,0 +1,31 @@
+# Evidence Report - Quiver v21 AI-First Layout
+
+## Summary
+
+Implementation and release-readiness validation are complete.
+
+## Evidence By Slice
+
+| Slice | Evidence |
+| --- | --- |
+| slice-00 | Completed. Created spec foundation, all slice handoffs, execution plan, and PR body. Validated JSON parsing for all `slice.json` files and `git diff --check`. |
+| slice-01 | Completed. Added explicit `init` command parsing, init profile flags, pure layout planner, dry-run formatter, compatibility alias handling, and focused tests. Evidence: `node --test tests/lib/init-layout.test.js tests/commands/init-profiles.test.js`; `git diff --check`. |
+| slice-02 | Completed. Added `.quiver/` internal path helpers, versionable config, internal gitignore for runtime folders, packaged/exported/legacy template resolver, and explicit template-root support in init docs. Evidence: `node --test tests/lib/template-resolver.test.js tests/lib/quiver-internal-layout.test.js tests/lib/init-layout.test.js tests/commands/init-profiles.test.js`; `git diff --check`. |
+| slice-03 | Completed. Implemented profile-aware init generation. Default no longer creates root `docs-template/`, `tools/scripts/`, or placeholder specs; minimal creates the essential onboarding contract; full preserves the broad compatibility layout. Evidence: `node --test tests/**/*.test.js`; `bash scripts/ci/smoke-init-docs.sh`; `bash scripts/ci/smoke-create-quiver.sh`; `git diff --check`. |
+| slice-04 | Completed. Moved raw analyze output to `.quiver/scans/PROJECT_SCAN.json`, kept `docs/PROJECT_MAP.md` visible, added current/legacy scan helpers, and wired context pack metadata plus doctor scan detection to accept the new path with legacy fallback. Evidence: `node --test tests/commands/analyze.test.js tests/lib/project-scan.test.js tests/lib/ai-context-packs.test.js`; `node --test tests/**/*.test.js`; `bash scripts/ci/smoke-create-quiver.sh`; `node scripts/ci/smoke-cross-platform.js`; `git diff --check`. |
+| slice-05 | Completed. Updated doctor so projects initialized with the clean AI-first layout can have no specs yet without failing. Added layout detection for new, legacy, hybrid, and incomplete projects while preserving valid empty states for plan, graph, and next. Evidence: `node --test tests/commands/doctor.test.js tests/lib/doctor.test.js tests/commands/plan.test.js tests/commands/graph.test.js tests/commands/next.test.js`; `node --test tests/**/*.test.js`; `git diff --check`. |
+| slice-06 | Completed. Added non-destructive migrate reporting for legacy `docs-template/`, `tools/scripts/`, and `docs/PROJECT_SCAN.json`, plus explicit optional asset coverage for `--legacy-scripts`, `--include-templates`, and `--full`. Evidence: `node --test tests/commands/init-profiles.test.js tests/lib/init-docs.test.js`; `bash scripts/ci/smoke-init-docs.sh`; `bash scripts/ci/smoke-create-quiver.sh`; `node scripts/ci/smoke-cross-platform.js`; `node --test tests/**/*.test.js`; `git diff --check`. |
+| slice-07 | Completed. Aligned root README, AI guide, onboarding/workflow/command templates, generated README text, and smoke assertions with the AI-first layout. Docs now distinguish visible contract from `.quiver/` internals, mark `docs-template/` and `tools/scripts/` as legacy/optional, and point raw scan output to `.quiver/scans/PROJECT_SCAN.json`. Evidence: `node --test tests/commands/init-profiles.test.js tests/lib/init-docs.test.js`; `bash scripts/ci/smoke-init-docs.sh`; `bash scripts/ci/smoke-create-quiver.sh`; `node --test tests/**/*.test.js`; `bash -n scripts/init-docs.sh`; `git diff --check`. |
+| slice-08 | Completed. Hardened the tiered context-pack smoke to use the explicit `--full --skip-install` compatibility profile and updated expectations for the no-spec AI-first doctor guidance. Completed the final validation matrix. Evidence: `node --test tests/**/*.test.js`; `npm run smoke:create-quiver`; `bash scripts/ci/smoke-init-docs.sh`; `node scripts/ci/smoke-cross-platform.js`; `npm run smoke:tiered-pack`; `git diff --check`. |
+
+## Final Evidence
+
+- `node --test tests/**/*.test.js` passed: 143 tests.
+- `npm run smoke:create-quiver` passed.
+- `bash scripts/ci/smoke-init-docs.sh` passed.
+- `node scripts/ci/smoke-cross-platform.js` passed.
+- `PATH=/private/tmp/quiver-no-npm-path-bin node bin/create-quiver.js init --name "No Npm Smoke 2" --dir /private/tmp/quiver-no-npm-smoke-2 --full --skip-install` passed, covering init when `npm` is unavailable and install is skipped.
+- `npm run smoke:tiered-pack` passed.
+- `git diff --check` passed.
+- GitHub Actions CI run `26196340530` passed validate plus macOS, Ubuntu, and Windows cross-platform smoke jobs.
+- Default init is covered by tests and smokes that assert no root `docs-template/`, no `tools/scripts/`, and no placeholder spec in the default/minimal profiles.

package/specs/quiver-v21-ai-first-layout/EXECUTION_PLAN.md

@@ -0,0 +1,185 @@
+# Execution Plan - Quiver v21 AI-First Layout
+
+## Execution Waves
+
+`slice-00` must run first. It publishes the spec, slices, handoffs, and PR body.
+
+### Ola 0 - Base documental obligatoria
+
+Ejecutar primero y de forma secuencial:
+
+1. `slice-00-spec-foundation`
+
+Salida esperada:
+
+- Spec, slices, briefs, execution plan y PR body versionados.
+- El resto de agentes puede leer solo su slice y handoff.
+
+Gate para avanzar:
+
+- `slice-00` mergeado o, como minimo, disponible en la rama base compartida por los worktrees.
+- Todos los `slice.json` parsean.
+- No hay cambios de codigo de producto.
+
+### Ola 1 - Contrato de entrada del init
+
+Ejecutar de forma secuencial:
+
+1. `slice-01-init-profiles-dry-run`
+
+Motivo:
+
+- Define el parser, flags, alias compatible y layout planner.
+- Los demas slices dependen de estos contratos para no duplicar decisiones.
+
+Gate para avanzar:
+
+- `init --dry-run` no escribe archivos.
+- `npx create-quiver --name` sigue funcionando como alias.
+- El layout planner esta testeado como funcion pura.
+
+### Ola 2 - Infraestructura interna
+
+Ejecutar de forma secuencial:
+
+1. `slice-02-internal-layout-template-resolver`
+
+Motivo:
+
+- Define `.quiver/`, paths internos y resolucion de templates.
+- Es prerequisito para cambiar generacion y analyze sin hardcodear rutas en varios lugares.
+
+Gate para avanzar:
+
+- `.quiver/state.json`, `.quiver/config.json` y `.quiver/.gitignore` definidos.
+- Templates resueltos desde el paquete sin requerir `docs-template/` visible.
+- Fallback legacy cubierto por tests.
+
+### Ola 3 - Cambios funcionales paralelizables
+
+Ejecutar en paralelo despues de la Ola 2:
+
+1. `slice-03-generation-profiles-visible-contract`
+2. `slice-04-analyze-scan-relocation`
+
+Por que pueden ir en paralelo:
+
+- `slice-03` cambia que escribe `init`.
+- `slice-04` cambia donde escribe y lee `analyze`.
+- Comparten helpers de `.quiver/`, pero no deberian modificar la misma responsabilidad principal.
+
+Condiciones de paralelismo:
+
+- Ambos worktrees deben partir de una rama que ya incluya `slice-02`.
+- Si ambos tocan `scripts/ci/smoke-create-quiver.sh`, coordinar el merge final para evitar conflictos de asserts.
+- Si ambos tocan helpers de paths internos, mantener la autoridad en `slice-02` y solo consumirlos.
+
+Gate para avanzar:
+
+- Default init no crea `docs-template/`, `tools/scripts/` ni spec placeholder.
+- `--minimal` y `--full` estan cubiertos.
+- `analyze` escribe `.quiver/scans/PROJECT_SCAN.json`.
+- `docs/PROJECT_MAP.md` sigue visible.
+- Lectura legacy de `docs/PROJECT_SCAN.json` funciona.
+
+### Ola 4 - Compatibilidad y comandos sobre el nuevo layout
+
+Ejecutar en paralelo despues de la Ola 3:
+
+1. `slice-05-empty-specs-layout-doctor`
+2. `slice-06-legacy-migration-optional-assets`
+
+Por que pueden ir en paralelo:
+
+- `slice-05` adapta comandos y doctor al estado sin specs y a deteccion de layout.
+- `slice-06` adapta migracion y assets opcionales.
+- Ambos consumen el comportamiento ya definido por `slice-03` y `slice-04`.
+
+Condiciones de paralelismo:
+
+- Ambos worktrees deben partir de una rama que incluya la Ola 3 completa.
+- Si ambos modifican `doctor`, coordinar ownership: `slice-05` debe ser owner de deteccion/reporting de layout; `slice-06` puede agregar mensajes de migracion usando esa API.
+- Si ambos modifican smokes, evitar duplicar escenarios.
+
+Gate para avanzar:
+
+- `plan`, `graph`, `next` y `doctor` soportan proyectos sin specs.
+- Doctor reporta layout nuevo, legacy, hibrido o incompleto.
+- `migrate` es no destructivo.
+- `--legacy-scripts`, `--include-templates` y `--full` generan assets consistentes.
+
+### Ola 5 - Documentacion alineada
+
+Ejecutar de forma secuencial despues de la Ola 4:
+
+1. `slice-07-docs-guidance-alignment`
+
+Motivo:
+
+- La documentacion debe reflejar comportamiento final, no comportamiento intermedio.
+
+Gate para avanzar:
+
+- README, README_FOR_AI, generated README y templates describen el mismo modelo.
+- `docs-template/`, `tools/scripts/` y scan legacy aparecen solo como compatibilidad u opciones.
+- Onboarding de IA empieza por contrato visible, no por `.quiver/`.
+
+### Ola 6 - Cierre y evidencia
+
+Ejecutar ultimo y de forma secuencial:
+
+1. `slice-08-smokes-release-readiness`
+
+Motivo:
+
+- Valida toda la matriz despues de comportamiento, compatibilidad y docs.
+
+Gate final:
+
+- Suite Node completa pasa.
+- Smokes principales pasan.
+- `EVIDENCE_REPORT.md` actualizado con evidencia real.
+- `pr.md` actualizado y listo para abrir PR.
+
+## Parallelism Summary
+
+| Ola | Slices | Modo |
+| --- | --- | --- |
+| 0 | `slice-00` | Secuencial obligatorio |
+| 1 | `slice-01` | Secuencial |
+| 2 | `slice-02` | Secuencial |
+| 3 | `slice-03`, `slice-04` | Paralelo condicionado |
+| 4 | `slice-05`, `slice-06` | Paralelo condicionado |
+| 5 | `slice-07` | Secuencial |
+| 6 | `slice-08` | Secuencial |
+
+## Worktree Guidance
+
+- Use one worktree per implementation slice.
+- Keep one commit per slice.
+- Do not run `slice-03` before `slice-02` because generation depends on the internal layout and template resolver.
+- Do not run `slice-07` until behavior is stable, otherwise docs will drift.
+
+## Suggested Branches
+
+- `feature/QUIVER-21-00-spec-foundation`
+- `feature/QUIVER-21-01-init-profiles`
+- `feature/QUIVER-21-02-internal-layout`
+- `feature/QUIVER-21-03-generation-profiles`
+- `feature/QUIVER-21-04-analyze-scan`
+- `feature/QUIVER-21-05-empty-specs-doctor`
+- `feature/QUIVER-21-06-legacy-migration`
+- `feature/QUIVER-21-07-docs-alignment`
+- `feature/QUIVER-21-08-smokes`
+
+## Validation Gate
+
+Before closing the spec:
+
+```bash
+node --test tests/**/*.test.js
+npm run smoke:create-quiver
+bash scripts/ci/smoke-init-docs.sh
+node scripts/ci/smoke-cross-platform.js
+git diff --check
+```

package/specs/quiver-v21-ai-first-layout/SPEC.md

@@ -0,0 +1,212 @@
+# Quiver v21 - AI-First Layout
+
+## Summary
+
+Quiver's current initialization flow creates too many visible files for a first onboarding pass. It mixes the project contract that humans and agents should read with Quiver's internal machinery: templates, legacy scripts, placeholder specs, scan artifacts, and optional community files.
+
+This spec redesigns initialization around an AI-first layout:
+
+- visible files are the project contract;
+- `.quiver/` contains internal machinery;
+- specs are created only when there is a real approved requirement;
+- legacy behavior remains available through explicit flags and migration support.
+
+## Problem
+
+The generated footprint can feel disorganized in a new or existing project. A user sees many files before Quiver has actually analyzed the repository or produced a real spec.
+
+The main risks are:
+
+- confusing generated placeholders with real project context;
+- forcing agents to inspect too many files;
+- creating `docs-template/`, `tools/scripts/`, and `specs/<project>/` before they are needed;
+- making future commands depend on files that should be internal implementation details;
+- breaking existing projects if the layout changes without compatibility.
+
+## Goals
+
+- Make the default init output small, legible, and AI-first.
+- Move internal Quiver machinery under `.quiver/`.
+- Keep human/agent-facing contract files visible and versionable.
+- Add explicit profiles for minimal, full, legacy scripts, and template export.
+- Add `init --dry-run` so users can preview file impact.
+- Preserve compatibility with existing Quiver projects and legacy paths.
+- Keep `npx create-quiver --name "Project"` working as a compatibility alias.
+
+## Non-Goals
+
+- Do not change provider execution behavior for `quiver ai`.
+- Do not redesign the spec/slice artifacts generated by `ai plan --phase spec`.
+- Do not publish a new npm release in this spec.
+- Do not migrate user projects destructively.
+- Do not hide `README.md`, `AGENTS.md`, `docs/`, or real `specs/` inside `.quiver/`.
+
+## Approved Acceptance Criteria
+
+### Initialization
+
+1. Given a project without Quiver, when the user runs the recommended init command, then Quiver creates a clean AI-first contract.
+2. Given default init, when generation finishes, then `docs-template/` is not created at the project root.
+3. Given default init, when generation finishes, then `tools/scripts/` is not created unless requested explicitly.
+4. Given default init without a real requirement, when generation finishes, then Quiver does not create a placeholder spec under `specs/<project-slug>/`.
+5. Given `npx create-quiver --name "Project"`, when it runs, then it remains a compatibility alias for the recommended init flow or emits a clear deprecation notice without failing.
+
+### `.quiver/` Internal Layout
+
+1. Given an initialized project, when Quiver stores internal state, then it uses `.quiver/`.
+2. Given `.quiver/cache`, `.quiver/runs`, or `.quiver/worktrees`, when `git status` runs, then those paths do not appear as versionable changes.
+3. Given `.quiver/state.json` and `.quiver/config.json`, when the repo is reviewed, then those files may be versioned as Quiver contract metadata.
+4. Given templates are needed internally, when default init runs, then Quiver uses packaged templates without requiring visible `docs-template/`.
+5. Given `--include-templates`, when init runs, then templates are copied explicitly under `.quiver/templates/`.
+
+### Visible Contract
+
+1. Given a generated project, when a human or AI agent onboards, then it can start from `README.md`, `AGENTS.md`, and `docs/`.
+2. Given a generated project, when an agent onboards, then it does not need to inspect `.quiver/` unless visible docs instruct it to.
+3. Given an initial diff, when it is reviewed, then every visible generated file has a clear purpose and is not a fake project artifact.
+
+### Profiles
+
+1. Given default init, when it runs, then it creates the AI-first clean layout.
+2. Given `--minimal`, when init runs, then Quiver creates only the minimum state, router, and context contract required for AI onboarding.
+3. Given `--full`, when init runs, then Quiver preserves the broader current generation behavior as an explicit mode.
+4. Given `--legacy-scripts`, when init runs, then legacy Bash wrappers and matching npm scripts are created in a documented location.
+5. Given an invalid profile or flag combination, when init runs, then Quiver fails with supported options and no partial writes.
+
+### Analyze
+
+1. Given the new layout, when `analyze` runs, then raw scan output is written to `.quiver/scans/PROJECT_SCAN.json`.
+2. Given `analyze` runs, when it completes, then `docs/PROJECT_MAP.md` remains visible for humans and agents.
+3. Given a legacy project with `docs/PROJECT_SCAN.json`, when `doctor` or AI onboarding reads scan data, then Quiver can read the legacy path without forcing immediate migration.
+
+### Specs and Slice Commands
+
+1. Given a project with no specs yet, when `plan`, `graph`, `next`, or `doctor` runs, then the command reports "no specs yet" or equivalent as a valid state.
+2. Given an approved technical plan, when `ai plan --phase spec` runs, then Quiver creates the real `specs/<spec-slug>/` tree.
+3. Given default init, when no spec exists, then no placeholder slice is created.
+
+### Dry-Run and Safety
+
+1. Given `init --dry-run`, when it runs, then it does not write, move, delete, install, or modify anything.
+2. Given `init --dry-run`, when it exits, then it prints files to create, preserve, ignore, and any risks.
+3. Given a git repo with pending changes, when init would write files, then Quiver warns before writing and provides a safe path forward.
+4. Given a target file already exists, when init runs, then Quiver preserves it by default and reports `skipped`.
+
+### Documentation and Tests
+
+1. Given the new layout, when `README.md`, `README_FOR_AI.md`, generated README, and docs templates are reviewed, then they all describe the same visible-vs-internal model.
+2. Given `.quiver/` is internal, when docs explain onboarding, then they start with visible contract files.
+3. Given the new layout, when smokes run, then default, minimal, full, legacy, include-templates, analyze, and no-spec states are covered.
+
+## Technical Plan
+
+### Architecture
+
+Introduce an initialization layout layer that plans the file operations before writing them.
+
+Core pieces:
+
+- CLI parser support for `init` and profile flags.
+- A pure layout planner that returns intended operations.
+- An init writer that executes the plan or prints it for `--dry-run`.
+- A template resolver that reads packaged templates by default and exported templates only when explicitly requested.
+- `.quiver/` metadata helpers for state, config, ignored runtime folders, scans, and optional templates.
+- Compatibility readers for legacy scan/template/script locations.
+
+### Commands
+
+Supported commands and aliases:
+
+```bash
+npx create-quiver init --name "Project"
+npx create-quiver init --name "Project" --minimal
+npx create-quiver init --name "Project" --full
+npx create-quiver init --name "Project" --legacy-scripts
+npx create-quiver init --name "Project" --include-templates
+npx create-quiver init --name "Project" --dry-run
+npx create-quiver --name "Project"
+```
+
+### Layout Contracts
+
+Default visible contract:
+
+```text
+README.md
+AGENTS.md
+docs/
+  AI_CONTEXT.md
+  AI_ONBOARDING_PROMPT.md
+  COMMANDS.md
+  WORKFLOW.md
+  GITFLOW_PR_GUIDE.md
+  PROJECT_MAP.md        # after analyze
+```
+
+Internal contract:
+
+```text
+.quiver/
+  state.json
+  config.json
+  .gitignore
+  scans/
+    PROJECT_SCAN.json   # after analyze
+  templates/            # only with --include-templates
+  cache/                # ignored
+  runs/                 # ignored
+  worktrees/            # ignored
+```
+
+### Error Handling
+
+- Invalid mode or incompatible flags fail before writes.
+- Missing packaged templates fail with actionable diagnostics.
+- Existing files are skipped by default.
+- `--dry-run` returns planned operations only.
+- Legacy paths are read as fallback and reported as legacy.
+- Empty specs state is valid for orchestration commands.
+
+### Validation
+
+Minimum validation:
+
+- unit tests for layout planning;
+- unit tests for template resolution;
+- CLI tests for init flags and alias behavior;
+- smokes for generated project profiles;
+- analyze smoke for scan relocation;
+- doctor/plan/graph/next smokes for no-spec repos;
+- documentation smoke assertions for visible-vs-internal language.
+
+## Slicing Strategy
+
+`slice-00` is mandatory and must land first because it publishes this spec and all slice handoffs to the repo. Behavior changes are split by responsibility so later execution agents can work with bounded context.
+
+## Slice Roadmap
+
+| Slice | Name | Status | Depends On |
+| --- | --- | --- | --- |
+| slice-00 | Spec foundation | Draft | - |
+| slice-01 | Init profiles and dry-run planner | Draft | slice-00 |
+| slice-02 | Internal layout and template resolver | Draft | slice-01 |
+| slice-03 | Generation profiles and visible contract | Draft | slice-02 |
+| slice-04 | Analyze scan relocation | Draft | slice-02 |
+| slice-05 | Empty specs and layout doctor | Draft | slice-03, slice-04 |
+| slice-06 | Legacy migration and optional assets | Draft | slice-03, slice-04 |
+| slice-07 | Documentation and guidance alignment | Draft | slice-05, slice-06 |
+| slice-08 | Smokes and release readiness | Draft | slice-07 |
+
+## Risks
+
+- Existing users may rely on visible `docs-template/` or `tools/scripts/`.
+- Docs may drift if generated README, root README, and AI guide are not updated together.
+- Commands can accidentally keep expecting placeholder specs.
+- Moving scans can break AI onboarding if fallbacks are incomplete.
+- Full mode can become a dumping ground if not defined tightly.
+
+## Open Questions
+
+- Whether `.quiver/scans/PROJECT_SCAN.json` should be versioned by default or optionally ignored.
+- Whether `--full` should include OSS community files by default or require a future `--oss` flag.
+- Whether the compatibility alias should print a warning immediately or after one release cycle.