openprompt-lang 0.5.0 → 0.5.1

package/README.md

@@ -8,6 +8,39 @@ openPrompt-Lang --version
 
 ---
 
+## Herramientas del Framework
+
+openPrompt-Lang no es un solo comando. Es un conjunto de **herramientas** que trabajan juntas para que tú y la IA hablen el mismo idioma. Cada herramienta resuelve un problema distinto. Aquí están explicadas de forma sencilla, sin técnicismos.
+
+### Anotaciones
+Es el idioma que usas para marcar tu código. Le dices a la IA cosas como "esto es un hook", "esto recibe un email y devuelve un usuario", "esto no puede pasar de 80 líneas". No es un comando, es una forma de escribir que la IA entiende.
+
+### Inicialización
+Con esta herramienta preparas el proyecto desde cero o adaptas uno que ya tengas. Crea carpetas, archivos de configuración, y deja todo listo para que tú y la IA empiecen a trabajar sin pensar en la estructura.
+
+### Validación
+Es el control de calidad. Antes de guardar cambios, esta herramienta revisa que todo esté bien: que las anotaciones tengan sentido, que no falten archivos, que el proyecto esté sano. Si algo está mal, te avisa antes de que sea un problema.
+
+### Trazabilidad (Work Context)
+Lleva un diario de todo lo que haces en cada sesión de trabajo. Registra qué tarea empezaste, qué planes hiciste, qué archivos tocaste, qué errores corregiste. Al final, te deja un reporte de lo que pasó y aprendizajes para futuros proyectos. Sirve para que ni tú ni la IA pierdan el hilo.
+
+### Memoria Semántica (Learning)
+Guarda conceptos visuales o técnicos para que la IA los entienda como tú los entiendes. Por ejemplo, si dices "moderno", la IA sabe que puedes referirte a un diseño minimalista, a uno oscuro con neón, o a uno con cristal difuminado. En lugar de adivinar, la herramienta te muestra las opciones y tú eliges. Así la IA no interpreta, sino que aprende cómo hablas.
+
+### Plantillas y Patrones
+Cuando necesitas un componente que ya existe en algún lado (un botón, un formulario, un hook de autenticación), esta herramienta lo busca y te enseña cómo está hecho. Aprendes del patrón sin tener que copiar y pegar ciegamente.
+
+### Generación con IA
+Le describes en palabras lo que necesitas y la herramienta genera el código. No es magia: usa las anotaciones, los patrones que ya existen y las reglas del proyecto para que el resultado sea coherente con el resto.
+
+### Extracción de Componentes
+Si ya tienes un proyecto funcionando y hay piezas que se repiten, esta herramienta las detecta y las convierte en plantillas reutilizables. Así no reinventas lo que ya funciona.
+
+### Integración con Editores
+Conecta todo esto con las herramientas que ya usas: OpenCode, VS Code, Cursor. Un solo comando deja todo configurado para que la IA trabaje directamente desde tu editor.
+
+---
+
 ## Índice
 
 - [Instalación](#instalación)
@@ -36,6 +69,15 @@ openPrompt-Lang --version
 - [Scripts descriptivos](#scripts-descriptivos)
 - [Estructura del proyecto](#estructura-del-proyecto)
 - [Sistema de componentes](#sistema-de-componentes)
+- [Work Context System](#work-context-system)
+  - [Comandos work-context](#comandos-work-context)
+  - [Flujo de trabajo obligatorio](#flujo-de-trabajo-obligatorio)
+  - [Referencias web seguras](#referencias-web-seguras)
+- [Memoria Semántica](#memoria-semántica)
+  - [Comandos learning](#comandos-learning)
+  - [Estructura de conceptos](#estructura-de-conceptos)
+  - [Variantes](#variantes)
+  - [Reglas de precisión](#reglas-de-precisión)
 - [VS Code Extension](#vs-code-extension)
 - [Versionado (SemVer)](#versionado-semver)
 - [Documentación](#documentación)
@@ -492,7 +534,7 @@ openPrompt-Lang component list --validated
 | `openPrompt-Lang ai-providers` | Lista proveedores IA disponibles y su estado |
 | `openPrompt-Lang extract [sourceDir]` | Analiza proyecto y extrae componentes reutilizables como templates |
 | `openPrompt-Lang analyze [sourceDir]` | Analiza estructura, dependencias y salud del proyecto |
-| `openPrompt-Lang integrate [--all]` | Configura Opencode, Cursor y VS Code para el proyecto |
+| `openPrompt-Lang integrate [--all]` | Configura Opencode, Cursor, VS Code y Antigravity para el proyecto |
 | `openPrompt-Lang qa-gen` | Genera tests desde errores aprendidos (@learn-error) |
 | `openPrompt-Lang qa-learn` | Parsea @learn-error de un archivo al módulo de lenguaje |
 | `openPrompt-Lang lang list` | Lista lenguajes disponibles |
@@ -506,6 +548,21 @@ openPrompt-Lang component list --validated
 | `openPrompt-Lang component add <nombre>` | Agrega componente de la biblioteca al proyecto |
 | `openPrompt-Lang component manifest` | Muestra el manifiesto de la biblioteca |
 | `openPrompt-Lang mcp` | Inicia servidor MCP para integración con Opencode |
+| `openPrompt-Lang work-context init` | Inicializa sistema work-context en proyecto existente |
+| `openPrompt-Lang work-context start <desc>` | Inicia sesión de trabajo con descripción |
+| `openPrompt-Lang work-context status` | Muestra estado actual del contexto de trabajo |
+| `openPrompt-Lang work-context log <msg>` | Añade entrada a la bitácora cronológica |
+| `openPrompt-Lang work-context plan new <name>` | Crea plan de trabajo (--task para búsqueda de conocimiento) |
+| `openPrompt-Lang work-context plan check [name]` | Verifica plan existente contra conocimiento actual |
+| `openPrompt-Lang work-context close` | Cierra sesión activa y genera reporte |
+| `openPrompt-Lang work-context learn` | Extrae aprendizajes a LEARNINGS.md |
+| `openPrompt-Lang work-context report` | Genera reporte completo del contexto |
+| `openPrompt-Lang work-context check` | Verifica consistencia del work-context |
+| `openPrompt-Lang learning init` | Inicializa sistema de memoria semántica |
+| `openPrompt-Lang learning search <query>` | Busca conceptos por nombre o categoría |
+| `openPrompt-Lang learning add <name> --category <cat>` | Crea nuevo concepto con template |
+| `openPrompt-Lang learning map` | Genera mapa visual Mermaid del grafo de conceptos |
+| `openPrompt-Lang learning import-personal <file.md>` | Importa documento de vocabulario personal como conceptos en la categoría `personal/` |
 
 ---
 
@@ -528,6 +585,13 @@ mi-app-web/
 ├── package.json             # Scripts descriptivos (dev:start, test:unit, validate:all...)
 ├── prompt-lang.json         # Configuración del framework
 ├── AGENTS.md                # Contexto para la IA
+├── .opencode/
+│   └── work-context/        # Sistema de trazabilidad (creado automáticamente)
+│       ├── CONTEXT.md       # Índice maestro
+│       ├── SESSION.json     # Estado de sesión
+│       ├── LOG.json         # Bitácora
+│       ├── LEARNINGS.md     # Aprendizajes
+│       └── REFERENCES.md    # Referencias web seguras
 └── .gitignore
 ```
 
@@ -582,9 +646,10 @@ cd mi-proyecto-ya-iniciado
 openPrompt-Lang init --existing
 ```
 
-Esto detecta automáticamente el stack y crea solo:
+Esto detecta automáticamente el stack y crea:
 - `prompt-lang.json` (config con stack detectado)
 - `AGENTS.md` (contexto para IA con tecnologías reales)
+- `.opencode/work-context/` (sistema de trazabilidad obligatorio)
 
 Te preguntará:
 - ¿Agregar scripts descriptivos al `package.json`? (merge sin romper)
@@ -748,7 +813,23 @@ openPrompt-Lang/
 ├── .opencode/                  ← Configuración para Opencode
 │   ├── opencode.json           ← MCP server + skills + default_agent
 │   ├── agent/openPrompt.md     ← Agente con 4 workflows + Default Workflow
-│   └── skills/openPrompt/SKILL.md ← Skill auto-detectable con MCP tools
+│   ├── skills/openPrompt/SKILL.md ← Skill auto-detectable con MCP tools
+│   └── work-context/           ← Sistema de trazabilidad obligatorio
+│       ├── CONTEXT.md          ← Índice maestro para la IA
+│       ├── SESSION.json        ← Estado de sesión actual
+│       ├── LOG.json            ← Bitácora de acciones
+│       ├── LEARNINGS.md        ← Aprendizajes acumulados
+│       ├── REFERENCES.md       ← Referencias web (uso seguro)
+│       ├── PLANS/              ← Planes de trabajo
+│       └── REPORTS/            ← Reportes de sesiones cerradas
+│   └── learning/               ← Memoria semántica (conceptos, variantes, relaciones)
+│       ├── index.md            ← Puerta de entrada para la IA
+│       ├── glossary.md         ← Glosario alfabético
+│       ├── concepts/           ← Conceptos por categoría (visual/, ui/, backend/, ...)
+│       ├── relations/          ← Grafo (graph.json) y mapa visual (map.md)
+│       ├── clarifications/     ← Historial de aclaraciones
+│       ├── decisions/          ← Decisiones validadas
+│       └── examples/           ← Ejemplos de componentes y referencias
 ├── tests/
 │   ├── annotations.test.js     ← ~45 tests de parser y validador
 │   ├── config.test.js          ← Tests de deep merge
@@ -805,6 +886,12 @@ openPrompt-Lang/
 | `docs/PROMPT_AI_CONTEXT.md` | Prompt pre-hecho para copiar-pegar a Gemini/Claude/ChatGPT |
 | `vscode-extension/` | Extensión VS Code: syntax highlighting y snippets para anotaciones |
 | `schemas/prompt-lang.json` | JSON Schema para validar `prompt-lang.json` |
+| `.opencode/work-context/CONTEXT.md` | Índice maestro del sistema work-context (lectura obligatoria para la IA) |
+| `.opencode/work-context/LEARNINGS.md` | Aprendizajes acumulados del proyecto |
+| `.opencode/work-context/REFERENCES.md` | Referencias web con checklist de uso seguro |
+| `.opencode/learning/index.md` | Puerta de entrada de la memoria semántica (lectura obligatoria para la IA) |
+| `.opencode/learning/glossary.md` | Glosario semántico alfabético |
+| `.opencode/learning/relations/graph.json` | Grafo de conceptos y relaciones |
 
 ---
 
@@ -969,6 +1056,210 @@ openPrompt-Lang init --existing
 
 ---
 
+## Work Context System
+
+El **Work Context** es un sistema integrado de trazabilidad obligatoria que registra sesiones de trabajo, planes, acciones, aprendizajes y referencias externas. Se inicializa automáticamente con `init` en proyectos nuevos y existentes.
+
+### Estructura
+
+```
+.opencode/work-context/
+├── CONTEXT.md           # Índice maestro (lo primero que lee la IA)
+├── SESSION.json         # Estado actual de la sesión (JSON validable)
+├── LOG.json             # Bitácora cronológica de acciones
+├── LEARNINGS.md         # Aprendizajes acumulados del proyecto
+├── REFERENCES.md        # Referencias web (con checklist de uso seguro)
+├── PLANS/               # Planes de trabajo guardados por sesión
+└── REPORTS/             # Reportes generados al cerrar sesiones
+```
+
+### Comandos work-context
+
+| Comando | Descripción |
+|---------|-------------|
+| `openPrompt-Lang work-context init` | Inicializa el sistema en un proyecto existente. Crea estructura `.opencode/work-context/`, `SESSION.json`, `LOG.json`, `LEARNINGS.md`, `REFERENCES.md`, directorios `PLANS/` y `REPORTS/` |
+| `openPrompt-Lang work-context start <desc>` | Inicia una nueva sesión de trabajo. Genera ID único (`ses_YYMMDD_NNN`), timestamp ISO, detecta rama git automáticamente. Requiere descripción de la tarea |
+| `openPrompt-Lang work-context status` | Muestra el estado actual: ID de sesión, estado (activa/pausada/cerrada), tarea, tipo, prioridad, etapa del ciclo, métricas (archivos cambiados, planes creados, errores corregidos, aprendizajes), últimas 5 entradas del log |
+| `openPrompt-Lang work-context log <msg>` | Añade entrada a la bitácora cronológica con timestamp, tipo de acción y resultado (ok/error/warn). Consultable con `status` o `report` |
+| `openPrompt-Lang work-context plan new <name>` | Crea un plan de trabajo en `PLANS/` con template estructurado: fecha, sesión, rama, objetivo, checklist de tareas, validación contra anotaciones, aprendizaje esperado. Usa `--task "<desc>"` para generar un plan informado con búsqueda automática en learning concepts, knowledge chapters, learnings y glosario |
+| `openPrompt-Lang work-context plan check [name]` | Verifica un plan existente re-consultando todas las fuentes de conocimiento y reportando conceptos nuevos no cubiertos en el plan original |
+| `openPrompt-Lang work-context close` | Cierra la sesión activa: cambia estado a `closed`, genera reporte en `REPORTS/` con métricas de la sesión (duración, archivos, planes, errores). No se puede iniciar otra sesión sin cerrar la actual |
+| `openPrompt-Lang work-context learn` | Extrae aprendizajes de la sesión cerrada y los acumula en `LEARNINGS.md` con fecha, categoría, problema, solución y plan relacionado |
+| `openPrompt-Lang work-context report` | Genera reporte completo: período, duración total, número de entradas, errores, métricas, historial cronológico completo con referencias a planes |
+| `openPrompt-Lang work-context check` | Verifica consistencia del work-context: valida que `SESSION.json` exista y tenga estructura correcta, detecta sesiones activas olvidadas (>24h), confirma que los planes referenciados existen en disco, valida que `LOG.json` sea un array válido |
+| `validate --work-context` | Incluye la verificación de work-context dentro del pipeline de validación estándar |
+
+### Flujo de trabajo obligatorio
+
+La IA debe seguir este ciclo en **cada sesión de trabajo**:
+
+```
+1. CONTEXT.md + SESSION.json  → restaurar estado o iniciar nuevo
+2. ANALYZE request            → clasificar tipo de tarea
+3. PLAN → `work-context plan new <name> --task "<desc>"` → PLANS/, log en LOG
+4. VALIDATE plan              → contra @kind, @contract, @limit
+5. IMPLEMENT                  → codificar, log cada acción
+6. VALIDATE código            → validate + validate --work-context
+7. INTEGRATE                  → actualizar AGENTS.md si toca
+8. LEARN + REFERENCES.md      → checklist de referencias seguras
+9. CLOSE                      → reporte, métricas finales
+```
+
+Cada paso registra su acción en `LOG.json` automáticamente.
+
+### Referencias web seguras
+
+Al usar una referencia web externa, la IA ejecuta este checklist **antes de implementar**:
+
+```
+CHECKLIST (obligatorio):
+□ ¿Es un principio abstracto, no copia de pantalla?
+□ ¿La identidad visual del proyecto sigue siendo propia?
+□ ¿Se evitó copiar assets, textos o estructura exacta?
+□ ¿La referencia resolvió un problema puntual?
+□ ¿El resultado final no parece un clon reconocible?
+```
+
+Si algún check falla → refactorizar antes de continuar. La fuente y el patrón extraído se registran en `REFERENCES.md` con el formato:
+
+```markdown
+### Ref-XXX — [Nombre]
+- URL, fecha, problema resuelto
+- Patrón extraído (principio abstracto)
+- Reinterpretación (cómo se adaptó)
+- Checklist completado
+```
+
+---
+
+## Memoria Semántica
+
+El sistema de **memoria semántica** guarda conceptos, variantes y relaciones para traducir lenguaje vago del usuario en decisiones concretas de diseño e implementación. Funciona como una red de conocimiento navegable que la IA consulta obligatoriamente antes de planificar.
+
+Cuando el usuario dice "quiero un diseño moderno y atractivo", la IA busca en la memoria semántica, muestra variantes disponibles, pide confirmación, y aplica los tokens de diseño correspondientes.
+
+### Estructura
+
+```
+.opencode/learning/
+├── index.md                 # Puerta de entrada + instrucciones para la IA
+├── glossary.md              # Glosario plano alfabético
+├── concepts/
+│   ├── personal/            # Vocabulario personal del usuario (bonito, fudoshin, etc.)
+│   │   ├── bonito/concept.md
+│   │   ├── fudoshin/concept.md
+│   │   └── ...               # +27 términos personales
+│   ├── visual/              # Conceptos visuales (moderno, elegante, femenino, etc.)
+│   │   └── moderno/
+│   │       ├── concept.md       # Ficha madre del concepto
+│   │       ├── minimalista.md   # Variante: minimalista
+│   │       └── dark-neon.md     # Variante: dark-neon
+│   ├── ui/                  # Patrones de interfaz (card, hero, sidebar, etc.)
+│   ├── backend/             # Conceptos de backend (auth, api, storage, etc.)
+│   ├── product/             # Conceptos de producto (onboarding, checkout, etc.)
+│   └── ai/                  # Conceptos de IA (generación, validación, etc.)
+├── relations/
+│   ├── graph.json           # Grafo machine-readable (nodos + aristas)
+│   └── map.md               # Mapa visual generado por CLI (Mermaid)
+├── clarifications/
+│   └── log.json             # Historial de preguntas de aclaración
+├── decisions/               # Decisiones validadas con el usuario
+└── examples/
+    ├── components/          # Componentes que materializan conceptos
+    └── references/          # Referencias externas seguras
+```
+
+### Comandos learning
+
+| Comando | Descripción |
+|---------|-------------|
+| `openPrompt-Lang learning init` | Inicializa la memoria semántica en el proyecto. Crea toda la estructura de directorios, `index.md`, `glossary.md`, `graph.json`, `map.md` y `clarifications/log.json` |
+| `openPrompt-Lang learning search <query>` | Busca conceptos por nombre. Soporta filtro por categoría con `--category visual`. Busca también dentro del contenido de los archivos `concept.md` si el nombre no coincide exactamente. Muestra ruta y variantes disponibles |
+| `openPrompt-Lang learning add <nombre> [--category <cat>]` | Crea un nuevo concepto con template validado. Genera `concept.md`, actualiza `graph.json` con el nuevo nodo y añade entrada al `glossary.md`. Categorías disponibles: `personal`, `visual`, `ui`, `backend`, `product`, `ai` (default: `visual`) |
+| `openPrompt-Lang learning map` | Genera el mapa visual `relations/map.md` en formato Mermaid a partir del grafo `graph.json`. Colorea nodos por categoría y dibuja aristas de relación. Ideal para commitear y visualizar en GitHub |
+| `openPrompt-Lang learning import-personal <file.md>` | Importa un documento Markdown con vocabulario personal (formato `### Término` + descripción) y crea conceptos en la categoría `personal/`. Cada sección se convierte en un concepto con su definición, se añade al grafo y al glosario automáticamente. Omite duplicados. Ideal para cargar tu propio diccionario de términos |
+
+### Estructura de conceptos
+
+Cada concepto vive en `concepts/<categoría>/<nombre>/` con dos niveles:
+
+**Ficha madre** (`concept.md`):
+```markdown
+# moderno
+
+## Resumen
+Estética contemporánea con énfasis en simplicidad.
+
+## Tipo
+visual
+
+## Estado
+propuesto | confirmado | usado | obsoleto
+
+## Variantes disponibles
+| Variante | Archivo | Descripción |
+|----------|---------|-------------|
+| minimalista | minimalista.md | Mucho espacio, colores neutros |
+
+## Relaciones
+- Similar a: contemporaneo, limpio
+- Contraste con: clasico, recargado
+- Compatible con: elegante, profesional
+```
+
+**Variante** (`minimalista.md`):
+```markdown
+# moderno / minimalista
+
+## Tokens de diseño
+- spacing: xl (p-8, gap-6)
+- font: Inter, weight 300-500
+- colors: slate-50, slate-900, accent: blue-500
+- borders: rounded-lg, border-0
+
+## Componentes asociados
+- Button(variant: ghost, size: md)
+- Card(variant: bordered, padding: lg)
+
+## Cuándo usarlo
+- Landing pages profesionales
+- Aplicaciones B2B SaaS
+
+## Riesgos
+- Puede resultar frío sin acento de color
+- Evitar copiar composiciones exactas de referencias
+
+## Confirmación
+- [ ] Verificado con usuario
+```
+
+### Variantes
+
+Cada concepto tiene **variantes** que representan diferentes interpretaciones. El usuario elige una variante y la IA aplica sus tokens de diseño directamente. Así:
+
+| Concepto | Variante | Descripción | Cuándo usarla |
+|----------|----------|-------------|---------------|
+| moderno | minimalista | Mucho espacio, tipografía limpia | Proyectos corporativos |
+| moderno | dark-neon | Fondo oscuro, acentos neón | Apps de tecnología |
+| moderno | glassmorphism | Fondos traslúcidos, blur | Dashboards modernos |
+
+### Reglas de precisión
+
+Obligatorias para la IA en cada sesión:
+
+```
+1. Término vago → learning search <término> antes de implementar
+2. Si existe → mostrar variantes, pedir confirmación al usuario
+3. Si no existe → preguntar: intención, contexto, dominio, ejemplo
+4. Múltiples interpretaciones → ofrecer opciones cerradas
+5. Sin proyecto/dominio → NO clasificar
+6. Referencia externa → separar aprendizaje de copia (REFERENCES.md)
+7. Concepto duplicado → reutilizar, no duplicar
+8. Cada confirmación → log en clarifications/log.json y LOG.json
+```
+
+---
+
 ## VS Code Extension
 
 openPrompt-Lang incluye una extensión para VS Code en `vscode-extension/` con resaltado de sintaxis y snippets.
@@ -1016,9 +1307,9 @@ code --install-extension openprompt-lang-*.vsix
 
 ---
 
-## OpenCode Integration
+## OpenCode & Antigravity Integration
 
-openPrompt-Lang tiene integración nativa con [OpenCode](https://opencode.ai) mediante **MCP server**, **agente especializado**, y **skill auto-detectable**.
+openPrompt-Lang tiene integración nativa con [OpenCode](https://opencode.ai) y [Antigravity](https://antigravity.google) (Google AI IDE) mediante **MCP server**, **agente especializado**, **skill auto-detectable**, y **reglas de workflow obligatorio**.
 
 ### Configuración rápida
 
@@ -1028,14 +1319,22 @@ npx openprompt-lang integrate --all
 
 Esto genera:
 
-- **`.opencode/opencode.json`** — Configuración con MCP server, skill paths y default_agent
-- **`.opencode/agent/openPrompt.md`** — Agente con 4 workflows + Default Workflow
-- **`.opencode/skills/openPrompt/SKILL.md`** — Skill auto-detectable (solo se activa si el proyecto usa anotaciones)
-- **MCP server** — Expone 9 herramientas que Opencode puede llamar directamente
+| Generado para | Archivos |
+|---------------|----------|
+| **Opencode** | `.opencode/opencode.json` — MCP server, skill paths, default_agent |
+| | `.opencode/agent/openPrompt.md` — Agente con 4 workflows |
+| | `.opencode/skills/openPrompt/SKILL.md` — Skill auto-detectable |
+| **Cursor** | `.cursor/config.json` + `.cursor/rules` + `.cursorrules` — Reglas de estilo y anotaciones |
+| **VS Code** | `.vscode/settings.json` — Lint, formateo, TypeScript |
+| | `.vscode/extensions.json` — Extensiones recomendadas |
+| | `.vscode/mcp.json` — MCP server para GitHub Copilot y extensiones compatibles |
+| **Antigravity** | `GEMINI.md` — Instrucciones obligatorias de workflow para Gemini |
+| | `~/.gemini/antigravity/mcp_config.json` — MCP server global (opcional) |
+| **MCP server** | `npx openprompt-lang mcp` — 9 herramientas para todos los editores |
 
 ### MCP Server
 
-El MCP (Model Context Protocol) server permite que Opencode invoque herramientas de openPrompt-Lang de forma nativa, sin comandos slash. Las herramientas retornan estructura consistente:
+El MCP (Model Context Protocol) server permite que **Opencode**, **Antigravity**, **VS Code Copilot**, **Cursor**, y cualquier otro editor compatible invoque herramientas de openPrompt-Lang de forma nativa, sin comandos slash. Las herramientas retornan estructura consistente:
 
 ```
 ## Result: success|error|warning
@@ -1058,9 +1357,22 @@ El MCP (Model Context Protocol) server permite que Opencode invoque herramientas
 | **Testing** | `generate_tests(sourceDir, lang, output)` | Genera tests desde `@learn-error`. Usar **después de documentar un bug** |
 | **Scaffold** | `scaffold_project(framework, name)` | Crea estructura de proyecto y archivos base |
 
-### Auto-supervisión IA (Default Workflow)
+### Auto-supervisión IA (Default Workflow + Work Context)
 
-El **skill auto-detectable** se activa cuando el proyecto usa anotaciones y guía a la IA con este ciclo:
+El **skill auto-detectable** guía a la IA con dos ciclos integrados:
+
+**Work Context (obligatorio, previo a todo):**
+
+```
+1. CONTEXT.md + SESSION.json      → restaurar estado
+2. ANALYZE request                → clasificar tarea
+3. PLAN informed                  → plan new <name> --task "<desc>"
+4. VALIDATE plan                  → @kind, @contract, @limit
+5. IMPLEMENT                      → log cada acción
+6. VALIDATE + close               → validate + reporte final
+```
+
+**MCP Tools (durante implementación):**
 
 ```
 1. analyze_project  → entender el proyecto
@@ -1071,7 +1383,7 @@ El **skill auto-detectable** se activa cuando el proyecto usa anotaciones y guí
 6. validate         → verificar que todo está limpio
 ```
 
-El **agente `openPrompt`** incluye 4 workflows especializados (debugging de anotaciones, implementar componente, onboarding, nuevo proyecto) que la IA sigue automáticamente.
+El **agente `openPrompt`** incluye 4 workflows especializados (debugging de anotaciones, implementar componente, onboarding, nuevo proyecto) que la IA sigue automáticamente, además del sistema work-context obligatorio.
 
 ### Uso manual (sin `integrate`)
 
@@ -1099,6 +1411,60 @@ Luego agrega `.opencode/agent/openPrompt.md` (instrucciones del agente) y `.open
 
 ---
 
+### Antigravity Integration
+
+[Antigravity](https://antigravity.google) (Google AI IDE, basado en VS Code) tiene soporte nativo para:
+
+#### 1. MCP Server (herramientas disponibles)
+
+Antigravity lee `.vscode/mcp.json` y el config global `~/.gemini/antigravity/mcp_config.json`. Ambos se crean automáticamente con `integrate --all`. Esto permite que Gemini llame directamente a las herramientas MCP de openPrompt-Lang sin comandos manuales.
+
+**Transporte stdio:**
+```
+npx openprompt-lang mcp
+```
+
+#### 2. GEMINI.md — Instrucciones obligatorias
+
+`GEMINI.md` en la raíz del proyecto contiene **reglas de workflow obligatorias** que Antigravity inyecta como instrucciones del sistema a Gemini en cada sesión. No es opcional — Gemini las recibe como directivas de máxima prioridad.
+
+**Lo que fuerza:**
+
+| Regla | Descripción |
+|-------|-------------|
+| Ciclo de trabajo | Plan → Validate → Implement → Validate → Learn → Close |
+| Anotaciones | Todo archivo DEBE tener `@use()`, `@kind`, `@contract`/`@props` |
+| Validación | No se puede marcar tarea como completa sin `openprompt-lang validate` |
+| Límites | Componentes ≤120, hooks ≤80, páginas ≤200, servicios ≤150 líneas |
+| Memoria semántica | Consultar `learning search` antes de implementar conceptos vagos |
+| @learn-error | Documentar bugs encontrados para prevenir regresiones |
+| Prohibiciones | No `any`, no saltar validación, no modificar templates |
+
+#### 3. Compatibilidad con AGENTS.md
+
+Antigravity v1.20.3+ también lee `AGENTS.md` como reglas compartidas con Cursor y Claude Code. `GEMINI.md` tiene prioridad sobre `AGENTS.md`, permitiendo tener reglas generales en `AGENTS.md` y reglas estrictas de workflow en `GEMINI.md`.
+
+#### 4. Integración manual
+
+Si no usas `integrate --all`, crea estos archivos manualmente:
+
+```json
+// .vscode/mcp.json
+{
+  "servers": {
+    "openPrompt-Lang": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["openprompt-lang", "mcp"]
+    }
+  }
+}
+```
+
+Y copia `GEMINI.md` de cualquier proyecto openPrompt-Lang en tu raíz. Antigravity lo detecta automáticamente.
+
+---
+
 ## Tutorial: Usar openPrompt-Lang con cualquier IA
 
 Puedes usar openPrompt-Lang con **cualquier asistente de IA** — Google Gemini, Claude, ChatGPT, Cursor AI, etc. El framework no depende de Opencode; las anotaciones son simplemente código que cualquier IA puede leer e interpretar.