BehaviorHarness

Harness comportamental para agentes de IA — funciona como plugin do OpenCode e como servidor MCP, impondo gates de fluxo de trabalho que o modelo não pode pular.

O harness força uma sequência obrigatória de verificação (preflight → domain-check → prohibited-check → verify) e injeta as regras diretamente no system prompt, de modo que regras comportamentais deixam de ser texto ignorável e passam a ser estruturalmente aplicadas.

Instalação

npm install behavior-harness

O pacote expõe duas camadas independentes. Use uma ou as duas — se uma falhar, a outra continua operacional.

1. Como plugin do OpenCode

Em opencode.json / opencode.jsonc:

{
  "plugin": ["behavior-harness"]
}

O plugin:

• injeta as regras do harness no system prompt de todo request (funciona em Plan e Build mode);
• registra os slash commands /harness-verify e /harness-status.

2. Como servidor MCP

{
  "mcp": {
    "harness": {
      "type": "local",
      "command": ["npx", "behavior-harness"],
      "enabled": true
    }
  }
}

O servidor MCP fornece as ferramentas de gate descritas abaixo. É compatível com qualquer cliente MCP (OpenCode, Claude Desktop, Cursor, Gemini CLI).

Ferramentas (gates)

| Ferramenta | Papel | |---|---| | harness_preflight(task) | Obrigatória primeiro. Analisa a tarefa, define o agente autorizado, libera o gate de edição e inicia o rastreamento de fluxo. | | harness_select_agent(change_type) | Retorna o agente correto e as fronteiras de domínio para um tipo de mudança. | | harness_domain_check(agent, file_path) | Gate de edição. Bloqueia se o preflight não foi chamado ou se o agente não está autorizado para o arquivo. | | harness_prohibited_check(code_snippet) | Verifica padrões proibidos (smell-code) e registra a chamada no log da sessão. | | harness_verify() | Gate final. Audita o fluxo da sessão e falha com a lista de violações se alguma etapa obrigatória foi pulada. | | harness_run_checks(full_suite?) | Executa validação real via scripts Python (security, lint, typecheck, tests). | | harness_session_status() | Retorna o estado atual da sessão: gates chamados, arquivos aprovados e violações detectadas. |

Fluxo imposto

harness_preflight(task)            → desbloqueia a sessão
  └─ harness_domain_check(...)     → antes de editar cada arquivo
       └─ harness_prohibited_check → após escrever código novo
            └─ harness_verify()    → antes de reportar conclusão

Diferente de um lembrete em Markdown, os gates bloqueiam de fato:

• harness_domain_check retorna blocked: true se o preflight não foi chamado (PREFLIGHT_REQUIRED) ou se o agente não é o autorizado (WRONG_AGENT).
• harness_verify retorna FLOW_VIOLATIONS_DETECTED e impede a conclusão se qualquer etapa obrigatória foi pulada, listando exatamente o que falta.

Tipos de mudança e agentes

O harness_preflight detecta o tipo de mudança a partir da descrição (pt-BR/en) e roteia para o agente correto, entre 16 tipos (ui, api, db, infra, bug, auth, refactor, perf, audit, docs, test, seo, mobile, game, planning, unknown) e 20 agentes. Tarefas complexas (3+ domínios) são roteadas para o orchestrator.

Configuração por projeto (opcional)

Crie um harness.config.json em qualquer diretório-pai do processo para estender o comportamento:

{
  "projectName": "meu-projeto",
  "extraProhibitedPatterns": ["console.log em produção"]
}

Campos suportados: projectName, customAgents, customDomains, extraProhibitedPatterns.

Build

pnpm build          # gera dist/index.js (plugin) + dist/server.js (MCP)
pnpm build:plugin   # apenas o plugin (tsup)
pnpm build:mcp      # apenas o servidor MCP (tsc)

Licença

MIT