create-quiver 0.9.0 → 0.10.0

package/README.md

@@ -1,226 +1,414 @@
 # Quiver
 
-Quiver is a CLI-first documentation workflow for projects that use specs, slices, and AI-assisted implementation.
+Quiver es un framework para trabajar con **WDD + SDD asistido por IA** en proyectos de software.
+Ayuda a transformar un repositorio en un entorno donde humanos y agentes pueden entender el contexto, planificar por specs, ejecutar slices y revisar cambios con evidencia.
+Está pensado para equipos que quieren usar IA de forma ordenada: primero workflow, después specs, después implementación.
 
-It gives a project a repeatable structure for planning work, starting focused implementation slices, validating readiness, and keeping human and AI contributors aligned.
+## 🚀 Inicio rápido
 
-## Developer Onboarding Flow
+### Usar Quiver con IA en un proyecto
 
-Use this flow when adopting Quiver in an existing project or starting a new one.
-
-### 1. Install Quiver
-
-Run Quiver from the project where the workflow will live:
+Ejecutá Quiver desde la raíz del proyecto donde querés instalar el workflow:
 
 ```bash
-cd /path/to/your-project
-npx create-quiver --name "Project Name"
+npx create-quiver init --name "Mi Proyecto"
+npx create-quiver analyze
+npx create-quiver doctor
+npx create-quiver ai onboard --dry-run
 ```
 
-Do not install Quiver globally. Running it with `npx` from the project root keeps the generated docs, specs, and scripts in the right repository.
+Después de eso, revisá:
 
-If your team wants to pin the Quiver version in the project, install it as a devDependency:
+- `AGENTS.md`
+- `docs/PROJECT_MAP.md`
+- `docs/AI_CONTEXT.md`
+- `docs/AI_ONBOARDING_PROMPT.md`
+
+La maquinaria interna queda en `.quiver/`. Las specs reales no se crean durante el init: aparecen cuando el planner genera y aprueba una spec con `ai plan --phase spec`.
+
+El flujo normal con IA continúa así:
 
 ```bash
-npm install --save-dev create-quiver
-npx create-quiver --name "Project Name"
+npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
+npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run
+npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
+npx create-quiver next
+npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
 ```
 
-To initialize a different directory from outside the project, pass `--dir` explicitly. Quote paths that contain spaces:
+Usá `--dry-run` para validar provider, rol, contexto y paths sin ejecutar el modelo. Cuando el output esté revisado y aprobado, quitá `--dry-run`.
+
+### Desarrollar este repositorio
 
 ```bash
-npx create-quiver --name "Project Name" --dir "/Users/me/My Project"
+git clone <repo-url>
+cd quiver
+npm install
+node bin/create-quiver.js --help
+node --test tests/**/*.test.js
 ```
 
-### 2. Analyze And Validate
+> El remote local detectado usa un alias SSH (`git@github-personal:FabriJuncal/quiver.git`). Si no tenés ese alias configurado, cloná con la URL que use tu equipo.
 
-Run the local analyzer and then validate the generated contract from the project root:
+## 🧠 Workflow principal: WDD + SDD con IA
+
+Quiver asume que la mayoría de los equipos lo van a usar para coordinar trabajo con agentes de IA. Por eso el flujo principal no empieza por código: empieza por contexto, workflow y planificación.
+
+| Etapa | Qué significa | Artefactos principales |
+|---|---|---|
+| WDD | Workflow-Driven Development: dejar claro cómo se trabaja antes de implementar. | `AGENTS.md`, `docs/WORKFLOW.md`, `docs/AI_CONTEXT.md`, `docs/PROJECT_MAP.md` |
+| SDD | Spec-Driven Development: definir el trabajo en specs y slices antes de tocar código. | `specs/<project-slug>/SPEC.md`, `slice.json`, `EXECUTION_BRIEF.md`, `pr.md` |
+| IA planner | Agente que lee contexto amplio y propone criterios, plan técnico, spec y slices. | `ai onboard`, `ai plan` |
+| IA executor | Agente que recibe un slice aprobado y trabaja con contexto mínimo. | `ai execute-slice`, `check-scope`, `check-slice` |
+
+Flujo recomendado:
 
 ```bash
 npx create-quiver analyze
-npx create-quiver graph
 npx create-quiver doctor
+npx create-quiver ai onboard --dry-run
+npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
+npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run
+npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
+npx create-quiver graph
 npx create-quiver next
+npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
 ```
 
-Use `npx create-quiver graph --format mermaid` for PR-ready Markdown or `npx create-quiver graph --format dot` for Graphviz source.
-
-If you need to target another directory from outside the project, pass `--dir` explicitly. For the current project root, omit it.
-
-The analyzer creates `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md`. These files give the AI agent a deterministic project map before it edits context docs.
+Regla práctica: el planner no modifica código de producto; el executor solo trabaja sobre un slice aprobado y dentro de los archivos declarados en `slice.json`.
 
-The doctor checks the generated project contract and prints the next workflow steps. If the scan artifacts are missing, it recommends `npx create-quiver analyze` first.
-`npx create-quiver next` prints the next ready slice and can auto-start it behind a confirmation prompt.
+## 🛠️ Empezar a usar Quiver según tu caso
 
-### Project NPM Scripts
+### 1. Proyecto nuevo desde cero
 
-Generated projects include `quiver:*` npm scripts that call the Node CLI and are the preferred repeatable workflow:
+Usá este camino cuando todavía no existe el proyecto o estás arrancando una carpeta nueva y querés que Quiver acompañe el workflow desde el primer commit.
 
 ```bash
-npm run quiver:analyze
-npm run quiver:plan
-npm run quiver:graph
-npm run quiver:next
-npm run quiver:doctor
-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
-npm run quiver:check-pr -- specs/<project-slug>/slices/slice-01/slice.json
-npm run quiver:cleanup-slice -- specs/<project-slug>/slices/slice-01/slice.json
-npm run quiver:check-scope -- specs/<project-slug>/slices/slice-01/slice.json
-npm run quiver:refresh-active-slices
+mkdir mi-proyecto
+cd mi-proyecto
+npx create-quiver init --name "Mi Proyecto"
+npx create-quiver analyze
+npx create-quiver doctor
+npx create-quiver ai onboard --dry-run
 ```
 
-`npm run quiver:graph` prints the tree view by default. Pass `--format mermaid` or `--format dot` when you need an exportable graph artifact.
-`npm run quiver:next` points to the next ready slice and can auto-start it behind a confirmation prompt.
-`npx create-quiver next --all-ready` shows the full ready level when you want the whole queue instead of one slice.
+Qué esperar:
 
-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.
-`npm run quiver:migrate` is only for projects that were already initialized by Quiver.
+- Quiver crea un contrato visible chico: `AGENTS.md`, `docs/`, scripts `quiver:*` en `package.json` y configuración interna en `.quiver/`.
+- No crea `docs-template/`, `tools/scripts/` ni una spec placeholder en el flujo default.
+- `analyze` crea el scan crudo en `.quiver/scans/PROJECT_SCAN.json` y el mapa legible en `docs/PROJECT_MAP.md`.
+- `doctor` valida que el contrato inicial esté completo.
+- `ai onboard --dry-run` muestra cómo se incorporaría un agente planner sin ejecutar el provider todavía.
 
-### 3. Upgrade Existing Projects
-
-If the project already had Quiver from an older version, upgrade it from the project root:
+Después del bootstrap, revisá:
 
 ```bash
-cd /path/to/your-project
-npx create-quiver migrate
-npx create-quiver analyze
+npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
+npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run
+npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
+npx create-quiver plan
 npx create-quiver graph
-npx create-quiver doctor
 npx create-quiver next
 ```
 
-Use `npx create-quiver graph --format mermaid` for GitHub-friendly graph embeds or `npx create-quiver graph --format dot` for Graphviz pipelines.
+### 2. Proyecto ya iniciado sin Quiver
+
+Usá este camino cuando el repo ya tiene código, pero nunca fue inicializado con Quiver.
 
-If the project never ran Quiver initialization before, do not use `migrate` as bootstrap. Run:
+Primero revisá el estado actual:
 
 ```bash
-npx create-quiver --name "Project Name"
+git status --short
 ```
 
-If your team prefers a pinned local dependency, update the package first and then run the same flow:
+Si hay cambios pendientes, conviene guardarlos, commitearlos o crear una rama dedicada para que el diff de onboarding sea fácil de revisar.
+
+Luego inicializá Quiver desde la raíz del proyecto:
 
 ```bash
-npm install --save-dev create-quiver@latest
-npx create-quiver migrate
+npx create-quiver init --name "Nombre del Proyecto"
 npx create-quiver analyze
-npx create-quiver graph
 npx create-quiver doctor
+npx create-quiver ai onboard --dry-run
+git status --short
 ```
 
-The tree output remains the default, but Mermaid and DOT are available on demand for exported docs and slide decks.
+Qué esperar:
 
-### 4. Ask The AI To Prepare Context
+- Quiver agrega documentación, scripts `quiver:*` y archivos internos de soporte en `.quiver/`.
+- No deberías mezclar este paso con cambios de producto.
+- `docs/PROJECT_MAP.md` queda como fuente de verdad para stack, package manager, comandos y rutas importantes.
+- Las specs y slices reales se crean después, con `ai plan --phase spec`, cuando ya existen criterios y plan técnico aprobados.
+- El primer trabajo de IA debería ser preparar contexto y planificación, no implementar.
 
-Open your AI agent in the target project and run this short handoff:
+Importante: no uses `migrate` para un proyecto que nunca tuvo Quiver. `migrate` es solo para proyectos previamente inicializados.
 
-```text
-Read docs/AI_ONBOARDING_PROMPT.md and execute it.
-Do not modify product code unless I explicitly authorize it.
-Prepare the project context docs and report assumptions, risks, and files changed.
-```
+### 3. Proyecto iniciado con una versión vieja de Quiver
 
-The AI should use the scan artifacts to prepare `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md`, `docs/STATUS.md`, and the initial project spec. The developer should review those documentation changes before implementation work starts.
+Usá este camino cuando el repo ya tiene señales de Quiver, pero querés actualizarlo al contrato actual.
 
-### 5. Start The First Slice
+Señales típicas de una instalación previa:
 
-After the context docs are reviewed:
+- `.quiver/state.json`
+- `AGENTS.md`
+- `docs/AI_CONTEXT.md`
+- `docs/PROJECT_MAP.md`
+- `docs-template/` como señal legacy u opcional
+- `tools/scripts/` como señal legacy u opcional
+- scripts `quiver:*` o scripts legacy en `package.json`
 
-1. Define or refine `specs/<project-slug>/SPEC.md`.
-2. Create the first slice from `specs/<project-slug>/slices/slice-template/slice.json`.
-3. Start work with `npx create-quiver start-slice <slice.json>` or `npm run quiver:start-slice -- <slice.json>`.
-4. Make one commit per slice.
-5. Open one PR per spec.
+Desde la raíz del proyecto:
 
-Slice numbering is local to each spec: every new spec starts at `slice-01`.
-
-## Requirements
+```bash
+npx create-quiver doctor
+npx create-quiver migrate
+npx create-quiver analyze
+npx create-quiver doctor
+npx create-quiver ai onboard --dry-run
+git status --short
+```
 
-- Node.js and npm for the installer
-- Git for slice branches, worktrees, and PR workflow checks
-- macOS, Linux, and Windows PowerShell/CMD are the target developer environments for the cross-platform runtime work
+Si estás en CI, offline o no querés que la migración instale dependencias automáticamente:
 
-Windows native support is verified only when the cross-platform CI matrix is green. Bash remains a legacy compatibility path until the runtime slices land.
+```bash
+npx create-quiver migrate --skip-install
+```
 
-See the generated `docs/SUPPORT_MATRIX.md` for the detailed support contract.
+Qué esperar:
+
+- La migración restaura o agrega archivos faltantes de forma aditiva.
+- No debería sobrescribir archivos existentes de proyecto sin necesidad.
+- Después de migrar, `analyze` actualiza el mapa técnico y `doctor` confirma los próximos pasos.
+- `ai onboard --dry-run` ayuda a validar que el contexto viejo quedó entendible para un agente planner.
+
+Si `doctor` falla indicando que el proyecto no fue inicializado por Quiver, usá el flujo del caso 2.
+
+## ✨ Qué hace
+
+Quiver instala una estructura de trabajo para que un proyecto pueda usar IA sin improvisar contexto en cada tarea:
+
+- documentación base para humanos y agentes;
+- contexto AI-first con roles de planner y executor;
+- specs y slices para dividir trabajo en partes revisables;
+- comandos para planificar, ejecutar y validar trabajo asistido por IA;
+- checks de readiness, PR, handoff y scope;
+- plantillas de contribución, soporte, seguridad, changelog y GitHub Actions.
+
+La idea práctica: primero contexto, después plan, después código.
+
+## 🧱 Stack tecnológico
+
+| Área | Tecnología detectada |
+|---|---|
+| Runtime | Node.js CLI |
+| Lenguaje | JavaScript CommonJS |
+| Package manager | npm (`package-lock.json`) |
+| Binario npm | `create-quiver` -> `bin/create-quiver.js` |
+| Tests | Node built-in test runner (`node:test`) |
+| CI/CD | GitHub Actions |
+| Distribución | Paquete npm público `create-quiver` |
+| Base de datos | No detectada |
+| Docker / Compose | No detectado |
+| Prisma / Supabase / migrations / seeders | No detectados |
+
+## 📦 Requisitos
+
+- Node.js 22.x recomendado. La CI usa Node 22, aunque `package.json` todavía no declara `engines`.
+- npm.
+- Git, especialmente para ramas y worktrees.
+- `shellcheck` si querés replicar localmente el job de CI que valida scripts Bash.
+- Opcional: `gh` para preflight de PR con GitHub.
+- CLI local de `codex`, `claude` o `gemini` si vas a ejecutar comandos de IA sin `--dry-run`.
+
+No se detectaron archivos `.env`; Quiver no requiere variables de entorno para el flujo básico.
+
+## 📁 Estructura del proyecto
+
+| Ruta | Propósito |
+|---|---|
+| `bin/create-quiver.js` | Entry point ejecutable del CLI. |
+| `src/create-quiver/` | Código fuente del CLI y comandos principales. |
+| `src/create-quiver/commands/` | Comandos `ai`, `graph`, `next` y `plan`. |
+| `src/create-quiver/lib/` | Lógica de análisis, doctor, slices, lifecycle, IA, Git y renderers. |
+| `docs/` | Plantillas que Quiver copia a proyectos destino. |
+| `specs/` | Specs internas del desarrollo de Quiver y templates usados cuando `ai plan --phase spec` crea una spec real. |
+| `scripts/` | Scripts de packaging, release, CI smoke y wrappers legacy. |
+| `tests/` | Tests unitarios y fixtures. |
+| `examples/` | Ejemplo mínimo de spec/slice. |
+| `i18n/es/` | Documentación y plantillas en español. |
+| `.github/` | Workflows, templates de issues y PR. |
+
+## ⚙️ Configuración
+
+### Variables opcionales
+
+| Variable | Uso |
+|---|---|
+| `SLICE_WORKTREES_DIR` | Cambia la carpeta donde `start-slice` crea worktrees. |
+| `ALLOW_DRAFT_SLICE=1` | Permite iniciar slices en estado `draft`. Equivale a usar `--allow-draft`. |
+| `QUIVER_VERSION` | Usada por scripts legacy de inicialización. |
+| `QUIVER_MIGRATE` | Activa modo migración en scripts legacy. |
+| `QUIVER_PROJECT_NAME` | Define nombre de proyecto en scripts legacy. |
+
+Para IA sin `--dry-run`, la autenticación depende del proveedor local que uses (`codex`, `claude` o `gemini`). Para PR preflight, Quiver espera que `gh` y tu configuración SSH ya existan; no instala ni modifica credenciales.
+
+## 🧭 Comandos principales
+
+Los comandos reales del CLI se ejecutan con `npx create-quiver ...` o, durante desarrollo local, con `node bin/create-quiver.js ...`.
+
+| Comando | Para qué sirve |
+|---|---|
+| `npx create-quiver init --name "Proyecto"` | Inicializa Quiver en un proyecto nuevo o nunca inicializado. |
+| `npx create-quiver --name "Proyecto"` | Alias compatible del flujo de init recomendado. |
+| `npx create-quiver init --minimal` | Crea solo el contrato esencial de onboarding. |
+| `npx create-quiver init --full` | Crea el layout amplio de compatibilidad. |
+| `npx create-quiver init --legacy-scripts` | Agrega wrappers Bash legacy bajo `tools/scripts/`. |
+| `npx create-quiver init --include-templates` | Exporta templates empaquetados bajo `.quiver/templates/`. |
+| `npx create-quiver analyze` | Genera `.quiver/scans/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md`. |
+| `npx create-quiver doctor` | Valida que el contrato de Quiver esté completo. |
+| `npx create-quiver migrate` | Actualiza proyectos que ya fueron inicializados con Quiver. |
+| `npx create-quiver plan` | Lista slices pendientes en orden y calcula camino crítico. |
+| `npx create-quiver graph` | Muestra el grafo de dependencias (`tree`, `mermaid` o `dot`). |
+| `npx create-quiver next` | Sugiere el próximo slice listo para trabajar. |
+| `npx create-quiver start-slice <slice.json>` | Prepara worktree y contexto para ejecutar un slice. |
+| `npx create-quiver check-slice <slice.json>` | Valida readiness del slice. |
+| `npx create-quiver check-pr <slice.json>` | Valida estructura esperada para PR. |
+| `npx create-quiver check-scope <slice.json>` | Verifica que los archivos modificados estén dentro del alcance declarado. |
+| `npx create-quiver cleanup-slice <slice.json>` | Limpia worktree/branch local asociado a un slice. |
+| `npx create-quiver refresh-active-slices` | Regenera el tablero local `ACTIVE_SLICES.md`. |
+| `npx create-quiver check-handoff <handoff.md>` | Valida un handoff. |
+| `npx create-quiver new-handoff <spec-slug>` | Crea un handoff para una transferencia excepcional. |
+
+### Comandos de IA para WDD + SDD
 
-## Cross-Platform Support
+```bash
+npx create-quiver ai onboard --dry-run
+npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
+npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run
+npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run
+npx create-quiver ai execute-slice --slice specs/<project-slug>/slices/slice-01/slice.json --dry-run
+npx create-quiver ai doctor --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npx create-quiver ai pr --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+```
 
-Quiver is targeting native support on macOS, Linux, and Windows PowerShell/CMD. Bash is a legacy compatibility path until the runtime slices land, so the long-term contract is a Node-first workflow rather than a Bash-first one. The CI matrix must be green before Windows is considered fully verified.
+Providers soportados: `codex`, `claude` y `gemini`, siempre vía CLI local.
+Usá `--dry-run` primero para revisar provider, rol, context pack, prompt y paths sin ejecutar el modelo.
 
-## What Gets Generated
+Orden recomendado:
 
-Quiver generates a project-local workflow under:
+1. `ai onboard`: el planner entiende el repo y el workflow.
+2. `ai plan --phase acceptance`: convierte requerimientos en criterios de aceptación.
+3. `ai plan --phase technical-plan`: propone el plan técnico.
+4. `ai plan --phase spec`: genera spec, slices, handoffs y PR body.
+5. `ai execute-slice`: ejecuta un slice aprobado con rol executor.
+6. `ai doctor` / `ai pr`: valida preflight de GitHub y PR.
 
-- `docs/` for project context, workflow, support, troubleshooting, and AI guidance
-- `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md` after `create-quiver analyze`
-- `docs/AI_ONBOARDING_PROMPT.md` as the generated handoff prompt for the AI agent
-- `specs/<project-slug>/HANDOFF.md` as the exceptional transfer artifact between agents or phases
-- `npx create-quiver new-handoff <spec-slug>` to scaffold an optional handoff artifact when work needs to move between agents or phases
-- `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md` to validate a transferred handoff before execution
-- `docs/COMMANDS.md` as the canonical command reference table for orchestration
-- `specs/<project-slug>/` for the project spec, status, evidence, and slice contracts
-- `tools/scripts/` for slice lifecycle and readiness gates
-- `.github/` for default PR, issue, and CI templates
-- `package.json` scripts for the workflow commands
+## 🧪 Cómo probar que funciona
 
-For the detailed support contract, read `docs/SUPPORT_MATRIX.md` in the generated project. For recovery paths, read `docs/TROUBLESHOOTING.md`.
+Validación rápida del repo:
 
-## Manual Template Use
+```bash
+node bin/create-quiver.js --help
+node --test tests/**/*.test.js
+npm run package:quiver
+```
 
-Use the manual flow only when developing Quiver locally or testing a template checkout. From a target project where this repository was copied as `docs-template/`, run:
+Validaciones adicionales disponibles:
 
 ```bash
-./docs-template/scripts/init-docs.sh "Project Name"
+npm run smoke:create-quiver
+npm run smoke:tiered-pack
 ```
 
-The CLI path is the supported adoption path for users.
-For analyzed projects, the agent handoff prompt lives at `docs/AI_ONBOARDING_PROMPT.md` in the generated project. If a bounded transfer between agents or phases is needed, scaffold `specs/<project-slug>/HANDOFF.md` with `npx create-quiver new-handoff <spec-slug>` and validate it with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md`.
+Notas reales del estado actual:
+
+- No hay script `npm test`; el comando verificado para tests es `node --test tests/**/*.test.js`.
+- `npm run package:quiver` valida el contenido del paquete npm generado.
+- `npm run smoke:tiered-pack` existe, pero revisar la sección "Información pendiente de confirmar" antes de usarlo como gate obligatorio.
+
+## 📜 Scripts npm
+
+| Script | Uso |
+|---|---|
+| `npm run quiver:plan` | Ejecuta `npx create-quiver plan`. |
+| `npm run quiver:graph` | Ejecuta `npx create-quiver graph`. |
+| `npm run quiver:next` | Ejecuta `npx create-quiver next`. |
+| `npm run quiver:ai:onboard` | Ejecuta onboarding de IA. |
+| `npm run quiver:ai:plan` | Ejecuta planificación IA por fases. |
+| `npm run quiver:ai:execute-slice` | Ejecuta un slice con rol executor. |
+| `npm run quiver:ai:doctor` | Ejecuta preflight IA/GitHub. |
+| `npm run quiver:ai:pr` | Ejecuta preflight de PR. |
+| `npm run package:quiver` | Empaqueta y valida el tarball npm. |
+| `npm run smoke:create-quiver` | Smoke del instalador `create-quiver`. |
+| `npm run smoke:tiered-pack` | Smoke de context packs y lifecycle. |
+| `npm run release:quiver` | Release dry-run o publish, según flags. |
 
-## For AI Agents
+`package.json` también contiene scripts legacy como `check:slice`, `check:pr`, `start:slice`, `cleanup:slice` y `migrate` que apuntan a `tools/scripts/*`. En proyectos generados esos wrappers aparecen solo cuando se pide compatibilidad con `--legacy-scripts` o el perfil amplio `--full`; en este repo fuente requieren revisión antes de usarse directamente.
 
-Read `README_FOR_AI.md` before working in this repository or in a generated project. In generated projects, `docs/AI_CONTEXT.md` is the first agent context file to read, followed by `docs/AI_ONBOARDING_PROMPT.md`, `docs/CONTEXTO.md`, and `docs/WORKFLOW.md`.
+## 🔁 Flujo recomendado
 
-## For Maintainers
+1. Inicializá Quiver o migrá si el proyecto ya lo tenía.
+2. Corré `analyze` para generar el mapa técnico.
+3. Corré `doctor` para validar el contrato.
+4. Incorporá al planner con `ai onboard --dry-run`.
+5. Convertí requerimientos en criterios, plan técnico y spec con `ai plan`.
+6. Revisá dependencias con `graph` y elegí el próximo trabajo con `next`.
+7. Ejecutá el slice con `ai execute-slice` o con tu agente usando el handoff generado.
+8. Validá con `check-slice`, `check-scope` y `check-pr`.
+9. Cerrá el trabajo con evidencia en el PR.
 
-Release preflight:
+## 🤝 Contribuir
+
+1. Abrí un issue describiendo el problema o propuesta.
+2. Acordá el alcance antes de implementar si hace falta.
+3. Trabajá en un slice pequeño y revisable.
+4. Incluí evidencia de validación en el PR.
+5. Mantené una relación clara: un slice, un commit; una spec, un PR.
+
+## 🚢 Release
+
+Release dry-run:
 
 ```bash
-npm whoami
-npm view create-quiver version
-npm run package:quiver
-npm run smoke:create-quiver
 npm run release:quiver
 ```
 
-Current-version publish:
+Publicar la versión actual:
 
 ```bash
 bash scripts/release-quiver.sh --publish-current
 ```
 
-Versioned publish:
+Publicar con bump:
 
 ```bash
 bash scripts/release-quiver.sh patch --publish
 ```
 
-The release helper stays explicit on purpose: `--publish-current` publishes the current version, and `--publish` follows a normal version bump flow.
+Antes de publicar, verificá autenticación y estado del paquete:
 
-If `npm whoami` or `npm view create-quiver version` fails, fix npm auth or registry reachability before publishing.
-
-For a first release, prefer `--publish-current` so the published package stays at `0.4.0`.
+```bash
+npm whoami
+npm view create-quiver version
+```
 
-## References
+## 📚 Documentación útil
 
-- [AI guide](./README_FOR_AI.md)
-- [AI context template](./docs/AI_CONTEXT.md.template)
-- [Support matrix template](./docs/SUPPORT_MATRIX.md.template)
-- [Troubleshooting template](./docs/TROUBLESHOOTING.md.template)
+- [README para agentes de IA](./README_FOR_AI.md)
 - [Changelog](./CHANGELOG.md)
 - [Roadmap](./ROADMAP.md)
+- [Backlog](./BACKLOG.md)
+- [Guía de templates](./TEMPLATE.md)
+- [Contribución](./CONTRIBUTING.md)
+- [Seguridad](./SECURITY.md)
+
+## Información pendiente de confirmar
+
+- `package.json` no declara `engines`; la versión mínima real de Node queda pendiente. La CI usa Node 22.
+- `package.json` está en `0.9.0`, igual que `CHANGELOG.md`.
+- `docs/COMMANDS.md.template` marca algunos comandos de IA como `v0.10`, aunque `package.json` todavía está en `0.9.0`; la próxima publicación debe alinear versión y changelog.
+- Los scripts legacy de `package.json` que apuntan a `tools/scripts/*` deben confirmarse para este repo fuente o separarse de los scripts pensados para proyectos generados con `--legacy-scripts` o `--full`.
 
-## License
+## Licencia
 
 MIT