Imported from rmaiafrontend/harness-orca (AGENTS.md). Install upstream with npx skills add rmaiafrontend/harness-orca. Copyright stays with the author.

AGENTS.md — harness-orca

Regras para qualquer agente que trabalhe neste repositório. Se você é um worker despachado por um harness que usa este repo, o arquivo que vale é o AGENTS.md daquele projeto, não este.

O que este repo é

Política de orquestração, não runtime. O runtime é o Orca (worktrees, ciclo de vida de worker, inbox, DAG, gates). Aqui mora só a decisão: como classificar uma task, qual capacidade ela exige, e como cada papel se comporta.

Não há build, não há teste automatizado. A verificação é a da seção final.

A regra que mais se quebra

Cada coisa mora numa camada só. Em policy/mapeamento.yaml isso é literal e verificável:

• capacidades, niveis, tipos são política. Não podem conter ID de modelo, nome de provider, nem fato desta máquina. Se você precisou escrever claude- ali, a mudança está na camada errada.
• resolucao é fato de máquina. É o único lugar onde ID de modelo aparece.

O mesmo vale para os papéis: se o conteúdo é universal, fica em roles/; se é de um projeto, vira chave no harness.yaml daquele projeto.

Nunca fixe flag do Orca de memória

A camada de orquestração é experimental e a doc pública é subconjunto do binário — 18 comandos documentados contra 29 instalados, com --deps entre os omitidos. Antes de escrever qualquer comando orca:

orca agent-context --json          # gramática exata: comandos, flags, usage
orca skills get orchestration --full   # semântica e ciclo de vida

onorca.dev/docs serve para modelo mental, nunca para flags. O histórico está em docs/orca-harness-orquestracao.md §14.

Proibido

• orca orchestration reset — não tem flag de escopo; atinge o runtime inteiro e destrói o trabalho de outros coordenadores.
• Inventar ID de modelo. Se não deu para confirmar com o provider, deixe null e controle o custo pelo effort.
• Copiar arquivo de roles/ ou policy/ para dentro de um projeto consumidor.

Verificação antes de reportar

python3 -c "import yaml,io,sys
alvos=['skills/orquestrar/policy/mapeamento.yaml',
       'template/harness.yaml.example','template/orca.yaml.example']
for f in alvos:
    try: yaml.safe_load(io.open(f,encoding='utf-8').read()); print('ok',f)
    except Exception as e: print('FALHOU',f,e); sys.exit(1)
s=io.open('skills/orquestrar/SKILL.md',encoding='utf-8').read()
assert s.startswith('---'), 'SKILL.md sem frontmatter'
print('frontmatter:', yaml.safe_load(s.split('---',2)[1])['name'])
assert s.count('\`\`\`') % 2 == 0, 'cercas de codigo desbalanceadas'
print('cercas ok')"

Só mapeamento.yaml, harness.yaml.example e orca.yaml.example são YAML. AGENTS.md.example é markdown e worktreeinclude.example é lista de caminhos — não passe nenhum dos dois pelo parser.

Confira também que o frontmatter de skills/orquestrar/SKILL.md continua parseável e que as cercas de código estão balanceadas — a skill é lida por máquina, e frontmatter quebrado a torna invisível para a descoberta.

E rode o verificador de comandos, que é o que torna executável a regra de não fixar flag de memória:

python3 scripts/verificar-comandos.py

Ele cruza cada invocação orca ... escrita no repo contra orca agent-context --json. Falha em comando inexistente, flag inválida ou flag obrigatória ausente. Rode depois de qualquer edição que escreva um comando orca — foi assim que se pegou um send de heartbeat sem --subject.