███████╗ ██████╗ ██████╗  ██████╗ ███████╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝ ██╔════╝
█████╗  ██║   ██║██████╔╝██║  ███╗█████╗
██╔══╝  ██║   ██║██╔══██╗██║   ██║██╔══╝
██║     ╚██████╔╝██║  ██║╚██████╔╝███████╗
╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚══════╝

FORGE — From idea to product, forged locally

Convierte una idea en un MVP funcional sin conocimiento técnico. Lenguaje natural → descubrimiento → diseño → wireframe → especificación → código.

FORGE es un sistema de generación de MVPs que opera en dos modos complementarios: como plugin de Claude Code (sin necesidad de abrir un navegador) y como web app local accesible en localhost:3742. En ambos casos el flujo es el mismo: describes tu idea en lenguaje natural y FORGE orquesta un pipeline de agentes especializados que produce un producto real.

Está construido sobre sdd-lite, un plugin de Spec-Driven Development en español para Claude Code que aporta 30 comandos, 14 agentes y 17 skills. FORGE añade encima el pipeline de interpretación de ideas, los design systems, el picker de dirección visual y la capa web multi-proveedor (Anthropic, OpenAI, Ollama).

Tabla de contenidos

1. Instalación
2. Uso rápido
3. Arquitectura y pipeline
4. Design Systems
5. Comandos SDD
6. Pipeline API
7. Multi-proveedor
8. Tests
9. Contribuir
10. Licencia

Instalación

Requisitos

• Node.js >= 18
• Claude Code (para el modo plugin)

Opción 1 — npx (recomendado)

npx forge-mvp setup
npx forge-mvp build "Tu idea"

Opción 2 — Script de instalación

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/tu-usuario/sdd-lite/main/instalar.sh | bash

O descarga y ejecuta localmente:

bash instalar.sh           # proyecto actual
bash instalar.sh --global  # para todos tus proyectos

Windows (PowerShell):

.\instalar.sh
# Si la política de ejecución lo bloquea:
powershell -ExecutionPolicy Bypass -File .\instalar.sh

Opción 3 — Desde el código fuente

git clone https://github.com/tu-usuario/sdd-lite.git
cd sdd-lite
npm install
npm start

Para modo desarrollo (sin abrir el navegador):

npm run dev

Uso rápido

Modo CLI (línea de comandos)

Paso 1: Configurar proveedor

npx forge-mvp setup

Responde las preguntas interactivas:

• ¿Qué proveedor? (anthropic, openai, google, grok, ollama)
• ¿Qué modelo? (opciones listadas según proveedor)
• API key (o host para Ollama)

Tu configuración se guarda en .forge.config.json

Paso 2: Generar MVP

npx forge-mvp build "App para gestionar citas dentales"

FORGE ejecuta el pipeline completo:

1. Interpreter — analiza tu idea y extrae requirements
2. Discovery — preguntas contextuales automáticas
3. Product Designer — diseño de flujos de usuario
4. Architecture — definición técnica y stack
5. Wireframe — generación de HTML navegable
6. Spec — especificación técnica lista para implementar

Proveedores soportados

| Proveedor | Modelos | Requisito | |-----------|---------|-----------| | Anthropic | Claude Opus 4.8, Sonnet 4.6, Haiku 4.5 | API key | | OpenAI | GPT-4o, GPT-4 Turbo, GPT-4o Mini | API key | | Google Gemini | 2.0 Flash, 1.5 Pro, 1.5 Flash | API key | | Grok / xAI | Grok 2, Grok 1 | API key | | Ollama | Llama 3, Mistral, Gemma, Nemotron, etc. | Local (sin API) |

Flujo SDD completo (proyectos de código existente):

/sdd.constitucion         ← principios, stack, restricciones
/sdd.especificar [idea]   ← spec con criterios de aceptación testeables
/sdd.planificar           ← plan técnico con arquitectura
/sdd.tareas               ← tareas atómicas con agente asignado
/sdd.implementar          ← agentes especializados en paralelo
/sdd.qa                   ← QA en navegador real (Playwright)
/sdd.verificar            ← verificación contra spec original
/sdd.desplegar            ← gate de calidad → deploy → health check

Arquitectura y pipeline

  ENTRADA
     │
     ▼
┌─────────────────────────────────────────────────────────┐
│  Lenguaje Natural (idea del usuario)                    │
└─────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────┐
│   DISCOVERY     │  5 preguntas: superficie · audiencia · tono
│  (skill)        │  restricciones · inspiración
└────────┬────────┘
         │  descubrimiento.md
         ▼
┌─────────────────┐
│  INTERPRETER    │  Fase A: razonamiento libre (Opus)
│  (skill)        │  Fase B: extracción a IR JSON
└────────┬────────┘
         │  .sdd/ir.json  (confidence 0.0–1.0)
         ▼
┌─────────────────┐
│ DIRECTION PICKER│  5 design systems → el usuario elige
│  (skill)        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ PRODUCT DESIGNER│  user_flow · core_screens · MVP scope
│  (agent, Opus)  │  → .sdd/product-design.json
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   ARCHITECTURE  │  stack · servicios · contratos
│  DESIGNER       │  → .sdd/arquitectura/
│  (agent, Sonnet)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   WIREFRAME     │  HTML navegable por pantalla
│  (skill, Sonnet)│  → .sdd/diseño/wireframe-*.html
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  DESIGN CRITIC  │  evalúa consistencia visual
│  (skill, Sonnet)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  SPEC + TAREAS  │  criterios de aceptación testeables
│  IMPLEMENTAR    │  → agentes especializados en paralelo (PTC)
│  QA · VERIFICAR │  → tests E2E reales (Playwright)
└────────┬────────┘
         │
         ▼
  PRODUCTO LISTO

Componentes del sistema

| Capa | Contenido | |------|-----------| | cli/ | CLI interactivo: setup, build. Gestiona config y comanda pipeline | | providers/ | Adaptador multi-proveedor (model-client.js) con streaming | | pipeline/ | Definiciones de los pasos del pipeline | | sdd-lite/commands/ | 30 comandos Claude Code (Markdown con frontmatter) | | sdd-lite/agents/ | 14 agentes especializados | | sdd-lite/skills/ | 17 skills reutilizables | | sdd-lite/core/ | Types TypeScript del IR, mappers, project memory | | design-systems/ | 5 design systems con tokens, tipografía y paletas | | craft/ | Estándares editoriales: tipografía, color, accesibilidad |

Design Systems

FORGE incluye 5 design systems completos. En el Direction Picker, el usuario elige uno antes de generar el wireframe.

| Design System | Estilo | Mejor para | |---------------|--------|------------| | neutral-modern | Limpio, minimalista, grises neutros | SaaS, herramientas de productividad, B2B | | warm-editorial | Tipografía serif, tonos tierra, espaciado generoso | Blogs, publicaciones, servicios creativos | | bold-brutalist | Alto contraste, bordes gruesos, tipografía pesada | Portfolios, productos disruptivos, landing pages | | editorial-minimal | Grid estricto, paleta reducida, jerarquía tipográfica | Medios, newsletters, documentación premium | | vibrant-consumer | Colores saturados, gradientes, energía visual | Apps de consumo, e-commerce, productos B2C |

Cada design system incluye:

• Tokens de color (primario, secundario, neutros, semánticos)
• Escala tipográfica completa con pesos y alturas de línea
• Especificaciones de espaciado
• Guía de componentes clave
• Principios anti-AI-slop para evitar interfaces genéricas

Comandos SDD

El plugin sdd-lite aporta 30 comandos accesibles desde Claude Code. El hub /sdd entiende lenguaje natural y enruta al comando correcto.

FORGE (idea → producto)

| Comando | Qué hace | |---------|----------| | /sdd.interpretar [idea] | Discovery (5 preguntas) + interpretación a IR JSON. Punto de entrada FORGE. | | /sdd.diseñar | Direction picker + Product Designer + wireframe MVP | | /sdd.construir | Pipeline completo automático: diseño → spec → tareas → código | | /sdd.exportar | Empaqueta el bundle del proyecto en un archivo distribuible |

Inicialización y configuración

| Comando | Qué hace | |---------|----------| | /sdd | Hub central — entiende lenguaje natural y enruta al comando correcto | | /sdd.constitucion | Establece principios, stack y restricciones del proyecto | | /sdd.configurar | Ajusta agentes activos y modelos asignados | | /sdd.descubrir | Extrae contexto de una idea vaga | | /sdd.ayuda | Guía completa de todos los comandos |

Especificación

| Comando | Qué hace | |---------|----------| | /sdd.especificar [idea] | Convierte una intención en spec con criterios de aceptación testeables | | /sdd.importar [url] | Importa spec externa (URL o archivo) | | /sdd.aclarar | Resuelve marcas [NECESITA_ACLARACION] de la spec | | /sdd.checklist | Valida calidad formal de la spec |

Planificación e implementación

| Comando | Qué hace | |---------|----------| | /sdd.planificar | Genera plan técnico con arquitectura | | /sdd.planificar aprobar | Aprueba el plan explícitamente | | /sdd.tareas | Desglosa el plan en tareas atómicas con agente asignado | | /sdd.analizar | Auditoría cruzada constitución ↔ spec ↔ plan ↔ tareas (PTC paralelo) | | /sdd.implementar | Ejecuta tareas con agentes especializados (PTC paralelo) | | /sdd.qa | QA en navegador real desde cada Criterio de Aceptación (Playwright) | | /sdd.verificar | Verificación final independiente contra la spec original |

Despliegue

| Comando | Qué hace | |---------|----------| | /sdd.desplegar | Gate de calidad → confirmación → deploy → health check con latencia | | /sdd.canary | Monitoreo post-deploy con rounds de health check | | /sdd.retro | Retrospectiva del ciclo, registra aprendizajes en SNAPSHOT |

Fábrica

| Comando | Qué hace | |---------|----------| | /sdd.crear-app [desc] | Genera app web o CLI desde descripción en lenguaje natural | | /sdd.crear-mcp [desc] | Genera servidor MCP empaquetado como .mcpb instalable |

Producto y dominio

| Comando | Qué hace | |---------|----------| | /sdd.snapshot | Actualiza SNAPSHOT.md con el estado actual del producto | | /sdd.glosario | Gestiona términos del dominio del proyecto | | /sdd.estado | Dashboard de progreso del sprint | | /sdd.release | Versión semántica + CHANGELOG desde specs completadas |

Utilidades

| Comando | Qué hace | |---------|----------| | /sdd.mapear | Indexa estructura, símbolos y dependencias (ahorra 50–65k tokens/sesión) | | /sdd.comprimir | Comprime archivos de memoria (−60 a −70% tokens) |

Modos de output

Todos los comandos que producen reportes aceptan un modificador de audiencia:

/sdd.estado pm          # lenguaje de negocio, sin código
/sdd.verificar arq      # diagramas y trade-offs técnicos
/sdd.analizar dev       # código, diffs, rutas de archivo (por defecto)

Configuración multi-proveedor

FORGE soporta 5 proveedores de modelos. El adaptador providers/model-client.js normaliza la interfaz de llamada y streaming.

Al ejecutar forge setup, se te pide elegir:

Elige tu proveedor de IA:

  [anthropic] Anthropic
  [openai] OpenAI
  [google] Google Gemini
  [grok] Grok (xAI)
  [ollama] Ollama (local)

Luego elige el modelo específico:

Anthropic (recomendado para reasoning)

• Claude Opus 4.8 (más potente, lento)
• Claude Sonnet 4.6 (equilibrio)
• Claude Haiku 4.5 (rápido)

OpenAI

• GPT-4o (más potente)
• GPT-4 Turbo
• GPT-4o Mini (rápido, económico)

Google Gemini

• Gemini 2.0 Flash (rápido)
• Gemini 1.5 Pro (potente)
• Gemini 1.5 Flash

Grok / xAI

• Grok 2 (actual)
• Grok 1 (anterior)

Ollama (local, sin API key)

Requiere Ollama instalado:

ollama pull llama3
ollama pull mistral
ollama serve

Luego en FORGE:

forge setup
# Provider: ollama
# Model: mistral (u otro instalado)

Ventaja: Todo el procesamiento es local. Perfecto para desarrollo y privacidad total.

Agentes especializados

sdd-lite incluye 14 agentes. Cada agente tiene un rol acotado, un modelo recomendado, y trabaja sobre artefactos específicos del flujo SDD.

| Agente | Rol | Modelo recomendado | |--------|-----|--------------------| | product-designer | Diseño de producto: user flow, pantallas, MVP scope | opus | | architecture-designer | Stack, servicios, contratos, decisiones de arquitectura | sonnet | | arquitecto | Decisiones técnicas de alto nivel y ADRs | opus | | disenador-api | Contratos OpenAPI / GraphQL / gRPC | sonnet | | asesor-datos | Esquemas, queries, índices, migraciones | opus | | desarrollador-backend | Lógica de servidor, servicios, APIs | sonnet | | desarrollador-frontend | UI, componentes, estado cliente | sonnet | | operaciones | CI/CD, deploy, infraestructura | sonnet | | tester | Tests unitarios, integración, E2E | sonnet | | revisor | Revisión cruzada contra spec y constitución | opus | | critico | Riesgos, puntos ciegos, devil's advocate | opus | | seguridad | Auditoría de vulnerabilidades | opus | | investigador | Stack existente, deuda técnica, patrones | sonnet | | documentador | Documentación técnica útil | sonnet |

Cambia modelos o desactiva agentes con /sdd.configurar o editando .sdd/sdd.config.yaml.

Skills

17 skills reutilizables que los comandos y agentes invocan internamente:

| Skill | Qué hace | |-------|----------| | descubrir-idea | 5 preguntas de discovery sin jerga técnica | | interpretar-idea | Análisis libre + extracción a IR JSON (confidence 0.0–1.0) | | elegir-direccion | Presenta los 5 design systems y captura la elección | | wireframe-mvp | Genera wireframe HTML navegable por pantalla | | critica-diseno | Evalúa consistencia visual y usabilidad del wireframe | | deteccion-stack | Detecta lenguaje, framework, plataforma de deploy | | gestion-estado | Lee y escribe estado.json con RAG en 3 capas | | validacion-spec | Verifica criterios de calidad de una spec | | enrutador-agentes | Asigna el agente correcto a cada tarea | | verificador-implementacion | Comprueba que el código cumple los criterios de aceptación | | indexador | Genera mapas de estructura, símbolos y dependencias | | compresion-tokens | Reglas de compresión estilo caveman para Markdown | | constitucion-constraint | Aplica DEBE/NUNCA de la constitución como hard constraint | | modo-guiado | Conduce el flujo sin jerga para usuarios no técnicos | | orquestacion-ptc | Patrón PTC: despacha agentes en paralelo, −85% tokens | | anti-ai-slop | Detecta y corrige patrones visuales genéricos de IA | | modo-output | Adapta el formato de salida a pm / arq / dev |

Tests

FORGE usa el runner nativo node:test (sin dependencias externas).

npm test

Cubre:

• Validación de pasos del pipeline
• Integración multi-proveedor (Anthropic, OpenAI, Google, Grok, Ollama)
• Persistencia de estado en .sdd/
• Los 5 design systems (existencia y estructura)
• Generación de wireframe HTML

Estructura del repositorio

sdd-lite/
├── cli/
│   ├── index.js              ← entrypoint `forge` (bin)
│   └── server.js             ← servidor HTTP nativo (puerto 3742)
├── ui/
│   └── app.html.js           ← SPA 6 pantallas como módulo JS
├── providers/
│   └── model-client.js       ← adaptador Anthropic / OpenAI / Ollama
├── pipeline/                 ← definiciones de pasos del pipeline
├── sdd-lite/
│   ├── commands/             ← 30 comandos SDD (Markdown + frontmatter)
│   │   ├── sdd.md            ← hub central (punto de entrada)
│   │   ├── sdd.interpretar.md
│   │   ├── sdd.diseñar.md
│   │   └── ...
│   ├── agents/               ← 14 agentes especializados
│   ├── skills/               ← 17 skills (flat .md + carpetas SKILL.md)
│   └── core/
│       ├── ir.types.ts       ← schema TypeScript del IR
│       ├── ir-to-spec-mapper.ts
│       └── project-memory.ts
├── design-systems/
│   ├── neutral-modern/
│   ├── warm-editorial/
│   ├── bold-brutalist/
│   ├── editorial-minimal/
│   └── vibrant-consumer/
├── craft/
│   ├── typography.md
│   ├── color.md
│   └── accessibility-baseline.md
├── tests/
│   └── forge.test.js         ← 59 tests E2E con node:test nativo
├── instalar.sh               ← instalador macOS/Linux
├── FORGE-STATUS.md           ← progreso y plan de tareas
└── package.json

Cuando sdd-lite se instala en un proyecto, genera esta estructura:

tu-proyecto/
├── .claude/
│   ├── commands/sdd.*.md     ← 30 comandos
│   ├── agents/*.md           ← 14 agentes
│   ├── skills/               ← 17 skills
│   └── hooks/                ← hooks de seguridad
└── .sdd/
    ├── sdd.config.yaml       ← configuración personalizable
    ├── estado.json           ← estado global del flujo
    ├── ir.json               ← IR del producto (FORGE)
    ├── product-design.json   ← diseño del producto (FORGE)
    ├── SNAPSHOT.md
    ├── memoria/constitucion.md
    ├── dominio/glosario.md
    ├── arquitectura/         ← ADRs
    ├── diseño/wireframe-*.html
    └── especificaciones/{ID}/
        ├── spec.md
        ├── plan.md
        ├── tareas.md
        ├── analisis.md
        ├── qa.md
        ├── verificacion.md
        └── .estado-tareas.json

Ahorro de tokens

| Técnica | Ahorro estimado | |---------|----------------| | Mapas estáticos (/sdd.mapear) | −50 a −65k tokens por sesión | | Compresión caveman (/sdd.comprimir) | −60 a −70% en archivos de memoria | | RAG en 3 capas (estado → spec → constitución) | Carga solo lo necesario por fase | | PTC paralelo (orquestacion-ptc) | −70 a −85% en orquestación multi-agente |

Contribuir

El proyecto está diseñado para ser forkeado y personalizado. Todo el plugin son archivos Markdown planos: los comandos, agentes y skills se editan directamente.

Para contribuir mejoras genéricas:

git clone https://github.com/tu-usuario/sdd-lite.git
cd sdd-lite
git checkout -b mi-mejora
# ... edita ...
npm test   # los 59 tests deben seguir en verde
git push origin mi-mejora
# abre un PR contra main

Convenciones de commits usadas en este repo:

[LAYER] [ACTION]: descripción

# Ejemplos:
[FORGE] ADD: web app local completa - servidor HTTP + SPA + multi-proveedor
[INTERPRETER] ADD: ir.types.ts - schema TypeScript del IR
[FOUNDATION] ADD: FORGE-STATUS.md con progreso y plan de tareas

Estado del proyecto

FORGE está en v0.1.0-alpha (rama forge-mvp). El pipeline completo está implementado y testeado. El objetivo es completar V1 en las próximas semanas con:

• Fase 1 INTERPRETER: skill descubrir-idea, skill interpretar-idea, comando sdd.interpretar, validación
• Fase 2 DESIGN SYSTEM: skills de diseño, agentes, los 5 design systems completos
• Fase 3 PIPELINE AUTO: mappers IR → spec, memoria de proyecto, comandos sdd.construir y sdd.exportar
• Fase 4 WEB APP: providers, servidor, SPA completa

Ver el detalle completo en FORGE-STATUS.md.

Licencia

MIT — úsalo, modifícalo, distribúyelo libremente.