Probar dai

La forma más rápida de conocer dai: instala el CLI y corre el ciclo completo en tu máquina. Empieza sin credenciales (backend md) para ver el flujo entero en un par de minutos, y después pruébalo contra tu tracker real (ClickUp o Jira).

Esto es la guía para usar dai por primera vez. Para verlo funcionando sobre una US real (narrado), mira EJEMPLO-END-TO-END.md.

Instalar el CLI

npm i -g @dforce2055/dai
dai --version

Paso 1 — sin credenciales (backend md)

Recorre el loop completo link-us → check → stamp sin red ni tokens: todo local. Perfecto para ver cómo funciona antes de conectar nada.

# 1. Repo de prueba + bootstrap (dai init deja el .env.dai; elige "md" cuando pregunte)
mkdir /tmp/dai-test && cd /tmp/dai-test
git init && git commit --allow-empty -m init
git remote add origin git@github.com:TU-USUARIO/dai-test.git   # para los links de branch/commit
dai init --for both --pm md

# 2. Escribe una US (formato formato-us.md) y publícala con el CLI
cat > draft.md <<'EOF'
# Finalizar la compra del carrito

## Criterios de aceptación
- Dado un carrito vacío, cuando se finaliza, entonces se rechaza
EOF
dai publish draft.md             # crea la US → devuelve el key (con md, un slug)
#   ej: "US publicada en md: finalizar-la-compra-del-carrito"

# 3. El flujo del dev
dai link-us finalizar-la-compra-del-carrito   # branch + implements.yaml
git add -A && git commit -m "feat: guard carrito vacío"
dai check                        # ✅ al día

# 4. La demo del ⚠️: cambia el QUÉ y mira cómo se detecta solo
dai edit-us finalizar-la-compra-del-carrito   # la trae, la abres, valida, pregunta si sube spec_version
dai check                        # ⚠️ ATRASADO (exit 1)  → sugiere: dai link-us <id> --resync

# 5. Estampa la cobertura
dai stamp                        # con md, deja .dai/us/<slug>.coverage.md

En el paso 4, dai edit-us abre tu $EDITOR. Si no tienes uno configurado te pide editar el archivo y volver, así que también funciona con el archivo abierto en tu IDE. Agrega un criterio, guarda, y responde s a "¿subo spec_version?" para ver el ⚠️.

Con esto ya viste el ciclo entero. Ahora conéctalo a tu tracker real.

Paso 2 — contra tu tracker real (ClickUp)

Preparar ClickUp:

1. La US: una tarea con los criterios en la descripción, bajo un heading que matchee Criterios de aceptación (es lo que dai hashea).
2. El ID: en la tarea, ... → Copy ID (tipo 86cxyz).
3. El token: ClickUp → Settings → Apps → Generate (empieza con pk_...).

Config y flujo:

cat > .env.dai <<'EOF'
DAI_PM=clickup
DAI_CLICKUP_TOKEN=pk_XXXXXXXX
EOF
# El link a la tarea lo deduce dai solo. Solo si tu tracker vive en otra URL:
#   DAI_TRACKER_URL_TEMPLATE=https://mi-tracker/t/{id}
dai doctor                       # confirma DAI_PM=clickup y el token

dai link-us 86cxyz               # trae la US de ClickUp → branch + implements.yaml
git add -A && git commit -m "feat: ..."
dai check                        # ✅ al día

# → edita un criterio de la tarea en ClickUp (en el navegador). Después:
dai check                        # ⚠️ ATRASADO (lo detectó solo)
dai stamp                        # deja un COMENTARIO en la tarea con la cobertura

# ¿Editar la US sin salir de la terminal? La trae, la abres, valida y la devuelve:
dai edit-us 86cxyz --dry-run     # el preview completo, sin escribir en ClickUp

El .env.dai no se versiona: el token no se commitea, y el .env del equipo no se toca (ADR-0017; modelo de auth en ADR-0007).

Troubleshooting

Síntoma	Causa probable
no encontré la US <id>	ID mal, o el token no ve esa tarea
clickup 401	token inválido o expirado
edit-us dice que la US no tiene el formato mínimo	le falta el # Título o la sección ## Criterios de aceptación. Sin criterios no hay ac_hash y no hay link
check siempre da ⚠️	editaste la US entre link-us y check (esperado), o los criterios no están bajo el heading Criterios de aceptación
sin US en check	la tarea no tiene el bloque de criterios en la descripción
branch/commit vacíos en el stamp	falta el remoto git (git remote add origin …)