# ai-first init > Qué escribe init, sus opciones, qué skills instala, cómo reporta lo que ya existía y cómo funciona la entrevista. `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 ```text ai-first init [--raiz ] [--enlazar] [--skills |todas] [--entrevista | --sin-entrevista] [--sin-hook] [--hook-local] [--sin-ci] ``` Para correrlo sin instalar nada, desde la raíz del proyecto: ```bash 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: 1. **`.git/`**, sólo si la carpeta todavía no era un repositorio: corre `git init` y sigue. No crea commits. 2. **`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](https://ai-first.falcux.com/docs/referencia/ai-first-md/). 3. **`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. 4. **`docs/SESSION_LOG.md`** y **`docs/changes/CHANGE_LOG.md`**, con su cabecera, y **`docs/changes/pending/`**, que se crea con un `.gitkeep`. 5. **Las skills**, cada una en `.agents/skills//`. Cuáles, en [Qué skills instala](#qu%C3%A9-skills-instala). 6. **La adaptación de cada skill**, sólo si hubo entrevista: un bloque dentro de su sección «Adaptación a tu proyecto». 7. **`.claude/skills`**, un enlace simbólico relativo a `.agents/skills/` para que Claude Code las lea. 8. **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. 9. **`.github/workflows/ai-first.yml`**, el flujo de integración continua. 10. **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ú | Nota `init` declara `agents` y `adr` como artefactos, pero no el registro de sesión ni el de cambios aunque los escriba: son cronología, nombran archivos que ya se retiraron, y la verificación de artefactos huérfanos los cobraría para siempre. ## Opciones | Opción | Qué hace | Por defecto | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | `--raiz ` | 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 ` | 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](#qu%C3%A9-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](https://ai-first.falcux.com/docs/referencia/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](https://ai-first.falcux.com/docs/guias/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](https://ai-first.falcux.com/docs/parte-2/skills-hooks-contexto/). **`.github/workflows/ai-first.yml`** corre en cada pull request, **con `--estricto`**: ahí cualquier hallazgo corta. Su paso final: ```yaml - 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`: ```text 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](https://ai-first.falcux.com/docs/referencia/ai-first-md/#un-ejemplo-real). ## 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 repo](https://ai-first.falcux.com/docs/empezar/que-instala/)Los mismos archivos, explicados para quien lo corre por primera vez. [Adoptar en un proyecto existente](https://ai-first.falcux.com/docs/empezar/proyecto-existente/)Qué pasa cuando el repo ya tiene AGENTS.md, skills o hooks propios. [ai-first audit](https://ai-first.falcux.com/docs/referencia/audit/)El comando que corre el punto de control. [Las 11 skills](https://ai-first.falcux.com/docs/referencia/skills/)Qué instala cada perfil y qué hace cada skill.