dai — Desarrollo Asistido por IA

dai ayuda a los equipos a desarrollar software en menos tiempo y con más calidad — sacándose de encima la burocracia para enfocarse en lo que importa: pensar, documentar y construir. La IA acelera; dai mantiene el control y la trazabilidad.

Qué es y qué resuelve

Desarrollar con IA es rápido, pero sin método el código se desconecta del por qué se escribió, aparece el vibe coding, y el qué (negocio) se mezcla con el cómo (técnica). dai es una metodología asistida por IA que ataca eso combinando tres piezas:

• 🖥️ El CLI dai — un comando para cada fase del desarrollo (definir, linkear, verificar, revisar, publicar). Mantiene atado el requerimiento al código, del principio al fin.
• 🧩 OpenSpec — convierte el qué en un cómo (diseño + tareas) con ayuda de agentes de IA, sin que nadie escriba la burocracia técnica a mano.
• 🤖 La IA — para debatir, analizar, conectarse a tus herramientas por MCP (Jira, ClickUp, GitHub, Gitlab) y automatizar el papeleo, para que te enfoques en documentar y construir.

Juntas hacen que la IA potencie tu desarrollo sin perder el control: todo lo que se construye queda linkeado a por qué se construyó, y la máquina te avisa sola cuando algo se desincroniza. Del solo developer a un equipo entero de desarrollo — el mismo método, con Claude, Copilot o Cursor.

Cómo funciona (3 ideas)

• Separa el QUÉ del CÓMO, con dueños distintos, linkeados ida y vuelta.
• El link se autora una sola vez (en el código, implements.yaml); la cobertura inversa se genera, nunca se mantiene a mano.
• @version = número + hash de criterios: cuando el QUÉ cambia, los CÓMO atrasados se marcan solos.

Quickstart

Requiere Node ≥ 18 (el CLI no tiene dependencias). Elige tu rol:

🟡 Como analista funcional — quiero crear historias o épicas

Trabajas en tu asistente (Claude Desktop / Copilot en el IDE), no en la terminal. Una vez, deja las skills disponibles:

npm i -g @dforce2055/dai        # el CLI
dai skills install              # skills de IA → Claude y Cursor (global por defecto)

Y después, en el chat del asistente, según lo que tengas:

/grill-user-story               # una historia → te interroga y la publica en el tracker
/grill-epic                     # algo grande → una épica partida en varias US
/doc-to-backlog <PDF/Word>      # un documento de análisis → backlog candidato de épicas + US
/grill-intent                   # (opcional) Gate 0: ¿es el problema correcto, antes de escribir?

Las skills te interrogan hasta que la historia es testeable (nunca inventan requerimientos: los sacan a preguntas), y la publican en el tracker que configuraste (DAI_PM en el .env): por el MCP de Jira/ClickUp si está conectado, o con dai publish <us.md> si no (crea el issue vía token). Tú respondes y decides.

🔵 Como dev — tengo una US y voy a implementarla

Una vez, preparas el repo:

npm i -g @dforce2055/dai
cd mi-repo && dai init          # bootstrap: skills + tracker + OpenSpec + PR template
# completa el token del tracker en .env  (o DAI_PM=md para probar sin credenciales)
dai doctor                      # verifica que todo quedó en su lugar

Y por cada US, el ciclo completo:

dai link-us <ID>                # trae la US del tracker → branch + implements.yaml

/opsx:explore  →  /opsx:propose # exploras la solución y armas el diseño + tareas
/opsx:apply  ·  /tdd            # implementas con tests primero → genera los commits

dai check                       # ¿tu código sigue al día con la US?  ✅ / ⚠️ atrasado
# revisas tu propio código + smoke test local antes de la PR
dai pr --assignee <compañero>   # crea la PR precargada y se la asigna a un compañero

/dai-review <PR>                # tu compañero deja un review estándar; un humano aprueba

dai stamp                       # al mergear: estampa la cobertura en el tracker

Cómo usarlo — el flujo, paso a paso

Guía completa con salidas reales en docs/PROBAR.md; un caso narrado en docs/EJEMPLO-END-TO-END.md.

flowchart TD
    subgraph QUE["🟡 EL QUÉ · funcional (PO / analista)"]
        A["💡 Idea / problema"] -->|"/grill-user-story 🤖"| B["📋 US testeable"]
        B -->|"dai publish ⚙️ · o MCP"| C[("🎯 US en el tracker (Jira / ClickUp)")]
    end
    subgraph COMO["🔵 EL CÓMO · técnico (dev)"]
        C -->|"dai link-us ⚙️"| D["🌿 branch + implements.yaml"]
        D -->|"/opsx:propose 🤖"| E["📐 design + tasks"]
        E -->|"/tdd 🤖"| F["🧪 código + tests"]
        F -->|"dai check ⚙️"| G{"¿al día?"}
        G -->|"✅ sí"| H["🔀 dai pr ⚙️"]
        H -->|"/dai-review 🤖 + 👤 firma"| I["✅ merge"]
        I -->|"dai stamp ⚙️"| J[("🎯 cobertura estampada")]
    end
    G -.->|"⚠️ el QUÉ cambió (@version)"| C

Leyenda: 🤖 skill de IA · ⚙️ comando dai · 👤 un humano firma · 🎯 el tracker. La línea punteada es la detección de drift: si el PO edita la US, dai check lo marca ⚠️ y volvés a sincronizar. (El diagrama se renderiza en GitHub; el detalle, en la tabla.)

| # | Fase | Cómo | Quién | |---|---|---|---| | 1 | Instalar el CLI | npm i -g @dforce2055/dai (o npm link en dev) · dai --version · actualizar después: dai upgrade | dev | | 2 | Bootstrap del repo | dai init → .dai + Claude/Copilot/Cursor + config + PR template | dev/lead | | 3a | Definir el QUÉ | /grill-user-story (una US) · /grill-epic (algo grande) · /doc-to-backlog (un doc) — te interrogan hasta una US testeable | PO / analista | | 3b | Publicar la US | la skill la sube al tracker vía MCP, o con dai publish <us.md> (crea el issue vía token, sin MCP) → devuelve el key | PO / IA | | 4 | Linkear la US | dai link-us <ID> → branch + openspec/changes/<id>/implements.yaml | dev | | 5 | Verificar / listar | dai check (¿al día?) · dai ls (qué implementa el repo) | dev | | 6 | Resincronizar (si el PO editó la US) | dai link-us <ID> --resync | dev | | 7 | Diseñar el CÓMO | en el asistente: /opsx:explore → /opsx:propose → design + tasks | dev + IA | | 8 | Implementar | /opsx:apply → implementa la US con TDD y genera los commits | dev + IA | | 9 | Code review propio | revisas tu implementación (correctitud + calidad) antes de la PR | dev | | 10 | Smoke test | pides al agente un smoke local del flujo | dev + IA | | 11 | Crear la PR | dai pr → pregunta la branch base, arma el texto, lo muestra, confirma, pushea y crea la PR/MR | dev | | 12 | Review de un partner | skill /dai-review <PR> deja un comentario estándar; un humano aprueba | partner | | 13 | Merge + estampar | al mergear: dai stamp → cobertura inversa en el tracker | dev / CI | | 14 | Cerrar la US | dai done → vuelve a la base, actualiza y borra la branch local (si está mergeada) | dev |

Paso 3b (publicar): el MCP crea el issue interactivamente; dai publish necesita el token del tracker en .env (Jira además DAI_JIRA_PROJECT, ClickUp DAI_CLICKUP_LIST_ID).

Paso 7 (OpenSpec): dai init te ofrece instalarlo e inicializarlo solo. Si los comandos /opsx:* no aparecen en el asistente, reinicia el IDE (se cargan al arrancar).

Paso 11 (PR): necesita un remoto git (origin) y gh/glab autenticado. Sin remoto, dai no crea la PR (te deja el texto listo igual).

Comandos

| Comando | Qué hace | |---|---| | dai init [<repo>] | scaffolder interactivo del repo. Flags: --for claude\|copilot\|both\|cursor\|all (asistente, default all) · --pm md\|jira\|clickup (tracker) · --openspec | | dai skills install [--global \| --local <repo>] [--force] [--dry-run] [--for claude\|cursor\|all] | instala/actualiza las skills de dai en Claude y/o Cursor (--for all por defecto). --force re-copia. Alias: dai install. Ej: dai skills install --local . --for cursor --force | | dai skills install --from <git-url\|path>[#ref] [--for …] | instala skills externas (por-stack: .NET, Java, …) desde un repo/dir, convertidas para los 3 asistentes. Self-service, one-off, sin registro; dai sync no las toca. Colisión con una skill de dai → salta (ADR-0013). Ej: dai skills install --from github.com/mi-org/net-skills | | dai sync [--dry-run] [--for <asistentes>] | refresca skills, constitución, templates y PR template a la versión del CLI — aditivo (no pisa tu CLAUDE.md), no toca el .env ni OpenSpec. Detecta los asistentes del repo o pasás --for. --dry-run muestra qué cambiaría (ADR-0010) | | dai upgrade [--check] [--dry-run] · alias dai update | actualiza el CLI global a la última publicada (npm i -g …@latest) — self-update. No toca el repo: reporta el drift del scaffold pero deja el dai sync al mantenedor. --check solo informa · --dry-run muestra el comando (ADR-0012) | | dai publish <us.md> | crea la US en el tracker (Jira/ClickUp/md) desde un .md y devuelve el key. Es el fallback del MCP para publicar sin el asistente | | dai link-us <ID> [--us <md>] | crea branch + implements.yaml; sin --us trae la US del tracker | | dai link-us <ID> --resync | re-estampa el ac_hash contra la US viva (tras un ⚠️ de check) | | dai check | compara tu código vs la US viva → ✅ al día / ⚠️ atrasado (exit code = gate de PR) | | dai ls [--json] | lista las US que implementa el repo + su link al tracker | | dai pr [--assignee u] [--base b] [--draft] [--yes] | crea TU PR/MR precargada: pregunta la branch base (default main), muestra el texto y confirma antes de publicar | | dai stamp | estampa la cobertura inversa en el tracker (branch + commit-ancla) | | dai done [--base main] [--force] | cierra la US: vuelve a la base, fetch --prune + pull, y borra la branch local si está mergeada (chequeo estricto; --force la borra igual). Redes: no estar en la base, sin cambios sueltos, sin commits sin pushear | | dai archive [<change>] [--skip-specs] | funde los delta specs del change en las specs canónicas (openspec/specs/) y lo archiva. Lo corre el aprobador de la PR (gate de aprobación, ADR-0011); detecta el change activo o le pasás el nombre. Envuelve openspec archive | | dai forge comment <ref> --body-file <f> · dai forge pr <ref> | comentar / leer una PR/MR (GitHub/GitLab) | | dai ac-hash <us.md> | calcula el hash de los criterios de aceptación de una US | | dai doctor · dai docs <dest> · dai version | diagnóstico del entorno (incluye version-drift del scaffold) · copiar la doc · versión (dai version avisa si tu repo quedó atrás) |

🆕 Mantené tu repo al día — dai sync. Las skills, la constitución y los templates son un caché derivable del CLI. Cuando actualizás dai (dai upgrade), dai doctor y dai version te avisan solos si tu scaffold quedó atrás — con color y un ⬆️ —, y dai sync lo refresca: aditivo (conserva tu CLAUDE.md propio), sin tocar el .env ni OpenSpec. Probá sin riesgo con dai sync --dry-run. El versionado es semver: patch/minor no rompen nada; solo un major pediría migración. (ADR-0010)

🧩 Skills de cualquier stack — dai skills install --from. Además de las skills de dai, cada equipo suma las suyas (por-stack: .NET, Java, Rust…) desde su propio repo: dai skills install --from github.com/tu-org/net-skills. dai las convierte para los 3 asistentes (Claude/Cursor/Copilot) e instala. dai es el distribuidor de skills de cualquier stack, sin opinar sobre su contenido — self-service, sin registro; dai sync sigue siendo solo de dai. (ADR-0013)

La fuente puede ser pública, privada (por SSH) o un path local: dai no hace auth propia, delega en git — si podés git clone el repo, dai instala desde ahí. Para privados usá la forma SSH ([email protected]:tu-org/net-skills.git), consistente con el modelo de auth de dai (ADR-0007). Público = cero fricción entre equipos/máquinas.

Cómo armar una skill que dai ingiera. Cada skill es un directorio con un SKILL.md en formato Agent Skills de Claude: frontmatter con name y description (obligatorios) + el cuerpo con las instrucciones. dai valida ese contrato: si a un SKILL.md le falta name/description, o un dir no tiene SKILL.md, lo saltea con un warn (no instala una skill rota). El contenido no lo valida — bajo tu criterio. Molde: templates/skill.md · ejemplos reales: las skills de dai en skills/.

Skills (se invocan en el asistente): /doc-to-backlog · /grill-intent · /grill-epic · /grill-user-story · /link-us · /tdd · /dai-review. Config del tracker (md|jira|clickup) y tokens: en .env — ver .env.example. Auth (SSH + tokens): ADR-0007.

El flag --for — ¿para qué asistente preparo el repo?

dai init genera los archivos que hacen que las skills de IA (grill-user-story, link-us, etc.) estén disponibles en tu asistente. --for elige para cuál:

| Valor | Genera | Elígelo si… | |---|---|---| | --for claude | .claude/skills/ + CLAUDE.md | tu equipo usa Claude (Code / Desktop) | | --for copilot | .github/prompts/*.prompt.md + .github/copilot-instructions.md | tu equipo usa GitHub Copilot (en VS Code / JetBrains) | | --for cursor | .cursor/skills/ + .cursor/rules/dai-constitution.mdc | tu equipo usa Cursor Agent | | --for both | Claude + Copilot | equipo mixto sin Cursor | | --for all (default) | Claude + Copilot + Cursor | quieres dejar el repo listo para cualquier asistente |

• Combinables: pasá un subconjunto separado por coma — --for claude,cursor o --for copilot. all = los tres · both = Claude+Copilot. (Igual en dai install, aunque ahí Copilot no aplica: no tiene skills instalables.)
• Es aditivo, no destructivo: los conjuntos conviven sin pisarse (viven en carpetas distintas). La misma skill se transforma al formato de cada asistente.
• Si ejecutas dai init sin flag, te lo pregunta de forma interactiva.
• No afecta el CLI: dai link-us / check / stamp funcionan igual con cualquier --for (o ninguno) — el flag solo prepara la invocación de skills en el asistente.
• Ante la duda, --for all: cubre a todo el equipo y no cuesta nada.

Lo que obtienes en tu repo

Después de dai init (con --for all):

mi-repo/
├── CLAUDE.md                       · Constitución del proyecto (auto-cargada por Claude)
├── .env                            · configurado con tu tracker (gitignored, completa el token)
├── .claude/skills/                 · Las skills, locales al repo (el equipo las hereda)
│   └── doc-to-backlog · grill-intent · grill-epic · grill-user-story · link-us · tdd · dai-review
├── .github/
│   ├── copilot-instructions.md     · La constitución, auto-inyectada en cada chat de Copilot
│   ├── prompts/*.prompt.md         · Las mismas skills, generadas en formato Copilot
│   └── pull_request_template.md    · Molde de PR/MR atado al link
├── .cursor/
│   ├── skills/                     · Las mismas skills, en formato Cursor
│   └── rules/dai-constitution.mdc  · Constitución always-on de Cursor
└── .dai/
    ├── templates/                  · formato-us · epica · DoR · DoD · adr · pull-request
    └── governance/                 · branch-naming · ci-rules · commit-convention

Al trabajar se suma:
└── openspec/changes/<id>/          · implements.yaml (el link) + proposal · design · tasks

¿Cómo se ve un implements.yaml? Ejemplo lleno + el árbol de dónde vive entre los artefactos de OpenSpec, en ADR-0004.

Dónde se invocan las skills (por asistente)

Las skills se invocan en el asistente — no en todas sus superficies (límite del asistente, no de dai):

| Asistente / superficie | ¿Skills? | Mecanismo | |---|---|---| | Claude Desktop | ✅ | ~/.claude/skills/ (global) — sin IDE ni consola | | Claude Code | ✅ | ~/.claude/skills/ + .claude/skills/ del repo | | Cursor Agent (IDE) | ✅ | .cursor/skills/*/SKILL.md + .cursor/rules/*.mdc | | Copilot app / CLI | ✅ | ~/.copilot/skills/ (global) + .github/skills/ del repo | | Copilot en VS Code / JetBrains | ✅ | ídem (modo agente) | | Copilot code review · cloud agent | ✅ | .github/skills/ del repo | | Chat de github.com | ❌ | no carga skills |

El analista no necesita IDE: cierra el ciclo con Claude Desktop o con la app / CLI de Copilot. El CLI dai corre en cualquier terminal, con cualquier asistente o ninguno.

Copilot lee el SKILL.md tal cual, sin conversión (ADR-0014). Si vienes de dai ≤ 0.7, corre dai init --for copilot una vez: cambia los .github/prompts/*.prompt.md por .github/skills/ (con los templates/, que antes se perdían) y limpia los viejos para que no te dupliquen cada /comando.

Se adapta a cualquier escala

Un protocolo invariante para, sólo developer, equipos chicos y grandes, una misma ceremonia. N1 (un dev, todo local) → N2 (equipo + tracker) → N3 (muchos repos, CI que estampa). Cada capa se agrega cuando es necesario, no antes. El dev que lo usa en un equipo chico, está listo para usarlo en equipos grandes distribuidos.

Por dónde empezar a leer

1. docs/MANIFIESTO.md — la ley: 4 valores + 15 artículos. 5 minutos.
2. docs/SCRUM-CON-IA.md — tu Scrum de siempre, en 10 pasos con IA.
3. docs/EJEMPLO-END-TO-END.md — el golden path sobre una US real.
4. docs/METODOLOGIA.md — el detalle del protocolo y el porqué.

Además: docs/glosario.md · guías por rol (po · dev · lead) · decisiones (ADRs) · landing.

Qué hay en la caja (el paquete dai)

dai/
├── cli/            🖥️  el binario `dai` (Node, cero dependencias) + su suite de tests
├── docs/           📖  la metodología: MANIFIESTO · METODOLOGIA · SCRUM-CON-IA · EJEMPLO ·
│                       glosario · guias/ · detalle/ (10 pasos) · adr/ (0001–0009)
├── templates/      🧩  los moldes (formato-us · epica · DoR · DoD · adr · pull-request)
├── skills/         🤖  doc-to-backlog · grill-intent · grill-epic · grill-user-story · link-us · tdd · dai-review
├── governance/     🛡️  branch-naming · ci-rules · commit-convention
├── index.html      📊  landing autocontenido (la historia); publicable por GitHub Pages
└── manifest.yaml · VERSION · install.sh (shim) · .env.example

Licencia

GPLv3 (GPL-3.0-or-later) — ver LICENSE. Software libre: puedes verlo, auditarlo, modificarlo y redistribuirlo; si distribuyes una versión modificada, tiene que quedar también libre. Libre no es gratis: se puede cobrar por uso, soporte o desarrollo. Detalle en ADR-0006.

Ayúdanos a mejorar dai 🌱 — es software libre y una metodología viva: se hace mejor con la comunidad. Si te sirve, cuenta tu experiencia, reporta lo que falle y propón mejoras. Toda contribución al método o a la herramienta es bienvenida. Empieza por CONTRIBUTING.md.

Agradecimientos

dai se apoya en ideas y aprendizajes de la comunidad. En particular, gracias a Matt Pocock por su aporte con las skills y por su canal de YouTube explicándolas — su trabajo nos ayudó a construir esta herramienta.

Seguridad: SECURITY.md · Conducta: CODE_OF_CONDUCT.md