@fullchico/harness 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,46 +11,413 @@
11
11
  npx @fullchico/harness install .
12
12
  ```
13
13
 
14
- Ambiente de desenvolvimento com agentes, para o Claude Code. Um plugin que padroniza, em
15
- todo projeto que o adota, o fluxo de uma mudança, os guardrails e o ambiente de
16
- desenvolvimento por feature.
17
-
18
-
19
- ## O que ele faz
20
-
21
- - **Conduz uma mudança da entrevista ao pull request,** com `/harness:entregar`: entrevista,
22
- spec, revisão da spec, tickets em grafo, implementação em paralelo por subagentes,
23
- checagem, revisão de segurança e de código, envio.
24
- - **Traz a arquitetura junto.** Back em módulos com use cases, portas e adaptadores; front em
25
- Feature-Sliced Design; contrato entre os dois num pacote comum. O ofício vem de skills dos
26
- autores, copiadas para o projeto e fixadas no `skills-lock.json`; as convenções que resolvem
27
- os atritos entre elas estão no `AGENTS.md`.
28
- - **Paraleliza por contrato.** Cada ticket é dono de pastas (`Owns:`). Dois tickets paralelos
29
- nunca possuem o mesmo caminho, o contrato fecha antes dos demais começarem, e a integração
30
- recusa a branch que mexer fora da posse ou quebrar a checagem.
31
- - **Gasta o modelo caro só onde ele paga.** A sua sessão (Opus) faz a entrevista e a spec. A
32
- execução inteira é de um orquestrador em Sonnet, que recebe só a spec; os implementadores e
33
- os revisores também são Sonnet, e os implementadores e o trabalho bruto são Haiku.
34
- - **Não deixa código sem revisão chegar ao remoto.** O shell do agente roda no sandbox do
35
- Claude Code, sem rede para o servidor de git. O único caminho é `.harness/push`, que
36
- exige quatro aprovações sobre o commit (segurança, revisão de código, caça a bugs e
37
- qualidade: a checagem completa do projeto passou nele) e, para uma `feat`, a spec da mudança.
38
- - **Nenhum agente aprova o próprio trabalho.** A aprovação nasce do veredito de um revisor
39
- de contexto novo, gravada por um hook, num lugar onde o agente não escreve.
40
- - **Dá a cada feature o próprio ambiente Docker,** com portas e projeto isolados, levantado
41
- sem pedir nada a você.
42
- - **Mantém um mapa do código que não envelhece calado.** Cada resumo guarda o commit em que
43
- foi escrito, e o git diz, sem custo, o que mudou desde então. Toda sessão começa com o índice.
44
- - **Liga o `ponytail` e o `rtk` em todo projeto.** O `ponytail` segura o tamanho do código que
45
- o agente escreve; o `rtk` comprime a saída de git e de testes. Os dois entram como estão, sem
46
- adaptação.
47
- - **Mantém a configuração igual entre projetos.** O que o harness instala não é editado no
48
- projeto: muda aqui e chega por atualização.
49
-
50
- ## Pré-requisitos
51
-
52
- macOS ou Linux, `git`, `python3` 3.9 ou mais novo, Docker com Compose v2, e o Claude Code
53
- com sandbox disponível. O remoto do projeto precisa ser HTTPS. Recomendado: `rtk`.
14
+ Um plugin para o Claude Code que troca instrução por trilhos e portões (hooks, guards e
15
+ scripts), para que agentes levem uma mudança da entrevista ao pull request sem que nada
16
+ chegue ao remoto sem revisão independente.
17
+
18
+ ## Sumário
19
+
20
+ - [O conceito](#o-conceito)
21
+ - [Como é usar](#como-é-usar)
22
+ - [A entrevista](#a-entrevista)
23
+ - [Quem faz o quê](#quem-faz-o-quê)
24
+ - [Os portões](#os-portões)
25
+ - [O que é recusado por máquina](#o-que-é-recusado-por-máquina)
26
+ - [O que é instalado e o que é exigido](#o-que-é-instalado-e-o-que-é-exigido)
27
+ - [Instalar num projeto](#instalar-num-projeto)
28
+ - [Comandos](#comandos)
29
+ - [Configuração](#configuração)
30
+ - [Arquitetura que o harness espera](#arquitetura-que-o-harness-espera)
31
+ - [Ambiente por feature](#ambiente-por-feature)
32
+ - [Memória do projeto](#memória-do-projeto)
33
+ - [Projeto sem remoto](#projeto-sem-remoto)
34
+ - [Atualizar o harness](#atualizar-o-harness)
35
+ - [O que já foi provado e o que ainda não](#o-que-já-foi-provado-e-o-que-ainda-não)
36
+ - [Desenvolver o harness](#desenvolver-o-harness)
37
+ - [Licença](#licença)
38
+
39
+ ## O conceito
40
+
41
+ Uma instrução escrita num arquivo é texto, e texto o agente interpreta: ele pode ler de outro
42
+ jeito, esquecer no meio de uma sessão longa ou decidir que aquele caso é exceção. Um trilho
43
+ é diferente: é um hook, um guard ou um script que confere a regra e recusa o que não passa.
44
+ O agente não precisa concordar com ele, e não tem como atravessá-lo.
45
+
46
+ O harness aplica essa ideia ao ciclo inteiro de uma mudança. O que pode ser conferido por
47
+ máquina é conferido por máquina; o texto fica só para o que exige julgamento.
48
+
49
+ <img src="site/img/fluxo.svg" alt="Fluxo de uma entrega: pedido, entrevista, spec, revisão da spec, tickets, implementação em paralelo, integração, checagem, revisão e envio, com os portões entre as etapas">
50
+
51
+ São três princípios:
52
+
53
+ 1. **Quem escreve não aprova.** Revisão no mesmo contexto não é revisão. Todo revisor é um
54
+ subagente de contexto novo, que recebe só ponteiros para os documentos e para o diff, sem
55
+ a conversa nem a opinião de quem escreveu. A aprovação é gravada por um hook, a partir do
56
+ veredito do revisor, num lugar onde o agente não escreve.
57
+ 2. **Nada sai sem os portões.** O shell do agente roda no sandbox do Claude Code, sem rede
58
+ para o servidor de git. O único caminho até o remoto é `.harness/push`, que exige quatro
59
+ vereditos sobre o commit do topo da branch.
60
+ 3. **Paralelismo por contrato e posse de arquivo.** Cada ticket é dono de pastas (`Owns:`).
61
+ Dois tickets que rodam ao mesmo tempo nunca possuem o mesmo caminho, o ticket de contrato
62
+ fecha antes de todos os outros, e a integração recusa a branch que mexer fora da posse.
63
+
64
+ ## Como é usar
65
+
66
+ O loop é: pedido curto, entrevista, pronto. Você abre um worktree para a feature, faz o
67
+ pedido numa sessão do Claude Code dentro dele e responde à entrevista. O resto corre sem você.
68
+
69
+ ```text
70
+ /harness:entregar quero um sistema de agendamento para uma barbearia
71
+ ```
72
+
73
+ O que acontece em cada etapa:
74
+
75
+ | Passo | O que acontece | Quem faz |
76
+ |---|---|---|
77
+ | 1. Entrevistar | perguntas até não sobrar decisão em aberto; o vocabulário vai para o `GLOSSARY.md` e as decisões difíceis de reverter viram ADRs | a sua sessão, com você |
78
+ | 2. Especificar | a spec é escrita em `docs/specs/<slug>/spec.md` e entra em commit | a sua sessão |
79
+ | 3. Revisar a spec | um revisor de contexto novo lê a spec como quem vai implementá-la sem poder perguntar, e aponta o que falta | `revisor-spec` |
80
+ | 4. Fatiar | um arquivo por ticket em `docs/specs/<slug>/issues/`, com o que o bloqueia e o que ele possui | `orquestrador` |
81
+ | 5. Implementar | os tickets da fronteira do grafo rodam em paralelo, cada um num worktree próprio, com TDD | `implementador` |
82
+ | 6. Integrar | cada ticket passa pela caça a bugs e só então é juntado à branch da feature, um por vez | `revisor-bugs` e `.harness/integrate` |
83
+ | 7. Checar | a checagem completa do projeto, sem custo de IA | `.harness/validate` |
84
+ | 8. Revisar | quatro vereditos, em paralelo, sobre o mesmo commit | `seguranca`, `revisor`, `revisor-bugs`, `qualidade` |
85
+ | 9. Enviar | push, pull request, e o aplicativo deixado de pé | `.harness/push` e `.harness/pr` |
86
+
87
+ A entrega tem duas metades de propósito. O **desenho** (passos 1 a 3) acontece na sua sessão,
88
+ onde o raciocínio mais caro paga e onde você participa. A **execução** (passos 4 em diante) é
89
+ entregue a um subagente `orquestrador`, em modelo mais barato, que recebe só o caminho da
90
+ spec: o que ficou só na conversa não chega até ele.
91
+
92
+ No fim, o relato traz o link do pull request, o endereço do aplicativo que ficou rodando (com
93
+ o usuário de teste e como parar), o que entrou, o que ficou de fora, quantas rodadas de
94
+ correção houve e as decisões tomadas sem você. Depois do merge, `/harness:aprender` fecha o
95
+ ciclo.
96
+
97
+ ### Quando você é chamado
98
+
99
+ | Parada | Quando |
100
+ |---|---|
101
+ | A entrevista | sempre, no começo |
102
+ | Aprovar a spec (PARADA 1) | depois da revisão da spec: você resolve cada achado e aprova |
103
+ | Um ticket que não fecha (PARADA 2) | só se um ticket não fechar em 3 rodadas de correção |
104
+ | Remover um ambiente | `.harness/destroy` apaga dados, então sempre pergunta |
105
+ | Instalar uma skill nova | `.harness/skills-add` pergunta a cada skill |
106
+ | O merge | sempre seu, preservando os commits, sem squash |
107
+
108
+ Todo o resto roda sem pergunta: os comandos dentro do sandbox e os scripts do harness. Se
109
+ quiser alguma pergunta de volta, acrescente a regra em `permissions.ask` num fragmento do
110
+ projeto (`harness.d/settings.json`); pergunta vence liberação.
111
+
112
+ ### Seguir sem você
113
+
114
+ Se você disser "segue até o fim" (ou "pode seguir com o recomendado", "confio na sua análise"),
115
+ a entrega passa a correr em modo autônomo, e continua assim até você dizer o contrário:
116
+
117
+ - toda pergunta recebe a resposta recomendada, na entrevista e nos achados do revisor da spec;
118
+ - a aprovação da spec deixa de ser uma parada;
119
+ - cada decisão tomada sem você fica escrita na spec, na seção "Decisões tomadas sem o dono",
120
+ com o que foi escolhido, a alternativa descartada e o motivo.
121
+
122
+ O que continua parando: remover um ambiente, um ticket que não fecha em 3 rodadas, uma
123
+ decisão que depende de um dado que só você tem, e o merge. O modo autônomo não muda os
124
+ portões, as revisões nem o sandbox.
125
+
126
+ ### Quando o pedido é um bug
127
+
128
+ Bug entra pela skill `diagnosing-bugs` no lugar da entrevista. Não há spec nem tickets: a
129
+ própria sessão corrige, com teste, em commits `fix`, e depois passa pela mesma checagem,
130
+ pelos mesmos revisores e pelo mesmo envio.
131
+
132
+ ## A entrevista
133
+
134
+ A entrevista (grilling) é uma sequência de perguntas ao dono, até não sobrar decisão em
135
+ aberto. Ela vem antes de qualquer código porque quem executa não tem a quem perguntar: o
136
+ orquestrador e os implementadores nascem sem a conversa e trabalham só com o que está nos
137
+ documentos. Uma decisão que ficou de fora da spec vira um ticket reaberto no meio da entrega,
138
+ e uma rodada perdida para todos os que dependem dele.
139
+
140
+ <img src="site/img/entrevista.svg" alt="A entrevista: o pedido curto vira perguntas ao dono, e delas saem o glossário, os ADRs e a spec, que é revisada antes da execução">
141
+
142
+ Quem faz são skills do plugin de terceiros `mattpocock-skills`:
143
+
144
+ | Skill | Para quê |
145
+ |---|---|
146
+ | `grilling` | conduz a entrevista com o dono |
147
+ | `domain-modeling` | registra o vocabulário no `GLOSSARY.md` e as decisões difíceis de reverter em ADRs (`docs/adr/`) |
148
+ | `diagnosing-bugs` | substitui a entrevista quando o pedido é um bug |
149
+
150
+ O que sai da entrevista é a spec, escrita para alguém que vai implementar sem ter visto a
151
+ conversa. As seções dela:
152
+
153
+ | Seção | O que traz |
154
+ |---|---|
155
+ | Problema e Solução | o que incomoda hoje e o que passa a acontecer, do ponto de vista de quem usa |
156
+ | Histórias | lista numerada, cobrindo casos de erro e estados vazios, não só o caminho feliz |
157
+ | Decisões de implementação | módulos que nascem ou mudam, contratos, mudanças de esquema, e cada escolha da entrevista com o motivo |
158
+ | Decisões de teste | os pontos de costura: por onde cada comportamento é testado |
159
+ | Critérios de aceite | numerados; cada um vira um teste de ponta a ponta |
160
+ | Módulos e contrato | os módulos do back e as fatias do front, cada um com a sua pasta (daqui sai a posse de cada ticket); as operações entre front e back; o que cada módulo oferece e consome dos outros |
161
+ | Ambiente e execução | os serviços de que os testes dependem, como os implementadores se isolam e, em projeto novo, o conteúdo do `harness.conf` |
162
+ | Fora de escopo | o que não entra, dito com todas as letras |
163
+
164
+ Antes da execução, a spec é revisada pelo `revisor-spec`, um subagente que não recebe nada da
165
+ conversa. Ele procura premissa não declarada, requisito ambíguo, decisão que falta, módulo
166
+ que depende de outro sem contrato, nome fora da língua do código, teste sem ponto de costura,
167
+ conflito com o glossário ou com um ADR, e risco de implementação. Ele não dá veredito nem
168
+ reescreve a spec: quem resolve os achados e aprova é o dono (ou a própria sessão, no modo
169
+ autônomo).
170
+
171
+ ## Quem faz o quê
172
+
173
+ Três papéis:
174
+
175
+ - **Elefante:** o agente raiz da sessão. Carrega o contexto e desenha com o dono: entrevista
176
+ e spec. Entrega a execução ao orquestrador e não revisa o que orquestrou.
177
+ - **Goldfish:** todo subagente. Nasce sem a conversa, entrega o trabalho e não valida o
178
+ próprio resultado.
179
+ - **Dono:** você. Aprova a spec e faz o merge.
180
+
181
+ <img src="site/img/papeis.svg" alt="Os papéis: o dono e a sessão desenham; o orquestrador conduz a execução; implementadores escrevem; revisores de contexto novo dão os vereditos">
182
+
183
+ Os oito agentes do plugin:
184
+
185
+ | Agente | Modelo | O que faz | O que recebe | O que não pode |
186
+ |---|---|---|---|---|
187
+ | `orquestrador` | Sonnet | executa a spec aprovada: fatia, despacha, integra, checa, passa pelos revisores e envia | `spec`, `leitura` | escrever o código da feature, revisar o que orquestrou, juntar branch à mão, perguntar ao dono |
188
+ | `implementador` | Haiku (Sonnet no ticket de contrato) | implementa um ticket, com TDD, num worktree próprio | `spec`, `ticket`, `leitura`, `achado` | mexer fora do `Owns:`, subir ou parar ambiente, enviar, abrir pull request |
189
+ | `revisor-spec` | o da sua sessão | lê a spec como quem vai implementá-la sem poder perguntar | `spec`, `leitura` | editar arquivos, dar veredito, propor a solução |
190
+ | `revisor-bugs` | Sonnet | caça defeito: por ticket antes de integrar, e na branch inteira antes do push | `spec`, `ticket`, `diff`, `commit`, `leitura`, `achado` | editar, corrigir, trocar o commit do worktree |
191
+ | `revisor-ambiente` | Opus | só no ticket de contrato: confere que o que ele monta funciona numa cópia limpa | `spec`, `ticket`, `diff`, `commit`, `leitura`, `achado` | editar, corrigir, trocar o commit do worktree |
192
+ | `seguranca` | Sonnet | revisão de segurança da branch inteira | `diff`, `commit`, `spec`, `leitura` | editar, corrigir, reprovar por estilo ou risco hipotético |
193
+ | `revisor` | Sonnet | revisão de código: padrões do repositório, aderência à spec, arquitetura e clareza | `diff`, `commit`, `spec`, `leitura` | editar, corrigir |
194
+ | `qualidade` | Haiku | roda a checagem completa no commit e atesta o resultado | `commit` | revisar, opinar, consertar, rodar de novo "para ver se passa" |
195
+
196
+ Uma rodada de correção de um ticket sobe de modelo: vai em Sonnet e, depois de duas
197
+ reprovações, em Opus. Se o projeto tem um agente próprio em `.claude/agents/` cuja descrição
198
+ cobre a área do ticket, ele é usado no lugar do `implementador`.
199
+
200
+ O pedido a qualquer um desses agentes só aponta, uma chave por linha (`spec:`, `ticket:`,
201
+ `diff:`, `commit:`, `leitura:`, `achado:`). Narrativa e opinião são recusadas por um hook: o
202
+ documento é a única interface, e uma lacuna se corrige no documento, não por fora.
203
+
204
+ ```mermaid
205
+ sequenceDiagram
206
+ actor Dono
207
+ participant Sessao as Sessão (elefante)
208
+ participant RS as revisor-spec
209
+ participant Orq as orquestrador
210
+ participant Impl as implementadores
211
+ participant Rev as revisores
212
+ participant Remoto
213
+
214
+ Dono->>Sessao: /harness:entregar pedido
215
+ Sessao->>Dono: entrevista (grilling)
216
+ Sessao->>Sessao: spec em commit
217
+ Sessao->>RS: spec
218
+ RS-->>Sessao: achados
219
+ Sessao->>Dono: PARADA 1, aprovar a spec
220
+ Sessao->>Orq: spec aprovada
221
+ Orq->>Orq: fatia em tickets e valida o grafo
222
+ loop cada onda do grafo
223
+ Orq->>Impl: tickets da fronteira, em paralelo
224
+ Impl-->>Orq: branch de cada ticket
225
+ Orq->>Rev: revisor-bugs por ticket
226
+ Rev-->>Orq: veredito
227
+ Orq->>Orq: .harness/integrate, um ticket por vez
228
+ end
229
+ Orq->>Orq: .harness/validate --profile merge
230
+ Orq->>Rev: seguranca, revisor, revisor-bugs e qualidade
231
+ Rev-->>Orq: quatro vereditos sobre o mesmo commit
232
+ Orq->>Remoto: .harness/push e .harness/pr
233
+ Orq-->>Sessao: relato
234
+ Sessao-->>Dono: link do PR e endereço do aplicativo
235
+ Dono->>Remoto: merge
236
+ ```
237
+
238
+ ## Os portões
239
+
240
+ <img src="site/img/portoes.svg" alt="Os portões: revisão por ticket antes de integrar, checagem completa, e os quatro vereditos sobre o commit do topo antes do push">
241
+
242
+ ### Os quatro vereditos sobre o commit
243
+
244
+ Nada sai da máquina sem quatro aprovações sobre o commit do topo da branch:
245
+
246
+ | Veredito | Quem dá | O que atesta |
247
+ |---|---|---|
248
+ | segurança | `seguranca` | sem segredo, injeção, autorização ausente, dado sensível exposto, dependência duvidosa ou guardrail desligado no diff da branch |
249
+ | revisão de código | `revisor` | o código segue os padrões do repositório, a spec e a arquitetura |
250
+ | caça a bugs | `revisor-bugs` | o passe final sobre a branch inteira: o que só aparece olhando os módulos juntos |
251
+ | qualidade | `qualidade` | a checagem completa do projeto (testes, fronteiras, build, ponta a ponta) passou naquele commit |
252
+
253
+ Todo revisor termina a resposta com um bloco fixo:
254
+
255
+ ```text
256
+ VEREDITO: APPROVED (ou REJECTED)
257
+ COMMIT: <hash completo do commit revisado>
258
+ RESUMO: <uma linha>
259
+ ```
260
+
261
+ Um hook lê esse bloco e grava a aprovação, e só quando o commit revisado é o topo atual.
262
+ Nenhum agente carimba aprovação. Commit local é livre; entrou commit novo, a validação é
263
+ refeita. Além dos vereditos, uma branch com commit `feat` precisa trazer a spec da mudança em
264
+ `docs/specs/<slug>/spec.md`. O carimbo manual, `.harness/approve`, é do dono e exige terminal.
265
+
266
+ ### A revisão por ticket, antes de integrar
267
+
268
+ Cada ticket passa pela caça a bugs antes de ser juntado: um `revisor-bugs` por ticket, sobre a
269
+ ponta da branch do implementador. O diff de um ticket é pequeno, e é aí que a revisão funda
270
+ funciona: o defeito não chega aos tickets que dependem dele. O `.harness/integrate` recusa a
271
+ branch que não foi aprovada naquele commit exato.
272
+
273
+ O ticket de contrato tem duas leituras, juntas, porque é a base de todos os outros:
274
+
275
+ - o `revisor-bugs` procura defeito de comportamento e o que falta no contrato (cada porta que
276
+ um módulo consome, as respostas de erro comuns, as constantes de regra);
277
+ - o `revisor-ambiente` procura o que só funciona na pasta de quem escreveu: dependência fora
278
+ do commit, checagem que depende da ordem, valor fixo onde devia vir do ambiente, instalação
279
+ não reproduzível.
280
+
281
+ A integração exige as duas aprovações nesse commit.
282
+
283
+ ### Pendências
284
+
285
+ Achado simples não reprova. Um achado é severo quando quem usa recebe resultado errado, um
286
+ dado se perde ou fica inconsistente, uma proteção não protege, uma falha some, ou um teste
287
+ passa sem exercitar o que diz. O que sobra é simples: o revisor aprova com linhas
288
+ `PENDENCIA:`, o hook as registra, e o ticket segue.
289
+
290
+ - O teto é de duas pendências abertas por ticket. Passou disso, a aprovação não é gravada,
291
+ mesmo que o revisor tenha escrito `APPROVED`.
292
+ - As pendências são corrigidas no fechamento, cada uma com o teste que a pegaria.
293
+ - Só um revisor fecha uma pendência: o `revisor-bugs`, no passe final, responde
294
+ `RESOLVIDA: <id>` depois de conferir a correção no código.
295
+ - O push é recusado enquanto houver uma aberta. `.harness/pendings` lista.
296
+
297
+ ### Teto de rodadas
298
+
299
+ Quando a checagem ou um revisor reprova, o achado é gravado em
300
+ `docs/specs/<slug>/achados/`, o ticket é reaberto e despachado de novo, e o revisor que
301
+ reprovou confere a correção. As rodadas são contadas por ticket, e só reprovação conta. Cada
302
+ ticket tem limite de 3 rodadas de correção: na quarta, o orquestrador para e devolve o relato
303
+ do que travou. Os outros tickets continuam andando enquanto um está em correção.
304
+
305
+ ## O que é recusado por máquina
306
+
307
+ | Regra | Quem recusa |
308
+ |---|---|
309
+ | `git push`, `git fetch` e `gh` diretos | sandbox do Claude Code: a rede para o servidor de git é negada |
310
+ | Gravar em `.harness/`, `harness.conf`, `harness.d/`, `.claude/skills/`, `skills-lock.json`, `CLAUDE.md`, `docs/agents/` | sandbox (`filesystem.denyWrite`) e `permissions.deny` |
311
+ | Desligar o sandbox num comando | `allowUnsandboxedCommands: false` nas configurações geradas |
312
+ | Editar a região gerenciada do `AGENTS.md` | hook `managed_guard` |
313
+ | Pular hooks de git (`--no-verify`, `core.hooksPath`) | hook `service_guard` |
314
+ | Encadear ou embrulhar um script que sai do sandbox (`.harness/up && ...`) | hook `service_guard` |
315
+ | Implementador ou revisor subir, parar ou remover ambiente, rodar o aplicativo, enviar ou abrir pull request | hook `service_guard` |
316
+ | Revisor trocar o commit do worktree (`git checkout`, `switch`, `reset`, `restore`, `stash`, `clean`) | hook `service_guard` |
317
+ | Orquestrador juntar branch à mão (`git merge`, `rebase`, `cherry-pick`) | hook `service_guard` |
318
+ | Proposta de `harness.conf` fora do formato, ou que remove uma checagem já gravada | hook `service_guard`, ao rodar `.harness/conf-apply` |
319
+ | Pedido a um agente do harness com narrativa, chave que ele não recebe ou caminho que não existe | hook `dispatch_guard` |
320
+ | Pedido de revisão cujo `commit` não é o topo ou cujo `diff` não cobre a branch inteira | hook `dispatch_guard` |
321
+ | Implementador despachado por quem não é o orquestrador, ou sem worktree isolado | hook `dispatch_guard` |
322
+ | Orquestrador despachado com a spec fora de commit, ou sem `harness.conf` no projeto nem na spec | hook `dispatch_guard` |
323
+ | Aprovação sem veredito `APPROVED` de um revisor sobre o commit do topo, ou com mais de duas pendências no ticket | hook `gate_stamp`, que só então grava |
324
+ | Grafo de tickets com ciclo, referência inexistente, cabeçalho faltando, posse sobreposta entre paralelos ou ticket que não espera o contrato | `.harness/tickets_check.py` |
325
+ | Integrar branch sem a caça a bugs naquele commit (e, no ticket de contrato, sem a conferência de ambiente) | `.harness/integrate` |
326
+ | Integrar branch que mexeu fora do `Owns:` do ticket, ou que conflita | `.harness/integrate` |
327
+ | Integrar branch que quebra a checagem do projeto | `.harness/integrate`, que desfaz a junção |
328
+ | Marcar um ticket como `Status: done` num commit em que a checagem não passa | hook de git `pre-commit` |
329
+ | Assunto de commit fora de `tipo(escopo): descrição`, com mais de 80 caracteres, ou com co-autoria ou assinatura de IA | hook de git `commit-msg` |
330
+ | Módulo do back importando por dentro de outro módulo | `.harness/arch_check.py`, dentro do `.harness/validate` |
331
+ | Arquivo gerenciado alterado fora da atualização | `.harness/manifest_check.py`, dentro do `.harness/validate` |
332
+ | Push sem os quatro vereditos sobre o commit do topo | `.harness/gate-check`, chamado pelo `.harness/push` e pelo hook `pre-push` |
333
+ | Push de branch com commit `feat` e sem spec | `.harness/gate-check` |
334
+ | Push com pendência aberta | `.harness/gate-check` |
335
+ | Pull request com título fora do formato, sem o parágrafo de abertura, sem as seções "Critérios de aceite" e "Validação", com assinatura de IA, ou de branch que não passou pelo push | `.harness/pr` |
336
+ | Compose que dá a um contêiner acesso a algo fora da pasta do projeto | `.harness/compose_check.py`, dentro do `.harness/up` |
337
+ | Carimbo manual de aprovação por um agente | sandbox e exigência de terminal no `.harness/approve` |
338
+
339
+ Um erro interno de um guard vira negação, nunca liberação.
340
+
341
+ ## O que é instalado e o que é exigido
342
+
343
+ ### Pré-requisitos da máquina
344
+
345
+ | Item | Para quê |
346
+ |---|---|
347
+ | macOS ou Linux | os scripts são shell e Python |
348
+ | `git` | o projeto precisa ser um repositório git; o remoto, quando houver, por HTTPS |
349
+ | `python3` 3.9 ou mais novo | hooks, guards e validadores |
350
+ | Node.js 18 ou mais novo | o `npx` do instalador e da instalação das skills |
351
+ | Docker com Compose v2 | o ambiente por feature |
352
+ | Claude Code com sandbox disponível | a barreira de escrita e de rede |
353
+ | `gh` | abrir o pull request (`.harness/pr`) |
354
+ | `rtk` (recomendado) | comprime a saída de git e de testes; sem ele, o hook é ignorado |
355
+
356
+ ### Plugins de terceiros
357
+
358
+ O instalador registra os marketplaces e instala, no escopo do projeto, o plugin do harness e
359
+ estes:
360
+
361
+ | Plugin | Origem | Para que serve aqui |
362
+ |---|---|---|
363
+ | `mattpocock-skills` | marketplace oficial `claude-plugins-official` | `grilling` e `domain-modeling` na entrevista, `tdd` na implementação, `diagnosing-bugs` para bugs; traz também skills avulsas, como `code-review`, `prototype`, `research` e `codebase-design` |
364
+ | `ponytail` | `DietrichGebert/ponytail` | sempre ligado: segura o tamanho do código que o agente escreve; a `ponytail-review` dá ao revisor os critérios de duplicação e enxugamento |
365
+ | `frontend-design` | marketplace oficial `claude-plugins-official` | direção visual das telas, para o implementador de front |
366
+
367
+ Os três entram como estão, sem adaptação no conteúdo.
368
+
369
+ ### As 20 skills de stack
370
+
371
+ São skills públicas dos autores de cada tecnologia, copiadas para `.claude/skills/` e fixadas
372
+ no `skills-lock.json`. Cada papel usa só as suas; onde uma skill diverge das regras do
373
+ projeto, vale o que está em `docs/agents/stack.md`.
374
+
375
+ | Papel | Skill | Origem | Para quê |
376
+ |---|---|---|---|
377
+ | quem fatia | `parallel-feature-development` | `wshobson/agents` | fatiar para trabalho paralelo: um dono por arquivo, contrato primeiro |
378
+ | ticket de contrato | `pnpm` | `antfu/skills` | monorepo e dependências |
379
+ | ticket de contrato e páginas públicas | `seo` | `addyosmani/web-quality-skills` | SEO técnico |
380
+ | implementadores | `zod` | `anivar/zod-skill` | validação e contrato |
381
+ | todos | `vitest` | `antfu/skills` | testes de unidade e integração |
382
+ | módulo do back | `hexagonal-architecture` | `affaan-m/ecc` | use case, portas, adaptadores, ponto único de montagem |
383
+ | módulo do back | `nestjs-best-practices` | `kadajett/agent-nestjs-skills` | NestJS: módulos, injeção, erros, testes |
384
+ | módulo do back | `drizzle-orm-patterns` | `giuseppe-trisciuoglio/developer-kit` | acesso a banco |
385
+ | módulo do back | `supabase-postgres-best-practices` | `supabase/agent-skills` | esquema e consultas no Postgres |
386
+ | módulo do back | `bullmq` | `jgamaraalv/ts-dev-kit` | filas |
387
+ | módulo do back e caçador de bugs | `property-based-testing` | `trailofbits/skills` | teste por propriedade em regra com borda (data, dinheiro, intervalo) |
388
+ | fatia do front | `feature-sliced-design` | `feature-sliced/skills` | camadas, fatias, entrada pública |
389
+ | fatia do front | `nextjs-app-router-patterns` | `wshobson/agents` | Next.js: App Router, componentes de servidor e de cliente |
390
+ | fatia do front | `vercel-react-best-practices` | `vercel-labs/agent-skills` | React e desempenho no front |
391
+ | fatia do front | `shadcn` | `shadcn-ui/ui` | componentes de interface |
392
+ | ticket de ponta a ponta | `playwright-best-practices` | `currents-dev/playwright-best-practices-skill` | testes de ponta a ponta |
393
+ | revisor de código | `clean-code-guard` | `amelnagdy/guard-skills` | a rubrica do revisor: nomes, funções, SOLID, DRY |
394
+ | revisor de código | `accessibility` | `addyosmani/web-quality-skills` | acessibilidade |
395
+ | revisor de segurança | `owasp-security` | `agamm/claude-code-owasp` | lista do que procurar na revisão de segurança |
396
+ | quem fecha a entrega | `write-pr-description` | `warpdotdev/common-skills` | texto do pull request |
397
+
398
+ As 20 valem no perfil `fullstack-typescript`. O perfil `livre` recebe
399
+ `hexagonal-architecture`, `parallel-feature-development` e `clean-code-guard`; o perfil
400
+ `existente`, as duas últimas. Para outra tecnologia, `/harness:buscar-skills` procura, lê e
401
+ mostra candidatas, e só instala o que você aprovar.
402
+
403
+ ### Arquivos gravados no projeto
404
+
405
+ | Caminho | O que é | Quem muda |
406
+ |---|---|---|
407
+ | `.harness/` | os scripts, os hooks, os hooks de git e os roteiros da entrega | gerenciado: só `.harness/update` |
408
+ | `.claude/settings.json` | plugins, hooks, sandbox e permissões | gerenciado; o que é do projeto entra por `harness.d/settings.json` |
409
+ | `CLAUDE.md` | aponta para o `AGENTS.md` | gerenciado |
410
+ | `docs/agents/` | onde ficam o glossário, os ADRs e os tickets e, no perfil padrão, a stack (`stack.md`) | gerenciado |
411
+ | `orca.yaml` | integração com o Orca: prepara o worktree ao abrir | gerenciado |
412
+ | `AGENTS.md` | papéis, ciclo, arquitetura e portões, entre os marcadores `harness:begin` e `harness:end` | a região entre os marcadores é gerenciada; o que está abaixo dela é do projeto |
413
+ | `harness.conf` | a configuração do projeto | o dono, ou o agente por `.harness/conf-apply` |
414
+ | `harness.d/settings.json` | hooks, permissões, servidores MCP e sites liberados só do projeto, somados na geração | só o dono |
415
+ | `.claude/skills/` e `skills-lock.json` | as skills dos autores | só `.harness/skills-add`, com a sua confirmação |
416
+
417
+ Arquivo gerenciado não se edita no projeto: uma mudança de padrão se faz no repositório do
418
+ harness e chega por atualização. Ficam livres o código, o `CLAUDE.local.md` e a parte do
419
+ `AGENTS.md` abaixo da região gerenciada. Durante o trabalho, os arquivos temporários ficam em
420
+ `.harness-run/`, fora do versionamento.
54
421
 
55
422
  ## Instalar num projeto
56
423
 
@@ -98,9 +465,9 @@ No fim, relate em poucas linhas o que foi instalado e o comando para começar a
98
465
 
99
466
  Ele grava `.harness/`, `.claude/settings.json`, `AGENTS.md`, `CLAUDE.md`, `docs/agents/` e
100
467
  `orca.yaml`, registra os marketplaces, e instala no escopo do projeto o plugin do harness e os
101
- de terceiros (`mattpocock-skills`, `ponytail`). Se o `harness.conf` já estiver preenchido,
102
- também grava as portas no `.env` e instala as dependências. Pode ser rodado de novo. Arquivo
103
- gerenciado alterado à mão trava a instalação; `--force` substitui.
468
+ de terceiros (`mattpocock-skills`, `ponytail`, `frontend-design`). Se o `harness.conf` já
469
+ estiver preenchido, também grava as portas no `.env` e instala as dependências. Pode ser
470
+ rodado de novo. Arquivo gerenciado alterado à mão trava a instalação; `--force` substitui.
104
471
 
105
472
  ### Perfis
106
473
 
@@ -112,120 +479,201 @@ O instalador aceita `--profile`, e a escolha fica no `harness.conf`:
112
479
  | `livre` | projeto novo em outra stack | os conceitos de arquitetura; a stack é escolhida na spec |
113
480
  | `existente` | projeto que já tinha código | nada de arquitetura nem de língua: vale o que o projeto já usa |
114
481
 
115
- O núcleo vale nos três: sandbox, os três portões do push, tickets com posse de arquivo,
116
- contrato primeiro e paralelismo.
482
+ O núcleo vale nos três: sandbox, os portões do push, tickets com posse de arquivo, contrato
483
+ primeiro e paralelismo.
117
484
 
118
485
  O que é só do projeto (hooks, permissões, servidores MCP, sites liberados) vai em
119
486
  `harness.d/settings.json`, que é somado na geração.
120
487
 
121
- ## O que muda no dia a dia
488
+ ## Comandos
122
489
 
123
- **O shell do agente passa a rodar em sandbox.** Ele grava só dentro do projeto, não alcança
124
- o servidor de git e só acessa os sites liberados. Para você, no terminal, nada muda.
490
+ ### Os comandos do plugin
125
491
 
126
- **Os comandos do harness:**
492
+ | Comando | Para quê |
493
+ |---|---|
494
+ | `/harness:entregar <pedido>` | conduz uma mudança da entrevista ao pull request, dentro do worktree de uma feature |
495
+ | `/harness:setup` | configura o harness num projeto que já tinha código: propõe o `harness.conf` e a parte do projeto no `AGENTS.md` |
496
+ | `/harness:buscar-skills` | procura skills públicas para a stack do projeto, lê cada candidata, mostra o que achou e só instala o que você aprovar |
497
+ | `/harness:mapear` | gera ou atualiza o mapa do código e as âncoras do glossário e dos ADRs |
498
+ | `/harness:aprender` | depois do merge: atualiza o mapa, mede o consumo por papel, faz a retrospectiva e consolida as notas |
499
+ | `/harness:dream` | transforma o que as sessões ensinaram sobre o projeto em notas curtas, ancoradas no código |
127
500
 
128
- | Comando | Para quê | Quem roda |
501
+ ### Os scripts do projeto
502
+
503
+ | Script | Para quê | Quem roda |
129
504
  |---|---|---|
130
- | `.harness/up` | sobe a infra da feature | você ou o agente |
131
- | `.harness/prepare` | migration e seed | você ou o agente |
132
- | `.harness/dev` | o app | você ou o agente |
133
- | `.harness/down` | para o ambiente, mantém os dados | você ou o agente |
134
- | `.harness/destroy` | remove o ambiente da feature | você ou o agente, com a sua permissão |
135
- | `.harness/conf-apply` | grava o `harness.conf` que o agente propôs | o agente |
136
- | `.harness/integrate <ticket> <branch>` | junta o trabalho de um implementador: posse, merge, checagem | o agente |
137
- | `.harness/ticket claim\|reopen` | marca tickets como em andamento, ou reabre um, já com o commit | o agente |
138
- | `.harness/agents-clean` | remove os worktrees de agente já integrados | o agente |
505
+ | `.harness/up` | sobe a infra da feature | você ou o orquestrador |
506
+ | `.harness/prepare` | migration e seed (`AFTER_UP`) | você ou o orquestrador |
507
+ | `.harness/dev` | o aplicativo (`DEV_CMD`); `--background` deixa rodando | você ou o orquestrador |
508
+ | `.harness/down` | para o aplicativo e os contêineres, mantém os dados | você ou o orquestrador |
509
+ | `.harness/destroy` | remove o ambiente da feature e apaga os dados | você, ou o agente com a sua permissão |
510
+ | `.harness/ports-free` | encerra processo esquecido numa porta da feature | o orquestrador; roda sozinho quando um revisor termina |
511
+ | `.harness/setup-worktree` | prepara um worktree: `.env` e dependências | o Orca ao abrir o worktree, você, ou cada implementador |
512
+ | `.harness/worktree-env` | deriva o projeto Docker e as portas da feature e grava no `.env` | chamado pelos outros scripts |
513
+ | `.harness/conf-apply` | grava o `harness.conf` que o agente propôs, depois de conferido | o agente |
514
+ | `.harness/ticket claim\|reopen` | marca tickets como em andamento, ou reabre um, já com o commit | o orquestrador |
515
+ | `.harness/integrate <ticket> <branch>` | junta o trabalho de um implementador: revisão, posse, merge, checagem | o orquestrador |
516
+ | `.harness/agents-clean` | remove os worktrees de agente já integrados | o orquestrador |
517
+ | `.harness/pendings` | lista as pendências abertas da feature | você ou o agente |
518
+ | `.harness/validate --profile push\|merge` | checagens do projeto, sem custo de IA | você ou o agente |
139
519
  | `.harness/fetch` | atualiza as referências do remoto | o agente |
140
520
  | `.harness/push` | envia a branch, depois do portão | o agente |
141
- | `.harness/pr` | abre ou consulta o pull request | o agente |
142
- | `.harness/validate` | checagens do projeto, sem custo de IA | você ou o agente |
143
- | `.harness/memory` | mapa do código, âncoras e notas: `check`, `slice <caminho>`, `index`, `notes` | você ou o agente |
144
- | `.harness/learn` | sessões passadas: `sessions`, `usage`, `digest` | você ou o agente |
145
- | `.harness/approve` | sua aprovação manual de um portão | só você, no terminal |
521
+ | `.harness/pr create\|view` | abre ou consulta o pull request | o agente |
522
+ | `.harness/skills-search <termo>` | procura skills públicas | o agente |
523
+ | `.harness/skills-show <repositório> <skill>` | mostra o texto de uma skill candidata | o agente |
524
+ | `.harness/skills-add <repositório> <skill>` | instala uma skill e a fixa no `skills-lock.json` | o agente, com a sua confirmação |
525
+ | `.harness/memory` | o mapa do código, as âncoras e as notas: `check`, `slice <caminho>`, `index`, `units`, `record`, `anchor`, `note` | você ou o agente |
526
+ | `.harness/learn` | as sessões passadas: `sessions`, `usage`, `digest`, `mark` | você ou o agente |
527
+ | `.harness/approve <portão> "<resumo>"` | a sua aprovação manual de um portão | só você, no terminal |
146
528
  | `.harness/update <tag>` | leva o projeto para uma versão do harness | só você, no terminal |
147
529
 
148
- **O princípio é máximo de qualidade com máximo de autonomia e mínimo de interrupção.** Você é
149
- chamado para aprovar a spec (e nem isso no modo autônomo), para remover um ambiente, que apaga
150
- dados, e para fazer o merge. Todo o resto roda sem pergunta: os comandos dentro do sandbox e os
151
- scripts do harness. A qualidade não depende da sua atenção: vem dos portões, dos revisores e do
152
- sandbox. Se quiser alguma pergunta de volta, acrescente a regra em `permissions.ask` num
153
- fragmento do projeto (`harness.d/settings.json`); pergunta vence liberação.
154
-
155
- ## Uma primeira entrega
156
-
157
- 1. Abra um worktree para a feature, pelo Orca ou com `git worktree add`. O
158
- `.harness/setup-worktree` grava as portas dela no `.env` e instala as dependências.
159
- 2. Na sessão do Claude Code, dentro do worktree: `/harness:entregar`.
160
- 3. Responda a entrevista. Leia os achados do revisor da spec e aprove a spec.
161
- 4. Acompanhe: os tickets são criados, os implementadores trabalham em paralelo, a
162
- checagem roda, os dois revisores e o portão de qualidade dão o veredito, a branch é enviada e o pull request é aberto.
163
- 5. Faça o merge, preservando os commits.
164
-
165
- ## Seguir sem você
530
+ Os scripts que saem do sandbox (`up`, `down`, `destroy`, `conf-apply`, `push`, `fetch`, `pr`,
531
+ `ports-free` e os de skills) rodam sozinhos, um por chamada, na forma exata: sem `&&`, `;`,
532
+ `|` nem `bash` na frente. Para você, no terminal, nada muda.
166
533
 
167
- Se você disser "segue até o fim" durante uma entrega, ela corre em modo autônomo: toda
168
- pergunta recebe a resposta recomendada, a aprovação da spec deixa de ser uma parada, e cada
169
- decisão tomada sem você fica escrita na spec, na seção "Decisões tomadas sem o dono". Você
170
- só é chamado se a entrega não fechar em três rodadas de correção, se faltar um dado que só
171
- você tem, e para o merge.
534
+ ## Configuração
172
535
 
173
- ## O mapa do código
536
+ O `harness.conf` fica na raiz do projeto, no formato `CHAVE=valor`, uma por linha. Em projeto
537
+ novo ele é preenchido na primeira entrega, a partir da spec; em projeto que já tinha código,
538
+ `/harness:setup` propõe o conteúdo.
174
539
 
175
- `/harness:mapear` gera o mapa na primeira vez e depois refaz só o que mudou. O trabalho de
176
- ler o código é de subagentes no modelo mais barato. `.harness/memory check` mostra o que
177
- envelheceu, inclusive termos do glossário cujo código não existe mais e decisões de
178
- arquitetura cuja área mudou bastante.
179
-
180
- ## Depois do merge
181
-
182
- `/harness:aprender` fecha o ciclo: atualiza o mapa, mostra quanto cada papel gastou em tokens
183
- (`.harness/learn usage`), faz a retrospectiva da entrega e, com `/harness:dream`, transforma o
184
- que as sessões ensinaram sobre o projeto em notas ancoradas no código. As propostas de
185
- melhoria ficam em `.harness-run/propostas/`; o que for do harness você traz para este
186
- repositório.
187
-
188
- ## Atualizar
189
-
190
- Uma mudança de padrão se faz neste repositório e sai numa tag. No projeto:
540
+ | Chave | O que define | Exemplo |
541
+ |---|---|---|
542
+ | `PROFILE` | o perfil do projeto; mudar pede nova sincronização | `fullstack-typescript` |
543
+ | `PROJECT` | o nome usado no projeto Docker de cada worktree | `meuapp` |
544
+ | `SERVICES` | os serviços que precisam de porta; a ordem define o deslocamento dentro do bloco | `"web api postgres redis"` |
545
+ | `COMPOSE_FILE` | o compose do ambiente | `docker-compose.dev.yml` |
546
+ | `INSTALL_CMD` | a instalação de dependências, rodada ao criar um worktree | `"pnpm install --frozen-lockfile"` |
547
+ | `AFTER_UP` | o que roda depois de a infra ficar saudável: migration, seed | `"pnpm db:migrate"` |
548
+ | `DEV_CMD` | o processo do aplicativo | `"pnpm dev"` |
549
+ | `VALIDATE_PUSH` | a checagem ao fechar e ao integrar cada ticket, e no push feito à mão | `"pnpm test"` |
550
+ | `VALIDATE_MERGE` | a checagem completa, antes de abrir o pull request; é onde entram os testes de ponta a ponta | `"pnpm test && pnpm build"` |
551
+ | `CONTRACT_PATHS` | os caminhos do que é comum (o contrato, a camada `shared` do front): só o ticket de contrato os possui | `"packages/contracts apps/web/src/shared"` |
552
+ | `MODULE_ROOTS` | onde ficam os módulos do back; o harness recusa a importação por dentro de outro módulo | `"apps/api/src/modules"` |
553
+ | `VALIDATE_ARCH` | o comando que confere as demais fronteiras, com a ferramenta da linguagem | `"pnpm exec depcruise apps/api/src && pnpm exec steiger apps/web/src"` |
554
+ | `DEFAULT_BRANCH` | a branch padrão, quando não for `main` nem `master` e o remoto não a anunciar | `trunk` |
555
+ | `MAX_PARALLEL` | o máximo de implementadores em paralelo (3, se não houver) | `3` |
556
+ | `MAP_DEPTH` | a profundidade das unidades do mapa do código | `2` |
557
+ | `MAP_EXCLUDE` | as pastas que ficam fora do mapa | `"docs .harness .claude .github"` |
558
+ | `ADR_REVIEW_COMMITS` | quantos commits na área de um ADR pedem que ele seja relido | `20` |
559
+ | `CONDUCTOR` | gera também a integração com o Conductor (`.conductor/settings.toml`) | `1` |
560
+ | `ENV_<NOME>` | variável derivada das portas, gravada no `.env` do worktree | `ENV_DATABASE_URL='postgresql://app:app@localhost:${POSTGRES_PORT}/app'` |
561
+
562
+ Os perfis estão em [Instalar num projeto](#perfis).
563
+
564
+ ## Arquitetura que o harness espera
565
+
566
+ No perfil `fullstack-typescript`, a arquitetura vem junto e está na seção Arquitetura do
567
+ `AGENTS.md`. As skills dos autores ensinam o como; onde elas divergem, vale o `AGENTS.md`.
568
+
569
+ | Parte | Stack padrão |
570
+ |---|---|
571
+ | back | NestJS, Drizzle, Postgres; filas com BullMQ sobre Redis |
572
+ | front | Next.js (App Router), shadcn, Tailwind |
573
+ | contrato e validação | Zod, num pacote comum importado pelos dois lados |
574
+ | testes | Vitest (unidade e integração) e Playwright (ponta a ponta) |
575
+ | monorepo | pnpm |
576
+
577
+ - **Módulos com contrato.** O back se divide em módulos por área de negócio. Um módulo nunca
578
+ importa outro por dentro: o que um oferece ao outro é uma porta definida no que é comum,
579
+ pelo ticket de contrato. O que front e back trocam fica num pacote comum, importado pelos dois.
580
+ - **Portas e adaptadores no back.** Dentro de cada módulo: domínio, use cases, portas e
581
+ adaptadores, com as dependências apontando para dentro. Um use case por comportamento,
582
+ recebendo as portas por injeção, sem importar framework. Porta só para o que sai do
583
+ processo (banco, fila, serviço externo); log, relógio e utilitário não viram porta.
584
+ - **Feature-Sliced Design no front.** O código nasce na página, cada fatia tem entrada
585
+ pública, e só se importa de camada abaixo.
586
+ - **Código em inglês.** Identificadores, arquivos, pastas, rotas e mensagens de commit. Em
587
+ português ficam o texto que o usuário vê, a spec, os tickets e o glossário, que traz o nome
588
+ em inglês de cada termo de domínio.
589
+
590
+ Uma spec pode escolher outra peça da stack, dizendo o motivo. No perfil `livre` valem os
591
+ conceitos (módulos, portas, contrato num lugar só) em qualquer linguagem; no perfil
592
+ `existente` vale a organização que o repositório já tem.
593
+
594
+ ## Ambiente por feature
595
+
596
+ Uma feature é um worktree, e cada worktree tem o próprio ambiente: um projeto Docker e um
597
+ bloco de portas derivados do nome da pasta, gravados no `.env`. Ninguém escolhe porta à mão.
598
+ Os worktrees de agente, onde os implementadores trabalham, usam o ambiente da feature de onde
599
+ saíram. O ambiente só sobe quando a validação exige; `docker` solto não funciona dentro do
600
+ sandbox, e o caminho é `.harness/up`, que confere o compose antes de subir.
601
+
602
+ ## Memória do projeto
603
+
604
+ - **O mapa do código.** `/harness:mapear` gera um resumo curto de cada parte do repositório,
605
+ escrito por subagentes em Haiku e guardado fora dos arquivos versionados. Cada resumo fica
606
+ ancorado no commit em que foi escrito: `.harness/memory check` diz, sem custo de IA, o que
607
+ envelheceu, e só isso é refeito. Toda sessão começa com o índice do mapa.
608
+ - **Glossário e ADRs ancorados.** O `check` também aponta termos do glossário cujo código não
609
+ existe mais e ADRs cuja área mudou bastante. A decisão sobre eles é do dono.
610
+ - **Depois do merge.** `/harness:aprender` atualiza o mapa, mostra os tokens de cada papel
611
+ (`.harness/learn usage`), faz a retrospectiva da entrega e, com `/harness:dream`, grava
612
+ notas ancoradas no código. Uma nota só entra se o código de hoje a confirma. As propostas
613
+ de melhoria ficam em `.harness-run/propostas/`.
614
+
615
+ ## Projeto sem remoto
616
+
617
+ O harness não exige remoto para começar. Sem ele, a entrega roda até o fim: os tickets são
618
+ integrados, a checagem passa, os quatro vereditos são dados, e `.harness/push` confere os
619
+ portões do mesmo jeito e termina dizendo que a branch está aprovada e que nada foi enviado.
620
+ Não há pull request; o aplicativo fica de pé e o relato diz o que falta para publicar. Quando
621
+ o remoto existir, o primeiro envio da branch padrão é seu, no terminal.
622
+
623
+ ## Atualizar o harness
624
+
625
+ Uma mudança de padrão se faz no repositório do harness e sai numa tag. No projeto, no seu
626
+ terminal:
191
627
 
192
628
  ```bash
193
- .harness/update v0.2.0
629
+ .harness/update <tag>
194
630
  ```
195
631
 
196
- Arquivo gerenciado que foi alterado à mão trava a atualização, que lista o que encontrou.
632
+ O comando baixa a tag e executa o sincronizador daquela versão, para que o plugin, a pasta
633
+ `.harness/` e os arquivos gerados saiam todos com a mesma versão. Arquivo gerenciado que foi
634
+ alterado à mão trava a atualização, que lista o que encontrou; `--force` substitui. O agente
635
+ não roda a atualização: dentro do sandbox ele não grava em `.harness/`.
636
+
637
+ ## O que já foi provado e o que ainda não
197
638
 
198
- ## O que ainda não foi verificado
639
+ **O que tem prova:**
199
640
 
200
- Tudo abaixo passou em testes automáticos ou em sessões sem interface, mas não numa sessão
201
- interativa com um projeto de verdade. É a lista para a primeira validação:
641
+ - As peças têm testes automáticos: os guards, o carimbo a partir do veredito, o portão de
642
+ push, o validador do grafo de tickets, a integração com posse, as pendências, as fronteiras
643
+ entre módulos, o instalador, a atualização e os scripts de ambiente. A suíte roda no CI.
644
+ - Os testes também conferem a coerência entre o que os roteiros mandam fazer e o que os
645
+ guards aceitam.
646
+ - O ciclo completo foi exercitado em entregas que partem de um projeto do zero, com um pedido
647
+ curto, no perfil `fullstack-typescript`.
202
648
 
203
- - `.harness/conf-apply`, `up` e `down` rodando sem pergunta, e a pergunta do `destroy` aparecendo.
204
- - `.harness/push` enviando para o GitHub com as suas credenciais, e `.harness/pr` com o `gh`.
205
- - `/harness:setup` e `/harness:entregar` de ponta a ponta. A orquestração é conduzida por
206
- um modelo e não tem teste automático: os testes cobrem as peças e a coerência entre o que
207
- a skill manda fazer e o que os guards aceitam.
208
- - O carimbo automático a partir do veredito dos revisores, com os dois revisores. Só o
209
- de segurança rodou de ponta a ponta numa sessão real.
210
- - Instalar dependências (`pnpm install`) dentro do sandbox, num projeto com muitas.
211
- - A trava contra desligar o sandbox, numa sessão interativa.
212
- - `/harness:aprender` e `/harness:dream` sobre uma entrega de verdade: se a leitura das
213
- transcrições reconhece o formato das suas sessões, se os números de consumo batem, e se as
214
- notas que saem valem a pena.
215
- - `/harness:mapear` num projeto de verdade: a qualidade dos resumos, o custo da primeira
216
- geração, e o hook que injeta o índice no começo da sessão.
217
- - Um push por SSH: a rede é negada por nome de servidor, e não foi conferido se isso cobre SSH.
649
+ **O que ainda não foi provado:**
218
650
 
219
- Limites conhecidos, que não são falha de teste:
651
+ - **Uma segunda entrega sobre código que já existe.** As entregas exercitadas partiram de um
652
+ projeto vazio. Evoluir um sistema já entregue, com o mapa, o glossário e a suíte de ponta a
653
+ ponta protegendo o que funciona, ainda não foi posto à prova.
654
+ - **Os perfis fora do `fullstack-typescript`.** `livre` e `existente` têm testes das peças,
655
+ mas não uma entrega de ponta a ponta.
656
+ - **Achar defeito continua dependendo de um revisor que é um modelo.** Os trilhos garantem
657
+ que a revisão acontece, sobre o commit certo, por quem não escreveu o código. Não garantem
658
+ que o revisor enxergue todo defeito.
659
+ - **A orquestração em si não tem teste automático.** Ela é conduzida por um modelo: os testes
660
+ cobrem as peças, não a condução.
661
+
662
+ **Limites conhecidos:**
220
663
 
221
664
  - Sem o sandbox ligado, os portões protegem contra descuido, não contra um agente que insiste.
222
- - Um servidor de desenvolvimento que vigia arquivos pode não subir dentro do sandbox (visto com
223
- o `next dev`). A validação é feita então sobre o build de produção.
665
+ - Um servidor de desenvolvimento que vigia arquivos pode não subir dentro do sandbox (visto
666
+ com o `next dev`). Os testes de ponta a ponta rodam sobre o build de produção.
667
+ - O navegador dos testes de ponta a ponta não abre dentro do sandbox: ele roda num contêiner
668
+ do ambiente.
224
669
  - No Linux o sandbox não alcança `localhost`; `prepare` e `dev` precisariam de outra saída.
225
- - Subagentes em paralelo na mesma feature compartilham o banco.
670
+ - Os implementadores de uma mesma feature dividem o ambiente dela; a spec precisa dizer como
671
+ cada um isola o seu banco de teste.
672
+ - O sandbox só alcança o registro do npm. Dependência de outro lugar pede um domínio liberado
673
+ em `harness.d/settings.json`, e liberar é do dono.
674
+ - O carimbo automático lê o veredito da transcrição do subagente. Se ele não acontecer, a
675
+ falha é fechada: o push fica negado, e o dono usa `.harness/approve`.
226
676
  - Não há suporte ao Codex ainda.
227
- - Seis revisões adversariais acharam falhas reais, todas corrigidas. Isso mostra que
228
- revisar funciona, e não que não reste nenhuma.
229
677
 
230
678
  ## Desenvolver o harness
231
679
 
@@ -236,4 +684,6 @@ python3 -m unittest discover -s tests
236
684
  Os testes gravam em `~/.claude/harness/` e apagam ao sair, então não rodam de dentro de
237
685
  uma sessão com o sandbox ligado. Alguns usam Docker de verdade e são pulados sem ele.
238
686
 
239
- Licença MIT.
687
+ ## Licença
688
+
689
+ MIT.
package/install CHANGED
@@ -37,45 +37,71 @@ python3 -I "$HARNESS/plugin/bin/sync" "$ROOT" --version "$VERSION" $FORCE ${PROF
37
37
  PROFILE="$(sed -n 's/^PROFILE=//p' "$ROOT/harness.conf" | tr -d "\"'" | sed -n 1p)"
38
38
  PROFILE="${PROFILE:-fullstack-typescript}"
39
39
 
40
+ # Mostra em que ponto está: registrar plugins e baixar skills leva mais de um minuto, e em
41
+ # silêncio parece travado. Num terminal a linha é reescrita; fora dele sai uma linha por passo.
42
+ if [ -t 1 ]; then
43
+ progress() { printf '\r\033[K%s' "$1"; }
44
+ settle() { printf '\r\033[K%s\n' "$1"; }
45
+ else
46
+ progress() { echo "$1"; }
47
+ settle() { :; }
48
+ fi
49
+ echo "[1/3] Arquivos do harness gravados"
50
+
40
51
  if [ -z "${HARNESS_SKIP_PLUGIN:-}" ] && command -v claude >/dev/null 2>&1; then
41
- warn() { echo "install: não consegui $1; rode à mão: $2" >&2; }
52
+ warn() { [ -t 1 ] && printf '\r\033[K'; echo "install: não consegui $1; rode à mão: $2" >&2; }
42
53
  # Num clone do repositório, o marketplace é esta pasta (desenvolvimento do próprio harness).
43
54
  # Instalado pelo npm, a pasta é o cache do npx e some: vale o repositório publicado.
44
55
  if [ -d "$HARNESS/.git" ] || [ -f "$HARNESS/.git" ]; then MARKET="$HARNESS"; else MARKET="FullChico/fullchico-harness"; fi
45
56
  MARKET="${HARNESS_MARKETPLACE:-$MARKET}"
57
+ progress "[2/3] Plugins: registrando os marketplaces"
46
58
  claude plugin marketplace add "$MARKET" >/dev/null 2>&1 || warn "registrar o marketplace do harness" "claude plugin marketplace add $MARKET"
47
- python3 -I - "$ROOT/.claude/settings.json" <<'PY' | while IFS= read -r REPO; do
59
+ REPOS="$(python3 -I - "$ROOT/.claude/settings.json" <<'PY'
48
60
  import json, sys
49
61
  for name, entry in json.load(open(sys.argv[1])).get("extraKnownMarketplaces", {}).items():
50
62
  source = entry.get("source", {})
51
63
  if name != "fullchico" and source.get("source") == "github" and source.get("repo"):
52
64
  print(source["repo"])
53
65
  PY
66
+ )"
67
+ for REPO in $REPOS; do
54
68
  claude plugin marketplace add "$REPO" >/dev/null 2>&1 || warn "registrar o marketplace $REPO" "claude plugin marketplace add $REPO"
55
69
  done
56
70
  # Instalar é por projeto: o comando roda de dentro dele.
57
- python3 -I - "$ROOT/.claude/settings.json" <<'PY' | while IFS= read -r PLUGIN; do
71
+ PLUGINS="$(python3 -I - "$ROOT/.claude/settings.json" <<'PY'
58
72
  import json, sys
59
73
  for name, enabled in json.load(open(sys.argv[1])).get("enabledPlugins", {}).items():
60
74
  if enabled:
61
75
  print(name)
62
76
  PY
77
+ )"
78
+ TOTAL="$(printf '%s\n' $PLUGINS | grep -c .)" N=0
79
+ for PLUGIN in $PLUGINS; do
80
+ N=$((N + 1))
81
+ progress "[2/3] Plugins ($N/$TOTAL): $PLUGIN"
63
82
  (cd "$ROOT" && claude plugin install "$PLUGIN" --scope project >/dev/null 2>&1) || warn "instalar $PLUGIN" "claude plugin install $PLUGIN --scope project"
64
83
  done
84
+ settle "[2/3] Plugins instalados ($TOTAL)"
65
85
  else
66
86
  echo "install: sem o comando claude; os plugins ficam para depois." >&2
67
87
  fi
68
88
 
69
89
  # Skills de arquitetura, dos autores, copiadas para o projeto e fixadas no skills-lock.json.
70
90
  if [ -z "${HARNESS_SKIP_PLUGIN:-}" ] && command -v npx >/dev/null 2>&1; then
71
- python3 -I -c 'import json,sys
91
+ SKILLS="$(python3 -I -c 'import json,sys
72
92
  for s in json.load(open(sys.argv[1])).get("project_skills", []):
73
93
  if sys.argv[2] in s.get("profiles", []):
74
- print(s["repo"], s["skill"])' "$HARNESS/plugin/map.json" "$PROFILE" | while read -r REPO SKILL; do
94
+ print(s["repo"] + "|" + s["skill"])' "$HARNESS/plugin/map.json" "$PROFILE")"
95
+ TOTAL="$(printf '%s\n' $SKILLS | grep -c .)" N=0
96
+ for PAIR in $SKILLS; do
97
+ REPO="${PAIR%%|*}" SKILL="${PAIR##*|}"
98
+ N=$((N + 1))
99
+ progress "[3/3] Skills ($N/$TOTAL): $SKILL"
75
100
  [ -d "$ROOT/.claude/skills/$SKILL" ] && continue
76
101
  (cd "$ROOT" && npx -y skills add "$REPO" -s "$SKILL" -a claude-code -y --copy </dev/null >/dev/null 2>&1) \
77
- || echo "install: não instalei a skill $SKILL; rode à mão: npx skills add $REPO -s $SKILL -a claude-code -y --copy" >&2
102
+ || { [ -t 1 ] && printf '\r\033[K'; echo "install: não instalei a skill $SKILL; rode à mão: npx skills add $REPO -s $SKILL -a claude-code -y --copy" >&2; }
78
103
  done
104
+ [ "$TOTAL" -eq 0 ] || settle "[3/3] Skills instaladas ($TOTAL)"
79
105
  fi
80
106
 
81
107
  # Com o harness.conf já preenchido, deixa o worktree pronto: portas no .env e dependências.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fullchico/harness",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "Trilhos e portões para projetos desenvolvidos com agentes no Claude Code: orquestração por ticket, revisão independente presa ao commit, ambiente por feature.",
5
5
  "license": "MIT",
6
6
  "author": "FullChico",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "harness",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "Orquestração, guardrails e memória para projetos desenvolvidos com agentes.",
5
5
  "license": "MIT",
6
6
  "author": {