SDD Assistant: Orquestador de IA para Software-Driven Development

SDD Assistant es la extensión oficial de Visual Studio Code para el paradigma Software-Driven Development. Funciona como el "puente" local y determinista entre tu repositorio y tus agentes de IA: un sistema de agentes (Cursor, GitHub Copilot, Antigravity, Terminal, Clipboard) que gestiona los prompts de las tareas del ciclo Software-Driven Development y una máquina de estados finita (FSM) que orquesta el ciclo de vida de cada Historia de Usuario. La extensión es 100% local y determinista: no requiere red, no empaqueta LLM ni motores de conocimiento embebidos.

🚀 ¿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. Sistema de Agentes Multi-IDE: Enruta cada prompt de tarea al agente configurado (GitHub Copilot, Cursor, Antigravity o portapapeles); Terminal se usa como fallback interno.
4. Máquina de Estados Finita (FSM) Inquebrantable: Ciclo de vida estricto (raw → writing → pending → certified → in-progress → smell-check → testing → done → closed) con autoridad única de escritura de sus banderas y protecciones contra retrocesos no deseados.
5. Panel de Control de IA (Sidebar): Vista lateral nativa para gestionar el Backlog, el Historial, adoptar Roles/Skills y lanzar comandos de verificación.
6. Commit-Guardian: Valida Markdown antes del cierre, solicita confirmación del commit y aplica Git-First; Guardian sanea secretos en los prompts enviados al agente.
7. ADR (Architecture Decision Records): Sistema formal de decisiones arquitectónicas en .sdd/project/adr/; los 6 ADRs fundacionales se validan automáticamente solo cuando están presentes localmente.
8. Almacenamiento local SQLite (sql.js/WASM): Persistencia del backlog de HUs con SQLite embebido (sin dependencias nativas ni de red).

🏛️ Arquitectura Interna (Clean Architecture)

El código fuente sigue Clean Architecture estrictamente dividida 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,
│                     #   guardian, prompt-engine, sdd-compilation, telemetry…)
├── infrastructure/   # Adaptadores: SQLite WASM, Git, FileSystem, estrategias de agente
├── presentation/     # Sidebar WebViews, comandos VS Code, renderers, dashboard
└── bootstrap/        # Composition root: ensambla agentes, servicios y BD (HU-134)

Invariante crítico: Nada dentro de src/core/ puede importar vscode. El script check:core-isolation lo verifica automáticamente en cada build. El composition root (única capa que construye los adaptadores concretos) vive en src/bootstrap/.

🛠️ Instalación y Configuración Inicial

1. Descarga e instala el archivo sdd-assistant-X.Y.Z.vsix en tu Visual Studio 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:
  • project/architecture.md — Stack tecnológico e invariantes.
  • project/verification.md — Comandos de tests, lint y seguridad.
  • project/contracts.md — Índice de contratos públicos (Anti-Drift).
  • project/product.md — Visión de negocio.
  • project/adr/ — Registro opcional de decisiones arquitectónicas mediante adr-writer; no se crea durante onboarding.
• Se crea el backlog.json para gestionar el ciclo de vida de HUs.
• Se instala un hook pre-commit que valida con markdownlint los Markdown de .sdd/ incluidos en el commit.
• Se copia al proyecto el ecosistema versionado de templates, agents, skills y standards.
• El VSIX incluye resources/ completo para que el onboarding pueda leerlo; las guías de resources/guides/ permanecen en la extensión y no se copian a .sdd/.
• .vscode/settings.json es un archivo versionado del repositorio y no debe eliminarse como parte del onboarding.

🖥️ Interfaz (Sidebar)

Una vez inicializado el proyecto verás el ícono SDD en la barra de actividad de VS Code. La vista main 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 → writing → pending → certified → in-progress → smell-check → testing → done → closed. No se permiten saltos de estado; done sigue siendo activa hasta el cierre humano (closed).
• Flujo de Trabajo Seguro: La UI bloquea el estado durante procesos asíncronos (evita race conditions).
• Quality Gate Interactivo: Antes del cierre, ejecuta ESLint; el cierre transaccional valida Markdown con markdownlint. Permite autocorrección o continuar explícitamente; los tests se ejecutan por separado.
• Verificación Dinámica (Terminal): Botones context-aware que lanzan comandos desde verification.md. Si detectan la rama actual (ej. feature/HU-139), muestran únicamente los comandos relevantes para esa HU.
• Indicador de actividad (status-bar): Estados fiables de la extensión (compilar, quality-gate, transiciones, envío a agente) notificados al webview vía IPC agentStatus.

Además de la vista main, el sidebar dispone de la vista dedicada Historial. Los Roles y Skills ya no son vistas separadas del activity bar: se invocan desde el botón Roles & Skills del título de la vista main, que abre un selector rápido (QuickPick) para enviar el prompt del rol/skill elegido al agente configurado.

🗃️ Historial

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

👥 Roles (vía QuickPick)

Inyecta el prompt del rol correcto para cada fase del ciclo de desarrollo. Roles disponibles:

🛠️ Skills (vía QuickPick)

Micro-Agentes especializados accesibles desde el panel y mediante prompts:

Ciclo de Vida de HUs

• hu-writer — Redacción estructurada de Historias de Usuario (modo completar/entrevistar).
• multi-agent-certification — Comité de Architect + DBA + Security Auditor para certificar HUs antes de iniciar desarrollo.

Calidad y Arquitectura

• smell-detector — Análisis estático de Code Smells y Anti-Patrones con routing multi-agente.
• code-cleaner — Refactorización guiada bajo principios KISS/SOLID.
• pattern-refactorer — Aplicación de patrones de diseño correctivos.
• automata-architect — Refactoriza código de estado frágil a Autómatas Finitos (DFA/NFA).
• contracts-writer — Actualiza contratos públicos en .sdd/project/contracts/ (Anti-Drift).
• mermaid-expert — Generación de diagramas Mermaid (C4, sequence, flowchart, state).
• adr-writer — Redacción y actualización de Architecture Decision Records al formato canónico.

Testing y Verificación

• golden-tester — Generación de tests resilientes (BDD, Gherkin, Vitest/Mocha).
• ci-writer — Configuración de pipelines de integración continua.
• commit-guardian — Validación pre-commit con Quality Gate interactivo.

Análisis de Ecosistema

• project-onboarder — Escaneo del código existente y configuración inicial de SDD.
• product-onboarder — Entrevista de producto para definir visión y alcance.
• business-context-analyzer — Detección de Bounded Contexts en el código.
• domain-scaffolder — Generación de scaffolding de dominio (entidades, ports, adapters).
• security-auditor — Auditoría OWASP, vulnerabilidades y fixes dinámicos.
• dependency-analyzer — Verificación de dependencias obsoletas o vulnerables.

Mantenimiento

• verification-updater — Autodescubrimiento de scripts de testing.
• config-exporter — Exportación del ecosistema SDD a ZIP/TAR para compartir configuración de equipo.

🤖 Agentes (Configuración IA)

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

• Auto-Prompting Dinámico: La extensión detecta la rama activa e instruye a la IA para leer las especificaciones del Backlog antes de actuar. El asistente nunca programa a ciegas.
• Detección automática de agente: En modo auto, detecta Copilot, Antigravity o Cursor; Terminal es fallback interno y portapapeles el último fallback (HU-174).

📊 Dashboard Dinámico

Webview interactivo (Ver Dashboard, comando sdd-assistant.openDashboard) 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)

Los botones del sidebar (Certificar HU, Iniciar Desarrollo, Smell Check, Handoff) disparan las transiciones FSM correspondientes (sdd.certifyHU, sdd.startDevelopment, sdd.smellCheck, sdd.handoff) a través del agente configurado.

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
• sdd-assistant.agentModel: modelo a sugerir al agente (opcional).
• sdd-assistant.copilotTransport: transporte para la integración con GitHub Copilot (auto | cli | api).
• sdd-assistant.debugLogging: activa el registro de depuración (por defecto false).

🏗️ ADRs Fundacionales

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

🧭 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.

🆕 Historial de Versiones Recientes

v0.28.7 — 22 de Septiembre de 2026

Documentación — routing-table y protocolo de escalamiento

• Eliminados 6 triggers solapados del refactoring_partner en routing-table.json (4 con technical_lead, 2 con architect).
• Añadida referencia a pattern-refactorer y protocolo de escalamiento a TECHNICAL_LEAD en refactoring_partner.md.

v0.28.6 — 11 de Septiembre de 2026

Blindaje — una HU cerrada no puede volver a contar como activa aunque su frontmatter no lo diga

• scanDir deriva el estado por ubicación: ficheros en history/ son closed aunque su frontmatter diga otra cosa.

v0.28.5 — 11 de Septiembre de 2026

Corregido — prompt de cada gate pertenece a su self-loop

v0.25.1 — Julio de 2026

Eliminación del motor RAG/embeddings — La extensión no empaqueta @huggingface/onnx ni modelos de embeddings. La inyección de contexto se delega al sistema de agentes y la compilación de AGENTS.md.

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 Septiembre de 2026 — v0.28.7

Hecho con ❤️ por el sdd-team