Arrancar un producto desde cero

Tienes una idea, un requerimiento o las notas de una reunión, y todavía no hay PRD ni arquitectura. Quieres que el agente te ayude a definir el producto y que lo que salga quede escrito en el repo, no en un chat.

Cuándo usarla

• Hay una idea o un requerimiento y docs/ está vacío, o sólo tiene lo que escribió init.
• Hay que decidir el stack y nadie lo ha registrado.
• Un proyecto existente cambió tanto de alcance que su PRD dejó de describirlo.

protocolo-arranque corre una vez por proyecto, o una vez por giro grande de producto. Si el producto ya está definido y vas a construir una parte, es Desarrollar una feature. Si vas a modificar algo que ya funciona, incluido un artefacto que este protocolo escribió, es Cambiar algo que ya funciona.

Antes de empezar

protocolo-arranque no está entre las cinco skills que init instala por defecto. Entra de dos maneras:

• Con la entrevista. En una carpeta vacía y desde una terminal, init entrevista sin preguntar, y cuando entrevista instala protocolo-arranque junto con las skills que pide el perfil del producto:

  npx @falcux/ai-first@latest init

• Sola, en un repo ya inicializado. Si corriste init sin entrevista, agrégala con --skills. Instala sólo las que nombras; las que ya estaban no se tocan.

  npx @falcux/ai-first@latest init --skills protocolo-arranque

Con entrevista, AI-FIRST.md declara el perfil —producto y repositorio— y la skill lo lee para saber qué artefactos escribir. Sin perfil, es lo primero que te pregunta. La entrevista está en Adaptar las skills.

Paso a paso

1. Dale el contexto base. Pega el mensaje, el documento o las notas tal como estén, y nombra la skill para que el agente la cargue:

   Usa protocolo-arranque. Este es el requerimiento tal como llegó:
   
   [pega aquí el correo, las notas de la reunión o el documento]
   
   El cliente ya tiene una base de datos en PostgreSQL que hay que usar.
   Antes de escribir nada, haz el descubrimiento completo.

   La skill lee primero AI-FIRST.md, AGENTS.md, lo que haya en docs/ y docs/ADR.md, para no preguntarte lo que ya está escrito.

2. Responde el descubrimiento. Es la Fase 1, y no se genera ningún artefacto hasta que cierra. El agente arma un benchmark de herramientas parecidas, con una línea por cada una, y te dice si lo que quieres construir ya se puede comprar. Después pregunta en tandas, sin límite, por el problema y el éxito, los usuarios, la lógica de negocio, los datos, las integraciones y las restricciones.

   Si una idea tuya es ineficiente, la skill le pide proponer la alternativa con su porqué. Si la reafirmas, se acata y queda en el ADR con las dos posturas.

3. Cierra la fase. Cierra cuando el agente puede decir, sin suponer, qué se construye, para quién, con qué reglas, contra qué datos y cómo se mide el éxito. Te pregunta si falta algo y enumera lo que quedó supuesto.

4. Deja que genere los artefactos, en orden. La Fase 2 escribe cada documento desde su template del paquete, en su ruta definitiva:

   1. Decisión de stack        → fila en docs/ADR.md
   2. docs/PRD.md              → qué se construye y para quién
   3. docs/ARQUITECTURA.md     → componentes, límites y el diagrama
   4. docs/GUIA_DISENO.md      → si el producto tiene interfaz
   5. docs/specs/<modulo>.md   → una por módulo, en orden de construcción
   6. AI-FIRST.md y AGENTS.md  → completar con lo que ahora se sabe

   El agente no instala nada ni corre generadores de proyecto: deja escritos los comandos de instalación en la fila del ADR o en el PRD. Tampoco escribe las specs de todo el backlog, sólo las de lo que se construye primero.

5. Revisa la validación final. La skill comprueba que el PRD y la arquitectura no se contradigan, que cada decisión difícil de revertir tenga su fila, que AI-FIRST.md declare las Zonas Prohibidas que la arquitectura hizo evidentes y que las specs listen sus archivos. La última comprobación es el detector:

   npx @falcux/ai-first@latest audit

6. Cierra el tramo. El arranque se cierra como cualquier otro trabajo, con protocolo-cierre. Ver Cerrar la sesión.

Precaución

Si el agente empieza a escribir «se definirá más adelante», si dos artefactos cuentan distinto el mismo flujo o si el PRD crece con features que nadie pidió, la skill manda detener la generación y volver a la Fase 1.

Qué queda escrito

Qué artefactos salen depende del perfil. Todos salen de un template del paquete:

Artefacto	Template	Cuándo
Fila de la decisión de stack en docs/ADR.md	—	Siempre
docs/PRD.md	templates/PRD_TEMPLATE.md	Siempre
docs/ARQUITECTURA.md	templates/ARQUITECTURA_TEMPLATE.md	Siempre
docs/specs/<modulo>.md	templates/SPEC_MODULO_TEMPLATE.md	Una por módulo; en una landing, una sola del sitio
docs/GUIA_DISENO.md	templates/GUIA_DISENO_TEMPLATE.md	Con interfaz: saas, landing, movil
docs/COMPONENTES.md	templates/COMPONENT_LIBRARY_TEMPLATE.md	Con interfaz: saas, landing, movil
docs/TECH_NOTES.md	templates/TECH_NOTES_TEMPLATE.md	Siempre

Además, completa AI-FIRST.md con las Zonas Prohibidas —migraciones, infraestructura, secretos— y su razón, y AGENTS.md fuera de las marcas del bloque que mantiene init. En un monorepo la arquitectura describe qué paquete depende de qué; en varios repos, el PRD y la arquitectura viven en uno solo.

El registro de sesión, el de cambios y el handoff no son artefactos de arranque: nacen vacíos con init y los llenan otras skills.

Qué vigila el detector

• Artefacto huérfano (P2). Cada ruta que un artefacto declarado en AI-FIRST.md menciona tiene que existir. Por eso, con varios repos, los demás referencian el PRD en prosa y sin ruta: una ruta a otro repo se cobra como huérfana.
• Zona Prohibida tocada (P0). Sólo vigila las zonas que declares. Las que el arranque hizo evidentes van a AI-FIRST.md antes de la primera feature.
• Alcance excedido (P1). Lee la sección «Archivos» o «Alcance» de la spec activa, con las rutas entre acentos graves. La sección «Archivos del módulo» del template ya tiene ese nombre, sin número delante, por esa razón.
• Inventario de componentes (P2). Se reporta omitido hasta que artefactos declara inventario_componentes y componentes_dir.

El detalle de cada una está en Las cinco verificaciones.

Por qué funciona así

El stack va primero porque condiciona todo lo demás y es la decisión más cara de revertir, y las specs van al final porque cada una necesita saber en qué capa vive. La cadena completa, y qué pasa cuando se salta un eslabón, está en La cadena de artefactos.

Próximos pasos

Desarrollar una featureConstruir lo que el arranque definió, spec por spec.

Adaptar las skillsLa entrevista que fija el perfil y adapta cada skill.

TemplatesLos templates de los que sale cada artefacto.