SDD Assistant: Orquestador de IA para Software-Driven Design

SDD Assistant es la extensión oficial de Visual Studio Code para el paradigma Spec-Driven Development. Funciona como el "puente" local y determinista entre tu repositorio y tu Agente de IA preferido (Cursor, GitHub Copilot, Antigravity, Gemini, Claude, etc.).

🚀 ¿Qué hace SDD Assistant?

En lugar de depender de que una IA intente "adivinar" toda la arquitectura de tu proyecto, SDD Assistant estructura un andamiaje documental (.sdd/) y gestiona dinámicamente el contexto (AGENTS.md + derivados por IDE) inyectando únicamente las especificaciones de la historia de usuario activa.

1. Gestión de Contexto Reactivo: Observa tus ramas de Git (ej. feature/HU-101) y compila dinámicamente tu archivo de reglas de IA en tiempo real.
2. Onboarding Automático: Prepara tu repositorio para colaborar con Inteligencia Artificial con un solo comando.
3. Commit-Guardian Transaccional: Evalúa y limpia el código (Linters, Tests, ADRs) antes de permitir un commit, forzando un flujo Test-Driven.
4. Máquina de Estados Finita (FSM) Inquebrantable: Ciclo de vida estricto raw → pending → certified → in-progress → smell-check → testing → done con protecciones contra retrocesos que evitan bucles infinitos en Agentes IA.
5. Panel de Control de IA (Sidebar): Vista lateral nativa para gestionar Backlog, adoptar Roles/Agentes y lanzar comandos de Verificación.
6. Orquestador RAG Local (SQLite WASM): Base de datos sql.js embebida y operativa en la extensión. Provee búsqueda semántica e inyección de contexto O(1) con cero fugas de memoria y sin dependencias de red.
7. ADR (Architecture Decision Records): Sistema formal de registro de decisiones arquitectónicas en .sdd/project/adr/, con 6 ADRs fundacionales validados automáticamente por la suite de tests (Vitest).

🏛️ Arquitectura Interna (Clean Architecture)

El código fuente sigue Clean Architecture dividida estrictamente en capas bajo src/:

src/
├── core/           # Dominio puro — sin dependencia de `vscode` ni librerías externas
│   ├── domain/     # Entidades, Value Objects, FSM de tareas
│   ├── ports/      # Interfaces (contratos) hacia infraestructura
│   └── __tests__/  # Tests unitarios BDD con Vitest (coverage ≥ 90%)
├── contexts/       # Bounded Contexts de negocio (task-management, quality-gate…)
├── infrastructure/ # Adaptadores: SQLite WASM, Git, FileSystem
└── presentation/   # Sidebar WebViews, comandos VS Code, renderers

Invariante crítico: Nada dentro de src/core/ puede importar vscode. El script check:core-isolation lo verifica automáticamente en cada build.

Pipeline de Calidad Automatizado

Cada pretest ejecuta en cadena:

clean → compile → lint → check:circular → check:core-isolation

Y npm run test:coverage (Vitest) garantiza ≥ 90% de cobertura sobre src/core/ de forma aislada del Extension Host de VS Code.

🛠️ Instalación y Configuración Inicial

1. Descarga e instala el archivo .vsix en VS Code:

   Extensions → ··· → Install from VSIX…

2. Abre tu proyecto local en VS Code.
3. Abre la paleta de comandos (Ctrl+Shift+P / Cmd+Shift+P) y ejecuta: SDD: Inicializar Proyecto

¿Qué ocurre al inicializar?

Se crea la carpeta .sdd/ con el esqueleto completo del proyecto:

Además se instala un hook pre-commit que valida Markdown y la extensión copia automáticamente el prompt de inicio del project-onboarder al portapapeles.

🖥️ Interfaz (Sidebar)

Una vez inicializado el proyecto verás el ícono SDD en la barra de actividad de VS Code. El panel está dividido en 6 vistas nativas:

1. 📋 SDD Assistant (Backlog & Verificación)

La vista principal orquesta el trabajo activo y la calidad:

• Gestión de HUs: Crea y edita Historias de Usuario a través de un formulario Webview con campos de Fibonacci, MoSCoW y descripción completa.
• Ciclo de Vida FSM: Botones de transición de estado siguen estrictamente la cadena raw → pending → certified → in-progress → smell-check → testing → done. No se permiten saltos de estado.
• Estado working: Bloquea la UI durante procesos asíncronos para evitar race conditions.
• Quality Gate Interactivo: Antes de commitear ejecuta Markdown lint, lint de TypeScript y tests. Permite autocorrección o bloqueo explícito.
• Verificación Dinámica: Botones context-aware que leen verification.md. Si detectan la rama activa (ej. feature/HU-139), muestran solo los comandos relevantes para esa HU.

2. 🗃️ Historial

• Gestión de HUs finalizadas o bloqueadas.
• Archivado Profundo (archiveOldTasks): mueve tareas con más de 30 días a .sdd/features/archive/YYYY-MM/.

3. 👥 Roles

Inyecta el prompt del rol correcto en tu chat de IA según la fase del ciclo de desarrollo:

4. 🛠️ Skills

Micro-Agentes especializados, organizados por área:

Ciclo de Vida de HUs

Calidad y Arquitectura

Testing y Verificación

Análisis de Ecosistema

Mantenimiento

5. 🤖 Agentes (Configuración IA)

Configura hacia dónde se envían los prompts contextuales:

• Auto-Prompting Dinámico: La extensión detecta tu rama activa e instruye a la IA para leer las especificaciones del backlog antes de actuar. El asistente nunca programa a ciegas.

6. 📊 Dashboard Dinámico

Webview interactivo (SDD: Open Dashboard) con:

• Progreso en vivo del Backlog (por estado y prioridad).
• Salud Arquitectónica (lectura de frontmatter de architecture.md).
• Resúmenes técnicos extraídos de Frontmatter YAML de las HUs.

⚡ Comandos Disponibles

Paleta de Comandos (Ctrl+Shift+P)

Scripts NPM

⚙️ Settings de Integración Multi-IDE

• sdd-assistant.targetIde: auto | cursor | vscode | antigravity | universal
  • auto → detecta el IDE en runtime con fallback seguro
  • cursor → AGENTS.md + .cursor/rules/sdd-context.mdc
  • vscode → AGENTS.md + .github/copilot-instructions.md
  • antigravity → AGENTS.md + .agents/* + GEMINI.md
  • universal → todos los anteriores, compilando AGENTS.md una sola vez
• sdd-assistant.agentIntegration: auto | cursor | copilot | antigravity | clipboard

🧭 Convención de Rutas

• En prompts, mensajes y Markdown: rutas POSIX con prefijo ./ (ej. ./.sdd/project/product.md).
• Toda ruta textual es relativa a la raíz del workspace.
• Evita formatos ambiguos como ~.sdd/... o rutas absolutas en documentos.
• En código TypeScript/Node usa path.join(...) siempre.

🏗️ ADRs Fundacionales

Las decisiones arquitectónicas están documentadas en .sdd/project/adr/ y son validadas automáticamente por la suite de tests en cada ciclo de CI:

🆕 Historial de Versiones Recientes

v0.20.0 — 22 de Julio de 2026 (Fase 7)

Auditoría de Capas, CQRS y Cobertura (HU-137 a HU-139)

• Auditoría y Separación de Capas (HU-137): Verificación formal de que ningún artefacto del core cruza límites hacia vscode o infraestructura.
• CQRS en Módulo de Tareas (HU-138): Commands (escritura) y Queries (lectura) en rutas separadas con contratos propios.
• Cobertura Rigurosa y ADRs (HU-139): Vitest con threshold ≥ 90% en src/core/. Cobertura actual: 98.79%. 6 ADRs fundacionales validados automáticamente.
• Invariante check:core-isolation: Script de CI que previene imports de vscode dentro de src/core/.

v0.19.5 — 22 de Julio de 2026 (Fase 5)

Commit-Guardian Predictivo (HU-131 a HU-133)

• Interceptor y Detector de Secretos (HU-131): Hook pre-commit que analiza diffs con el motor RAG y bloquea tokens, API keys o contraseñas hardcodeadas.
• Validación Semántica del Commit (HU-132): El CommitGuard vectoriza el diff y lo compara contra la DoD de la HU activa. Bloquea commits no alineados.
• UI modo warn (HU-133): Modo no bloqueante que advierte sin rechazar, permitiendo al desarrollador decidir.

v0.19.4 — 22 de Julio de 2026 (Fase 4)

Análisis Proactivo y Resiliencia (HU-134 a HU-136)

• Análisis Delta-Driven (HU-134): Re-vectorización automática solo de los fragmentos que cambiaron al guardar, sin re-indexar el grafo completo.
• Multi-Repo Zero-Crossover (HU-135): Shadow DB aislada por repositorio en workspaces multi-root. Sin contaminación cruzada de contexto.
• Evaluación HNSW Condicional (HU-136): Algoritmo HNSW como alternativa a búsqueda bruta para bases >10k chunks. Documentado en ADR-007.

v0.19.3 — 22 de Julio de 2026 (Fase 3)

SearchService y PromptCrafter RAG (HU-126 a HU-130)

• Corrección de Drift Arquitectónico (HU-126): Sincronización de contratos de TelemetryRepository, SearchService y EmbeddingWorker.
• SearchService MVP FTS5+BM25 (HU-127): Búsqueda unificada con ranking BM25. Devuelve top-K resultados con score normalizado.
• PromptCrafter con Inyección Top-3 (HU-128): Inyección automática de los 3 fragmentos más relevantes de la knowledge base en cada prompt, reduciendo desperdicio de tokens.
• Telemetría de Tokens Ahorrados (HU-129): Métricas en logs/YYYY-MM-audit.jsonl para medir el ROI del motor semántico.
• ConversationManager Ventana Fija (HU-130): Solo los últimos 3 turnos (~1,500 tokens) se incluyen en cada llamada. Elimina el crecimiento ilimitado de contexto.

v0.19.2 — 22 de Julio de 2026 (Fase 2)

Motor de Embeddings y Vectorización (HU-122 a HU-125)

• Indexación de Contratos y Skills (HU-122): El bootstrapper indexa .sdd/project/contracts/ y .sdd/skills/ en la shadow DB.
• Motor de Embeddings en Web Worker (HU-123): @xenova/transformers ejecutándose en hilo separado sin bloquear la UI.
• Descarga Progresiva Cold Start (HU-124): Barra de progreso en la status bar durante la primera descarga del modelo; caché local en activaciones posteriores.
• Vectorización de Knowledge Base (HU-125): Pipeline completo: chunking + vectores de 384 dimensiones almacenados en SQLite para búsqueda semántica por similitud coseno.

v0.19.1 — 22 de Julio de 2026 (Fase 1)

Orquestador RAG Local: Shadow DB y FTS5 (HU-119 a HU-121)

• Bootstrap SQLite desde Archivos Planos (HU-119): La Shadow DB (sql.js WASM) se inicializa al activar la extensión, indexando todos los Markdown de .sdd/ con sus metadatos de frontmatter.
• FileWatcher con Sincronización Bidireccional (HU-120): Watcher reactivo sobre .sdd/features/; upsert/delete automático en la shadow DB al modificar HUs en disco sin reiniciar VS Code.
• Búsqueda FTS5 con BM25 (HU-121): Búsqueda de texto completo con ranking BM25 en tiempo O(\log n) sobre la knowledge base.

v0.19.0 — 20 de Julio de 2026

• Graph Forge & SRP: Motor matemático Graph Forge + extracción de referencias a references.md.
• Onboarding Refactorizado: Plantillas físicas (TEMPLATE_REFERENCES.md) en lugar de strings quemados.
• Skill Automata Architect: Refactorización de estado frágil a Autómatas Finitos (DFA/NFA) con integración UI.

v0.18.0 — 20 de Julio de 2026

• Skill automata-architect: Refactoriza Spaghetti Code de estado en DFA/NFA.
• Interconectividad IA: smell-detector delega hallazgos de estado frágil a automata-architect.

v0.17.0 — 20 de Julio de 2026

• TDD Framework FSM (HU-117 & HU-118): Cobertura completa del Happy Path y Reject Path de la Máquina de Estados.

v0.16.0 — 20 de Julio de 2026

• Estado CERTIFIED inyectado en la FSM. Certificación por Comité IA obligatoria entre PENDING e IN_PROGRESS.

v0.15.0 — 17 de Julio de 2026

• Dashboard Dinámico (HU-111, HU-113, HU-114) y FSM Mutex (HU-110, HU-112).

🔮 Orquestador RAG Local — Estado Actual

El Cerebro Orquestador Semántico (Local RAG) está implementado y operativo desde v0.15.0:

Arquitectura del RAG

• Shadow DB (SQLite WASM): Base de datos sql.js local para consultas O(1) que actúa como caché reactivo, preservando la filosofía Docs as Code.
• Telemetría de Agentes: Registro asíncrono en JSONL (logs/YYYY-MM-audit.jsonl) con métricas de prompts, variables de contexto y tasas de acierto.
• Adaptador Aislado: La implementación reside en src/infrastructure/ respetando el contrato ports/ del dominio, garantizando el aislamiento total del core.

🔜 Próximas Capacidades — Fase 6: UI Webview y Terminal Integrada

Duración estimada: 10-14 días | Riesgo: Medio

La terminal v2 con xterm.js embebido en el Sidebar es una mejora post-MVP condicionada a demanda real de usuarios (≥ 30% de preferencia confirmada). Ver ADR-006 en .sdd/project/adr/.

Última actualización: 22 de Julio de 2026 — v0.20.0

Hecho con ❤️ por el sdd-team