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

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

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

Design Systems

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

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)

Inicialización y configuración

Especificación

Planificación e implementación

Despliegue

Fábrica

Producto y dominio

Utilidades

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.

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:

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

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.