![\"npm](\"https://img.shields.io/npm/v/youmindag?color=blue&label=npm\")
\n ![\"license\"](\"https://img.shields.io/npm/l/youmindag\")
\n ![\"GitHub](\"https://img.shields.io/github/stars/CESARBR2025/youmindag?style=flat\")
\n ![\"Node](\"https://img.shields.io/badge/node-%3E%3D18-brightgreen\"){kind=icon}
\n ![\"opencode](\"https://img.shields.io/badge/opencode-native%20plugin-purple\"){kind=icon}
\n\n
\n Tu agente entiende tu proyecto desde el primer mensaje.
\n Una lĂnea inyecta arquitectura, dependencias, reglas y esquema de BD a Claude Code, Cursor, opencode y Copilot.\n
\n npx youmindag\n
\n Instalación ·\n El caso real ·\n Cómo funciona ·\n Compatibilidad ·\n La historia\n
\n\n\n\n đ„ Demo en terminal â prĂłximamente\n
\n\n---\n\n## đ El caso real\n\nNo usamos las cifras de npm (\"+2,000 instalaciones\") porque probablemente estĂĄn infladas por bots de seguridad que escanean cada versiĂłn publicada, no por uso real. En vez de eso, esto es un caso medido en un proyecto real:\n\n\n ![\"GrĂĄfica:](\"./assets/tokens-ahorrados.svg\")
\n
\n\n| Proyecto | Archivos | LĂneas | Tokens antes | Tokens despuĂ©s | Ahorro |\n|---|---|---|---|---|---|\n| Parrilla Norteña Soft | 149 | 26,000 | 30,033 | 9,137 | **~70%** |\n\n
\n\nEsa diferencia es lo que el agente ya no tiene que \"descubrir a mano\" leyendo archivo por archivo antes de poder trabajar en una tarea.\n\n## đŻ El problema\n\nCuando trabajas con AI coding tools (opencode, Claude Code, Cursor, etc.) en proyectos reales, el agente:\n\n- â **No sabe** la estructura del proyecto\n- â **Gasta tokens** buscando archivos que deberĂa conocer\n- â **No conoce** las reglas de arquitectura\n- â **Ignora** dependencias entre mĂłdulos\n\n## â La soluciĂłn\n\nYouMindAG inyecta un **sistema de contexto completo** en tu proyecto en 30 segundos:\n\n| Componente | QuĂ© resuelve |\n|-----------|-------------|\n| `boveda/` | DocumentaciĂłn estructurada (Obsidian-ready) |\n| `.opencode/` | Plugin que auto-carga contexto segĂșn la tarea |\n| `scripts/` | Analizador de tareas, extractor de BD |\n| `AGENTS.md` | Reglas + prohibiciones + checklist |\n| Graphify | Grafo de dependencias del proyecto |\n\n## đ InstalaciĂłn\n\n```bash\ncd /ruta/a/mi-proyecto\nnpx youmindag\n```\n\nListo. Abre un chat con tu AI coding tool y escribe cualquier tarea.\n\n**Lo que NO modifica:**\n\n- â No toca tu cĂłdigo fuente\n- â No modifica archivos existentes (solo agrega nuevos)\n- â No instala dependencias adicionales (excepto `@sentropic/graphify`)\n- â No rompe el build\n\n## đ CĂłmo funciona\n\n```\nTĂș escribes: \"agrega campo telĂ©fono al mĂłdulo X\"\n â\nPlugin detecta \"mĂłdulo X\" â ejecuta load-context.mjs\n â\nSe muestra: docs + source + graph deps + troubleshooting\n â\nEl agente ya sabe quĂ© archivos leer\n â\nImplementa siguiendo las reglas de arquitectura\n â\nnpx tsc --noEmit + npm run build + npx graphify update\n```\n\n## đ€ Compatibilidad\n\n| Herramienta | Soporte | Enforcement |\n|-------------|---------|-------------|\n| opencode | â Plugin nativo | Activo â inyecta contexto, deniega grep/glob a subagentes, checkpoints |\n| Claude Code | â Hooks + CLAUDE.md + skill | **Activo** â hooks nativos (ver abajo) |\n| Cursor | â ïž Regla generada | Pasivo â `.cursor/rules/youmindag.mdc` si existe `.cursor/` |\n| GitHub Copilot | â ïž Solo AGENTS.md | Pasivo â el agente lee el archivo, sin interceptaciĂłn |\n\n### đĄïž Enforcement para Claude Code\n\nEl texto en `AGENTS.md` es pasivo: el agente lo lee una vez y lo olvida. Para que **no pueda** saltarse el flujo, YouMindAG instala hooks nativos en `.claude/settings.json` (con merge idempotente que nunca pisa tu config):\n\n- **`PreToolUse` (Bash)** â detecta exploraciĂłn cruda (`grep -r`, `rg`, `find -name`, `cat` de cĂłdigo fuente) y redirige a `youmindag references` / `youmindag architect`. Modos configurables en `.youmindag.json`: `\"guard\": \"warn\"` (default, sugiere), `\"block\"` (bloquea con exit 2) o `\"off\"`. Escape hatch puntual: `YM_NO_GUARD=1`.\n- **`PreToolUse` (Grep/Glob/Read)** â las tools nativas de Claude Code no son \"crudas\" (son el diseño correcto), asĂ que aquĂ nunca se bloquea: cada 5 usos seguidos recuerda que `youmindag references`/`architect` traen ademĂĄs bĂłveda + grafo + historial, no solo el match/archivo. `Read` solo cuenta si el archivo es cĂłdigo fuente (`.ts`/`.tsx`/`.js`/âŠ) â leer la bĂłveda (`.md`) o config no es un salto de protocolo, asĂ que no genera ruido. Cubre el caso de leer un archivo de cĂłdigo directamente (a mano o vĂa un subagente) sin pasar antes por `references`, aunque ya se conozca la ruta exacta.\n- **`SessionStart`** â inyecta al inicio de cada sesiĂłn el protocolo, los mĂłdulos de la bĂłveda, la antigĂŒedad del grafo, las Ășltimas decisiones, y ahora tambiĂ©n **quĂ© features de la bĂłveda estĂĄn posiblemente desactualizados** (staleness por feature, ver abajo) â sin que nadie tenga que correr `doctor` para enterarse.\n- **`PostToolUse` (Edit/Write)** â dos mecanismos independientes en el mismo hook:\n - Cada 10 ediciones lanza una sincronizaciĂłn **en background** (grafo + secciones auto-generables de la bĂłveda), no solo un recordatorio. El hook no espera al proceso â lo lanza desacoplado y sale de inmediato. Cooldown de 2 min entre corridas, recuperaciĂłn automĂĄtica de locks huĂ©rfanos. Desactivable con `\"autoSync\": false` en `.youmindag.json`.\n - **En cada ediciĂłn**: si el archivo tocado aparece en la tabla `## Componentes` de algĂșn `Feature.md`, avisa (cooldown de 30 min por feature) para actualizar esa doc como parte del mismo cambio â el nudge llega al agente en el momento, no al usuario despuĂ©s. No reescribe nada: la prosa narrativa la sigue escribiendo un agente con contexto real, nunca un script en background sin supervisiĂłn (ver razonamiento abajo).\n\n### đ Staleness por feature, no por repo\n\n`doctor` y el chequeo pre-install ya no comparan `boveda/` contra el repo entero (esa comparaciĂłn mide *actividad*, no *drift de contenido*: un typo en cualquier archivo sube el contador igual que reescribir un flujo completo). En su lugar, cada `Feature.md` declara su propia tabla `## Componentes` (`| Archivo | Rol |`) â la misma convenciĂłn de la plantilla â y el chequeo compara el Ășltimo commit del doc contra el Ășltimo commit de *esos archivos exactos*. El resultado te dice quĂ© doc revisar, no solo que \"algo cambiĂł\":\n\n```\nâ ïž Brechas: 3/13 features posiblemente desactualizados: Infracciones, Juzgado, Liberaciones\n```\n\nSi ningĂșn Feature.md tiene tabla de Componentes parseable, cae de vuelta al chequeo global (impreciso, pero mejor que silencio total).\n\nEsta misma detecciĂłn alimenta tanto `doctor`/`SessionStart` (te dice quĂ© revisar) como el nudge de `PostToolUse` (te avisa en el momento exacto en que tocas el cĂłdigo relevante). Deliberadamente **no existe** un modo que reescriba la prosa sola en background: contenido \"fuente de verdad\" generado sin supervisiĂłn, si se equivoca, es peor que contenido honestamente desactualizado â el objetivo es que el humano/agente nunca tenga que *acordarse* de revisar, no que nadie *revise*.\n\nSe instala automĂĄticamente si detecta `.claude/` o `CLAUDE.md`. GestiĂłn manual:\n\n```bash\nyoumindag enforce # estado\nyoumindag enforce --install # instalar hooks + CLAUDE.md + skill\nyoumindag enforce --uninstall # retirar solo las entradas youmindag\n```\n\nTodos los hooks son **fail-open**: ante cualquier error interno salen con cĂłdigo 0 y jamĂĄs dejan tu terminal sin Bash.\n\n\n Una lĂnea. Tu AI entiende tu proyecto.
\n npx youmindag\n