versatile.sh
Uma pequena organização tocada como side project: motores independentes, um jeito compartilhado de trabalhar com agentes de IA e os harnesses que mantêm os dois honestos.
Visão geral
versatile-sh é a organização que eu toco como side project. Ela é construída em torno de uma ideia: motores independentes. Cada motor faz um trabalho (workflows duráveis, um motor de testes, um motor de computação, um protocolo de plugins), mantém um núcleo neutro que não nomeia nenhum produto e pode ser usado sem os outros.
A organização também é um jeito de trabalhar. Um time pequeno trabalha com agentes de IA, e o time aprende uma vez só: o que uma pessoa ensina a um agente vira uma regra, um registro ou um lint compartilhado em vez de ficar na memória de uma máquina.
Este case descreve esse jeito de trabalhar de forma segura para o público: a estrutura, os fluxos e os gates. Os repositórios dos harnesses são privados, então seus caminhos são nomeados mas não linkados. Os motores aparecem por codinome: nagare (workflow durável), hakoniwa (motor de testes), heya (motor de computação), tsugite (protocolo de plugins).
| Parte | O que é |
|---|---|
| Motores | Repositórios independentes com núcleos neutros, cada um com seu lar de registros |
| Site da empresa | Export estático de Next.js 16, Tailwind CSS 4 e TypeScript, com diretórios de conectores e skills e formulários |
| Harness central | Como o time trabalha: router, docs de workflow, skills, agentes, comandos, hooks, ferramentas |
| Harnesses satélites | Conhecimento de engenharia e registros dos projetos, config de infraestrutura, motor de pesquisa, mídia |
Primeiros passos
Quem contribui clona o harness central e os satélites de que precisa, lado a lado, e roda duas ferramentas. bin/sync deixa tudo em dia. bin/install liga os skills, agentes e comandos em cada checkout.
bin/sync # fast-forward clean checkouts on main; move read copies to each satellite's main
bin/install # link skills, agents, commands into each versatile-sh checkout
bin/install --with-hooks --with-timer # team hooks and a daily sync + harvest timer
bin/conformance # what each repository misses from the baseline- bin/install escreve um symlink por skill, agente e comando, listado no .git/info/exclude de cada projeto para que nada seja commitado num projeto.
- Um item do próprio projeto com o mesmo nome vence um item linkado.
- bin/install cria uma área local/ que nunca é enviada, para tudo que não faz parte da organização, e monta uma lista de bloqueio pessoal a partir dos seus outros checkouts.
- bin/sync é idempotente: rodar duas vezes não muda nada na segunda. Ele nunca faz stash, reset nem troca de branch.
- --bump registra o main atual de cada satélite como ponteiro do submódulo, por um pull request.
O site da empresa roda com o mise, que instala Node.js, pnpm e Bun.
mise run install
mise run dev # pages on http://localhost:3000, without the forms API
mise run build # static export into out/
mise run preview # out/ plus the forms API| Variável | Usada por | Efeito |
|---|---|---|
| DATA_DIR | servidor do site | Onde o banco de dados dos formulários é guardado |
| CATALOG_DIR | tarefas do site | Checkout do catálogo lido por mise run catalog e mise run skills |
| VERSATILE_CONFORMANCE=off | bin/sync | Pula a linha de resumo de conformidade |
Arquitetura
O harness central é o único lugar que reúne tudo. Todo outro harness é um satélite com seu próprio repositório, trazido como submódulo git em harness/ no central. Nada é copiado.
versatile-sh/.claude (center: how we work)
router, docs/work, skills, agents, commands, bin, hooks
|
+-------------------+--------------------+--------------------+
| | | |
versatile-harness hosting-harness research-harness <domain>-media
engineering rules infra + deploy method, studies, canonical images,
project records config per app generated home video, logos
|
+-- projects/<repo>/ profile, agents.md, adr/, roadmap, issues
project repositories: the product only (code, tests, README)| Harness | Guarda |
|---|---|
| Central (.claude) | Como trabalhamos: router, docs/work, skills, agentes, comandos, ferramentas bin, hooks, o guia para colegas. Nunca regras de engenharia nem fatos de um projeto |
| versatile-harness | Base de conhecimento de engenharia (premissas, regras, padrões, standards, lints, design, decisões, arquitetura, índice de pesquisa) e o lar de registros de cada projeto |
| hosting-harness | Infraestrutura e a configuração de deploy de cada app |
| research-harness | O motor de pesquisa: método, estudos, estado, um lar de pesquisa gerado |
| repositórios de mídia | A cópia canônica de toda imagem, vídeo, logo e fonte de design |
| Um repositório de projeto | Só o produto, escrito como se fosse público amanhã |
A verdade de um satélite é o seu main no GitHub. A cópia em harness/ é somente leitura e o bin/sync a mantém nesse main. Uma mudança é feita na cópia de trabalho irmã, numa branch, por um pull request.
Tudo que não faz parte da organização fica em local/ ou na memória própria de cada pessoa. O inverso também vale: nada sobre a organização tem a memória pessoal como único lar.
Ciclo de aprendizado
Quando um problema se repete ou alguém repete um pedido, a resposta é um protocolo fixo. Memória numa máquina não é aprendizado, e uma regra só em prosa será quebrada de novo.
- 1Reconhecer a classeNomear o problema como uma classe, por exemplo valores de cor crus em componentes. Conferir primeiro as issues abertas e o catálogo de lints.
- 2Corrigir a causa raizA menor mudança que remove a causa, não um remendo no sintoma.
- 3CertificarUm teste que falha primeiro ou um antes e depois, mais uma varredura por outras instâncias da classe.
- 4Pedir confirmaçãoUma linha para o dono. A certificação é do agente, a confirmação é do dono.
- 5Codificar o guardSó depois de um sim explícito: um lint, check, teste ou ratchet, provado reintroduzindo o erro uma vez, e registrado no catálogo de lints na mesma unidade de trabalho.
- 6Registrar e compartilharUm pull request no lar compartilhado. Os colegas recebem no próximo pull.
Se o dono não responde, a correção e seu teste de regressão ficam, a issue é marcada como corrigida mas não confirmada, e nenhum guard para a classe inteira é adicionado. Separadamente, quando uma pessoa faz algo melhor do que o harness descreve, isso é registrado como prática de campo no arquivo dono do tema e substitui o texto da regra no segundo caso confirmado.
Gate do pull request
Em todo repositório versatile-sh o trabalho chega ao main só por um pull request a partir de uma feature branch, integrado com um merge commit depois da validação local. Não há push direto, nem force-push ou reescrita de histórico sem a aprovação explícita do dono.
- 1Branchgit fetch, depois um worktree numa feature branch a partir de origin/main. Os commits são granulares, um por responsabilidade, cada um compilando.
- 2Validar localmenteO único comando de check do repositório. Os workflows de CI são manuais e não bloqueiam nada, então a evidência no pull request é a prova.
- 3Checklist de conhecimento da sessãoAntes de abrir o pull request, atualizar o que a sessão mudou ou aprendeu: o README e os docs do projeto, os registros no versatile-harness, qualquer regra, padrão ou lint que surgiu e o harness central se o jeito de trabalhar mudou. Cada um vai por seu próprio pull request.
- 4Registrarbin/pr-ready guarda as respostas do checklist para a branch. O hook em gh pr create segura o comando até esse registro existir. Ele expira em um dia.
- 5Merge e limpezagh pr merge --merge --delete-branch, apagar a branch local, remover o worktree, tudo na mesma unidade de trabalho. O dono é avisado no chat do que foi atualizado, com links.
O gate é simbólico e falha aberto. Ele se satisfaz apenas fazendo o checklist, não se aplica aos próprios repositórios de harness e deixa passar qualquer outro comando.
Método de pesquisa
As decisões reais passam por um único motor, o research harness. Um estudo sustenta uma decisão do dono, e um estudo que não consegue nomear sua decisão não começa. O método foi reescrito a partir do que pesquisas anteriores fizeram bem e mal, e é emendado depois de cada estudo.
- 1IntakeO dono responde as perguntas antes de qualquer trabalho começar, registradas com a data.
- 2RecuperarO que já está fechado sobre o tema, com data e commit.
- 3CharterDecisão, unidade de análise, regra de julgamento, níveis de prova, pisos, escopo, assentos e orçamento. O dono libera.
- 4Ataque ao enquadramentoUm red team questiona a pergunta e as premissas antes de existir qualquer resposta.
- 5Inventário e exploraçãoUm inventário cego construído do usuário para fora e do código para dentro, depois uma tabela macro de candidatos. O dono escolhe o que aprofundar.
- 6RodadasPropostas, objeções, decisões, auditoria e spikes, liberados em lotes. O dono decide depois de cada lote.
- 7Síntese e encerramentoUm mapa ou matriz, decisões do dono com recomendações, itens adiados com um gatilho, uma auditoria final por um auditor que não é o juiz e uma retro que emenda o método.
Uma pergunta estreita que uma fonte resolve é pesquisa pontual e pula as rodadas. Uma escolha dentro de uma tarefa recebe uma matriz de decisão de dez linhas no corpo do pull request, escrita antes de os candidatos rodarem.
Premissas
Uma premissa é uma suposição permanente de que todo design parte e que não é rediscutida a cada tarefa. Cada uma tem seu próprio arquivo pequeno em versatile-harness/premises/.
| Premissa | O que significa para um design |
|---|---|
| Público amanhã | Todo repositório de projeto é escrito como se fosse público amanhã |
| Núcleo neutro | Um núcleo não nomeia produto, cliente, fornecedor nem projeto irmão |
| Registros privados | Os registros são privados e vivem em um só lugar |
| Um artefato, todo deploy | Um artefato serve a todo deploy |
| Segredos são referências | Um segredo é uma referência em todo lugar, exceto no store e no processo que precisa dele |
| Sem dados de clientes | Nenhum dado de cliente, empregador ou pessoal em lugar nenhum |
| Validação local | Nenhum job remoto bloqueia um pull request |
| Só pull requests | O trabalho chega ao main só por um pull request |
| Evidência antes de concluir | Nada está pronto sem evidência |
| Os registros mudam com o código | Mesma unidade de trabalho, mesmo fluxo de pull request |
| Time pequeno com IA | O time aprende uma vez só |
| Cada harness seu próprio repositório | O central liga satélites, nunca os copia |
Um repositório de projeto guarda só o produto. Nenhum ADR, runbook, pesquisa, config de deploy, host ou processo interno aparece em seus arquivos, commits, corpos de pull request ou nomes de branch. É isso que torna testável a premissa do público amanhã.
Gates e lints
Toda mudança sobe pelos mesmos gates, do mais barato ao mais caro, todos na máquina de quem desenvolve. Um gate checa uma coisa, tem um lar de config e chama o único comando de check do repositório, mise run check, em vez de reimplementá-lo.
| Gate | Checa |
|---|---|
| Editor e formatação | Formatação e lint rápido enquanto se digita |
| Pre-commit | Formatação e lint só de AST dos arquivos staged, corrigidos e re-staged |
| Pre-push e check | Linters nos pacotes alterados desde o merge base; o check completo sob demanda |
| Gate de conhecimento | O checklist da sessão é registrado antes de gh pr create |
| Revisão | Eixos de standards e de spec, por /review ou /pre-pr |
| Gate de merge | O commit integrado é o que a validação carimbou; só onde o repositório tem um |
| Catálogo de lints | Um erro recorrente confirmado vira um lint compartilhado que todo projeto ativa |
| Bootstrap de repositório novo | Dependabot, Semgrep, lefthook, LICENSE, SECURITY.md, padrão de README, go-lint para Go |
| Conformidade da organização | bin/conformance lista o que cada repositório ainda não tem |
O catálogo de lints lista cada lint uma vez com o problema que previne, onde está implementado e quais projetos o ativaram. Exemplos incluem um gate de neutralidade para núcleos de motores, uma tabela de arestas de dependência, uma checagem de comentários, um clock seam, uma checagem de ambiente na raiz de composição e um gate Semgrep com ratchet no merge base. As checagens de Go vêm de um único kit compartilhado, o go-lint.
Pull requests do Dependabot nunca ficam ociosos: cada um é revisado e integrado, corrigido e integrado, migrado ou planejado numa issue com sua versão ignorada.
Níveis de prova
Uma afirmação precisa de evidência que outra pessoa consiga reproduzir, mostrada como antes e depois, com a linha de base capturada primeiro. Há uma única escala, e toda célula de ADR, estudo ou matriz de decisão usa posições dela.
| Nível | Evidência | Serve para |
|---|---|---|
| S | Comportamento observado no sistema em execução: screenshots, saída real de comandos, requisição e resposta reais | UI, comportamento de ponta a ponta, deploys |
| A | Um teste que falhou antes da mudança e passa depois | Bugs, race conditions, regras |
| B | Testes direcionados, checagem de tipos, lint e build, tudo verde | Refactors, mudanças internas |
| C | Li o código e deve funcionar | Nada: não é evidência |
| Mudança | Evidência mínima |
|---|---|
| Feature | A, mais S quando tem interface de usuário |
| Correção de bug | A: o teste que falha primeiro |
| Refactor | B, testes de comportamento inalterados e verdes |
| Configuração ou deploy | S: observado no sistema em execução |
| Mudança visual | S: screenshots em largura de desktop e de celular |
| Alegação de desempenho | S ou A com números, mesmas condições antes e depois |
Nos estudos, os rótulos lido, especificado e executado mapeiam para esta escala. Uma afirmação lida só vale como um fato sobre a sua fonte, com versão e data. Nunca é prova de que a nossa mudança funciona.
Site da empresa
O site é um export estático do Next.js 16 com App Router, Tailwind CSS 4 e TypeScript. Um pequeno servidor Bun entrega o export e guarda os formulários em SQLite, a partir do schema em migrations/.
- Páginas da empresa, mais diretórios /connectors e /skills construídos a partir de dois catálogos de arquivos simples.
- Formulários: lista de espera, contato e envios de conectores e skills. A validação de leads fica em lib/leads.ts.
- POST /api/leads aplica uma checagem de mesma origem, um limite de 8 KB, um honeypot e um limite de taxa por endereço.
- O servidor responde / com um espelho em Markdown quando a requisição pede text/markdown; o site também entrega rotas de descoberta llms.txt.
- O site não traz configuração de deploy. As regras de design estão em DESIGN.md.
Decisões
| Decisão | Escolhido | Rejeitado | Por quê |
|---|---|---|---|
| Formato das ferramentas | Um harness central mais satélites como submódulos | Um monorepo; conteúdo copiado | Cada responsabilidade tem seu histórico e sua verdade; o central liga, nunca copia |
| Entrega | Pull request, merge commit, validação local | Push direto; squash; gate de CI remoto | O main fica limpo e cada merge reverte como uma unidade; um job remoto que nunca roda não bloqueia nada |
| Aprendizado | Guard após confirmação do dono, registrado uma vez | Só memória; cópias por repositório | Prosa é quebrada de novo; cópias divergem |
| Lar do conhecimento | Registros num satélite privado | ADRs e runbooks nos repos de produto | Um repositório de produto precisa poder ser publicado amanhã |
| Pesquisa | Um estudo com charter, juiz e auditor independentes | Uma passada única de um agente | Uma passada única é rascunho, nunca resultado |
| Prova | Uma escala S, A, B, C | Escalas por documento | Tudo é comparável |
| Comando de check | Um mise run check por repositório | Makefiles e scripts ad hoc | Duas definições de verde divergem |
- O gate de merge existe só em alguns repositórios de produto; nos demais a evidência no pull request é o gate.
- O gate de conhecimento é simbólico e falha aberto se seu hook der erro.
- Os harnesses e vários motores são privados, então este case não pode linká-los.
- Alguns lints constam com implementação ainda não verificada; a ferramenta de conformidade reporta o que cada repositório ainda não tem.
Arquivos
Os caminhos dos harnesses são privados e relativos a cada repositório de harness.
.claude/CLAUDE.mdRouter do harness central: escopo, regras inegociáveis, tabela de roteamento.claude/docs/work/01-WORKFLOW.mdO ciclo de trabalho, a matriz de decisão, a condição de parada.claude/docs/work/03-EVIDENCE.mdNíveis de prova e antes e depois.claude/docs/work/04-LEARNING-LOOP.mdProblema recorrente para guard para registro compartilhado.claude/docs/work/06-GIT-AND-PRS.mdRegras de git e o checklist de conhecimento da sessão.claude/docs/work/10-GATES.mdA escada de gates.claude/bin/syncAtualiza checkouts e cópias de leitura dos satélites.claude/bin/installLiga skills, agentes, comandos; hooks e timer.claude/bin/conformanceChecagem da linha de base em toda a organizaçãoversatile-harness/premises/00-INDEX.mdÍndice das premissas permanentesversatile-harness/rules/00-INDEX.mdÍndice das regras de engenhariaversatile-harness/lints/00-INDEX.mdO catálogo de lintsresearch-harness/docs/methodology.mdRegras de estudo, etapas e níveis de provaversatile.sh/lib/leads.tsValidação de leads do siteversatile.sh/DESIGN.mdRegras de design do site