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.

org · siteversatile.shside project pessoal (organização, repositórios em sua maioria privados)Formato uma organização, não um repositórioSite export estático do Next.js 16, servidor de formulários em BunJeito de trabalhar um harness central mais harnesses satélitesVisibilidade site e alguns motores públicos; harnesses privadosversatile.sh

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).

ParteO que é
MotoresRepositórios independentes com núcleos neutros, cada um com seu lar de registros
Site da empresaExport estático de Next.js 16, Tailwind CSS 4 e TypeScript, com diretórios de conectores e skills e formulários
Harness centralComo o time trabalha: router, docs de workflow, skills, agentes, comandos, hooks, ferramentas
Harnesses satélitesConhecimento 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.

Bootstrap do harnesssh
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.

Site da empresash
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ávelUsada porEfeito
DATA_DIRservidor do siteOnde o banco de dados dos formulários é guardado
CATALOG_DIRtarefas do siteCheckout do catálogo lido por mise run catalog e mise run skills
VERSATILE_CONFORMANCE=offbin/syncPula a linha de resumo de conformidade

Arquitetura

rulesstudycenterdeploymedia
O harness central é o eixo; cada satélite é seu próprio repositório, ligado a ele e nunca copiado para dentro.

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.

text
          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)
HarnessGuarda
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-harnessBase 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-harnessInfraestrutura e a configuração de deploy de cada app
research-harnessO motor de pesquisa: método, estudos, estado, um lar de pesquisa gerado
repositórios de mídiaA cópia canônica de toda imagem, vídeo, logo e fonte de design
Um repositório de projetoSó 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

recordfixguardproofok?
Um problema recorrente percorre correção, prova, confirmação do dono, guard e registro, e o guard impede que ele volte.

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.

  1. 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.
  2. 2Corrigir a causa raizA menor mudança que remove a causa, não um remendo no sintoma.
  3. 3CertificarUm teste que falha primeiro ou um antes e depois, mais uma varredura por outras instâncias da classe.
  4. 4Pedir confirmaçãoUma linha para o dono. A certificação é do agente, a confirmação é do dono.
  5. 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.
  6. 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

checklistnotemain
A catraca só gira quando a nota de conhecimento da sessão está na caixa; aí a branch chega ao main.

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.

  1. 1Branchgit fetch, depois um worktree numa feature branch a partir de origin/main. Os commits são granulares, um por responsabilidade, cada um compilando.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

  1. 1IntakeO dono responde as perguntas antes de qualquer trabalho começar, registradas com a data.
  2. 2RecuperarO que já está fechado sobre o tema, com data e commit.
  3. 3CharterDecisão, unidade de análise, regra de julgamento, níveis de prova, pisos, escopo, assentos e orçamento. O dono libera.
  4. 4Ataque ao enquadramentoUm red team questiona a pergunta e as premissas antes de existir qualquer resposta.
  5. 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.
  6. 6RodadasPropostas, objeções, decisões, auditoria e spikes, liberados em lotes. O dono decide depois de cada lote.
  7. 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/.

PremissaO que significa para um design
Público amanhãTodo repositório de projeto é escrito como se fosse público amanhã
Núcleo neutroUm núcleo não nomeia produto, cliente, fornecedor nem projeto irmão
Registros privadosOs registros são privados e vivem em um só lugar
Um artefato, todo deployUm artefato serve a todo deploy
Segredos são referênciasUm segredo é uma referência em todo lugar, exceto no store e no processo que precisa dele
Sem dados de clientesNenhum dado de cliente, empregador ou pessoal em lugar nenhum
Validação localNenhum job remoto bloqueia um pull request
Só pull requestsO trabalho chega ao main só por um pull request
Evidência antes de concluirNada está pronto sem evidência
Os registros mudam com o códigoMesma unidade de trabalho, mesmo fluxo de pull request
Time pequeno com IAO time aprende uma vez só
Cada harness seu próprio repositórioO 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.

GateCheca
Editor e formataçãoFormatação e lint rápido enquanto se digita
Pre-commitFormatação e lint só de AST dos arquivos staged, corrigidos e re-staged
Pre-push e checkLinters nos pacotes alterados desde o merge base; o check completo sob demanda
Gate de conhecimentoO checklist da sessão é registrado antes de gh pr create
RevisãoEixos de standards e de spec, por /review ou /pre-pr
Gate de mergeO commit integrado é o que a validação carimbou; só onde o repositório tem um
Catálogo de lintsUm erro recorrente confirmado vira um lint compartilhado que todo projeto ativa
Bootstrap de repositório novoDependabot, Semgrep, lefthook, LICENSE, SECURITY.md, padrão de README, go-lint para Go
Conformidade da organizaçãobin/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ívelEvidênciaServe para
SComportamento observado no sistema em execução: screenshots, saída real de comandos, requisição e resposta reaisUI, comportamento de ponta a ponta, deploys
AUm teste que falhou antes da mudança e passa depoisBugs, race conditions, regras
BTestes direcionados, checagem de tipos, lint e build, tudo verdeRefactors, mudanças internas
CLi o código e deve funcionarNada: não é evidência
MudançaEvidência mínima
FeatureA, mais S quando tem interface de usuário
Correção de bugA: o teste que falha primeiro
RefactorB, testes de comportamento inalterados e verdes
Configuração ou deployS: observado no sistema em execução
Mudança visualS: screenshots em largura de desktop e de celular
Alegação de desempenhoS 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ãoEscolhidoRejeitadoPor quê
Formato das ferramentasUm harness central mais satélites como submódulosUm monorepo; conteúdo copiadoCada responsabilidade tem seu histórico e sua verdade; o central liga, nunca copia
EntregaPull request, merge commit, validação localPush direto; squash; gate de CI remotoO main fica limpo e cada merge reverte como uma unidade; um job remoto que nunca roda não bloqueia nada
AprendizadoGuard após confirmação do dono, registrado uma vezSó memória; cópias por repositórioProsa é quebrada de novo; cópias divergem
Lar do conhecimentoRegistros num satélite privadoADRs e runbooks nos repos de produtoUm repositório de produto precisa poder ser publicado amanhã
PesquisaUm estudo com charter, juiz e auditor independentesUma passada única de um agenteUma passada única é rascunho, nunca resultado
ProvaUma escala S, A, B, CEscalas por documentoTudo é comparável
Comando de checkUm mise run check por repositórioMakefiles e scripts ad hocDuas 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ção
  • versatile-harness/premises/00-INDEX.mdÍndice das premissas permanentes
  • versatile-harness/rules/00-INDEX.mdÍndice das regras de engenharia
  • versatile-harness/lints/00-INDEX.mdO catálogo de lints
  • research-harness/docs/methodology.mdRegras de estudo, etapas e níveis de prova
  • versatile.sh/lib/leads.tsValidação de leads do site
  • versatile.sh/DESIGN.mdRegras de design do site