# Qué deja init en tu repo

> La anatomía de lo que escribe ai-first init, pieza por pieza, y qué skill o verificación usa cada una.

`init` deja en el repo todo lo que los protocolos y el detector dan por hecho. Esta página recorre cada pieza: qué es, qué contiene al nacer y quién la lee.

## El árbol

Así queda una carpeta vacía después de `npx @falcux/ai-first@latest init --sin-entrevista`, sin contar `.git/`:

* .agents/

  * skills/

    * protocolo-cambios/

      * SKILL.md

      * references/

        * documento-de-cambio.md

    * protocolo-cierre/

      * SKILL.md

    * protocolo-features/

      * SKILL.md

    * test-fix/

      * SKILL.md

    * version-bump/

      * SKILL.md

* .claude/

  * skills enlace simbólico a ../.agents/skills

* .githooks/

  * pre-push

* .github/

  * workflows/

    * ai-first.yml

* docs/

  * ADR.md

  * SESSION\_LOG.md

  * changes/

    * CHANGE\_LOG.md

    * pending/

      * .gitkeep

* AGENTS.md

* AI-FIRST.md

Además, en la configuración local del repo, `core.hooksPath` queda apuntando a `.githooks`. `init` no escribe `CLAUDE.md`: si usas Claude Code, el template `templates/CLAUDE_MD_TEMPLATE.md` del paquete es una línea, `@AGENTS.md`.

## AI-FIRST.md

El mapa que el detector verifica. Un frontmatter YAML con lo que `init` encontró, cada campo con un comentario que explica para qué es:

* `zonas_prohibidas`: rutas que el agente no modifica sin aprobación explícita. `init` sugiere las que encuentra —carpetas de migraciones, `infra/`, `terraform/`, `LICENSE`— y `.env*` siempre. Tocar una es un **P0**.
* `superficies_de_decision`: rutas donde un cambio se presume decisión arquitectónica, como `**/*.config.*` o los flujos de `.github/workflows/`. Si una se toca y el ADR no gana una fila, es un **P1**. Si no encuentra ninguna, el campo queda comentado.
* `alcance.spec`: la carpeta del cambio en curso, `docs/changes/pending/`.
* `artefactos`: los documentos que hablan de este repo, como `AGENTS.md` y el ADR. El detector comprueba que lo que mencionan exista.

`verificacion`, el comando que decide si el proyecto está sano, sale de los scripts `build` y `test` del `package.json` si los hay. Con entrevista, `fase`, `perfil` y `verificacion` quedan con tus respuestas. Debajo del frontmatter, la sección «Notas» pide la razón de cada zona. La skill `protocolo-arranque` también escribe en este archivo. Campo por campo, en la [referencia de AI-FIRST.md](https://ai-first.falcux.com/docs/referencia/ai-first-md/).

## docs/ADR.md

El registro de decisiones, vacío salvo por sus reglas y un molde comentado de `ADR-001`. Una decisión entra si es difícil de revertir, tenía alternativas reales y alguien va a preguntar por qué dentro de seis meses. No se edita: se agrega una nueva que supera a la vieja.

Lo usan `protocolo-cierre`, `protocolo-features`, `protocolo-cambios`, `protocolo-arranque` e `information-architecture`. La verificación «Decisión sin fila en ADR» busca encabezados `## ADR-` nuevos en él. Si el repo ya tenía un `ADR.md` en la raíz o en `docs/`, `init` usa ése.

## docs/SESSION\_LOG.md

El registro de sesiones: qué se hizo, qué cambió y qué quedó pendiente, con la sesión más reciente arriba. Nace con su cabecera y ninguna entrada. Lo escribe `protocolo-cierre` en su Fase A y lo verifica el humano; `version-bump` lo lee.

## docs/changes/

* `pending/` es donde vive el documento de un cambio mientras está abierto. `protocolo-cambios` lo crea ahí a partir de su molde, `references/documento-de-cambio.md`, y la verificación «Alcance excedido» lee la lista de archivos de esa spec. Nace con un `.gitkeep` para que git la versione vacía.
* `CHANGE_LOG.md` es el resumen permanente de cada cambio cerrado. Al cerrarlo, el documento sale de `pending/` y su resumen queda acá.

## .agents/skills y el enlace .claude/skills

Las skills, copiadas del paquete. Sin entrevista son las cinco que no piden interfaz: `protocolo-features`, `protocolo-cambios`, `protocolo-cierre`, `version-bump` y `test-fix`. Con entrevista, las que pida el perfil del producto, más `protocolo-arranque`. `--skills` elige otras y `--enlazar` deja enlaces simbólicos en vez de copias.

`.agents/skills/` es la carpeta del estándar Agent Skills. `.claude/skills` es un enlace simbólico relativo a ella, porque Claude Code lee su propia carpeta: cada archivo existe una sola vez. Cómo las lee cada herramienta, en [Agentes compatibles](https://ai-first.falcux.com/docs/empezar/agentes/).

## El bloque de AGENTS.md

Si no había `AGENTS.md`, `init` lo crea con una cabecera mínima que apunta al template. Si ya existía, agrega al final un bloque entre dos marcas:

```md
<!-- ai-first:inicio -->
### Metodología AI-First
…
<!-- ai-first:fin -->
```

Dentro va una tabla con cada skill instalada y cuándo se invoca, y otra que traduce el vocabulario del manual a las rutas del repo: registro de sesión, registro de decisiones, cambio en curso. Cada corrida de `init` reescribe lo que hay entre las marcas con lo que encuentra instalado; **fuera de ellas no toca una letra**. Si falta una de las dos marcas, o están al revés, `init` se detiene y te pide arreglarlo a mano.

## .githooks/pre-push y core.hooksPath

El punto de control local. Antes de cada `git push` corre `audit` sobre el rango que vas a publicar, **sin `--estricto`**: imprime todo, pero sólo un P0 interrumpe el push. Si la rama todavía no existe en el remoto, audita el árbol de trabajo.

* Busca el `ai-first` del proyecto, luego el del PATH, y sólo usa `npx --no-install`, que no descarga nada. Si no lo encuentra, avisa y deja pasar el push.
* Si no encuentra `node`, lo busca en las rutas habituales y en `nvm.sh`; si aun así no aparece, avisa y deja pasar.
* Se salta con `git push --no-verify`.

Para que git lo use, `init` fija `core.hooksPath` en `.githooks`, **sólo si estaba sin configurar**. Un `core.hooksPath` de husky o lefthook no se pisa: se reporta como sugerido. Con `--hook-local` el hook va a `.git/hooks/`, que no viaja en el clon; con `--sin-hook` no se escribe. Es un hook de git, no un hook del agente.

## .github/workflows/ai-first.yml

El mismo detector en cada pull request, **con `--estricto`**: acá cualquier hallazgo, P1 o P2 incluidos, deja el check en rojo. Hace checkout con toda la historia, instala Node 22 y corre:

```bash
npx --yes @falcux/ai-first audit --base "origin/${{ github.base_ref }}" --estricto
```

Con `--sin-ci` no se escribe.

## Nunca sobreescribe

Lo que ya existe se salta, se reporta y el comando sigue. Cada línea del reporte tiene uno de tres estados:

| Estado     | Qué significa                                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------------------------- |
| `escrito`  | No existía y `init` lo creó.                                                                                     |
| `saltado`  | Ya existía y no se tocó. Entre paréntesis, la razón si no es «ya existe».                                        |
| `sugerido` | Hacía falta algo en un archivo o una configuración que ya existía; en vez de cambiarlo, `init` dice qué agregar. |

Una skill cuya carpeta ya existe se salta entera, sin fusionar nada dentro. El enlace `.claude/skills` tampoco se crea si ahí ya hay algo. Correr `init` dos veces deja el repo igual.

Nota

Todas las opciones de `init` y el detalle de cada estado están en la [referencia de init](https://ai-first.falcux.com/docs/referencia/init/).

## Próximos pasos

[El formato de AI-FIRST.md](https://ai-first.falcux.com/docs/referencia/ai-first-md/)Cada campo del frontmatter y cómo lo lee el detector.

[ai-first init](https://ai-first.falcux.com/docs/referencia/init/)Todas las opciones y lo que reporta.

[Adoptar en un proyecto existente](https://ai-first.falcux.com/docs/empezar/proyecto-existente/)Qué pasa cuando el repo ya tiene AGENTS.md, hooks o documentación.