/tbd es un comando de Claude Code que sincroniza el trabajo técnico con GitHub usando Trunk-Based Development. No es solo un helper de git — es el puente entre los artefactos SDD guardados en Engram y el estado visible en GitHub: issues, checkboxes, Kanban, commits y PRs.
Esta guía explica cada paso del comando: qué hace en la primera ejecución, cómo funciona el Modo Light para bugs y fixes, y cómo el Modo Full conecta cada fase de SDD con una acción concreta en GitHub.
¿Qué es /tbd y por qué existe?
En Trunk-Based Development existe una sola rama permanente: main. Las features son ramas efímeras que nacen desde main y deben volver a main en 1 a 2 días máximo. No hay develop, no hay release branches. El trunk siempre tiene que estar deployable.
El problema es que trabajar así sin sistema genera caos: ¿quién sabe qué está en esa rama? ¿el issue refleja el estado real? ¿el PR tiene contexto de por qué se hizo el cambio? /tbd resuelve esto conectando el ciclo SDD con GitHub de forma automática y trazable.
/tbd tiene dos modos detectados automáticamente:
- /tbd sin argumentos → Modo Full: lee Engram fase por fase y sincroniza GitHub
- /tbd "descripción" con texto → Modo Light: flujo directo para bugs y fixes pequeños
Bootstrap: la primera vez en un proyecto
La primera vez que /tbd corre en un proyecto nuevo, verifica que main exista y esté configurado como rama principal, crea ONBOARDING.md detectando el stack del proyecto (package.json, pyproject.toml, go.mod, etc.), y configura el GitHub Project Kanban.
El Kanban de GitHub Projects por defecto solo tiene 3 opciones (Todo, In Progress, Done). /tbd elimina el campo Status default y lo recrea con 4 opciones via GraphQL:
# /tbd crea el proyecto y recrea el Status con 4 columnas:
# Todo → In Progress → In Review → Done
gh project create --title "[repo] Board" --owner @me
# Luego elimina el Status default (3 opciones) y crea uno nuevo (4 opciones)
gh api graphql -f query="mutation {
createProjectV2Field(input: {
projectId: \"$PROJECT_ID\"
dataType: SINGLE_SELECT
name: \"Status\"
singleSelectOptions: [
{name: \"Todo\", color: GRAY},
{name: \"In Progress\", color: BLUE},
{name: \"In Review\", color: YELLOW},
{name: \"Done\", color: GREEN}
]
}) { projectV2Field { id } } }"
El bootstrap es idempotente: si ONBOARDING.md ya existe o el proyecto ya tiene Kanban, /tbd lo detecta y no lo vuelve a crear.
Modo Light: bugs y fixes en 4 pasos
Para cambios que no justifican el peso completo de SDD. Se invoca con texto: /tbd "descripción del problema".
Paso 1 — Crear el issue
/tbd crea un issue con label bug a partir de la descripción. El cuerpo incluye el problema expandido, una lista de tareas con checkbox, y los criterios de aceptación.
gh issue create \
--title "descripción del argumento" \
--body "## Problema\n[expandido]\n\n## Tareas\n- [ ] tarea principal\n\n## Criterios de aceptación\n- [ ] qué debe ser verdad al resolver" \
--label "bug"
# Guarda el número #N
Paso 2 — Crear branch desde main
/tbd crea la branch fix/N-nombre desde main actualizado y mueve el Kanban a In Progress.
git checkout main && git pull origin main
git checkout -b fix/N-nombre
# Kanban → In Progress
Paso 3 — Seguimiento
Cuando el usuario avisa que terminó, /tbd revisa los commits (deben seguir la convención fix(scope): descripción), actualiza el checkbox del issue como completado, y avisa si la branch lleva más de 2 días abierta.
git log main..HEAD --oneline
# Verifica: fix(scope): descripción
gh issue comment N --body "Fix completado.\n\nCommits:\n- abc1234 fix(auth): ..."
Paso 4 — PR y cierre
/tbd crea el PR hacia main con Closes #N y mueve el Kanban a In Review. Al mergear (squash), mueve a Done y actualiza ONBOARDING.md.
gh pr create \
--base main \
--title "fix: descripción" \
--body "## Qué cambia\n...\n\n## Cómo testear\n...\n\nCloses #N"
# Kanban → In Review
# Al merge → Kanban → Done + ONBOARDING.md
Modo Full: features con SDD completo
El Modo Full se invoca sin argumentos: /tbd. Busca en Engram todos los changes SDD disponibles y los presenta antes de hacer nada:
Changes SDD en Engram:
newsletter-subscription proposal ✓ tasks ✓ apply-progress ✓ verify-report ✗ archive-report ✗
user-auth-refactor proposal ✓ tasks ✗ apply-progress ✗ verify-report ✗ archive-report ✗
fix-payment-gateway proposal ✓ tasks ✓ apply-progress ✓ verify-report ✓ archive-report ✓ (archivado)
¿Con cuál querés continuar?
Una vez elegido el change, /tbd detecta la fase actual comparando qué artefactos existen en Engram y ejecuta exactamente la acción GitHub correspondiente. No hace más ni menos.
Si un change solo tiene proposal (sin tasks), /tbd pregunta: ¿Full SDD (continúa con sdd-ff + apply + verify) o Light (issue directo + branch + PR)? Esto evita aplicar el peso completo de SDD a cambios simples.
Modo Full: qué hace /tbd en cada fase SDD
Cuando existe proposal → issue + branch + Kanban "Todo"
/tbd lee el proposal de Engram, crea el issue en GitHub con el título y descripción del proposal, crea la branch feat/N-nombre desde main, y posiciona la card en Kanban Todo. El número del issue (N) pasa a ser parte del change name: N-nombre.
gh issue create --title "[nombre del propose]" --body "..." --label "feature"
git checkout main && git pull origin main
git checkout -b feat/N-nombre
# Kanban → Todo
/tbd avisa en este momento: esta branch debe mergearse en 1-2 días. Si el scope es muy grande, conviene partir el change antes de empezar.
Cuando existen tasks → checkboxes + Kanban "In Progress" ← OBLIGATORIO antes de sdd-apply
Este es el paso más crítico y el más frecuentemente saltado. Después de /sdd-ff (que genera spec + design + tasks en Engram), hay que correr /tbd antes de /sdd-apply. /tbd actualiza el cuerpo del issue con la lista de tareas como checkboxes y mueve el Kanban a In Progress.
gh issue edit N --body "[cuerpo anterior + sección Tareas con checkboxes]"
gh issue comment N --body "Tareas definidas. Comenzando implementación."
# Kanban → In Progress
# DESPUÉS de este paso → recién entonces /sdd-apply
Si saltás esta llamada y vas directo a /sdd-apply, el issue nunca recibe los checkboxes y el Kanban nunca pasa a In Progress. El equipo implementa código sin reflejo visible en GitHub.
Cuando existe apply-progress → checkboxes actualizados + comment
/tbd lee el apply-progress de Engram, actualiza los checkboxes del issue (completadas vs pendientes), verifica la antigüedad de la branch, y agrega un comment narrativo con el progreso.
gh issue edit N --body "[checkboxes: ✅ completadas, [ ] pendientes]"
gh issue comment N --body "**Progreso actual**\n\nCompletadas:\n- [x] tarea 1 (commit: abc1234)\n\nPendientes:\n- [ ] tarea 2"
# Si la branch lleva más de 2 días:
# ⚠️ Esta branch lleva N días abierta. ¿El scope es demasiado grande?
Cuando existe verify-report → PR + Kanban "In Review"
/tbd agrega un comment al issue con el resultado de /sdd-verify (PASSED / PASSED WITH WARNINGS), crea el PR hacia main, y mueve el Kanban a In Review. Los option IDs del Status se resuelven dinámicamente via GraphQL — no hay hardcoding.
gh issue comment N --body "**Verificación completada**\nEstado: PASSED\nListo para PR."
gh pr create \
--base main \
--title "feat: título del issue" \
--body "## Qué cambia\n...\n\n## Commits\n[lista]\n\nCloses #N"
# Kanban → In Review (via GraphQL dinámico)
Cuando existe archive-report → Kanban "Done" + ONBOARDING
/tbd agrega el comment final al issue, mueve el Kanban a Done, y actualiza ONBOARDING.md con una entrada del change: número de issue, fecha, qué se implementó, decisiones arquitectónicas tomadas.
gh issue comment N --body "**Change completado y archivado.**\nTodas las tareas resueltas. PR mergeado a main."
# Kanban → Done
# ONBOARDING.md recibe:
# ### #N — título (feat/N-nombre) — fecha
# - qué se implementó
# - decisiones arquitectónicas
# - qué quedó fuera de scope
Resumen: qué mueve cada columna del Kanban
- Todo → /tbd detecta proposal (issue + branch recién creados)
- In Progress → /tbd detecta tasks (después de /sdd-ff, ANTES de /sdd-apply)
- In Review → /tbd detecta verify-report (PR creado, listo para merge)
- Done → /tbd detecta archive-report (change cerrado y documentado)
Cada transición es explícita: el Kanban no avanza automáticamente. Requiere una llamada a /tbd que corresponda con el estado de Engram. Esto fuerza trazabilidad — GitHub siempre refleja el estado real del trabajo.
Branch age warning: el guardián de TBD
En cada llamada al Modo Full con apply-progress, /tbd verifica cuántos días lleva abierta la branch. Si supera los 2 días, emite una advertencia:
No es un error — es una señal de diseño. Una rama que vive demasiado acumula divergencia con main y eventualmente genera conflictos costosos. La solución no es cerrar el aviso: es dividir el change en slices más pequeños que puedan mergearse independientemente.
Convención de nombres: trazabilidad garantizada
El nombre del change SDD se propaga a todos los artefactos. Si el propose se llama newsletter-subscription y el issue recibe el número 42:
- Issue title: "newsletter subscription"
- Branch: feat/42-newsletter-subscription
- Change name en Engram: 42-newsletter-subscription
- PR title: feat: newsletter subscription
- ONBOARDING entry: #42 — newsletter subscription
Dado un commit podés llegar al issue. Dado el issue podés llegar a la spec. Dada la spec podés entender cada decisión técnica. Esta cadena de trazabilidad es lo que hace que el sistema escale.
Ventajas de usar /tbd con SDD
- GitHub siempre refleja el estado real: el Kanban es un dashboard confiable, no una estimación
- Onboarding instantáneo: ONBOARDING.md + issues abiertos dan contexto completo en 30 minutos
- Merge conflicts mínimos: las ramas viven 1-2 días, la divergencia con main es mínima
- Trazabilidad commit → issue → spec: cualquier línea de código tiene justificación técnica
- Sin deuda de integración: no hay rama develop que acumule trabajo sin integrar
- Feedback rápido: features pequeñas mergeadas frecuentemente vs. features grandes que explotan al integrar
Conclusión
/tbd no es un wrapper de gh ni un helper de git. Es el sistema nervioso que conecta la planificación técnica (SDD + Engram) con la visibilidad del equipo (GitHub Issues + Kanban). Cada artefacto SDD tiene una acción GitHub. Cada acción GitHub tiene un lugar en el Kanban.
La disciplina de TBD — ramas cortas, merges frecuentes, trunk siempre deployable — combinada con la trazabilidad de SDD — spec antes de código, 1 tarea = 1 commit, verify antes del PR — produce un flujo que funciona igual con 1 desarrollador que con 20.
/tbd es un slash command de Claude Code: un archivo .md auto-contenido que se instala con bash install.sh y funciona desde cualquier proyecto con gh autenticado y Engram MCP activo. No hay infra extra — solo el protocolo.