Comandos

ai-first init

init deja un repositorio listo para la metodología en un comando: escribe AI-FIRST.md y los registros que los protocolos asumen, instala las skills, monta el punto de control y mantiene un bloque en AGENTS.md. Nunca sobreescribe: lo que ya existe se salta y se reporta.

Uso

ai-first init  [--raiz <dir>] [--enlazar] [--skills <lista>|todas]
               [--entrevista | --sin-entrevista]
               [--sin-hook] [--hook-local] [--sin-ci]

Para correrlo sin instalar nada, desde la raíz del proyecto:

npx @falcux/ai-first@latest init

El @latest importa: si alguna vez corriste una versión anterior, npx puede reutilizar la que guardó en su caché sin preguntarle al registro. Y el subcomando también: npx @falcux/ai-first a secas sólo imprime la ayuda.

Qué escribe

En este orden, que es también el del reporte:

.git/, sólo si la carpeta todavía no era un repositorio: corre git init y sigue. No crea commits.
AI-FIRST.md, con lo que encontró el escaneo: Zonas Prohibidas sugeridas, superficies de decisión y documentos existentes. El formato está en El formato de AI-FIRST.md.
docs/ADR.md, vacío salvo por su cabecera y el molde de una fila entre comentarios. Si el repo ya tiene ADR.md o docs/ADR.md, se usa ése.
docs/SESSION_LOG.md y docs/changes/CHANGE_LOG.md, con su cabecera, y docs/changes/pending/, que se crea con un .gitkeep.
Las skills, cada una en .agents/skills/<nombre>/. Cuáles, en Qué skills instala.
La adaptación de cada skill, sólo si hubo entrevista: un bloque dentro de su sección «Adaptación a tu proyecto».
.claude/skills, un enlace simbólico relativo a .agents/skills/ para que Claude Code las lea.
El hook de git: .githooks/pre-push, ejecutable, y core.hooksPath apuntando a .githooks en la configuración local del repo. Con --hook-local va a .git/hooks/pre-push y la configuración no se toca.
.github/workflows/ai-first.yml, el flujo de integración continua.
El bloque de AGENTS.md, entre  y : qué skills hay instaladas, cuándo se invoca cada una y dónde escribe cada una. Si AGENTS.md no existe, lo crea con una cabecera mínima que apunta al template.

La configuración de git que toca es sólo la del repo, y sólo core.hooksPath cuando estaba vacía. La global del usuario, nunca.

Qué busca el escaneo

init no pregunta lo que puede deducir. Mira los archivos que git conoce, seguidos o nuevos no ignorados:

Qué	Dónde lo busca	Qué hace con ello
Nombre del proyecto	`name` de `package.json`, sin el scope; si no hay, el nombre de la carpeta	`proyecto`
Comando de verificación	Los scripts `build` y `test` de `package.json`, con el gestor que indique el lockfile	`verificacion`; sin scripts, queda comentado
Zonas Prohibidas	`migrations/`, `prisma/migrations/`, `supabase/migrations/`, `db/migrations/`, `infra/`, `terraform/` y `LICENSE`, si existen. `.env*` se sugiere siempre	`zonas_prohibidas`, con una razón por defecto que tienes que revisar
Superficies de decisión	`*/.config.`, `/schema.prisma`, `pnpm-workspace.yaml`, `turbo.json`, `Dockerfile`, `docker-compose.yml`, `wrangler.`, `vercel.json`, `netlify.toml`, `.github/workflows/.yml`, si alguno coincide	`superficies_de_decision`; sin coincidencias, queda comentado
Documentos	`AGENTS.md`, `ARQUITECTURA.md`, `GUIA_DISENO.md`, `TECH_NOTES.md`, `SESSION_LOG.md`, `CHANGE_LOG.md`, `COMPONENT_LIBRARY.md` y sus variantes, en la raíz o en `docs/`	`artefactos`, más `adr` y `agents` siempre
Carpeta de componentes	`src/components/`, `components/`, `app/components/`, `packages/ui/src/components/`	Deja comentadas las dos claves del check 5 para que las actives tú

Opciones

Opción	Qué hace	Por defecto
`--raiz <dir>`	Raíz del repositorio.	El directorio actual
`--enlazar`	Instala las skills como enlaces simbólicos relativos a la carpeta `skills/` del paquete, en vez de copiarlas. Para el repo del paquete y para quien lo vendoriza en un monorepo. Una skill enlazada nunca se adapta.	Copia
`--skills <lista>`	Cuáles instalar, separadas por comas, o `todas`. Un nombre que el paquete no trae detiene el comando antes de instalar nada.	Ver Qué skills instala
`--entrevista`	Entrevista aunque el proyecto ya esté documentado. Necesita una terminal interactiva.	Entrevista sólo si el proyecto no tiene documentación
`--sin-entrevista`	No entrevista nunca, ni en un repo vacío.	—
`--sin-hook`	No escribe el hook de git ni toca `core.hooksPath`.	Escribe el hook
`--hook-local`	El hook va a `.git/hooks/`, que no viaja en el clon, y la configuración del repo no se toca.	`.githooks/`, que sí viaja y se revisa en un PR
`--sin-ci`	No escribe el flujo de integración continua.	Lo escribe

--entrevista y --sin-entrevista se contradicen, igual que --sin-hook y --hook-local: pasar las dos de un par sale con 2.

Qué skills instala

Situación	Qué instala
Sin `--skills` y sin entrevista	Las cinco que no piden interfaz: `protocolo-features`, `protocolo-cambios`, `protocolo-cierre`, `version-bump` y `test-fix`
Sin `--skills`, con entrevista	Las que pide el perfil del producto, más `protocolo-arranque`
`--skills todas`	Las once
`--skills protocolo-ux,i18n`	Exactamente ésas, con o sin entrevista

Lo que pide cada perfil, según la respuesta a «¿Qué clase de producto es?»:

Producto	Skills
`saas`, `movil`	Las cinco de base, `protocolo-ux`, `ux-writer`, `ux-audit` e `information-architecture`
`landing`	Las cinco de base, `protocolo-ux`, `ux-writer` y `ux-audit`
`api`, `cli`	Las cinco de base

i18n no la instala ningún perfil: entra sólo con --skills. protocolo-arranque entra con la entrevista porque es la skill que se usa una vez, al principio; en un repo ya definido sobra. El catálogo completo está en Las 11 skills.

Nunca sobreescribe

Ni archivos, ni carpetas, ni enlaces. Cada ítem del reporte termina en uno de tres estados:

Estado	Qué significa
`escrito`	No existía y se creó.
`saltado`	Ya existía y no se tocó. Si la razón no es «ya existe», se dice entre paréntesis.
`sugerido`	Hacía falta escribir en algo que ya existía. No se escribe: se dice qué añadir.

Los casos concretos:

Una skill que ya existe se salta entera. No se fusiona nada dentro de su carpeta.
AI-FIRST.md existente se salta. Si le falta alcance.spec, se reporta como sugerido con la línea que falta; si ya la tiene, como saltado.
.claude/skills se salta si ya hay algo ahí. Si es un directorio real y no un enlace, se dice: crear el enlace dentro habría dejado un .claude/skills/skills que no lee nadie.
core.hooksPath ya configurado con otra carpeta, por ejemplo la de husky o lefthook, no se pisa: queda sugerido, con la carpeta a la que apunta.
Una skill instalada con --enlazar no se adapta: queda sugerida, porque escribir ahí cambiaría la carpeta del paquete y no tu copia.
AGENTS.md es la excepción razonada: su bloque se reescribe en cada corrida, pero sólo lo que está entre las marcas. Fuera de ellas no cambia una letra. Si el bloque ya está al día, se reporta saltado. Una marca sin su pareja, o las dos al revés, detiene el comando: un bloque roto se arregla a mano.

Correrlo dos veces deja el repo igual.

La entrevista

Pregunta lo que no se puede deducir y lo escribe donde corresponde. Nada de ella llama a un modelo: definir el producto —PRD, arquitectura, specs— es trabajo de la skill protocolo-arranque, que corre tu agente.

Cuándo se entrevista

Un proyecto sin documentación se entrevista sin preguntar.
Un proyecto documentado recibe la oferta, con saltarla como valor por defecto ([s/N]). Cuenta como documentado si git ya conoce AI-FIRST.md, AGENTS.md o algún .md bajo docs/, sin contar los que escribe el propio init.
Con --entrevista se entrevista siempre; con --sin-entrevista, nunca.
Sin terminal interactiva, como en integración continua, no se entrevista nunca, y el reporte lo dice con la línea Sin entrevista: no hay terminal interactiva.

Todo lo que puede fallar por uso —un nombre de skill que no existe, un bloque roto en AGENTS.md— se comprueba antes de la primera pregunta. Si cancelas a mitad, con Ctrl+C o Ctrl+D, no se escribe nada más; lo único que puede haber quedado es el git init de una carpeta que no era repositorio.

Las preguntas

Todas tienen un valor por defecto entre corchetes, y Enter lo acepta. En las de opción vale el valor, su número en la lista o un prefijo sin ambigüedad.

Pregunta	Tipo	Por defecto	Dónde va
¿Cómo se llama el proyecto?	texto	El nombre deducido	`proyecto` en `AI-FIRST.md`
¿En qué fase está?	`exploracion`, `mvp`, `produccion`	`exploracion`	`fase`
¿Qué clase de producto es?	`saas`, `landing`, `api`, `cli`, `movil`	`saas`	`perfil.producto`; decide las skills
¿Qué forma tiene el repositorio?	`unico`, `monorepo`, `multiple`	`unico`	`perfil.repositorio`
¿Qué comando decide que el proyecto está sano?	texto	El deducido, o `pnpm test`	`verificacion` y varias skills
¿Y el de tipos?	texto	El script de tipos, si lo hay	`protocolo-features`, `test-fix`
¿Y el de lint?	texto	El script `lint`, si lo hay	`protocolo-features`, `test-fix`
¿Trabajas con varios agentes en paralelo?	sí/no	no	`protocolo-features`, `test-fix`
¿Qué archivo lleva el número de versión?	texto	El manifiesto encontrado, o `package.json`	`version-bump`, `protocolo-cierre`
¿En qué orden se implementa una feature?	opción, según el producto	La primera que ofrece el producto	`protocolo-features`
¿«…» es Zona Prohibida?	sí/no, una por zona sugerida	sí	Un «no» la quita de `zonas_prohibidas`

Son nueve preguntas fijas, la de la secuencia y una por cada Zona Prohibida sugerida. El número exacto se anuncia antes de empezar.

Las secuencias que ofrece la penúltima pregunta:

Valor	Secuencia	Se ofrece a
`hexagonal`	schema o migración, dominio, aplicación, infraestructura backend, compartido, interfaz, pruebas	`saas`, `api`, `movil`
`capas-web`	schema, consultas y acciones de servidor, componentes, ruta o página, pruebas	`saas`, `landing`, `movil`
`vertical`	contrato de la feature, datos, lógica, interfaz, pruebas	todos menos `cli`
`contenido`	contenido y copia, componentes, página, pruebas	`landing`
`contrato-cli`	contrato, dominio, aplicación, interfaz de línea de comandos, pruebas	`cli`, `api`

Dónde escribe las respuestas

En AI-FIRST.md: proyecto, fase, perfil, verificacion y las zonas confirmadas. Sólo si init crea el archivo en esa corrida; un AI-FIRST.md que ya existía no se toca.
En cada skill instalada, dentro de su sección «Adaptación a tu proyecto» y entre las mismas marcas que AGENTS.md. Cada corrida reescribe lo que hay entre las marcas; lo que agregues fuera sobrevive. Una skill para la que la entrevista no aporta nada, como i18n, se reporta saltada con esa razón.

Cómo revisar y completar esa adaptación está en Adaptar las skills.

El punto de control

init escribe el mismo detector en dos sitios, con tolerancias distintas.

.githooks/pre-push corre ai-first audit sin --estricto sobre lo que se va a empujar: sólo un P0 interrumpe el push; un P1 o un P2 se imprimen y el push sigue. Toma como base el commit que el remoto ya tiene; si la rama todavía no existe en el remoto, compara el árbol de trabajo. Busca el comando en node_modules/.bin, luego en el PATH, luego en la caché de npx sin descargar nada. Si no encuentra Node o el paquete, avisa y deja pasar el push: no encontrarse nunca es motivo para frenar. Se salta con git push --no-verify.

Es un hook de git, no del agente: no es el PostToolUse ni el Stop de Skills, hooks y gestión de contexto.

.github/workflows/ai-first.yml corre en cada pull request, con --estricto: ahí cualquier hallazgo corta. Su paso final:

- name: Entropía documental
  run: npx --yes @falcux/ai-first audit --base "origin/${{ github.base_ref }}" --estricto

Clona con fetch-depth: 0, porque sin historia no hay rango que comparar, y usa Node 22.

Salida

init --sin-entrevista en una carpeta vacía llamada demo:

ai-first init — demo

  escrito  .git/
  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
  escrito  core.hooksPath
  escrito  .github/workflows/ai-first.yml
  escrito  AGENTS.md

  1 Zona Prohibida sugerida: .env*
  0 superficies de decisión: —
  2 artefactos declarados

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

Un ítem saltado se imprime con su razón entre paréntesis, o (ya existe); uno sugerido, con la razón tras una raya. El AI-FIRST.md que dejó esta corrida está completo en El formato de AI-FIRST.md.

Códigos de salida

Código	Cuándo
`0`	Terminó, aunque haya saltado o sugerido cosas: saltar no es error.
`2`	Error de uso: dos opciones que se contradicen, `--entrevista` sin terminal interactiva, una skill que el paquete no trae, un bloque roto en `AGENTS.md`, una `--raiz` que no existe, una opción desconocida o una entrevista cancelada.

init nunca sale con 1: ese código es de audit.

Relacionado

Qué deja init en tu repoLos mismos archivos, explicados para quien lo corre por primera vez.

Adoptar en un proyecto existenteQué pasa cuando el repo ya tiene AGENTS.md, skills o hooks propios.

ai-first auditEl comando que corre el punto de control.

Las 11 skillsQué instala cada perfil y qué hace cada skill.