docs: explain catalog evidence, loop safety and offline replay
This commit is contained in:
Evandro committed
1 parent
3f70b8dd48
commit
cfcce1fe8d
5 files changed
+501
-92
No files matched your search
+73
-8
@@ -2,7 +2,7 @@
|
||||
|
||||
# Dev Workflows
|
||||
|
||||
**Plugin do Claude Code (também para opencode e Hermes Agent) que ajusta o processo ao tamanho do pedido**: um roteador escolhe o nível, agentes com permissão mínima fazem o trabalho e um gate de qualidade determinístico decide quando terminou.
|
||||
**Plugin do Claude Code (também para OpenCode e OMP; Hermes recebe só skills) que ajusta o processo ao tamanho do pedido**: um roteador escolhe o nível, agentes com permissão mínima fazem o trabalho e um gate de qualidade determinístico decide quando terminou.
|
||||
|
||||
[](LICENSE)
|
||||
[](https://agentskills.io)
|
||||
@@ -62,6 +62,7 @@ git clone https://github.com/evandrodevbr/dev-workflows && cd dev-workflows
|
||||
python3 scripts/install.py claude # plugin: skills + agentes + hooks
|
||||
python3 scripts/install.py opencode # skills, agentes e plugin em ~/.config/opencode
|
||||
python3 scripts/install.py hermes # só skills, em ~/.hermes/skills
|
||||
python3 scripts/install.py omp # pacote nativo OMP: skills + agentes (sem hooks Claude)
|
||||
```
|
||||
|
||||
Claude Code sem clonar:
|
||||
@@ -73,9 +74,10 @@ Claude Code sem clonar:
|
||||
|
||||
Diferenças entre os agentes:
|
||||
|
||||
- **opencode** não consegue bloquear o fim do turno, então gate ausente ou falho vira aviso no log em vez de bloqueio. Os agentes viram subagentes do opencode com as mesmas permissões.
|
||||
- **Hermes** recebe só as skills; rode o gate você mesmo.
|
||||
- No opencode e no Hermes as cópias apontam para o seu clone: mantenha-o no lugar (ou rode a instalação de novo depois de mover).
|
||||
- **OpenCode** não consegue bloquear o fim do turno, então gate ausente ou falho vira aviso no log. Seus subagentes têm ferramentas negadas por padrão; o controlador externo verifica o gate por conta própria.
|
||||
- **OMP** usa plugin nativo com skills e sete agentes, sem hooks Claude. O controlador externo impõe o gate.
|
||||
- **Hermes** recebe só as skills; rode o gate você mesmo. Não existe executor Hermes para o loop.
|
||||
- No OpenCode e no Hermes as cópias apontam para o seu clone: mantenha-o no lugar (ou reinstale depois de mover). O pacote OMP é construído independentemente do clone.
|
||||
|
||||
Desligue o hook de `Stop` numa sessão com `DW_GATE=off`.
|
||||
|
||||
@@ -96,11 +98,12 @@ instalação: [`docs/SKILLS.md`](docs/SKILLS.md).
|
||||
```bash
|
||||
python3 qa/lint_skills.py # frontmatter, limites de tamanho, referências, links, caminhos de máquina
|
||||
python3 qa/test_gate.py # gate e hooks num repositório descartável
|
||||
python3 -m unittest discover -s qa -p 'test_*.py' -q # catálogo, roteador, adapters, loop
|
||||
python3 qa/check_upstream.py # skills vendorizadas atrás do upstream
|
||||
claude plugin validate --strict .claude-plugin/plugin.json
|
||||
```
|
||||
|
||||
O CI roda os dois primeiros em todo PR; a checagem de upstream roda todo mês.
|
||||
O CI roda lint, testes do gate/hooks e a suíte comportamental em todo PR; a checagem de upstream roda todo mês.
|
||||
|
||||
**Ainda não medido:** se o kit melhora o código que um agente produz. Estudos públicos
|
||||
([SkillsBench](https://arxiv.org/abs/2602.12670), [SWE-Skills-Bench](https://arxiv.org/abs/2603.15401))
|
||||
@@ -108,6 +111,67 @@ mostram que skills também podem piorar o resultado, então o próximo passo é
|
||||
sem o kit) no [Harbor](https://github.com/harbor-framework/harbor), com testes ocultos, score de
|
||||
mutação e checagens de segurança.
|
||||
|
||||
## Catálogo de modelos e loop de meta opt-in
|
||||
|
||||
A [spec de roteamento e loop](docs/goal-loop-model-routing-spec.md) está implementada em CLIs independentes; instalar um plugin **nunca inicia o loop**. Requisitos: Python 3.11+, Git, `bubblewrap` no Linux, CLI de agente suportada configurada, avaliador externo aprovado, checkout limpo e ferramentas do gate do projeto. Não rode em projetos sensíveis sem isolamento adicional: a CLI do agente pode acessar a rede e ler arquivos do host; **não** há sandbox de rede restrita só ao provider. Avaliador e gate rodam sem acesso à rede.
|
||||
|
||||
Para inspecionar modelos sem chamar nenhum deles (neste repositório):
|
||||
|
||||
```bash
|
||||
python3 scripts/model_catalog.py sync --tool opencode --providers opencode,opencode-go
|
||||
python3 scripts/model_catalog.py list --tool opencode --show-missing --format csv
|
||||
python3 scripts/model_catalog.py route --tool opencode --role planner --providers opencode,opencode-go --explain
|
||||
```
|
||||
|
||||
`sync` consulta fontes públicas [Zen](https://opencode.ai/zen/v1/models), [Go](https://opencode.ai/zen/go/v1/models), [OpenRouter](https://openrouter.ai/api/v1/models) e `opencode models <provider> --refresh` local; para OMP, passe `--tool omp --providers <provider-configurado>` para descobrir modelos locais. Lista, login armazenado ou tarifa OpenRouter **não comprovam** acesso da conta, cota Go, saldo Zen ou cobrança real. Rota pontuada elegível exige seus próprios `--availability-snapshot` e `--aa-snapshot` auditados; para cobranças/cotas nativas, `--price-overrides` com `native_tariffs`. Veja os [contratos](docs/goal-loop-model-routing-spec.md#4-contratos-de-dados-e-interface-proposta) e validadores de `scripts/model_catalog.py`. O Coding Agent Index v1.5 da AA é importado manualmente, com autorização e atribuição: sem scraping da leaderboard ou notas inventadas. Faixas fixas de nota de código: `[10,20)`, `[20,50)`, `[50,100]`; modelos inacessíveis ou sem nota não vencem uma rota pontuada. Preços OpenRouter em USD/1M são **comparativos**, não cobrança Zen/Go/Claude; cache ausente é `n/d`, não gratuito.
|
||||
Uma nota `exact` exige o mesmo harness e esforço de execução; outro harness só entra como `proxy` autorizado. No OMP, apenas esforços `thinking` anunciados pelo modelo local são elegíveis, inclusive IDs de modelo com `/`. Overrides públicos de contexto longo do OpenRouter entram no custo **referencial** do perfil de tokens.
|
||||
|
||||
A [tabela CSV completa capturada](docs/model-catalog-zen-go-2026-09-25.csv) inclui **122 modelos públicos** (Zen 80, Go 42) em 2026-09-25 07:18:38 UTC: **0/122 notas AA licenciadas importadas**, oito pareamentos de preço OpenRouter curados e nenhum acesso de conta confirmado localmente nesta captura. Reproduza **exatamente estes bytes, sem rede**, usando o [snapshot normalizado arquivado](docs/model-catalog-snapshot-2026-09-25/catalog-opencode.json) com `python3 scripts/model_catalog.py list --tool opencode --show-missing --format csv --cache-dir docs/model-catalog-snapshot-2026-09-25 --as-of-utc 2026-09-25T07:18:38Z`; o SHA-256 da saída é `80e2930877b20e5c47d4fd18f394c17a4683b257ca715496e91c63520d528230`. Sem `--as-of-utc`, o relatório de obsolescência usa o horário atual. Rode `sync` e `list --format csv` para catálogos/preços *atuais*. Dados públicos não são fatura nem garantia de acesso.
|
||||
|
||||
No `.dev-workflows.toml` **do aplicativo**, preserve seus `[commands]` do gate e defina um avaliador independente mantido fora do checkout. O stdout deve ser JSON com `schema_version: 1`, métrica/valor/unidade/direção configuradas, `checks` aprovados e evidências geradas sob `DW_REPORT_DIR` (veja o [contrato do avaliador](docs/goal-loop-model-routing-spec.md#4-contratos-de-dados-e-interface-proposta)). Exemplo com assinatura Claude e alias fixo, deliberadamente **sem ranking**:
|
||||
|
||||
```toml
|
||||
[loop]
|
||||
enabled = false # mude para true apenas quando decidir executar
|
||||
harness = "claude"
|
||||
tier = 1 # mudança de comportamento pequena; aumente para tarefas de risco
|
||||
max_iterations = 3
|
||||
max_minutes = 15
|
||||
max_stagnant = 2
|
||||
min_improvement = 1
|
||||
max_paid_usd = 0
|
||||
|
||||
[loop.goal]
|
||||
name = "app_quality"
|
||||
unit = "points"
|
||||
direction = "maximize"
|
||||
target = 80
|
||||
|
||||
[loop.evaluator]
|
||||
argv = ["python3", "/caminho/absoluto/fora/do/checkout/evaluate.py"]
|
||||
trusted_sha256 = "<cole os 64 caracteres do SHA-256 do avaliador>"
|
||||
required_checks = ["test", "lint"]
|
||||
|
||||
[models.roles.implementer]
|
||||
model_key = "sonnet"
|
||||
billing_mode = "claude_subscription"
|
||||
manual_unranked_approval = true
|
||||
```
|
||||
|
||||
Aprove o arquivo/hash do avaliador (`sha256sum /caminho/absoluto/fora/do/checkout/evaluate.py`), defina meta mensurável e comandos do gate. Depois, **num checkout limpo do app** (troque `DW` pelo caminho absoluto deste repositório):
|
||||
|
||||
```bash
|
||||
DW=/caminho/absoluto/para/dev-workflows
|
||||
python3 "$DW/scripts/goal_loop.py" plan --config .dev-workflows.toml
|
||||
# Mude enabled = true no app, faça commit dessa escolha deliberada e então:
|
||||
python3 "$DW/scripts/goal_loop.py" run --config .dev-workflows.toml
|
||||
python3 "$DW/scripts/goal_loop.py" status --config .dev-workflows.toml --run <run-id>
|
||||
python3 "$DW/scripts/goal_loop.py" resume --config .dev-workflows.toml --run <run-id>
|
||||
python3 "$DW/scripts/goal_loop.py" stop --config .dev-workflows.toml --run <run-id>
|
||||
```
|
||||
|
||||
`plan` não chama agentes; `run` mede o score inicial do app e tenta mudanças em worktrees separados. Cada tentativa cria um commit candidato detached; o gate e o avaliador executam em cópias limpas e separadas desse commit, sem arquivos ignorados criados pelo agente. Só aceita melhora após gate `pass` atual, checks obrigatórios e avaliação independente. Não faz merge, publicação ou exclusão da sua branch/worktrees; inspecione `status` e o worktree/commit vencedor antes de decidir aplicar. Estado/evidências ficam em `$XDG_STATE_HOME/dev-workflows` (padrão `~/.local/state/dev-workflows`). `resume` revalida configuração/avaliador/gate/base/rota; `stop` solicita parar novas tentativas, sem interromper imediatamente uma chamada em andamento. Zen/pay-as-you-go requer auditoria recente de conta/saldo, estimativa nativa, orçamento explícito e positivo **e** autorização interativa antes de cada chamada; consumo real desconhecido pausa o loop e impede retomada automática, pois estimativas não são limite rígido de cobrança. Go exige cotas recentes por modelo para 5h/semana/mês, sem fallback para saldo Zen. Assinatura Claude **não** recebe custo fictício USD/token nem nota AA emprestada do alias.
|
||||
|
||||
## Estrutura
|
||||
|
||||
```
|
||||
@@ -115,9 +179,10 @@ mutação e checagens de segurança.
|
||||
skills/ dev-router, lean-code, workflows wf-*, skills vendorizadas (NOTICE.md)
|
||||
agents/ explorer, planner, implementer, reviewer, security-auditor, ui-critic, verifier
|
||||
hooks/hooks.json Stop, PreToolUse, PostToolUse
|
||||
scripts/ quality-gate, install.py, hooks/*.py
|
||||
adapters/opencode/ plugin do opencode
|
||||
qa/ lint, testes do gate, checagem de upstream
|
||||
scripts/ quality-gate, instalação, catálogo/roteador, loop, executores e hooks
|
||||
adapters/opencode/ plugin do OpenCode
|
||||
adapters/omp/ construtor do pacote nativo OMP
|
||||
qa/ lint, testes do gate e de integração, checagem de upstream
|
||||
docs/SKILLS.md inventário de skills e comandos de instalação
|
||||
```
|
||||
|
||||
|
||||
Reference in new issue
Block a user