/github-project y /tbd son dos slash commands de Claude Code que desarrollé para resolver un problema concreto de coordinación de equipos: mantener sincronizados el trabajo técnico (planificado con SDD y guardado en Engram) con el estado visible en GitHub (issues, ramas, Kanban y PRs). Ambos logran lo mismo — trazabilidad total entre código y contexto — pero están diseñados para estrategias de branching distintas.
No son comandos de propósito general. Son herramientas opinionadas, construidas sobre la metodología SDD (Spec-Driven Development), para equipos que quieren iterar de forma ágil sin perder contexto ni visibilidad. Este artículo los compara directamente: casos de uso, flujo de trabajo resumido, y cuándo elegir cada uno.
/github-project: Gitflow con SDD
/github-project implementa el protocolo SDD → GitHub sobre una estrategia Gitflow clásica. Hay dos ramas de larga duración — main (producción) y develop (integración) — y las features viven en ramas que mergean a develop antes de llegar a main.
Casos de uso ideales
- Librerías y SDKs con versionado semántico — el ciclo develop → main por release encaja naturalmente
- Apps móviles con revisión de tienda — no podés deployar en cualquier momento, necesitás una rama de integración
- Proyectos con QA formal — develop acumula features hasta que el equipo de QA aprueba el release
- Equipos distribuidos en múltiples zonas horarias — develop como buffer reduce la presión de integración continua
Flujo de trabajo resumido
- Modo Light (/github-project "descripción"): issue → branch fix/N desde develop → fix → PR a develop → Done
- Modo Full (/github-project): lee Engram → issue + branch feat/N desde develop + Kanban Todo
- Después de /sdd-ff → /github-project actualiza checkboxes + Kanban In Progress
- Después de /sdd-verify → /github-project crea PR a develop + Kanban In Review
- Después de /sdd-archive → /github-project cierra issue + Kanban Done + ONBOARDING.md
- develop → PR → main en cada release
feat/N-nombre → develop → main
Bootstrap: crea develop si no existe
PR base: develop (no main)
Podés leer el detalle completo del comando en el blog: https://www.miguel-anay.nom.pe/blog/github-project-sincronizador-sdd/
/tbd: Trunk-Based Development con SDD
/tbd implementa el mismo protocolo SDD → GitHub pero sobre Trunk-Based Development: una sola rama permanente (main), sin develop, y ramas de feature que deben mergearse en 1 a 2 días máximo. Si una rama vive más tiempo, /tbd avisa — es una señal de que el scope es demasiado grande.
Casos de uso ideales
- SaaS y apps web con CI/CD — cada merge a main puede ir a producción automáticamente
- Startups en iteración rápida — TBD fuerza a dividir el trabajo en incrementos pequeños, acelerando el feedback
- Equipos donde los merge conflicts son recurrentes — TBD los elimina estructuralmente al mantener ramas cortas
- Proyectos con feature flags — podés deployar código sin activarlo para usuarios todavía
Flujo de trabajo resumido
- Modo Light (/tbd "descripción"): issue → branch fix/N desde main → fix → PR a main → Done
- Modo Full (/tbd): lee Engram → issue + branch feat/N desde main + Kanban Todo
- Después de /sdd-ff → /tbd actualiza checkboxes + Kanban In Progress
- Después de /sdd-verify → /tbd crea PR a main + Kanban In Review
- Después de /sdd-archive → /tbd cierra issue + Kanban Done + ONBOARDING.md
- No hay rama develop — main siempre deployable
feat/N-nombre → main (directo)
Bootstrap: solo verifica main
PR base: main
Branch age warning: 2 días máximo
Podés leer el detalle completo del comando en el blog: https://www.miguel-anay.nom.pe/blog/guia-completa-tbd-sdd-github-trunk-based-development/
Comparativa directa
- Ramas permanentes: /github-project tiene main + develop. /tbd solo tiene main.
- PR base: /github-project → develop. /tbd → main.
- Vida de una feature branch: /github-project puede durar semanas. /tbd máximo 2 días.
- Branch age warning: solo /tbd lo tiene — avisa si la rama supera los 2 días.
- Bootstrap: /github-project crea develop. /tbd no — main es la única rama permanente.
- Kanban Status IDs: /github-project puede tener IDs hardcodeados. /tbd los resuelve dinámicamente via GraphQL.
- Protocolo SDD: idéntico en ambos — mismas fases, mismos artefactos, mismo Engram.
¿Cuál usar?
La decisión es organizacional, no técnica. Antes de elegir, respondé estas preguntas:
- ¿Tu equipo puede deployar a producción en cualquier momento? → /tbd
- ¿Tenés ciclos de release con fechas definidas? → /github-project
- ¿Las features tardan más de una semana? → /github-project (o revisá el scope)
- ¿Los merge conflicts son un problema frecuente? → /tbd
- ¿Es una librería con versionado semántico? → /github-project
- ¿Es un SaaS que itera semanalmente? → /tbd
Podés usar ambos en el mismo equipo para proyectos distintos. La instalación es independiente por proyecto — bash install.sh copia los comandos a ~/.claude/commands/ y funcionan desde cualquier repo con gh autenticado y Engram MCP activo.
Por qué los construí
Ambos comandos nacieron de un problema que vi repetirse en distintos equipos: el trabajo técnico y el estado visible en GitHub siempre estaban desincronizados. Los developers implementaban en sus ramas pero los issues no se actualizaban, el Kanban no avanzaba, y los PRs llegaban sin contexto de por qué se tomó cada decisión.
SDD resolvía la parte de planificación y contexto técnico (spec, design, tasks en Engram). Pero la sincronización con GitHub era manual y se salteaba. /github-project y /tbd automatizan esa sincronización: dado el estado de Engram, saben exactamente qué acción ejecutar en GitHub.
El resultado es un flujo donde la trazabilidad es estructural: dado un commit llegás al issue, dado el issue llegás a la spec, dada la spec entendés cada decisión técnica. Eso es lo que hace que un equipo escale sin perder contexto.
Profundizá en cada comando
Si querés entender en detalle cómo funciona cada comando — bootstrap, paso a paso del Modo Full, cada fase SDD explicada, ejemplos de código real — tenés los artículos completos en el blog:
- /github-project completo → https://www.miguel-anay.nom.pe/blog/github-project-sincronizador-sdd/
- /tbd completo con todos los pasos → https://www.miguel-anay.nom.pe/blog/guia-completa-tbd-sdd-github-trunk-based-development/
Código fuente de los comandos
El código fuente completo de /github-project y /tbd está disponible en este gist — dos archivos .md listos para instalar con bash install.sh:
https://gist.github.com/miguel-anay/f314e53df2bd128519f29946b9552b83
Ambos comandos están disponibles en el repositorio claude-commands como archivos .md auto-contenidos. Se instalan con bash install.sh y no tienen dependencias externas más allá de gh autenticado y Engram MCP activo.