SDD Legacy¶

Plugin de onboarding de proyectos legacy al flujo Spec-Driven Development. Escanea un codebase existente, extrae features y reglas de negocio enterradas en el codigo, y genera los artefactos (Feature Specs, milestones, labels) que ATL Inteliside necesita para operar como si fuera un proyecto greenfield. Dirigido al PM que prepara el proyecto y al dev que implementa en paralelo.

Prerequisitos¶

Claude Code instalado
GitHub CLI autenticado con scope repo (gh auth login)
Engram conectado como plugin
Repositorio clonado localmente — SDD Legacy trabaja sobre codigo local
Dependencias instaladas (npm install o equivalente) para auditoria completa

# Plugin individual
claude --plugin-dir ./plugins/sdd-legacy

# Stack completo PM + Dev
claude --plugin-dir ./plugins/sdd-legacy --plugin-dir ./plugins/atl-inteliside

Skills¶

SDD Legacy tiene 7 skills que se ejecutan en un orden canonico estricto. Cada skill produce artefactos con schema JSON fijo en Engram que alimentan al siguiente, garantizando determinismo. Los skills pesados (audit, spec-extractor, rules-extractor) usan modelo opus; los mas ligeros (conventions, handoff, baseline, onboard) usan sonnet. Todos operan en context: fork.

Skill	Descripcion	Invocacion	Tools permitidos
`legacy-audit-wizard`	Escanea stack, mide health score por area, detecta deuda tecnica y dependencias vulnerables. Primer paso obligatorio.	`/sdd-legacy:legacy-audit-wizard`	Read, Glob, Grep, Bash, Write
`legacy-conventions-wizard`	Analiza patrones existentes en el codigo y formaliza convenciones. Genera `.claude/rules/`.	`/sdd-legacy:legacy-conventions-wizard`	Read, Glob, Grep, Bash, Write
`legacy-spec-extractor`	Reverse-engineer de features desde el codigo. Genera Feature Specs en formato identico a SDD-Wizards. Modo bulk o per-feature.	`/sdd-legacy:legacy-spec-extractor [feature-name]`	Read, Glob, Grep, Bash, Write
`legacy-rules-extractor`	Extrae reglas de negocio enterradas en el codigo y genera test cases Given/When/Then. Modo bulk o per-domain.	`/sdd-legacy:legacy-rules-extractor [domain]`	Read, Glob, Grep, Bash, Write
`legacy-handoff`	Valida artefactos de una feature, hace commit/push, agrega label `atl-ready` en GitHub. Gate per-feature.	`/sdd-legacy:legacy-handoff [feature-name]`	Read, Glob, Grep, Bash
`legacy-baseline-wizard`	Genera plan de accion priorizado para SDD-readiness. Compila deuda tecnica en milestone de GitHub.	`/sdd-legacy:legacy-baseline-wizard`	Read, Glob, Grep, Bash
`legacy-onboard-wizard`	Setup final: CLAUDE.md configurado, labels faltantes, Engram inicializado. Proyecto queda SDD-ready.	`/sdd-legacy:legacy-onboard-wizard`	Read, Glob, Grep, Bash, Write

Flujo de trabajo¶

El pipeline sigue 3 fases con un orden canonico: audit -> conventions -> [spec -> rules -> handoff] x N -> baseline -> onboard. El paralelismo PM/Dev es consecuencia natural del handoff per-feature.

Fase 1 — Setup (una sola vez)¶

legacy-audit-wizard: Escanea el proyecto, genera Audit Report con health score, detecta stack y deuda tecnica. Bootstrap de ATL en CLAUDE.md. Crea rama sdd/setup y hace push.
legacy-conventions-wizard: Detecta y formaliza convenciones del proyecto en .claude/rules/*.md. Commit en rama sdd/setup.
Notificar al dev: "Rama sdd/setup lista. Haz pull."

Fase 2 — Per-feature (repetir N veces)¶

legacy-spec-extractor: Analiza codigo y genera Feature Spec + milestone en GitHub. Puede ejecutarse en modo bulk (todas las features) o per-feature (una a la vez).
legacy-rules-extractor: Extrae reglas de negocio del dominio y genera test cases G/W/T. Puede ejecutarse en modo bulk o per-domain.
legacy-handoff: Valida artefactos, hace commit/push, agrega label atl-ready. El dev puede empezar a implementar con ATL desde el primer handoff.

El dev ejecuta en paralelo: /atl-inteliside:orchestrador feat-[feature]

Fase 3 — Cierre (una sola vez)¶

legacy-baseline-wizard: Plan de deuda tecnica priorizado, milestone baseline-sdd con issues ATL-compatible.
legacy-onboard-wizard: Validacion final, CLAUDE.md completo, Engram inicializado con project/config.

Despues del onboarding, el proyecto esta listo para: - Features nuevas: /sdd-wizards:feature-spec-wizard - Implementacion: /atl-inteliside:orchestrador feat-[nombre] - Baseline: /atl-inteliside:orchestrador baseline-sdd

Contratos de datos¶

Engram¶

SDD Legacy usa el mismo proyecto Engram que ATL ({nombre-proyecto}-dev). Cada wizard produce un artifact con schema JSON fijo que el siguiente consume. Esto garantiza determinismo: ATL recibe datos pre-digeridos.

Los artifacts siguen una cadena de dependencias clara donde cada skill tiene writers y readers definidos:

topic_key	Writer	Readers
`legacy/audit`	legacy-audit-wizard	spec-extractor, baseline, conventions, onboard
`legacy/stack`	legacy-audit-wizard	spec-extractor, rules-extractor, conventions, onboard
`legacy/health-score`	legacy-audit-wizard	baseline, onboard
`legacy/features/{feature-name}`	legacy-spec-extractor	rules-extractor, baseline
`legacy/features-index`	legacy-spec-extractor	rules-extractor, baseline, onboard
`legacy/prd`	legacy-spec-extractor	baseline, onboard
`legacy/rules/{domain}`	legacy-rules-extractor	baseline, onboard
`legacy/test-cases/{domain}`	legacy-rules-extractor	baseline, onboard
`legacy/rules-index`	legacy-rules-extractor	baseline, onboard
`legacy/preexisting-issues`	legacy-spec-extractor	baseline
`legacy/baseline`	legacy-baseline-wizard	onboard
`legacy/conventions`	legacy-conventions-wizard	onboard
`legacy/onboard-status`	legacy-onboard-wizard	ATL orchestrador
`legacy/handoff/{feature}`	legacy-handoff	ATL sdd-from-github (opcional)
`project/github-context`	legacy-audit-wizard	todos (compatible con ATL)
`project/config`	legacy-onboard-wizard	todos (compatible con ATL sdd-init)

Contrato completo con schemas JSON en plugins/sdd-legacy/docs/engram-legacy-contract.md.

GitHub¶

SDD Legacy trabaja sobre un repositorio existente — no crea repos nuevos. Mantiene paridad total con SDD-Wizards y ATL Inteliside en labels, milestones e issues.

El audit wizard detecta el repositorio desde git config o pregunta al usuario, y crea/detecta un GitHub Project vinculado. Los labels, milestones e issues son identicos a los de SDD-Wizards para que ATL no necesite distinguir el origen.

Recursos creados: - Labels: feature-spec, atl-ready, atl-task, area:*, atl:* (idempotentes) - Milestones: feat-{kebab-case} por feature extraida - Issues: Feature Specs como body del issue, con labels feature-spec + atl-ready - GitHub Project: Detectado o creado, con items vinculados

Contrato completo en plugins/sdd-legacy/docs/github-legacy-contract.md.

Hooks¶

SDD Legacy incluye hooks de validacion que se ejecutan automaticamente durante el uso del plugin. Hay dos hooks que aseguran calidad: uno verifica prerequisitos despues de comandos Bash, y otro valida el schema de los artefactos escritos.

Evento	Matcher	Handler	Tipo	Timeout	Async
PostToolUse	`Bash`	`prereq-check.sh`	command	10s	si
PostToolUse	`Write`	`output-schema-validator.sh`	command	15s	no

Los scripts viven en plugins/sdd-legacy/hooks/.

Configuracion para proyectos¶

Copiar plugins/sdd-legacy/examples/CLAUDE.md al proyecto legacy antes de iniciar. El template incluye:

Datos del proyecto (nombre, repo, stack, contacto tecnico)
Flujo canonico con el orden exacto de wizards
Prerequisitos del sistema (GitHub CLI, dependencias, permisos de Bash)
Reglas de sesion (una conversacion por wizard, orden estricto, per-feature recomendado)
Contexto del proyecto a llenar (que hace, usuarios, modulos criticos, restricciones)

Reglas clave de sesion: 1. Una conversacion por wizard — evita overflow de contexto 2. Orden canonico obligatorio: audit -> conventions -> [spec -> rules -> handoff] x N -> baseline -> onboard 3. Per-feature es el modo recomendado — spec-extractor y rules-extractor aceptan argumento 4. Handoff hace commit y push — sincroniza artefactos con el repo 5. spec-extractor debe preguntar por issues preexistentes antes de analizar codigo

Integracion con Doc-Gen¶

Despues de completar el onboarding (legacy-onboard-wizard), se recomienda correr doc-gen para mantener la documentacion del proyecto actualizada.

Cuando	Comando
Despues de completar el onboarding	`/doc-gen:doc-proyecto`
Verificacion periodica	`/doc-gen:doc-sync`

Limitaciones conocidas¶

Una conversacion por wizard: Cada wizard debe ejecutarse en una conversacion separada para evitar overflow de contexto. No es posible ejecutar todo el pipeline en una sola sesion.
Orden canonico rigido: El audit es obligatorio como primer paso. Las convenciones deben formalizarse antes de extraer features. No se puede saltar ni reordenar pasos.
No modifica codigo funcional: SDD Legacy solo lee, analiza y documenta. Las unicas escrituras son a CLAUDE.md, .claude/rules/, y artefactos de documentacion.
Dependencias deben estar instaladas: Para auditoria completa de dependencias vulnerables, node_modules (o equivalente) debe existir.
GitHub es el canal principal: ATL funciona con solo el milestone + CLAUDE.md. Engram es enrichment opcional que mejora la calidad si ambos (PM y dev) comparten el mismo backend.

Inventario de archivos de referencia¶

El plugin incluye 12 archivos de referencia que los skills cargan bajo demanda:

references/audit-checklist.md — Checklist de auditoria
references/audit-output-assembly.md — Ensamblado del reporte de auditoria
references/audit-preflight-checks.md — Verificaciones previas
references/audit-atl-bootstrap.md — Bootstrap de ATL en CLAUDE.md
references/feature-detection-heuristics.md — Heuristicas para detectar features
references/spec-extractor-continuation-mode.md — Modo de continuacion
references/spec-extractor-document-import.md — Importacion de documentos
references/spec-extractor-feature-template.md — Template de Feature Spec
references/spec-extractor-prd-generation.md — Generacion de PRD retroactivo
references/spec-extractor-preexisting-issues.md — Manejo de issues preexistentes
references/rule-detection-patterns.md — Patrones para detectar reglas
references/rules-extraction-workflow.md — Workflow de extraccion de reglas