Arquitectura de agentes

Esta es una página de especificación técnica orientada a desarrolladores. Usa el vocabulario interno de Apothem —clases de adaptador, materializadores, manifiesto de propagación, convergencia de convenciones entre pares— sin suavizarlo para una audiencia general.

Apothem lee un único perfil compartido (~/.config/apothem/profile.yaml) y materializa la configuración nativa de cada entorno para diecisiete adaptadores registrados. Los entornos no comparten un modelo de capacidades: algunos exponen hooks previos a la llamada de herramienta, algunos ejecutan reglas desde archivos .md planos, algunos incrustan cada regla en un único archivo de instrucciones, y algunos renderizan una configuración derivada del perfil en el momento de la instalación. Esta página mapea esa divergencia y la disciplina que Apothem aplica sobre ella.

Matriz de capacidades por entornoCopy Anchor Link

La matriz a continuación cubre los diecisiete entornos. Columnas: la superficie de hook PreToolUse que el adaptador conecta (cuando un entorno documenta hooks que el adaptador no registra, la celda lo indica), el formato que Apothem usa para activar reglas, la clase de adaptador (consulta Clases de adaptador) y si el adaptador renderiza una configuración nativa mediante un materializador.

Notas sobre la matriz:

• claude-code es el adaptador con la superficie nativa más amplia. Incorpora hooks nativos PreToolUse, PostToolUse, Stop y SessionStart, y distribuye plantillas de ajustes del proveedor. Escribe un único bloque gestionado delimitado por centinelas en CLAUDE.md y deja sin cambios la prosa del operador fuera de los centinelas.
• codex instala hooks de ciclo de vida nativos mediante hooks.json, convierte los agentes a TOML, envuelve los prompts de comando como skills de Codex y deja config.toml en propiedad del operador.
• antigravity mantiene ~/.gemini/GEMINI.md como ancla de contexto global e instala un plugin de Apothem en ~/.gemini/antigravity-cli/plugins/apothem/. Los archivos de hook se conservan como material de soporte hasta que el adaptador asuma la traducción del esquema de hooks de Antigravity.
• cursor activa las reglas mediante un solo archivo .mdc que lleva el frontmatter MDC del proveedor (description, globs, alwaysApply); el adaptador no escribe ningún .cursorrules de archivo único.
• windsurf usa .devin/rules/; el adaptador no escribe ningún .windsurfrules de archivo único.
• hermes y open-claw renderizan archivos de configuración nativos y conectan los directorios de skills de soporte de Apothem mediante el ajuste de directorio de skills documentado por cada entorno. Las cohortes compartidas no soportadas permanecen en subárboles de soporte propiedad de Apothem.
• qwen-code renderiza las claves documentadas de settings.json para el contexto y el despacho de hooks, y después usa los directorios nativos de comandos, skills y agentes de Qwen.

Disciplina de orquestación entre entornosCopy Anchor Link

Apothem aplica convergencia de convenciones entre pares: el mismo flujo de trabajo invocable por el operador se proyecta al idioma nativo de cada entorno en lugar de forzarlo a un único formato compartido. Una regla que se activa como archivo plano .md en claude-code se convierte en una regla de workspace .mdc en cursor, en una sección incrustada de GEMINI.md en gemini-cli, y en una referencia concatenada en el QWEN.md de qwen-code más sus directorios de descubrimiento nativos — la misma intención, el dialecto de cada entorno.

La cohorte maestra canónica reside en:

src/apothem/{rules,commands,skills,agents,output-styles,hooks,conformity,statuslines}/

Cada adaptador propaga un subconjunto de esta cohorte. El subconjunto por entorno se declara en src/apothem/lib/propagation-manifest.yaml; el manifiesto es la única fuente de verdad sobre qué artefactos llegan a qué entorno y en qué forma. Un adaptador nunca inventa artefactos fuera del manifiesto, y el manifiesto nunca asigna a un entorno un artefacto que carece de la superficie para alojarlo.

Clases de adaptador explicadasCopy Anchor Link

Apothem clasifica los adaptadores en tres clases según cómo traducen el perfil compartido a salida nativa del entorno.

• Clase I — propagación directa. El adaptador copia los artefactos de la cohorte maestra canónica (un subconjunto declarado en el manifiesto) directamente a la ubicación de configuración del entorno sin paso de renderizado. No hay materializador. antigravity, codebuddy, codex, cursor, gemini-cli, github-copilot, glm, kimi-code, kiro, trae, windsurf y zed son de Clase I.
• Clase II-A — directa + plantillas de ajustes ligadas al proveedor. El adaptador propaga directamente los artefactos y además gestiona plantillas de ajustes específicas del proveedor ligadas al esquema del proveedor. claude-code es de Clase II-A.
• Clase II-B — materializador de superficie única renderizada desde el perfil. El adaptador renderiza el perfil compartido a una única superficie de configuración nativa mediante un materializador. hermes, open-claw, opencode y qwen-code son de Clase II-B.

Comportamiento en el momento de la materializaciónCopy Anchor Link

La distinción de clase se manifiesta en el momento de la materialización — cuando un operador ejecuta la CLI contra un entorno:

• apothem install --harness <H> propaga el subconjunto del manifiesto para <H> y, para los adaptadores de Clase II-A / II-B, renderiza la configuración nativa del entorno.
• apothem verify --harness <H> comprueba que los archivos gestionados existen y se analizan correctamente. Con --profile PATH también los comprueba contra lo que ese perfil produciría y falla si hay desviación.
• apothem status informa de si cada entorno está instalado y de si se ha desviado del perfil compartido actual.
• apothem doctor informa de la salud por entorno en cada adaptador registrado: ok, not_installed, needs_project, verify_failed, hook_failed o error.

Consulta la referencia de la CLI para ver las superficies de comando completas.

Taxonomía de la divergenciaCopy Anchor Link

Los diecisiete entornos divergen a lo largo de tres ejes. Cada diferencia por entorno en la matriz se reduce a uno de ellos.

El trabajo de Apothem es mantener constante una única intención coherente del operador mientras estos tres ejes varían por entorno. El manifiesto de propagación y el contrato de clase de adaptador son los dos mecanismos que mantienen esa intención estable a través de la divergencia.