haos-model-router

Files (1)

• SKILL.md

SKILL.md (first lines)

# HAOS Model Router

Autor: Gian Marco Menegussi Scaglianti. Decisao permanente do dono do projeto.

## Principio (nao negociavel)

1. **Qualidade primeiro.** O objetivo e a tarefa sair CERTA na primeira vez.
2. **Custo-beneficio segundo.** Dentro do que entrega qualidade, escolher o mais barato.
3. **Economia nunca por si so.** Nao existe "usar haiku pra poupar" quando a tarefa pede julgamento.
4. **Na duvida entre dois tiers, SOBE.** Retrabalho, decisao errada ou mensagem externa errada custa muito mais que a diferenca de token.
5. **O main (orquestrador) fica no modelo da sessao.** O router decide o modelo dos SUB-AGENTES, nao o do main.

## Matriz por tipo de tarefa

| Tipo de tarefa | Tier | Por que | Quando subir / descer |
|---|---|---|---|
| Varredura, inventario, leitura em massa, grep, listagem de arquivos | `haiku` | Trabalho mecanico, criterio ja dado, volume alto | SOBE pra sonnet se a varredura exige INTERPRETAR o que achou (nao so achar) |
| Formatacao, conversao de formato, extracao deterministica de campo, renomear em lote | `haiku` | Regra explicita, zero ambiguidade | SOBE se o formato de destino for ambiguo ou se houver dado sujo/heterogeneo |
| Resumo mecanico de log, contagem, checagem de existencia | `haiku` | Saida verificavel objetivamente | SOBE se o resumo vira base de decisao |
| Codigo de rotina, script, CRUD, integracao com API ja conhecida | `sonnet` | Padrao conhecido, custo-beneficio otimo | SOBE pra opus se e codigo de producao critico, concorrencia, idempotencia ou dinheiro |
| Analise de dados padrao, relatorio, dashboard de metrica ja definida | `sonnet` | Pipeline conhecido | SOBE pra opus/fable se a analise vai virar decisao de midia ou investimento |
| QA de checklist, conferencia item a item contra criterio escrito | `sonnet` | Criterio existe, so aplicar | SOBE pra opus se o QA e adversarial (procurar o que ninguem viu) |
| Documentacao tecnica, POP, README | `sonnet` | Estrutura conhecida | SOBE se o doc define contrato entre times/sistemas |
| Arquitetura de sistema, decisao tecnica com trade-off | `opus` | Erro aqui contamina tudo que vem depois | SOBE pra fable se a decisao tem impacto estrategico/financeiro alto |
| Debugging profundo de causa raiz, bug intermitente, corrupcao de dado | `opus` | Exige hipotese, refutacao e leitura de sistema inteiro | Nunca desce |
| Seguranca, auditoria, hardening, revisao de guard/permissao | `opus` | Falso negativo custa incidente | SOBE pra fable em auditoria de escopo amplo |
| Refatoracao ampla, migracao de dados, mudanca de contrato | `opus` | Efeito colateral em cadeia | Nunca desce |
| Verificacao adversarial (provar que o fix esta errado) | `opus` | O papel e achar o que passou | SOBE pra fable quando fecha entrega para o dono |
| Estrategia, posicionamento, plano de campanha | `fable` | Julgamento aberto, sem gabarito | Nunca desce |
| Conselho / conclave / segunda opiniao de decisao | `fable` | Qualidade do julgamento e o produto | Nunca desce |
| Copy de conversao de alto valor (VSL, carta, oferta, headline principal) | `fable` | Diferenca de tier vira diferenca de faturamento | Copy operacional de baixo risco pode descer pra sonnet |
| Briefing que gera GASTO ou MENSAGEM EXTERNA (ativar campanha, disparo, envio) | `fable` | Irreversivel; erro sai pra fora | Nunca desce |
| Sintese final de multi-agente, consolidacao de entrega | `fable` | E o ponto onde o erro dos outros e pego ou passa | Nunca desce |
| Julgamento de qualidade (isso esta bom o suficiente?) | `fable` | Exige gosto e padrao alto | Nunca desce |

## Regra de effort (Workflow)

O parametro `effort` (`low` / `medium` / `high` / `xhigh` / `max`) e ortogonal ao modelo.

- Mecanico e deterministico: `low`.
- Trabalho padrao (codigo, analise, doc): `medium`.
- Verificacao, juizo, decisao, sintese final: `high` ou acima.
- Nunca economizar effort em fase de verificacao. E exatamente ali que a economia custa caro.

## Composicao em Workflow

- Fase mecanica DESCE (haiku/sonnet, effort low/medium).
- Fase de verificacao, decisao ou sintese SOBE (opus/fable, effort high+).
- Declarar `model` explicitamente em CADA `agent()` do script e em cada item de `meta.phases`.
- Workflow sem `model` declarado = roteamento por acaso. Nao aceitar.

## Como declarar

- Ferramenta `Agent`: parametro `model` OBRIGATORIO, valor em `haiku` | `sonnet` | `opus` | `fable`.
- No briefing do sub-agente, incluir uma linha:
  `MODELO: <tier> porque <motivo em 1 frase>`
- Ao spawnar, o main mostra ao dono essa mesma linha, curta, sem enrolacao. Uma linha por agente.

Exemplo:
```
MODELO: opus porque e causa raiz de bug intermitente em producao, nao rotina.
MODELO: haiku porque e varredura de arquivo com criterio ja fechado.
```

## Anti-padroes (nao fazer)

- `haiku` em tarefa que exige julgamento, trade-off ou juizo de qualidade.
- `fable` em grep, listagem ou conversao de formato.
- Economizar tier na fase de VERIFICACAO de qualquer pipeline.
- Spawnar Agent sem declarar `model` (o guard `model_guard.py` bloqueia).
- Escolher tier "porque a sessao ja estava nele". Herdar nao e decidir.
- Descer tier em tarefa que gera gasto, envio externo ou alteracao irreversivel.

## Trava fisica

O hook PreToolUse `model_guard.py` bloqueia qualquer chamada de `Agent` feita pelo MAIN dentro do escopo protegido sem `model` valido declarado. Sub-agentes nao sao afetados. `Workflow` nao e bloqueado pelo hook (o script e texto); a disciplina ali vem do `GATE MODELO` injetado a cada prompt pelo `prompt_router.py` e desta skill.

---

## Tarifa de spawn

Decisao do dono do projeto, tomada apos um conclave interno sobre quando o orquestrador deve
executar direto e quando deve delegar.

**O fato que gerou a regra.** Spawn nao e gratis e o custo NAO e proporcional a tarefa: o **boot do
sub-agente** domina. Piso medido de um spawn: **88k tokens e 1 minuto**. Mediana: **183k tokens e
8,3 minutos**. Nesta semana, **5 spawns triviais custaram 678k tokens** contra 10-40k se o main
tivesse feito na mao: **94% a 99% de desperdicio**. Escolher tier certo (secao acima) resolve metade
do problema; a outra metade e **nao pagar boot por nada**.

### Matriz: quando spawnar x quando NAO spawnar

| SPAWNAR (o boot se paga) | NAO SPAWNAR (o boot e o custo inteiro) |
|---|---|
| **3+ frentes independentes** rodando em paralelo | Tarefa que o main resolve em **ate 5 tool-calls de LEITURA** (ler arquivo, grep, checar existencia, `git status`, health check) |
| **Especialidade de produto** da tabela §4 do CLAUDE.md (copy, design, estrategia, midia, tracking, CRM) | **Reler o que o main JA tem em contexto**: o sub-agente vai ler de novo, do zero, e cobrar boot por isso |
| **Varredura volumosa**: mais de ~15 arquivos ou ~2.000 linhas, onde o ruido queimaria o contexto do main | **Verificacao visual de UI**: sub-agente NAO tem browser; quem olha a tela e o main |
| **Acao externa ou irreversivel** (publicar, enviar, ativar campanha, deploy, push, delete) | **Passo que exige MCP**: sub-agente NAO enxerga MCP (sem grafo de conhecimento, sem base vetorial de conhecimento, sem memoria de sessao, sem MCP de CRM/ERP proprio) |
| **Briefing que gera GASTO** ou mensagem para fora | **Transporte de arquivo sem julgamento**: o main move/copia/renomeia e delega so o MIOLO que exige juizo |
| **Escrita bloqueada pelo guard** (`main_guard.py` em ENFORCE) fora da allowlist de leitura | Passo unico dentro de uma cadeia que o main ja esta conduzindo, so para "ter um segundo par de olhos" sem hipotese concreta a testar |

**Regra de bolso:** *o spawn tem que comprar alguma coisa que o main nao tem* - especialidade,
volume que queimaria contexto, paralelismo, ou uma trava fisica. Se ele so repete o que o main faria,
voce pagou 88k de boot por nada.

> Este pacote nao inclui um regime de "cota de mutacao trivial" para o orquestrador: toda
> mutacao fora da allowlist de leitura pura vai para sub-agente (Regra de Ouro, ver docs).
> Se voce quiser um regime de cota, e uma extensao que voce escreve por cima deste guard,
> nao algo que este pacote traz pronto.

### Modelo por classe (com as metas do piloto)

| Classe de trabalho | Tier | Meta |
|---|---|---|
| Mecanico deterministico: inventario, grep em massa, formatacao, extracao de campo, contagem | `haiku` | **haiku >= 25% dos spawns** |
| Rotina: codigo padrao, script, integracao conhecida, relatorio, QA de checklist | `sonnet` | o volume do meio |
| Julgamento tecnico: causa raiz, arquitetura, seguranca, refatoracao ampla, verificacao adversarial | `opus` | **opus <= 45% dos spawns** |
| Julgamento aberto: estrategia, conclave, copy de alto valor, sintese final, acao externa | `fable` | sem teto |

From simtransforma/HAOS-CC-Model, MIT.

More from simtransforma/HAOS-CC-Model