SDD Workflow — Spec-Driven Development con IA

Resumen

Este documento describe el workflow oficial para desarrollar cambios en Sistema Bautista usando SDD (Spec-Driven Development) asistido por agentes de IA. Cubre el ciclo completo de fases, el modo de persistencia híbrido (Engram + OpenSpec), y las obligaciones de sincronización de memoria.

1. ¿Qué es SDD?

SDD es el proceso estructurado de planificación y ejecución de cambios antes de escribir una sola línea de código. El objetivo es que el alcance, los requerimientos y la arquitectura estén validados antes de implementar.

explore → propose → spec → design → tasks → apply → verify → archive

Cada fase produce un artifact que la siguiente fase consume. No se puede saltar fases.

2. Artifact Store: Modo Híbrido (OBLIGATORIO)

En este proyecto el modo es siempre hybrid. Sin excepciones.

Backend	Qué almacena	Cuándo usar
Engram	Memoria persistente cross-session	Siempre — fuente primaria de recuperación
OpenSpec	Archivos locales en `openspec/changes/`	Siempre — historial git, revisión de equipo, auditoría

Por qué los dos

Solo Engram: si el servidor de memoria falla o se pierde el contexto, los artifacts desaparecen
Solo OpenSpec: si se cambia de máquina o developer, la memoria no viaja con el archivo
Hybrid: cada artifact está en los dos lugares — el que resuelva primero gana

Convención de topic keys en Engram

sdd/{change-name}/explore
sdd/{change-name}/proposal
sdd/{change-name}/spec
sdd/{change-name}/design
sdd/{change-name}/tasks
sdd/{change-name}/apply-progress
sdd/{change-name}/verify-report
sdd/{change-name}/archive-report

Estructura en OpenSpec

openspec/
└── changes/
    └── {change-name}/
        ├── state.yaml          # estado actual del change
        ├── proposal.md
        ├── design.md
        ├── tasks.md
        ├── specs/
        │   ├── spec-01-*.md
        │   └── spec-02-*.md
        └── archive/            # archivado al completar

Orden de búsqueda de artifacts

Engram: mem_search(query: "{topic_key}", project: "bautista") → mem_get_observation(id)
Si no está en Engram → leer openspec/changes/{change-name}/
Si no está en ninguno → el artifact no existe, reportar al usuario

3. Fases del Ciclo SDD

`/sdd-explore`

Propósito: Investigar el codebase antes de comprometerse con un enfoque. Solo lectura.

Lee archivos, busca patrones, compara opciones
No modifica nada
Retorna análisis estructurado: Current State, Affected Areas, Approaches, Recommendation
Persiste artifact explore en Engram + openspec/

Cuándo usar: Antes de cualquier cambio de mediana o alta complejidad. Para features simples puede omitirse.

`/sdd-propose`

Propósito: Formalizar la idea como propuesta con alcance, motivación y enfoque.

Lee la exploración (si existe)
Documenta: qué problema resuelve, qué módulos afecta, qué enfoque se tomará, qué queda fuera del alcance
El usuario valida la propuesta antes de continuar

Artifact: proposal.md

`/sdd-spec`

Propósito: Escribir los requerimientos formales con escenarios Given/When/Then.

Lee la propuesta
Genera specs por área de cambio (una spec por módulo/capa si el cambio es amplio)
Cada spec tiene: descripción, reglas de negocio, criterios de aceptación, escenarios

Artifact: spec-XX-*.md por spec + entry en specs/

`/sdd-design`

Propósito: Definir la arquitectura técnica del cambio.

Lee la propuesta
Documenta: capas afectadas, nuevas entidades, contratos de API, decisiones técnicas con tradeoffs
En este proyecto: debe respetar la arquitectura 5-layer del backend y los patrones React del frontend

Artifact: design.md

`/sdd-tasks`

Propósito: Descomponer el cambio en tareas implementables y ordenadas.

Lee spec + design (ambos requeridos)
Genera checklist de tareas con dependencias explícitas
Cada tarea es atómica, testeable, estimable

Artifact: tasks.md

`/sdd-apply`

Propósito: Implementar las tareas.

Lee tasks + spec + design
Marca tareas completadas a medida que avanza
En modo TDD: primero tests, luego código (ver nota abajo)
Guarda apply-progress en Engram al finalizar cada batch

Nota TDD: Este proyecto tiene Strict TDD activo. El agente de apply DEBE seguir Red → Green → Refactor. No se saltan tests.

`/sdd-verify`

Propósito: Validar que la implementación coincide con las specs.

Lee spec + tasks + apply-progress
Reporta COMPLIANT / PARTIAL / SPEC_DIVERGENCE por cada criterio
Si hay divergencias: decide si corrección o actualización de spec (con confirmación del usuario)

`/sdd-archive`

Propósito: Cerrar el change y persisitir el estado final.

Consolida todos los artifacts en el archive report
Mueve el change a openspec/changes/archive/
Guarda el reporte final en Engram

No ejecutar archive hasta que verify haya pasado.

4. Comandos Meta (Orquestador)

Estos comandos los maneja el orquestador — no son skills directas:

Comando	Qué hace
`/sdd-new <change>`	Lanza explore + propose en secuencia
`/sdd-ff <change>`	Fast-forward: proposal → spec → design → tasks sin pausar
`/sdd-continue <change>`	Retoma el change en la siguiente fase pendiente

5. Engram: Sincronización y Obligatoriedad

Proyecto único: `bautista`

Toda la memoria del sistema (ERP, Portal, Ecommerce) vive bajo el proyecto bautista. No hay proyectos separados.

bash

# Siempre especificar el proyecto al guardar
mem_save --project bautista --title "..."

# Siempre especificar al buscar
mem_search --project bautista --query "..."

Cuándo guardar (obligatorio, sin esperar que te pidan)

El agente DEBE llamar mem_save inmediatamente después de cualquiera de estos eventos:

Decisión de arquitectura o diseño tomada
Bug fix completado (con root cause)
Convención o patrón establecido
Gotcha o comportamiento inesperado descubierto
Configuración de entorno realizada
Cualquier artifact SDD producido (explore, proposal, spec, design, tasks, apply-progress, verify-report)

Formato de observación

**What**: [qué se hizo, una línea]
**Why**: [por qué, motivación o problema]
**Where**: [archivos o paths afectados]
**Learned**: [gotchas, edge cases, decisiones — omitir si no hay]

Cierre de sesión (OBLIGATORIO)

Antes de terminar cualquier sesión significativa, el agente DEBE llamar mem_session_summary:

## Goal
[Qué se trabajó en la sesión]

## Discoveries
- [Hallazgos técnicos, gotchas]

## Accomplished
- ✅ [Completado con detalles]
- 🔲 [Identificado pero pendiente]

## Next Steps
- [Qué queda para la próxima sesión]

## Relevant Files
- path/to/file — [qué cambió o su rol]

Sin este cierre, la próxima sesión arranca sin contexto.

Recuperación post-compactación

Si el contexto se compacta (el historial se trunca), el agente DEBE:

Llamar mem_session_summary con el contenido del resumen de compactación
Llamar mem_context para recuperar contexto de sesiones anteriores
Recién entonces continuar trabajando

Sincronización con git

El directorio ~/.engram/ es local — no se commitea.

Para exportar y compartir:

bash

# Exportar snapshot de memoria
./scripts/engram-sync.sh

# Sincronizar + importar
./scripts/engram-sync.sh --import

# Ver estado
./scripts/engram-sync.sh --status

6. Gates de Documentación

El workflow SDD incluye dos gates obligatorios que generan documentación en docs/:

Pre-Apply Gate (después de tasks, antes de apply)

Si el cambio introduce una nueva feature funcional o modifica comportamiento existente:

Generar documentación de negocio en docs/features/{módulo}/
Mostrar al usuario y confirmar antes de proceder con apply

Post-Apply Gate (después de verify, antes de archive)

Si verify reportó divergencias → actualizar docs de negocio para reflejar lo implementado
Si el cambio introduce un nuevo patrón arquitectónico o módulo → generar docs técnicas en docs/backend/ o docs/frontend/

Criterio rápido: si nadie externo al equipo AI sabría que el sistema cambió leyendo solo docs/, hay que documentar.

7. Flujo Completo — Referencia Visual

Usuario: /sdd-new mi-feature
        │
        ▼
  [explore]  →  Lee codebase, compara enfoques
        │
        ▼
  [propose]  →  Alcance + motivación + enfoque elegido
        │         ← Usuario valida
        ▼
  [spec]     →  Requerimientos con Given/When/Then
        │
        ▼
  [design]   →  Arquitectura técnica, contratos API
        │
        ▼
  [tasks]    →  Checklist de tareas ordenadas
        │
        ├── [PRE-APPLY GATE] → docs/features/ si aplica
        │
        ▼
  [apply]    →  TDD: Red → Green → Refactor
        │         Guarda apply-progress en Engram
        ▼
  [verify]   →  Valida contra specs → COMPLIANT / DIVERGENCE
        │
        ├── [POST-APPLY GATE] → actualizar docs si aplica
        │
        ▼
  [archive]  →  Cierra change, persiste en Engram + openspec/archive/

8. Instalación del Stack

Stack completo (gentle-ai)

Incluye agentes de IA preconfigurados, Engram, skills base y configuración del entorno.

bash

# Ver instrucciones en el repo
# https://github.com/Gentleman-Programming/gentle-ai

→ Gentleman-Programming/gentle-ai

Usar este repo si se quiere levantar el entorno completo desde cero: agentes de IA + Engram + skills + configuración de proyecto.

Solo Engram

Si el entorno ya está configurado y solo se necesita la capa de memoria persistente:

bash

# Ver instrucciones en el repo
# https://github.com/Gentleman-Programming/engram

→ Gentleman-Programming/engram

Usar este repo para instalar únicamente Engram como sistema de memoria cross-session, independientemente del resto del stack.

Ver también

Engram Workflow — comandos de memoria detallados
Parallel Agents Workflow — apply con múltiples agentes en paralelo
CLAUDE.md (raíz) — política completa de SDD, documentación y multi-tenant

Joins

Retenciones

Ganancias

Sicore

Catalogos

Comercializacion

Extensiones

Presupuestos

Tercerizacion

Recursos Principales

Relaciones

Ciclo Comercial

Administracion

Comercial

Produccion

Tesoreria

Catalogos Base

Cupon Pago

Facturacion

Gestion Miembros

Grupos Familiares

Soporte Tecnico

Architecture

Backend

Api

Database

Migrations

Middleware

Security

Services

Deployment

Development

Testing

Frontend

Integrations

Payment Gateways

Retenciones

SDD Workflow — Spec-Driven Development con IA ​

Resumen ​

1. ¿Qué es SDD? ​

2. Artifact Store: Modo Híbrido (OBLIGATORIO) ​

Por qué los dos ​

Convención de topic keys en Engram ​

Estructura en OpenSpec ​

Orden de búsqueda de artifacts ​

3. Fases del Ciclo SDD ​

/sdd-explore ​

/sdd-propose ​

/sdd-spec ​

/sdd-design ​

/sdd-tasks ​

/sdd-apply ​

/sdd-verify ​

/sdd-archive ​

4. Comandos Meta (Orquestador) ​

5. Engram: Sincronización y Obligatoriedad ​

Proyecto único: bautista ​

Cuándo guardar (obligatorio, sin esperar que te pidan) ​

Formato de observación ​

Cierre de sesión (OBLIGATORIO) ​

Recuperación post-compactación ​

Sincronización con git ​

6. Gates de Documentación ​

Pre-Apply Gate (después de tasks, antes de apply) ​

Post-Apply Gate (después de verify, antes de archive) ​

7. Flujo Completo — Referencia Visual ​

8. Instalación del Stack ​

Stack completo (gentle-ai) ​

Solo Engram ​

Ver también ​

SDD Workflow — Spec-Driven Development con IA

Resumen

1. ¿Qué es SDD?

2. Artifact Store: Modo Híbrido (OBLIGATORIO)

Por qué los dos

Convención de topic keys en Engram

Estructura en OpenSpec

Orden de búsqueda de artifacts

3. Fases del Ciclo SDD

`/sdd-explore`

`/sdd-propose`

`/sdd-spec`

`/sdd-design`

`/sdd-tasks`

`/sdd-apply`

`/sdd-verify`

`/sdd-archive`

4. Comandos Meta (Orquestador)

5. Engram: Sincronización y Obligatoriedad

Proyecto único: `bautista`

Cuándo guardar (obligatorio, sin esperar que te pidan)

Formato de observación

Cierre de sesión (OBLIGATORIO)

Recuperación post-compactación

Sincronización con git

6. Gates de Documentación

Pre-Apply Gate (después de tasks, antes de apply)

Post-Apply Gate (después de verify, antes de archive)

7. Flujo Completo — Referencia Visual

8. Instalación del Stack

Stack completo (gentle-ai)

Solo Engram

Ver también