sdd-es 2.0.0

package/docs/INICIO-RAPIDO.md

@@ -0,0 +1,116 @@
+# Inicio Rápido — SDD-ES
+
+SDD-ES es un plugin para Claude Code que añade un flujo estructurado para convertir ideas en código verificado. En lugar de pedirle a Claude "implementa X", defines primero qué quieres y por qué, y el sistema coordina agentes especializados para construirlo con trazabilidad completa.
+
+---
+
+## Instalación
+
+Requiere **Node.js >= 18**. El instalador funciona igual en Windows, macOS y Linux.
+
+```bash
+# 1. Ve a tu proyecto
+cd mi-proyecto
+
+# 2. Instala (camino recomendado, multiplataforma)
+npx sdd-es init
+```
+
+**Windows (PowerShell)** — atajo equivalente:
+
+```powershell
+.\instalar.ps1
+```
+
+**macOS / Linux / Git Bash** — atajo equivalente:
+
+```bash
+bash /ruta/a/sdd-es/instalar.sh
+```
+
+El instalador crea la carpeta `.sdd/` en tu proyecto y copia los comandos, agentes, skills y hooks de seguridad al `.claude/` local. Comprueba que todo quedó bien con:
+
+```bash
+npx sdd-es doctor
+```
+
+---
+
+## Primera vez en un proyecto
+
+Abre Claude Code en tu proyecto y ejecuta:
+
+```
+/sdd.constitucion
+```
+
+Claude te hace preguntas sobre tu proyecto (stack, principios, estándares de calidad) y genera `.sdd/memoria/constitucion.md` — la ley del proyecto que todos los agentes respetan.
+
+Solo se hace una vez por proyecto.
+
+---
+
+## Flujo diario
+
+```
+/sdd.especificar [descripción de lo que quieres]
+```
+
+Desde ahí el sistema te guía paso a paso. No necesitas memorizar el resto de comandos — `/sdd` solo te pregunta qué quieres y enruta automáticamente.
+
+---
+
+## Los 4 comandos que más usarás
+
+| Comando | Para qué |
+|---|---|
+| `/sdd` | Punto de entrada — di lo que quieres en lenguaje natural |
+| `/sdd.especificar [idea]` | Convertir una idea en spec con criterios de aceptación |
+| `/sdd.implementar` | Ejecutar las tareas con los agentes especializados |
+| `/sdd.estado` | Ver dashboard del proyecto |
+
+---
+
+## ¿Eres nuevo en programación?
+
+SDD-ES tiene un **perfil guiado** para personas con poca o ninguna experiencia. Durante `/sdd.constitucion` puedes elegirlo (o el sistema lo detecta automáticamente por la forma en que hablas).
+
+En perfil guiado:
+- No ves comandos ni tecnicismos — solo preguntas en lenguaje normal
+- El sistema elige el stack por ti
+- Confirmas con "sí" entre cada paso
+- Al final, Claude publica tu app en internet
+
+**Atajo directo para no-programadores:**
+
+```
+/sdd.crear-app [describe tu idea]
+```
+
+Ver el recorrido completo en [FABRICA.md](FABRICA.md).
+
+---
+
+## Crear una herramienta para Claude
+
+Si quieres que Claude pueda hacer algo nuevo (consultar una API, acceder a tus archivos, etc.):
+
+```
+/sdd.crear-mcp [describe qué hace la herramienta]
+```
+
+Genera un servidor MCP funcional empaquetado como `.mcpb` instalable con una línea.
+
+---
+
+## Si algo sale mal o quieres retomar
+
+```
+/sdd.estado                    # ¿dónde estoy?
+/sdd.implementar continuar     # retomar desde la última tarea
+/sdd.ayuda                     # lista completa de comandos
+```
+
+---
+
+## Ejemplo completo → ver [EJEMPLO-PRACTICA.md](EJEMPLO-PRACTICA.md)

package/docs/MAPAS.md

@@ -0,0 +1,113 @@
+# Mapas del Proyecto — Ahorrar 50-65k tokens por sesión
+
+## El problema
+
+Una sesión típica de SDD-ES (`constitucion → especificar → planificar → implementar → verificar`):
+
+- Claude necesita entender la estructura del proyecto
+- Corre `find . -type f` → 50-100 archivos
+- Lee cada archivo para entender qué hace → ~50k tokens
+- Esto se repite cada sesión
+
+## La solución: Mapas estáticos
+
+En lugar de que Claude lea archivos, consulta 3 archivos Markdown pequeños:
+
+1. **estructura.md** — árbol + 1 línea por archivo
+2. **simbolos.md** — funciones, clases, tipos exportados
+3. **dependencias.md** — quién depende de quién
+
+Total: ~10k tokens. Ahorro: 80-85%.
+
+## Cómo usarlo
+
+```bash
+# Primera vez: genera todos los mapas
+/sdd.mapear
+
+# Después: detecta cambios, actualiza automáticamente
+/sdd.mapear
+
+# Forzar regeneración completa (casi nunca)
+/sdd.mapear regenerar
+
+# Verificar estado sin actualizar
+/sdd.mapear validar
+```
+
+## Dónde van
+
+```
+.sdd/mapa/
+├── estructura.md          (~5KB)
+├── simbolos.md            (~8KB)
+├── dependencias.md        (~3KB)
+├── .estado-mapeo          (timestamp)
+└── .checksums             (md5 de archivos)
+```
+
+## Cómo Claude los usa
+
+Durante `/sdd.planificar`:
+1. Busca si existen mapas
+2. Los lee (rápido, 10k tokens)
+3. Entiende la estructura sin leer código
+4. Si necesita más detalle: entonces corre `/Read archivo.ts`
+
+Result: típicamente **no necesita leer nada** — el mapa le alcanza.
+
+## Actualización automática
+
+- **Hook `despues_implementar`** actualiza mapas después de que ejecutas una tarea
+- **Validación perezosa** — al inicio de comandos SDD, verifica si hay archivos nuevos y actualiza silenciosamente
+- **Backup** — `.estructura.md.backup`, etc.
+
+## Manual vs Auto-descripción
+
+Cada archivo en `estructura.md` tiene una descripción:
+
+```markdown
+src/
+├── auth/
+│   ├── login.service.ts        — Servicio: autenticación local+JWT
+│   │                            ^ puedes editar esto manualmente
+```
+
+Si editas la descripción, la próxima ejecución de `/sdd.mapear` respeta tus cambios.
+
+## Lenguajes soportados
+
+Detección automática: TypeScript, JavaScript, Python, Rust, Go, Java, C#, Ruby, PHP.
+
+Otros lenguajes: edita manualmente el mapa o ejecuta desde proyecto raíz con esos lenguajes presentes.
+
+## Ignorar directorios
+
+Edita `.sdd/.mapeoignore`:
+
+```
+node_modules/
+dist/
+.git/
+vendor/
+__pycache__/
+```
+
+Próxima ejecución los salta.
+
+## Limitaciones honestas
+
+- ❌ Imports dinámicos (`require(variable)`) no se detectan
+- ⚠️ Proyectos >5000 archivos: capa un máximo de 2000 (avisa al usuario)
+- ❌ No sigue tipos a través de funciones (solo detecta firmas)
+
+Son trade-offs aceptables para una solución sin dependencias.
+
+## ROI
+
+Si una sesión típica carga 200k tokens:
+- Sin mapas: ~200k
+- Con mapas: ~140k (30% ahorro)
+- Multiplicado por 20 sesiones/mes: **1.2M tokens ahorrados/mes**
+
+En pesos: ~USD 5 de ahorro al mes por usuario (con Claude Pro).

package/docs/MODELOS.md

@@ -0,0 +1,103 @@
+# Guía de Modelos por Agente
+
+## Tabla maestra de recomendaciones
+
+| Agente | Recomendado | Aceptable | Evitar | Razón principal |
+|--------|-------------|-----------|--------|-----------------|
+| arquitecto | **opus** | sonnet (proyectos pequeños) | haiku | Decisiones difíciles de revertir |
+| disenador-api | **sonnet** | opus (APIs complejas) | haiku | Diseño estructurado pero acotado |
+| asesor-datos | **opus** | sonnet (BD simple) | haiku | Errores de BD son costosos |
+| desarrollador-backend | **sonnet** | opus (lógica compleja), haiku (CRUD simple) | — | Codificación general |
+| desarrollador-frontend | **sonnet** | opus (UI compleja), haiku (componentes simples) | — | Codificación general |
+| operaciones | **sonnet** | haiku (scripts simples), opus (infra crítica) | — | Configuración |
+| tester | **sonnet** | haiku (tests simples) | opus (overkill) | Generación con patrones |
+| revisor | **opus** | sonnet | haiku | Revisión profunda atrapa más bugs |
+| critico | **opus** | sonnet | haiku | Requiere razonamiento abstracto |
+| seguridad | **opus** | — | sonnet, haiku | Auditoría debe ser exhaustiva |
+| documentador | **sonnet** | haiku | opus (overkill) | Generación estructurada |
+
+## Filosofía
+
+**Usa el modelo más pequeño que resuelva el problema bien.** Subir de tier solo si el agente falla repetidamente.
+
+### ¿Cuándo subir a opus?
+
+- El agente da respuestas inconsistentes
+- La tarea requiere considerar múltiples restricciones simultáneamente
+- El costo de un error es alto (BD, seguridad, arquitectura)
+- El razonamiento requiere abstracción profunda
+
+### ¿Cuándo bajar a haiku?
+
+- La tarea es muy estructurada (rellenar plantilla)
+- El agente funciona bien con sonnet y quieres ahorrar
+- Tareas en lote (muchas similares)
+
+## Combinaciones efectivas
+
+### Combinación "alta calidad"
+```yaml
+# Diseño con opus, implementación con sonnet, calidad con opus
+arquitecto: opus
+disenador-api: sonnet
+asesor-datos: opus
+desarrollador-backend: sonnet
+desarrollador-frontend: sonnet
+operaciones: sonnet
+tester: sonnet
+revisor: opus
+critico: opus
+seguridad: opus
+```
+
+### Combinación "rápida y económica" (para MVPs)
+```yaml
+arquitecto: sonnet
+disenador-api: sonnet
+asesor-datos: sonnet
+desarrollador-backend: sonnet
+desarrollador-frontend: sonnet
+operaciones: haiku
+tester: haiku
+revisor: sonnet
+critico: sonnet
+seguridad: sonnet
+```
+
+### Combinación "máxima calidad" (enterprise)
+```yaml
+# Todo opus en agentes de decisión, sonnet en implementación rápida
+arquitecto: opus
+disenador-api: opus
+asesor-datos: opus
+desarrollador-backend: sonnet
+desarrollador-frontend: sonnet
+operaciones: opus  # infra crítica
+tester: sonnet
+revisor: opus
+critico: opus
+seguridad: opus
+documentador: sonnet
+```
+
+## Cambiar modelos
+
+```
+/sdd.configurar modelos
+```
+
+O edita `.sdd/sdd.config.yaml`:
+
+```yaml
+agentes:
+  arquitecto:
+    modelo: opus  # cambiar aquí
+```
+
+Los cambios aplican a la próxima invocación.
+
+## Notas
+
+- Esta guía se basa en la familia Claude (opus/sonnet/haiku) al momento de escribir esto.
+- Si Anthropic publica un nuevo modelo, actualiza esta tabla en tu proyecto.
+- Otros proveedores: si usas Claude Code con otros modelos, ajusta las recomendaciones.

package/docs/PERSONALIZACION.md

@@ -0,0 +1,152 @@
+# Guía Exhaustiva de Personalización
+
+SDD-ES está diseñado para ser **completamente personalizable**. Cada archivo es Markdown plano que puedes editar.
+
+## Niveles de personalización
+
+### Nivel 1: Configuración (`.sdd/sdd.config.yaml`)
+
+Cambios sin tocar lógica del plugin.
+
+- Activar/desactivar agentes
+- Cambiar modelos por agente
+- Cambiar rutas de archivos
+- Ajustar umbrales de calidad
+- Modificar comportamientos (numeración de specs, ruta rápida, etc.)
+- Definir protecciones (archivos no tocar, comandos prohibidos)
+
+### Nivel 2: Plantillas (`plantillas/*.md`)
+
+Cambios en el formato de los artefactos generados.
+
+- Modificar secciones de la spec
+- Cambiar el formato del plan
+- Personalizar el ADR
+- Añadir/quitar secciones del snapshot
+
+Las plantillas se leen al generar cada artefacto. Cambia un campo aquí y todos los artefactos futuros lo respetarán.
+
+### Nivel 3: Comandos (`commands/sdd.*.md`)
+
+Cambios en el comportamiento del flujo.
+
+- Modificar el orden de pasos en un comando
+- Cambiar las preguntas que se hacen
+- Ajustar criterios de detección automática
+- Personalizar mensajes y outputs
+
+### Nivel 4: Agentes (`agents/*.md`)
+
+Cambios en la personalidad y reglas de los expertos.
+
+- Añadir restricciones específicas del proyecto
+- Cambiar el formato de salida
+- Definir conocimiento de dominio
+- Ajustar criterios de aceptación de su trabajo
+
+### Nivel 5: Hooks (`.sdd/hooks/*.sh`)
+
+Integración con tus sistemas externos.
+
+- Git/GitLab/GitHub workflows
+- Notificaciones (Slack, Teams, Discord)
+- Triggers de CI/CD
+- Linters/formatters automáticos
+- Backups
+- Sync con sistemas de tickets (Jira, Linear, etc.)
+
+## Casos de personalización comunes
+
+### Caso 1: Agregar una sección obligatoria a las specs
+
+Edita `plantillas/especificacion.md` y añade tu sección. Luego edita `commands/sdd.especificar.md` para mencionarla en el PASO 4.
+
+Opcional: edita `commands/sdd.checklist.md` para añadir un check sobre esa sección.
+
+### Caso 2: Cambiar el formato de los ADRs
+
+Edita `plantillas/decision-arquitectura.md`.
+
+### Caso 3: Integrar con tu workflow de Git (sin que SDD lo haga directamente)
+
+Crea `.sdd/hooks/despues_especificar.sh`:
+```bash
+#!/bin/bash
+# Crear branch automáticamente al crear una spec
+SPEC_ID="$1"
+git checkout -b "spec/${SPEC_ID}"
+echo "✅ Branch creada: spec/${SPEC_ID}"
+```
+
+Y `.sdd/hooks/despues_implementar.sh`:
+```bash
+#!/bin/bash
+# Hacer commit y abrir PR
+SPEC_ID=$(grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json | cut -d'"' -f4)
+git add -A
+git commit -m "feat(${SPEC_ID}): implementación completada"
+gh pr create --title "${SPEC_ID}" --body "$(cat .sdd/especificaciones/${SPEC_ID}/spec.md | head -20)"
+```
+
+### Caso 4: Notificar al equipo cuando se aprueba un plan
+
+Crea `.sdd/hooks/despues_planificar.sh`:
+```bash
+#!/bin/bash
+SPEC_ID=$(grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json | cut -d'"' -f4)
+TITULO=$(grep "^titulo:" ".sdd/especificaciones/${SPEC_ID}/spec.md" | cut -d'"' -f2)
+
+curl -X POST https://hooks.slack.com/services/XXX/YYY/ZZZ \
+  -H 'Content-type: application/json' \
+  --data "{\"text\":\"📋 Plan aprobado: ${TITULO}\"}"
+```
+
+### Caso 5: Añadir un agente nuevo (ej: "mobile-developer")
+
+1. Crea `agents/desarrollador-mobile.md` con el frontmatter y el rol
+2. Añádelo a `.claude-plugin/plugin.json` en `agents:`
+3. Añade entrada en `.sdd/sdd.config.yaml`:
+   ```yaml
+   agentes:
+     desarrollador-mobile:
+       activo: true
+       modelo: sonnet
+       descripcion: "Desarrollo de apps móviles."
+   ```
+4. Edita `skills/enrutador-agentes.md` para incluir reglas de cuándo invocarlo
+5. (Opcional) Edita `commands/sdd.tareas.md` para asignarle tareas específicas
+
+### Caso 6: Soportar otro idioma además de español
+
+Aunque SDD-ES está en español, puedes:
+- Duplicar los archivos `commands/sdd.*.md` con sufijo `.en.md` y traducirlos
+- Mantener variables como `.sdd/idioma` y leer condicionalmente
+- Más simple: forkea el repo y traduce todo
+
+### Caso 7: Bloquear ciertos archivos
+
+En `.sdd/sdd.config.yaml`:
+```yaml
+protecciones:
+  no_tocar_archivos:
+    - ".env*"
+    - "src/legacy/**"           ← añade tus rutas
+    - "vendor/**"
+    - "secrets/**"
+```
+
+### Caso 8: Numeración secuencial en lugar de fecha
+
+En `.sdd/sdd.config.yaml`:
+```yaml
+comportamiento:
+  numeracion_especificaciones: "secuencial"  # 001-, 002-, ...
+  # o "ambos": 2026-06-08-001-feature-x
+```
+
+## Filosofía de personalización
+
+- **Empieza simple**: usa los defaults, personaliza solo cuando los necesites
+- **Documenta tus cambios**: si cambias una plantilla, deja un comentario explicando por qué
+- **No olvides el equipo**: si trabajas en equipo, commitea las personalizaciones
+- **Versiona la constitución**: cuando cambias principios, sube versión MAYOR/MENOR/PARCHE

package/instalar.ps1

@@ -0,0 +1,39 @@
+# SDD-ES — Atajo de instalación para Windows (PowerShell).
+#
+# Delega en el CLI Node multiplataforma (cli\index.js), que es la fuente
+# de verdad única de la lógica de instalación. Si no hay Node, avisa.
+#
+# Uso:
+#   .\instalar.ps1            Instala en el proyecto actual
+#   .\instalar.ps1 -Global    Instala para todos tus proyectos ($HOME\.claude)
+#
+# El camino canónico recomendado es:  npx sdd-es init [--global]
+#
+# Si PowerShell bloquea el script por la política de ejecución, corre:
+#   powershell -ExecutionPolicy Bypass -File .\instalar.ps1
+
+param(
+    [switch]$Global
+)
+
+$ErrorActionPreference = "Stop"
+$PluginDir = $PSScriptRoot
+
+# Verificar Node
+$node = Get-Command node -ErrorAction SilentlyContinue
+if ($null -eq $node) {
+    Write-Host "✗ Node.js no está instalado." -ForegroundColor Red
+    Write-Host "  SDD-ES necesita Node >=18 para instalarse."
+    Write-Host "  Instala Node desde https://nodejs.org y reintenta."
+    exit 1
+}
+
+# Construir argumentos para el CLI
+$cliArgs = @("init")
+if ($Global) {
+    $cliArgs += "--global"
+}
+
+# Delegar al CLI Node (misma lógica que instalar.sh y npx sdd-es)
+& node (Join-Path $PluginDir "cli\index.js") @cliArgs
+exit $LASTEXITCODE

package/instalar.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# SDD-ES — Atajo de instalación para Unix (macOS / Linux / Git Bash).
+#
+# Delega en el CLI Node multiplataforma (cli/index.js), que es la fuente
+# de verdad única de la lógica de instalación. Si no hay Node, avisa.
+#
+# Uso: bash instalar.sh [--global]
+#   El camino canónico recomendado es:  npx sdd-es init [--global]
+
+set -e
+
+PLUGIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if ! command -v node &> /dev/null; then
+  echo "✗ Node.js no está instalado." >&2
+  echo "  SDD-ES necesita Node >=18 para instalarse." >&2
+  echo "  Instala Node desde https://nodejs.org y reintenta." >&2
+  exit 1
+fi
+
+# Pasa todos los argumentos (p. ej. --global) al subcomando init del CLI
+exec node "${PLUGIN_DIR}/cli/index.js" init "$@"

package/mcp-figma/README.md

@@ -0,0 +1,158 @@
+# sdd-figma-mcp
+
+MCP server local para integración de Figma con proyectos que usan SDD-ES. Lo usa el agente `desarrollador-frontend` para analizar el sistema de diseño del proyecto, traer componentes de Figma y generar código adaptado — sin romper lo que ya existe.
+
+## Qué hace
+
+| Herramienta | Qué resuelve |
+|---|---|
+| `analizar_sistema_diseño` | Lee tokens, colores, tipografía y componentes del proyecto local |
+| `evaluar_ui_existente` | Score 0-100 + problemas + sugerencias de mejora |
+| `conectar_figma` | Verifica PAT y metadata del archivo |
+| `listar_componentes` | Lista componentes publicados en el archivo Figma |
+| `traer_componente` | Detalle completo de un nodo: estructura, fills, texto, dimensiones |
+| `mapear_estilos` | Cruza colores/tipografía de Figma con tokens del proyecto |
+| `generar_componente` | Código React/Vue adaptado al sistema de diseño local |
+| `sugerir_mejoras` | Lista priorizada de mejoras al design system |
+
+## Instalación
+
+### 1. Sin dependencias — listo para ejecutar
+
+No hay `npm install`. El servidor usa exclusivamente módulos built-in de Node.js (`readline`, `fs`, `path`) y `fetch` nativo (disponible desde Node 18). El `package.json` es solo un descriptor — no instala nada.
+
+### 2. Obtener el Personal Access Token de Figma
+
+1. Abre Figma → Menú de usuario (esquina superior derecha) → **Settings**
+2. Pestaña **Security** → **Personal access tokens** → **Generate new token**
+3. Dale un nombre (ej. `sdd-figma-mcp`) y copia el token
+
+### 3. Definir FIGMA_PAT como variable de entorno del sistema
+
+El MCP lee el token desde `process.env.FIGMA_PAT` — **no está hardcodeado en ningún archivo de configuración** para evitar que quede en el repositorio.
+
+Claude Code hereda las variables de entorno de la sesión donde se lanza, así que basta con definirla una vez en el sistema:
+
+**Windows (PowerShell, permanente para el usuario):**
+```powershell
+[System.Environment]::SetEnvironmentVariable("FIGMA_PAT", "tu-token-aqui", "User")
+# Cierra y vuelve a abrir la terminal para que tome efecto
+```
+
+**Windows (solo sesión actual):**
+```powershell
+$env:FIGMA_PAT = "tu-token-aqui"
+```
+
+**macOS / Linux (permanente):**
+```bash
+echo 'export FIGMA_PAT="tu-token-aqui"' >> ~/.zshrc   # o ~/.bashrc
+source ~/.zshrc
+```
+
+> Si el proyecto tiene un `.env` que Claude Code carga automáticamente, también puedes agregar `FIGMA_PAT=tu-token` ahí — el proceso Node lo hereda igual.
+
+### 4. Registrar el MCP en Claude Code
+
+Agrega esto a tu `.claude/settings.json` (o `~/.claude/settings.json` para uso global):
+
+```json
+{
+  "mcpServers": {
+    "sdd-figma": {
+      "command": "node",
+      "args": ["/ruta/absoluta/al/sdd-lite/mcp-figma/src/index.js"]
+    }
+  }
+}
+```
+
+No hay campo `env` — el servidor hereda `FIGMA_PAT` directamente del entorno del sistema (paso 3). Así el token nunca queda registrado en ningún archivo de configuración del repositorio.
+
+> Reemplaza `/ruta/absoluta/al/sdd-lite` con la ruta real donde instalaste SDD-ES.
+> En Windows usa barras invertidas dobles: `"c:\\\\Users\\\\usuario\\\\sdd-lite\\\\mcp-figma\\\\src\\\\index.js"`
+
+### 5. Verificar
+
+Reinicia Claude Code y ejecuta en cualquier proyecto frontend:
+
+```
+analizar_sistema_diseño({ project_root: "." })
+```
+
+Deberías ver el perfil del sistema de diseño del proyecto.
+
+## Cómo encontrar el file_key de Figma
+
+La URL de Figma tiene este formato:
+
+```
+https://www.figma.com/file/ABCDEF123456/nombre-del-archivo?node-id=0:1
+                           ^^^^^^^^^^^^
+                           este es el file_key
+```
+
+## Cómo encontrar el node_id
+
+1. Selecciona el frame o componente en Figma
+2. La URL cambia a: `?node-id=123:456`
+3. Ese valor (`123:456` o en formato `123-456`) es el `node_id`
+
+## Flujo típico de uso
+
+```
+# 1. Analiza lo que ya tiene el proyecto
+analizar_sistema_diseño({ project_root: "/mi/proyecto" })
+
+# 2. Conecta con el archivo de Figma
+conectar_figma({ file_key: "ABCDEF123456" })
+
+# 3. Lista los componentes disponibles
+listar_componentes({ file_key: "ABCDEF123456", filter: "Button" })
+
+# 4. Trae el componente que quieres implementar
+traer_componente({ file_key: "ABCDEF123456", node_id: "123:456" })
+
+# 5. Verifica que los estilos tienen equivalente en el proyecto
+mapear_estilos({ file_key: "ABCDEF123456", node_id: "123:456", project_root: "/mi/proyecto" })
+
+# 6. Genera el código adaptado
+generar_componente({ file_key: "ABCDEF123456", node_id: "123:456", project_root: "/mi/proyecto" })
+```
+
+## Stacks soportados
+
+| Framework | CSS | Estado |
+|---|---|---|
+| React / Next.js | Tailwind CSS | ✅ Completo |
+| React / Next.js | CSS Modules | ✅ Completo |
+| Vue 3 | Tailwind / Scoped CSS | ✅ Completo |
+| React / Next.js | styled-components | ⚠️ Parcial (genera CSS Module) |
+| Angular | Cualquiera | ⚠️ Genera React, ajusta manualmente |
+| Svelte | Cualquiera | 🔜 En roadmap |
+
+## Variables de entorno
+
+| Variable | Requerida | Descripción |
+|---|---|---|
+| `FIGMA_PAT` | Sí | Personal Access Token de Figma |
+
+## Estructura del proyecto
+
+```
+mcp-figma/
+├── src/
+│   ├── index.js                  ← Servidor MCP + definición de tools
+│   ├── mcp.js                    ← Protocolo JSON-RPC 2.0 sobre stdio (sin deps)
+│   ├── figma-client.js           ← Cliente HTTP de la API de Figma
+│   ├── design-system-analyzer.js ← Análisis del sistema de diseño local
+│   ├── style-mapper.js           ← Mapeo de estilos Figma ↔ tokens locales
+│   └── component-generator.js   ← Generación de código por framework
+└── package.json                  ← Cero dependencias — solo descriptor
+```
+
+## Limitaciones conocidas
+
+- La detección de tokens en Tailwind usa análisis estático de texto (no ejecuta el módulo), por lo que configs muy dinámicas pueden no detectarse completamente
+- La generación de componentes es un punto de partida — siempre revisa accesibilidad, props faltantes y manejo de estado
+- La API de Figma Variables (tokens del sistema de diseño de Figma) requiere plan Professional o superior