Failed to generate image: PlantUML preprocessing failed: [From <input> (line 18) ]

@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false

title Evolución de las Sesiones — Desde la Sesión 1 hasta 150+
legend top
    |= Couleur |= Projet |
    | <#4CAF50> | cheroliv.com |
    | <#2196F3> | plantuml-plugin |
    | <#FF9800> | bakery-plugin |
    | <#9C27B0> | magic-stick |
endlegend

concise "Sesiones Activas" as S

@S
0 is ".md bruto"
1 is "Migración
^^^^^
 Syntax Error? (Assumed diagram type: timing)

@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false

title Evolución de las Sesiones — Desde la Sesión 1 hasta 150+
legend top
    |= Couleur |= Projet |
    | <#4CAF50> | cheroliv.com |
    | <#2196F3> | plantuml-plugin |
    | <#FF9800> | bakery-plugin |
    | <#9C27B0> | magic-stick |
endlegend

concise "Sesiones Activas" as S

@S
0 is ".md bruto"
1 is "Migración
AsciiDoc"
10 is "Eager/Lazy\nformalizado"
62 is "Regla seguridad\n(site.yml)"
87 is "Cracking\ncontexto"
109 is "Optimización
-60% tokens"
133 is "133 sesiones\n240 pruebas PASS"

S@0 -> S@1 : Session 1\n(cheroliv.com)
S@1 -> S@10
S@10 -> S@62 : Session 62\n(plantuml-plugin)
S@62 -> S@87 : Session 87\n(Cry 4 help)
S@87 -> S@109 : Session 109\n(API Key Pool)
S@109 -> S@133 : Session 133\n(Aujourd'hui)

@enduml

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 15) ]

@startuml
skinparam defaultTextAlignment center
skinparam wrapWidth 200

package "Raíz del Proyecto (Eager - Auto-cargado)" {
    component "<b>AGENT.adoc</b>\nReglas absolutas\nEstructura & Convenciones" as AGENT
    component "<b>PROMPT_REPRISE.adoc</b>\nMisión de la sesión N\nResumen N-1" as PROMPT
    component "<b>INDEX.adoc</b>\nPunto de entrada\nReglas + Sesiones" as INDEX
    component "<b>*_ESSENTIALS.adoc</b>\nContexto de negocio\ncrítico" as ESS
}

package ".agents/ (Lazy - cargado bajo demanda)" {
    component "<b>sessions/N-*.adoc</b>\nArchivos detallados\nDecisiones & Output" as SESS
    component "<b>SESSIONS_HISTORY.adoc</b>\nResumen\nDate/Type/Score" as HIST
    component "<b>PROCEDURES.adoc</b>
^^^^^
 Syntax Error? (Assumed diagram type: component)

@startuml
skinparam defaultTextAlignment center
skinparam wrapWidth 200

package "Raíz del Proyecto (Eager - Auto-cargado)" {
    component "<b>AGENT.adoc</b>\nReglas absolutas\nEstructura & Convenciones" as AGENT
    component "<b>PROMPT_REPRISE.adoc</b>\nMisión de la sesión N\nResumen N-1" as PROMPT
    component "<b>INDEX.adoc</b>\nPunto de entrada\nReglas + Sesiones" as INDEX
    component "<b>*_ESSENTIALS.adoc</b>\nContexto de negocio\ncrítico" as ESS
}

package ".agents/ (Lazy - cargado bajo demanda)" {
    component "<b>sessions/N-*.adoc</b>\nArchivos detallados\nDecisiones & Output" as SESS
    component "<b>SESSIONS_HISTORY.adoc</b>\nResumen\nDate/Type/Score" as HIST
    component "<b>PROCEDURES.adoc</b>
Plantillas fin de sesión
6 pasos" as PROC
    component "<b>*_REFERENCE.adoc</b>\nArquitectura completa\nReferencias técnicas" as REF
    component "<b>COMPLETED_TASKS_ARCHIVE</b>\nTareas completadas\nPor mes" as ARCH
    component "<b>AGENT_MODUS_OPERANDI.adoc</b>\nDocumentación de estrategia\nMetodología" as MOD
    component "<b>*_REFERENCE.adoc</b>
Boot tests, A/B partition
Contextos específicos" as SPEC
}

AGENT --> PROMPT : "Referencias"
AGENT --> INDEX : "Referencias"
INDEX --> SESS : "Indexa"
INDEX --> HIST : "Indexa"
INDEX --> PROC : "Referencia"
INDEX --> ARCH : "Referencia"
INDEX --> REF : "Referencia"
PROMPT --> SESS : "archivo N-1"
PROMPT --> ESS : "Contexto de negocio"

@enduml

----
----
| magic-stick    | Session 23 | SCRIPT_VERIFICATION.adoc | 2026-04-27 |
| bakery-gradle  | Session 11 | TEST_COVERAGE_ANALYSIS   | 2026-04-27 |
| cheroliv.com   | Session 9  | TEST_COVERAGE_ANALYSIS   | 2026-04-27 |
| plantuml-gradle| Session 133| TEST_COVERAGE_ANALYSIS   | 2026-04-23 |
| jhipster-gradle-plugins | Session 1 | TEST_COVERAGE_ANALYSIS | 2026-04-28 |
----

Por favor, proporcione el texto que desea traducir del francés al español.`*_ESSENTIALS.adoc`** -- Un añadido reciente (Sesión 109, plantuml-plugin) para optimizar aún más el contexto Eager. En lugar de cargar 200 líneas de contexto empresarial en el grupo de claves API, cargo 50 líneas de lo esencial, y las otras 150 líneas permanecen en LAZY en`*_REFERENCE.adoc`.

Resultado medido: paso de**~25k tokens EAGER a ~10k tokens**(ganancia del 60%). El agente ya no necesita recordatorios que consumen energía.

==== El Eslabón Perdido : `opencode.json

Debo confesarles una cosa que casi olvidé documentar. Por encima de todos estos archivos .adoc, hay un pequeño archivo JSON sin el cual nada funciona. Se llama`opencode.json`y hace seis líneas. Literalmente seis líneas.

[source,json]
----
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENT.adoc"
  ]
}
----

Este es el archivo que le dice a Opencode: «Al iniciar, carga`AGENT.adoc`automáticamente. » Sin él, el agente es una página en blanco exactamente como lo describía al inicio del artículo. Con él, el agente ya tiene entre las manos las reglas absolutas, la arquitectura del proyecto y los comandos esenciales — antes incluso de que yo diga hola.

Descubrí por casualidad la importancia de este archivo. Sobre`bakery-plugin`, no existía. Me preguntaba por qué el agente estaba sistemáticamente más « perdido » en este proyecto que en los otros. Las reglas absolutas estaban bien dentro de`AGENT.adoc`— pero`AGENT.adoc`nunca estaba cargado. El agente solo leía lo que yo le decía que lea, manualmente, en cada sesión. Era la sesión 11 de`bakery-plugin`cuando me di cuenta de la ausencia del`opencode.json`. Lo creé — y la sesión 12 comenzó como las demás.

Este archivo es tan obvio para mí ahora que ni siquiera lo tenía en cuenta. Un error clásico del desarrollador que conoce demasiado su herramienta. Hoy, lo creo sistemáticamente *antes*`AGENT.adoc`. Es la primera piedra.

==== La dualidad de `INDEX.adoc

Otra sutileza que merece ser explicitada :`INDEX.adoc`vive en`.agents/`— una carpeta que he presentado como `LAZY`. Sin embargo, la enumero como `EAGER` en todas mis tablas. Hay una tensión aparente aquí.

La realidad de campo: los archivos`.agents/INDEX.adoc`están bien cargados automáticamente al inicio de la sesión, al mismo nivel que`AGENT.adoc` et `PROMPT_REPRISE.adoc`Ellos están en`.agents/`Por razones de organización — no invadir la raíz — pero su comportamiento es EAGER.

sobre`plantuml-plugin`, `INDEX.adoc`tiene 200 líneas y contiene las reglas absolutas *completas* con su historial (las lecciones de las sesiones pasadas), los EPICs con puntuaciones, y el portafolio de proyectos. Es el documento que el agente consulta para saber « dónde estamos». Sobre`bakery-plugin`, hace 150 líneas con la hoja de ruta y las sesiones recientes.

La redundancia voluntaria entre`AGENT.adoc` et `INDEX.adoc`Puede sorprender. Las reglas absolutas están presentes en ambos. ¿Por qué? Porque cumplen dos funciones diferentes: en`AGENT.adoc`, son *explicativas* (el storytelling de la regla, la lección aprendida); en`INDEX.adoc`, ellas son *ejecutivas*(la regla desnuda, sin justificación, para una consulta rápida). El agente lee`AGENT.adoc`una vez para *comprender* ; él vuelve a leer`INDEX.adoc`à cada sesión para *aplicar*. Dos usos, dos formatos.

[plantuml, format=svg, id=diag-dualite-agent-index, alt="Comparaison entre AGENT.adoc (narratif) et INDEX.adoc (exécutif)"]
----
@startuml
skinparam backgroundColor #FEFEFE
skinparam defaultTextAlignment center

title Dualidad AGENT.adoc ←→ INDEX.adoc
left to right direction

rectangle "AGENT.adoc\n(Raíz — EAGER)" as AGENT #E3F2FD {
  rectangle "📖 **Formato Narrativo**
El storytelling de la regla
la lección aprendida, el contexto" as NARR
  rectangle "�🏗️ **Arquitectura Completa**\nEstructura del proyecto, componentes\nBacklog detallado US" as ARCHI
  rectangle "📋 **Reglas Explicatives**
¿Por qué existe la regla?
Historial del incidente" as EXPL
}

rectangle "INDEX.adoc\n(.agents/ — EAGER)" as INDEX #E8F5E9 {
  rectangle "�⚡ **Formato Ejecutivo**
La regla desnuda, sin justificación
Consulta rápida" as EXEC
  rectangle "📊 **Roadmap & EPICs**\nTabla resumen\nProgreso, Puntuación, Prioridad" as ROAD
  rectangle "�🌐 **Portafolio de proyectos**
Visión transversal
5 proyectos sincronizados" as PORT
}

AGENT --> INDEX : "Agent lee AGENT.adoc
1 vez para **comprender**"
INDEX --> AGENT : "Agent vuelve a leer INDEX.adoc\nCada sesión para **aplicar**"

note bottom of AGENT
  Taille max : 200 lignes
end note

note bottom of INDEX
  Taille max : 200 lignes
  Source de vérité en cas de divergence
end note

@enduml
----

Esta redundancia asumida es una elección de diseño. Consume ~50 líneas adicionales de tokens EAGER — pero garantiza que el agente siempre tenga las reglas a la vista, incluso en el formato conciso que facilita la obediencia inmediata.

=== Los Archivos LAZY: El Manual del Propietario

Estos archivos viven en`.agents/`y solo se leen cuando el agente los necesita. Constituyen la verdadera riqueza del método, porque acumulan el conocimiento del proyecto sin contaminar el contexto actual.

[plantuml, format=svg, id=diag-agents-tree, alt="Arborescence complète du dossier .agents/"]
----
@startuml
skinparam folderBackgroundColor #E3F2FD
skinparam folderBorderColor #1565C0
skinparam fileBackgroundColor #FFF3E0
skinparam fileBorderColor #EF6C00

folder ".agents/" as ROOT {
  file "INDEX.adoc
(EAGER -- 200 líneas)" as IDX #E8F5E9
  file "AGENT_SESSION_MANAGER.adoc
(Sesión de plantilla)" as ASM
  file "SESSION_CHECKLIST.adoc
(¿Cuándo cambiar?)" as CHK
  file "PROCEDURES.adoc\n(6 pasos + LAZY/EAGER)" as PRO
  file "SESSIONS_HISTORY.adoc\n(Toutes sessions)" as HIS

  folder "sesiones/" as SESS {
    file "1-chore-migration.adoc" as S1
    file "109-formalización-lazy.adoc" as S109 #FFECB3
    file "133-epic11-article.adoc" as S133
    file "... +130 otros" as SMORE
  }

  folder "archivos/" as ARCH {
    file "COMPLETED_TASKS_2026-04.adoc" as CTA
    file "SESSIONS_HISTORY_83-95.adoc" as SHIST
    folder "sessions_resúmenes/" as SUM {
      file "SESSION_64_SUMMARY.adoc" as SU64
      file "SESSION_73_SUMMARY.adoc" as SU73
      file "..." as SUMORE
    }
    folder "prompts_archive/" as PARCH {
      file "PROMPT_REPRISE_S65.adoc" as PR65
      file "PROMPT_REPRISE_S75.adoc" as PR75
      file "..." as PMORE
    }
  }
}

IDX --> SESS : "Índice"
IDX --> HIS : "Índice"
IDX --> ARCH : "Referencia"

note right of S109
  Session 109 =
  Formalisation stratégie
  LAZY/EAGER
  Token : ~25k → ~10k
end note

@enduml
----

El árbol anterior muestra la estructura real de la carpeta`.agents/`sobre`plantuml-plugin`, el proyecto más maduro. Observe la profundidad en tres capas: archivos raíz (metadatos), carpeta`sessions/`(archivos cronológicos), y expediente`archives/`(agregaciones y resúmenes). Es esta profundidad la que transforma la gobernanza de un simple archivo TODO en una**memoria organizacional completa**.

**.agents/sessions/{N}-{título}.adoc**Los archivos detallados de cada sesión. Actualmente :

* `plantuml-plugin`:**133 sesiones archivadas**(de la sesión 1 al 133)
* `bakery-plugin`:**11 sesiones**
* `magic-stick` : **23 sesiones**
* `cheroliv.com`:**9 sesiones formales**+ 7 sesiones pre-sistema reconstituidas retroactivamente

Cada archivo contiene el contexto completo de la sesión, las decisiones tomadas, los problemas encontrados y su resolución, los comandos ejecutados y su salida.

**.agents/SESSIONS_HISTORY.adoc**-- Un cuadro resumen de todas las sesiones con una puntuación. Ejemplo sobre`cheroliv.com`:

----

| -6 | 2025-05 | chore | Initialisation projet Gradle/JBake | 7/10 |  1 | 2026-04-25 | chore | Migration gouvernance agent | 8/10 |  7 | 2026-04-27 | debug/fix | Correction publishSite | 9/10 |  8 | 2026-04-27 | analyse | Analyse article 0108 | 7/10

**.agents/COMPLETED_TASKS_ARCHIVE_{mois}.adoc**-- Las tareas completadas archivadas por mes, para no sobrecargar el backlog activo. Cuando una historia de usuario está completa, se mueve aquí. El backlog sigue siendo legible: máximo 10 ítems activos.

**.agents/PROCEDURES.adoc**-- Plantillas detalladas del procedimiento de fin de sesión. Larga, pero leída una sola vez por el agente cuando aprende el método. Luego, el procedimiento se vuelve mecánico.

**.agents/AGENT_MODUS_OPERANDI.adoc**-- La documentación estratégica completa. Sobre`plantuml-plugin`, este archivo hace**900+ líneas**y se llama en realidad`AGENT_METHODOLOGIES.adoc`— cambié el nombre entre la redacción de este artículo y su implementación efectiva. Este tipo de divergencia de naming es inevitable en un sistema artesanal que evoluciona. Lo importante es la convención de nomenclatura: si el archivo documenta la *méthode*, comienza por`AGENT_`o un prefijo explícito. Documenta la metodología Eager/Lazy, los patrones a seguir, los anti-patrones a evitar. Es LAZY porque un agente no necesita volver a leer toda la estrategia en cada sesión, solo cuando hay ambigüedad.

**`*_REFERENCE.adoc`** -- Las referencias técnicas específicas del proyecto. Sobre`magic-stick`, dos archivos LAZY densos :

* `AB_PARTITION_REFERENCE.adoc`(147 líneas) -- Arquitectura de partición A/B GPT, scripts`update-system.sh`, tamaños estimados, mecanismo de rollback
* `BOOT_TEST_REFERENCE.adoc`(144 líneas) -- Procedimiento QEMU + VNC para probar el arranque de la ISO sin hardware físico, lista de verificación BIOS/UEFI, limitaciones CI/CD

Sobre`plantuml-plugin`</think> </think>

* `ARCHITECTURE.adoc`(134 líneas) -- Estructura de las 11 clases de datos, puntos de atención (trampas a evitar), comandos de prueba optimizados
* `API_KEY_POOL_REFERENCE.adoc`-- Detalles completos del pool de claves (LAZY mientras que`ESSENTIALS`está EAGER)

== Los Agentes Especializados : Un Equipo Virtual

La gobernanza no se limita a archivos pasivos. He formalizado de**roles de agentes especializados**en archivos LAZY dedicados, que definen el flujo de trabajo esperado según el tipo de tarea.

|===
|agente |Archivo |rol |Proyecto |**CODIFICAR** |`CODER.adoc` |Implementación FTL/CSS/JS, etiquetas semánticas, criterios de accesibilidad |cheroliv.com |**Maestro SCRUM** |`SCRUM_MASTER.adoc` |Planificación EE. UU., desglose en sub-tareas, detección de dependencias |cheroliv.com |**PlantUML Diseñador** |`PLANTUML_DESIGNER.adoc` |Creación de diagramas, sintaxis PUML, integración JBake |cheroliv.com
|===

El archivo`CODER.adoc`sobre`cheroliv.com`contiene reglas concretas : _Un solo`<h1>`por página_, _Prefijar los caminos con`${content.rootpath}`_, _Declarar el idioma`<html lang="${content.lang!"fr"}">`_. Estas convenciones, escritas una vez, se respetan automáticamente por el agente desde la sesión 1.

El archivo`SCRUM_MASTER.adoc`impone una estructura de entregable:**Objetivo**, **Tareas**(coordenadas con asignación)**Criterios de aceptación**, **Riesgos**. Cuando pido un plan de acción, el agente produce esta estructura sin que yo se la haya pedido. La gobernanza**programa**el agente.

==== Cuando los agentes especializados se vuelven indispensables

La creación de los agentes especializados sigue una curva natural. Al comienzo de un proyecto, no los necesitas —`AGENT.adoc`basta ampliamente. Pero cuando el proyecto crezca (digamos, más de 20 sesiones), dos señales deben alertarle:

1. El agente mezcla las convenciones de dos dominios distintos (ej: sintaxis PlantUML y reglas CSS)
2. Pasas más tiempo corrigiendo al agente sobre convenciones que ya le has explicado 5 veces

Sobre`cheroliv.com`, llegó a la sesión... 1. Sí, desde el principio. Porque este proyecto es un sitio web con tres lenguajes (FTL, CSS, JS), contenido AsciiDoc, y diagramas PlantUML — tres áreas que no tienen nada que ver. El agente CODER necesita conocer los tamaños de fuente y las media queries; el agente PLANTUML_DESIGNER necesita conocer la sintaxis`@startuml`. Sin separación, el agente CODER me proponía diagramas, y viceversa. El caos.

Sobre`jhipster-gradle-plugins`, he creado dos agentes especializados adaptados al desarrollo de plugins Gradle :`PLUGIN_DEVELOPER.adoc` et `BACKLOG_MANAGER.adoc`. El primero codifica todas las convenciones Kotlin/Gradle (no`!!`, clases de datos para los modelos,`@TaskAction`para las tareas). El segundo sabe que`persistence`debe ser estable antes de que`assistant`no comienza su desarrollo — una dependencia crítica en un mono-repo.

El error que no se debe cometer : crear demasiados agentes demasiado temprano`plantuml-plugin`Esperó la sesión 108 antes de formalizar un agente especializado para el conjunto de claves API. Antes de eso, el contexto del negocio se encontraba en`AGENT.adoc`. La regla empírica: un agente especializado se justifica cuando su dominio de negocio supera las 100 líneas de documentación.

==== Convención de Nomenclatura de Sesiones

Un detalle que parece fútil pero que se vuelve crítico cuando se alcanzan 100 sesiones. ¿Cómo nombrar los archivos de archivo?

He aprendido a mis expensas que una convención es necesaria — cuatro proyectos, cuatro formatos diferentes al principio, y ya no sabía orientarme. Hoy, la convención que he estabilizado es :

Ejemplos concretos:

* `1-chore-migration-gouvernance-agent.adoc`— sesión 1, tipo tarea
* `10-solidification-tests.adoc`— sesión 10, sin tipo explícito (el sujeto basta)
* `036-debug-graphify-symlink-epic9.adoc`— sesión 36 con número de 3 dígitos para la ordenación

El número de sesión es el criterio de ordenación principal. Los proyectos que utilizan números de tres cifras (001, 036, 133) evitan los problemas de ordenación lexicográfica cuando se supera 99. Esto es lo que ahora utilizo en`magic-stick`:`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`.

El tipo es opcional y se deriva de las palabras clave de la sesión (debug, feature, refactor, docs, chore, test). El asunto en kebab-case es la parte más importante: debe permitir recuperar una sesión sin abrir el archivo. Si te preguntas « ¿cuál fue la sesión en la que se corrigió el timeout de las pruebas de integración? », la respuesta es`124-fix-timeout-integration-test.adoc`.

Para las sesiones históricas reconstituidas (proyectos nacidos antes de la gobernanza), utilizo números negativos. Sobre`cheroliv.com`, las sesiones -6 a 0 cubren todo el historial pre-gobernanza del proyecto. Y para las sesiones « no documentadas » o perdidas, creo una entrada en`SESSIONS_HISTORY.adoc`sin archivo correspondiente, con una puntuación`?`. Es más honesto que fingir.

[plantuml, format=svg, id=diag-naming-convention, alt="Arbre de décision pour le nommage des fichiers de session"]

==== TEST_COVERAGE_ANALYSIS.adoc` — El Paso 5 Detallado

El paso 5 del procedimiento de fin de sesión es el más misterioso. Dice « Actualizar`TEST_COVERAGE_ANALYSIS.adoc`si se han añadido o modificado las pruebas. » Pero, ¿qué aspecto tiene este archivo?

sobre`plantuml-plugin`, ha evolucionado de unas pocas líneas a una estructura completa. Aquí está su forma estabilizada:

[source]