create-quiver 0.9.1 → 0.12.0

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.

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

@@ -0,0 +1,37 @@
+# Quiver v21 - AI-First Layout Status
+
+## Status
+
+Completed.
+
+## Summary
+
+This spec defines the cleanup of Quiver's generated project layout. The default init should become AI-first and small, while `.quiver/` owns internal machinery and optional legacy/full assets move behind explicit flags.
+
+## Slice Status
+
+| Slice | Name | Status | Depends On |
+| --- | --- | --- | --- |
+| slice-00 | Spec foundation | Completed | - |
+| slice-01 | Init profiles and dry-run planner | Completed | slice-00 |
+| slice-02 | Internal layout and template resolver | Completed | slice-01 |
+| slice-03 | Generation profiles and visible contract | Completed | slice-02 |
+| slice-04 | Analyze scan relocation | Completed | slice-02 |
+| slice-05 | Empty specs and layout doctor | Completed | slice-03, slice-04 |
+| slice-06 | Legacy migration and optional assets | Completed | slice-03, slice-04 |
+| slice-07 | Documentation and guidance alignment | Completed | slice-05, slice-06 |
+| slice-08 | Smokes and release readiness | Completed | slice-07 |
+
+## Current Evidence
+
+- Acceptance criteria approved by user.
+- Technical plan approved by user.
+- `slice-00` completed with documentation-only artifacts.
+- `slice-01` completed with init dry-run planner, explicit init/profile flags, and compatibility alias tests.
+- `slice-02` completed with `.quiver/` internal layout helpers and template resolver support.
+- `slice-03` completed with profile-aware generation for default, minimal, full, legacy scripts, and template export.
+- `slice-04` completed with analyze scan relocation to `.quiver/scans/PROJECT_SCAN.json` and legacy scan fallback.
+- `slice-05` completed with no-spec doctor support and layout detection for new, legacy, hybrid, and incomplete projects.
+- `slice-06` completed with non-destructive migration reporting and explicit optional assets for `--legacy-scripts`, `--include-templates`, and `--full`.
+- `slice-07` completed with documentation alignment for AI-first init, internal `.quiver/` scan paths, optional legacy assets, and generated README guidance.
+- `slice-08` completed with final validation, tiered smoke alignment for the explicit full compatibility profile, and PR/evidence readiness.

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

@@ -0,0 +1,110 @@
+## Title
+
+Quiver v21 - AI-First Layout
+
+## Summary
+
+Redesign Quiver's generated project layout so the default init is small, visible, and AI-first while internal machinery moves under `.quiver/`.
+
+## Scope
+
+- Add init profiles and `init --dry-run`.
+- Move internal templates, state, scans, and runtime folders under `.quiver/`.
+- Stop generating `docs-template/`, `tools/scripts/`, and placeholder specs by default.
+- Preserve full/legacy behavior behind explicit flags.
+- Keep `docs/PROJECT_MAP.md` visible while moving raw scan output to `.quiver/scans/PROJECT_SCAN.json`.
+- Update doctor, no-spec command behavior, documentation, and smokes.
+
+## Files
+
+- `src/create-quiver/index.js`
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/init-layout.js`
+- `src/create-quiver/lib/init-docs.js`
+- `src/create-quiver/lib/project-scan.js`
+- `src/create-quiver/lib/paths.js`
+- `src/create-quiver/lib/slice.js`
+- `src/create-quiver/lib/doctor.js`
+- `src/create-quiver/lib/state.js`
+- `src/create-quiver/lib/ai/context-packs.js`
+- `scripts/*.sh`
+- `scripts/ci/*`
+- `tests/**/*.test.js`
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/*.template`
+- `specs/quiver-v21-ai-first-layout/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js 22.x recommended.
+- npm.
+- Git with worktree support.
+- macOS/Linux shell for local smokes.
+- Windows behavior is covered by `smoke-cross-platform`.
+
+### Worktree Access
+
+Use the dedicated spec branch/worktree:
+
+```bash
+git switch docs/QUIVER-21-ai-first-layout
+```
+
+### Run the Project
+
+```bash
+node bin/create-quiver.js --help
+```
+
+### Use Cases
+
+#### Case 1: Default AI-first init
+
+Run `npx create-quiver init --name "Smoke Project"` and confirm it creates the visible onboarding contract without root `docs-template/`, `tools/scripts/`, or placeholder specs.
+
+#### Case 2: Explicit compatibility profiles
+
+Run init with `--minimal`, `--full`, `--legacy-scripts`, and `--include-templates` in isolated directories and confirm each profile creates only its intended assets.
+
+#### Case 3: Analyze and no-spec lifecycle
+
+Run `analyze`, `doctor`, `plan`, `graph`, and `next` on a project with no specs yet. Confirm the raw scan is under `.quiver/scans/PROJECT_SCAN.json`, the visible map stays at `docs/PROJECT_MAP.md`, and lifecycle commands return valid no-spec output.
+
+#### Case 4: Legacy compatibility
+
+Run migrate/doctor against a legacy layout and confirm `docs-template/`, `tools/scripts/`, and legacy `docs/PROJECT_SCAN.json` are preserved or reported as compatibility paths.
+
+### Technical Verification
+
+- `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.
+- `npm run smoke:tiered-pack` passed.
+- `git diff --check` passed.
+- GitHub Actions CI passed on validate, macOS, Ubuntu, and Windows: run `26196340530`.
+
+## Evidence
+
+- Default/minimal init coverage asserts no root `docs-template/`, no `tools/scripts/`, and no placeholder spec.
+- Evidence details are recorded in `specs/quiver-v21-ai-first-layout/EVIDENCE_REPORT.md`.
+- Slice status is recorded in `specs/quiver-v21-ai-first-layout/STATUS.md`.
+- Windows/Git Bash path handling is covered by `tests/lib/paths.test.js`.
+
+## Rollback
+
+- Revert this PR to restore the previous generated layout behavior:
+
+```bash
+git revert <merge-commit-sha>
+```
+
+- Existing projects can continue using legacy-compatible paths via `migrate`, `--full`, `--legacy-scripts`, or `--include-templates`.
+
+## Risks / Notes
+
+- Existing projects that depend on legacy generated paths should use `migrate`, `--full`, `--legacy-scripts`, or `--include-templates` intentionally.
+- npm publication should happen only after this PR is merged.

package/specs/quiver-v21-ai-first-layout/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE BRIEF - slice-00: Spec foundation
+
+## Resumen de lo realizado
+
+Se creo la base documental completa de `quiver-v21-ai-first-layout`: spec, status, evidence report, execution plan, cuerpo de PR y nueve slices con `slice.json`, `EXECUTION_BRIEF.md` y `CLOSURE_BRIEF.md`.
+
+## Validacion contra criterios de aceptacion
+
+- [x] Spec incluye criterios aprobados.
+- [x] Plan tecnico aprobado incluido.
+- [x] Todos los slices tienen handoffs.
+- [x] No se modifico codigo de producto.
+
+## Cambios relevantes
+
+- `SPEC.md` documenta el layout AI-first y la separacion contrato visible vs maquinaria interna.
+- `EXECUTION_PLAN.md` define olas secuenciales y paralelas.
+- Cada slice tiene brief de ejecucion y cierre.
+
+## Pendientes
+
+- Implementar `slice-01` a `slice-08`.
+
+## Riesgos remanentes
+
+- El alcance toca init, analyze, doctor, docs y smokes; los merges de olas paralelas pueden requerir coordinacion manual.
+
+## Recomendaciones futuras
+
+- Ejecutar las olas en orden y no iniciar documentacion final hasta estabilizar comportamiento.

package/specs/quiver-v21-ai-first-layout/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,63 @@
+# EXECUTION BRIEF - slice-00: Spec foundation
+
+**Spec:** quiver-v21-ai-first-layout
+**Slice:** slice-00-spec-foundation
+**Tipo:** docs
+
+## Contexto
+
+Quiver necesita redisenar su layout generado para que el init default sea AI-first y limpio. Este slice publica el contrato aprobado antes de tocar codigo.
+
+## Objetivo
+
+Crear y validar la documentacion completa de la spec v21, incluyendo slices y handoffs.
+
+## Alcance
+
+- `SPEC.md`
+- `STATUS.md`
+- `EVIDENCE_REPORT.md`
+- `EXECUTION_PLAN.md`
+- `pr.md`
+- `slices/**/slice.json`
+- `slices/**/EXECUTION_BRIEF.md`
+- `slices/**/CLOSURE_BRIEF.md`
+
+## Criterios de aceptacion
+
+- La spec incluye criterios aprobados y plan tecnico aprobado.
+- Todos los slices tienen handoffs obligatorios.
+- `slice-00` queda marcado como prerequisito para el resto.
+- No hay cambios de codigo de producto.
+
+## Plan tecnico resumido
+
+Crear solo artefactos documentales bajo `specs/quiver-v21-ai-first-layout/`.
+
+## Pasos sugeridos de ejecucion
+
+1. Revisar `README_FOR_AI.md` y specs recientes para mantener el formato local.
+2. Crear la carpeta de spec.
+3. Crear archivos raiz de la spec.
+4. Crear slices con `slice.json` y briefs.
+5. Validar JSON y whitespace.
+
+## Restricciones
+
+- No implementar codigo.
+- No modificar docs fuera de la spec.
+- No publicar release.
+
+## Riesgos
+
+- Slices demasiado grandes para ejecutores.
+- Dependencias ambiguas entre slices.
+- Desalineacion con el formato real de Quiver.
+
+## Checklist de finalizacion
+
+- [ ] Spec raiz creada.
+- [ ] Execution plan creado.
+- [ ] Todos los slices creados.
+- [ ] Todos los `slice.json` parsean.
+- [ ] `git diff --check` pasa.

package/specs/quiver-v21-ai-first-layout/slices/slice-00-spec-foundation/slice.json

@@ -0,0 +1,45 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-21-00",
+  "type": "docs",
+  "title": "Publish AI-first layout spec foundation",
+  "objective": "Commit the approved spec, execution plan, PR body, slice definitions, and handoff briefs for the AI-first layout initiative.",
+  "description": "This slice is mandatory and must land first so every later executor can work from an approved, versioned handoff.",
+  "git": {
+    "branch_type": "docs",
+    "base_branch": "main",
+    "branch_slug": "quiver-21-ai-first-layout-spec-foundation",
+    "branch_name": "docs/QUIVER-21-00-ai-first-layout-spec-foundation"
+  },
+  "files": [
+    "specs/quiver-v21-ai-first-layout/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Foundation documentation must be reviewed before implementation slices start.",
+  "must": [
+    "Create SPEC.md with approved acceptance criteria and technical plan.",
+    "Create STATUS.md, EVIDENCE_REPORT.md, EXECUTION_PLAN.md, and pr.md.",
+    "Create every slice directory with slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Keep scope limited to documentation artifacts."
+  ],
+  "not_included": [
+    "Product code changes.",
+    "Generated project behavior changes.",
+    "Release or npm publication."
+  ],
+  "acceptance": [
+    "Spec documents the visible-vs-internal layout decision.",
+    "Every slice has an EXECUTION_BRIEF and CLOSURE_BRIEF at its slice root.",
+    "Execution plan names sequential and parallel levels.",
+    "All slice.json files parse as valid JSON."
+  ],
+  "tests": [
+    "find specs/quiver-v21-ai-first-layout/slices -name 'slice.json' -print -exec node -e \"JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))\" {} \\;",
+    "git diff --check"
+  ],
+  "estimated_hours": 2,
+  "actual_hours": 2,
+  "status": "completed",
+  "blocked_reason": null
+}