@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 | Actualiza templates a la ultima version | | aif doc | aif doctor | Verifica que la configuracion este completa |

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.

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 3 comandos adicionales:

| Comando | Que hace | Ejemplo de uso | |---|---|---| | /backlog | Ver tareas del Sprint actual en Monday.com. Lista items con prioridad, story points y asignado. | /backlog | | /pick | Tomar una tarea del backlog: mueve a "In Progress" en Monday, crea branch, arranca /feat o /fix automaticamente. | /pick 1234567890 | | /done | Completar tarea: valida CI, mueve a "Done" en Monday, agrega update con resumen de cambios. | /done |

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

Los comandos funcionan igual en Antigravity y Gemini CLI. El wizard genera el formato correcto para cada herramienta automaticamente.

Flujo de trabajo

IDEA (o /backlog para ver sprint)
  |
  v
/explore                          <- Investigar, entender el problema
  |
  v
/pick (o /feat, /fix, /refac)     <- Tomar tarea de Monday o ejecutar directo
  |
  +-- Fase 1: Propuesta           <- proposal.md (que y por que)         PAUSA
  +-- Fase 2: Especificaciones    <- specs.md (REQs verificables)
  +-- Fase 3: Diseno tecnico      <- design.md (arquitectura, decisiones) PAUSA
  +-- Fase 4: Tareas              <- tasks.md (checkboxes concretas)
  +-- Fase 5: Implementacion      <- Codigo + tests, marca [x] en tasks
  +-- Fase 6: Verificacion        <- Score 3D (completitud/correctitud/coherencia)
  |
  v
aif ci                            <- CI local (lint + test + build)
  |
  v
git push + PR                     <- Push al repo
  |
  v
/cr                               <- Code review (lee specs para contexto)
  |
  v
/qa                               <- QA (valida contra REQs y escenarios)
  |
  v
/verify                           <- Re-verificacion si es necesario
  |                                  Archiva specs al aprobar
  v
/done                             <- (Monday) Actualiza board y cierra item
  |
  v
MERGE

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:

• API Token: tu token v2 de Monday.com (se guarda en .env, nunca se commitea)
• Board ID: el ID del board donde esta tu sprint
• Grupos: nombres de los grupos Backlog, In Progress y Done en tu board
• Columna de estado: nombre de la columna de status

Genera automaticamente la configuracion MCP para que Antigravity y/o Gemini CLI puedan interactuar con Monday.

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)
.agent/workflows/feat.md           <- /feat (pipeline completo)
.agent/workflows/fix.md            <- /fix (pipeline de bugfix)
.agent/workflows/refac.md          <- /refac (pipeline de refactor)
.agent/workflows/explore.md        <- /explore
.agent/workflows/verify.md         <- /verify
.agent/workflows/qa.md             <- /qa
.agent/workflows/cr.md             <- /cr
.agent/workflows/onb.md            <- /onb
.agent/workflows/backlog.md        <- /backlog (Monday.com, si habilitado)
.agent/workflows/pick.md           <- /pick (Monday.com, si habilitado)
.agent/workflows/done.md           <- /done (Monday.com, si habilitado)

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.com, si habilitado)
.gemini/commands/pick.toml         <- /pick (Monday.com, si habilitado)
.gemini/commands/done.toml         <- /done (Monday.com, si habilitado)
.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)

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)
~/.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)
  + .env (monday_token)

  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 .agent/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 archivos (sobreescribe los existentes)
npx aif i

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