@fullchico/harness 0.1.3 → 0.1.5

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
@@ -1,111 +1,473 @@
1
- # FullChico Harness
2
-
3
- Página do projeto: https://fullchico.github.io/fullchico-harness/
4
-
5
- Ambiente de desenvolvimento com agentes, para o Claude Code. Um plugin que padroniza, em
6
- todo projeto que o adota, o fluxo de uma mudança, os guardrails e o ambiente de
7
- desenvolvimento por feature.
8
-
9
-
10
- ## O que ele faz
11
-
12
- - **Conduz uma mudança da entrevista ao pull request,** com `/harness:entregar`: entrevista,
13
- spec, revisão da spec, tickets em grafo, implementação em paralelo por subagentes,
14
- checagem, revisão de segurança e de código, envio.
15
- - **Traz a arquitetura junto.** Back em módulos com use cases, portas e adaptadores; front em
16
- Feature-Sliced Design; contrato entre os dois num pacote comum. O ofício vem de skills dos
17
- autores, copiadas para o projeto e fixadas no `skills-lock.json`; as convenções que resolvem
18
- os atritos entre elas estão no `AGENTS.md`.
19
- - **Paraleliza por contrato.** Cada ticket é dono de pastas (`Owns:`). Dois tickets paralelos
20
- nunca possuem o mesmo caminho, o contrato fecha antes dos demais começarem, e a integração
21
- recusa a branch que mexer fora da posse ou quebrar a checagem.
22
- - **Gasta o modelo caro só onde ele paga.** A sua sessão (Opus) faz a entrevista e a spec. A
23
- execução inteira é de um orquestrador em Sonnet, que recebe só a spec; os implementadores e
24
- os revisores também são Sonnet, e os implementadores e o trabalho bruto são Haiku.
25
- - **Não deixa código sem revisão chegar ao remoto.** O shell do agente roda no sandbox do
26
- Claude Code, sem rede para o servidor de git. O único caminho é `.harness/push`, que
27
- exige quatro aprovações sobre o commit (segurança, revisão de código, caça a bugs e
28
- qualidade: a checagem completa do projeto passou nele) e, para uma `feat`, a spec da mudança.
29
- - **Nenhum agente aprova o próprio trabalho.** A aprovação nasce do veredito de um revisor
30
- de contexto novo, gravada por um hook, num lugar onde o agente não escreve.
31
- - **Dá a cada feature o próprio ambiente Docker,** com portas e projeto isolados, levantado
32
- sem pedir nada a você.
33
- - **Mantém um mapa do código que não envelhece calado.** Cada resumo guarda o commit em que
34
- foi escrito, e o git diz, sem custo, o que mudou desde então. Toda sessão começa com o índice.
35
- - **Liga o `ponytail` e o `rtk` em todo projeto.** O `ponytail` segura o tamanho do código que
36
- o agente escreve; o `rtk` comprime a saída de git e de testes. Os dois entram como estão, sem
37
- adaptação.
38
- - **Mantém a configuração igual entre projetos.** O que o harness instala não é editado no
39
- projeto: muda aqui e chega por atualização.
40
-
41
- ## Pré-requisitos
42
-
43
- macOS ou Linux, `git`, `python3` 3.9 ou mais novo, Docker com Compose v2, e o Claude Code
44
- com sandbox disponível. O remoto do projeto precisa ser HTTPS. Recomendado: `rtk`.
1
+ <img src="site/trem.svg" alt="" width="72" align="right">
45
2
 
46
- ## Instalar num projeto
3
+ # FullChico Harness
47
4
 
48
- Antes: o projeto precisa ser um repositório git. O remoto, que tem de ser HTTPS, pode vir
49
- depois: sem ele a entrega roda até o fim e termina aprovada e pronta, e só o envio e o pull
50
- request ficam esperando.
5
+ [![npm](https://img.shields.io/npm/v/@fullchico/harness?label=npm&color=1d1b16)](https://www.npmjs.com/package/@fullchico/harness)
6
+ [![ci](https://github.com/fullchico/fullchico-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/fullchico/fullchico-harness/actions/workflows/ci.yml)
51
7
 
52
- Um comando, **no seu terminal, fora de uma sessão do Claude Code**, na pasta do projeto:
8
+ [Página do projeto](https://fullchico.github.io/fullchico-harness/) · [Pacote no npm](https://www.npmjs.com/package/@fullchico/harness)
53
9
 
54
10
  ```bash
55
11
  npx @fullchico/harness install .
56
12
  ```
57
13
 
58
- De dentro de uma sessão o sandbox bloqueia o GitHub: os arquivos são gravados, mas o registro
59
- do marketplace falha. Se foi o seu caso, complete no terminal, **na pasta do projeto** (o
60
- segundo comando liga o plugin na pasta em que é rodado):
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.
421
+
422
+ ## Instalar num projeto
423
+
424
+ Um comando, no seu terminal, na pasta do projeto (um repositório git):
61
425
 
62
426
  ```bash
63
- cd /caminho/do/projeto
64
- claude plugin marketplace add FullChico/fullchico-harness
65
- claude plugin install harness@fullchico --scope project
427
+ npx @fullchico/harness install .
66
428
  ```
67
429
 
68
- Se o primeiro responder que a origem não bate com uma entrada já registrada, há um marketplace
69
- `fullchico` antigo nas suas configurações: `claude plugin marketplace remove fullchico` e repita.
430
+ É só isso. Ele grava os arquivos do harness, registra o marketplace, instala o plugin e as
431
+ skills. Depois abra o Claude Code na pasta e faça o pedido:
70
432
 
71
- Depois de instalar, abra o Claude Code na pasta uma vez, em modo interativo, e aceite o
72
- diálogo de confiança: sem isso ele ignora as permissões do projeto.
433
+ ```text
434
+ /harness:entregar quero um sistema de agendamento para uma barbearia
435
+ ```
436
+
437
+ Na primeira vez o Claude Code pergunta se você confia na pasta: aceite. O remoto pode vir
438
+ depois: sem ele a entrega roda até o fim, e só o envio e o pull request ficam esperando.
73
439
 
74
440
  ### Deixar o Claude instalar
75
441
 
76
- Cole este pedido numa sessão do Claude Code aberta na pasta do projeto:
442
+ Se preferir, cole este pedido numa sessão do Claude Code aberta na pasta do projeto:
77
443
 
78
444
  ```text
79
- Instale o FullChico Harness neste projeto e deixe-o pronto para a primeira entrega. Siga esta ordem e pare se algo falhar, mostrando o erro exato.
445
+ Instale o FullChico Harness neste projeto e deixe-o pronto para a primeira entrega. Pare se algo falhar, mostrando o erro exato.
80
446
 
81
447
  1. Confira os pré-requisitos: esta pasta é um repositório git (se não for, pergunte antes de criar um), e existem `python3`, `node`, `docker compose` e `claude`. Diga o que falta.
82
- 2. Rode `npx @fullchico/harness install .`. O perfil padrão é o fullstack TypeScript; se eu quiser outro, eu digo.
83
- 3. Se o instalador avisar que o marketplace ou o plugin não foram registrados (acontece dentro de uma sessão, por causa do sandbox), não tente contornar. Passe-me os comandos para eu rodar no meu terminal, na pasta do projeto, e espere eu confirmar:
84
- claude plugin marketplace add FullChico/fullchico-harness
85
- claude plugin install harness@fullchico --scope project
86
- 4. Confira o que foi gravado: `.harness/`, `.claude/settings.json`, `.claude/skills/`, `AGENTS.md`, `CLAUDE.md` e `harness.conf`. Não edite arquivo gerenciado pelo harness.
87
- 5. Peça-me para reiniciar o Claude Code nesta pasta, para o plugin e os hooks carregarem, e para aceitar o diálogo de confiança. Depois de reiniciar, rode `/harness:setup`.
88
- 6. Faça o commit do que foi gerado, numa branch, e explique o primeiro envio: com remoto, ele é meu, no terminal; sem remoto, o projeto segue local.
89
-
90
- No fim, relate em poucas linhas o que foi instalado, o que eu preciso fazer à mão e o comando para começar a primeira entrega.
448
+ 2. Rode `npx @fullchico/harness install .` fora do sandbox do Bash, pedindo a minha permissão: o instalador precisa alcançar o GitHub para registrar o plugin, e dentro do sandbox isso é bloqueado. Um comando só faz tudo: grava os arquivos, registra o marketplace e instala o plugin e as skills.
449
+ 3. Confira o que foi gravado: `.harness/`, `.claude/settings.json`, `.claude/skills/`, `AGENTS.md`, `CLAUDE.md` e `harness.conf`. Não edite arquivo gerenciado pelo harness.
450
+ 4. Faça o commit do que foi gerado, numa branch.
451
+ 5. Peça-me para reiniciar o Claude Code nesta pasta, para o plugin e os hooks carregarem.
452
+
453
+ No fim, relate em poucas linhas o que foi instalado e o comando para começar a primeira entrega: `/harness:entregar <o que eu quero construir>`, num worktree de feature.
91
454
  ```
92
455
 
93
- Com o repositório clonado, `/caminho/do/fullchico-harness/install /caminho/do/projeto` faz o mesmo.
456
+ ### Se algo não funcionar
457
+
458
+ - **Rodei o comando de dentro de uma sessão do Claude Code e o plugin não apareceu.** O
459
+ sandbox da sessão bloqueia o GitHub. Rode de novo no seu terminal, fora da sessão; o comando
460
+ pode ser repetido sem dano.
461
+ - **"A origem não bate com uma entrada já registrada".** Há um marketplace `fullchico` antigo
462
+ nas suas configurações: `claude plugin marketplace remove fullchico` e rode o instalador de novo.
463
+ - **Projeto que já tinha código.** Depois de instalar, rode `/harness:setup` numa sessão: ele
464
+ propõe o `harness.conf` a partir do que encontra.
94
465
 
95
466
  Ele grava `.harness/`, `.claude/settings.json`, `AGENTS.md`, `CLAUDE.md`, `docs/agents/` e
96
467
  `orca.yaml`, registra os marketplaces, e instala no escopo do projeto o plugin do harness e os
97
- de terceiros (`mattpocock-skills`, `ponytail`). Se o `harness.conf` já estiver preenchido,
98
- também grava as portas no `.env` e instala as dependências. Pode ser rodado de novo. Arquivo
99
- gerenciado alterado à mão trava a instalação; `--force` substitui.
100
-
101
- Num projeto novo falta um passo, numa sessão do Claude Code aberta nele:
102
-
103
- ```
104
- /harness:setup
105
- ```
106
-
107
- Ele propõe o `harness.conf` a partir do que encontra no projeto. Faça o commit do que foi
108
- gerado e reinicie a sessão.
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.
109
471
 
110
472
  ### Perfis
111
473
 
@@ -117,120 +479,201 @@ O instalador aceita `--profile`, e a escolha fica no `harness.conf`:
117
479
  | `livre` | projeto novo em outra stack | os conceitos de arquitetura; a stack é escolhida na spec |
118
480
  | `existente` | projeto que já tinha código | nada de arquitetura nem de língua: vale o que o projeto já usa |
119
481
 
120
- O núcleo vale nos três: sandbox, os três portões do push, tickets com posse de arquivo,
121
- 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.
122
484
 
123
485
  O que é só do projeto (hooks, permissões, servidores MCP, sites liberados) vai em
124
486
  `harness.d/settings.json`, que é somado na geração.
125
487
 
126
- ## O que muda no dia a dia
488
+ ## Comandos
127
489
 
128
- **O shell do agente passa a rodar em sandbox.** Ele grava só dentro do projeto, não alcança
129
- o servidor de git e só acessa os sites liberados. Para você, no terminal, nada muda.
490
+ ### Os comandos do plugin
130
491
 
131
- **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 |
132
500
 
133
- | Comando | Para quê | Quem roda |
501
+ ### Os scripts do projeto
502
+
503
+ | Script | Para quê | Quem roda |
134
504
  |---|---|---|
135
- | `.harness/up` | sobe a infra da feature | você ou o agente |
136
- | `.harness/prepare` | migration e seed | você ou o agente |
137
- | `.harness/dev` | o app | você ou o agente |
138
- | `.harness/down` | para o ambiente, mantém os dados | você ou o agente |
139
- | `.harness/destroy` | remove o ambiente da feature | você ou o agente, com a sua permissão |
140
- | `.harness/conf-apply` | grava o `harness.conf` que o agente propôs | o agente |
141
- | `.harness/integrate <ticket> <branch>` | junta o trabalho de um implementador: posse, merge, checagem | o agente |
142
- | `.harness/ticket claim\|reopen` | marca tickets como em andamento, ou reabre um, já com o commit | o agente |
143
- | `.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 |
144
519
  | `.harness/fetch` | atualiza as referências do remoto | o agente |
145
520
  | `.harness/push` | envia a branch, depois do portão | o agente |
146
- | `.harness/pr` | abre ou consulta o pull request | o agente |
147
- | `.harness/validate` | checagens do projeto, sem custo de IA | você ou o agente |
148
- | `.harness/memory` | mapa do código, âncoras e notas: `check`, `slice <caminho>`, `index`, `notes` | você ou o agente |
149
- | `.harness/learn` | sessões passadas: `sessions`, `usage`, `digest` | você ou o agente |
150
- | `.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 |
151
528
  | `.harness/update <tag>` | leva o projeto para uma versão do harness | só você, no terminal |
152
529
 
153
- **O princípio é máximo de qualidade com máximo de autonomia e mínimo de interrupção.** Você é
154
- chamado para aprovar a spec (e nem isso no modo autônomo), para remover um ambiente, que apaga
155
- dados, e para fazer o merge. Todo o resto roda sem pergunta: os comandos dentro do sandbox e os
156
- scripts do harness. A qualidade não depende da sua atenção: vem dos portões, dos revisores e do
157
- sandbox. Se quiser alguma pergunta de volta, acrescente a regra em `permissions.ask` num
158
- fragmento do projeto (`harness.d/settings.json`); pergunta vence liberação.
159
-
160
- ## Uma primeira entrega
161
-
162
- 1. Abra um worktree para a feature, pelo Orca ou com `git worktree add`. O
163
- `.harness/setup-worktree` grava as portas dela no `.env` e instala as dependências.
164
- 2. Na sessão do Claude Code, dentro do worktree: `/harness:entregar`.
165
- 3. Responda a entrevista. Leia os achados do revisor da spec e aprove a spec.
166
- 4. Acompanhe: os tickets são criados, os implementadores trabalham em paralelo, a
167
- checagem roda, os dois revisores e o portão de qualidade dão o veredito, a branch é enviada e o pull request é aberto.
168
- 5. Faça o merge, preservando os commits.
169
-
170
- ## Seguir sem você
171
-
172
- Se você disser "segue até o fim" durante uma entrega, ela corre em modo autônomo: toda
173
- pergunta recebe a resposta recomendada, a aprovação da spec deixa de ser uma parada, e cada
174
- decisão tomada sem você fica escrita na spec, na seção "Decisões tomadas sem o dono". Você
175
- só é chamado se a entrega não fechar em três rodadas de correção, se faltar um dado que só
176
- você tem, e para o merge.
177
-
178
- ## O mapa do código
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.
179
533
 
180
- `/harness:mapear` gera o mapa na primeira vez e depois refaz só o que mudou. O trabalho de
181
- ler o código é de subagentes no modelo mais barato. `.harness/memory check` mostra o que
182
- envelheceu, inclusive termos do glossário cujo código não existe mais e decisões de
183
- arquitetura cuja área mudou bastante.
534
+ ## Configuração
184
535
 
185
- ## Depois do merge
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.
186
539
 
187
- `/harness:aprender` fecha o ciclo: atualiza o mapa, mostra quanto cada papel gastou em tokens
188
- (`.harness/learn usage`), faz a retrospectiva da entrega e, com `/harness:dream`, transforma o
189
- que as sessões ensinaram sobre o projeto em notas ancoradas no código. As propostas de
190
- melhoria ficam em `.harness-run/propostas/`; o que for do harness você traz para este
191
- repositório.
192
-
193
- ## Atualizar
194
-
195
- 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:
196
627
 
197
628
  ```bash
198
- .harness/update v0.2.0
629
+ .harness/update <tag>
199
630
  ```
200
631
 
201
- 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/`.
202
636
 
203
- ## O que ainda não foi verificado
637
+ ## O que já foi provado e o que ainda não
204
638
 
205
- Tudo abaixo passou em testes automáticos ou em sessões sem interface, mas não numa sessão
206
- interativa com um projeto de verdade. É a lista para a primeira validação:
639
+ **O que tem prova:**
207
640
 
208
- - `.harness/conf-apply`, `up` e `down` rodando sem pergunta, e a pergunta do `destroy` aparecendo.
209
- - `.harness/push` enviando para o GitHub com as suas credenciais, e `.harness/pr` com o `gh`.
210
- - `/harness:setup` e `/harness:entregar` de ponta a ponta. A orquestração é conduzida por
211
- um modelo e não tem teste automático: os testes cobrem as peças e a coerência entre o que
212
- a skill manda fazer e o que os guards aceitam.
213
- - O carimbo automático a partir do veredito dos revisores, com os dois revisores. Só o
214
- de segurança rodou de ponta a ponta numa sessão real.
215
- - Instalar dependências (`pnpm install`) dentro do sandbox, num projeto com muitas.
216
- - A trava contra desligar o sandbox, numa sessão interativa.
217
- - `/harness:aprender` e `/harness:dream` sobre uma entrega de verdade: se a leitura das
218
- transcrições reconhece o formato das suas sessões, se os números de consumo batem, e se as
219
- notas que saem valem a pena.
220
- - `/harness:mapear` num projeto de verdade: a qualidade dos resumos, o custo da primeira
221
- geração, e o hook que injeta o índice no começo da sessão.
222
- - Um push por SSH: a rede é negada por nome de servidor, e não foi conferido se isso cobre SSH.
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`.
223
648
 
224
- Limites conhecidos, que não são falha de teste:
649
+ **O que ainda não foi provado:**
650
+
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:**
225
663
 
226
664
  - Sem o sandbox ligado, os portões protegem contra descuido, não contra um agente que insiste.
227
- - Um servidor de desenvolvimento que vigia arquivos pode não subir dentro do sandbox (visto com
228
- 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.
229
669
  - No Linux o sandbox não alcança `localhost`; `prepare` e `dev` precisariam de outra saída.
230
- - 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`.
231
676
  - Não há suporte ao Codex ainda.
232
- - Seis revisões adversariais acharam falhas reais, todas corrigidas. Isso mostra que
233
- revisar funciona, e não que não reste nenhuma.
234
677
 
235
678
  ## Desenvolver o harness
236
679
 
@@ -241,4 +684,6 @@ python3 -m unittest discover -s tests
241
684
  Os testes gravam em `~/.claude/harness/` e apagam ao sair, então não rodam de dentro de
242
685
  uma sessão com o sandbox ligado. Alguns usam Docker de verdade e são pulados sem ele.
243
686
 
244
- Licença MIT.
687
+ ## Licença
688
+
689
+ MIT.
package/install CHANGED
@@ -79,7 +79,7 @@ for s in json.load(open(sys.argv[1])).get("project_skills", []):
79
79
  fi
80
80
 
81
81
  # Com o harness.conf já preenchido, deixa o worktree pronto: portas no .env e dependências.
82
- NEXT="Falta, numa sessão do Claude Code aberta no projeto: /harness:setup, que propõe o harness.conf."
82
+ NEXT="O harness.conf é preenchido na primeira entrega. Se o projeto já tem código, rode antes /harness:setup, que o propõe a partir do que encontra."
83
83
  if grep -Eq '^PROJECT="?[^"[:space:]]' "$ROOT/harness.conf" 2>/dev/null; then
84
84
  HARNESS_SKIP_PLUGIN=1 "$ROOT/.harness/setup-worktree" || exit $?
85
85
  NEXT="O harness.conf já estava preenchido: portas gravadas no .env e dependências instaladas."
@@ -88,12 +88,10 @@ fi
88
88
  if [ -n "${CLAUDECODE:-}" ]; then
89
89
  cat >&2 <<'EOT'
90
90
 
91
- install: você está dentro de uma sessão do Claude Code. O sandbox dela bloqueia o acesso ao
92
- GitHub, e o registro do marketplace e a instalação dos plugins podem ter falhado. Os arquivos
93
- do projeto foram gravados. Para completar, rode no seu terminal, fora da sessão:
94
- cd <pasta do projeto>
95
- claude plugin marketplace add FullChico/fullchico-harness
96
- claude plugin install harness@fullchico --scope project
91
+ install: você está dentro de uma sessão do Claude Code, e o sandbox dela bloqueia o GitHub: o
92
+ plugin pode não ter sido instalado. Os arquivos do projeto foram gravados. Para completar, rode
93
+ este mesmo comando no seu terminal, fora da sessão; ele pode ser repetido sem dano:
94
+ npx @fullchico/harness install <pasta do projeto>
97
95
  EOT
98
96
  fi
99
97
 
@@ -101,8 +99,6 @@ cat <<EOT
101
99
 
102
100
  Harness $VERSION instalado em $ROOT, no perfil $PROFILE.
103
101
  $NEXT
104
- Abra o Claude Code uma vez nessa pasta, em modo interativo, e aceite o diálogo de confiança:
105
- sem isso ele ignora as permissões do projeto (.claude/settings.json), inclusive em sessões por linha de comando.
106
- Depois faça o commit do que foi gerado e envie a branch padrão ao remoto. Esse primeiro envio é
107
- seu, no terminal: os portões valem para ele também (.harness/approve em cada um).
102
+ Pronto. Abra o Claude Code nessa pasta (na primeira vez, aceite a confiança da pasta) e peça:
103
+ /harness:entregar <o que você quer construir>
108
104
  EOT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fullchico/harness",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
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.3",
3
+ "version": "0.1.5",
4
4
  "description": "Orquestração, guardrails e memória para projetos desenvolvidos com agentes.",
5
5
  "license": "MIT",
6
6
  "author": {