Contribuir a Apothem — Guía del desarrollador

Esta guía ayuda a los desarrolladores a mantener y extender el ecosistema de Apothem con estándares de calidad SOTA.

Referencia rápida: tipos de artefactoCopy Anchor Link

Esta guía cubre cinco tipos de artefacto, cada uno con un propósito específico. Las reglas, los comandos, los ayudantes y las skills llevan frontmatter YAML; los hooks se registran en hooks.json y settings.json y no llevan ninguno. Los output-styles son otra clase de artefacto con dos claves de frontmatter obligatorias, name y description; consulta el Esquema de frontmatter.

Contrato del adaptador de entornoCopy Anchor Link

Los datos de identidad y de capacidades de cada entorno residen en src/apothem/lib/harness_registry.py. Un cambio de entorno solo está completo cuando estas superficies concuerdan:

Los adaptadores de ámbito de proyecto deben establecer requires_project = True, aceptar project: Path | None en los métodos de ciclo de vida y rechazar las raíces de proyecto faltantes o inseguras antes de cualquier escritura. Los adaptadores de ámbito de usuario deben mantener las rutas bajo la raíz de configuración de usuario documentada del entorno.

Política de fixtures goldenCopy Anchor Link

tests/fixtures/harness-golden-plans.json registra la forma pública del plan de instalación de los diecisiete entornos del registro: ID público, modo de materialización, ruta de cohorte/plantilla de origen y ruta de destino normalizada bajo <ROOT>. Cuando el comportamiento del registro, del manifiesto o del destino de las plantillas cambia de forma intencionada, actualiza el fixture golden en el mismo commit que el cambio en el código fuente para que el diff muestre la diferencia de comportamiento.

Validación antes de escribirCopy Anchor Link

El driver de instalación compartido valida cada origen y cada destino antes de la primera escritura. Rechaza las fuentes de manifiesto faltantes, los recorridos fuera del destino, las rutas de destino fuera de la raíz seleccionada y los cruces de enlaces simbólicos. Los dry-runs ejecutan la misma validación y devuelven resultados estructurados skipped o unchanged sin crear archivos.

Ocultación y datos de ejemploCopy Anchor Link

Los diagnósticos del perfil ocultan los campos con forma de token, secreto, contraseña, credencial, clave de API, clave privada, autorización, auth y encabezado. La documentación, los fixtures, los ejemplos y los fragmentos JSON usan example.invalid, Example User, example-user y marcadores de posición evidentes en lugar de secretos o cuentas personales de apariencia real.

Antes de escribir: el esquema canónicoCopy Anchor Link

El contrato legible por máquina y aplicado por la puerta lo constituyen los esquemas JSON por clase bajo src/apothem/schemas/*.schema.json — additionalProperties rechaza las claves desconocidas, así que la puerta de conformidad tiene la última palabra. Dos proyecciones legibles por humanos los siguen: site/content/docs/reference/frontmatter-schema.mdx (el índice de claves requeridas) y site/content/docs/reference/artifact-schema.mdx (plantillas por clase y ejemplos desarrollados). Cuando una página discrepa de los esquemas JSON, prevalecen los esquemas.

• Lee el esquema JSON de tu tipo de artefacto bajo src/apothem/schemas/
• Lee site/content/docs/reference/artifact-schema.mdx § «Schema» para ver la plantilla y un ejemplo desarrollado
• Copia los campos requeridos, rellena los valores obligatorios y añade campos opcionales según sea necesario

Comprobación rápida del frontmatterCopy Anchor Link

El frontmatter de cada artefacto debe superar estas comprobaciones. Aplica las comprobaciones de version, updated y portability solo a una clase que lleve la clave: las reglas no llevan ninguna de ellas, y las skills no llevan portability.

✓ Valid YAML syntax (use tools: `yamllint` or PowerShell `ConvertFrom-Yaml` where available)
✓ All mandatory fields present (per schema for artifact type)
✓ name: uses kebab-case
✓ version: semantic MAJOR.MINOR.PATCH
✓ updated: ISO 8601 date (YYYY-MM-DD)
✓ description: single-line, non-empty
✓ scope fields valid per artifact type (rules: pathFilter + alwaysApply; CLAUDE.md root: scope)
✓ portability: string, for example `universal` (the schemas do not enumerate its values)
✓ No typos in field names — must match canonical schema exactly
✓ Optional fields use correct enum values

Convenciones de nomenclaturaCopy Anchor Link

Nombres de artefacto (kebab-case)Copy Anchor Link

• Reglas: operational-mandates, clean-room-generation, context-management
• Comandos: plan-execute, plan-spec, plan-generate
• Ayudantes: codebase-explorer, convention-auditor, quality-gate
• Skills: plan-suite, ecosystem-audit

Patrón: minúsculas, guiones entre palabras, sin espacios ni guiones bajos.

Nomenclatura de archivosCopy Anchor Link

• Reglas: {name}.md
• Comandos: {name}.md
• Ayudantes: {name}.md
• Skills: Dentro de la carpeta src/apothem/skills/{name}/SKILL.md (mayúsculas exactas: SKILL.md)
• Hooks: Dentro de la carpeta src/apothem/hooks/. Todos los manejadores de eventos están escritos en Python. Cada comando de hook de la plantilla settings.json de Claude Code usa la forma exec: command es el marcador de posición del intérprete ${PYTHON_BIN}, que se resuelve en el momento de la instalación, y args contiene la ruta del script y sus argumentos. Esa plantilla ejecuta ${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py <event> [<message-name>] y ${HARNESS_ROOT}/.apothem/support/conformity/gate.py --hook por ruta absoluta, así que la copia instalada no necesita un paquete apothem importable. El plugin de Claude Code registra en cambio los hooks en src/apothem/hooks/hooks.json, como comandos de shell que ejecutan hooks/lib/bootstrap.sh mediante bash; ese stub localiza Python y ejecuta dispatch.py, de modo que los manejadores siguen siendo de Python. Registra un hook nuevo en hooks.json y en la plantilla settings.json de Claude Code. dispatch.py enruta SessionStart a session_start_bootstrap.main() y todos los demás eventos de la lista de permitidos a emit_hook_context.main(). Los únicos stubs de shell permitidos bajo src/apothem/hooks/ o scripts/ son los seis archivos de localizador y arranque (find-python.{ps1,sh}, find-pwsh.{ps1,sh}, bootstrap.{ps1,sh}); cualquier otro archivo .ps1 / .sh no supera la comprobación de higiene de scripts/dev/validate_hooks.py.

Referencias cruzadasCopy Anchor Link

Al hacer referencia a otros artefactos, usa los nombres exactos:

• Reglas: "operational-mandates" (valor del campo name)
• Comandos: /plan-execute (con barra en la documentación para humanos; sin ella en el código)
• Ayudantes: codebase-explorer (valor del campo name)
• Skills: plan-suite (valor del campo name)

Nunca uses rutas de archivo ni nombres truncados en la prosa.

Portabilidad: Windows frente a UnixCopy Anchor Link

Cada comando DEBE declarar explícitamente su estado de portabilidad en el campo portability. Un ayudante PUEDE declararlo. Las skills, las reglas y los output-styles no llevan ningún campo portability.

UniversalCopy Anchor Link

• Funciona de forma idéntica en Windows, macOS y Linux
• Sin suposiciones sobre la shell
• Las rutas usan barras normales (/)
• Sin rutas absolutas codificadas de forma fija
• Sin sintaxis de PowerShell específica de Windows

portability: "universal"

Universal con salvedades de WindowsCopy Anchor Link

• Universal en todos los hosts POSIX; la salvedad indicada se aplica a la variante de la plataforma Windows declarada en el contenido
• Documenta la salvedad de forma explícita en el contenido
• Ejemplo: «Los enlaces simbólicos no se admiten en Windows antes de Win 10»

portability: "universal-with-windows-caveats"

Documenta la salvedad en una nota inmediatamente después del título.

Solo Unix / Solo WindowsCopy Anchor Link

• Restringido explícitamente a una plataforma
• Poco común en Apothem — la mayoría debería ser universal
• Úsalo solo si las funciones específicas de la plataforma son esenciales

portability: "unix-only"

Documenta el motivo en la primera sección del artefacto.

Ámbito: siempre activo frente a filtrado por rutaCopy Anchor Link

Siempre activoCopy Anchor Link

La regla se aplica en todas partes. Cinco reglas son siempre activas: agnostic-posture, authority-inquiry, session-closure, context-management y el índice de reglas (apothem-rule-index). El conjunto es pequeño porque cada regla siempre activa consume contexto en cada sesión.

pathFilter: ""
alwaysApply: true

Filtrado por rutaCopy Anchor Link

La regla se aplica de forma condicional según la ruta del archivo.

pathFilter: "**/*.py, **/*.toml"
alwaysApply: false

pathFilter usa patrones glob (el mismo formato que .gitignore). Cuando un archivo coincide con el filtro, la regla se activa.

Semántica de versionesCopy Anchor Link

Cada artefacto versionado lleva su propia versión semántica (MAJOR.MINOR.PATCH). Los comandos y las skills la requieren, los ayudantes y los output-styles PUEDEN llevarla, y las reglas no llevan ninguna:

• PATCH — un cambio de comportamiento que corrige una directiva existente sin romper el contrato.
• MINOR — cambios aditivos que no rompen la compatibilidad: nuevas secciones opcionales, nuevos campos opcionales de frontmatter, nuevos ejemplos. Los consumidores existentes siguen funcionando sin cambios.
• MAJOR — cambios incompatibles de esquema o de contrato: secciones eliminadas, campos renombrados, comportamiento alterado de una directiva existente, cambios que obligan a los artefactos dependientes a adaptarse.

Las correcciones de erratas, de enlaces y de formato, así como las ediciones que solo tocan comentarios o documentación, dejan la versión sin cambios. Solo un cambio de comportamiento la incrementa. Aun así, esa edición actualiza la fecha updated del artefacto.

Ejemplos:

• vX.Y.Z → vX.Y.(Z+1) (PATCH: una directiva corregida que cambia el comportamiento)
• vX.Y.Z → vX.Y.Z (sin incremento: corrección de una errata o de un enlace; updated cambia)
• vX.Y.Z → vX.(Y+1).0 (MINOR: se añadió una nueva sección opcional)
• v0.Y.Z → v(0+1).0.0 (MAJOR: se declaró estable el contrato; los artefactos nuevos parten de v0.Y.Z)
• vX.Y.Z → v(X+1).0.0 (MAJOR: se eliminó un campo obligatorio de frontmatter)

Incrementa version y updated a la vez en cada edición que cambie el comportamiento de un artefacto que los lleve. Añade una fila correspondiente al CHANGELOG.md del nivel del ecosistema para los lanzamientos que agrupen cambios de artefactos.

Revisiones de suites de planCopy Anchor Link

La regla de artefactos anterior no se aplica a las suites de plan. La versión de una suite de plan es el valor vX.Y.Z registrado en el encabezado de su MASTER-PLAN.md y en la tabla de Historial de revisiones. Una corrección de erratas en una suite de plan es una revisión que incrementa el número PATCH. El paso 10.2 de /plan-review establece la clasificación y añade la fila del Historial de revisiones.

• vX.Y.Z → vX.Y.(Z+1) (suite de plan, corrección de erratas: PATCH)
• vX.Y.Z → vX.Y.Z (artefacto, corrección de erratas: sin incremento; la regla de artefactos anterior)

Cuándo editar un artefactoCopy Anchor Link

ReglasCopy Anchor Link

• Trata la estructura Obligatorio/Opcional como un pilar estructural — reestructurarla repercute en cada artefacto dependiente.
• Refina los Antipatrones, los ejemplos de Escalado por Seriedad y las citas a medida que se profundiza la comprensión.
• Registra la justificación de cualquier cambio estructural en el archivo de tema de memoria correspondiente.

ComandosCopy Anchor Link

• La forma de los argumentos forma parte del contrato público — rómpela solo con intención explícita y propaga el cambio a cada invocador (incremento MAJOR).
• Mantén los pasos del flujo de trabajo y los contratos de retorno precisos y actualizados.
• Documenta en línea la secuencia de pasos que no sea evidente.

AyudantesCopy Anchor Link

• Mantén disallowedTools mínimo pero suficiente; documenta la justificación cuando cambie.
• Refina los Principios Operativos y los Contratos de Retorno a medida que madura el rol del ayudante (incremento MINOR).
• Registra en línea los cambios de capacidad para que los invocadores puedan recalibrar sus expectativas.

SkillsCopy Anchor Link

• Mantén los pasos de Procedimiento y los Ejemplos sincronizados con la realidad.
• Las señales de detección deben reflejar la formulación real de los usuarios en el uso actual.
• Divide una skill en cuanto supere las ~150 líneas (consulta auto-memory.md § Topic File Management).

Paso a paso: añadir una nueva reglaCopy Anchor Link

1. Evalúa la ortogonalidadCopy Anchor Link

¿Se solapa esta regla con reglas existentes? Busca contenido relacionado en src/apothem/rules/.

Si el solapamiento supera el 50 %, plantéate ampliar una regla existente en su lugar. Consulta persistent-conventions-vigilance.md § Artifact Evolution.

2. Escribe el contenidoCopy Anchor Link

Sigue esta estructura:

• Título: # Rule: {Title}
• Sección de Propósito
• Obligaciones / Directivas centrales (numeradas, enlazadas)
• Tabla de Escalado por Seriedad (siempre requerida)
• Sección de Antipatrones
• Sección de Cumplimiento

3. Crea el frontmatterCopy Anchor Link

Usa el esquema de site/content/docs/reference/artifact-schema.mdx § Schema: Rules. Establece:

• name: identificador en kebab-case
• description: resumen de una línea para los registros
• pathFilter: lista de globs para las reglas filtradas por ruta; la cadena vacía ("") para las reglas siempre activas
• alwaysApply: true para las reglas siempre activas, false para las reglas filtradas por ruta

Las reglas llevan solo estos cuatro campos — sin version / updated / scope / portability / implements.

Una regla nueva es filtrada por ruta. Una nueva regla siempre activa requiere ampliar la lista central y los límites de bytes en el mismo cambio: la lista en tests/unit/test_always_on_core.py y los límites en conformity/always_on_budget_grep.py. Una regla complementaria (<parent>-<aspect>) toma el pathFilter de su regla madre, o uno más acotado.

Ejemplo:

---
name: "my-new-rule"
description: "Brief one-liner"
pathFilter: "**/*.py"
alwaysApply: false
---

4. Actualiza el README de las reglasCopy Anchor Link

Añade una fila a la tabla de la familia de la regla en la sección Rule families de src/apothem/rules/README.md:

| `my-new-rule.md` | One-line concern of the new rule. |

Elige la tabla de la familia cuya temática coincida con la de la regla. Nombra también la regla en la línea de src/apothem/rules/apothem-rule-index.md correspondiente a la situación que la requiere; tests/unit/test_always_on_core.py falla cuando falta una regla en el índice.

5. Añade una entrada a CHANGELOG.mdCopy Anchor Link

Añade una fila bajo la sección ### Added del próximo lanzamiento que describa la nueva regla.

6. Ejecuta la validaciónCopy Anchor Link

Invoca la skill ecosystem-audit para verificar la nueva regla, centrándote en el área de reglas:

Invoke the ecosystem-audit skill with --focus rules --fix

Verifica que no se informe ningún error para tu nueva regla.

Paso a paso: añadir un nuevo comandoCopy Anchor Link

Los comandos son comandos de barra como /plan-spec, /plan-execute, /security-audit, etc.

1. Determina el rolCopy Anchor Link

Los comandos son flujos de trabajo que dispara el usuario. El modelo ejecuta uno por iniciativa propia solo cuando su ajuste disable-model-invocation es false (paso 2). Pregúntate:

• ¿Es este un flujo de trabajo en el que el usuario teclea /command-name?
• ¿Orquesta varios pasos?
• ¿Podría agotar el tiempo de espera o requerir intervención del usuario a mitad de la ejecución?

Si la respuesta a cualquiera de estas preguntas es «no», probablemente sea una skill, no un comando.

2. Crea el archivoCopy Anchor Link

Ruta: src/apothem/commands/{name}.md

Frontmatter (de site/content/docs/reference/artifact-schema.mdx § Schema: Commands):

---
name: "my-command"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this command does"
argument-hint: "[path/to/input] [--flag VALUE]"
disable-model-invocation: false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

disable-model-invocation: true hace que solo el operador pueda invocar un comando; con false, el modelo puede ejecutarlo cuando una solicitud coincide con su descripción. El valor predeterminado es false para los comandos de solo lectura y de asesoramiento, con una descripción que empieza por el caso de uso; 35 de los 45 comandos lo usan. Un comando se queda en true cuando cambia el estado fuera del árbol de trabajo o depende de que el operador elija el momento (10 comandos). La tabla de invocación de src/apothem/commands/README.md lista el valor de cada comando; añade una fila para un comando nuevo. Mantén allowed-tools en solo lectura: un entorno que lo respeta ejecuta esas herramientas sin preguntar. Concede una herramienta con efectos secundarios solo como regla acotada, como Bash(git log *); el esquema rechaza "*" y cualquiera de Bash, PowerShell, Write, Edit, NotebookEdit o WebFetch escrito sin acotar.

3. Escribe el contenidoCopy Anchor Link

Estructura:

• Título: # /{name} — Human-Readable Title
• Sección de Rol (quién lo ejecuta)
• Instrucciones de alto nivel
• Sección de Flujo de trabajo con pasos
• Contrato de retorno / formato de salida

La emisión de skills de un entorno divide cada comando en un SKILL.md reducido más archivos references/ por sección H2. Dale a un comando una sola sección ## Workflow, cierra cada bloque de código y clasifica cualquier tipo nuevo de H2 en src/apothem/lib/claude_skill_split.py; tests/unit/test_claude_skill_split.py falla ante un tipo sin clasificar. Las reglas están en el contrato Skill-emission split de src/apothem/commands/README.md.

4. Actualiza el README y CHANGELOG.mdCopy Anchor Link

Añade una fila a la tabla de la sección del comando en src/apothem/commands/README.md, además de la fila de la tabla de invocación del paso 2; añade una fila de CHANGELOG bajo la sección ### Added del próximo lanzamiento.

5. ValidaCopy Anchor Link

Invoca la skill ecosystem-audit, centrándote en los comandos:

Invoke the ecosystem-audit skill with --focus commands --fix

Paso a paso: añadir un nuevo ayudanteCopy Anchor Link

Los ayudantes son definiciones persistentes de trabajadores delegados para el trabajo en paralelo.

1. Identifica el patrónCopy Anchor Link

¿Encaja este ayudante en alguno de los patrones de equipo que se enumeran a continuación?

• Equipo de Investigación: solo lectura, recopilación de información
• Equipo de Auditoría: verificación, comprobaciones de coherencia
• Equipo de Implementación: cambios de código en paralelo
• Equipo de Calidad: lint, pruebas, comprobación de tipos, seguridad
• Equipo de Documentación: actualizaciones de la documentación
• Otro: tarea especializada

2. Crea el archivoCopy Anchor Link

Ruta:

src/apothem/agents/{name}.md

Frontmatter:

---
name: "my-helper"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this helper specializes in"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit"
maxTurns: 15
portability: "universal"
---

Omite model, effort y permissionMode para que el ayudante herede las elecciones de la sesión (la postura agnóstica), y omite memory salvo que el ayudante necesite un ámbito de memoria persistente (user, project o local).

3. Escribe el contenidoCopy Anchor Link

Secciones:

• Principios Operativos (solo lectura, basados en evidencia, veredictos binarios, exhaustivos)
• Flujo de trabajo (pasos numerados)
• Contrato de Retorno (máximo de tokens, estructura, campos requeridos)

4. Actualiza el README y CHANGELOG.mdCopy Anchor Link

Añade una fila a la tabla Index de src/apothem/agents/README.md; añade una fila de CHANGELOG bajo la sección ### Added del próximo lanzamiento.

5. PruebaCopy Anchor Link

Despliega el ayudante en un escenario real y verifica que funciona como está documentado.

Paso a paso: añadir una nueva skillCopy Anchor Link

Las skills son técnicas reutilizables y detectables.

1. Identifica la reutilizaciónCopy Anchor Link

Antes de escribir una skill:

• ¿Has visto este problema/técnica 3 o más veces?
• ¿Es detectable? (¿La señala un patrón en las solicitudes del usuario?)
• ¿Puedes codificarla de forma reproducible?

Si las tres respuestas son sí, escribe una skill.

2. Crea la estructuraCopy Anchor Link

%%{ init: { "theme": "neutral" } }%%
%% verified: 2026-04-27 %%
%% provenance: site/content/docs/reference/artifact-schema.mdx (skill artifact schema) %%
%% cross-reference: src/apothem/skills/plan-suite/SKILL.md (canonical example) %%
flowchart TD
    accTitle: New skill directory structure
    accDescr: Top-down flowchart of the directory structure for a new skill under src/apothem/skills: a {skill-name} folder holding the required SKILL.md plus optional examples and templates subfolders.
    SKILLS["src/apothem/skills/"]
    SKILLS --> NAME["{skill-name}/"]
    NAME --> SKILLMD["SKILL.md<br/>(main definition · required)"]
    NAME --> EX["examples/<br/>(optional · example workflows)"]
    NAME --> TPL["templates/<br/>(optional · reusable templates)"]

3. Escribe SKILL.mdCopy Anchor Link

Frontmatter:

---
name: "skill-name"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
argument-hint: "[args]"               # optional; if userInvocable
---

Estructura del contenido:

• Propósito
• Cuándo usar esta skill
• Requisitos previos
• Procedimiento paso a paso
• Errores comunes
• Ejemplos

4. Actualiza el README y CHANGELOG.mdCopy Anchor Link

Añade una fila a la tabla Index y una fila por cada archivo de la skill a la tabla Folder contents de src/apothem/skills/README.md; añade una fila de CHANGELOG bajo la sección ### Added del próximo lanzamiento.

5. ValidaCopy Anchor Link

Invoca la skill ecosystem-audit, centrándote en las skills:

Invoke the ecosystem-audit skill with --focus skills --fix

Lista de verificación antes de hacer commitCopy Anchor Link

• El frontmatter supera la comprobación de sintaxis YAML
• Todos los campos obligatorios están presentes según el esquema
• El campo name usa kebab-case
• version (solo las clases versionadas; las reglas no llevan ninguna) es semántica (MAJOR.MINOR.PATCH) y se incrementó si cambió el comportamiento
• updated coincide con la fecha de hoy en cualquier artefacto que hayas tocado y que lleve el campo
• El campo portability está establecido y es válido (obligatorio en los comandos, opcional en los ayudantes)
• CHANGELOG.md recoge el cambio en la categoría adecuada bajo la sección del próximo lanzamiento
• Sin referencias internas de planes (cumplimiento de CM-7)
• Las referencias cruzadas son coherentes con los demás artefactos
• El nuevo artefacto está registrado en el índice del README de su carpeta
• El artefacto se ha probado (si corresponde)
• La skill ecosystem-audit se ejecuta sin errores
• El contenido sigue las convenciones estructurales (formato del título, secciones, etc.)

Referenciar otros artefactosCopy Anchor Link

Usa exactamente estas convenciones:

Referenciar una reglaCopy Anchor Link

See `src/apothem/rules/operational-mandates.md` or shorthand: the Operational Mandates rule.
In prose: ... per CM-1–10 (Operational Mandates rule) ...

Referenciar un comandoCopy Anchor Link

See `/plan-execute` command. Or: Run `/plan-execute`.
In prose: The `/plan-execute` command handles phase execution.

Referenciar un ayudanteCopy Anchor Link

Deploy the `codebase-explorer` delegated worker.
In prose: The codebase-explorer worker finds patterns.

Referenciar una skillCopy Anchor Link

Use the `plan-suite` skill.
In prose: The plan-suite skill provides the Master Plan Suite template.

Referenciar secciones de CLAUDE.mdCopy Anchor Link

See CLAUDE.md § Harness Adapter Pattern.
Or: § Plans Discipline.

Linting y formatoCopy Anchor Link

Todos los artefactos usan:

• Markdown: GFM (GitHub Flavored Markdown)
• YAML: conforme a YAML 1.2
• Finales de línea: LF (estilo Unix)
• Codificación: UTF-8
• Ancho de línea: ajuste suave a 100 caracteres para el contenido (sin saltos de línea forzados)

Usa el formateador / linter Ruff para los archivos Python. Para Markdown, usa prettier o un equivalente.

Pruebas y mediciónCopy Anchor Link

Ejecutar la suiteCopy Anchor Link

python -m pytest                      # unit, integration, property, conformity, scripts
python -m pytest tests/property       # Hypothesis properties (profile loader, frontmatter, merge)

La suite es hermética: pasa con el checkout bajo $TMPDIR y con un python en PATH que carece de los requisitos previos de la CLI, porque las pruebas de integración ejecutan el intérprete que ejecuta pytest y tokenizan las rutas temporales y de código fuente anidadas de la más larga a la más corta.

Cobertura por paqueteCopy Anchor Link

La CI mide tres paquetes y exige a cada uno su propio umbral mínimo. Ninguno se integra en otro.

La cifra es la cobertura de líneas más ramas, el mismo porcentaje que informa coverage.py con branch = true; el artefacto de métricas también registra la cifra solo de sentencias bajo coverage_lines. El umbral de cada paquete es el valor medido de líneas más ramas redondeado hacia abajo. Sube un umbral cuando la cobertura aumente; nunca bajes uno para que un cambio pase. Para comprobarlo localmente:

python -m pytest --cov=src/apothem --cov-report=json:coverage.json
python scripts/dev/collect_metrics.py --coverage-json coverage.json --check-floors \
  --skip-hooks --skip-coldstart --harness zed

El artefacto de métricasCopy Anchor Link

El trabajo metrics de la CI ejecuta scripts/dev/collect_metrics.py en cada push y cada pull request y sube metrics.json (schema_version: 1). Cada valor que es null lleva su motivo bajo nulls.

Qué archivos cuentan como cargados al arrancar es una regla por entorno tomada de las superficies de instrucciones documentadas de cada proveedor. Los listados que solo llevan una descripción (skills, comandos, subagentes) no se cuentan. El texto de la regla también se escribe en el artefacto bajo rules.always_on_bytes:

antigravity     ~/.gemini/{GEMINI,AGENTS}.md, ~/.gemini/config/{GEMINI,AGENTS}.md,
                ~/.gemini/config/rules/*.md with trigger: always_on, project
                GEMINI.md and AGENTS.md. The plugin rules/ folder is not a
                documented launch surface.
claude-code     ~/.claude/CLAUDE.md and ~/.claude/rules/**/*.md without paths:
                frontmatter, plus the project equivalents.
codebuddy       .codebuddy/rules/**/*.md (project and home) unless
                alwaysApply: false, plus CODEBUDDY.md.
codex           ~/.codex/AGENTS.md and the project AGENTS.md.
cursor          .cursor/rules/**/*.mdc with alwaysApply: true, and AGENTS.md.
gemini-cli      ~/.gemini/GEMINI.md and the project GEMINI.md.
github-copilot  .github/copilot-instructions.md and the project AGENTS.md.
hermes          ~/.hermes/SOUL.md, project .hermes.md, AGENTS.md, CLAUDE.md.
                The support tree and apothem/rules/ are not launch surfaces.
kimi-code       ~/.kimi-code/AGENTS.md, project AGENTS.md and .kimi-code/AGENTS.md.
kiro            .kiro/steering/**/*.md with inclusion: always or no inclusion
                key, and the project AGENTS.md.
open-claw       Workspace bootstrap files ~/.openclaw/workspace/*.md.
opencode        ~/.config/opencode/AGENTS.md, the project AGENTS.md, and every
                file the instructions globs in opencode.json match.
qwen-code       The context files named by context.fileName in
                ~/.qwen/settings.json (default QWEN.md), in ~/.qwen/ and the project.
trae            .trae/rules/**/*.md with alwaysApply: true, and
                ~/.trae/user_rules/*.md.
windsurf        .devin/rules/**/*.md and .windsurf/rules/**/*.md with
                trigger: always_on, the global global_rules.md, and AGENTS.md.
zed             The first of .rules, .cursorrules, .windsurfrules, .clinerules,
                .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md,
                GEMINI.md in the project, plus ~/.config/zed/AGENTS.md.
glm             Nothing: GLM is a model backend and loads no instruction files.

Evaluaciones de comportamientoCopy Anchor Link

La suite bajo evals/ mide el comportamiento en lugar de la forma: 148 casos de activación (cada comando, skill y subagente invocable por el modelo se activa ante una solicitud de su dominio y no se activa ante una solicitud cercana que queda fuera de él, y seis comandos que solo invoca el usuario no se inician por sí solos), 32 casos de resultado (uno por etapa de plan, etapa de investigación y dimensión de auditoría) y 6 pares de efecto de regla (el texto de una regla de muestra, presente y ausente). Los casos son datos simples que python -m pytest tests/unit/test_eval_suite.py valida sin coste; ejecutarlos se factura y es manual. Consulta Ejecutar las evaluaciones de comportamiento para el flujo de trabajo Evals, una ejecución local y cómo añadir un caso. Después de editar una regla que tiene un par, ejecuta python scripts/dev/sync_eval_rule_cases.py.

BenchmarksCopy Anchor Link

make benchmarks ejecuta los drivers por clase bajo src/apothem/benchmarks/, salvo bench_agents.py. Cada driver sale con 0 si pasa, 1 si supera el presupuesto, 2 si hay un error (la ejecución medida no se llevó a cabo) o 3 si no se midió.

• bench_hooks.py ejecuta cada comando shell: bash que registra hooks/hooks.json, tal como está escrito, sobre una carga útil real por evento y matcher, e informa la mediana del tiempo total, el comando más lento (comparado con el presupuesto del evento) y los caracteres inyectados. Un comando que no puede ejecutarse tal como está registrado (salida 126 cuando a un script le falta el bit de ejecución) es un error, no un aprobado.
• bench_agents.py informa NOT MEASURED (salida 3): lanzar un subagente requiere un entorno anfitrión y una llamada al modelo. make benchmarks no lo ejecuta.

La comprobación de presupuesto always-on (always-on-budget-grep) cuenta las palabras separadas por espacios en blanco, excluyendo la sección Bindings y las líneas de puntero a archivos complementarios. Su informe JSON también lleva always-on-loaded: los bytes, caracteres y palabras de los cuerpos sin frontmatter que carga un entorno, sumados sobre las reglas siempre activas. Apuntada al directorio de reglas distribuido, la comprobación también falla cuando esa suma supera un límite de bytes (informado como always-on-ceiling-bytes) o cuando el índice de reglas supera el suyo propio. Claude Code carga sus copias de las reglas sin la sección Bindings, así que su tamaño cargado es menor que la cifra que informa esta comprobación.

Auditoría del ecosistema: ejecutar la validaciónCopy Anchor Link

Dos superficies de validación complementarias cubren el ecosistema:

Comprobable por máquina (validadores de Python) — ejecútalos antes de cada commit:

python scripts/dev/validate_hooks.py       # Hook structure + Python-only hygiene
python scripts/dev/validate_ecosystem.py   # Full tree + frontmatter + delegated hook checks
python scripts/dev/chaos_pass.py           # Adversarial sweep across configured hooks
pytest tests                                    # Unit tests for the hook runtime

Dirigida por el asistente — para auditorías de referencias cruzadas, de narrativa y de convenciones:

/ecosystem-audit --focus all --fix

Esto ejecuta en paralelo:

• Auditoría de estructura: precisión del registro, existencia de archivos, validez del frontmatter
• Auditoría de artefactos: referencias cruzadas, cobertura de mandatos, orden de la canalización
• Auditoría de memoria: afirmaciones de los archivos de memoria frente al estado del sistema de archivos

Salida esperada: PASS con cero hallazgos en ambas superficies.

Si se informa FINDINGS:

• Revisa la severidad de cada hallazgo (Crítico / Importante / Consultivo)
• Aborda de inmediato los elementos Críticos
• Planifica los elementos Importantes para el próximo ciclo
• Considera los elementos Consultivos para la próxima iteración

¿Preguntas?Copy Anchor Link

Consulta:

• Esquema de frontmatter: site/content/docs/reference/artifact-schema.mdx
• Ciclo de vida de los artefactos: src/apothem/rules/persistent-conventions-vigilance.md § Artifact Evolution
• Mandatos operativos: src/apothem/rules/operational-mandates.md CM-1–10
• Referencia de la suite de plan: src/apothem/skills/plan-suite/master-template.md
• Notas de lanzamiento: CHANGELOG.md