spec 1.0 · normativo
Frontmatter del perfil de agente de Leji
Traducción asistida por agentes de IA. Ante cualquier diferencia, prevalece la página en inglés. Si encuentra algún problema en el texto, abra un issue o envíe un pull request.
Valida el frontmatter YAML de un documento de perfil de agente. El cuerpo en markdown queda libre.
Campos
- #
idstringobligatorio Identificador estable de este perfil, por ejemplo "core" o "reviewer".
Patrón
^[a-z0-9]+(-[a-z0-9]+)*$- #
namestringobligatorio Nombre del rol, legible por personas.
- #
rolestringobligatorio El identificador de rol que cubre este perfil, vinculado en el mapa agents del manifiesto.
- #
purposestring Una línea sobre para qué sirve este rol.
- #
versionstring Versión de este perfil; opcional.
- #
inheritsstring id del único perfil core cuyos arrays de postura y cuyo cuerpo extiende este perfil, resuelto según la especificación. La resolución es de un solo nivel: el destino debe existir, ser único y declarar el rol core. Un perfil que declara inherits puede omitir requiredRead y mustAskWhen allí donde el perfil base ya los aporta.
Patrón
^[a-z0-9]+(-[a-z0-9]+)*$- #
requiredReadarray de cadenas Rutas que este rol carga antes de cualquier tarea.
- #
defaultContextarray de "domain" · "system" · "practice" · "governance" · "decisions" Categorías que este rol carga por defecto.
- #
mustAskWhenarray de cadenas Condiciones en las que el rol debe detenerse y preguntar a una persona.
- #
mustRefuseWhenarray de cadenas Condiciones en las que el rol debe negarse sin más, en vez de preguntar.
- #
escalationstring A quién o a dónde escalar.
- #
ownersarray de cadenas Responsables de este perfil; opcional.
- #
freshnessobject Horizonte de revisión de este perfil.
reviewAfterstringFecha ISO 8601 a partir de la cual conviene revisar el perfil por si está desactualizado.
- #
hoststring El host de agente que ejecuta este agente, por ejemplo "claude-code", "codex" o "cursor". Omítalo en los perfiles independientes del host.
- #
invocationobject Cómo invocar este agente como una CLI externa. Omítalo cuando se trate del agente residente del propio host.
commandstringobligatorioPlantilla de comando para invocar este agente desde un shell. Debe llevar el marcador <prompt> como palabra de shell propia y sin comillas; el pattern solo comprueba que el punto de sustitución existe, y su colocación la fija la especificación.
constraintsarray de cadenasRestricciones operativas que conviene que una máquina conozca, por ejemplo límites de longitud del prompt o tiempos de espera.
Esquema y ejemplo
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://leji.org/schemas/v1.0/agent-profile.schema.json",
"title": "Leji agent profile frontmatter",
"description": "Validates the YAML frontmatter of an agent profile document. The markdown body stays free-form.",
"type": "object",
"required": [
"id",
"name",
"role"
],
"if": {
"not": {
"required": [
"inherits"
]
}
},
"then": {
"required": [
"requiredRead",
"mustAskWhen"
]
},
"additionalProperties": false,
"properties": {
"id": {
"description": "Stable identifier for this profile, e.g. \"core\" or \"reviewer\".",
"type": "string",
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
},
"name": {
"description": "Human-readable name of the role.",
"type": "string",
"minLength": 1
},
"role": {
"description": "The role identifier this profile fills, bound in the manifest's agents map.",
"type": "string",
"minLength": 1
},
"purpose": {
"description": "One line on what this role is for.",
"type": "string"
},
"version": {
"description": "Optional version of this profile.",
"type": "string"
},
"inherits": {
"type": "string",
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
"description": "id of the single core profile whose posture arrays and body this profile extends, resolved per the specification. Resolution is single-level: the target must exist, be unique, and declare role core. A profile that declares inherits may omit requiredRead and mustAskWhen where the base supplies them."
},
"requiredRead": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+$"
},
"description": "Paths this role loads before any task."
},
"defaultContext": {
"type": "array",
"items": {
"enum": [
"domain",
"system",
"practice",
"governance",
"decisions"
]
},
"description": "Categories this role loads by default."
},
"mustAskWhen": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
},
"description": "Conditions under which the role must stop and ask a human."
},
"mustRefuseWhen": {
"description": "Conditions under which the role must refuse outright rather than ask.",
"type": "array",
"items": {
"type": "string"
}
},
"escalation": {
"type": "string",
"description": "Who or what to escalate to."
},
"owners": {
"description": "Optional owners of this profile.",
"type": "array",
"items": {
"type": "string"
}
},
"freshness": {
"description": "Review horizon for this profile.",
"type": "object",
"additionalProperties": false,
"properties": {
"reviewAfter": {
"description": "ISO 8601 date after which the profile should be reviewed for staleness.",
"type": "string",
"pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"
}
}
},
"host": {
"type": "string",
"description": "The agent host that runs this agent, e.g. \"claude-code\", \"codex\", \"cursor\". Omit for host-agnostic profiles."
},
"invocation": {
"type": "object",
"additionalProperties": false,
"required": [
"command"
],
"properties": {
"command": {
"type": "string",
"pattern": "<prompt>",
"description": "Command template to engage this agent from a shell. Must carry the <prompt> placeholder, standing as its own unquoted shell word; the pattern verifies the substitution site exists, placement is the spec's rule."
},
"constraints": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operational constraints worth machine-knowing, e.g. prompt length limits, timeouts."
}
},
"description": "How to engage this agent as an external CLI. Omit for the host's own resident agent."
}
}
}Un perfil de agente conforme. Este esquema valida el frontmatter YAML; el cuerpo en markdown que hay debajo es prosa libre.
---
id: thought-partner
name: Thought Partner (Codex)
role: thought-partner
purpose: Segunda opinión independiente sobre textos, decisiones de diseño y cuestiones de criterio.
host: codex
invocation:
command: codex exec --skip-git-repo-check <prompt>
constraints:
- mantenga los prompts breves; los prompts muy largos bloquean la CLI
- no interactivo; entra un prompt, sale una respuesta, sin estado de sesión
inherits: core
requiredRead:
- docs/boot-profile.md
mustAskWhen:
- cuando el veredicto cambiaría una decisión ya registrada
- cuando la pregunta implica material confidencial que no está ya en la capa de contexto
---
# Thought Partner (Codex)
Se invoca a través del rol `thought-partner` de `leji.json`, nunca por su nombre
en los protocolos. Dele el encargo con prompts autocontenidos: el texto o la
decisión de que se trate, las restricciones que lo condicionan y la pregunta
exacta que hay que responder. No tiene acceso a este repositorio ni a su
historial; todo lo que deba sopesar tiene que ir en el prompt.
Trate sus veredictos como una perspectiva más. Cuando el thought partner y el
agente residente discrepan, el asunto pasa a una persona, citando ambas posturas.