@fullchico/harness 0.0.0-stage → 0.1.3

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.
Files changed (83) hide show
  1. package/.claude-plugin/marketplace.json +14 -0
  2. package/LICENSE +21 -0
  3. package/README.md +243 -2
  4. package/bin/harness.js +21 -0
  5. package/install +108 -0
  6. package/package.json +27 -4
  7. package/plugin/.claude-plugin/plugin.json +9 -0
  8. package/plugin/agents/implementador.md +55 -0
  9. package/plugin/agents/orquestrador.md +59 -0
  10. package/plugin/agents/qualidade.md +44 -0
  11. package/plugin/agents/revisor-ambiente.md +86 -0
  12. package/plugin/agents/revisor-bugs.md +153 -0
  13. package/plugin/agents/revisor-spec.md +49 -0
  14. package/plugin/agents/revisor.md +96 -0
  15. package/plugin/agents/seguranca.md +62 -0
  16. package/plugin/bin/sync +322 -0
  17. package/plugin/map.json +387 -0
  18. package/plugin/payload/agents-clean +77 -0
  19. package/plugin/payload/approve +34 -0
  20. package/plugin/payload/arch_check.py +94 -0
  21. package/plugin/payload/compose_check.py +186 -0
  22. package/plugin/payload/conf-apply +22 -0
  23. package/plugin/payload/destroy +21 -0
  24. package/plugin/payload/dev +24 -0
  25. package/plugin/payload/down +20 -0
  26. package/plugin/payload/entrega/despacho.md +186 -0
  27. package/plugin/payload/entrega/fechamento.md +179 -0
  28. package/plugin/payload/entrega/tickets.md +154 -0
  29. package/plugin/payload/env-common.sh +64 -0
  30. package/plugin/payload/fetch +10 -0
  31. package/plugin/payload/gate-check +159 -0
  32. package/plugin/payload/git-hooks/commit-msg +32 -0
  33. package/plugin/payload/git-hooks/pre-commit +19 -0
  34. package/plugin/payload/git-hooks/pre-push +15 -0
  35. package/plugin/payload/hooks/__pycache__/common.cpython-313.pyc +0 -0
  36. package/plugin/payload/hooks/__pycache__/gate_stamp.cpython-313.pyc +0 -0
  37. package/plugin/payload/hooks/common.py +274 -0
  38. package/plugin/payload/hooks/dispatch_guard.py +290 -0
  39. package/plugin/payload/hooks/gate_stamp.py +242 -0
  40. package/plugin/payload/hooks/managed_guard.py +95 -0
  41. package/plugin/payload/hooks/service_guard.py +178 -0
  42. package/plugin/payload/hooks/session_context.py +68 -0
  43. package/plugin/payload/hooks/subagent_context.py +49 -0
  44. package/plugin/payload/integrate +110 -0
  45. package/plugin/payload/learn +7 -0
  46. package/plugin/payload/learn.py +282 -0
  47. package/plugin/payload/manifest_check.py +68 -0
  48. package/plugin/payload/memory +7 -0
  49. package/plugin/payload/memory.py +521 -0
  50. package/plugin/payload/pendings +7 -0
  51. package/plugin/payload/ports-free +55 -0
  52. package/plugin/payload/pr +52 -0
  53. package/plugin/payload/prepare +10 -0
  54. package/plugin/payload/push +44 -0
  55. package/plugin/payload/setup-worktree +61 -0
  56. package/plugin/payload/skills-add +20 -0
  57. package/plugin/payload/skills-search +6 -0
  58. package/plugin/payload/skills-show +6 -0
  59. package/plugin/payload/skills_remote.py +111 -0
  60. package/plugin/payload/subagent-rules.md +14 -0
  61. package/plugin/payload/ticket +67 -0
  62. package/plugin/payload/tickets_check.py +206 -0
  63. package/plugin/payload/up +45 -0
  64. package/plugin/payload/update +45 -0
  65. package/plugin/payload/validate +90 -0
  66. package/plugin/payload/worktree-env +128 -0
  67. package/plugin/skills/aprender/SKILL.md +62 -0
  68. package/plugin/skills/buscar-skills/SKILL.md +73 -0
  69. package/plugin/skills/dream/SKILL.md +92 -0
  70. package/plugin/skills/entregar/SKILL.md +110 -0
  71. package/plugin/skills/entregar/references/spec.md +84 -0
  72. package/plugin/skills/mapear/SKILL.md +85 -0
  73. package/plugin/skills/setup/SKILL.md +66 -0
  74. package/plugin/templates/AGENTS.managed.md +173 -0
  75. package/plugin/templates/AGENTS.project.md +3 -0
  76. package/plugin/templates/CLAUDE.md +10 -0
  77. package/plugin/templates/conductor.toml +16 -0
  78. package/plugin/templates/docs/agents/domain.md +15 -0
  79. package/plugin/templates/docs/agents/issue-tracker.md +23 -0
  80. package/plugin/templates/docs/agents/stack.md +132 -0
  81. package/plugin/templates/harness.conf +61 -0
  82. package/plugin/templates/orca.yaml +10 -0
  83. package/plugin/templates/settings.json +210 -0
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "fullchico",
3
+ "description": "Marketplace do FullChico Harness.",
4
+ "owner": {
5
+ "name": "FullChico"
6
+ },
7
+ "plugins": [
8
+ {
9
+ "name": "harness",
10
+ "source": "./plugin",
11
+ "description": "Ambiente de desenvolvimento com agentes: orquestração, portões de push, memória ancorada em git."
12
+ }
13
+ ]
14
+ }
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 FullChico
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,244 @@
1
- # Temporary Holding Version
1
+ # FullChico Harness
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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`.
45
+
46
+ ## Instalar num projeto
47
+
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.
51
+
52
+ Um comando, **no seu terminal, fora de uma sessão do Claude Code**, na pasta do projeto:
53
+
54
+ ```bash
55
+ npx @fullchico/harness install .
56
+ ```
57
+
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):
61
+
62
+ ```bash
63
+ cd /caminho/do/projeto
64
+ claude plugin marketplace add FullChico/fullchico-harness
65
+ claude plugin install harness@fullchico --scope project
66
+ ```
67
+
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.
70
+
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.
73
+
74
+ ### Deixar o Claude instalar
75
+
76
+ Cole este pedido numa sessão do Claude Code aberta na pasta do projeto:
77
+
78
+ ```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.
80
+
81
+ 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.
91
+ ```
92
+
93
+ Com o repositório clonado, `/caminho/do/fullchico-harness/install /caminho/do/projeto` faz o mesmo.
94
+
95
+ Ele grava `.harness/`, `.claude/settings.json`, `AGENTS.md`, `CLAUDE.md`, `docs/agents/` e
96
+ `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.
109
+
110
+ ### Perfis
111
+
112
+ O instalador aceita `--profile`, e a escolha fica no `harness.conf`:
113
+
114
+ | Perfil | Para quê | O que traz além do núcleo |
115
+ |---|---|---|
116
+ | `fullstack-typescript` (padrão) | projeto novo na stack padrão: NestJS, Next.js, Drizzle, Zod | a arquitetura, o arquivo da stack e as skills dela |
117
+ | `livre` | projeto novo em outra stack | os conceitos de arquitetura; a stack é escolhida na spec |
118
+ | `existente` | projeto que já tinha código | nada de arquitetura nem de língua: vale o que o projeto já usa |
119
+
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.
122
+
123
+ O que é só do projeto (hooks, permissões, servidores MCP, sites liberados) vai em
124
+ `harness.d/settings.json`, que é somado na geração.
125
+
126
+ ## O que muda no dia a dia
127
+
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.
130
+
131
+ **Os comandos do harness:**
132
+
133
+ | Comando | Para quê | Quem roda |
134
+ |---|---|---|
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 |
144
+ | `.harness/fetch` | atualiza as referências do remoto | o agente |
145
+ | `.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 |
151
+ | `.harness/update <tag>` | leva o projeto para uma versão do harness | só você, no terminal |
152
+
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
179
+
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.
184
+
185
+ ## Depois do merge
186
+
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:
196
+
197
+ ```bash
198
+ .harness/update v0.2.0
199
+ ```
200
+
201
+ Arquivo gerenciado que foi alterado à mão trava a atualização, que lista o que encontrou.
202
+
203
+ ## O que ainda não foi verificado
204
+
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:
207
+
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.
223
+
224
+ Limites conhecidos, que não são falha de teste:
225
+
226
+ - 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.
229
+ - 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.
231
+ - 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
+
235
+ ## Desenvolver o harness
236
+
237
+ ```bash
238
+ python3 -m unittest discover -s tests
239
+ ```
240
+
241
+ Os testes gravam em `~/.claude/harness/` e apagam ao sair, então não rodam de dentro de
242
+ uma sessão com o sandbox ligado. Alguns usam Docker de verdade e são pulados sem ele.
243
+
244
+ Licença MIT.
package/bin/harness.js ADDED
@@ -0,0 +1,21 @@
1
+ #!/usr/bin/env node
2
+ // Entrada do pacote: `npx @fullchico/harness install [pasta do projeto] [--profile <perfil>] [--force]`.
3
+ // O trabalho é do script `install`, em shell e Python: aqui só se acha a pasta do pacote e se repassa.
4
+ "use strict";
5
+ const { spawnSync } = require("node:child_process");
6
+ const path = require("node:path");
7
+
8
+ const root = path.resolve(__dirname, "..");
9
+ const [command, ...rest] = process.argv.slice(2);
10
+ const usage = "uso: fullchico-harness install [pasta do projeto] [--profile fullstack-typescript|livre|existente] [--force]\n" +
11
+ " fullchico-harness --version";
12
+
13
+ if (command === "--version" || command === "-v") {
14
+ console.log(require(path.join(root, "package.json")).version);
15
+ } else if (command === "install") {
16
+ const run = spawnSync("bash", [path.join(root, "install"), ...rest], { stdio: "inherit" });
17
+ process.exit(run.status === null ? 1 : run.status);
18
+ } else {
19
+ console.error(usage);
20
+ process.exit(command === "--help" || command === "-h" ? 0 : 2);
21
+ }
package/install ADDED
@@ -0,0 +1,108 @@
1
+ #!/usr/bin/env bash
2
+ # Adota o harness num projeto, num comando só.
3
+ # Uso: npx @fullchico/harness install [pasta do projeto] [--profile <perfil>] [--force]
4
+ # <pasta do harness>/install [pasta do projeto] [--profile <perfil>] [--force] (num clone)
5
+ #
6
+ # Perfis: fullstack-typescript (padrão; a stack e as skills dela), livre (projeto novo em
7
+ # outra stack) e existente (projeto que já tinha código; não impõe arquitetura nem língua).
8
+ #
9
+ # Grava os arquivos gerenciados, registra os marketplaces, instala os plugins no
10
+ # escopo do projeto e prepara o worktree. Pode ser rodado de novo sem dano.
11
+ # Variável: HARNESS_SKIP_PLUGIN=1 não chama o `claude`.
12
+ set -uo pipefail
13
+
14
+ HARNESS="$(cd "$(dirname "$0")" && pwd -P)"
15
+ PROJECT="." FORCE="" PROFILE="" WANT_PROFILE=""
16
+ for ARG in "$@"; do
17
+ if [ -n "$WANT_PROFILE" ]; then PROFILE="$ARG"; WANT_PROFILE=""; continue; fi
18
+ case "$ARG" in
19
+ --force) FORCE="--force" ;;
20
+ --profile) WANT_PROFILE=1 ;;
21
+ --profile=*) PROFILE="${ARG#--profile=}" ;;
22
+ -*) echo "uso: install [pasta do projeto] [--profile fullstack-typescript|livre|existente] [--force]" >&2; exit 2 ;;
23
+ *) PROJECT="$ARG" ;;
24
+ esac
25
+ done
26
+
27
+ ROOT="$(git -C "$PROJECT" rev-parse --show-toplevel 2>/dev/null)" || {
28
+ echo "install: $PROJECT não é um repositório git." >&2; exit 2; }
29
+ command -v python3 >/dev/null 2>&1 || { echo "install: falta o python3." >&2; exit 2; }
30
+
31
+ VERSION="v$(python3 -I -c 'import json,sys; print(json.load(open(sys.argv[1]))["version"])' \
32
+ "$HARNESS/plugin/.claude-plugin/plugin.json")" || exit 1
33
+
34
+ # shellcheck disable=SC2086
35
+ python3 -I "$HARNESS/plugin/bin/sync" "$ROOT" --version "$VERSION" $FORCE ${PROFILE:+--profile "$PROFILE"} || exit $?
36
+ # O perfil que vale é o que ficou no harness.conf: o pedido agora, ou o de uma instalação anterior.
37
+ PROFILE="$(sed -n 's/^PROFILE=//p' "$ROOT/harness.conf" | tr -d "\"'" | sed -n 1p)"
38
+ PROFILE="${PROFILE:-fullstack-typescript}"
39
+
40
+ 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; }
42
+ # Num clone do repositório, o marketplace é esta pasta (desenvolvimento do próprio harness).
43
+ # Instalado pelo npm, a pasta é o cache do npx e some: vale o repositório publicado.
44
+ if [ -d "$HARNESS/.git" ] || [ -f "$HARNESS/.git" ]; then MARKET="$HARNESS"; else MARKET="FullChico/fullchico-harness"; fi
45
+ MARKET="${HARNESS_MARKETPLACE:-$MARKET}"
46
+ 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
48
+ import json, sys
49
+ for name, entry in json.load(open(sys.argv[1])).get("extraKnownMarketplaces", {}).items():
50
+ source = entry.get("source", {})
51
+ if name != "fullchico" and source.get("source") == "github" and source.get("repo"):
52
+ print(source["repo"])
53
+ PY
54
+ claude plugin marketplace add "$REPO" >/dev/null 2>&1 || warn "registrar o marketplace $REPO" "claude plugin marketplace add $REPO"
55
+ done
56
+ # Instalar é por projeto: o comando roda de dentro dele.
57
+ python3 -I - "$ROOT/.claude/settings.json" <<'PY' | while IFS= read -r PLUGIN; do
58
+ import json, sys
59
+ for name, enabled in json.load(open(sys.argv[1])).get("enabledPlugins", {}).items():
60
+ if enabled:
61
+ print(name)
62
+ PY
63
+ (cd "$ROOT" && claude plugin install "$PLUGIN" --scope project >/dev/null 2>&1) || warn "instalar $PLUGIN" "claude plugin install $PLUGIN --scope project"
64
+ done
65
+ else
66
+ echo "install: sem o comando claude; os plugins ficam para depois." >&2
67
+ fi
68
+
69
+ # Skills de arquitetura, dos autores, copiadas para o projeto e fixadas no skills-lock.json.
70
+ if [ -z "${HARNESS_SKIP_PLUGIN:-}" ] && command -v npx >/dev/null 2>&1; then
71
+ python3 -I -c 'import json,sys
72
+ for s in json.load(open(sys.argv[1])).get("project_skills", []):
73
+ 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
75
+ [ -d "$ROOT/.claude/skills/$SKILL" ] && continue
76
+ (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
78
+ done
79
+ fi
80
+
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."
83
+ if grep -Eq '^PROJECT="?[^"[:space:]]' "$ROOT/harness.conf" 2>/dev/null; then
84
+ HARNESS_SKIP_PLUGIN=1 "$ROOT/.harness/setup-worktree" || exit $?
85
+ NEXT="O harness.conf já estava preenchido: portas gravadas no .env e dependências instaladas."
86
+ fi
87
+
88
+ if [ -n "${CLAUDECODE:-}" ]; then
89
+ cat >&2 <<'EOT'
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
97
+ EOT
98
+ fi
99
+
100
+ cat <<EOT
101
+
102
+ Harness $VERSION instalado em $ROOT, no perfil $PROFILE.
103
+ $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).
108
+ EOT
package/package.json CHANGED
@@ -1,6 +1,29 @@
1
1
  {
2
2
  "name": "@fullchico/harness",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.3",
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
+ "license": "MIT",
6
+ "author": "FullChico",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/fullchico/fullchico-harness.git"
10
+ },
11
+ "homepage": "https://github.com/fullchico/fullchico-harness#readme",
12
+ "bugs": {
13
+ "url": "https://github.com/fullchico/fullchico-harness/issues"
14
+ },
15
+ "keywords": ["claude-code", "agents", "harness", "guardrails", "hooks"],
16
+ "bin": {
17
+ "fullchico-harness": "bin/harness.js"
18
+ },
19
+ "files": ["bin/", "install", "plugin/", ".claude-plugin/", "LICENSE", "README.md"],
20
+ "engines": {
21
+ "node": ">=18"
22
+ },
23
+ "publishConfig": {
24
+ "access": "public"
25
+ },
26
+ "scripts": {
27
+ "test": "python3 -W error -m unittest discover -s tests"
28
+ }
29
+ }
@@ -0,0 +1,9 @@
1
+ {
2
+ "name": "harness",
3
+ "version": "0.1.3",
4
+ "description": "Orquestração, guardrails e memória para projetos desenvolvidos com agentes.",
5
+ "license": "MIT",
6
+ "author": {
7
+ "name": "FullChico"
8
+ }
9
+ }
@@ -0,0 +1,55 @@
1
+ ---
2
+ name: implementador
3
+ description: Implementa um ticket de uma spec, em contexto novo, a partir só da spec e do ticket. Usado pela entrega quando o projeto não tem agente próprio para a área.
4
+ model: haiku
5
+ tools: Read, Grep, Glob, Edit, Write, Bash, Skill
6
+ ---
7
+
8
+ # Implementador
9
+
10
+ Você implementa um ticket. Você não tem a conversa de quem escreveu a spec: o que
11
+ vale é o que está nos documentos e no repositório.
12
+
13
+ ## O que você recebe
14
+
15
+ ```pedido harness:implementador
16
+ spec: docs/specs/exemplo/spec.md
17
+ ticket: docs/specs/exemplo/issues/01-nome.md
18
+ leitura: GLOSSARY.md
19
+ ```
20
+
21
+ Numa rodada de correção vem também o arquivo com o que um revisor ou a checagem apontou:
22
+
23
+ ```pedido harness:implementador
24
+ spec: docs/specs/exemplo/spec.md
25
+ ticket: docs/specs/exemplo/issues/01-nome.md
26
+ achado: docs/specs/exemplo/achados/01-rodada-1.md
27
+ ```
28
+
29
+ ## Como trabalhar
30
+
31
+ 1. Se você está num worktree de agente (o caminho da pasta contém `.claude/worktrees/`),
32
+ rode `.harness/setup-worktree` antes de tudo: ele traz o `.env` da feature e instala as
33
+ dependências.
34
+ 2. Leia a spec inteira, o ticket e os arquivos de `leitura`. Leia o histórico da área que
35
+ vai tocar: `git log -- <caminho>`.
36
+ 3. Se o ticket não dá para ser feito só com esses documentos, pare e diga o que falta.
37
+ Não preencha a lacuna por conta própria.
38
+ 4. Implemente só o ticket, com a skill `tdd`, nos pontos de costura que a spec define. A seção
39
+ Arquitetura do `AGENTS.md` diz como o código deste projeto se organiza e que skills seguir;
40
+ se existir `docs/agents/stack.md`, ele traz as skills do seu papel e o que vale quando
41
+ elas divergem: leia os dois antes de escrever. O `AGENTS.md` vale sobre qualquer skill.
42
+ 5. Fique dentro do que o ticket possui (linha `Owns:`). Arquivo fora da posse faz a integração
43
+ ser recusada, inclusive manifesto de dependências e contrato. Se precisar de algo comum que
44
+ não existe (um tipo, um utilitário, uma dependência), não o crie fora da sua posse: pare e
45
+ relate. O commit que fecha o ticket roda a checagem do projeto e é recusado se ela falhar.
46
+ 6. Havendo `achado`, corrija o que ele aponta e nada além.
47
+ 7. Marque o ticket como `Status: done` no mesmo conjunto de commits, e só depois de ver os
48
+ testes dele passarem no ambiente da feature. Se não conseguiu rodá-los, não marque: termine
49
+ dizendo o que impediu. Não troque o banco da feature por um substituto em memória nem por
50
+ um servidor que você mesmo subiu.
51
+
52
+ ## Como terminar
53
+
54
+ Três itens: o que foi feito, o que ficou de fora e por quê, e como validar. Diga o
55
+ nome da branch em que os commits ficaram.
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: orquestrador
3
+ description: Executa uma spec já aprovada até o pull request. Fatia em tickets, despacha os implementadores em paralelo, integra, valida, passa pelos revisores e envia. Use depois que a spec foi revisada e aprovada.
4
+ model: sonnet
5
+ tools: Read, Grep, Glob, Edit, Write, Bash, Agent, Skill
6
+ ---
7
+
8
+ # Orquestrador
9
+
10
+ Você executa uma spec aprovada, do fatiamento ao pull request. Quem desenhou a solução foi
11
+ outra sessão; você não tem a conversa dela, e isso é proposital: o que vale é a spec.
12
+
13
+ ## O que você recebe
14
+
15
+ ```pedido harness:orquestrador
16
+ spec: docs/specs/exemplo/spec.md
17
+ leitura: GLOSSARY.md
18
+ ```
19
+
20
+ ## Regras
21
+
22
+ 1. **O documento é a única interface.** Todo pedido seu a um subagente só aponta arquivos,
23
+ no formato fixo mostrado nos roteiros. Sem narrativa, sem opinião.
24
+ 2. **Lacuna se corrige no documento.** Se um implementador não consegue trabalhar só com a
25
+ spec e o ticket, corrija a spec ou o ticket, faça o commit, e despache de novo.
26
+ 3. **Você não revisa o que orquestrou.** A revisão é dos revisores.
27
+ 4. **Você não tem a quem perguntar.** Toda escolha recebe a opção que você recomendaria, e
28
+ cada uma fica escrita na spec, na seção `## Decisões tomadas sem o dono`: o que foi
29
+ escolhido, a alternativa descartada e o motivo. Só devolva sem terminar quando faltar um
30
+ dado que ninguém além do dono tem.
31
+ 5. **Não peça ao dono nada que tenha comando próprio.** O `harness.conf` se grava com
32
+ `.harness/conf-apply` e o ambiente sobe com `.harness/up`.
33
+ 6. **Você conduz; quem escreve o código da feature são os implementadores.**
34
+
35
+ ## Roteiro
36
+
37
+ Leia cada roteiro na hora de usá-lo, não todos de uma vez:
38
+
39
+ 1. Fatiar a spec em tickets: `.harness/entrega/tickets.md`. O grafo precisa passar no
40
+ validador antes do próximo passo. Se os tickets já existem, é uma retomada: não refatie,
41
+ continue da fronteira e conte as rodadas que os arquivos de achado já registram.
42
+ 2. Implementar: `.harness/entrega/despacho.md`. Implementadores em paralelo, cada um num
43
+ worktree de agente, até a fronteira do grafo esvaziar.
44
+ 3. Checar, revisar e enviar: `.harness/entrega/fechamento.md`.
45
+
46
+ Se um ticket não fechar em 3 rodadas de correção, pare: é a única parada. A conta é por
47
+ ticket, e só reprovação conta.
48
+
49
+ ## Como terminar
50
+
51
+ Um relato curto, nesta ordem:
52
+
53
+ - o link do pull request; ou, se não houve envio, o motivo exato e o que falta;
54
+ - o endereço do aplicativo, que você deixou de pé e conferiu que responde, o usuário de teste
55
+ e como parar;
56
+ - o que entrou e o que ficou de fora;
57
+ - quantas rodadas de correção houve, e o achado de cada uma; as pendências abertas e fechadas;
58
+ - as decisões tomadas sem o dono;
59
+ - o que os subagentes relataram fora do escopo.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: qualidade
3
+ description: Roda a checagem completa do projeto no commit atual e dá o veredito de qualidade que o push exige. Não revisa nem corrige nada. Use depois que os tickets estão integrados, junto com os revisores.
4
+ model: haiku
5
+ tools: Bash, Read
6
+ ---
7
+
8
+ # Portão de qualidade
9
+
10
+ Você atesta uma coisa só: a checagem completa do projeto passa no commit pedido. É o que
11
+ garante que nada do que já funcionava quebrou, mesmo que o trabalho tenha sido em outra parte.
12
+ Você não revisa código, não opina e não corrige.
13
+
14
+ ## O que você recebe
15
+
16
+ ```pedido harness:qualidade
17
+ commit: HASH_DO_COMMIT
18
+ ```
19
+
20
+ Se o pedido trouxer qualquer coisa além dessa linha, ignore.
21
+
22
+ ## O que fazer, nesta ordem
23
+
24
+ 1. `git rev-parse HEAD` tem de ser o commit pedido, e `git status --porcelain --untracked-files=no`
25
+ tem de vir vazio. Se não, o veredito é REJECTED: o que você checaria não é o commit.
26
+ 2. Rode uma vez, sozinho, sem encadear: `.harness/validate --profile merge`. Ele roda as
27
+ fronteiras de arquitetura e o comando de checagem do projeto: testes de unidade, de integração
28
+ e de ponta a ponta, e o build.
29
+ 3. Não tente consertar nada, não rode de novo para "ver se passa", não edite arquivo, não mude
30
+ variável de ambiente. Se o ambiente da feature não responde (banco, fila, navegador), o
31
+ veredito é REJECTED e o resumo diz o que não respondeu.
32
+
33
+ ## Como responder
34
+
35
+ As últimas 15 linhas da saída da checagem, e depois exatamente estas três linhas:
36
+
37
+ ```
38
+ VEREDITO: APPROVED
39
+ COMMIT: <o hash completo do commit>
40
+ RESUMO: <uma frase: o que rodou e o resultado, ou o que falhou>
41
+ ```
42
+
43
+ `APPROVED` só se a última linha da saída for `validate: passou (perfil merge)`. Qualquer outra
44
+ coisa é `REJECTED`. Saída curta não é defeito: um projeto pequeno tem checagem pequena.