OpenPrompt-Lang

Framework de anotaciones como código para desarrollo asistido por IA. Escribe @kind, @contract, @limit como sintaxis directa (sin comentarios) para guiar a la IA sobre estructura, contratos y límites de tu código. Las anotaciones se eliminan automáticamente en build mediante plugins oficiales para Vite y TypeScript, y se integran con OpenCode vía MCP server. Extensible por módulos de lenguaje y tags personalizados.

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.

Repositorio de Conocimiento (Knowledge)

Almacena, indexa y procesa documentos PDF y fuentes web técnicas. Detecta capítulos automáticamente y los divide en secciones de lectura rápida para que la IA los use. Incluye 33 libros y guías pre-empaquetados (JavaScript, TypeScript, Rust, React, Node.js, Python, Scrum, accesibilidad, algoritmos, API de pagos, etc.) accesibles sin configuración previa vía MCP (knowledge_search, knowledge_list, knowledge_read, knowledge_concept) o CLI (knowledge search, knowledge sync --all). Genera automáticamente .openprompt/FRAMEWORK.md con el manual operativo restrictivo para la IA.

Búsqueda Semántica por Embeddings (Vector Search)

Reemplaza el mapa semántico manual con vectores numéricos generados por IA local. Divide documentos en chunks semánticos, los convierte en vectores (768d con Ollama o 384d con Transformers.js), y busca por similitud de coseno. Incluye un pipeline completo: chunker (3 estrategias), embedder (Ollama + Transformers.js con auto-fallback), vector store (SQLite + FTS5), y soporte de búsqueda híbrida (FTS5 + reordenamiento semántico). Se integra con opl search --mode vector y el indexado automático tras la ingesta de PDFs.

Requisitos:

• Primario: Ollama con ollama pull nomic-embed-text (recomendado)
• Fallback: @xenova/transformers (incluido como dependencia opcional, se activa automáticamente si Ollama no está disponible)

Comandos:

opl embeddings status                    # Ver estado del índice vectorial
opl embeddings index <docId>             # Indexar un documento
opl embeddings remove <docId>            # Eliminar embeddings
opl embeddings config                    # Ver/configurar proveedor
opl search "consulta" --mode vector      # Búsqueda semántica
opl search "consulta" --mode hybrid      # Híbrido (incluye vectorial)
opl webscrape <url> --domain frontend    # Scrapear web e indexar
knowledge ingest doc.pdf                 # Ingesta PDF + auto-embedding

IA Local (Local Setup)

Configura un entorno de desarrollo completamente local y desconectado. Prepara la integración con modelos locales en Ollama (como Llama 3 o Qwen 2.5 Coder) y la suite de herramientas OpenCode, permitiendo trabajar sin internet ni costos de API, pero manteniendo el 100% de la precisión del framework.

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
• Nuevas Capacidades (v0.4.0)
  • Aprender de proyectos reales
  • Aprender de documentación
  • Transferencia de contexto
  • Contexto por dominio
  • Presets pre-ensamblados
  • Reglas de base de datos
  • Filtros de componentes
• Anotaciones PromptLang (directorio completo)
  • Tags de definición
  • Tags de contrato
  • Tags de restricción
  • Tags de composición
  • Tags de plataforma
  • Tags de alcance
  • Tags de testing
  • Tags de metadata
• Comandos CLI
• Tutorial: Empezar desde 0
• Tutorial: Refactorizar proyecto existente
• Configuración (prompt-lang.json)
• Validación cruzada
• Scripts descriptivos
• Estructura del proyecto
• Sistema de componentes
• Work Context System
  • Comandos work-context
  • Flujo de trabajo obligatorio
  • Referencias web seguras
• Memoria Semántica
  • Comandos learning
  • Estructura de conceptos
  • Variantes
  • Reglas de precisión
• Repositorio de Conocimiento (Knowledge)
  • Comandos knowledge
  • Flujo de ingesta y procesamiento
• IA Local (Local Setup)
  • Comandos local-setup
• VS Code Extension
• Versionado (SemVer)
• Documentación

Instalación

Linux / macOS

# Instalación global
npm install -g openprompt-lang

# Si no tienes permisos globales:
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"   # agrega a ~/.bashrc o ~/.zshrc
npm install -g openprompt-lang

# Verificar
openPrompt-Lang --version

Windows (PowerShell)

# Instalación global
npm install -g openprompt-lang

# Si no tienes permisos globales (ejecutar como Administrador una vez):
npm config set prefix "${env:APPDATA}\npm"
# O crear carpeta local:
mkdir "$env:USERPROFILE\.npm-global" -Force
npm config set prefix "$env:USERPROFILE\.npm-global"
# Agregar al PATH (PowerShell profile):
[Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\.npm-global\bin;" + $env:Path, "User")
# O desde cmd/símbolo del sistema:
:: setx PATH "%USERPROFILE%\.npm-global\bin;%PATH%"

# Verificar
openPrompt-Lang --version

Alternativa: npx (sin instalar)

npx openprompt-lang --help

El paquete está publicado en npm: npx openprompt-lang --help

Anotaciones PromptLang (directorio completo)

Las anotaciones se escriben en el código para guiar a la IA sobre restricciones, contratos y contexto del archivo. El parser detecta anotaciones tanto en comentarios como en código directo.

Sintaxis general

Soporta dos modos:

Modo comentario (compatible con TS/JS estándar)

// @nombre(args)
// @nombre(key: value, key2: value2)

/* Formato multilinea */
/*
 * @use(kind, contract, deps)
 * @kind(service)
 * @contract(in: DTO -> out: Result @error: ServiceError)
 */

Modo código (sin //)

@nombre(args)
@nombre(key: value, key2: value2)

El parser reconoce automáticamente ambos formatos. Puedes mezclarlos libremente:

// @use(kind, contract, deps)
@kind(service)
@contract(in: DTO -> out: Result @error: ServiceError)

@use — Declaración de tags (OBLIGATORIO)

Primer tag de todo archivo. Declara qué tags se usan.

| Sintaxis | Significado | |---|---| | @use(*) | Todos los tags disponibles | | @use(kind, contract) | Solo los tags listados |

Tags de definición

@kind — Tipo de elemento

@kind(tipo)

| Valor | Descripción | Tags requeridos | Tags prohibidos | Límite default | |---|---|---|---|---| | hook | Custom hook React | @contract | @props | 80 líneas | | component | Componente UI | @props (recomendado) | @contract | 120 líneas | | page | Página completa | @compose | — | 200 líneas | | service | Servicio / API | @contract | @props, @state | 150 líneas | | store | Estado global | @deps(zustand) | — | 100 líneas | | util | Función utilitaria | — | @state | 100 líneas | | type | Interfaz / tipo | — | @limit, @state | — | | layout | Componente de layout | — | — | 150 líneas | | feature | Módulo completo | @compose | — | — |

@pattern — Patrón de diseño

@pattern(nombre)

Valores: compound, composition, generic, render-prop, provider, singleton

Tags de contrato

@contract — Interfaz de función (hooks / services)

@contract(in: tipos -> out: tipo @error: tipo)

@contract(in: email, password -> out: User @error: AuthError)
@contract(in: ProductDTO -> out: Product @error: ValidationError)

@props — Props de componente

@props({ "nombre": "tipo", "nombre2?": "tipo", "nombre3": "tipo" })

Importante: @props acepta dos formatos:

// Formato JSON (estricto):
✅ @props({ "name": "string", "age?": "number", "label": "string" })

// Formato TypeScript (recomendado, más legible):
✅ @props({ name: string, age?: number, label: string })

// ❌ Mezclar ambos no funciona:
❌ @props({ "name": string })

@props({ "name": "string", "age?": "number", "label": "string" })

@state — Estados visuales

@state(loading, empty, error, success, idle, submitting)

Tags de restricción

@limit — Límites del archivo

@limit(lines: 120, functions: 3, params: 2, complexity: 5, nesting: 3)

@forbidden — Prohibiciones explícitas

@forbidden(any, css-modules, class-components)

Tags de composición

@compose — Dependencias internas

@compose(Header, DataTable, Sidebar)

Requerido en @kind(page).

@deps — Dependencias externas

@deps(@external: [supabase, zod], @internal: [utils], @forbidden: [axios])

| Sub-tag | Descripción | |---|---| | @external | Librerías npm/pip/cargo | | @internal | Módulos del mismo proyecto | | @forbidden | Librerías prohibidas | | @peer | Peer dependencies |

Tags de plataforma

@platform — Target de ejecución

@platform(web, mobile, desktop)

Compatibilidad:

| Plataforma | @capacitor/* | @tauri-apps/* | |---|---|---| | web | ❌ Prohibido | ❌ Prohibido | | mobile | ✅ Permitido | ❌ Prohibido | | desktop | ❌ Prohibido | ✅ Permitido |

Tags de alcance

@scope — Impacto del módulo

@scope(module: auth, affects: [login, register], breaking: false)

Tags de testing

@test — Requisitos de testing

@test(@unit, @integration, @mock: [servicio], @coverage: 80)

Tags de metadata

@meta — Metadatos del archivo

@meta(@version: "1.0.0", @author: "dev", @tags: [auth, supabase])

Tags de aprendizaje y documentación

@learn-error — Error aprendido

Documenta un bug encontrado y su solución para prevenir regresiones:

// @learn-error id=BUTTON-001 input='...' expected=200 actual=500 fix='...' category=validation

Usado por qa-gen para generar tests de regresión automáticamente.

@goodPractice — Buena práctica

Marca una sección de código como ejemplo de buena práctica:

// @goodPractice("Usar early return reduce indentación")

@badPractice — Mala práctica

Marca una sección como ejemplo de lo que no debe hacerse:

// @badPractice("No mutar props directamente")

@teachMe — Enseñanza estructurada

Documenta el diseño, propósito o lección de un archivo para que la IA lo entienda:

// @teachMe
// Este hook maneja autenticación con Supabase.
// Usa early return para errores de validación antes de llamar a la API.
// El token se persiste en localStorage y se verifica al montar.

Usado por openPrompt-Lang teach y el agente de Opencode.

@template — Plantilla reutilizable

Marca un archivo como template reutilizable dentro del módulo de lenguaje.

@source — Origen de extracción

Indica el archivo original del que se extrajo un template (usado por extract).

@reuse — Reutilización

Indica cuántas veces se ha reutilizado un template extraído.

@extracted — Extraído

Marca un template como generado por el extractor automático.

Ejemplos completos

Modo comentario

// @use(kind, contract, limit, deps, platform, scope, meta)
// @kind(hook)
// @limit(lines: 75, params: 1)
// @contract(in: email, password -> out: user, token @error: AuthError)
// @deps(@external: [supabase], @forbidden: [axios])
// @platform(web)
// @scope(module: auth, affects: [login, register, session])
// @meta(@version: "1.0.0", @tags: [auth, supabase])
export function useAuth() { ... }

// @use(kind, props, state, limit, pattern)
// @kind(component)
// @props({ "variant": "string", "size": "string", "children": "ReactNode", "disabled?": "boolean" })
// @state(idle, disabled, loading)
// @limit(lines: 90, functions: 2)
// @pattern(composition)
export function Button(props: ButtonProps) { ... }

Modo código

@use(kind, contract, limit, deps, platform, scope, meta)
@kind(hook)
@limit(lines: 75, params: 1)
@contract(in: email, password -> out: user, token @error: AuthError)
@deps(@external: [supabase], @forbidden: [axios])
@platform(web)
@scope(module: auth, affects: [login, register, session])
@meta(@version: "1.0.0", @tags: [auth, supabase])
export function useAuth() { ... }

@use(kind, props, state, limit, pattern)
@kind(component)
@props({ variant: string, size: string, children: ReactNode, disabled?: boolean })
@state(idle, disabled, loading)
@limit(lines: 90, functions: 2)
@pattern(composition)
export function Button(props: ButtonProps) { ... }

Nota: El modo código usa la sintaxis @tag( ... ) sin //. El parser solo reconoce tags conocidos (@kind, @use, @props, etc.) para evitar confundirlos con decoradores JS/TS como @Component o @Injectable. Funciona tanto en .ts como en .js, .py, .vue, etc.

📖 Especificación completa: docs/SYNTAX.md

Nuevas Capacidades (v0.4.0)

Aprender de proyectos reales — extract --learn

Analiza un proyecto y extrae sus patrones: convención de nombres, arquitectura, estilo UI, hooks, anotaciones. Genera un perfil reutilizable.

openPrompt-Lang extract ./proyecto-pulido --learn
openPrompt-Lang init --name nuevo --learn-from ./aprendizaje-perfil.json

Aprender de documentación — learn

Usa IA para transformar documentación local en módulos de lenguaje funcionales con templates, tests y prácticas.

openPrompt-Lang learn --docs ./docs-rust/ --name rust
openPrompt-Lang learn --docs ./docs-react/ --from ./proyecto-real/ --name react
openPrompt-Lang learn --docs ./docs/ --name django --integrate

Los módulos se guardan en ~/.openprompt/knowledge/langs/<id>/ (accesibles para cualquier proyecto).

Transferencia de contexto — integrate --from/--to

Copia el contexto de negocio entre proyectos: stack, convenciones, @kind/@contract detectados, arquitectura.

openPrompt-Lang integrate --from ./web-react --to ./app-mobile

Contexto por dominio — context --domain

Filtra el contexto del proyecto por dominio de negocio: ecommerce, saas, mobile, api, admin, blog.

openPrompt-Lang context --domain ecommerce

Presets pre-ensamblados — init --preset

Stacks completos con servicios incluidos: Supabase, Stripe, Ionic, Tauri, Firebase.

openPrompt-Lang init --preset react-supabase-stripe --name tienda
openPrompt-Lang init --list-presets

Reglas de base de datos — db-rules

Knowledge base de buenas prácticas, anti-patrones y reglas para SQL, Supabase, Postgres, Docker.

openPrompt-Lang db-rules --id db-001
openPrompt-Lang db-rules --tag performance

Filtros de componentes — component list --style/--tech/--validated

openPrompt-Lang component list --style shadcn
openPrompt-Lang component list --tech vue
openPrompt-Lang component list --validated

📖 Manual completo para IA: docs/AI-MANUAL.md — todos los comandos, workflows ordenados y configuración.

Comandos CLI

| Comando | Descripción | |---|---|---| | openPrompt-Lang init --name miapp | Crea proyecto desde 0 con scaffolding completo + scripts descriptivos | | openPrompt-Lang init --existing | Configura proyecto existente (solo archivos de config) | | openPrompt-Lang context --output contexto.md | Extrae todo el código + anotaciones para dar contexto a la IA | | openPrompt-Lang validate [--fix] | Valida anotaciones y ejecuta pipeline de verificación | | openPrompt-Lang figma | Genera prompt para diseño Figma | | openPrompt-Lang suggest "descripción" | IA sugiere stack y estructura según descripción | | openPrompt-Lang wizard | Asistente interactivo para configurar proyecto openPrompt-Lang | | openPrompt-Lang teach <templateId> | Enseñanza estructurada desde template con @teachMe | | openPrompt-Lang ai-gen | Genera componentes desde descripciones en lenguaje natural | | 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, 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 | | openPrompt-Lang lang index <langId> | Muestra índice de templates de un lenguaje | | openPrompt-Lang lang search <query> | Busca templates en todos los lenguajes | | openPrompt-Lang lang errors [langId] | Muestra errores aprendidos | | openPrompt-Lang scaffold folders <framework> | Crea estructura de carpetas según framework | | openPrompt-Lang scaffold list | Lista frameworks disponibles en el catálogo | | openPrompt-Lang component init | Inicializa biblioteca de componentes reutilizables | | openPrompt-Lang component list | Lista componentes disponibles (proyecto + biblioteca) | | 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/ | | openPrompt-Lang knowledge init | Inicializa estructura knowledge/ en el proyecto | | openPrompt-Lang knowledge ingest <file> | Procesa un PDF: extrae texto nativo/OCR, detecta capítulos y almacena | | openPrompt-Lang knowledge list | Lista los PDFs procesados con sus metadatos | | openPrompt-Lang knowledge status [id] | Muestra estado detallado de uno o todos los PDFs | | openPrompt-Lang knowledge to-learning | Integra los capítulos de los PDFs procesados a la memoria semántica | | openPrompt-Lang knowledge rebuild | Reconstruye el índice general desde metadatos individuales | | openPrompt-Lang knowledge sync [--all] | Sincroniza libros de la biblioteca empaquetada al proyecto local | | openPrompt-Lang local-setup | Configura integración con IA local (Ollama + OpenCode) | | opl workflow select <desc> | Selecciona workflow óptimo según descripción de la tarea (usar SIEMPRE primero) | | opl workflow delivery | Inicia desarrollo por tickets (E.3) | | opl workflow close | Cierra sesión activa y genera reporte (E.4) | | opl epic create --title "..." --desc "..." | Crea épica con tickets generados automáticamente | | opl epic list | Lista épicas con métricas de progreso | | opl epic show <id> | Muestra detalle de épica y sus tickets | | opl epic close <id> | Cierra épica | | opl sprint create <name> --goal "..." | Crea sprint con duración configurable | | opl sprint list | Lista sprints con métricas | | opl sprint plan <id> --capacity N | Planifica sprint automáticamente desde épicas activas | | opl sprint close <id> | Cierra sprint | | opl ticket create --title "..." --severity ... | Crea ticket de bug/tarea | | opl ticket list | Lista tickets del proyecto | | opl ticket close <id> | Cierra ticket como fixed | | opl embeddings status | Ver estado del índice vectorial semántico | | opl embeddings index <docId> | Indexa un documento en el vector store | | opl embeddings remove <docId> | Elimina embeddings de un documento | | opl embeddings config | Ver/configurar proveedor de embeddings | | opl webscrape <url> | Extrae contenido web y lo indexa en knowledge + embeddings |

Base de Conocimiento Empaquetada

openPrompt-Lang incluye 33 libros y guías técnicas pre-empaquetados (no requiere configuración previa):

| Categoría | Libros | |-----------|--------| | Lenguajes | JavaScript Elocuente (4ª ed), TypeScript, Rust Libro Oficial ES, Rust Aprendizaje, Node.js ES, Python | | Web/Frameworks | React Aprendiz Maestro, React+Redux, React StackOverflow, CapacitorJS, Flowbite React, Qwik | | Metodologías | Guías de Desarrollo Software (Chile), Scrum, Scrum+XP | | Algoritmos | Estructuras de Datos, Algoritmos, Lógica de Programación, Problemas y Algoritmos | | API/Integraciones | Flow API (Chile — pagos) | | Accesibilidad | WCAG Tips, Guías de Accesibilidad Web (Chile) | | Fundamentos | Fundamentos de Programación, Introducción POO, Bases de Datos |

La IA accede a esta base de conocimiento a través de:

1. MCP Tools (recomendado): knowledge_search, knowledge_list, knowledge_read, knowledge_concept
2. CLI: npx openPrompt-Lang knowledge search "término", knowledge list, knowledge sync --all
3. Fallback: .openprompt/FRAMEWORK.md contiene el manual operativo completo con el catálogo de libros

Tutorial: Empezar desde 0

Paso 1: Inicializar el proyecto

openPrompt-Lang init --name mi-app-web
cd mi-app-web

Esto crea:

mi-app-web/
├── src/                     # Scaffolding: components/, hooks/, features/, services/, store/, ...
├── docs/                    # BACKLOG/, COMMITS/, LOGS/, PROMPTS/
├── scripts/
│   └── validate.sh          # Pipeline de validación pre-commit
├── 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

Paso 2: Inicializar Vite + React + TS

npm create vite@latest . -- --template react-ts
npm install
npm install tailwindcss @tailwindcss/vite

Luego copia los scripts descriptivos del package.json generado o usa --existing para mergearlos.

Paso 3: Anotar tu primer hook

// src/hooks/useAuth.ts
// @use(kind, contract, limit, deps)
// @kind(hook)
// @limit(lines: 60, params: 1)
// @contract(in: email, password -> out: User | null @error: string)
// @deps(@external: [supabase])
export function useAuth() {
  // ...
}

Paso 4: Validar

openPrompt-Lang validate
npm run type:check
npm run test:unit

Paso 5: Extraer contexto para la IA

openPrompt-Lang context --output contexto.md

Pasa ese contexto.md a la IA junto con docs/referencia-metodologia/ para que entienda el proyecto completo.

Tutorial: Refactorizar proyecto existente

Paso 1: Configurar

cd mi-proyecto-ya-iniciado
openPrompt-Lang init --existing

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)
• ¿Crear docs/BACKLOG, COMMITS, LOGS?

Paso 2: Anotar los archivos a refactorizar

Empieza por los archivos que vas a tocar:

// @use(kind, contract, limit)
// @kind(service)
// @limit(lines: 100)
// @contract(in: UserDTO -> out: User @error: ApiError)
export async function createUser(data: UserDTO): Promise<User> { ... }

Paso 3: Validar solo lo que cambiaste

openPrompt-Lang validate src/services/userService.ts

Paso 4: Generar contexto para la IA

openPrompt-Lang context --output contexto.md --scope auth

Filtra por módulo (@scope) para no saturar a la IA con código no relevante.

Paso 5: Refactorizar

Pasa el contexto.md a la IA con instrucciones específicas (qué refactorizar, qué patrones usar, límites).

Configuración (prompt-lang.json)

{
  "name": "mi-app",
  "version": "0.1.0",
  "stack": {
    "base": ["react", "typescript", "vite", "tailwind"],
    "extensions": ["supabase", "ionic"]
  },
  "profile": "senior",
  "annotations": { "enabled": true, "strict": false },
  "docs": { "commits": true, "logs": true, "backlog": true },
  "extractor": {
    "ignore": [".env", "*.local", "dist", "node_modules"],
    "output": "contexto.md"
  }
}

| Campo | Descripción | |---|---| | stack.base | Tecnologías base del proyecto | | stack.extensions | Extensiones opcionales (supabase, ionic, tauri) | | profile | Perfil del dev: senior, mid, junior | | annotations.strict | Si true, falla en warnings (no solo errores) | | components.source | Ruta de componentes del proyecto (src/components/ui) | | components.library | Ruta de la biblioteca de componentes reutilizables | | extractor.ignore | Patrones a ignorar al extraer contexto |

Validación cruzada

El CLI valida relaciones entre tags automáticamente:

| @kind | @contract | @props | @state | @compose | @limit default | |---|---|---|---|---|---| | hook | REQUERIDO | PROHIBIDO | — | — | 80 | | component | PROHIBIDO | RECOMENDADO | RECOMENDADO | — | 120 | | page | — | — | — | REQUERIDO | 200 | | service | REQUERIDO | PROHIBIDO | PROHIBIDO | — | 150 | | store | — | — | — | — | 100 | | type | — | — | PROHIBIDO | — | N/A |

Además:

• @platform(web) + @deps(@capacitor/*) → ERROR
• @platform(mobile) + @deps(@tauri-apps/*) → ERROR
• @scope(breaking: true) → commit debe ser breaking change !
• @forbidden(any) → warning si se detecta any en el código
• @state(error) sin @contract(@error) → warning (solo en hook/service, no en component/page)

Scripts descriptivos

Generados automáticamente por npm init (o mergeables con --existing).

| Script | Comando real | Propósito | |---|---|---| | npm run dev:start | vite | Servidor de desarrollo | | npm run dev:preview | vite preview | Vista previa del build | | npm run build:prod | vite build | Build producción | | npm run build:analyze | vite build --analyze | Build con análisis de bundle | | npm run lint:check | eslint src --ext .ts,.tsx | Verificar lint | | npm run lint:fix | eslint src --ext .ts,.tsx --fix | Auto-corregir lint | | npm run type:check | tsc --noEmit | Verificar tipos TypeScript | | npm run quality:doctor | npx react-doctor check ./src | Auditoría React | | npm run test:unit | vitest run | Tests unitarios | | npm run test:watch | vitest | Tests en modo watch | | npm run test:coverage | vitest run --coverage | Tests con cobertura | | npm run validate:all | lint + typecheck + doctor + test | Pipeline completo |

Estructura del proyecto

openPrompt-Lang/
├── bin/
│   ├── cli.js                  ← Entry point del CLI
│   ├── create.js               ← Scafolder directo
│   └── lint.js                 ← Linter independiente
├── src/
│   ├── commands/
│   │   ├── init.js             ← init + --existing
│   │   ├── context.js          ← Extractor de contexto
│   │   ├── validate.js         ← Validador de anotaciones (con --fix)
│   │   ├── figma.js            ← Generador de prompts Figma
│   │   ├── suggest.js          ← Sugerencia de stack vía IA
│   │   ├── wizard.js           ← Asistente interactivo
│   │   ├── teach.js            ← Enseñanza desde @teachMe
│   │   ├── ai-gen.js           ← Generación de componentes vía IA
│   │   ├── extract.js          ← Extractor de templates reutilizables
│   │   ├── integrate.js        ← Integración con Opencode/Cursor/VS Code
│   │   ├── qa-gen.js           ← Generación de tests desde @learn-error
│   │   ├── lang.js             ← Gestión de módulos de lenguaje
│   │   ├── scaffold.js         ← Scaffolding de proyectos
│   │   ├── component.js        ← Biblioteca de componentes
│   │   └── mcp-server.js       ← Servidor MCP (9 herramientas)
│   ├── utils/
│   │   ├── annotations.js      ← Parser + validador de anotaciones
│   │   ├── config.js           ← Loader de prompt-lang.json + deep merge
│   │   ├── ai.js               ← Módulo de IA (OpenAI / Anthropic / Ollama)
│   │   ├── language-loader.js  ← Cargador de módulos de lenguaje
│   │   ├── error-learner.js    ← Sistema de @learn-error
│   │   ├── file-utils.js       ← findAllFiles / findComponentFiles / analyzeImports / countFiles
│   │   └── template-utils.js   ← extractLesson / extractTags (compartido)
│   ├── annotations/
│   │   ├── tags.json           ← Lista canónica de 24 tags
│   │   └── registry.js         ← Fusiona builtin + módulo + proyecto
│   ├── ai/
│   │   ├── providers.js        ← Proveedores IA (OpenAI, Anthropic, Ollama, Mock, None)
│   │   └── prompt-builder.js   ← Constructor de prompts
│   ├── generators/
│   │   └── figma-prompt.js     ← Generador de prompts Figma
│   ├── vite-plugin/
│   │   └── index.js            ← Plugin Vite para eliminar anotaciones en build
│   └── templates/
│       ├── langs/
│       │   ├── react/          ← 11 templates (Button, Input, Select, Card, Modal, DataTable, hooks, services)
│       │   └── vue/            ← 12 templates (6 UI components + 5 composables + 1 service)
│       └── scripts/            ← Scripts shell (validate.sh, etc.)
├── .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
│   └── 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
│   ├── init.test.js            ← Tests de init
│   ├── language-loader.test.js ← Tests de language-loader
│   ├── wizard.test.js          ← Tests de qualityGate
│   ├── scaffold.test.js        ← Tests de scaffold
│   ├── validate.test.js        ← Tests de validate
│   ├── qa-gen.test.js          ← Tests de QA generation
│   ├── mcp-integration.test.js ← 14 tests MCP end-to-end
│   ├── context.test.js         ← Tests de extracción de contexto
│   ├── integrate.test.js       ← Tests de integración Opencode/Cursor/VS Code
│   ├── file-utils.test.js      ← Tests de findAllFiles / countFiles
│   ├── template-utils.test.js  ← Tests de extractLesson / extractTags
│   ├── teach.test.js           ← Tests de enseñanza desde templates
│   ├── ai-gen.test.js          ← Tests de generación vía IA
│   ├── extract.test.js         ← Tests de extracción de templates
│   └── component.test.js       ← Tests de biblioteca de componentes
├── docs/
│   ├── COMMANDS.md             ← Documentación completa de comandos
│   ├── SYNTAX.md               ← Especificación del lenguaje PromptLang
│   ├── DEPENDENCIES.md         ← Dependencias y versiones
│   ├── VERSIONING.md           ← Convención SemVer
│   ├── FRAMEWORK.md            ← Framework spec (acceso rápido)
│   └── referencia-metodologia/ ← Metodología completa (17 archivos)
│       ├── Indice General.md
│       ├── Fase - 1.md a Fase - 8.md
│       ├── docs/PROMPTS/       ← Biblioteca de prompts reutilizables
│       └── ...
├── vscode-extension/          ← Extensión VS Code (highlighting + snippets)
├── schemas/
│   └── prompt-lang.json        ← JSON Schema para la configuración
├── scaffolds/                  ← Scaffolds base para proyectos
│   └── AGENTS.md               ← Template de AGENTS.md
├── package.json
└── .gitignore

Documentación

| Archivo | Contenido | |---|---| | docs/SYNTAX.md | Especificación completa del lenguaje de anotaciones PromptLang | | docs/COMMANDS.md | Todos los comandos, opciones y configuración del CLI | | docs/DEPENDENCIES.md | Dependencias del proyecto, versiones y notas técnicas | | docs/FRAMEWORK.md | Framework spec — catálogo de patrones y metodología | | docs/VERSIONING.md | Convención de versionado SemVer (MAJOR/MINOR/PATCH, pre-release) | | docs/referencia-metodologia/ | Metodología completa: fases, patrones, templates de prompts | | docs/referencia-metodologia/docs/CONVENCIONES_DB.md | 18 prácticas de base de datos (RLS, índices, batch, etc.) | | docs/referencia-metodologia/docs/CONVENCIONES_DOCUMENTACION.md | Estándar de documentación (tablas DB, Mermaid, contratos RPC) | | docs/referencia-metodologia/docs/PROMPTS/ | Biblioteca de prompts reutilizables (17 plantillas + 3 stacks) | | 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 |

Versionado (SemVer)

openPrompt-Lang sigue SemVer estricto:

| Bump | Cuándo | Ejemplo | |---|---|---| | MAJOR | Breaking changes en API, CLI o anotaciones | 1.0.0 → 2.0.0 | | MINOR | Nuevas funcionalidades, comandos, tags | 0.3.0 → 0.4.0 | | PATCH | Fixes, docs, refactors sin cambio de API | 0.2.0 → 0.2.1 |

Pre-release: 1.0.0-alpha.1, 1.0.0-beta.1, 1.0.0-rc.1

📖 Especificación completa: docs/VERSIONING.md

Sistema de componentes

openPrompt-Lang incluye un sistema de biblioteca de componentes reutilizables:

• component init — Crea una biblioteca con ejemplos (Button, ConfirmModal, Input)
• component list — Muestra componentes del proyecto y de la biblioteca
• component add <nombre> — Copia un componente de la biblioteca al proyecto
• Los componentes incluyen UX patterns: ConfirmModal para acciones destructivas, Button con variante danger, etc.
• Configurable en prompt-lang.json → components.library

Extensibilidad

El sistema de tags es extensible en tres niveles sin modificar el core:

Nivel 1 — Módulo de lenguaje

Agrega annotationTags en el MODULE.json de tu módulo:

{
  "id": "react-query",
  "name": "React Query",
  "annotationTags": ["query", "mutation"]
}

Nivel 2 — Configuración del proyecto

Agrega customTags en prompt-lang.json:

{
  "annotations": {
    "customTags": ["audit", "security", "performance"]
  }
}

Nivel 3 — Plugins de build

Los plugins de Vite, TypeScript y Transformer aceptan la opción tags o customTags:

// vite.config.ts
import { openPromptAnnotations } from "openprompt-lang/vite-plugin";

export default {
  plugins: [
    openPromptAnnotations({ tags: ["audit", "security"] }),
  ],
};

// tsconfig.json
{
  "compilerOptions": {
    "plugins": [
      { "name": "openprompt-lang/ts-plugin", "customTags": ["audit"] }
    ]
  }
}

Canonical tag list

La lista completa de tags builtin está en src/annotations/tags.json. El registry (src/annotations/registry.js) fusiona builtin + módulo + proyecto automáticamente. Todos los plugins y herramientas (parser, Vite, TS, grammar, MCP) consumen de esta misma fuente.

Build Plugins

Para usar anotaciones como código (sin //), necesitas que el compilador las ignore en build.

Vite Plugin (Recomendado)

npm install -D openprompt-lang

// vite.config.ts
import { openPromptAnnotations } from "openprompt-lang/vite-plugin";

export default defineConfig({
  plugins: [
    openPromptAnnotations(),
  ],
});

Elimina las líneas @tag(...) antes de que esbuild las procese. Soporta paréntesis anidados y multi-línea.

TypeScript Language Service Plugin

Para VS Code (suprime errores rojos en @tag(...)):

// tsconfig.json
{
  "compilerOptions": {
    "plugins": [
      { "name": "openprompt-lang/ts-plugin" }
    ]
  }
}

TS Transformer (para tsc / Next.js)

// next.config.js o en tsconfig.json via ts-patch
const { createTransformer } = require("openprompt-lang/ts-transformer");

module.exports = {
  webpack: (config) => {
    config.module.rules.push({
      test: /\.tsx?$/,
      use: {
        loader: "ts-loader",
        options: {
          getCustomTransformers: () => ({
            before: [createTransformer()],
          }),
        },
      },
    });
    return config;
  },
};

Auto-configuración

# Para proyectos existentes:
openPrompt-Lang init --existing

# Te preguntará si configurar Vite plugin y TS plugin automáticamente.

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 (v1.3.0)

La IA debe seguir este ciclo en cada sesión de trabajo. No hay excepciones:

1. → workflow_select          → "opl workflow select <descripción>"
                               La IA describe su tarea, el sistema selecciona workflow óptimo
2. → create_ticket             → "opl ticket create --title ... --severity ..."
                               TODO cambio requiere ticket ANTES de implementar
3. → check_gates               → workflow_selected ✓, ticket_created ✓, plan_approved ✓
4. → work_context_plan         → Planificar usando work-context con búsqueda de conocimiento
5. → implement                 → Codificar con anotaciones OPL primero (@kind → @contract → @limit)
6. → validate                  → "opl validate" antes de cerrar
7. → docs_updated              → Actualizar documentación (OBLIGATORIO antes de cerrar)
8. → work_context_close        → Cerrar sesión y generar reporte

Reglas inquebrantables:

• Regla #1: workflow select primero — Sin workflow seleccionado no hay implementación
• Regla #2: ticket create antes de código — Sin ticket no se escribe código
• Regla #3: docs_updated antes de cerrar — Sin documentación actualizada no se cierra sesión

El sistema de gates (workflow_selected, ticket_created, plan_approved, docs_updated) bloquea herramientas automáticamente si no se cumplen los prerrequisitos (configurable en prompt-lang.json → workflow.enforcement).

Ver también: AGENTS.md para instrucciones detalladas de cada paso. 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):

# 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):

# 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

Repositorio de Conocimiento (Knowledge)

El sistema Knowledge permite expandir la memoria de tu entorno de desarrollo ingiriendo y procesando especificaciones, libros, manuales, o documentación técnica pesada en formato PDF. El framework extrae el texto, estructura los capítulos automáticamente, y te permite importarlos directo a tu memoria semántica (learning).

Estructura de directorios

Cuando inicializas el sistema, se crea la siguiente estructura en la raíz de tu proyecto:

knowledge/
├── source-pdfs/          # Copia de seguridad de los archivos PDF originales
├── extracted-md/         # Texto plano extraído de cada PDF
├── chapters/             # Capítulos individuales divididos automáticamente
├── meta/                 # Metadatos individuales de procesamiento JSON
│   ├── index.json        # Índice machine-readable general de PDFs
│   └── <pdf-id>.json     # Metadatos del PDF
└── index.md              # Índice en Markdown legible para humanos y la IA

Comandos knowledge

| Comando | Descripción | |---------|-------------| | openPrompt-Lang knowledge init | Inicializa la estructura de directorios de conocimiento y crea el archivo index.md. | | openPrompt-Lang knowledge ingest <file> [--ocr] [--auto-ocr] [--force] [--verbose] | Procesa un archivo PDF. Detecta texto nativo o ejecuta OCR (con --ocr o de manera automática con --auto-ocr si hay baja densidad de texto), divide el texto por capítulos y guarda los metadatos. | | openPrompt-Lang knowledge list | Lista todos los PDFs que han sido procesados, su ID único, número de páginas, método de extracción y cuántos capítulos se detectaron. | | openPrompt-Lang knowledge status [id] | Muestra un resumen general o el desglose detallado de un PDF específico, incluyendo su autor, fecha de procesamiento y la lista de capítulos con sus ubicaciones en disco. | | openPrompt-Lang knowledge to-learning [--pdf <id>] [--force] | Convierte los capítulos del PDF en conceptos de la memoria semántica (.opencode/learning/concepts/knowledge/). Actualiza el grafo de relaciones y el glosario de términos automáticamente. | | openPrompt-Lang knowledge rebuild | Reconstruye el índice general (meta/index.json) y el archivo legible index.md a partir de los archivos de metadatos individuales. |

Flujo de ingesta y procesamiento

1. Ingesta inicial: El comando knowledge ingest manual-spring.pdf --auto-ocr analiza el PDF, extrae el contenido, detecta la separación de capítulos y genera archivos .md independientes por capítulo en knowledge/chapters/.
2. Integración semántica: Corres knowledge to-learning para inyectar estos capítulos directamente en la memoria semántica del framework (.opencode/learning/).
3. Uso por la IA: La IA ahora puede buscar y consumir estos capítulos de forma desacoplada y eficiente usando learning search <concepto> o a través de la inyección de contexto en los planes de trabajo (work-context plan new <name> --task "<desc>").

IA Local (Local Setup)

El comando Local Setup te permite desvincularte de APIs pagas y dependencias de internet configurando un entorno ágil e independiente utilizando Ollama como motor de inferencia local y OpenCode como integrador en el editor.

Comandos local-setup

| Comando | Descripción | |---------|-------------| | openPrompt-Lang local-setup [--dry-run] | Configura el espacio de trabajo activo con archivos para IA local. Genera la configuración opencode.json con soporte para Ollama (Llama 3, Qwen 2.5 Coder), el comando /local-ai y la estructura de memoria docs/AI_CONTEXT.md. |

Archivos creados

• opencode.json: Archivo de configuración maestro de integración con editores, configurando el provider Ollama en http://localhost:11434/v1 y especificando los modelos recomendados.
• .opencode/commands/local-ai.md: Un comando estructurado para el chat que le indica a la IA local que lea el contexto y AGENTS.md, adaptando su temperatura y nivel de atención a pasos más pequeños y seguros.
• docs/AI_CONTEXT.md: Diario e índice de memoria global del proyecto para que la IA local se asiente rápidamente en el dominio del negocio.
• docs/AI_IMPROVEMENTS.md: Registro estructurado de mejoras técnicas y de rendimiento realizadas sobre la base de código.

VS Code Extension

openPrompt-Lang incluye una extensión para VS Code en vscode-extension/ con resaltado de sintaxis y snippets.

Instalación

Opción 1 — Desde el paquete npm (recomendada):

# La extensión está dentro del paquete npm instalado
code --install-extension ./node_modules/openprompt-lang/vscode-extension/

Opción 2 — Desde el repositorio local:

cd ruta/a/openPrompt-Lang/vscode-extension/
code --install-extension .

Opción 3 — Empaquetar como .vsix:

cd ruta/a/openPrompt-Lang/vscode-extension/
npx @vscode/vsce package
code --install-extension openprompt-lang-*.vsix

Funcionalidades

• Syntax highlighting: todos los tags (@kind, @props, @contract, etc.) se resaltan tanto en comentarios (// @kind) como en código directo (@kind)
• Snippets: escribe @kind- y autocompleta:
  • @kind-hook → hook con @contract
  • @kind-component → componente con @props
  • @kind-service → servicio con @contract + @platform
  • @kind-page → página con @compose
  • @kind-store → store Zustand
  • @use-header → declaración @use()
  • @props-ts → props con sintaxis TypeScript

Requisitos

• VS Code >= 1.85.0
• La extensión se activa automáticamente en archivos .ts y .tsx

OpenCode & Antigravity Integration

openPrompt-Lang tiene integración nativa con OpenCode y Antigravity (Google AI IDE) mediante MCP server, agente especializado, skill auto-detectable, y reglas de workflow obligatorio.

Configuración rápida

npx openprompt-lang integrate --all

Esto genera:

| 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 — 15 herramientas para todos los editores (11 originales + 4 de conocimiento) |

MCP Server

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:

Herramientas de proyecto y validación:

| Herramienta | Descripción | |------------|-------------| | validate | Pre-commit: escanea anotaciones del proyecto | | lint_file | Lint detallado de un archivo | | parse_code | Valida sintaxis de anotaciones inline | | context | Extrae contexto del proyecto | | search_templates | Busca templates por keyword | | teach_template | Lección + código de un template | | generate_tests | Genera tests desde @learn-error | | analyze_project | Auditoría completa del proyecto | | init_project | Inicializa proyecto nuevo | | component_list | Lista componentes disponibles | | scaffold_project | Crea estructura de carpetas |

Herramientas de conocimiento (NUEVO):

| Herramienta | Descripción | |------------|-------------| | knowledge_search | Busca en los 33 libros empaquetados por query. Retorna resultados rankeados con snippets. | | knowledge_list | Lista los 33 libros disponibles con metadatos. | | knowledge_read | Lee el contenido completo de un capítulo específico de un libro. | | knowledge_concept | Expande un concepto semántico y muestra conceptos relacionados del grafo. |

## Result: success|error|warning
<summary>
### Details
- <detalle 1>
### Recommended Actions
- <acción 1>

| Contexto | Herramienta | Descripción | |---|---|---| | Auditar proyecto | analyze_project(dir) | Primera herramienta en proyectos nuevos. Retorna config, conteo de archivos, estadísticas | | Validar | validate([dir, filePath]) | Escanea proyecto/archivo buscando errores. Usar antes de commits | | | lint_file(filePath, strict) | Debug detallado de un archivo. Más información que validate | | | parse_code(code) | Valida sintaxis inline. Útil durante generación de código | | Contexto | context([dir, scope]) | Extrae estructura del proyecto con resumen de config | | Templates | search_templates(query, lang) | Busca templates por keyword (button, auth, fetch) | | | teach_template(templateId, showCode) | Lección estructurada, prácticas y código del template | | 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 + Work Context)

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
2. validate         → diagnosticar errores
3. lint_file        → debug profundo de archivos con errores
4. fix + @learn-error → documentar lo aprendido
5. generate_tests   → prevenir regresión
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, además del sistema work-context obligatorio.

Uso manual (sin integrate)

Crea .opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openPrompt": {
      "type": "local",
      "command": ["npx", "openprompt-lang", "mcp"],
      "enabled": true
    }
  },
  "skills": {
    "paths": [".opencode/skills"]
  },
  "default_agent": "openPrompt",
  "instructions": ["AGENTS.md"]
}

Luego agrega .opencode/agent/openPrompt.md (instrucciones del agente) y .opencode/skills/openPrompt/SKILL.md (skill). O simplemente ejecuta npx openprompt-lang integrate --all.

Antigravity In