Contrato GitHub Projects Unificado¶

GitHub Projects es el canal de coordinacion visible entre PM y Dev en el ecosistema Marketplace Inteliside. Los plugins crean y consumen milestones, issues y labels siguiendo convenciones identicas para que ATL Inteliside pueda implementar features sin distinguir su origen (SDD-Wizards, SDD-Legacy, RE-Wizard o SDD-Intake).

Si eres un humano: este documento describe como se organizan los milestones, labels e issues en GitHub. Consultalo cuando necesites saber que labels crear, que formato usa un milestone, o como filtrar features listas para implementar.

Si eres un agente de IA: usa las tablas de labels y convenciones de naming para crear artefactos en GitHub. Todas las operaciones DEBEN ser idempotentes (ejecutables multiples veces sin duplicar).

Labels¶

Tabla unificada de labels¶

Label	Color	Descripcion	Plugins que lo crean	Plugins que lo usan
`prd`	`#0075ca`	Product Requirements Document	SDD-Wizards, SDD-Legacy	SDD-Wizards, SDD-Legacy
`feature-spec`	`#1d76db`	Issue contiene Feature Spec	SDD-Wizards, SDD-Legacy, RE-Wizard	ATL (sdd-from-github)
`milestone-spec`	`#d876e3`	Milestone tracking	SDD-Wizards, SDD-Legacy	SDD-Wizards
`atl-ready`	`#0e8a16`	Feature lista para implementacion con ATL	SDD-Wizards, SDD-Legacy, RE-Wizard	ATL orchestrador, filtrado PM/Dev
`atl-task`	`#0075ca`	Task generada por ATL Inteliside	SDD-Wizards (proactivo), SDD-Legacy (proactivo), RE-Wizard (proactivo), ATL (sdd-tasks)	ATL (sdd-apply, sdd-verify, sdd-archive)
`area:backend`	`#e4e669`	Tarea de backend / servicios	SDD-Wizards (proactivo), SDD-Legacy (proactivo), RE-Wizard (proactivo), ATL	ATL
`area:frontend`	`#d93f0b`	Tarea de frontend / UI	SDD-Wizards (proactivo), SDD-Legacy (proactivo), RE-Wizard (proactivo), ATL	ATL
`area:db`	`#0e8a16`	Tarea de base de datos / migrations	SDD-Wizards (proactivo), SDD-Legacy (proactivo), RE-Wizard (proactivo), ATL	ATL
`area:test`	`#5319e7`	Tarea de testing	SDD-Wizards (proactivo), SDD-Legacy (proactivo), RE-Wizard (proactivo), ATL	ATL
`atl:pending`	`#ededed`	Task creada, pendiente de implementar	ATL (sdd-tasks)	ATL (sdd-apply)
`atl:in-progress`	`#fbca04`	Task en implementacion activa	ATL (sdd-apply)	ATL (sdd-verify)
`atl:done`	`#0e8a16`	Task implementada y verificada	ATL (sdd-apply, sdd-archive)	ATL (sdd-archive)
`atl-summary`	`#cfd3d7`	Resumen de la feature	ATL	ATL
`legacy-audit`	`#c5def5`	Audit report de SDD Legacy	SDD-Legacy	SDD-Legacy
`business-rules`	`#fbca04`	Reglas de negocio extraidas	SDD-Legacy	SDD-Legacy
`baseline-sdd`	`#d4c5f9`	Tarea de baseline para SDD readiness	SDD-Legacy	SDD-Legacy, ATL
`re-wizard`	`#7057ff`	Generado por RE-Wizard (trazabilidad)	RE-Wizard	Filtrado/trazabilidad
`design-ready`	—	Feature tiene Design Spec adjunto	UX Studio	ATL (sdd-design)

Notas sobre labels¶

Creacion idempotente: todos los labels se crean con 2>/dev/null || true para no fallar si ya existen.
Creacion proactiva de labels ATL: SDD-Wizards, SDD-Legacy y RE-Wizard crean los labels de ATL proactivamente para que esten listos cuando ATL inicie.
atl-ready como senal visible: el PM y dev pueden filtrar issues por atl-ready para saber que features estan listas para implementar.

Comando para crear todos los labels de una vez¶

# Labels de SDD-Wizards
gh label create "prd" --color "0075ca" --description "Product Requirements Document" 2>/dev/null || true
gh label create "feature-spec" --color "1d76db" --description "Feature Specification" 2>/dev/null || true
gh label create "milestone-spec" --color "d876e3" --description "Milestone tracking" 2>/dev/null || true
gh label create "atl-ready" --color "0e8a16" --description "Feature lista para ATL" 2>/dev/null || true

# Labels de SDD-Legacy
gh label create "legacy-audit" --color "c5def5" --description "Audit report de SDD Legacy" 2>/dev/null || true
gh label create "business-rules" --color "fbca04" --description "Reglas de negocio extraidas" 2>/dev/null || true
gh label create "baseline-sdd" --color "d4c5f9" --description "Tarea de baseline SDD" 2>/dev/null || true

# Labels de RE-Wizard
gh label create "re-wizard" --color "7057ff" --description "Generado por RE-Wizard" 2>/dev/null || true

# Labels de ATL Inteliside
gh label create "atl-task" --color "0075ca" --description "Task generada por ATL Inteliside" 2>/dev/null || true
gh label create "area:backend" --color "e4e669" --description "Backend/services" 2>/dev/null || true
gh label create "area:frontend" --color "d93f0b" --description "Frontend/UI" 2>/dev/null || true
gh label create "area:db" --color "0e8a16" --description "Database/migrations" 2>/dev/null || true
gh label create "area:test" --color "5319e7" --description "Testing" 2>/dev/null || true
gh label create "atl:pending" --color "ededed" --description "Not yet implemented" 2>/dev/null || true
gh label create "atl:in-progress" --color "fbca04" --description "In active development" 2>/dev/null || true
gh label create "atl:done" --color "0e8a16" --description "Implemented & verified" 2>/dev/null || true
gh label create "atl-summary" --color "cfd3d7" --description "Resumen de la feature" 2>/dev/null || true

Campos Custom de Projects¶

Los plugins no crean campos custom en GitHub Projects. La coordinacion se realiza exclusivamente via milestones, labels y el body de los issues. El estado de las features se rastrea por combinacion de labels:

Estado logico	Labels presentes	Significado
Feature pendiente de spec	`feature-spec`	Feature Spec existe pero no esta lista
Feature lista para ATL	`feature-spec` + `atl-ready`	PM completo la especificacion
Feature con diseno	`feature-spec` + `atl-ready` + `design-ready`	Tiene Design Spec adjunto
Task pendiente	`atl-task` + `atl:pending` + `area:*`	Task creada por ATL, sin iniciar
Task en progreso	`atl-task` + `atl:in-progress` + `area:*`	Dev implementando
Task completada	`atl-task` + `atl:done` + `area:*`	Implementada y verificada

Milestones¶

Convenciones de naming¶

Tipo de milestone	Formato	Creado por	Consumido por
Feature	`feat-{kebab-case}`	SDD-Wizards, SDD-Legacy, RE-Wizard	ATL Inteliside
Business Rules	`baseline-business-rules`	SDD-Legacy	SDD-Legacy
Baseline SDD	`baseline-sdd`	SDD-Legacy	ATL Inteliside

Quien crea milestones¶

Plugin	Cuando	Formato	Descripcion del milestone
SDD-Wizards (feature-spec-wizard Phase 8)	Al completar un Feature Spec	`feat-{nombre}`	Contenido completo del Feature Spec en la descripcion
SDD-Legacy (legacy-spec-extractor)	Al extraer una feature del codigo legacy	`feat-{nombre}`	Feature Spec retroactiva, formato identico a SDD-Wizards
SDD-Legacy (legacy-rules-extractor)	Al extraer reglas de negocio	`baseline-business-rules`	Reglas por dominio con test cases G/W/T
SDD-Legacy (legacy-baseline-wizard)	Al generar plan de deuda tecnica	`baseline-sdd`	Tasks priorizadas para SDD-readiness
RE-Wizard (Phase 4, si usuario confirma)	Al completar sintesis de Feature Specs	`feat-{nombre}`	Feature Specs generados por ingenieria inversa, creados por wave

Quien consume milestones¶

Plugin	Como consume	Que busca
ATL Inteliside (sdd-from-github)	Lee milestone por titulo	`feat-{nombre}` — extrae Feature Spec de la descripcion
ATL Inteliside (sdd-tasks)	Crea issues bajo el milestone	Numero del milestone para vincular issues de tasks
ATL Inteliside (sdd-archive)	Cierra el milestone	Marca la feature como Done para el PM

Creacion idempotente de milestones¶

# Verificar si existe antes de crear
EXISTING=$(gh api repos/{owner}/{repo}/milestones \
  --jq '.[] | select(.title == "feat-{nombre}") | .number' 2>/dev/null || echo "")

if [ -z "$EXISTING" ]; then
  gh api repos/{owner}/{repo}/milestones \
    -f title="feat-{nombre}" \
    -f description="{contenido del Feature Spec}" \
    -f state="open"
fi

Flujo de Issues¶

Path A: Proyecto nuevo (greenfield)¶

SDD-Wizards                         GitHub                          ATL Inteliside
───────────                         ──────                          ──────────────
prd-wizard Phase 9
  ├─ Crea repo (si no existe)
  ├─ Crea GitHub Project
  ├─ Crea issue "PRD: {Nombre}" [prd]
  └─ Crea labels (todos)

feature-spec-wizard Phase 8
  ├─ Crea milestone feat-{nombre}
  ├─ Crea issue "Feature Spec: {Nombre}" [feature-spec, atl-ready]
  └─ Agrega al Project
                                                                    sdd-from-github
                                                                      └─ Lee milestone feat-{nombre}
                                                                    sdd-tasks
                                                                      └─ Crea issues "task: {area} {desc}"
                                                                         [atl-task, area:*, atl:pending]
                                                                         bajo milestone feat-{nombre}
                                                                    sdd-apply
                                                                      └─ atl:pending → atl:in-progress → atl:done
                                                                    sdd-archive
                                                                      ├─ Cierra todos los issues
                                                                      └─ Cierra milestone (state=closed)

Path B: Proyecto legacy¶

SDD-Legacy                          GitHub                          ATL Inteliside
──────────                          ──────                          ──────────────
legacy-audit-wizard
  ├─ Detecta repo existente
  ├─ Crea/detecta GitHub Project
  ├─ Crea issue "Audit Report: {Nombre}" [legacy-audit]
  └─ Crea labels (todos)

legacy-spec-extractor (por feature)
  ├─ Crea milestone feat-{nombre}
  └─ Crea issue "Feature Spec: {Nombre}" [feature-spec]

legacy-handoff feat-{nombre}
  └─ Agrega label [atl-ready] al issue
                                                                    (identico a Path A desde aqui)

legacy-rules-extractor
  ├─ Crea milestone baseline-business-rules
  └─ Crea issues "Business Rules: {Dominio}" [business-rules]

legacy-baseline-wizard
  ├─ Crea milestone baseline-sdd
  └─ Crea issues "task: {area} {desc}" [atl-task, area:*, atl:pending, baseline-sdd]
                                                                    ATL puede ejecutar baseline-sdd
                                                                    como si fuera una feature

Path C: Ingenieria inversa¶

RE-Wizard                           GitHub                          ATL Inteliside
─────────                           ──────                          ──────────────
Phase 4 (solo si usuario confirma)
  ├─ Crea labels (feature-spec, atl-ready, re-wizard + ATL labels)
  ├─ Crea milestones por wave:
  │    Wave 1: feat-user-auth, feat-product-catalog
  │    Wave 2: feat-shopping-cart, feat-checkout
  │    Wave 3: ...
  ├─ Crea issues "Feature Spec: {Nombre}" [feature-spec, atl-ready, re-wizard]
  └─ Cada issue bajo su milestone
                                                                    (identico a Path A desde aqui)

Path D: Con diseno UI/UX¶

UX Studio                           GitHub
─────────                           ──────
Design Handoff (Phase 8)
  ├─ Busca milestone feat-{nombre}
  ├─ Busca issue con label feature-spec
  ├─ Agrega seccion "## Design References" al body del issue
  └─ Agrega label [design-ready]

Filtros utiles para PM y Dev¶

# Ver features listas para ATL
gh issue list --label "feature-spec,atl-ready" --json number,title,milestone

# Ver features con diseno
gh issue list --label "feature-spec,atl-ready,design-ready" --json number,title

# Ver tasks pendientes de una feature
gh issue list --milestone "feat-{nombre}" --label "atl-task,atl:pending"

# Ver tasks en progreso
gh issue list --label "atl:in-progress"

# Ver features generadas por RE-Wizard
gh issue list --label "re-wizard,feature-spec"

Convenciones de Branches y Commits¶

Branches¶

Tipo	Formato	Ejemplo	Creado por
Feature	`feat/{nombre-kebab}`	`feat/user-auth`	ATL (sdd-apply)
Fix	`fix/{nombre-kebab}`	`fix/login-validation`	ATL (sdd-apply)
Legacy setup	`sdd/setup`	`sdd/setup`	SDD-Legacy (audit, conventions)

Commits¶

Formato: conventional commits.

Tipo	Uso	Ejemplo
`feat:`	Nueva feature o funcionalidad	`feat: user authentication`
`fix:`	Correccion de bug	`fix: login validation error`
`chore:`	Mantenimiento, sin cambio funcional	`chore: sync engram memories`
`docs:`	Documentacion	`docs: update CLAUDE.md`
`test:`	Tests	`test: add auth unit tests`
`refactor:`	Refactoring sin cambio funcional	`refactor: extract auth middleware`

Pull Requests¶

Formato	Ejemplo	Creado por
`feat: {nombre legible}`	`feat: user authentication`	ATL (sdd-archive)

Verificacion de branches y PRs existentes¶

ATL verifica antes de crear:

# Verificar si el branch ya existe
git ls-remote --heads origin feat/{nombre} | wc -l

# Verificar si ya hay un PR abierto
gh pr list --head "feat/{nombre}" --json number,title,state

Si el branch ya existe, hace checkout y continua. Si el PR ya existe, lo reutiliza.

Naming Conventions — Tabla Consolidada¶

Artefacto	Formato	Ejemplo	Plugins
Repositorio	`{owner}/{repo}`	`Intelliaa/mi-producto`	SDD-Wizards (crea), SDD-Legacy (detecta)
GitHub Project	Titulo del producto	`Mi Producto`	SDD-Wizards (crea), SDD-Legacy (crea/detecta)
PRD Issue	`PRD: {Nombre}`	`PRD: Mi Producto`	SDD-Wizards, SDD-Legacy
Audit Issue	`Audit Report: {Nombre}`	`Audit Report: Mi Proyecto`	SDD-Legacy
Feature Spec Issue	`Feature Spec: {Nombre}`	`Feature Spec: User Auth`	SDD-Wizards, SDD-Legacy, RE-Wizard
Business Rules Issue	`Business Rules: {Dominio}`	`Business Rules: Pagos`	SDD-Legacy
Task Issue	`task: {area} {descripcion}`	`task: db crear tabla users`	ATL (sdd-tasks), SDD-Legacy (baseline)
Milestone (feature)	`feat-{kebab-case}`	`feat-user-auth`	SDD-Wizards, SDD-Legacy, RE-Wizard
Milestone (rules)	`baseline-business-rules`	—	SDD-Legacy
Milestone (baseline)	`baseline-sdd`	—	SDD-Legacy
Branch (feature)	`feat/{kebab-case}`	`feat/user-auth`	ATL
PR	`feat: {nombre legible}`	`feat: user authentication`	ATL
Feature Spec file	`feat-{kebab-case}.md`	`feat-user-auth.md`	SDD-Wizards, RE-Wizard
PRD file	`PRD-{Nombre}.md`	`PRD-Mi-Producto.md`	SDD-Wizards

IDs de Artefactos¶

ID	Formato	Quien lo genera	Donde aparece
User Stories	`US-{N}`	SDD-Wizards, SDD-Legacy, RE-Wizard	Feature Spec
Acceptance Criteria	`AC-{NN}` (flat global por feature)	SDD-Wizards, SDD-Legacy, RE-Wizard	Feature Spec
Business Rules (flat)	`BR-{N}`	SDD-Wizards, RE-Wizard	Feature Spec (pre-ATL)
Business Rules (domain)	`BR-{domain}-{NNN}`	SDD-Legacy, ATL (sdd-spec)	Business Rules docs, Technical Spec
Tech Debt	`TD-{NNN}`	SDD-Legacy	Audit Report
Baseline Task	`BL-{NNN}`	SDD-Legacy	Baseline Plan

Nota: ATL normaliza automaticamente los BRs de formato flat (BR-01) al formato domain-prefixed (BR-auth-001) cuando genera la spec tecnica. Los ACs usan numeracion continua global dentro de cada feature (no reinician por user story).

Idempotencia¶

Todas las operaciones de GitHub DEBEN ser idempotentes. Patrones:

Operacion	Patron idempotente
Labels	`gh label create ... 2>/dev/null \\|\\| true`
Milestones	Verificar con `gh api repos/.../milestones --jq` antes de crear
Issues	Verificar si existe issue con mismo titulo/labels antes de crear
Project items	`gh project item-add` es naturalmente idempotente
Label assignment	`gh issue edit --add-label` es naturalmente idempotente

Prerequisitos de GitHub CLI¶

Antes de cualquier operacion, los plugins verifican (via hooks prereq-check.sh):

gh esta instalado (command -v gh)
gh esta autenticado (gh auth status)
El token tiene scope repo (gh auth status 2>&1 | grep "Token scopes")
Connectivity test (gh api user --jq '.login')
El repo existe (gh repo view {owner}/{repo} --json name)
Los labels necesarios existen (crearlos si no)

Si cualquier paso falla, el plugin bloquea con instrucciones claras.

Contrato GitHub Projects Unificado — Marketplace Inteliside v1.1.0