openprompt-lang 1.4.0 → 1.6.0

package/bin/cli.js

@@ -10,18 +10,12 @@ import { readFileSync } from "fs"
 import { join, dirname } from "path"
 import { fileURLToPath } from "url"
 
-import { register as registerInit } from "../src/cli/commands-init.js"
 import { register as registerContext } from "../src/cli/commands-context.js"
-import { register as registerAi } from "../src/cli/commands-ai.js"
-import { register as registerLang } from "../src/cli/commands-lang.js"
-import { register as registerKnowledge } from "../src/cli/commands-knowledge.js"
-import { register as registerWork } from "../src/cli/commands-work.js"
-import { register as registerLearning } from "../src/cli/commands-learning.js"
 import { register as registerOpl } from "../src/cli/commands-opl.js"
 import { register as registerMisc } from "../src/cli/commands-misc.js"
 import { register as registerWorkflow } from "../src/cli/commands-workflow.js"
 import { register as registerTeach } from "../src/cli/commands-teach.js"
-import { register as registerBoost } from "../src/cli/commands-boost.js"
+
 
 import { handleUncaughtErrors, EXIT_CODES } from "../src/utils/errors.js"
 
@@ -58,17 +52,10 @@ program
 registerOpl(program)
 
 // Registrar comandos existentes
-registerInit(program)
 registerContext(program)
-registerAi(program)
-registerLang(program)
-registerKnowledge(program)
-registerWork(program)
-registerLearning(program)
 registerMisc(program)
 registerWorkflow(program)
 registerTeach(program)
-registerBoost(program)
 
 try {
   await program.parseAsync(process.argv)

package/bin/mcp-plan.js

@@ -4,8 +4,8 @@
 // @contract(in: argv -> out: void, sideEffect: inicia servidor MCP modo plan)
 // @limit(lines: 20)
 
-import { startPlanServer } from "../src/mcp-plan-server.js"
+import { startServer } from "../src/mcp-server.js"
 
-// MCP Plan Server — modo planificación
-// opencode lo ejecuta como segundo MCP para el wizard de stack/folder
-await startPlanServer()
+// MCP Plan Server — tools de planificación están ahora en el servidor principal
+// (merged in BUG-012: mcp-plan-server.js eliminado, tools integradas en mcp-server.js)
+await startServer()

package/docs/02-STANDARDS/AGENTS.template.md

@@ -1,6 +1,6 @@
 # AGENTS.template.md — Plantilla Universal para Proyectos
 
-> **Versión:** 1.0
+> **Versión:** 2.0 (estructura navegable)
 > **Uso:** La IA debe ejecutar el Protocolo de Inicialización al detectar un proyecto sin AGENTS.md o con AGENTS.md incompleto.
 
 ---
@@ -25,11 +25,16 @@ Leer package.json:
 ejecutar: opl init → Crea prompt-lang.json y estructura base docs/
 ```
 
-### Paso 3: Generar AGENTS.md con el stack detectado
+### Paso 3: Generar AGENTS.md y secciones
 ```
-Copiar ESTE archivo como AGENTS.md en la raíz del proyecto.
-Reemplazar "## Stack" con las tecnologías detectadas.
-Reemplazar "## Perfil" según nivel (senior por defecto).
+1. Copiar ESTE archivo como AGENTS.md en la raíz del proyecto (versión resumida)
+2. Reemplazar "## Stack" con las tecnologías detectadas
+3. CREAR docs/02-STANDARDS/sections/ con archivos extraídos:
+   - 01-workflow.md → Workflow + gates + enforcement
+   - 02-annotations.md → @kind, @limit, cobertura
+   - 03-conventions.md → Stack detallado, código, UI
+   - 04-commands.md → CLI, PRA, knowledge
+   - 05-reference.md → Doc structure, setup
 ```
 
 ### Paso 4: Detectar archivos fuente sin anotaciones
@@ -87,3 +92,4 @@ senior
 ## Referencias
 - Framework: openPrompt-Lang
 - Tickets OPL: `opl ticket list`
+- Estructura navegable: `docs/02-STANDARDS/sections/` — 01-workflow, 02-annotations, 03-conventions, 04-commands, 05-reference

package/docs/02-STANDARDS/sections/00-first-5-min.md

@@ -0,0 +1,40 @@
+// @use(kind, contract, limit)
+// @kind(guide)
+// @contract(in: session start -> out: readiness, sideEffect: AI carga los contextos correctos, evita errores comunes)
+// @limit(lines: 40)
+
+# 🆕 Primeros 5 Minutos — Playbook de Inicio
+
+Esto se lee **al empezar cualquier sesión** (después de AGENTS.md + 01-workflow.md + 02-annotations.md).
+
+## 1. ¿Qué estoy haciendo?
+| Si la tarea es... | Workflow |
+|-------------------|----------|
+| Bugfix / depuración | Bugfix → ticket primero, fix rápido, validate |
+| Feature nueva | Feature → plan + implementación con anotaciones |
+| Refactor | Refactor → analyze_blast_radius, plan, implementar |
+| Research / exploración | Research → knowledge_search, recall |
+| Revisión de PR | Review → validate, lint_file |
+
+## 2. Pasos automáticos al arrancar
+
+```
+1.  analyze_project       → entender estructura
+2.  context_unified       → búsqueda cruzada en 7 fuentes
+3.  recall "tema"         → errores pasados relacionados
+4.  Todowrite             → desglosar tareas
+5.  work_context_start    → iniciar tracking
+```
+
+## 3. Errores comunes al empezar (no repetir)
+
+- ❌ Leer el AGENTS.md completo → leer solo índice, cargar bajo demanda
+- ❌ Implementar sin `work_context_start` → siempre iniciar sesión primero
+- ❌ Crear componente sin buscar template primero → `search_templates` + `teach_template`
+- ❌ Hacer un refactor sin `analyze_blast_radius` → siempre analizar impacto
+- ❌ Commitear sin `opl validate` → el pre-commit hook te va a bloquear igual
+
+## 4. ¿Tengo claro lo que voy a hacer antes de escribir?
+
+Sí → `work_context_plan` si es feature/refactor, después implementar
+No → `context_unified` + `knowledge_search` primero

package/docs/02-STANDARDS/sections/01-workflow.md

@@ -0,0 +1,150 @@
+// @use(kind, contract, limit)
+// @kind(guide)
+// @contract(in: session awareness -> out: workflow selected, sideEffect: AI sigue el flujo correcto)
+// @limit(lines: 150)
+
+# Workflow OPL — Reglas Absolutas y Flujo Único
+
+→ Complementos: [02-annotations.md](./02-annotations.md) para reglas de anotación | [00-first-5-min.md](./00-first-5-min.md) para onboarding rápido
+
+## ⛔ Regla Fundacional
+`@limit(lines: N)` NO es sugerencia — bloquea el commit. Refactorizar antes de committiar.
+Excepción: `// @limit(lines: 250, reason: "justificación")` documenta deuda técnica.
+
+## 🧭 Árbol de Decisión — ¿Qué flujo sigo?
+
+```
+¿Qué tipo de tarea?
+├── Bugfix / debug
+│   → ticket → analyze_blast_radius → fix → @learn-error → validate → close
+├── Feature nueva
+│   → context_unified → plan → implementar (anotaciones primero) → validate → close
+├── Refactor / deuda técnica
+│   → analyze_blast_radius → plan → implementar → validate → close
+├── Research / explorar
+│   → knowledge_search + recall → documentar hallazgos → close
+└── Onboarding / proyecto nuevo
+    → analyze_project → domain_status → context_unified → recall → templates → close
+```
+
+## Flujo Obligatorio (8 pasos, siempre este orden)
+
+```
+1. → workflow_select          "opl workflow select <descripción>"
+                               (OBLIGATORIO — bloquea implementación)
+2. → create_ticket            "opl ticket create --title ... --severity ..."
+                               (OBLIGATORIO — bloquea escritura de código)
+3. → check_gates              workflow_selected ✓, ticket_created ✓, plan_approved ✓ (si aplica)
+4. → work_context_plan        Planificar (features/refactors, bugfixes pueden saltar)
+5. → implementar              Codificar con anotaciones OPL primero
+6. → validate                 "opl validate" antes de cerrar
+7. → docs_updated             Actualizar documentación (OBLIGATORIO)
+8. → work_context_close       Cerrar sesión con reporte
+```
+
+**Regla #1:** `workflow select` primero — Sin workflow 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 docs no se cierra sesión.
+**Regla #4:** `work_context_plan` para features/refactors — Bugfixes simples pueden saltar.
+
+## Gates Evaluados Automáticamente
+
+| Gate | Verifica | Bloquea |
+|------|----------|---------|
+| `workflow_selected` | `workflow select` ejecutado | Siempre |
+| `ticket_created` | Ticket abierto existe | Siempre |
+| `plan_approved` | Plan reciente existe | Features/refactors |
+| `docs_updated` | Docs actualizados (<4h) | Antes de cerrar |
+
+## Enforcement MCP (v0.10.0+)
+
+El servidor MCP rastrea tu sesión y verifica que sigas el workflow. Si omites pasos:
+- **Guide mode** (default): Recibirás sugerencias con tiempo ahorrado estimado — el tool se ejecuta igual
+- **Gate mode** (`strictMode: true` en prompt-lang.json): El tool se BLOQUEA hasta que cumplas los prerrequisitos
+- **Learn mode**: Si encuentras errores tras omitir pasos, se crea un ticket automático
+
+### Flujo Obligatorio (MCP tools)
+
+```
+1. analyze_project     → Conoce el proyecto (30s, ahorra ~15min)
+2. workflow_check      → Verifica qué pasos faltan en tu sesión
+3. context_unified     → Búsqueda cruzada en 7 fuentes
+4. knowledge_search o recall → Buscar antes de crear (10s, ahorra ~30min)
+5. work_context_plan   → Planificar antes de implementar (1min, ahorra ~1hr)
+6. work_context_start  → Iniciar sesión con tracking
+7. work_context_close  → Cerrar sesión y registrar métricas
+```
+
+### Workflow: Debugging annotation errors
+1. `analyze_project` → ver el panorama
+2. `validate` → encontrar errores
+3. `lint_file` → debug de archivos específicos
+4. Fix + `@learn-error` → documentar
+5. `generate_tests` → tests de regresión
+6. `validate` → verificar fix
+
+### Workflow: Nueva feature o implementación
+1. `context_unified` + `knowledge_search` → buscar antes de crear
+2. `domain_status` → ver dominio activo y patrones
+3. `search_templates` + `teach_template` → aprender patrones existentes
+4. `work_context_plan` → planificar
+5. `work_context_start` → iniciar sesión
+6. Implementar con anotaciones
+7. `validate` → verificar
+8. `work_context_close` → cerrar sesión
+
+### Workflow: Onboarding a proyecto nuevo
+1. `analyze_project` → estructura
+2. `domain_status` → dominios y patrones
+3. `context_unified` → contexto completo en 7 fuentes
+4. `recall "keyword"` → memoria del proyecto
+5. `search_templates` + `teach_template` → patrones clave
+
+### Autonomía Táctica (Tridente para mutaciones)
+`analyze_blast_radius` → `ast_patch_mutate` → `execute_sandbox`
+1. No se muta código a ciegas
+2. Toda mutación pasa por análisis de impacto previo
+3. Todo parche se verifica en sandbox antes de cerrarse
+
+## Hook pre-commit
+`.husky/pre-commit` corre `npx openprompt-lang validate --strict` antes de cada commit.
+Bloquea commits si hay violaciones @limit o errores de anotaciones.
+Emergencias: `git commit --no-verify` (documentar por qué).
+
+Setup completo: [05-reference.md](./05-reference.md#setup-de-enforcement)
+
+## ⛔ NUNCA
+- Cerrar sesión sin `work_context_close`
+- Implementar sin `work_context_start`
+- Fixear bug sin crear ticket
+- Hacer commit sin `opl validate --strict`
+- Saltear `opl workflow select`
+- Detectar bug y fixearlo sin ticket primero
+- Cerrar sesión sin actualizar documentación
+- Corregir error sin `@learn-error` (→ ver [02-annotations.md](./02-annotations.md#-learn-error))
+- Crear plan sin revisar `recall` primero
+- Crear archivo sin `@use` con anotaciones
+- Modificar `*.template.*` directamente
+- Modificar `prompt-lang.json` sin consultar
+
+## 📋 Reporte de Workflow (obligatorio al cerrar)
+```
+## 📋 Reporte de Workflow — Sesión [FECHA]
+
+### ✅ Pasos Ejecutados
+| Paso | Comando | Resultado |
+|------|---------|-----------|
+| 1. Iniciar sesión | work_context_start | ✅ |
+| 2. Analizar proyecto | analyze_project | ✅ |
+| 3. Validar anotaciones | opl validate | ✅ 0 errores |
+| 4. Buscar errores previos | recall | ✅ N encontrados |
+| 5. Seleccionar workflow | opl workflow select | ✅ |
+| 6. TODO list | todowrite | ✅ N tareas |
+
+### 🔍 Validación Final
+| Check | Resultado |
+|-------|-----------|
+| tsc --noEmit | ✅ 0 errores |
+| opl validate | ✅ 0 errores |
+| Cobertura @use | X% |
+```

package/docs/02-STANDARDS/sections/02-annotations.md

@@ -0,0 +1,89 @@
+// @use(kind, contract, limit)
+// @kind(reference)
+// @contract(in: file creation/modification -> out: properly annotated code, sideEffect: prevents commit blocks from @limit violations)
+// @limit(lines: 100)
+
+# Anotaciones OPL — @kind, @limit, Cobertura
+
+→ Complementos: [01-workflow.md](./01-workflow.md) para flujo de trabajo | [03-conventions.md](./03-conventions.md) para stack y convenciones de código
+
+## 📐 Límites de Líneas (OBLIGATORIOS, bloquean commit)
+
+| @kind | Líneas máx | Anotaciones requeridas | Prohibido |
+|-------|------------|------------------------|-----------|
+| `hook` | 80 | `@contract` | `@props` |
+| `component` | 120 | `@props` | `@contract` |
+| `page` | 200 | `@compose` | — |
+| `service` | 150 | `@contract` | `@props` |
+| `store` | 100 | `@deps` | — |
+| `layout` | 150 | — | — |
+| `util` | 100 | — | `@state` |
+| `type` | sin límite | — | `@limit` |
+
+Excepción documentada:
+```typescript
+// @limit(lines: 250, reason: "justificación obligatoria de por qué se excede")
+```
+Sin `reason`, el límite bloquea en strict mode. Con `reason`, aparece como deuda documentada.
+
+## 📋 Reglas de Cobertura de Anotaciones
+
+**Deben tener `@use` al inicio:**
+
+| Patrón | @kind requerido |
+|--------|-----------------|
+| `src/lib/api/*.ts` | `@kind(service)` |
+| `src/lib/*.ts` | `@kind(service)` o `@kind(utility)` |
+| `src/features/*/hooks/*.ts` | `@kind(hook)` |
+| `src/pages/*.tsx` | `@kind(page)` |
+| `src/features/*/pages/*.tsx` | `@kind(page)` |
+| `src/contexts/*.tsx` | `@kind(context)` |
+| `src/features/*/components/*.tsx` | `@kind(component)` |
+
+**KPI cobertura objetivo: > 80% de archivos fuente con @use**
+
+## Secuencia obligatoria de anotaciones
+1. Identificar archivo y su capa (commands/, core/, persistence/, etc.)
+2. Definir propósito, responsabilidades y límites
+3. Escribir anotaciones en este orden: `@kind` → `@contract` → `@limit` → `@deps` → `@pattern` → `@teachMe`/`@level`/`@prerequisite`/`@learning-objective`
+4. Validar coherencia con capa, dominio y workflow activo
+5. **Recién entonces** implementar la lógica
+
+## Anotaciones esperadas por capa
+
+| Capa | @kind | @contract | @limit | @deps | Otras |
+|------|-------|-----------|--------|-------|-------|
+| commands/ | `module` | Requerido | 150 | Según deps | — |
+| core/ | `module` | Requerido | 150 | Según deps | @pattern si aplica |
+| persistence/ | `module` | Requerido | 150 | Según deps | — |
+| wizard/ | `module` | Requerido | 200 | Según deps | @pattern si aplica |
+| docgen/ | `module` | Requerido | 200 | Según deps | @pattern si aplica |
+
+**Regla:** No iniciar implementación si el archivo no tiene anotaciones OPL primero.
+
+## 🧠 @learn-error — Aprendizaje Obligatorio de Errores
+
+Cada vez que se corrige un error:
+1. Crear ticket: `opl ticket create --title "..." --severity <level>`
+2. Fixear el bug
+3. Documentar con `@learn-error` en el código:
+```typescript
+// @learn-error(id: '<CATEGORÍA>-<NNN>', input: 'qué causó el error', expected: 'cómo debería ser', actual: 'qué pasó', fix: 'cómo se corrigió')
+```
+4. Cerrar ticket: `opl ticket close BUG-XXX`
+5. El `@learn-error` se consulta automáticamente con `recall` en la próxima sesión
+
+**Antes de crear un plan:** ejecutar `recall` para buscar @learn-error relacionados. Incluir precauciones en el plan.
+
+## @scar — Cicatrices de Guerra (conocimiento negativo)
+```typescript
+// @scar(id: 'modal-scroll-lock', symptom: 'Modales anidados rompen scroll', cause: 'Estado local aislado', fix: 'hook centralizado', detect: 'document.body.style.overflow === "hidden" && !useLayoutScrollLock', severity: 'blocker', domains: ['frontend', 'accessibility'])
+```
+Campos: id (req), symptom (req), cause (req), fix (req), detect (opcional), severity (opcional: blocker/critical/warning/info), domains (opcional)
+
+## Contratos Abstractos
+IR que separa Contrato (esencia) de Sintaxis (framework):
+```
+Contrato Real = Contrato Abstracto + Adapter Sintáctico
+```
+- `opl contract list/show/search` — Gestionar contratos

package/docs/02-STANDARDS/sections/03-conventions.md

@@ -0,0 +1,56 @@
+// @use(kind, contract, limit)
+// @kind(reference)
+// @contract(in: coding task -> out: code following project conventions, sideEffect: consistent code style across files)
+// @limit(lines: 60)
+
+# Convenciones — Stack, Código, UI, Templates
+
+→ Complementos: [02-annotations.md](./02-annotations.md) para reglas de anotación por capa | [04-commands.md](./04-commands.md) para templates disponibles via teach_template
+
+## Stack del proyecto
+- React 19 + TypeScript + Vite 7 + Tailwind v4 (Estándar consistente)
+- Node.js + Express (TypeScript, ESM)
+- Spring Boot + Java (Controllers, Services, Repositories, DTOs)
+- Supabase (Backend/Auth/Storage)
+- Lucide React (Iconos) · Sonner (Notificaciones) · Radix UI (Primitivos accesibles)
+
+## Módulos de Lenguaje (Templates)
+| Módulo | Templates | Versión |
+|--------|-----------|---------|
+| React + TypeScript (Vite) | 23 | 1.1.0 |
+| Vue 3 + Nuxt | 12 | 1.0.0 |
+| Node.js + Express (TypeScript) | 12 | 1.0.0 |
+| Spring Boot (Java) | 8 | 1.0.0 |
+| OpenPrompt Core Knowledge | 3 | 1.0.0 |
+
+## Convenciones de Código
+- **Context Engine**: openPrompt-Lang (@kind, @contract, @limit annotations)
+- **Anotaciones primero**: No escribir implementación sin anotaciones previas
+- **Exports**: Named Exports sobre Default Exports
+- **Funciones**: Preferir `export function Name() {}` sobre arrow functions para componentes
+- **Tipado**: NO usar `any`. Tipar retornos de hooks y props de componentes.
+- **Iconos**: Preferir SVG inline o componentes dedicados si son pocos
+- **Validación**: `npx openPrompt-Lang validate` antes de cada commit
+
+### Convenciones por lenguaje
+- **React**: component/page/hook/service/store → shadcn/ui pattern (cva + cn())
+- **Node.js**: controller/service/route/middleware/model/repository → ESM imports, no CommonJS
+- **Java/Spring Boot**: controller/service/repository/entity/DTO → getters/setters explícitos (no Lombok)
+
+## UI & Diseño
+- **Colores**: El usuario elige la paleta. La IA NO inventa colores base a menos que se le pida.
+- **Modo Oscuro**: Soporte nativo (default: dark).
+- **Componentes**: Patrón shadcn/ui (cva + cn()).
+- **Layout**: Header tipo "pill flotante" centrado con backdrop-blur para landing pages.
+
+## Templates disponibles
+- `button-shadcn`, `input-shadcn`, `select-shadcn`, `card-shadcn`, `modal-dialog`, `datatable-shadcn`
+- `hook-useAuth`, `hook-useDebounce`, `hook-usePagination`, `hook-useForm`
+- `service-api`
+
+Buscar: `search_templates` / `teach_template` para aprender patrones existentes.
+
+## Calidad y QA
+- **Errores**: Documentar con `// @learn-error id=ID fix='...'`
+- **Tests**: `npx openPrompt-Lang qa-gen` tras corregir errores
+- **Anotaciones**: `@use()` al inicio si se usan utilidades externas

package/docs/02-STANDARDS/sections/04-commands.md

@@ -0,0 +1,54 @@
+# Comandos OPL — CLI, PRA, Knowledge, Pipeline
+
+## CLI — Comandos principales
+- `opl` (sin args) → Pantalla de bienvenida "puerta de entrada"
+- `opl help` → Misma pantalla de bienvenida
+- `opl tutorial` → Recorrido guiado interactivo (7 min)
+- `opl workflow select <desc>` → Seleccionar workflow con detección automática
+- `opl ticket create/list/close` → Gestión de tickets (OBLIGATORIO antes de código)
+- `opl init --knowledge` → Configurar biblioteca personal ~/.opl/knowledge/
+- `opl upgrade` → Migrar configuración a versión actual
+- `opl validate [--file <path>] [--strict]` → Validar anotaciones
+- `opl lint_file <path>` → Debug de anotaciones de archivo específico
+- `opl generate_tests` → Generar tests de regresión desde @learn-error
+- `opl session doc/close/diff` → Gestión de sesiones con documentación
+- `opl doc flow/framework` → Generar documentación (Mermaid, FRAMEWORK.md)
+
+## Comandos de Conocimiento
+- `opl index [path]` → Navegar conocimiento por niveles
+- `opl read <dominio>/<id>` → Leer contenido (--chapter n --full)
+- `opl search <query>` → Búsqueda híbrida (tags + fulltext + semántica)
+- `opl system [name]` → Explorar sistemas de conocimiento (10 sistemas)
+- `opl contract list/show/search` → Gestionar contratos abstractos
+- `opl graph [concept]` → Grafo de relaciones entre conceptos
+
+## Production Readiness Assessment (PRA)
+- **7 dimensiones**: Funcionalidad (25%), Calidad (20%), Seguridad (15%), Resiliencia (10%), Observabilidad (10%), Compliance (10%), Despliegue (10%)
+- **28 criterios** con scoring 0-100 por criterio
+- **Rangos**: 💀 Pre-Alfa (0-20) → 🔴 Alfa (21-40) → 🟡 Beta (41-60) → 🟢 RC (61-80) → 🔵 Prod-Ready (81-95) → 🟣 Hardened (96-100)
+- **Zero-tolerance**: F5 (transacciones atómicas), S2 (deny-by-default), S4 (no hardcoded secrets)
+- **IA ceiling**: 78 solo código / 85 con config / 90 con guías deploy
+- `opl assess [--verbose] [--save]` → Evaluar PRA
+- `opl workflow qa-assess` → Evaluación completa con PRA + recall + validate + findings
+
+## Comandos Dominio y Pattern
+- `context domain init/use/switch/clear/status/load` — Dominios modulares
+- `learn-pattern --from <docs> --type <type> --name <name>` — Extraer patrones
+- `pattern-list [--domain <domain>]` — Listar patrones por dominio
+
+Todos los comandos `knowledge list/learning search/ticket create/list/recall` aceptan `--domain`.
+
+## Pipeline Auto-curativo
+validate paso [4/5] tiene auto-healing loop:
+1. Ejecuta tsc/lint/format-check
+2. Si falla → lint:fix / format:fix
+3. Reintenta hasta 3 veces
+4. Si persiste → registra @learn-error automático
+
+Configurable en `prompt-lang.json` → `pipeline.autoheal`
+
+## Conocimiento (Knowledge)
+- **13 dominios**: payments, mobile-pwa, systems, qa, frontend, backend, accessibility, algorithms, fundamentals, architecture, typescript, saas, restaurant
+- **13 playbooks**: flow-integration, capacitor-setup, rust-ownership, scrum-workflow, frontend-react, backend-nodejs, accessibility-wcag, algorithms-patterns, fundamentals-programs, spa-auth-flow, api-rest-design, db-schema-design, microservice-architecture
+- **35 fuentes** de conocimiento empaquetadas (libros/docs + 2 proyectos reales)
+- **10 sistemas de conocimiento**: agrupaciones de fuentes que se necesitan juntas

package/docs/02-STANDARDS/sections/05-reference.md

@@ -0,0 +1,46 @@
+# Referencia — Documentación, Estructura, Setup
+
+## Documentación del proyecto
+```
+docs/
+├── INDEX.md                   ← Mapa maestro del proyecto
+├── 00-ARCHITECTURE/           ← Stack, flujos, esquemas
+├── 01-AUDITS/                 ← Auditorías de código y recursos
+├── 02-STANDARDS/              ← Convenciones, patrones, guías OPL
+│   ├── sections/              ← Archivos extraídos de AGENTS.md (carga bajo demanda)
+│   └── ticket-driven-development.md  ← Proceso TDD completo
+├── 03-SPRINTS/                ← Planificación ágil por sprint
+├── 04-TICKETS/                ← Tickets ejecutables por sprint
+└── 05-REFERENCES/             ← Referencias externas
+```
+
+## Referencia Canónica
+- **Manual completo**: `.openprompt/FRAMEWORK.md` — anotaciones, comandos CLI, MCP, dominios, módulos, reglas estrictas
+- **Proceso TDD**: `docs/02-STANDARDS/ticket-driven-development.md`
+- **Plantilla universal AGENTS.md**: `docs/02-STANDARDS/AGENTS.template.md`
+- **Pre-commit hook**: `scripts/pre-commit-opl.sh` (deployable), `.husky/pre-commit` (activo)
+- **Enforce setup**: `scripts/opl-enforce-setup.mjs` (interactivo), `npm run opl:enforce`
+
+## Setup de Enforcement
+```bash
+# Configurar enforcement completo (Ollama + pre-commit hook + agentes)
+npm run opl:enforce
+
+# O manualmente:
+cp scripts/pre-commit-opl.sh .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+## Contexto Navegable (NIVEL 0-3)
+La IA debe navegar el contexto por niveles:
+- **NIVEL 0**: AGENTS.md — Índice (~200 tokens). Leer siempre primero.
+- **NIVEL 1**: sections/01-workflow.md + 02-annotations.md — Obligatorios (~750 tokens)
+- **NIVEL 2**: sections/03-conventions.md + 04-commands.md — Bajo demanda (~600 tokens)
+- **NIVEL 3**: sections/05-reference.md — Solo cuando necesitas setup o estructura (~200 tokens)
+
+## Proceso de Documentación Pre-Close
+Cada sesión se documenta antes de cerrar:
+- `opl session doc` → Documentación automática
+- `opl session close` → Cerrar con validación
+- Gate mode bloquea close si falta documentación
+- Cada sesión deja: resumen.md, decisiones.md, errores.md, aprendizajes.md

package/docs/02-STANDARDS/sections/06-project-setup.md

@@ -0,0 +1,137 @@
+# Project Setup — AI Playbook
+
+Usa esto cuando necesites configurar un proyecto OPL o entender los requisitos de un proyecto nuevo.
+
+## Dos modos
+
+### Modo A: Proyecto nuevo (no hay archivos)
+Usa `opl init` (materials-first inference). El CLI pregunta "¿Qué quieres construir?" en **1 pregunta conversacional** — no 54 preguntas secuenciales.
+
+El AI detecta automáticamente: framework, lenguaje, bundler, CSS, UI, extensiones.
+
+**Si la inferencia es ambigua o incompleta**, puedes hacer preguntas adicionales usando las guías abajo. Pero no las hagas todas — solo las necesarias para resolver ambigüedades.
+
+### Modo B: Proyecto existente (hay archivos)
+`opl init` infiere desde materiales reales:
+- `package.json` → dependencias, scripts
+- `tsconfig.json` → JSX, module, target
+- Estructura de archivos → framework, patrones
+- Descripción opcional del usuario
+
+Cero preguntas si la inferencia es completa.
+
+---
+
+## Preguntas de Discovery (para AI, conversacionales)
+
+Si la inferencia no es suficiente, usa estas preguntas **como guía, no como formulario**. Pregunta naturalmente, una conversación fluida. No preguntes todo — solo lo que falte.
+
+### 1️⃣ Problema y Visión
+- ¿Qué problema resuelve el sistema?
+- ¿Para quién es?
+- ¿Qué valor diferencial aporta?
+- ¿Qué pasa si no existe?
+
+### 2️⃣ Usuarios y Actores
+- ¿Quiénes usan el sistema? (roles/usuarios)
+- ¿Hay usuarios externos o internos?
+- ¿Hay otros sistemas que interactúan?
+- ¿Qué permisos necesita cada rol?
+
+### 3️⃣ Alcance del MVP (MoSCoW)
+- MUST: ¿Qué es indispensable para el MVP?
+- SHOULD: ¿Qué es importante pero no crítico?
+- COULD: ¿Qué se puede agregar después?
+- WON'T: ¿Qué queda fuera del alcance?
+
+### 4️⃣ Funcionalidades Clave
+- ¿Cuáles son las 5-7 capacidades principales?
+- ¿Cuál es el flujo principal del usuario?
+- ¿Qué funcionalidades tienen más riesgo técnico?
+
+### 5️⃣ Restricciones
+- ¿Restricciones técnicas? (stack, hosting, escalabilidad)
+- ¿Restricciones legales? (GDPR, facturación, retención)
+- ¿Restricciones de negocio? (presupuesto, timeline)
+- ¿Restricciones de UX? (idioma, accesibilidad, dispositivos)
+
+### 6️⃣ Integraciones
+- ¿APIs externas? (pagos, auth, envíos, notificaciones)
+- ¿Servicios internos? (microservicios, BD, colas)
+- ¿Webhooks o eventos?
+
+### 7️⃣ Riesgos
+- ¿Qué puede salir mal? (riesgos técnicos)
+- ¿Riesgos de negocio?
+- ¿Dependencias críticas?
+- ¿Qué riesgos necesitan mitigación inmediata?
+
+### 8️⃣ Criterios de Éxito
+- ¿Cómo saber si el proyecto está bien encaminado?
+- ¿Cuáles son los KPIs del MVP?
+- ¿Qué definirá que el proyecto es exitoso?
+
+---
+
+## Technical Stack — preguntas de refinamiento por tipo de proyecto
+
+Usa SOLO si el usuario no mencionó el área y necesitas decidir.
+
+### API
+- Autenticación: none | JWT | Supabase | Auth.js | Clerk
+- Base de datos: none | SQLite | PostgreSQL | MongoDB | Supabase
+- ORM: none | Drizzle | Prisma | TypeORM | Knex
+- Validación: none | Zod | Yup | Joi
+- Testing: Vitest | Jest | none
+
+### Web
+- Routing: React Router | TanStack Router | File-based | none
+- Data fetching: TanStack Query | SWR | RTK Query | none
+- State management: Zustand | Redux Toolkit | Jotai | Context only | none
+- Styling: Tailwind | CSS Modules | Styled Components | Vanilla CSS
+
+### Mobile
+- Framework: React Native | Capacitor | Tauri
+- Navigation: React Navigation | File-based (Expo) | none
+
+### Desktop
+- Framework: Tauri | Electron
+
+### Library
+- Bundler: tsup | Rollup | Vite library mode
+- Publish: npm | GitHub Packages | none
+
+---
+
+## Convenciones de configuración (para IA)
+
+Cuando generes `prompt-lang.json` tras el setup:
+
+```json
+{
+  "name": "<project-name>",
+  "version": "0.1.0",
+  "lenguaje": "react | vue | node | springboot",
+  "strictMode": true,
+  "stack": {
+    "base": ["react", "typescript", "vite", "tailwind"],
+    "ui": "shadcn | mantine | none",
+    "extensions": ["supabase", "stripe"],
+    "domain": "general | ecommerce | saas"
+  },
+  "mcp": {
+    "servers": { "OPL": "src/mcp-server.js" },
+    "protocol": "json-rpc-2.0"
+  }
+}
+```
+
+## Estructura de directorios (init crea esto)
+
+```
+.opencode/work-context/PLANS/
+.opencode/work-context/REPORTS/
+.openprompt/
+docs/COMMITS/
+docs/02-STANDARDS/
+```

package/docs/AI_IMPROVEMENTS.md

@@ -2,3 +2,6 @@
 
 | Fecha | Mejora | Estado |
 |---|---|---|
+| 2026-06-04 | AGENTS.md rediseñado como índice navegable (418 líneas → 36 líneas). Contenido extraído a 5 secciones bajo demanda en `docs/02-STANDARDS/sections/`. Incluye: `00-first-5-min.md` (playbook de inicio), `01-workflow.md` (workflow + gates + decision tree), `02-annotations.md` (@kind, @limit, @learn-error, @scar), `03-conventions.md` (stack, código, UI), `04-commands.md` (CLI, PRA, knowledge), `05-reference.md` (doc structure, setup). La IA lee ~1K tokens base + 0-300 bajo demanda (vs ~1,800 del monolito). | done |
+| 2026-06-04 | @learn-error AGENTS-001 y AGENTS-002 documentan el problema del monolito y la falta de triggers de lectura. Triggers agregados al índice para secciones bajo demanda. | done |
+| 2026-06-04 | AGENTS.template.md actualizado a v2.0 — instruye crear estructura seccionada en lugar de AGENTS.md plano. | done |