spec 1.0 · normativo

Frontmatter do perfil de agente Leji

Tradução assistida por agentes de IA. Em caso de divergência, prevalece a página em inglês. Se você encontrar algum problema no texto, abra uma issue ou envie um pull request.

Valida o frontmatter YAML de um documento de perfil de agente. O corpo em markdown continua livre.

$id canônico: https://leji.org/schemas/v1.0/agent-profile.schema.json
Arquivo bruto: agent-profile.schema.json

Campos

#idstringobrigatório

Identificador estável deste perfil, por exemplo "core" ou "reviewer".

Padrão ^[a-z0-9]+(-[a-z0-9]+)*$

#namestringobrigatório

Nome do papel, legível por pessoas.

#rolestringobrigatório

O identificador do papel que este perfil ocupa, associado no mapa agents do manifesto.

#purposestring

Uma linha sobre para que serve este papel.

#versionstring

Versão deste perfil; opcional.

#inheritsstring

id do único perfil core cujos arrays de postura e cujo corpo este perfil estende, resolvido conforme a especificação. A resolução tem um só nível: o alvo precisa existir, ser único e declarar role core. Um perfil que declara inherits pode omitir requiredRead e mustAskWhen onde o perfil base já os fornece.

Padrão ^[a-z0-9]+(-[a-z0-9]+)*$

#requiredReadarray de strings

Os caminhos que este papel carrega antes de qualquer tarefa.

#defaultContextarray de "domain" · "system" · "practice" · "governance" · "decisions"

As categorias que este papel carrega por padrão.

#mustAskWhenarray de strings

As condições em que o papel precisa parar e perguntar a uma pessoa.

#mustRefuseWhenarray de strings

As condições em que o papel precisa recusar de imediato, em vez de perguntar.

#escalationstring

Para quem ou para onde escalar.

#ownersarray de strings

Os donos deste perfil; opcional.

#freshnessobject

Horizonte de atualidade deste perfil.

reviewAfterstring

Data em ISO 8601 a partir da qual o perfil deve ser revisado para ver se está desatualizado.

#hoststring

O host de agente que executa este agente, por exemplo "claude-code", "codex", "cursor". Omita em perfis que não dependem de host.

#invocationobject

Como acionar este agente como uma CLI externa. Omita para o agente residente do próprio host.

commandstringobrigatório

Modelo de comando para acionar este agente a partir de um shell. Precisa trazer o texto de espaço reservado <prompt>, sozinho como uma palavra de shell sem aspas; o padrão apenas confere que o lugar da substituição existe, e a posição é regra da especificação.

constraintsarray de strings

Restrições operacionais que vale a pena a máquina conhecer, por exemplo limites de tamanho de prompt e tempos limite.

Schema e exemplo

SchemaExemplo · thought-partner.md

{
  "$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."
    }
  }
}

Um perfil de agente em conformidade. Este schema valida o frontmatter YAML; o corpo em markdown logo abaixo é texto livre.

---
id: thought-partner
name: Thought Partner (Codex)
role: thought-partner
purpose: Segunda opinião independente sobre textos, decisões de design e questões de julgamento.
host: codex
invocation:
  command: codex exec --skip-git-repo-check <prompt>
  constraints:
    - mantenha os prompts curtos; prompts muito longos travam a CLI
    - não interativo; um prompt entra, uma resposta sai, sem estado de sessão
inherits: core
requiredRead:
  - docs/boot-profile.md
mustAskWhen:
  - o veredito mudaria uma decisão já registrada
  - a pergunta envolve material confidencial que ainda não está na camada de contexto
---

# Thought Partner (Codex)

Acionado pelo papel `thought-partner` em `leji.json`, nunca pelo nome dentro
dos protocolos. Instrua-o com prompts autocontidos: o texto ou a decisão em
questão, as restrições que pesam sobre ele e a pergunta exata. Ele não tem
acesso a este repositório nem ao histórico dele; tudo o que ele deve ponderar
vai no prompt.

Trate os vereditos dele como uma perspectiva. Quando este parceiro e o agente
residente discordarem, a divergência vai para uma pessoa, com as duas leituras.

← Todos os schemas