setup-opencode-harness

Spec-Driven Development com um harness determinístico e engenharia de loop. O processo não é só documentado — é imposto por máquina. Cada regra verificável é um check (script com exit code) que roda antes de cada ação do agente e bloqueia o que falha. A mesma lista de checks roda no agente, no /validate-all e na CI.

Instalador para OpenCode que materializa agentes, skills, commands, plugins e um harness de checks num projeto (ou global).

---

Por que usar

Setups de agente comuns escrevem o processo em prosa e torcem pra o modelo seguir. Funciona até não funcionar: o agente esquece, ninguém percebe, a regra é violada em silêncio. Quanto maior o projeto e mais longo o loop, pior.

Este setup troca confiança por imposição:

• Harness determinístico — regras como checks executáveis que bloqueiam tool calls. Sem spec? bloqueado. Secret hardcoded? bloqueado. Código sem rastreio? bloqueado.
• Loop evaluator-optimizer — o @evaluator mede cada acceptance criterion (PASS/FAIL) e fecha o loop gera→avalia→refina, com condição de parada.
• Cresce conforme o uso — adicionar uma regra = um arquivo + uma linha no registry. Zero mudança no core. (Modelo inspirado no GitHub Spec Kit.)
• Uma fonte de verdade — o que o agente respeita é o que o /validate-all e a CI cobram. Sem divergência.

Quando usar

Use quando…	Talvez não precise quando…
Time >1 pessoa, precisa de consistência	Script de uso único, descartável
Projeto que vai crescer / viver muito	Protótipo de algumas horas
Há regras não-negociáveis (segurança, rastreabilidade)	Exploração livre sem requisitos
Você roda loops de iteração	Tarefa de um passo só

Regra prática: comece simples. Ligue só os gates que doem; promova audit → gate conforme a confiança.

Como usar

# interativo (wizard)
./setup.sh

# não-interativo (CI / padronizar o time)
./setup.sh --answers answers.env

Requisitos: bash >= 4.3, jq. Para validar/desenvolver: shellcheck, bats.

Depois, no OpenCode:

/new-spec → /clarify → (humano aprova) → /gen-plan → /gen-tasks
   → /analyze → /implement-spec → @evaluator (loop) → /validate-all → PR
        ↑ gates do harness rodam automaticamente em cada escrita ↑

---

O harness

Vive em .opencode/harness/ (versionado — é a fonte de regras do time):

.opencode/harness/
  registry.json        ← declara cada check (prioridade, quando roda, bloqueia?)
  lib/common.sh        ← helpers (classificar arquivo, ler status de spec)
  checks/
    10-spec-exists.sh    GATE  — código sem nenhuma spec
    20-spec-approved.sh  GATE  — spec/plano ativos não aprovados
    30-trace-comment.sh  GATE  — código novo sem "Spec: docs/specs/NNNN"
    40-no-secrets.sh     GATE  — secret hardcoded
    50-ac-coverage.sh    AUDIT — AC sem task
    60-task-has-test.sh  AUDIT — task sem teste
  state/current.json   ← fase do loop + spec ativa (runtime, gitignored)

Modo	Quando roda	Efeito
gate	antes de cada tool call (em on)	exit ≠ 0 bloqueia
audit	sob demanda (/analyze, /validate-all, CI)	exit ≠ 0 reporta

Adicionar um check (cresce conforme o uso):

1. Crie checks/70-nome.sh (use os helpers de lib/common.sh).
2. Registre em registry.json (id, script, on, mode, blocking).
3. Reinicie a sessão. Zero mudança no plugin.

Detalhes em .opencode/harness/README.md e na skill harness-checks.

Plugins

• harness.ts — lê o registry e roda os gates em tool.execute.before. Bloqueia a tool com a mensagem do check.
• loop-state.ts — mantém state/current.json (fase + spec) e re-injeta o estado na compactação de contexto, pra o agente não "esquecer" a fase em loops longos.

---

Agentes

Agente	Papel	Modo
@spec-author	escreve specs (o quê/por quê + acceptance criteria)	primary
@planner	spec aprovada → plan.md + tasks.md	primary
@developer	implementa task a task, com rastreio	primary
@reviewer	code review read-only vs acceptance criteria	subagent
@tester	gera testes a partir dos acceptance criteria	subagent
@evaluator	mede cada AC PASS/FAIL, fecha o loop	subagent

Commands

Command	Faz
/new-spec	cria a spec da feature
/clarify	caça ambiguidade na spec antes de planejar
/gen-plan · /gen-tasks	plano técnico + tarefas testáveis
/analyze	consistência cruzada spec↔plan↔tasks (matriz de cobertura)
/checklist	"unit tests for English" — qualidade da própria spec
/implement-spec	implementa a próxima task (gates do harness ativos)
/converge	mede código vs spec e gera o delta de tasks (brownfield)
/trace	matriz de rastreabilidade spec→AC→task→código→teste
/why	explica o porquê de um arquivo/decisão (até a constituição)
/spec-status	panorama de todas as specs
/harness-status	fase do loop + gates ativos + resultado dos audits
/validate-all	lint + type-check + testes + audits do harness

---

Sessões & aliases

Contexto longo demais deixa o modelo mais lento, mais caro e mais propenso a se perder. Não acumule tudo num chat só — troque de sessão ao mudar de tarefa.

Situação	O que fazer
Assunto novo / outra tarefa	/new (alias /clear, atalho Ctrl+X N)
Mesma tarefa, contexto gigante	/compact (alias /summarize, Ctrl+X C) resume e segue
Voltar a uma sessão anterior	/sessions (aliases /resume, /continue, Ctrl+X L)
Desfazer / refazer o último turno	/undo / /redo

Regra prática: se você precisa rolar muito pra achar o começo da conversa, é hora de /new (assunto novo) ou /compact (mesma tarefa).

Aliases: no TUI, os commands (/nome) são seus atalhos — este setup já instala alguns; crie outros em .opencode/command/*.md. No shell:

alias oc='opencode'
alias ocr='opencode run'   # one-shot, sem abrir o TUI

---

Modelos

📖 Guia completo de modelos por papel, presets prontos e joias escondidas: veja MODELS.md.

O wizard pergunta o tier e três papéis. IDs free mudam — confirme com opencode models opencode.

Papel	Sugestão (free-zen)
spec-author / planner (mais forte)	MODEL_PLANNER
developer (executor)	MODEL_EXECUTOR
reviewer / tester / evaluator (mais leve)	MODEL_REVIEWER

Atenção: alguns modelos free usam seus dados para treino — não use com código sensível.

---

Desenvolvimento

bash -n setup.sh                                   # sintaxe
shellcheck setup.sh templates/harness/**/*.sh      # lint
bats tests/                                         # testes

A CI (azure-pipelines.yml) roda os três mais o shellcheck dos checks.

Estrutura

setup.sh                 wizard (pergunta, copia, substitui, valida)
answers.env.example      modo não-interativo
templates/
  agents/                spec-author, planner, developer, reviewer, tester, evaluator (.tpl)
  commands/              13 commands
  docs/                  CONCEPTS.md + specs/ (constitution, README, TEMPLATE)
  harness/               registry.json, lib/, checks/ (o coração)
  plugins/               harness.ts, loop-state.ts
  skills/                spec-writing, task-breakdown, loop-engineering, harness-checks, + stack
  references/            cole seus configs reais aqui
tests/                   setup.bats + fixtures

Relação com os outros setups

Setup	Foco
setup-opencode	DevOps/SRE
setup-opencode-dev	desenvolvimento de aplicações
setup-opencode-devtools	CLIs / tooling
setup-opencode-spec	Spec-Driven Development (base deste)
setup-opencode-harness	SDD + harness determinístico + loop engineering

Este é o mais avançado: pega o SDD do setup-opencode-spec e adiciona a camada que impõe o processo por máquina e estrutura os loops de iteração.