ESAA-Core AGENTS.md

AGENTS.md — Contrato operacional Codex/ESAA

Versão operacional curta para runners. Em divergência, os artefatos canônicos em .roadmap/ prevalecem. O ESAA não usa MCP. Use a CLI ESAA: python -m esaa.

1. Autoridade e termos

ESAA é o protocolo de governança. Harness executa. Orchestrator é o single writer do event store. Agente emite intenções válidas, nunca escreve diretamente no store.

Fontes canônicas:

• Event store: .roadmap/activity.jsonl.
• Projeções/read models: .roadmap/roadmap.json, .roadmap/issues.json, .roadmap/lessons.json.
• Contratos: .roadmap/AGENT_CONTRACT.yaml, .roadmap/ORCHESTRATOR_CONTRACT.yaml, .roadmap/agent_result.schema.json, .roadmap/RUNTIME_POLICY.yaml.

Read models são derivados do event store. Não edite manualmente roadmap.json, issues.json, lessons.json ou activity.jsonl.

2. CLI e runner

Em workspaces publicados, o pacote Python é esaa-core, mas o módulo/comando é esaa.

Comandos úteis:

python -m esaa --version
python -m esaa --root . verify
python -m esaa --root . eligible
python -m esaa --root . roadmap status --detail

Todo comando que escreve no event store deve identificar o runner:

# Informe o identificador real do runner que está executando a ação.
python -m esaa --root . --runner <runner_id> submit --actor agent-spec output.json

# Ou configure o runner uma vez por sessão:
$env:ESAA_RUNNER_ID = "<runner_id>"

Regras:

• Substitua <runner_id> pelo identificador exato do runner em execução.
• Use --runner <runner_id> ou ESAA_RUNNER_ID=<runner_id> em submit, task create, init e run.
• Não inclua o campo runner no JSON do agente; o Orchestrator o acrescenta ao evento.
• Runners registrados: claude-cowork, claude-code, codex, human-terminal e unattended.
• Com runner_validation: strict, um identificador não registrado é rejeitado com RUNNER_UNKNOWN.
• Novos runners devem ser registrados em .roadmap/agents_swarm.yaml antes de serem usados em modo strict.