Herramientas de Diseño y Planificación (Stream D)

El Stream D contiene 7 herramientas para convertir specs en artefactos de implementación concretos — esquemas, contratos de UI, decisiones de arquitectura, planes de ejecución y contratos de eventos.

generate_adr

Genera Architecture Decision Records para una spec.

Qué produce: Documentos ADR estructurados que cubren el contexto de la decisión, opciones consideradas, decisión tomada y consecuencias. El formato sigue MADR (Markdown Architectural Decision Records).

Cuándo usarlo: Cuando una spec involucra una elección tecnológica significativa, patrón de arquitectura o trade-off que los futuros desarrolladores necesitan entender.

Prompt: "Generate ADRs for spec SPEC-004 in project proj_abc123"

Ejemplo de output:

# ADR-001: Usar Redis para almacenamiento de sesiones

## Estado: Aceptado

## Contexto
La spec de autenticación requiere persistencia de sesión en múltiples instancias del servidor...

## Decisión
Usar Redis como almacén de sesiones...

## Consecuencias
- Positivo: Escalado horizontal sin sticky sessions
- Negativo: Agrega Redis como dependencia de infraestructura requerida

---

design_schema

Diseña el esquema de base de datos a partir de los requisitos de la spec.

Qué produce:

• Definiciones de tablas con columnas, tipos y restricciones
• Relaciones de claves primarias y foráneas
• Sugerencias de índices para rendimiento de consultas
• Hints de migración
• Esquema en múltiples dialectos (SQL, Prisma, SQLAlchemy, GORM, etc.)

Cuándo usarlo: Cuando una spec involucra persistencia de datos y necesitas un punto de partida concreto para la capa de base de datos.

Prompt: "Design the database schema for spec SPEC-002 in project proj_abc123"

---

define_ui_contract

Define contratos de componentes de UI, flujo de datos y gestión de estado.

Qué produce:

• Definiciones de interfaz de componentes (props, eventos, slots)
• Diagrama de flujo de datos (qué componentes poseen qué estado)
• Enfoque de gestión de estado (local, contexto, store)
• Contrato de API entre frontend y backend
• Requisitos de accesibilidad

Cuándo usarlo: Para cualquier spec que incluya un componente frontend, formulario o interacción de usuario.

Prompt: "Define the UI contract for the login flow in spec SPEC-001 for project proj_abc123"

---

challenge_spec

Hace stress-test de una spec buscando fallos, concurrencia, escala y casos borde.

Qué verifica:

• Problemas de concurrencia (race conditions, deadlocks)
• Puntos de quiebre de escala (¿qué pasa con 10x, 100x de carga?)
• Modos de fallo (¿qué pasa si la base de datos no está disponible?)
• Casos borde no cubiertos por los criterios de aceptación
• Superficie de ataque de seguridad

Cuándo usarlo: Para cualquier spec que correrá en producción con usuarios reales. Especialmente valioso para specs que tocan pagos, autenticación o features en tiempo real.

Prompt: "Challenge spec SPEC-003 for project proj_abc123"

---

generate_execution_plan

Genera un PLAN.md paso a paso para implementar una spec — ciclo RED/GREEN/VERIFY con pasos paralelizables.

Qué produce:

## Fase 1: Fundación (paralelo)
- [ ] Paso 1a: Crear migración de base de datos
- [ ] Paso 1b: Definir interfaces TypeScript
- [ ] Paso 1c: Escribir tests fallando (RED)

## Fase 2: Implementación (secuencial)
- [ ] Paso 2a: Implementar capa de repositorio (GREEN)
- [ ] Paso 2b: Implementar capa de servicio

## Fase 3: Verificación
- [ ] Paso 3a: Ejecutar suite completa de tests (VERIFY)
- [ ] Paso 3b: Actualizar estado de la spec a review

Cuándo usarlo: Antes de que comience la implementación. El PLAN.md se convierte en el contrato de implementación para el agente de IA o el desarrollador.

Prompt: "Generate an execution plan for spec SPEC-005 in project proj_abc123"

---

generate_orchestration_script

Genera un script de automatización paralela de 3 capas (worktrees + claude -p) para ejecutar múltiples specs concurrentemente.

Qué produce: Un script de shell que:

• Crea git worktrees aislados por spec
• Lanza workers de claude -p en paralelo
• Gestiona la asignación de recursos basada en CPU y RAM disponibles
• Monitorea la salud de los workers y maneja fallos

Cuándo usarlo: Cuando necesitas implementar múltiples specs independientes simultáneamente y quieres máximo paralelismo.

Prompt: "Generate an orchestration script for specs SPEC-010, SPEC-011, SPEC-012 in project proj_abc123"

---

event_contracts

Gestiona contratos de arquitectura event-driven — genera contratos de eventos JSON Schema para validación productor/consumidor.

Qué produce:

• Definiciones JSON Schema para cada tipo de evento
• Contrato del productor (qué garantiza el emisor)
• Contrato del consumidor (qué espera el suscriptor)
• Estrategia de versionado
• Notas de compatibilidad hacia atrás

Cuándo usarlo: Para cualquier spec que involucre colas de mensajes, buses de eventos (Kafka, RabbitMQ, AWS SQS/SNS, NATS) o integraciones de webhooks.

Prompt: "Define event contracts for the order processing flow in spec SPEC-008 for project proj_abc123"

Ejemplo de output:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "OrderPlaced",
  "version": "1.0.0",
  "type": "object",
  "required": ["orderId", "customerId", "items", "total", "placedAt"],
  "properties": {
    "orderId": { "type": "string", "format": "uuid" },
    "customerId": { "type": "string", "format": "uuid" },
    "items": { "type": "array", "items": { "$ref": "#/definitions/OrderItem" } },
    "total": { "type": "number", "minimum": 0 },
    "placedAt": { "type": "string", "format": "date-time" }
  }
}