@davinci-factory/aif

AI Factory CLI — Flujo de desarrollo con agentes IA para el equipo Davinci.

Configura en segundos tu proyecto (nuevo o existente) para trabajar con Antigravity y/o Gemini CLI. Genera reglas, slash commands, artefactos de cambio, CI local y GitHub Actions automaticamente.

Cada comando lleva al agente a traves de un flujo estructurado: propuesta → especificaciones → diseno → tareas → implementacion → verificacion.

Instalacion

# Como dependencia de desarrollo en tu proyecto
npm i -D @davinci-factory/aif

# O de forma global
npm i -g @davinci-factory/aif

Inicio rapido

# 1. Entra a tu proyecto
cd mi-proyecto

# 2. Ejecuta el wizard
npx aif i

# 3. Verifica que todo este configurado
npx aif doc

# 4. Listo! Usa los slash commands en Antigravity o Gemini CLI

Comandos del CLI

| Comando | Alias | Descripcion | |---|---|---| | aif i | aif init | Wizard interactivo para configurar el proyecto | | aif ci | — | CI local: corre lint + tests + build | | aif ls | aif list | Lista los slash commands disponibles | | aif up | aif update | Regenera workflows y templates con la config guardada (sin re-correr el wizard) | | aif doc | aif doctor | Verifica que la configuracion este completa | | aif monday sync | — | Verifica/crea las 5 columnas y los 9 grupos del board de Monday |

Slash commands generados

Despues de ejecutar aif i, tendras estos comandos disponibles en tu agente IA:

Desarrollo (pipeline integrado)

| Comando | Que hace | Ejemplo de uso | |---|---|---| | /feat | Nueva feature con pipeline completo: propuesta → specs → diseno → tareas → implementacion → verificacion | /feat crear endpoint de login con JWT | | /fix | Corregir bug: diagnostico → spec del fix → implementacion minima → verificacion | /fix el endpoint /users devuelve 500 | | /refac | Refactorizar: analisis → diseno antes/despues → refactor → verificacion | /refac extraer logica de auth a un servicio |

Cada comando genera artefactos en specs/changes/<nombre>/ (proposal, specs, design, tasks) y pausa entre fases para que el dev apruebe antes de continuar.

Aprobaciones obligatorias antes de escribir codigo

Los comandos que tocan codigo (/feat, /fix, /refac) y los que escriben docs al repo (/iniciar) no avanzan a la fase de implementacion sin aprobacion explicita del dev. En cada pausa el agente muestra este bloque y se detiene:

────────────────────────────────────────
PAUSA — <nombre fase>
Archivo: specs/changes/<nombre>/<archivo>.md

Opciones:
  [A] Aprobar y continuar a <siguiente fase>
  [I] Iterar — dime que ajustar y actualizo el archivo
  [C] Cancelar

Esperando tu respuesta.
────────────────────────────────────────

| Comando | Pausas antes de codigo | |---|---| | /feat | Propuesta, Specs, Diseno, Tareas (4 pausas) | | /fix | Diagnostico, Spec del fix (2 pausas) | | /refac | Analisis, Diseno (2 pausas) | | /iniciar | Plan inicial, PRD, ARCHITECTURE, CONVENTIONS (4 pausas) |

Reglas que aplica cada comando:

• Feedback libre del dev (sin elegir letra) = iterar: reescribe SOLO el archivo de la fase actual y vuelve a mostrar la misma PAUSA
• Iteraciones ilimitadas hasta que el dev escriba [A]
• Silencio no es aprobacion — si no hay respuesta, repite la PAUSA
• /pick no ejecuta el pipeline ni las pausas: baja la spec desde la columna Archivo de Monday y delega al comando que corresponda (/feat, /fix o /refac), que es quien aplica las pausas

Investigacion y verificacion

| Comando | Que hace | Ejemplo de uso | |---|---|---| | /explore | Investigar el codebase sin escribir codigo. Diagramas ASCII, analisis, preguntas. | /explore como funciona el sistema de permisos | | /verify | Re-verificar un cambio completado. Score 3D: Completitud + Correctitud + Coherencia. Archiva al aprobar. | /verify login-oauth |

Calidad

| Comando | Que hace | Ejemplo de uso | |---|---|---| | /qa | Revision de QA: valida contra specs/requerimientos, edge cases, regresiones | /qa revisar PR #45 | | /cr | Code review: lee specs para contexto, evalua seguridad, performance, tests | /cr revisar cambios en auth.service.ts |

Soporte

| Comando | Que hace | Ejemplo de uso | |---|---|---| | /onb | Onboarding: explica arquitectura, modulos, flujo de datos, setup | /onb explicar el modulo de pagos |

Monday.com — Scrum (opcional)

Si habilitas la integracion con Monday.com en el wizard, obtienes 6 comandos adicionales: 3 para el flujo del dev y 3 para el flujo del QA.

Comandos del dev

| Comando | Que hace | Ejemplo de uso | |---|---|---| | /backlog | Lista la "Cola de Fabricacion" ordenada por Prioridad. Marca como bloqueados los items sin archivo en la columna Archivo. | /backlog | | /pick | Valida que el item tenga Archivo cargado, descarga la spec a specs/changes/<nombre>/_spec-input.<ext>, detecta tipo (Feature/Fix/Refactor), mueve a "In Progress Dev", crea branch, escribe _monday.md con criterios -> REQ-XXX y sugiere /feat, /fix o /refac. | /pick 1234567890 | | /done | Valida CI (lint + tests), mueve a "Done Dev", deja un update corto en Monday avisando que esta listo para QA y archiva specs/changes/<nombre>/ -> specs/archive/<nombre>/. | /done |

Comandos del QA

| Comando | Que hace | Ejemplo de uso | |---|---|---| | /qa-backlog | Lista "Backlog QA" ordenado por Prioridad. Marca como bloqueados los items sin archivo en la columna Spec QA (libreto E2E). | /qa-backlog | | /qa-pick | Valida que el item tenga Spec QA cargado, descarga el libreto a qa/runs/<nombre>/_libreto.<ext>, mueve a "In Progress QA", reasigna Responsable al QA y escribe qa/runs/<nombre>/_qa.md con criterios extraidos del libreto. | /qa-pick 1234567890 | | /qa-done | Pide veredicto + evidencia. PASS -> mueve a "Done QA", publica resumen como update y archiva qa/runs/ -> qa/archive/. FAIL -> mueve a "In Progress Dev" reasignando al dev original con bugs documentados como update (no archiva, deja la corrida para el siguiente intento). | /qa-done |

Promocion de "Done QA" -> "Finish" es manual del lead/release. Ningun comando del CLI la hace.

Estos comandos usan el MCP de Monday.com (@mondaydotcomorg/monday-api-mcp) para leer y escribir en tu board directamente desde el agente IA. Funcionan igual en Antigravity y Gemini CLI.

Estructura del board (predefinida)

El wizard sincroniza automaticamente esta estructura. NO te pregunta nombres de grupos ni columnas — son fijos.

9 grupos (en orden del flujo):

Definicion Spec -> Backlog PM -> Cola de Fabricacion ->
  In Progress Dev -> Done Dev ->
    Backlog QA -> In Progress QA -> Done QA -> Finish

5 columnas:

| Columna | Tipo | Quien la usa | Para que | |---|---|---|---| | Responsable | people | Todos | Asignacion. /pick la setea al dev si esta vacia; /qa-pick la sobreescribe al QA; /qa-done (FAIL) la regresa al dev original | | Estado | status | Todos | Status del item. /pick y /qa-pick setean "Working on it"; /done y /qa-done (PASS) setean "Done"; /qa-done (FAIL) setea "Stuck" | | Archivo | file | Dev | Spec del dev (problema + solucion + criterios). PM la sube en "Definicion Spec"/"Backlog PM"; /backlog valida que exista; /pick la descarga como _spec-input.<ext> | | Prioridad | status (Alto/Medio/Bajo) | Todos | Orden de toma. /backlog y /qa-backlog ordenan Alto -> Medio -> Bajo | | Spec QA | file | QA | Libreto E2E (escenarios + criterios verificables + datos de prueba). PM/dev la sube cuando el item entra a Backlog QA; /qa-backlog valida que exista; /qa-pick la descarga como _libreto.<ext> |

Regla de oro: el item de Monday solo lleva metadata (titulo, prioridad, responsable). Toda la informacion de la tarea vive en archivos: Archivo para el dev, Spec QA para el QA. Sin esos archivos los comandos de /pick//qa-pick abortan.

Contrato entre comandos

/pick deja en specs/changes/<nombre>/:

• _spec-input.<ext> — spec original descargada de Monday (referencia inmutable)
• _monday.md — contexto estructurado (item ID, tipo, criterios -> REQ-XXX, placeholder ## Verify Score)

Cuando el dev arranca /feat, /fix o /refac:

• Lee _monday.md y _spec-input.<ext> para generar proposal/specs/design/tasks
• Al cerrar la fase de Verificacion, sobreescribe la linea bajo ## Verify Score con {score}/100 - {PASS|FAIL} (queda en specs/archive/ para trazabilidad cuando /done archive el folder)

/done ya no consume Verify Score como columna en Monday — solo notifica que el desarrollo termino y mueve el item. Toda la trazabilidad queda en specs/archive/<nombre>/.

/qa-pick deja en qa/runs/<nombre>/:

• _libreto.<ext> — libreto descargado de Monday (referencia inmutable)
• _qa.md — contexto QA (item ID, dev original, QA, criterios extraidos del libreto, escenarios principales, placeholder ## Resultado QA)

/qa-done sobreescribe ## Resultado QA con veredicto + evidencia + bugs (si FAIL), publica el resultado como update en Monday y archiva la corrida (solo si PASS).

Si el dev arranca /feat//fix//refac sin pasar por /pick, el bloque "Contexto opcional desde /pick" no aplica y operan con lo que pida el dev directamente.

Re-sincronizar despues

Si agregas el board despues del wizard, renombras columnas/grupos, o quieres re-verificar:

aif monday sync

Lee .aif/monday.json y .env, consulta el board, lista que columnas y grupos existen/faltan, y ofrece crear los faltantes. Tambien se usa si anadiste la integracion Monday a un proyecto ya configurado.

.aif/monday.json

Al configurar Monday en el wizard se genera .aif/monday.json con esta forma:

{
  "boardId": "1234567890",
  "columns": {
    "responsable": "people_xyz",
    "estado": "status_abc",
    "archivo": "file_def",
    "prioridad": "status_ghi",
    "specQa": "file_jkl"
  },
  "columnTitles": {
    "responsable": "Responsable",
    "estado": "Estado",
    "archivo": "Archivo",
    "prioridad": "Prioridad",
    "specQa": "Spec QA"
  },
  "groups": {
    "definicionSpec": "group_1",
    "backlogPm": "group_2",
    "colaFabricacion": "group_3",
    "inProgressDev": "group_4",
    "doneDev": "group_5",
    "backlogQa": "group_6",
    "inProgressQa": "group_7",
    "doneQa": "group_8",
    "finish": "group_9"
  },
  "groupTitles": { "definicionSpec": "Definición Spec", ... }
}

Este archivo no contiene secretos (el token sigue en .env) y puede commitearse si el equipo comparte el mismo board.

Flujo de trabajo

Lado dev (Cola de Fabricacion -> Done Dev)

PM define spec y la sube a la columna "Archivo"
PM mueve el item a "Cola de Fabricacion"
  |
  v
/backlog                          <- Lista Cola de Fabricacion (solo items con Archivo)
  |
  v
/pick {itemId}                    <- Valida Archivo, descarga _spec-input.<ext>,
  |                                  detecta tipo, mueve a In Progress Dev,
  |                                  crea branch, escribe _monday.md
  v
/feat | /fix | /refac             <- Pipeline (lee _monday.md + _spec-input)
  |
  +-- Fase 1: Propuesta           <- proposal.md (que y por que)         PAUSA
  +-- Fase 2: Especificaciones    <- specs.md (REQs verificables)        PAUSA
  +-- Fase 3: Diseno tecnico      <- design.md (arquitectura)            PAUSA
  +-- Fase 4: Tareas              <- tasks.md (checkboxes concretas)     PAUSA
  +-- Fase 5: Implementacion      <- Codigo + tests, marca [x] en tasks
  +-- Fase 6: Verificacion        <- Score 3D, escribe en _monday.md
  |
  v
aif ci                            <- CI local (lint + test + build)
  |
  v
git push + PR + /cr               <- Push, PR, code review
  |
  v
/done                             <- Valida CI, mueve a Done Dev, update
  |                                  corto en Monday, archiva specs
  v
PM/dev sube libreto a "Spec QA" y mueve el item a "Backlog QA"

Lado QA (Backlog QA -> Done QA)

/qa-backlog                       <- Lista Backlog QA (solo items con Spec QA)
  |
  v
/qa-pick {itemId}                 <- Valida Spec QA, descarga _libreto.<ext>,
  |                                  mueve a In Progress QA, reasigna Responsable,
  |                                  escribe _qa.md
  v
QA ejecuta el libreto (Playwright/Cypress/manual)
  |
  v
/qa-done
  |
  +-- PASS  -> Done QA            <- Update con resumen + evidencia, archiva qa/runs/
  |             |
  |             v
  |           lead/release promueve manualmente a "Finish"
  |
  +-- FAIL  -> In Progress Dev    <- Reasigna al dev original, update con bugs
                |                     y severidad. NO archiva la corrida.
                v
              dev corrige y vuelve a /done -> ciclo se repite

Sin Monday: el flujo arranca directamente en /feat, /fix o /refac. Sin /pick no hay _monday.md ni _spec-input, y el pipeline opera con lo que pida el dev.

Artefactos por cambio

Cada /feat, /fix o /refac genera artefactos estructurados:

specs/changes/<nombre-cambio>/
  proposal.md     <- Problema, solucion, alcance, impacto
  specs.md        <- Requerimientos formales (DEBE/NO DEBE + escenarios CUANDO/ENTONCES)
  design.md       <- Arquitectura, componentes, decisiones, riesgos
  tasks.md        <- Tareas concretas con checkboxes

Al completar y verificar, /verify mueve el cambio a specs/archive/ y mergea las specs al principal.

Verificacion 3D

Cada comando incluye autoverificacion al terminar. /verify permite re-verificar:

| Dimension | Peso | Que evalua | |---|---|---| | Completitud | 40% | Tareas [x], REQs implementados, escenarios con tests | | Correctitud | 40% | Tests pasan, lint pasa, sin vulnerabilidades, edge cases | | Coherencia | 20% | Naming consistente, patrones del proyecto, sin duplicacion |

Hallazgos clasificados como: CRITICO (bloquea merge) / WARNING (deberia corregirse) / SUGERENCIA (opcional).

El wizard: aif i

El wizard te guia paso a paso:

1. Tipo de proyecto

• Nuevo: te pregunta todo (stack, framework, DB, testing)
• Existente: analiza tu proyecto y detecta automaticamente el stack

2. Herramienta de IA

Elige entre Antigravity, Gemini CLI, o ambas. Se generan los archivos en el formato correcto de cada herramienta.

3. Stack tecnologico

Lenguaje, framework, base de datos y framework de testing.

4. Convenciones

Naming (camelCase/snake_case), estrategia de branches (GitFlow/Trunk-based) y formato de commits.

5. QA

Tipo de proceso de QA del equipo y si incluir el comando /qa para review automatizado.

6. CI/CD

• Local + GitHub Actions (recomendado): aif ci para feedback rapido + pipeline en PRs
• Solo local: solo aif ci
• Solo GitHub Actions: solo el pipeline
• Ninguno: se puede agregar despues

7. Monday.com (Scrum) — opcional

Si usas Monday.com para gestionar tareas, el wizard solo te pide:

• API Token: tu token v2 de Monday.com (se guarda en .env, nunca se commitea)
• Board ID: el ID del board

La estructura del board es predefinida (no te pregunta nombres). Despues de capturar el board, el wizard:

1. Sincroniza columnas: consulta el board, lista las 5 columnas requeridas (Responsable, Estado, Archivo, Prioridad, Spec QA), marca cuales existen, y ofrece crear las faltantes. La columna Prioridad la crea con labels Alto/Medio/Bajo por defecto.
2. Sincroniza grupos: hace lo mismo con los 9 grupos del flujo (Definición Spec, Backlog PM, Cola de Fabricación, In Progress Dev, Done Dev, Backlog QA, In Progress QA, Done QA, Finish).
3. Genera la config MCP para que Antigravity y/o Gemini CLI puedan interactuar con Monday.

Si rechazas crear los faltantes, los comandos /pick, /done, /qa-* te van a avisar cuando intenten usar algo que no existe. Puedes sincronizar despues con aif monday sync.

8. Deteccion automatica (solo proyectos existentes)

Analiza package.json, git, framework, testing y linter. Te pide confirmar antes de generar.

Archivos generados

Antigravity

.antigravity/rules.md              <- Reglas del proyecto (auto-cargado)
.agents/workflows/feat.md           <- /feat (pipeline completo)
.agents/workflows/fix.md            <- /fix (pipeline de bugfix)
.agents/workflows/refac.md          <- /refac (pipeline de refactor)
.agents/workflows/explore.md        <- /explore
.agents/workflows/verify.md         <- /verify
.agents/workflows/qa.md             <- /qa
.agents/workflows/cr.md             <- /cr
.agents/workflows/onb.md            <- /onb
.agents/workflows/backlog.md        <- /backlog (Monday — dev, si habilitado)
.agents/workflows/pick.md           <- /pick (Monday — dev)
.agents/workflows/done.md           <- /done (Monday — dev)
.agents/workflows/qa-backlog.md     <- /qa-backlog (Monday — QA)
.agents/workflows/qa-pick.md        <- /qa-pick (Monday — QA)
.agents/workflows/qa-done.md        <- /qa-done (Monday — QA)

Gemini CLI

GEMINI.md                          <- Instrucciones base (auto-cargado)
.gemini/commands/feat.toml         <- /feat (pipeline completo)
.gemini/commands/fix.toml          <- /fix (pipeline de bugfix)
.gemini/commands/refac.toml        <- /refac (pipeline de refactor)
.gemini/commands/explore.toml      <- /explore
.gemini/commands/verify.toml       <- /verify
.gemini/commands/qa.toml           <- /qa
.gemini/commands/cr.toml           <- /cr
.gemini/commands/onb.toml          <- /onb
.gemini/commands/backlog.toml      <- /backlog (Monday — dev, si habilitado)
.gemini/commands/pick.toml         <- /pick (Monday — dev)
.gemini/commands/done.toml         <- /done (Monday — dev)
.gemini/commands/qa-backlog.toml   <- /qa-backlog (Monday — QA)
.gemini/commands/qa-pick.toml      <- /qa-pick (Monday — QA)
.gemini/commands/qa-done.toml      <- /qa-done (Monday — QA)
.gemini/settings.json              <- MCP config Monday (si habilitado)

Despues de generar los archivos de Gemini CLI, ejecuta /commands reload para cargar los nuevos comandos.

Compartido

AGENTS.md                          <- Definicion de agentes del flujo
CONTEXT.md                         <- Contexto del proyecto (editar manualmente)
.aif/config.json                   <- Config persistida por el wizard (sin secretos). Usada por `aif up` para regenerar sin re-preguntar.

Artefactos

specs/
  changes/                         <- Cambios en progreso (creados por /feat, /fix, /refac)
  archive/                         <- Cambios completados (movidos por /verify)
  _template-proposal.md            <- Template reutilizable
  _template-specs.md               <- Template reutilizable
  _template-design.md              <- Template reutilizable
  _template-tasks.md               <- Template reutilizable

Monday.com (si habilitado)

.env                                          <- monday_token (en .gitignore, nunca se commitea)
.aif/monday.json                              <- board + column IDs + group IDs (sin secretos, commiteable)
specs/changes/<nombre>/_spec-input.<ext>      <- creado por /pick: spec original descargada de la columna Archivo (referencia inmutable)
specs/changes/<nombre>/_monday.md             <- creado por /pick: contrato con /feat|fix|refac (item, criterios -> REQ-XXX, ## Verify Score)
qa/runs/<nombre>/_libreto.<ext>               <- creado por /qa-pick: libreto descargado de la columna Spec QA (referencia inmutable)
qa/runs/<nombre>/_qa.md                       <- creado por /qa-pick: contrato con /qa-done (item, dev original, criterios, ## Resultado QA)
qa/archive/<nombre>/                          <- creado por /qa-done (PASS): corrida archivada con evidencia
~/.gemini/antigravity/mcp_config.json         <- MCP Monday para Antigravity (config global)
.gemini/settings.json                         <- MCP Monday para Gemini CLI (config proyecto)

Nota sobre Antigravity: La config MCP se instala en ~/.gemini/antigravity/mcp_config.json (global) porque Antigravity no soporta config MCP a nivel de proyecto. Si ya tienes otros MCP servers configurados, aif i hace merge automaticamente.

Nota sobre Gemini CLI: La config MCP se instala en .gemini/settings.json (proyecto). Usa $monday_token para leer el token desde tu entorno en runtime.

CI/CD

.github/workflows/ci.yml           <- GitHub Actions (corre en cada PR)

CI Local: aif ci

Corre lint, tests y build localmente antes de hacer push. Detecta automaticamente el stack.

$ aif ci

  Davinci AI Factory — CI Local
  ==============================

  Detectando stack...
  + Node.js

  Ejecutando validaciones...

  [1/3] Lint...
        npm run lint                              PASO

  [2/3] Tests...
        npm test                                  PASO

  [3/3] Build...
        npm run build                             PASO

  ==============================
  RESULTADO: PASO
  Listo para push y PR.

Deteccion automatica

| Stack | Lint | Tests | Build | |---|---|---|---| | Node.js (con scripts en package.json) | npm run lint | npm test | npm run build | | Node.js (sin scripts) | npx eslint . | npx jest | npx tsc --noEmit | | Python | ruff check . | pytest | mypy . |

Prioridad: si package.json tiene scripts lint, test y build definidos, aif ci los usa directamente.

Doctor: aif doc

Verifica que todos los archivos necesarios esten presentes:

$ aif doc

  Davinci AI Factory — Doctor

  + Antigravity rules
  + /feat
  + /fix
  + /refac
  + /explore
  + /verify
  + /qa
  + /cr
  + /onb
  + AGENTS.md
  + CONTEXT.md
  + specs/changes/
  + specs/archive/
  + GitHub Actions CI
  + /backlog (Monday)
  + /pick (Monday)
  + /done (Monday)
  + /qa-backlog (Monday)
  + /qa-pick (Monday)
  + /qa-done (Monday)
  + .env (MONDAY_API_TOKEN)
  + .aif/monday.json (board + columnas)

  Todo en orden! Configuracion completa.

Si falta algo, te dice que ejecutes aif i para regenerar.

Despues de instalar

Pasos para el equipo

1. Clonar el repo del proyecto
2. npm install (instala @davinci-factory/aif como devDependency)
3. npx aif doc para verificar que todo esta configurado
4. Empezar a usar /feat, /fix, /explore, etc. en Antigravity o Gemini CLI

Personalizar

• CONTEXT.md: edita este archivo con informacion especifica de tu proyecto (descripcion, arquitectura, APIs externas, variables de entorno)
• Reglas: edita .antigravity/rules.md o GEMINI.md para agregar reglas especificas
• Slash commands: modifica los archivos en .agents/workflows/ o .gemini/commands/ para ajustar los prompts
• Templates de specs: edita los archivos specs/_template-*.md para ajustar la estructura de los artefactos

Actualizar

# Actualizar el paquete
npm update @davinci-factory/aif

# Regenerar workflows y templates con la config guardada (sin re-correr el wizard)
npx aif up

aif up lee .aif/config.json (lo crea el wizard) y .env, y vuelve a correr el generador. Si no existe .aif/config.json (proyectos creados con una version anterior a 1.6.0), corre npx aif i una sola vez y a partir de ahi aif up ya funciona sin preguntas.

Requisitos

• Node.js >= 18
• npm >= 9
• Antigravity y/o Gemini CLI instalados
• Git (recomendado)
• Monday.com API Token v2 (solo si usas la integracion Monday/Scrum)

Soporte

Equipo AI Factory — Davinci