Primeros pasos

Qué deja init en tu repo

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/:

Directorio.agents/
- Directorioskills/
  - Directorioprotocolo-cambios/
    SKILL.md
    Directorioreferences/
    documento-de-cambio.md
  - Directorioprotocolo-cierre/
    SKILL.md
  - Directorioprotocolo-features/
    SKILL.md
  - Directoriotest-fix/
    SKILL.md
  - Directorioversion-bump/
    SKILL.md
Directorio.claude/
- skills enlace simbólico a ../.agents/skills
Directorio.githooks/
- pre-push
Directorio.github/
- Directorioworkflows/
  - ai-first.yml
Directoriodocs/
- ADR.md
- SESSION_LOG.md
- Directoriochanges/
  - CHANGE_LOG.md
  - Directoriopending/
    .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.

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.

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:

<!-- 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:

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.

Próximos pasos

El formato de AI-FIRST.mdCada campo del frontmatter y cómo lo lee el detector.

ai-first initTodas las opciones y lo que reporta.

Adoptar en un proyecto existenteQué pasa cuando el repo ya tiene AGENTS.md, hooks o documentación.