El problema que resuelve

Cuando trabajás con SDD (Spec-Driven Development), generás artefactos valiosos en Engram: proposals, specs, designs, tasks, apply-progress. Pero GitHub no sabe nada de eso. Los issues quedan sin actualizar, el Kanban no refleja el estado real, los commits flotan sin contexto.

/github-project resuelve exactamente eso. No ejecuta SDD, no genera código. Lee el estado que SDD dejó en Engram y lo refleja en GitHub de forma automatizada. Es el puente entre el trabajo técnico interno y la visibilidad del equipo.

¿Qué es /github-project?

Es un sincronizador unidireccional: Engram → GitHub. Lee los artefactos SDD por fase y ejecuta las acciones correspondientes. Cada artefacto tiene una acción GitHub asociada:

  • proposal → crea issue + branch + Kanban "Todo"
  • tasks → actualiza issue con checkboxes + mueve a "In Progress"
  • apply-progress → marca checkboxes completados + comment con commits
  • verify-report → crea PR + mueve a "In Review"
  • archive-report → cierra issue + "Done" + actualiza ONBOARDING.md

Dos modos de uso

Modo Light: cambios rápidos sin SDD

Cuando tenés un bug o un cambio pequeño que no justifica el flujo SDD completo, invocás el comando con una descripción: /github-project "fix login bug". Crea el issue, la branch y gestiona el PR sin pasar por specs ni design.

  • Issue creado con label "bug"
  • Branch fix/N-nombre desde develop
  • Kanban en "In Progress" automáticamente
  • PR con cierre automático del issue al mergear

Modo Full: feature con SDD completo

Invocás /github-project sin argumentos. Busca en Engram todos los changes SDD activos, muestra su estado (qué artefactos existen para cada uno) y sincroniza el que elijas. Cada invocación avanza el estado en GitHub según el artefacto más reciente disponible.

Bootstrap automático en proyectos nuevos

La primera ejecución en un proyecto nuevo hace tres cosas sin que tengas que configurar nada manualmente:

  • Branch develop: la crea si no existe y la sube al remoto
  • ONBOARDING.md: genera el archivo con stack detectado, estructura de directorios, comandos frecuentes y variables de entorno
  • GitHub Project (Kanban): crea el tablero con columnas Todo → In Progress → In Review → Done

El ONBOARDING.md no es un documento estático que se escribe una vez y queda desactualizado. Se actualiza automáticamente al cerrar cada change, sumando las decisiones arquitectónicas y qué quedó fuera de scope.

Relación con SDD

SDD se encarga del trabajo técnico: explorar el problema, escribir specs y diseño, implementar con trazabilidad por tarea, verificar contra criterios de aceptación. /github-project se encarga de la visibilidad: crear issues desde proposals, mover el Kanban en cada transición, actualizar checkboxes, crear PRs.

Son complementarios y tienen separación de responsabilidades clara. Podés usar SDD sin GitHub (equipos pequeños o proyectos personales) y podés usar Light mode sin SDD (bugs puntuales). Pero juntos forman un flujo donde ningún paso queda sin rastro.

Relación con Issues, Projects, Branches y Commits

Issues

Los issues son el rastro humano del trabajo. /github-project los crea desde el proposal con el problema, la solución propuesta y los criterios de aceptación. Los actualiza con checkboxes cuando las tasks SDD están listas, y agrega comments narrativos en cada transición: progreso, verificación, cierre.

GitHub Projects (Kanban)

El Kanban refleja la fase del artefacto SDD más avanzado disponible en Engram. No tenés que mover las tarjetas a mano: el comando lee el estado y determina la posición correcta. La columna donde vive la tarjeta es exactamente el estado del change.

Naming convention de branches

El nombre del branch viene del número de issue más el nombre del propose SDD. Esto garantiza trazabilidad desde cualquier punto:

text 
                propose name: "newsletter-subscription"
→ Issue #42 creado
→ Branch: feat/42-newsletter-subscription
→ Change SDD: 42-newsletter-subscription

Podés ir de cualquier commit al issue, y del issue al artefacto SDD en Engram. El contexto completo está siempre disponible.

Commits

La convención es 1 tarea SDD = 1 commit con formato conventional commits:

bash 
                feat(scope): descripción de la tarea
fix(scope): descripción del fix
refactor(scope): cambio estructural sin cambio de comportamiento

El apply-progress en Engram mapea cada tarea a su commit. Cuando /github-project lee ese artefacto, puede mostrar en el comment del issue exactamente qué commits completan qué tareas, con sus hashes.

Pull Requests

Se crean automáticamente cuando existe el verify-report. El PR incluye resumen del cambio, pasos para testear y la lista de commits con sus tareas correspondientes. Configurados para squash merge a develop, lo que mantiene el historial de main limpio.

Flujo de trabajo completo: ejemplo real

Querés agregar un sistema de newsletter a tu app. Así se ve el flujo completo combinando SDD y /github-project:

1. Exploración y propuesta

bash 
                /sdd-new "newsletter subscription"

SDD explora el codebase y crea el proposal en Engram con el problema y el enfoque técnico propuesto.

2. Sincronización inicial con GitHub

bash 
                /github-project

Lee el proposal → crea issue #42 "newsletter subscription" → crea feat/42-newsletter-subscription → Kanban "Todo".

3. Fast-forward de planning

bash 
                /sdd-ff

Genera spec, design y tasks en Engram en una sola invocación. Las tasks son la lista de trabajo atómica que sdd-apply va a ejecutar commit por commit.

4. Issue actualizado con checkboxes

bash 
                /github-project

Lee las tasks → actualiza el issue con checkboxes por tarea → comment "Comenzando implementación" → Kanban "In Progress".

5. Implementación

bash 
                /sdd-apply

Implementa tarea por tarea. Cada tarea genera un commit conventional. El apply-progress se actualiza en Engram registrando qué tareas están completas y qué commits las cubren.

6. Progreso visible en GitHub

bash 
                /github-project

Lee el apply-progress → marca checkboxes completados → comment con lista de commits y tareas pendientes.

7. Verificación

bash 
                /sdd-verify

Valida la implementación contra los specs. Guarda el verify-report en Engram con veredicto PASSED / PASSED WITH WARNINGS.

8. PR y revisión de código

bash 
                /github-project

Lee el verify-report → comment "Verificación: PASSED" → crea PR con todos los commits → Kanban "In Review". El equipo puede hacer code review con el contexto completo.

9. Cierre del change

bash 
                /sdd-archive
/github-project

sdd-archive cierra el change en Engram. /github-project lee el archive-report → cierra el issue → Kanban "Done" → actualiza ONBOARDING.md con las decisiones arquitectónicas.

¿Cuándo usar Light vs Full?

  • Bug reportado por un usuario → Light
  • Cambio en un solo archivo → Light
  • Feature nueva con múltiples archivos → Full
  • Cambio que requiere diseño antes de codear → Full
  • Refactor con impacto en varios módulos → Full

La regla práctica: si necesitás pensar el diseño antes de escribir código, usá Full. Si ya sabés exactamente qué cambiar, usá Light.

Ventajas clave

  • Cero duplicación: el proposal se convierte directamente en el issue. No escribís el mismo contexto en dos lugares.
  • Trazabilidad completa: commit → tarea SDD → issue → artefacto en Engram. Podés reconstruir el razonamiento de cualquier cambio.
  • ONBOARDING siempre actualizado: se actualiza solo al cerrar cada change, nunca queda obsoleto.
  • GitHub como vista externa: el equipo ve issues y Kanban sin necesitar conocer Engram ni SDD internamente.
  • Bootstrap en un comando: primer run en proyecto nuevo = develop branch + Kanban + ONBOARDING.md en automático.