Setup para desarrolladores (Windows)
Guía paso a paso para dejar tu entorno listo y tomar una User Story de Jira, implementarla y abrir la Merge Request en GitLab con las skills de dai desde GitHub Copilot, con la trazabilidad QUÉ↔CÓMO armada desde el primer commit.
Es el otro lado del setup del funcional: ahí la US nace, aquí se implementa. Tú no discutes el QUÉ; lo tomas ya definido y eres dueño del CÓMO.
¿Qué son las skills? Son los comandos que ejecuta el agente en el chat de Copilot:
/link-us(abre el CÓMO atado a la US, sin que tipees el key a mano),/tdd(test primero) y/dai-review(review inline de la MR de un compañero). El CLIdaies lo mecánico:dai check,dai mr,dai stamp. Más abajo está la tabla de qué va dónde.
Atajo: si tu proyecto ya tiene dai (existe la carpeta .dai\), lo único que te falta es tu .env.dai con tus credenciales → salta al Paso 6.
Los ejemplos usan acme.atlassian.net, el proyecto PROJ, un GitLab en gitlab.acme.com y un repositorio tienda: reemplázalos por los de tu empresa.
Lo que vas a tener al terminar
Jira PROJ-125 → /link-us → feature/PROJ-125-… → dai mr
(la US que ya existe) (rama + + implements.yaml (MR precargada
el link) + tu código con la US)Y un dai check que te avisa solo si el PO cambió los criterios mientras implementabas.
Paso 1 — Instala Node
Descarga el instalador LTS desde 👉 https://nodejs.org y ejecútalo. Siguiente → Siguiente → Instalar.
Para comprobar que quedó, abre PowerShell (tecla Windows → escribe powershell → Enter):
node --versionTiene que responder algo como v20.11.0. Cualquier número 18 o mayor sirve.
Si dice que no reconoce el comando: cierra PowerShell, ábrelo de nuevo y reintenta. El instalador no refresca las ventanas que ya estaban abiertas.
Paso 2 — Instala dai
npm i -g @dforce2055/dai
dai --versiondai --help te lista todos los comandos. Para actualizarlo más adelante: dai upgrade.
Paso 3 — Prepárate para trabajar con el repositorio
Tres cosas, una sola vez por máquina. Si ya trabajas con este repositorio, probablemente las tengas:
| Qué | Para qué | Tutorial |
|---|---|---|
| git configurado (nombre + correo) | que los commits te atribuyan a ti, y que dai link-us sepa quién autora el link | Configurar git |
| Clave SSH en GitLab | que dai mr pueda subir la rama sin pedirte credenciales | Claves SSH |
glab instalado y autenticado | que dai mr cree la MR, no solo suba la rama | Instalar gh / glab |
En GitLab corporativo, el --hostname es obligatorio al autenticar:
glab auth login --hostname gitlab.acme.comSi tu equipo clona por HTTPS en vez de SSH (habitual en Windows corporativo), no pasa nada:
dai mrte deja completar el login del Git Credential Manager la primera vez que sube la rama. Hazlo con la ventana a la vista, porque ahí te lo pide.
Paso 4 — Instala las skills en Copilot
Este es el comando que te habilita los /comandos:
dai skills install --for copilot --globalComprueba que llegaron:
dir $env:USERPROFILE\.copilot\skillsTienes que ver 7 carpetas: dai-review, doc-to-backlog, grill-epic, grill-intent, grill-user-story, link-us, tdd. Las tuyas son link-us, tdd, dai-review y grill-intent; las tres grill-* restantes son del funcional, y no molestan.
Reinicia Copilot (cierra y abre la sesión) y escribe / en el chat, en modo Agent. Tienen que aparecer marcadas User Data — esa etiqueta confirma que salen de tu usuario.
Si no aparecen: ejecuta
/skillsdentro de Copilot para refrescar el listado. Si sigue sin verlas, recarga la ventana:Ctrl+Shift+P→ Developer: Reload Window.
¿Por qué
--global? Porque te sirven en cualquier repositorio, sin preparar nada. El repositorio igual va a tener su propia copia versionada (Paso 5), que es la que ve todo el equipo — y esa gana si difieren (ADR-0014).
Paso 5 — Inicializa dai en tu proyecto
Párate en el repositorio en el que vas a trabajar — el que ya tienes clonado — y comprueba si dai ya está instalado ahí:
cd $HOME\proyectos\tienda
dir .daiSi la carpeta
.dai\ya existe, tu proyecto ya tiene dai: no ejecutesdai init, el scaffold es del equipo y está versionado. Lo único que te falta es tu configuración personal → salta al Paso 6.
Si no existe, inicializa dai en el repositorio:
dai init --for copilot --pm jiraTe va a preguntar si quieres instalar OpenSpec: responde s. Es el motor del CÓMO — convierte la US en design.md + tasks.md con los comandos /opsx-*. Un dev sí lo usa.
Lo que deja:
✓ .dai/ moldes (templates) + reglas (governance) del método
✓ .env.dai.example creado (plantilla versionada)
✓ .env.dai creado (no versionado), DAI_PM=jira (completa el token)
✓ .gitignore ajustado (skills/constitución versionadas; .env.dai y settings.local.json fuera)
✓ .github/ pull_request_template.md — molde de PR atado al link
✓ Copilot: .github/skills/ (7) + copilot-instructions.mdTodo eso se commitea —menos el .env.dai, que ya quedó ignorado— en una rama chore/, y va por MR como cualquier otro cambio: es el scaffold que va a usar todo el equipo.
Si OpenSpec falló (proxy, permisos de npm), súmalo después:
powershellnpm i -g @fission-ai/openspec@latest openspec init --tools github-copilot
Si algún comando te avisa que el scaffold quedó viejo respecto de tu CLI, se actualiza con
dai syncy se commitea. No lo hagas en medio de una historia: es un cambio del equipo, no tuyo.
Paso 6 — Conecta Jira
El .env.dai es tuyo, lleva tus credenciales y no se versiona (ADR-0017). Es lo único que edita cada dev: el resto del scaffold es del equipo.
Necesitas un token de API de Atlassian: si no tienes, sigue 👉 Cómo obtener el token de API de Jira y vuelve con el token copiado.
Si el proyecto ya tenía dai, el archivo todavía no existe en tu copia — créalo desde la plantilla versionada:
copy .env.dai.example .env.dai(Si lo acabas de crear con dai init, ya está: solo hay que completarlo.)
Abre el repositorio en el editor y completa el .env.dai:
code .DAI_PM=jira
DAI_JIRA_BASE_URL=https://acme.atlassian.net
DAI_JIRA_EMAIL=tu.correo@acme.com
DAI_JIRA_TOKEN=el-token-que-copiaste
DAI_JIRA_PROJECT=PROJ
DAI_JIRA_ISSUETYPE=Story
DAI_JIRA_FIELDS_FILE=.dai/jira-fields.json
# Solo si vas a usar /dai-review sobre la MR de un compañero (token con scope `api`):
GITLAB_TOKEN=Guarda con Ctrl+S.
| Variable | Qué va | El error típico |
|---|---|---|
DAI_JIRA_PROJECT | La clave del proyecto: las letras antes del guion. Si tus tickets son PROJ-123, va PROJ. | Pegar la clave de un ticket. dai te lo dice y te da el comando correcto. |
GITLAB_TOKEN | Un Personal Access Token de GitLab con scope api. Es otro token, distinto del de glab y del de Jira. | Confundirlo con el de Jira. Cada servicio, el suyo (ADR-0007). |
La URL de la US en Jira sale sola de
DAI_JIRA_BASE_URL(…/browse/PROJ-125). Solo si tu Jira usa otro esquema de URLs agregasDAI_TRACKER_URL_TEMPLATE=https://…/{id}— el{id}se deja tal cual: es el marcador que dai reemplaza.
Paso 7 — Verifica
dai doctorLo que te importa ver:
✓ Copilot: 7 skills
✓ constitución Copilot (.github/copilot-instructions.md)
› adaptador de PM:
✓ DAI_PM=jira
✓ token de Jira presente (no verificado: eso lo dice `dai publish`)
✓ proyecto=PROJ (para dai publish)
✓ .dai/ al día con el CLI (v0.11.0)Ojo:
dai doctorsolo comprueba que el token esté escrito, no que funcione. La prueba de verdad es el paso siguiente.
Paso 8 — La prueba de fuego: toma una US de verdad
Vas a recorrer el ciclo completo con una US real del sprint. No se publica nada hasta el final — y ahí te pregunta antes.
1. Abre el CÓMO desde el ID de la US
En el chat de Copilot, en modo Agent:
/link-us PROJ-125O directo con el CLI, que es lo que la skill termina ejecutando:
dai link-us PROJ-125Trae la US de Jira, calcula el ac_hash de sus criterios y deja dos cosas:
✓ branch: feature/PROJ-125-finalizar-la-compra-del-carrito
✓ archivo: openspec/changes/finalizar-la-compra-del-carrito/implements.yaml (ac_hash 380d814b)Ese implements.yaml es el único registro autorado del método (ADR-0004): el resto de la trazabilidad se deriva, este se escribe. "Autorado" significa que lo escribe alguien —no que lo tipees tú ahora—, y dai link-us ya te lo dejó casi entero:
change: finalizar-la-compra-del-carrito
repo: tienda
implements:
- id: PROJ-125 # ← ya está: lo puso link-us desde el ID que validó
version: v1 # ← ya está
ac_hash: 380d814b # ← ya está: calculado sobre los criterios de la US
introduces:
- <capacidad-tecnica> # ← lo ÚNICO pendiente, y NO se completa ahora
autor: tu.nombre # ← ya estáNo completes
introducestodavía. Es lo que este change introduce en el repo: las capacidades técnicas nuevas. Recién al terminar de implementar se sabe cuáles son —al empezar sería adivinar—, así que se completa al cerrar la implementación, no acá.
Y normalmente no lo escribes tú: lo escribe el agente. Cuando /opsx-apply termina de aplicar las tareas, el que implementó es el que sabe qué capacidades quedaron: pídele que complete introduces (o que borre el bloque si el change no introdujo ninguna) como último paso. Tú lo revisas en la MR — el archivo va versionado con el código justamente para que se lea en la revisión, igual que cualquier otro cambio.
El key no se tipea nunca a mano. La rama y el
implements.yamlsalen los dos del mismo ID validado: por eso el link no puede quedar mal escrito. El campo que sí requiere criterio humano —introduces— es el único que queda abierto, y no es un dato del tracker: es tu lectura de lo que el change agregó.
Si te dice que la US no tiene criterios de aceptación, frena: no es un problema de tu setup. Esa US no cumple el DoR y vuelve al PO.
2. Arma el CÓMO y programa
/opsx-explore → entender el terreno
/opsx-propose → design.md + tasks.md sobre la rama ya linkeada
/opsx-apply → el agente implementa las tareas con test primero (/tdd)En Copilot los comandos van con guion, no con dos puntos. OpenSpec nombra sus comandos según el asistente: en Claude Code son
/opsx:propose(namespace anidado), y en Copilot y Cursor son/opsx-propose, por el nombre del archivo que generan (.github/prompts/opsx-propose.prompt.md). Mucha documentación —la de OpenSpec incluida— muestra solo la forma de Claude.Si tipeas
/opsx:proposeen Copilot no falla con un error: no encuentra nada, se queda con tu texto suelto y se pone a improvisar. Se ve como un agente que "hace lo que quiere", que se saltea el gate y que arranca a programar sin haber escrito la propuesta. Si te pasa eso, lo primero que hay que mirar es cómo escribiste el comando.
Tú validas el diseño, decides qué comportamientos importa testear y revisas lo que escribió el agente: eres responsable del código, no la IA.
Cuando /opsx-apply termina, cierra el link — es el momento en que ya se sabe qué introdujo el change:
Completa `introduces` en el implements.yaml con las capacidades técnicas que agregó este
change (o borra el bloque si no agregó ninguna).Revisa lo que puso. introduces no es un dato del tracker: es la lectura de lo que el change agregó al repo, y viaja versionado para que se lea en la MR.
3. Commitea y comprueba el link
git add -A
git commit -m "feat(carrito): rechazar la compra con carrito vacío"
dai check✅ PROJ-125 al día (v1)Si el PO tocó los criterios mientras implementabas, en vez de eso vas a ver:
⚠️ PROJ-125 ATRASADO: implementaste 380d814b, la US viva es 9f2c1a04 (v2)
El QUÉ cambió desde que lo implementaste. Para resincronizar:
dai link-us PROJ-125 --resync # re-estampa el ac_hash contra la US viva
Después, revisa si tu implementación cubre el criterio nuevo.Eso es exactamente lo que dai viene a resolver: no te avisa una persona, te avisa el link. Lee qué cambió en Jira, cúbrelo, y recién entonces resincroniza.
4. La MR
dai mr --base develop(dai mr y dai pr son el mismo comando; mr es el nombre natural en GitLab.)
Te muestra todo antes de tocar nada:
── Pull Request a crear ──────────────────────────────
título: PROJ-125: Finalizar la compra del carrito
de: feature/PROJ-125-finalizar-la-compra-del-carrito
a: develop
US: PROJ-125 — la branch 'feature/PROJ-125-…' nombra PROJ-125
forge: gitlab (glab)
─────────────────────────────────────────────────────Debajo va el cuerpo completo de la MR, precargado con la US, el estado del dai check, tus commits y los enlaces. Recién ahí pregunta:
¿Publico la branch y creo el PR con glab? (s/N)Responde n para este ensayo si no quieres publicar todavía: te guarda el cuerpo en un archivo temporal y no hace nada. Cuando sea de verdad, s sube la rama y crea la MR.
La línea
US:dice de dónde salió la historia. Si ahí aparece una US que no es la tuya, frena y revisa la rama: el título es lo único que se ve en la lista de MRs, y una MR rotulada con la historia de otro rompe justo lo que dai garantiza.
5. Después del merge
dai stamp # estampa en Jira: implementado por <repo>, con rama y commit ancla
dai done --base develop # vuelve a la base, actualiza y borra la rama local si está mergeadadai stamp deduce qué US estampar del nombre de tu rama. Si el repositorio tiene varias vivas y no puede saberlo, te pregunta antes de escribir en Jira: un comentario en el tracker no se deshace.
Si las cinco partes te salieron, tu entorno funciona de punta a punta.
Qué va dónde
⚠️ Las skills no se ejecutan en PowerShell. Son acciones que le pides a un agente, en el chat de Copilot en modo Agent, escribiendo / adelante.
| Qué | Dónde se escribe | Ejemplos |
|---|---|---|
| Los comandos de dai | PowerShell, parado en el repositorio | dai link-us · dai check · dai mr · dai stamp · dai done |
Las skills (empiezan con /) | El chat de Copilot, modo Agent | /link-us · /tdd · /dai-review · /grill-intent |
| Los comandos de OpenSpec | El chat de Copilot | /opsx-explore · /opsx-propose · /opsx-apply (con guion: ver arriba) |
Cuando algo falla
El agente no respeta los pasos: implementa sin escribir la propuesta
Síntoma: le pides /opsx:explore o /opsx:propose y el agente te explica el método, te pide que le pegues el ticket a mano, o directamente se pone a escribir código sin haber generado proposal.md / design.md / tasks.md. Hay que frenarlo a mano en cada paso.
Casi siempre es el nombre del comando. En Copilot son /opsx-explore, /opsx-propose, /opsx-apply — con guion. Con los dos puntos, Copilot no encuentra ningún comando, no avisa, y toma tu texto como una charla suelta: el workflow nunca se cargó. Comprueba qué tienes disponible:
dai doctorEn el apartado OpenSpec te dice los comandos exactos de tu asistente:
› OpenSpec — los comandos van en el chat del asistente, no en la terminal:
✓ Copilot: /opsx-explore · /opsx-propose · /opsx-apply · /opsx-archiveSi dice que no hay comandos, falta inicializar OpenSpec:
openspec init --tools github-copilot --forceDespués reinicia VS Code: los comandos nuevos no aparecen hasta que se recarga.
Con el nombre correcto el agente frena al terminar la propuesta y espera tu aprobación antes de implementar.
Si aun así se pasa de largo —o si te nombra comandos con dos puntos que no existen—, mira la versión de OpenSpec: dai doctor te avisa si está vieja. Hasta la 1.10.0, los prompts que OpenSpec generaba para Copilot pedían herramientas que Copilot no tiene, y su única forma de frenar a preguntarte no existía. Actualiza:
npm i -g @fission-ai/openspec@latest
openspec init --tools github-copilot --forceEn cualquier caso, la aprobación del diseño es tuya: si ves que arrancó a programar sin que hayas dicho que sí, páralo y pídele la propuesta.
dai link-us dice que no encontró la US en jira
Por orden de frecuencia:
- El key está mal o es de otro proyecto. Cópialo de la URL del ticket (
…/browse/PROJ-125→PROJ-125). - No estás parado en el repositorio que tiene el
.env.dai. dai lee la configuración del directorio actual:cdal repositorio y reintenta. - El token venció. Ver el
jira 401de abajo.
dai check o dai publish dicen jira 401
El token no es válido o venció. Genera uno nuevo (tutorial) y pégalo de nuevo en el .env.dai. Comprueba también que DAI_JIRA_EMAIL sea exactamente el correo de tu cuenta de Atlassian.
dai mr dice hay N US vivas y la branch … no dice cuál
Pasa cuando el repositorio tiene varios changes vivos y tu rama no nombra ninguno (una rama que no creó dai link-us). No elige por ti: te lista las candidatas y te pregunta. Sin terminal interactiva (en un pipeline) falla, y se lo dices explícito:
dai mr --us PROJ-125dai mr dice no hay una US linkeada (implements.yaml)
Tu rama no tiene link y sí debería tenerlo (feature/… es trabajo de producto). Ejecuta dai link-us <ID> primero.
Si en cambio es un cambio sin historia (tooling, limpieza, documentación), nombra la rama chore/… o docs/…: esas están exentas de US (governance/branch-naming.md), y dai mr arma la MR sin US, con el título de tu último commit — en vez de colgarle la historia de un compañero.
dai mr no pudo subir la rama
Te muestra el error real de git debajo. Lo más común la primera vez contra un remoto HTTPS corporativo es que git necesite abrir el login y no lo hayas completado. Autentica subiendo la rama a mano una vez y vuelve:
git push -u origin feature/PROJ-125-finalizar-la-compra-del-carrito
dai mrdai mr dice que glab no está instalado
La rama ya se subió; solo faltó crear la MR. dai te deja el cuerpo en un archivo y el comando listo para ejecutar a mano. Instala glab (tutorial) o crea la MR desde la web pegando ese cuerpo.
Al salir a la red dice que no puede verificar el certificado
Es el proxy de tu empresa, que intercepta las conexiones con su propio certificado. Pide a Sistemas el archivo .pem de la CA y decláralo:
$env:NODE_EXTRA_CA_CERTS="C:\ruta\ca-empresa.pem"⛔ Nunca uses
NODE_TLS_REJECT_UNAUTHORIZED=0, aunque lo veas sugerido en internet o te lo proponga un asistente. Eso no arregla nada: apaga la verificación entera, y por esa conexión viaja tu token de Jira.
dai check imprime el ✅ y después tira Assertion failed … UV_HANDLE_CLOSING
✅ PROJ-125 al día (v1)
Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), file src\win\async.c, line 94El resultado que ves es el bueno: el chequeo terminó bien. Lo que revienta después es el cierre del proceso de Node en Windows, desarmando la conexión que se usó para consultar Jira. Es un problema de Node, no de tu configuración ni de tu US.
Ya está corregido en dai. Actualiza:
dai upgradeImportaba arreglarlo porque el proceso terminaba con un código de error aunque el chequeo hubiera pasado: un dai check verde se reportaba rojo en el CI o en un hook de git.
El CI falla con "falta el link"
Es el gate de governance/ci-rules.md, ejecutable con dai check --ci. Córrelo local para ver lo mismo que ve el CI:
dai check --ciTe dice qué exige tu rama y por qué: feature/ siempre requiere US, chore//docs//ci/ y compañía están exentas, fix/ solo si el nombre trae un ID.
Reglas de seguridad
- 🔒 El
.env.daitiene tus tokens: son contraseñas. Nunca lo pegues en un chat, en un ticket ni en una MR. Ya está fuera del control de versiones — déjalo así. - 🔑 Un token por servicio: Jira, GitLab y
glabson tres cosas distintas. No los reutilices ni los compartas. - 🙅 No aceptes atajos que bajen la seguridad. Si algo falla por un certificado, se declara la CA; no se apaga la verificación.
- ♻️ Rota los tokens periódicamente y revoca los que no uses. Si se filtra uno, revócalo de inmediato.
Lo que nunca tienes que hacer
- No cambies el contenido funcional de la US ni sus criterios. Si te parece que el QUÉ está mal, devuelves la US al PO: no se decide negocio desde el código. ¿Apareció un criterio nuevo mientras implementabas? Se empuja al tracker con
dai update-us PROJ-125, para que el PO se entere de que la historia creció. - No empieces sin una US con criterios testeables. Sin DoR no hay dónde anclar el link, y eso es vibe coding con más pasos.
- No edites el
ac_hasha mano para quedai checkdeje de quejarse. El ⚠️ es información, no un obstáculo: se resuelve con--resyncdespués de cubrir el criterio nuevo. - No apruebes tu propia MR. Tú haces tu propio review (paso 5 de la guía del dev); la firma es de un compañero.
- No commitees el
.env.daini pegues tokens en la descripción de una MR.
¿Qué sigue?
El entorno ya está listo y probado. Lo que viene es tu día a día:
- 👉 Guía del dev / ingeniero — empieza aquí. Tu rol de punta a punta: de qué eres dueño, qué no tocas, y los 10 pasos del día a día.
- Ejemplo end-to-end — el ciclo completo narrado sobre una US real, del
link-usalstamp. - Scrum con IA — los 10 pasos del equipo, para ubicar dónde entra tu parte y dónde termina.
- Glosario — el vocabulario del método: el QUÉ y el CÓMO,
ac_hash, atrasado, el link.
Eres dueño del CÓMO y autor del link. El QUÉ te llega definido, y el
ac_hashes lo que hace que te enteres si cambia — sin reuniones y sin leer Jira todos los días.