Adoptar en un proyecto existente

init está pensado para correr sobre un repo con historia. No sobreescribe nada: lo que ya existe se salta y se reporta, y lo que haría falta cambiar en un archivo tuyo se sugiere en vez de escribirse. Esta página dice qué pasa con cada cosa que ya tengas y qué revisar al terminar.

Correrlo

Desde la raíz del repo:

npx @falcux/ai-first@latest init

Para dejar fuera el hook, el flujo de CI o la entrevista, mira Qué dejar fuera.

Lo que ya tienes

Si ya hay…	init…
AGENTS.md	Agrega al final su bloque entre <!-- ai-first:inicio --> y <!-- ai-first:fin -->. El resto del archivo queda igual.
AI-FIRST.md	Lo salta. Si le falta alcance.spec, lo reporta como sugerido con la línea que añadir.
ADR.md en la raíz o en docs/	Lo usa como registro de decisiones y no crea otro.
docs/SESSION_LOG.md o docs/changes/CHANGE_LOG.md	Los salta.
Una skill con el mismo nombre en .agents/skills/	Salta la carpeta entera, sin fusionar nada dentro.
.claude/skills como directorio real	Lo deja como está y lo reporta: un enlace encima habría creado .claude/skills/skills.
core.hooksPath apuntando a otro sitio, como el de husky o lefthook	No lo cambia. Escribe .githooks/pre-push igual y reporta la configuración como sugerida.
.github/workflows/ai-first.yml	Lo salta.

Este es el reporte real sobre un repo con AGENTS.md, package.json, una carpeta migrations/, componentes en src/components/ y core.hooksPath apuntando a .husky, corrido sin terminal interactiva:

ai-first init — tienda

  escrito  AI-FIRST.md
  escrito  docs/ADR.md
  escrito  docs/SESSION_LOG.md
  escrito  docs/changes/CHANGE_LOG.md
  escrito  docs/changes/pending/.gitkeep
  escrito  .agents/skills/protocolo-features
  escrito  .agents/skills/protocolo-cambios
  escrito  .agents/skills/protocolo-cierre
  escrito  .agents/skills/version-bump
  escrito  .agents/skills/test-fix
  escrito  .claude/skills
  escrito  .githooks/pre-push
  sugerido core.hooksPath — ya apunta a .husky; mueve el hook ahí o cambia la configuración a .githooks
  escrito  .github/workflows/ai-first.yml
  escrito  AGENTS.md

  Sin entrevista: no hay terminal interactiva.

  2 Zonas Prohibidas sugeridas: migrations/, .env*
  1 superficie de decisión: **/*.config.*
  2 artefactos declarados

Revisa AI-FIRST.md —sobre todo las razones de cada zona— y AGENTS.md, y luego corre `ai-first audit`.

La línea escrito AGENTS.md significa que se agregó el bloque, no que se reemplazó el archivo. Una segunda corrida sobre el mismo repo reporta todo como saltado, y AGENTS.md con la razón «el bloque ya está al día».

La entrevista, en un repo documentado

init considera que el proyecto ya está documentado si encuentra AI-FIRST.md, AGENTS.md o algún .md bajo docs/ que git no ignore, sin contar los que init mismo escribe. En ese caso, en una terminal interactiva, dice qué encontró y ofrece la entrevista con saltarla como valor por defecto:

¿Entrevistar de todos modos? [s/N]

Las skills se instalan igual; la entrevista sólo sirve para adaptarlas. Para entrevistar sin la pregunta previa:

npx @falcux/ai-first@latest init --entrevista

Sin terminal interactiva —en CI, con la entrada redirigida o desde otro comando— no se entrevista nunca, y el reporte lo dice. --entrevista en ese caso es un error de uso.

Revisa las Zonas Prohibidas

init sugiere zonas por lo que encuentra —carpetas de migraciones, infra/, terraform/, LICENSE— y agrega .env* siempre. En el repo del ejemplo, el AI-FIRST.md quedó así:

zonas_prohibidas:
  - ruta: "migrations/"
    razon: "esquema de base de datos"
    desde: 2026-09-23
  - ruta: ".env*"
    razon: "credenciales"
    desde: 2026-09-23

La razón por defecto es genérica. Cámbiala por lo que cuesta revertir un error ahí, quita las que no sean tuyas y agrega las que init no puede adivinar. Pocas zonas: si todo es prohibido, nada lo es.

Revisa también superficies_de_decision y, si tienes componentes, las dos líneas comentadas de artefactos que activan la verificación de inventario:

  # Hay componentes en src/components/. Para vigilar su inventario, descomenta:
  # inventario_componentes: docs/COMPONENTES.md
  # componentes_dir: "src/components/"

Después corre npx @falcux/ai-first@latest audit y haz el commit.

Qué dejar fuera

Opción	Efecto
--sin-hook	No escribe el hook de git ni toca core.hooksPath.
--hook-local	El hook va a .git/hooks/, que no viaja en el clon, y la configuración del repo no se toca.
--sin-ci	No escribe .github/workflows/ai-first.yml.
--sin-entrevista	No entrevista nunca.

--sin-hook y --hook-local se contradicen: juntas son un error de uso. Si ya usas husky o lefthook, el reporte te da dos salidas: mover el hook a la carpeta que ya usas o cambiar la configuración a .githooks. La lista completa de opciones está en la referencia de init.

Instalar sólo las skills, sin la CLI

Si no quieres correr init, puedes copiar las skills a mano. Es lo mismo que hace el comando con ellas, sin el resto: no escribe AI-FIRST.md, ni el ADR, ni el hook. Primero trae la carpeta skills/ del paquete:

Desde npm

npm pack @falcux/ai-first@latest
tar -xzf falcux-ai-first-*.tgz
origen=package/skills

Desde git

git clone --depth 1 https://github.com/HoruxDeEdfu/falcux-ai-first-package.git
origen=falcux-ai-first-package/skills

Y después, desde la raíz de tu proyecto:

mkdir -p .agents/skills

# Copia sólo las que tu proyecto no tenga ya
for carpeta in "$origen"/*/; do
  nombre=$(basename "$carpeta")
  if [ -e ".agents/skills/$nombre" ]; then
    echo "saltada: $nombre — ya existe en tu proyecto"
  else
    cp -r "$carpeta" ".agents/skills/$nombre"
  fi
done

# Un solo enlace para Claude Code, si no hay nada en su sitio
mkdir -p .claude
[ -e .claude/skills ] || ln -s ../.agents/skills .claude/skills

Al terminar, borra lo que descargaste: la carpeta package/ y el .tgz, o el clon.

El bucle copia las once; init, por defecto, sólo cinco. Borra las que no vayas a usar todavía. Salta la carpeta entera cuando el nombre ya existe, en vez de fusionarla: copiar sin más habría pisado tu SKILL.md y dejado los archivos de apoyo del paquete dentro de tu skill, en silencio. El enlace tampoco se crea si .claude/skills ya es algo, porque sobre un directorio real te dejaría un .claude/skills/skills que no lee nadie.

Precaución

Una skill copiada a mano no está adaptada. Cada una trae al final la sección «Adaptación a tu proyecto» con lo que hay que cambiar; sin eso ocupa presupuesto de carga y da instrucciones que no aplican a tu stack. La entrevista de init hace esa adaptación por ti.

Si un nombre ya está ocupado

Seis skills llevan nombres de oficio —i18n, test-fix, version-bump, ux-writer, ux-audit, information-architecture— y tu proyecto puede tener ya una con alguno. Tienes tres salidas:

• Quedarte con la tuya. No hagas nada: el bucle ya la saltó.

• Quedarte con la del paquete. Borra la tuya y vuelve a correr el bucle.

• Tener las dos. Copia la del paquete con el prefijo ai-first- y cambia el name: de su frontmatter para que coincida con la carpeta:

  cp -r "$origen/i18n" .agents/skills/ai-first-i18n

  Las demás skills la siguen nombrando i18n, así que deja escrita la equivalencia en tu AGENTS.md mientras convivan.

Próximos pasos

Qué deja init en tu repoCada pieza y quién la lee.

Adaptar las skillsLa entrevista y lo que queda por hacer a mano.

Auditar en local y en CIEl hook, el flujo de CI y cómo leer lo que reportan.