Init

---
name: init
description: Inicializa un proyecto para desarrollo guiado por IA (spec-driven) o lo actualiza a la versión instalada del plugin. Úsala con /init, /init --upgrade o al preparar un repo nuevo o existente con AGENTS.md, constitución, arquitectura, despliegue, seguridad, observabilidad, specs y plantillas.
---

# /init — Inicialización de proyecto AI-Driven

Prepara un repositorio para trabajar con el flujo:

```
/init → /specify → /design-spec → /plan → /tasks → /analyze → /implement → /review → /release
```

Diseño y SEO tienen skills propias: `/init` llama a `/design-spec system` y a `/seo`.

Al terminar, el repositorio tiene una fuente de verdad (constitución, arquitectura, specs) que
todos los comandos posteriores leen y respetan.

**Versión del paquete de skills:** `1.13.0` (se escribe en `.ai/project.yaml → skills_version`).

## Argumentos

| Argumento | Efecto |
|---|---|
| `--upgrade` | Pone al día un proyecto ya inicializado con la versión instalada del plugin, sin re-explorar. Sigue `references/upgrade.md`. |
| `--upgrade --redo-design` | Atajo de `/design-spec system --redo-design`: re-extrae el sistema documentado del código. |
| `--upgrade --redo-options [--only <eje> --base <a\|b\|c>]` | Atajo de `/design-spec system --redo-options`: rehace las opciones antes de elegir sistema o afina un solo eje. |
| `--type <frontend\|backend\|fullstack\|mobile\|monorepo\|library>` | Omite la pregunta de tipo de proyecto |
| `--force` | Permite sobrescribir archivos existentes (siempre mostrando diff antes) |
| `--no-explore` | En brownfield, omite los subagentes y solo entrevista |
| `--dry-run` | Muestra qué archivos se crearían sin escribirlos |

## Reglas generales

- **Nunca inventes.** Lo que no se sepa por el código o por el usuario se pregunta o se marca como
  `TODO(init):`.
- **Nunca sobrescribas en silencio.** Si un archivo existe, sigue la política de la Fase 0.
- **No hagas commit ni push.** El usuario revisa y confirma.
- **Nunca despliegues.** `/init` documenta cómo se despliega; desplegar es trabajo de `/release`,
  y a producción solo con aprobación humana explícita.
- **Registra lo que confirma o decide el usuario.** Cuando el usuario confirme un dato o tome una
  decisión (en la entrevista o después), escríbelo en el documento con el marcador
  `(confirmado por el usuario, AAAA-MM-DD)` o `(decisión del usuario, AAAA-MM-DD)`. Esos
  marcadores protegen el contenido en re-sincronizaciones futuras (`references/brownfield.md` §5).
- **Declarado ≠ real.** `.env.example`, los valores por defecto de `config/` y la documentación
  describen la configuración **declarada**, no la que corre. Como `.env` no se lee (secretos), toda
  conclusión que dependa de un valor real no versionado (canal o nivel de log, entorno, driver de
  colas, `APP_DEBUG`…) se marca **no determinada** y se pregunta al usuario en la entrevista: esos
  valores no son secretos. Una brecha que depende de algo no determinado va a "Brechas por
  confirmar", sin severidad, nunca como hecho.
- **Presente ≠ en uso.** Toda herramienta detectada (logs, métricas, escáneres, CI, colas) se
  clasifica como *presente* (está instalada o declarada), *configurada* (tiene configuración para
  este proyecto) o *en uso* (el código o el pipeline la ejercita), con evidencia. Nunca des por
  cubierta una capacidad solo porque su herramienta existe.
- `AGENTS.md` es un **índice corto** (objetivo: < 150 líneas). El detalle vive en `docs/`.
- Todo contenido inferido de código lleva `status: inferred` y requiere revisión humana.
- Escribe los documentos en el idioma que use el usuario y regístralo en `project.yaml → language`.
  Las plantillas están en español: si el idioma es otro, tradúcelas usando los títulos y marcadores
  de `../../shared/vocabulary.md` (los que lee el validador), también las copias de `docs/templates/`.

---

## Fase 0 — Detección

1. **¿Ya inicializado?** Busca `.ai/project.yaml`, `AGENTS.md`, `docs/constitution.md`.
   - Si existe `.ai/project.yaml`: compara su `skills_version` con la versión de este archivo.
     Si es anterior, propone **(a)** `--upgrade` (recomendado). Si no, ofrece **(b)**
     re-sincronizar (re-explorar y proponer cambios en los documentos inferidos siguiendo
     `references/brownfield.md` §5: conserva lo confirmado o decidido por el usuario, no
     reescribe documentos `approved` y pregunta ante contradicciones; sin tocar la constitución),
     **(c)** reiniciar con `--force` (avisa de que se pierden las confirmaciones y decisiones
     registradas, y pide confirmación explícita) o **(d)** cancelar.
   - Si existe `AGENTS.md` o `CLAUDE.md` sin `.ai/project.yaml`: léelos y trátalos como **insumo**
     de la entrevista; al final propone un merge con diff, no un reemplazo.
2. **Metodologías o reglas de agentes en competencia.** Busca instrucciones para agentes que
   definan otro flujo de trabajo: secciones de `CLAUDE.md`/`AGENTS.md` que se declaren
   prioritarias ("overrides", "ALWAYS follow"), AI-DLC (`.aidlc*`, `aidlc-docs/`), Spec Kit
   (`.specify/`, `memory/constitution.md`), `.cursor/rules/`, `.cursorrules`, `.kiro/`,
   `.windsurfrules`, `.github/copilot-instructions.md`, `.clinerules`. Si hay alguna, sigue
   `references/brownfield.md` §1 y **pregunta** antes de tocar nada: pausar (mover literalmente a
   un archivo propio que no se carga por defecto), migrar (sus specs a `docs/specs/`) o convivir
   (documentar qué flujo manda en cada caso).
3. **¿Greenfield o brownfield?** Es brownfield si se cumple **al menos una**:
   - Existe un manifiesto: `package.json`, `pyproject.toml`, `requirements.txt`, `go.mod`,
     `Cargo.toml`, `pom.xml`, `build.gradle*`, `composer.json`, `Gemfile`, `*.csproj`, `pubspec.yaml`.
   - Hay más de ~10 archivos de código fuente fuera de carpetas de configuración.
   - `git rev-list --count HEAD` > 5.

   Si las señales son contradictorias (p. ej. manifiesto vacío, repo con solo un README), pregunta.
   **Andamiaje recién generado** (manifiesto, pero todo el código viene de una plantilla como
   `ionic start` o `npm create vite`, sin specs ni tests propios): pregunta si tratarlo como
   proyecto nuevo (recomendado) y sigue `references/greenfield.md` §1; no explores ni infieras
   specs del código de ejemplo.
4. **Tipo de proyecto** (si no vino `--type`): en brownfield infiérelo y pide confirmación; en
   greenfield pregúntalo. Señales por tipo en `references/project-types.md` §1 (una app híbrida es
   `mobile`; en monorepo, el tipo va por paquete).
5. **Interfaz y diseño** (`frontend`, `fullstack`, `mobile`): en brownfield, pregunta ahora si
   documentar el diseño existente, sin cambiar código (`../design-spec/references/system-mode.md`
   §3); con un no, `design.status: declined`. En greenfield se decide en la entrevista.
6. **SEO** (sitio web público): pregunta si debe aparecer en buscadores
   (`../seo/references/audit.md` §1); registra el bloque `seo` (`declined` si no lo quiere).

Informa en una línea qué detectaste antes de continuar.

---

## Fase 1 — Exploración (solo brownfield)

Omitir con `--no-explore` o en greenfield.

Lanza **en paralelo** los subagentes de solo lectura (tipo `Explore` si existe). Los prompts
exactos están en `references/explore-agents.md`:

| Subagente | Produce |
|---|---|
| A. Arquitectura | Capas, módulos, dependencias, flujo de datos, integraciones externas, despliegue |
| B. Dominio y features | Inventario de features con evidencia (rutas, archivos, tests) y specs previas en otros formatos |
| C. Convenciones | Estilo, naming, estructura, patrones, lint/format, commits |
| D. Tooling, calidad y despliegue | Comandos build/test/lint/dev, CI, cobertura, variables de entorno, pipelines de deploy, entornos, rollback |
| E. Seguridad | Autenticación y autorización, datos sensibles, puntos de entrada, manejo de secretos, herramientas de seguridad existentes, riesgos evidentes |
| F. Observabilidad y auditoría | Qué se registra realmente: configuración de logs, emisión desde el código, correlación de peticiones, eventos de auditoría, datos sensibles en logs, métricas y alertas |
| G. Interfaz y diseño (solo si el usuario aceptó documentarlo) | Tokens declarados y valores fijos, tipografía, componentes y sus estados, pantallas principales |
| H. SEO técnico (solo si el sitio es indexable) | Renderizado, rutas, fuentes de metadatos, robots y sitemap, hosting, build y carpeta de salida |

Cada subagente devuelve un informe estructurado con **evidencia** (rutas de archivo) y un nivel de
confianza (`alta`/`media`/`baja`) por hallazgo. No generan documentos: solo informan.
Si el entorno no permite subagentes, o el proyecto es pequeño (menos de ~20 archivos de código),
ejecuta las exploraciones tú mismo en secuencia con los mismos prompts y dilo en el resumen.

Después, **consolida**:
- Unifica el inventario de features (subagente B) y deduplica.
- Lista contradicciones entre informes y lo que no se pudo determinar → pasa a la entrevista.
- Si el inventario tiene más de 15 features, agrúpalas por dominio y pregunta al usuario cuáles
  documentar ahora; el resto queda listado en `docs/specs/README.md` como pendiente.

---

## Fase 2 — Entrevista

Sigue `references/interview.md`. Principios:
- Pregunta solo lo que **no** sepas. En brownfield, presenta lo inferido y pide confirmación.
- Usa preguntas de opción múltiple cuando sea posible, máximo 4 por ronda; omite las rondas cuyas
  respuestas ya conozcas.
- Si el usuario no está disponible (sesión desatendida), toma la opción más conservadora,
  márcala como `TODO(init): confirmar` y continúa.

Bloques obligatorios:
1. Propósito del proyecto y usuarios objetivo.
2. Tipo de proyecto y stack (confirmar o definir).
3. Principios innegociables (proponer un borrador según el tipo; el usuario edita).
4. Estrategia de testing y definición de "terminado".
5. Etapa actual y próximos objetivos (→ roadmap).
6. Despliegue: entornos, plataforma, quién aprueba producción y cómo se revierte
   (→ `docs/deployment.md`). En prototipos sin despliegue aún, registra `deploy.strategy: none`
   y marca la sección como `TODO(init)`.
7. Seguridad: clasificación de datos, modelo de autenticación y autorización, nivel ASVS
   objetivo y herramientas de seguridad (→ `docs/security.md`).
8. Observabilidad y auditoría: qué eventos deben quedar registrados, obligaciones legales de
   registro de accesos, retención y quién puede leer los registros (→ `docs/observability.md`).
9. Diseño (greenfield con interfaz): lo conduce `/design-spec system` (nicho y Ronda 4b).
10. SEO (sitio indexable): URL canónica, idiomas y qué no se indexa (Ronda 4c, para `/seo`).

---

## Fase 3 — Generación

Genera en este orden, usando las plantillas de `templates/` (carpeta junto a este `SKILL.md`).
Sustituye cada `{{placeholder}}`; lo que quede sin dato se convierte en `TODO(init): …`. Elimina
las secciones marcadas `<!-- if … -->` que no apliquen y quita los marcadores de las que sí (el
contenido se queda).

1. `.ai/project.yaml` ← `templates/project.yaml`
2. `docs/constitution.md` ← `templates/constitution.md` (en brownfield conserva el bloque
   "Código previo"; en greenfield elimínalo).
3. `docs/architecture.md` ← `templates/architecture.md`
   - Greenfield: arquitectura **propuesta**, marcada `status: proposed`.
   - Brownfield: arquitectura **observada**, `status: inferred`, con evidencia.
4. `docs/adr/0001-registro-de-decisiones.md` ← `templates/adr.md` (ADR inicial *"Registrar
   decisiones arquitectónicas mediante ADRs"*, `status: accepted`). En brownfield, crea ADRs
   adicionales solo para decisiones evidentes (framework, base de datos), marcados como
   "registrados a posteriori".
5. `docs/specs/` (solo brownfield), siguiendo las convenciones de `references/brownfield.md` §2:
   - `docs/specs/README.md` con el inventario completo y estado de cada spec.
   - Por cada feature seleccionada: `docs/specs/NNN-<slug>/spec.md` ← `templates/spec.md`,
     con `status: inferred`. Documenta lo que el código **hace**, no lo que debería hacer.
   - Specs previas en otros formatos: migración según `references/brownfield.md` §3.
6. `docs/deployment.md` ← `templates/deployment.md`
   - Greenfield: `status: proposed` con la estrategia acordada en la entrevista.
   - Brownfield: `status: inferred`, a partir de pipelines, Dockerfiles, IaC y scripts reales.
   - Si no hay procedimiento de rollback conocido, déjalo como `TODO(init)` y repórtalo como
     riesgo en el resumen: es el hueco más peligroso del documento.
   - `mobile` sin backend: no hay flag remoto para apagar una feature publicada; regístralo como
     riesgo `RD` con sus correcciones (publicación escalonada, prueba de actualización desde la
     versión instalada).
7. `docs/security.md` ← `templates/security.md`
   - Greenfield: `status: proposed`; propone herramientas según el stack (secretos, SAST, SCA,
     contenedores). En `.ai/project.yaml → security.tools` cada una lleva su estado
     (`propuesta` · `instalada` · `en-ci` · `no-aplica`): las skills solo ejecutan las `instalada` o
     `en-ci`, y una
     `propuesta` se reporta como pendiente, nunca como control activo. Antes de proponer una
     herramienta, comprueba que no envía código ni metadatos a un servicio que `docs/security.md` no
     aprueba (p. ej. `semgrep --config auto` exige métricas: propone reglas fijadas con
     `--metrics=off`).
   - Brownfield: `status: inferred`, a partir del subagente E.
   - Registra la edición vigente del OWASP Top 10 en "Referencias".
   - Numera cada riesgo (`RS1`, `RS2`…) y cada corrección que propone (`RS1.a`, `RS1.b`…), con su
     estado. Haz lo mismo con las brechas de `observability.md` (`OB`) y los riesgos de
     `deployment.md` (`RD`).
8. `docs/observability.md` ← `templates/observability.md`
   - Greenfield: `status: proposed` con los eventos de auditoría acordados.
   - Brownfield: `status: inferred`, a partir del subagente F, marcando cada capacidad como
     presente / configurada / en uso. Los huecos (sin correlación, sin auditoría, datos
     sensibles en logs, nivel `debug` por defecto) van a "Brechas".
8b. `docs/seo.md` (sitio indexable): `/seo setup` en greenfield; `/seo audit` en brownfield
   (auditoría sobre la build y brechas `SE`).
9. `docs/roadmap.md` ← `templates/roadmap.md`. Si el roadmap ya existe (re-sincronización),
   no lo regeneres: concilia las brechas de observabilidad, seguridad, despliegue y SEO con
   `references/brownfield.md` §4. Si es nuevo, las brechas prioritarias entran como objetivos.
   Un objetivo que nace de un riesgo **cita cada corrección** en su criterio de éxito: las que
   cubre y las que deja fuera con su destino (otro objetivo, spec o excepción). No resumas: si el
   riesgo propone cuatro correcciones, el objetivo nombra las cuatro. Pregunta al usuario por
   las que propones dejar fuera.
9a. **Diseño** (proyectos con interfaz): `/design-spec system` (opciones y sistema elegido en
    greenfield; sistema extraído y deuda `DS` en brownfield aceptado). Bloque `design` de
    `.ai/project.yaml` en ambos casos (`declined` si el usuario no lo quiso).
9b. `docs/specs/README.md` con la tabla de specs (vacía en greenfield): `AGENTS.md` la enlaza.
10. `docs/templates/` ← copia `templates/spec.md`, `templates/plan.md`, `templates/tasks.md`,
    `templates/review.md` y `templates/adr.md` para que los usen las demás skills. Después del
    paso 11, guarda sus huellas en `project.yaml` con `python .ai/bin/aidd.py templates --yaml`
    (`--upgrade` las usa para saber si el usuario las personalizó).
11. `.ai/bin/aidd.py` ← copia de `../../scripts/aidd.py` (validadores; así CI no depende del
    plugin). Propón añadir `.ai/cache/` al `.gitignore` (copias locales para `/analyze` delta).
12. **CI (opcional, pregunta):** si el proyecto usa GitHub, propone
    `.github/workflows/ai-dd.yml` ← `templates/ci/github-actions-aidd.yml`, rellenado con los
    comandos de `AGENTS.md` y `security.tools`; quita los pasos con `command: null` o
    `no-aplica`. Una herramienta `propuesta` que se añade a CI se instala en el job y su `status`
    pasa a `en-ci`.
    La plantilla revisa solo lo que cambia cada PR (modo baseline), para que la deuda previa no
    bloquee todos los PRs. Es una ruta protegida: créala solo con confirmación explícita. Si usa
    otra plataforma de CI, describe los pasos equivalentes en `docs/deployment.md`.
13. `CHANGELOG.md` ← `templates/CHANGELOG.md` (solo si no existe; si existe, respeta su formato).
14. `AGENTS.md` ← `templates/AGENTS.md` (se escribe al final porque enlaza todo lo anterior).
15. `CLAUDE.md` ← `templates/CLAUDE.md` (si no existe; si existe, añade `@AGENTS.md` al inicio y
    conserva el resto, salvo lo que el usuario decidió pausar o migrar en la Fase 0).

### Fase 3b — Proyecto base (solo greenfield)

Sigue `references/greenfield.md` §2 y §3: propone crear el proyecto base con el comando oficial de
la plantilla (o hacerlo en la spec 001), verifica sus dependencias en una tabla para el ADR del
stack, fija en `AGENTS.md` los comandos reales y audita los valores por defecto de la plantilla
contra la constitución (versiones mínimas, permisos, copias de seguridad, tamaños de control…).
Sin este paso, `/implement` no tiene comandos que ejecutar.

### Secciones condicionales por tipo

Aplica `references/project-types.md` §2 según `project.type` (en monorepo, por paquete): qué
incluye la arquitectura, qué principios propone la constitución y qué skills se habilitan.

---

## Fase 4 — Verificación

1. **Instalación:** antes de instalar dependencias, pide confirmación al usuario. En greenfield, si
   el proyecto base se dejó para la spec 001, registra `verification: []` con la nota y continúa. En brownfield,
   pregunta si el repositorio es suyo o de confianza: instalar ejecuta scripts de ciclo de vida
   de las dependencias (`postinstall`, etc.) con los permisos del usuario. Si no es de confianza,
   usa el modo sin scripts del gestor (p. ej. `npm ci --ignore-scripts`, `pnpm install
   --ignore-scripts`) o no instales, y registra la limitación.
   Después ejecuta los comandos declarados en `AGENTS.md` (lint, test, build) con timeout
   razonable. **No** ejecutes comandos de despliegue, migraciones sobre bases reales ni nada que
   escriba fuera del repo. Registra el resultado en `.ai/project.yaml → verification`.
   Si un comando falla, no lo borres: márcalo con `# ⚠ falló en /init: <motivo breve>`.
2. Comprueba que cada enlace relativo en `AGENTS.md` apunta a un archivo existente.
3. Comprueba que `AGENTS.md` no supera ~150 líneas; si lo hace, mueve detalle a `docs/`.
4. Comprueba que no quedan `{{placeholders}}` sin sustituir (excepto en `docs/templates/`, que
   los conserva a propósito, y las expresiones `${{ … }}` de GitHub Actions, que son sintaxis
   propia del workflow).
5. Detecta el intérprete que funciona (el primero de `python3`, `python` o `py` cuyo `--version`
   responda 3.8+; en Windows `python3` puede ser un acceso directo de Microsoft Store que no
   funciona) y ejecuta con él `.ai/bin/aidd.py validate`; corrige los errores de formato. Si no
   hay ninguno, avisa: sin Python el hook de guardia queda desactivado en silencio y los
   validadores no corren.
6. Explica al usuario el modo `workflow.enforcement` (por defecto `warn`: el hook pide aprobación
   antes de editar código sin spec activa, tocar rutas protegidas o añadir dependencias).

---

## Fase 5 — Resumen

Entrega al usuario, sin recapitular los pasos:
- Lista de archivos creados/modificados, y qué se pausó o migró en la Fase 0.
- Qué requiere revisión humana (todo lo `inferred`, `proposed` y cada `TODO(init)`), con conteo.
- Resultado de la verificación de comandos.
- Estado de `docs/deployment.md`, destacando si falta el procedimiento de rollback.
- Estado de `docs/security.md`: herramientas configuradas o pendientes, y riesgos evidentes
  detectados en brownfield (sin detallar vectores de explotación).
- Estado de `docs/observability.md`: qué capacidades están solo presentes y no en uso, y si
  falta el registro de auditoría de accesos a datos sensibles.
- Diseño: opciones generadas y elegida, o sistema extraído con su deuda `DS`, con las rutas de los
  HTML para abrirlos; o `declined`.
- SEO: rutas auditadas sobre la build, brechas `SE` y por confirmar; o `declined`.
- Conciliación con el roadmap (si ya existía): brechas cubiertas por objetivos existentes,
  propuestas aplicadas o rechazadas y lo que los objetivos del usuario mencionan y la
  exploración no detectó.
- Siguiente paso sugerido: revisar y aprobar `docs/constitution.md`, luego `/specify` para la
  primera feature.

---

## Contrato con las demás skills

Las reglas que comparten todas las skills del flujo (estados, numeración, puertas de
aprobación) viven en `../../shared/contract.md`. Léelo antes de generar y respétalo.