Especificación del esquema de artefactos

Plantillas de frontmatter YAML por clase y campos obligatorios para todos los artefactos del ecosistema Apothem.

Fuente de verdad. El contrato legible por máquina y aplicado por la puerta lo forman los JSON Schemas por clase bajo src/apothem/schemas/ (agent.schema.json, command.schema.json, skill.schema.json, …). Los esquemas de skill y de comando declaran additionalProperties: false, así que rechazan las claves desconocidas; los esquemas de agente, de output-style y de plan declaran additionalProperties: true. Esta página y frontmatter-schema.mdx son las dos proyecciones legibles por humanos de esos esquemas: esta página lleva las plantillas y los ejemplos desarrollados por clase, y frontmatter-schema, el índice conciso de claves obligatorias. Cuando una página discrepa de los JSON Schemas, prevalecen los esquemas.

Visión generalCopy Anchor Link

Todos los artefactos del árbol de fuentes de Apothem (bajo src/apothem/ y la superficie de configuración raíz) deben incluir un bloque de frontmatter YAML (entre delimitadores ---) con campos obligatorios y opcionales específicos de su tipo de artefacto. Este documento define el esquema canónico de cada tipo.

Reglas universales:

• El frontmatter cumple con YAML 1.2
• Todos los valores de cadena usan comillas dobles, y una cadena vacía se escribe ""
• Orden de los campos: primero los obligatorios; los opcionales, agrupados por relevancia
• Los comentarios en el frontmatter usan # seguido de un espacio: # comment
• Los valores de ruta deben ser relativos (sin / inicial) y usar barras diagonales (/) para la compatibilidad multiplataforma

Convención de versionado (clases de artefacto versionadas: comandos, ayudantes, skills, CLAUDE.md):

• version es semántica (MAJOR.MINOR.PATCH). Incrementa MAJOR para los cambios incompatibles de esquema o de contrato; MINOR para los cambios aditivos compatibles (nuevos campos opcionales, secciones adicionales, antipatrones adicionales); PATCH para un cambio de comportamiento que corrige una directiva existente sin romper el contrato.
• Las correcciones de erratas y de enlaces, el formato y las ediciones que solo tocan comentarios o documentación dejan version sin cambios. Solo un cambio de comportamiento la incrementa.
• updated es la fecha ISO 8601 (YYYY-MM-DD) de la edición más reciente. Debe cambiar con cada incremento de version, y también cambia con una corrección de erratas o de enlaces que no incrementa la versión.
• Los artefactos nuevos comienzan en v0.Y.Z. La promoción a vX.Y.Z indica que el contrato del artefacto es lo bastante estable como para ser un compromiso público.
• Las suites de plan quedan fuera de esta convención. Una corrección de erratas en una suite de plan incrementa el número PATCH de la versión de la suite (vX.Y.Z a vX.Y.(Z+1)) y añade una fila al Historial de revisiones. La guía para desarrolladores describe la regla de las suites de plan en su sección de revisiones de suites de plan.

Esquema: reglasCopy Anchor Link

Patrón de ruta: src/apothem/rules/*.md

Propósito: Mandatos de comportamiento y directivas operativas.

Campos obligatoriosCopy Anchor Link

---
name: "kebab-case-identifier"
description: "One-line description"
pathFilter: "**/*.py, **/*.toml"
alwaysApply: true | false
---

Campos opcionalesCopy Anchor Link

Las reglas no llevan campos de frontmatter opcionales y, a diferencia de otras clases de artefacto, tampoco llevan los campos version / updated / scope / portability. Los cuatro campos obligatorios anteriores son el contrato completo de frontmatter de las reglas que aplica frontmatter_grep.

EjemploCopy Anchor Link

---
name: "operational-mandates"
description: "Behavioral definitions for CM-1 through CM-10: violation indicators and recovery actions"
pathFilter: ""
alwaysApply: true
---

# Rule: Operational Mandates
...

Esquema: comandosCopy Anchor Link

Patrón de ruta: src/apothem/commands/*.md

Propósito: Definiciones de comandos de barra (/plan-execute, /freshify, etc.).

Campos obligatoriosCopy Anchor Link

---
name: "command-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this command does"
argument-hint: "[argument-pattern]"
disable-model-invocation: true | false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

Campos opcionalesCopy Anchor Link

Los comandos no llevan campos de frontmatter opcionales: los ocho campos obligatorios anteriores son el contrato completo de frontmatter de los comandos que aplica command.schema.json (additionalProperties: false).

EjemploCopy Anchor Link

---
name: "plan-execute"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Executes a specific phase from a Master Plan Suite with conformity checking and quality gates"
argument-hint: "[path/to/plan-suite/] [phase-id] [--dry-run]"
disable-model-invocation: true
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

# /plan-execute — Execute a Specific Phase
...

Esquema: ayudantesCopy Anchor Link

Patrón de ruta:

src/apothem/agents/*.md

Propósito: Definiciones persistentes de ayudantes (también llamados trabajadores delegados) para la exploración en paralelo, la auditoría y las puertas de calidad.

Campos obligatoriosCopy Anchor Link

---
name: "agent-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this agent specializes in"
tools: "Tool1, Tool2, Tool3"
disallowedTools: "Write, Edit"
maxTurns: 20
effort: "high" | "medium" | "low"
---

Campos opcionalesCopy Anchor Link

permissionMode: "default"       # Permission handling
memory: user | project | local  # Persistent-memory scope; omit for none
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

EjemploCopy Anchor Link

---
name: "codebase-explorer"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Deep codebase exploration — find patterns, trace dependencies, discover conventions, map architecture"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit, TodoWrite"
maxTurns: 20
effort: "high"
permissionMode: "default"
portability: "universal"
---

You are a codebase exploration specialist...

Esquema: skillsCopy Anchor Link

Patrón de ruta: src/apothem/skills/*/SKILL.md

Propósito: Definiciones de técnicas reutilizables con señales de detección y procedimientos de ejecución.

Campos obligatoriosCopy Anchor Link

---
name: "skill-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
---

Campos opcionalesCopy Anchor Link

argument-hint: "[args...]"                           # Usage pattern if userInvocable

EjemploCopy Anchor Link

---
name: "ecosystem-audit"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Comprehensive blind audit of the apothem ecosystem"
archetype: "audit-template"
userInvocable: true
disable-model-invocation: false
allowed-tools: "Read, Glob, Grep, Agent, TodoWrite"
argument-hint: "[--focus area] [--fix]"
---

## Purpose
...

Esquema: hooksCopy Anchor Link

Patrón de ruta: el bloque hooks de settings.json más las implementaciones de Python bajo src/apothem/hooks/.

Propósito: Declarar validadores activados por eventos y manejadores de gestión de estado que el host invoca en puntos bien definidos del ciclo de vida.

Esquema del archivo de ajustesCopy Anchor Link

La clave de nivel superior hooks asigna nombres de evento a arreglos de bloques matcher:

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "${PYTHON_BIN}",
          "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

La forma -m apothem.hooks.dispatch sirve para desarrollar desde un checkout del código fuente con PYTHONPATH=src.

Eventos obligatoriosCopy Anchor Link

La plantilla de Claude Code registra cuatro eventos: SessionStart, PreToolUse, PostToolUse y Stop. scripts/dev/validate_hooks.py comprueba en settings.json los cinco eventos de la tabla siguiente, que son un conjunto distinto, e informa de cada uno que no encuentra como un aviso, no como un fallo. PostToolUse está registrado, pero no es uno de los cinco. PreCompact y PostCompact figuran entre los cinco, pero no se registran en Claude Code (referencia de hooks), por lo que en ese caso el verificador emite un aviso por ambos.

Los valores de tiempo de espera reflejan los presupuestos canónicos de los eventos de hook: la tabla siguiente los reproduce para comodidad del lector; la fuente canónica prevalece.

dispatch.py también acepta UserPromptSubmit y Notification en su lista de eventos permitidos, por compatibilidad futura; ninguno de los dos está conectado en las plantillas distribuidas. Para habilitarlos, agrega un bloque matcher con el mismo patrón en forma exec.

Capa de PythonCopy Anchor Link

Cada comando de hook pasa por el mismo despachador de Python:

ValidaciónCopy Anchor Link

scripts/dev/validate_hooks.py aplica el contrato de los hooks:

• settings.json se analiza como JSON y declara cada uno de los cinco eventos de la tabla; que falte un evento es un aviso, no un fallo.
• Los tres scripts de Python existen y se analizan como Python válido.
• Todos los archivos de mensaje referenciados por argumentos --context-file existen.
• No aparece ninguna ruta absoluta de usuario codificada de forma fija (C:\Users\..., etc.) en src/apothem/hooks/**.py.
• Los artefactos de shell bajo src/apothem/hooks/ y scripts/ se limitan a los stubs aprobados de localizador / arranque.

Esquema: CLAUDE.mdCopy Anchor Link

Ruta: CLAUDE.md (raíz)

Propósito: Instrucciones de Claude Code acotadas al proyecto.

Frontmatter YAML obligatorioCopy Anchor Link

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Project-scoped Claude Code instructions for the Apothem source repository"
scope: "project"
portability: "project-local"
---

SeccionesCopy Anchor Link

CLAUDE.md se redacta en secciones de prosa, descritas en CLAUDE.md. Ningún validador exige una lista fija de secciones: scripts/dev/validate_ecosystem.py comprueba las claves de frontmatter anteriores.

Lista de verificación de validaciónCopy Anchor Link

Cada artefacto debe superar estas comprobaciones:

Validación del frontmatterCopy Anchor Link

• El YAML es sintácticamente válido (sin errores de análisis)
• Todos los campos obligatorios del tipo de artefacto están presentes
• name sigue la convención kebab-case
• version es semántica (MAJOR.MINOR.PATCH)
• updated tiene formato de fecha ISO 8601 (YYYY-MM-DD)
• description es una cadena no vacía, de una sola línea
• Los campos opcionales coinciden con los valores de enumeración esperados (si aplica)
• No hay erratas en los nombres de campo (usa los nombres canónicos del esquema)
• No hay espacios en blanco sobrantes ni problemas de formato

Validación del contenidoCopy Anchor Link

• El contenido comienza en una línea nueva después del --- de cierre; en los archivos de la familia Markdown, la línea de encabezado SPDX canónica es el primer contenido que le sigue
• No hay referencias internas del plan (cumplimiento de CM-7)
• Las referencias cruzadas se resuelven (si se listan otros artefactos)
• Los enlaces usan rutas relativas con barras diagonales

Validación de la portabilidadCopy Anchor Link

• No hay rutas absolutas codificadas de forma fija (usa rutas relativas)
• No hay sintaxis específica de Windows en los artefactos de alcance universal
• Los separadores de ruta son barras diagonales
• Las variables de entorno usan un formato independiente de la plataforma (${VAR} o nativo de la herramienta)

NotasCopy Anchor Link

• La coherencia como seguridad: El frontmatter canónico permite la validación automatizada, las herramientas y la verificación entre artefactos. Las desviaciones se acumulan rápidamente.
• Declaración de portabilidad: No todos los artefactos pueden ser universales. Declara las restricciones explícitamente: es mejor documentar una salvedad que distribuir un fallo silencioso.
• Kebab-case para los nombres: Fácil de usar en URL, scripts y contextos de línea de comandos. Evita los espacios, los guiones bajos y el camelCase en los nombres.
• Higiene del incremento de versión: Cada edición que cambie el comportamiento debe incrementar version y updated a la vez. Las correcciones de erratas, de enlaces y de formato dejan la versión sin cambios; las nuevas secciones opcionales o los nuevos antipatrones incrementan MINOR; la reorganización estructural o los cambios de contrato incrementan MAJOR.