SDD-Wizards¶

Plugin de levantamiento de requerimientos para el equipo de proyecto (PM). Guia al PM paso a paso desde la idea hasta un Feature Spec completo subido como milestone en GitHub Projects, listo para que el equipo de desarrollo lo implemente con ATL Inteliside. Produce PRDs profesionales y Feature Specs con User Stories, Acceptance Criteria, Business Rules, Data Model y API Spec.

Prerequisitos¶

Claude Code o Claude.ai
GitHub CLI (gh) instalado y autenticado (gh auth login)
Acceso a GitHub Projects del repositorio del proyecto
Engram instalado (recomendado, no bloqueante para prd-wizard)

Skills¶

SDD-Wizards incluye 3 skills que cubren el ciclo completo de levantamiento de requerimientos. El prd-wizard y el feature-spec-wizard son wizards conversacionales interactivos que guian al PM con preguntas paso a paso. El tech-stack-selector es un skill de soporte invocado automaticamente durante la fase tecnica del PRD.

Skill	Descripcion	Invocacion	Tools permitidos
prd-wizard	Wizard interactivo que guia al PM para crear un PRD profesional. Fases 1-6 son de negocio (preguntas al PM), fases 7-10 son auto-tecnicas (Claude genera y pide confirmacion). Crea repo, GitHub Project, CLAUDE.md y labels ATL.	`/sdd-wizards:prd-wizard [nombre-producto]`	Read, Glob, Grep, Bash, Write, mem_save, mem_search, mem_context
feature-spec-wizard	Wizard interactivo que toma un PRD y guia al PM para detallar cada feature. Fases 1-4 de negocio, fases 5-7 auto-tecnicas. Crea milestone y issue en GitHub.	`/sdd-wizards:feature-spec-wizard [nombre-feature]`	Read, Glob, Grep, Bash, Write, mem_save, mem_search, mem_context
tech-stack-selector	Recomienda el stack tecnologico optimo segun tipo de proyecto, escala y requerimientos. Conoce que tecnologias tienen CLI tools, MCP servers o son SDK-only.	`/sdd-wizards:tech-stack-selector`	Read, Glob, Grep

Notas sobre los skills: - prd-wizard y feature-spec-wizard usan context: fork y disable-model-invocation: true (solo se invocan explicitamente). - tech-stack-selector usa model: sonnet y no tiene context: fork — es un skill ligero de soporte. - Cada wizard debe ejecutarse en una conversacion dedicada (no mezclar PRD y Feature Spec en la misma sesion).

Flujo de trabajo¶

El flujo se organiza en conversaciones separadas. Cada conversacion produce un artefacto que alimenta la siguiente:

Conversacion 1 — PRD + GitHub Setup (prd-wizard):
El PM describe su idea de producto.
Claude hace preguntas organizadas en fases de negocio (problema, usuarios, user stories, alcance, metricas, riesgos).
Claude genera automaticamente las secciones tecnicas (data model, API, arquitectura) y pide confirmacion.
Al finalizar: genera PRD-[nombre].md, crea el repo en GitHub, crea un GitHub Project, sube el PRD como issue, genera CLAUDE.md con configuracion ATL, genera .claude/rules/ con convenciones del stack, y crea los 9 labels ATL.
Conversacion 2+ — Feature Spec (feature-spec-wizard, una por feature):
El PM adjunta el PRD descargado de la conversacion anterior.
Claude guia la definicion de User Stories, Acceptance Criteria, Business Rules y UI behavior.
Claude genera automaticamente Data Model, API Spec y Error Handling.
Al finalizar: genera feat-[nombre].md, crea un milestone en GitHub con el contenido completo, crea un issue vinculado al milestone con label atl-ready, y lo agrega al GitHub Project.
Handoff al equipo dev:
El dev toma el milestone directamente con ATL: /atl-inteliside:orchestrador feat-[nombre].
No se requiere ninguna transformacion adicional. Los milestones son consumibles directamente por ATL.

La frontera entre PM y dev es clara: el PM entrega Feature Specs como milestones, el dev descompone en tasks con ATL.

Contratos de datos¶

Engram¶

Todos los artefactos de SDD-Wizards se guardan en el mismo engram_project que usara ATL despues. No se crea un proyecto Engram separado.

Los wizards producen artefactos con schemas fijos que ATL consume de forma determinista. A continuacion los topic keys principales:

topic_key	Contenido	Writer	Reader
`project/prd`	PRD completo con estructura JSON (overview, users, stories, requirements, scope, risks, stack)	prd-wizard	feature-spec-wizard, ATL orchestrador
`project/stack`	Stack tecnologico seleccionado con componentes, ADRs y referencias CLI/MCP	prd-wizard (via tech-stack-selector)	feature-spec-wizard, ATL orchestrador
`project/github-context`	owner, repo, visibility, project number	prd-wizard (Phase 9)	feature-spec-wizard, ATL orchestrador
`project/features/{feature-name}`	Feature Spec completo con user stories, ACs, BRs, data model, API, errors	feature-spec-wizard	ATL orchestrador
`project/features-index`	Indice acumulativo de features con status y metricas de calidad	feature-spec-wizard	feature-spec-wizard (continuation), ATL
`project/handoff/{feature}`	Senal de que la feature esta lista para ATL con metricas y links	feature-spec-wizard (Phase 8)	ATL sdd-from-github

El features-index es acumulativo entre sesiones: cada ejecucion de feature-spec-wizard agrega entries al indice. Esto permite continuation mode — al iniciar una nueva sesion, el wizard detecta features existentes y ofrece opciones.

Prerequisite matrix:

Wizard	Requiere	Bloqueante
prd-wizard	nada	-
feature-spec-wizard	`project/prd`	No (puede funcionar con descripcion manual)
feature-spec-wizard	`project/features-index`	No (crea uno nuevo si no existe)
feature-spec-wizard	`project/github-context`	No (detecta repo o pregunta)

GitHub¶

SDD-Wizards puede crear repos nuevos y detectar repos existentes. Todas las operaciones de GitHub son idempotentes (se pueden ejecutar multiples veces sin duplicar artefactos).

Artefactos creados en GitHub:

Artefacto	Formato	Quien lo crea
Repositorio	`{owner}/{repo}`	prd-wizard (Phase 9) — si no existe
GitHub Project	Titulo del producto	prd-wizard (Phase 9)
PRD Issue	`PRD: {Nombre}` con label `prd`	prd-wizard (Phase 9)
Milestone	`feat-{kebab-case}`	feature-spec-wizard (Phase 8)
Feature Spec Issue	`Feature Spec: {Nombre}` con labels `feature-spec`, `atl-ready`	feature-spec-wizard (Phase 8)

Labels creados proactivamente (para compatibilidad con ATL): - De SDD-Wizards: prd, feature-spec, milestone-spec, atl-ready - De ATL (anticipados): atl-task, area:backend, area:frontend, area:db, area:test, atl:pending, atl:in-progress, atl:done

Hooks¶

SDD-Wizards incluye hooks para validar prerequisitos y esquemas de output durante la ejecucion de los wizards.

Evento	Matcher	Hook	Timeout	Proposito
PreToolUse	`Bash`	prereq-check.sh	10s	Verifica que `gh` esta instalado, autenticado y con scope `repo` antes de ejecutar comandos
PostToolUse	`Write`	output-schema-validator.sh	15s	Valida que los archivos generados (PRD, Feature Spec) cumplan con el schema esperado

Configuracion para proyectos¶

Copiar el examples/CLAUDE.md al contexto de la conversacion con Claude. El template incluye:

## SDD-Wizards
# Skills disponibles:
# /sdd-wizards:prd-wizard         — Crear PRD desde cero
# /sdd-wizards:feature-spec-wizard — Detallar una feature del PRD
# /sdd-wizards:tech-stack-selector — Recomendar stack tecnologico

## Contexto del proyecto (completar antes de empezar)
- Producto: [nombre del producto]
- Empresa / Cliente: [nombre]
- Problema que resuelve: [descripcion breve]
- Usuarios objetivo: [quienes son]
- Stack tecnologico (si ya definido): [ej: Next.js + Supabase]
- Restricciones importantes: [presupuesto, plazo, integraciones]

Reglas de sesion: 1. Una conversacion por skill — no mezclar PRD y Feature Spec. 2. Una conversacion por feature — no detallar dos features juntas. 3. Descargar el output antes de cerrar — el archivo es la memoria entre conversaciones.

Integracion con Doc-Gen¶

Despues de completar el PRD wizard y generar Feature Specs, se recomienda correr doc-gen para mantener la documentacion del proyecto actualizada.

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

Limitaciones conocidas¶

Una feature por conversacion: El feature-spec-wizard debe ejecutarse en una conversacion dedicada por feature. No permite crear multiples Feature Specs en la misma sesion.
El task-spec-wizard fue eliminado: La generacion de tasks es responsabilidad exclusiva de ATL Inteliside (sdd-tasks). No intentar crear tasks desde SDD-Wizards.
Dependencia de GitHub CLI: Si gh no esta instalado o autenticado, las fases de GitHub (9 en PRD, 8 en Feature Spec) fallan. El hook prereq-check.sh bloquea con instrucciones claras.
IDs de Acceptance Criteria: Los ACs usan numeracion flat global (AC-01, AC-02, ...) a traves de todas las user stories. No reinician por story. ATL normaliza al formato domain-prefixed al generar la spec tecnica.
Sesiones sin Engram: Si Engram no esta disponible, los wizards funcionan pero pierden la capacidad de continuation mode y el handoff automatico a ATL requiere que el dev lea el milestone manualmente.

SDD-Wizards v1.1.0 — Marketplace Inteliside