El slot de AGENTS.md

Qué es el slotCopiar enlace

El slot es un bloque que vexillum administra dentro de un archivo que es tuyo: el AGENTS.md de tu proyecto, o su CLAUDE.md cuando no hay AGENTS.md. Lleva el núcleo siempre activo de las reglas del commander, lo poco que tiene que estar en contexto en cada turno. Todo lo operativo (cómo despachar, elegir modelo, aterrizar, hacer ship, hacer strike, reaccionar al sentinel) vive en skills que Claude Code carga solo cuando hace falta.

Por qué un slot y no un archivo de reglas propio:

• Un bloque corto. El núcleo es chico y el detalle va a pedido.
• Vive en un archivo que el ecosistema ya lee. AGENTS.md y CLAUDE.md son donde van las instrucciones de agentes de tu proyecto. vexillum agrega a uno de ellos en vez de crear una convención paralela.
• Es seguro compartir el archivo. Todo lo que está fuera de los marcadores es tuyo y nunca se reordena ni se reescribe.

El bloque lo renderiza el binario, en inglés o en español. Podés ver el texto exacto en Bloque de AGENTS.md, generado desde el binario para que no se desfase.

Dónde va el bloqueCopiar enlace

El bloque vive en un solo archivo por proyecto, que se elige así:

1. Si AGENTS.md existe, el bloque va ahí (y CLAUDE.md importa AGENTS.md, ver la sección sobre el import al final).
2. Si AGENTS.md no existe, vx init propone poner el bloque en CLAUDE.md en vez de crear un AGENTS.md. La respuesta por defecto es sí, y CLAUDE.md se crea si no existe. Con --yes (o sin terminal) se toma el valor por defecto.
3. Si respondés que no, init crea AGENTS.md con el bloque, y CLAUDE.md lo importa.

This project has no AGENTS.md. Put the vexillum block in CLAUDE.md instead of creating an AGENTS.md? [Y/n]

Cuando el proyecto ya tiene un CLAUDE.md, la pregunta dice Add the vexillum block to your CLAUDE.md instead of creating an AGENTS.md? y tu texto del archivo se conserva: el bloque se agrega después. En el caso de CLAUDE.md no hace falta ninguna línea de import, porque Claude Code lee el archivo directamente.

Una vez que hay un bloque, se queda donde está. init, upgrade y doctor lo encuentran en cualquiera de los dos archivos y lo mantienen al día ahí, aunque después aparezca un AGENTS.md. Si los dos archivos tienen un bloque, cuenta el de AGENTS.md.

El formato de los marcadoresCopiar enlace

<!-- BEGIN VEXILLUM v:1 hash:ab12cd34 -->
...el núcleo del commander...
<!-- END VEXILLUM -->

El marcador BEGINCopiar enlace

<!-- BEGIN VEXILLUM v:1 hash:<8hex> --> lleva dos datos:

El cuerpoCopiar enlace

Entre los marcadores está el núcleo del commander. Contiene:

• Role check. Las reglas aplican solo al commander. Un soldier que las lea por accidente (cada camp es un checkout de tu proyecto, así que le va a pasar) tiene que seguir su prompt de dispatch y nunca despachar más soldiers.
• Vocabulary. general, commander, soldier, mission, scout, camp, sentinel. Estos términos quedan en inglés en todos los idiomas.
• Authority. Una instrucción explícita tuya anula una regla, pero el commander dice cuál dejó de lado.
• Tone. Cómo dirigirse a vos, y dejar el color cuando las noticias son malas.
• La instrucción de cargar la skill vexillum. Antes de despachar, elegir modelo, aterrizar, hacer ship, hacer strike o atender un aviso del sentinel, el commander tiene que cargar la skill y seguirla, no trabajar de memoria. Es el vínculo duro entre el núcleo siempre activo y el detalle a pedido.

El marcador ENDCopiar enlace

<!-- END VEXILLUM --> cierra el bloque. Todo lo que sigue es tuyo de nuevo.

Por qué los marcadores van en su propia líneaCopiar enlace

Cada marcador está solo en su línea. Claude Code quita los comentarios HTML de bloque de los archivos que carga en contexto, así que un marcador en su propia línea no cuesta tokens ni confunde al modelo. Además, la detección se ancla al inicio de la línea e ignora los marcadores dentro de bloques de código con cercas, así que una página que solo cita los marcadores (como esta) nunca se confunde con un bloque.

Los estadosCopiar enlace

vx doctor reporta el estado del slot (AGENTS.md vexillum block o CLAUDE.md vexillum block, según el archivo que lo tenga), y init y upgrade actúan según él.

Cuando editás el bloqueCopiar enlace

El bloque está pensado para ser administrado, pero el archivo es tuyo. Si cambiás algo dentro de los marcadores:

• init y upgrade lo dejan como está e imprimen el diff entre tu versión ("your edit") y la plantilla actual ("vexillum template");
• vx upgrade --force lo reemplaza con la plantilla actual. Tu versión editada se guarda antes en .vexillum/agents-md-slot.backup.md. Un backup anterior se sobrescribe.

vx doctor muestra un bloque drifted como drifted, edited by hand.

Si querés otras reglas siempre activas, poné tu propio texto fuera de los marcadores: es tuyo y nunca se toca.

Marcadores malformados y reparaciónCopiar enlace

Un bloque malformado nunca se arregla a tus espaldas. vx upgrade lista las reparaciones y pregunta Apply these repairs? [Y/n] (--yes acepta). Antes de escribir, el archivo entero tal como estaba se guarda en .vexillum/AGENTS.md.backup (.vexillum/CLAUDE.md.backup cuando el bloque está en CLAUDE.md). La reparación es deliberadamente acotada:

• conserva el primer par BEGIN/END bien formado;
• borra cualquier otro par duplicado, contenido incluido;
• borra un marcador BEGIN o END huérfano solo en esa línea, nunca el texto que lo rodea.

Si decís que no, el archivo queda como está. Después de reparar, el bloque todavía puede estar drifted: la reparación nunca juzga el cuerpo, así que un bloque que editaste conserva tu texto hasta que corras upgrade --force. init nunca repara; reporta el problema y te manda a upgrade.

Quitar el bloqueCopiar enlace

No hay un comando para desinstalar. Para sacar el bloque, borrá a mano la línea BEGIN, la línea END y todo lo que hay entre ellas (y la línea en blanco de arriba). El resto de tu texto no se toca. Tené en cuenta que vx init o vx upgrade vuelven a agregar el bloque cuando falta, así que sacalo solo si terminaste con vexillum en ese proyecto.

IdiomaCopiar enlace

El slot viene en inglés y en español. El vocabulario del dominio queda en inglés en ambos.

Cuando init o upgrade están por escribir el bloque, el idioma se resuelve en este orden:

1. --lang en o --lang es, si lo pasás;
2. el idioma de un bloque que ya está en el archivo, para que una nueva corrida no lo cambie porque el texto que lo rodea se lee distinto;
3. el idioma detectado en tu propio texto del archivo que tiene el bloque;
4. inglés.

La detección es simple, determinista y offline: cuenta palabras funcionales frecuentes de cada idioma, ignorando código, URLs y el propio bloque de vexillum. Necesita al menos 8 coincidencias y un 70% de participación para decidir; si no, y cuando el archivo no tiene texto tuyo, usa inglés.

Cuando el idioma se detectó o quedó por defecto (no lo diste con --lang ni se leyó de un bloque existente), lo ves antes de que se escriba nada, por ejemplo Detected language: es (from AGENTS.md). (o CLAUDE.md) seguido de Use es for the vexillum block? [Y/n]. Si respondés que no, te pregunta Language (en/es):. Con --yes, o sin terminal, solo se anuncia.

El hash es por idioma, así que cambiar de idioma es una actualización normal del bloque. vx doctor reporta el idioma del bloque que encontró.

Por qué CLAUDE.md tiene que importar AGENTS.mdCopiar enlace

Claude Code lee CLAUDE.md, no AGENTS.md. Para que el slot llegue al commander, CLAUDE.md tiene que importarlo con una línea:

@AGENTS.md

Esto aplica cuando el bloque está en AGENTS.md. Cuando el bloque está en el propio CLAUDE.md no hay nada que importar, y doctor no reporta el import.

init lo verifica. Si CLAUDE.md no existe, se crea con esa línea, como parte del aviso de consentimiento. Si existe sin el import, es un archivo tuyo con contenido, así que init hace una segunda pregunta aparte antes de agregar la línea:

CLAUDE.md does not import AGENTS.md, so Claude Code would not see the vexillum block. Add the line @AGENTS.md to it? [Y/n]

Si decís que no, init avisa que Claude Code no va a ver el bloque y te dice que agregues la línea vos. Un CLAUDE.md que es un symlink a AGENTS.md ya cuenta como import. vx doctor lo reporta como CLAUDE.md imports AGENTS.md.

RelacionadoCopiar enlace

• Skills: lo que se carga a pedido.
• Bloque de AGENTS.md: el texto exacto, en los dos idiomas.
• vx init, vx upgrade y vx doctor.