Método Expx

O método, escrito e executável

Pedir a um agente de IA para construir uma feature funciona — até a segunda hora. O plano era vago o bastante para o agente decidir sozinho no meio da implementação, e ele decide: escolhe um padrão que não é o do projeto, escreve o teste na pasta que o runner não olha, refatora três arquivos que ninguém pediu. O método Expx é o conjunto das restrições que evitam isso, escrito. Este site é a referência completa do expxdev — o CLI que instala e mantém as oito skills — e de cada uma delas.

npx expxdev init

Apresentação para o time → — deck navegável em HTML, pronto para levar essa introdução a uma reunião de engenharia.

As quatro apostas

O método parte de quatro premissas, e tudo o mais decorre delas.

1. Todo o esforço vai para o planejamento

   Uma pergunta feita durante a execução é sempre uma falha da fase de planejamento. Se a ambiguidade foi eliminada antes, a execução pode ser autônoma sem virar aposta.

2. Nada avança sem critério verificável

   Task, fase e sprint têm portão de aceite binário, sem adjetivo. TDD não é sugestão: o teste vem antes, e a task só fecha com a suíte inteira verde.

3. O escopo é travado no que a investigação provou

   O que não está no plano não é tocado. Melhoria avulsa vira registro de dívida, nunca um brinde no diff.

4. Quem implementa não aprova

   O QA e a auditoria são papéis distintos, e os agentes que os executam têm acesso somente de leitura — o que transforma “aponta, não corrige” de promessa em impossibilidade técnica.

O método de ponta a ponta

Build e Run são a mesma disciplina

sprintx e runx não são dois métodos: são o mesmo método com gatilhos diferentes.

As duas compartilham exatamente os mesmos contratos: base de conhecimento antes de qualquer plano, hierarquia sprint → fase → task, TDD obrigatório com no mínimo dois testes por task, critério de aceite verificável em toda transição e execução autônoma guiada por um arquivo orquestrador. Muda o gatilho e o tamanho. Nunca o rigor.

Começar

Instalação

O init busca as skills que você escolher nos repositórios oficiais, empacota apenas as selecionadas como um plugin local chamado expx e configura o harness.

O caminho declarativo

A seleção é feita por flag, o que faz a mesma linha servir ao seu terminal e ao CI:

npx expxdev init --skills sprintx,runx,mergex --harness claude,opencode --yes

Todas aceitam também a forma --flag=valor.

O caminho interativo

Rodando npx expxdev init sem --skills num terminal completo (stdin e stdout precisam ser TTY), o CLI abre um assistente:

  ███████ ██   ██ ██████  ██   ██   dev
  o CLI do metodo Expx · v0.5.0

? Quais skills instalar? (espaço marca, enter confirma)
 ◉ sprintx   planeja e executa features novas
 ◉ runx      ocorrencias de manutencao do dia a dia
 ◯ legadox   camada para projetos legados
 ◯ stackx    descobre o dialeto tecnico do repositorio
 ◉ mergex    versionamento, entrega e revisao de pull requests
 ◯ memox     memoria do projeto, indexa os artefatos ja fechados
 ◯ prodx     camada de produto, decide se o pedido vira trabalho

? Qual harness? ◉ claude  ◯ opencode

Resumo
  skills   sprintx, runx, mergex
  harness  claude

? Confirmar? (S/n)

Se já existe um .expx/ no projeto, o assistente pergunta antes se você quer reconfigurar, com o padrão em não — seguir remonta a instalação a partir da nova seleção.

O que fica no seu projeto

Commite o .expx/

A instalação é travada por lock, e o lock é para ser versionado. Quem clona o projeto recebe exatamente as mesmas skills que o time está usando, sem rede e sem rodar nada. O doctor trata como erro um .gitignore que ignore o .expx/.

Começar

O ecossistema

Oito skills que não se conhecem por código: elas se encontram em contratos escritos. É isso que permite instalar três delas e não as outras cinco, ou atualizar uma sem tocar nas demais.

As oito skills

Como as camadas compõem

A prodx é a única que roda antes das outras: ela decide se existe trabalho; as demais tratam de como fazê-lo. Sem ela, o método planeja com rigor uma feature que não deveria existir — o desperdício mais caro de uma software house, porque passa em todos os testes.

A regra de precedência que evita o pior colateral

stackx descreve o que deve ser seguido daqui pra frente. legadox descreve o que existe hoje, incluindo os dialetos conflitantes. Em projeto novo, só o stackx governa. Em projeto legado, na área tocada manda o padrão local descrito no PERFIL.md; o stackx governa apenas código novo, em arquivo novo.

Sem essa regra, a IA “moderniza” arquivo antigo achando que está obedecendo convenção — o colateral mais perigoso que existe, porque vem com a justificativa de estar seguindo uma regra.

Quadro comparativo

A memox é a única que não grava nada em docs/: o índice dela é derivado, descartável e gitignorado. A prodx e a buildx são as únicas sem hooks — e a buildx é a única cujos artefatos descrevem um projeto, não um trabalho.

Começar

As três camadas de garantia

Uma regra escrita na skill é uma instrução — e instrução é coisa que o modelo pode esquecer na task 14 de uma execução longa, justamente quando o trabalho é grande e o risco é maior.

Todo hook de método nasce em modo aviso

A razão é prática: hook que dá falso positivo é desinstalado, e junto com ele vão os que funcionavam. A exceção são os hooks de segurança, que nascem em bloqueio e falham fechados — segredo commitado não tem volta, e o falso positivo ali é raro.

O modo de cada hook vive em .expx/hooks.json:

{
  "expx_hooks": 1,
  "hooks": {
    "escopo-da-task":   { "modo": "aviso",    "tipo": "metodo" },
    "segredo":          { "modo": "bloqueio", "tipo": "seguranca" }
  }
}

Arquivo ausente, ilegível ou sem a entrada: hook de segurança assume bloqueio, hook de método assume aviso. Só um desligado explícito desliga um de segurança.

Os agentes do ecossistema

Skill · base

sprintx

Planeja e executa features novas em seis fases: ingestão → descoberta → plano → orquestrador → auditoria → execução. Todo o esforço vai para o planejamento, e a execução é autônoma porque a ambiguidade já foi eliminada.

As fases

A fase é detectada pelo disco

A skill nunca lê o .expx/estado.json para decidir onde está — ela olha o que existe:

Comandos

No Claude Code os comandos ganham o namespace do plugin: /expx:sprintx-sprints. No OpenCode ficam sem prefixo: /sprintx-sprints.

Agentes e hooks

Regras invioláveis

São vinte no total. As que mais governam o dia a dia:

• R2 — “As fases são estritamente sequenciais; nunca pule fase nem execute fora de ordem.”
• R3 — “TDD é obrigatório: o teste é escrito antes da implementação.”
• R4 — “Task só é marcada como concluída quando o teste de integração E o teste funcional passam; não existe ‘concluído com ressalva’.”
• R8 — “Dúvida nova durante a execução: registrar em 00-BLOQUEIOS.md, pular a task e seguir para a próxima paralelizável; nunca parar e esperar.”
• R9 — “Na F1 nada de invenção: se a fonte não afirma, escreva NÃO DOCUMENTADO; todo número vem com a referência que o afirma.”
• R14 — “Na F5 a IA é auditora: só aponta, nunca corrige; achado de severidade ALTA manda voltar para a F3.”
• R15 — “Proibido escrever código de implementação em qualquer fase antes da F6.”
• R18/R19 — “Estimativa sai sempre como faixa… Número único é proibido.” / “Estimativa é esforço, nunca prazo de calendário.”

Artefatos em disco

docs/sprintx/features/<slug>/
  00-BLOQUEIOS.md  00-DECISOES.md  00-ESTIMATIVA.md
  ORQUESTRADOR.md  00-AUDITORIA.md  FECHAMENTO.md
  base/00-INDICE.md  base/00-LACUNAS.md  base/<recurso>.md
  sprint-NN/sprint.md  sprint-NN/fases.md  sprint-NN/tasks.md
docs/sprintx/estimativas/HISTORICO.md   # append-only, atravessa features
docs/eventos/<trabalho_id>.jsonl        # rastro, gitignorado

Skill · base

runx

A metade Run: ocorrências de manutenção em produção, em cinco estágios — investigação com causa raiz comprovada, plano, fix sob TDD, QA independente e relatórios de fechamento.

Os estágios

QA.md reprovado volta para o E3. E há um retorno que o disco não mostra: se no E3 o teste de regressão passar antes do fix, a ocorrência volta ao E1 — porque o que se acreditava ser a causa não era.

Os tipos de ocorrência governam o E1

Só bug exige causa raiz comprovada; os demais entram em análise de impacto.

Comandos

Hooks

Regras invioláveis

• R1 — “Nenhum plano nasce sem base/ preenchida. Mapear antes de planejar.”
• R2 — “Bug não avança de E1 sem causa raiz comprovada.”
• R5 — “O teste de regressão é escrito antes do fix e tem que falhar antes.”
• R8 — “Escopo travado: o que não está em 01-CAUSA-RAIZ.md e em tasks.md não é tocado — nada de refactor de brinde, nada de ‘já que estou aqui’.”
• R10 — “Quem implementa não aprova: E4 é papel distinto de E3, e E4 não corrige nada.”
• R13 — “Durante E3 a skill não pergunta nada. Dúvida nova vira registro em BLOQUEIOS.md e a task é pulada.”
• R15 — “Coincidência de arquivo não é regressão. O campo regressao_de só é preenchido com evidência de vínculo causal.”

Proporcionalidade: uma correção de uma linha gera 1 sprint, 1 fase e 2 tasks. “Proibido inflar o plano para parecer robusto. Proibido enxugar campos para parecer ágil.”

Skill · base

mergex

Versionamento, entrega e revisão: branch, um commit por task, portão de prontidão, descrição de PR, pacote de QA e abertura do pull request. O princípio que a governa: o revisor humano é recurso caro e finito.

As etapas

Não é uma máquina de estados sequencial: E0 e E1 acontecem durante a execução do trabalho, E2–E8 acontecem no fim, e E9 é manual e avulsa.

As três faixas de atenção humana

O E3 classifica cada arquivo do diff em exatamente uma faixa, a partir de evidência já registrada pelas outras skills — nunca de sensação.

Comandos

O /mergex-revisar nunca é encadeado a partir de nenhum fluxo nem oferecido ao fim de um trabalho: integrar código é decisão humana.

As dez verificações do portão

Regras invioláveis

• R1 — “A branch nasce com o trabalho, não no fim.”
• R3 — “Cada task concluída com suíte verde vira um commit próprio. Nunca amontoar tasks distintas.”
• R6 — “O portão de prontidão barra e explica. Nunca maquia.”
• R7 — “Nada na entrega é inventado: todo conteúdo vem de artefato existente.”
• R9 — “Zona de risco, migração de banco, mudança de contrato público e efeito irreversível são sempre OLHO OBRIGATÓRIO.”
• R11 — “Nunca push forçado, nunca na branch principal, nunca reescrever histórico já enviado.”
• R18 — “A mergex não faz merge no fluxo automático, não aprova, não publica e não faz deploy.”
• R19 — “A mergex entrega; quem fecha a ocorrência é a runx.”

Skill · camada

legadox

Camada que endurece o trabalho em projetos legados. Não acrescenta fase: muda o rigor de cada uma, proporcional ao raio de impacto da mudança. Em código legado o comportamento atual é o contrato, bugs inclusive.

O raio de impacto

Oito sinais coletados por evidência — chamadores, telas e rotas, consumo assíncrono, cobertura, zona de risco, churn e idade, migração, dado histórico. Sinal que não puder ser coletado conta como pior caso, e isso fica escrito.

O que cada faixa aciona

A camada 9 é obrigatória, independentemente da faixa, em qualquer mudança de cálculo ou de regra de negócio.

Comandos

Regras invioláveis

1. “Sem docs/legado/PERFIL.md não existe modo legado. A primeira coisa é gerá-lo.”
2. “Nenhum plano é gerado sem o raio de impacto calculado e escrito.”
3. “A faixa do raio é calculada por sinais, nunca escolhida por sensação.”
4. “Em raio MEDIO ou ALTO, nada é alterado antes de existir teste de caracterização passando no código atual.”
5. “Nenhuma melhoria colateral. O que incomoda vai para docs/legado/DIVIDA.md.”
6. “O orçamento de mudança por task não é estourado em silêncio.”
7. “Toda task de raio MEDIO ou ALTO declara como se reverte, inclusive os efeitos que o versionador não desfaz.”
8. “Zona de risco tocada obriga as perguntas da zona respondidas antes do plano.”
9. “Raio ALTO obriga aprovação humana explícita e registrada.”
10. “Código morto identificado não é removido: vira achado.”
11. “Dado real usado em comparação é anonimizado e nunca é commitado.”
12. “O legadox não substitui a sprintx nem a runx: ele os endurece.”

Artefatos em disco

docs/legado/PERFIL.md                    # C1 — gatilho do modo legado
docs/legado/LACUNAS.md
docs/legado/DIVIDA.md                    # C6 — append-only
docs/legado/raio/<trabalho_id>.md        # C2
docs/legado/manual/<trabalho_id>.md      # C8
docs/legado/comparacao/<trabalho_id>.md  # C9

Skill · camada

stackx

Descobre o dialeto técnico do repositório — onde os testes moram, como o banco é isolado, quais comandos funcionam de verdade, quem pode chamar quem — e grava tudo com evidência. Convenção não se propõe, se descobre.

As etapas

A ordem da detecção

Não é arbitrária: vai do que declara a intenção para o que revela a prática.

1. manifestos e locks
2. configuração de runner, lint, formatador, type checker e build
3. os testes que já existem — a fonte mais rica
4. migrações e schema
5. scripts dos manifestos
6. integração contínua
7. arquivos de ambiente de exemplo
8. o próprio código

Os três cartuchos

Um cartucho só existe quando o assunto é, ao mesmo tempo, não óbvio, específico de versão ou engine e caro de errar.

Comandos

Regras invioláveis

1. “Toda convenção aponta um arquivo real do repositório que a exemplifica, com caminho e linha.”
2. “Convenção sem evidência no código não é convenção: é PROPOSTA, e é marcada como tal.”
3. “PROPOSTA não governa. Nas outras skills ela vira decisão a levantar, nunca regra a obedecer.”
4. “Diante de dialetos conflitantes, o stackx não escolhe sozinho: apresenta os dialetos com contagem e histórico, e pergunta.”
5. “Comando declarado precisa ter sido encontrado em manifesto, script ou integração contínua. Comando nunca é inferido do nome do framework.”
6. “Em projeto legado, na área tocada manda o PERFIL.md do legadox. O stackx governa apenas código novo em arquivo novo.”
7. “Atualização de convenção nunca sobrescreve em silêncio: apresenta diff e espera confirmação.”
8. “A verificação de aderência aponta, não corrige.”
9. “Cartucho não repete o que o modelo já sabe. Se virou tutorial de sintaxe, foi escrito errado.”
10. “Nenhum segredo, credencial ou dado real de cliente entra em CONVENCOES.md, exemplo ou template.”

O formato obrigatório da evidência é literal:

Evidência: src/users/create-user.test.ts:14, src/orders/place-order.test.ts:9

Skill · camada

memox

Indexa o que as outras skills já gravaram e responde o que se sabe sobre um arquivo antes de alguém mexer nele. Memória que precisa ser consultada não é usada — por isso ela se injeta sozinha no contexto.

Índice invertido, não busca semântica

A pergunta real não é “o que é parecido com isto”, é “quem já mexeu neste arquivo e por quê” — e isso é uma string exata. Resposta de índice aponta artefato e data, então dá para abrir e conferir; recuperação semântica erra em silêncio, devolvendo algo plausível com a mesma confiança do certo.

O que ele indexa

Regressão exige evidência causal, não coincidência

Um vínculo só é registrado como regressão quando as três condições valem juntas: um arquivo apontado pela causa raiz do trabalho posterior está entre os que o anterior alterou; a ordem cronológica está estabelecida; e a causa do posterior é comprovada, não hipótese. Faltando qualquer uma, o vínculo aparece como coincidencia_arquivo com o motivo escrito — é isso que impede o sinal mais valioso do índice de virar ruído.

Comandos

Os dois hooks falham abertos

Contrato dos dois: silencioso quando não há nada relevante; sai com 0 sempre, inclusive em erro; abaixo de 200 ms; sem rede e sem modelo.

Controle de ruído

No máximo 3 entradas recentes por arquivo, mais as que envolveram regressão, reprovação em QA ou zona de risco. Acima de 8 entradas relevantes ele não lista: informa a contagem. Tudo configurável em .expx/memoria/config.json.

python3 .claude/skills/memox/assets/memox.py indexar

O índice fica em .expx/memoria/indice.json, é local e gitignorado, e se reconstrói do zero a qualquer momento. Um clone recém-feito não tem nenhum — esse é o caso comum, não um erro.

Skill · camada

prodx

Recebe o pedido cru, tria, verifica se o que foi pedido já existe e emite um veredito com evidência para assinatura humana. O cliente pede solução, não problema.

Os estágios

Os oito gatilhos da triagem

Nenhum gatilho disparado: veredito direto, uma linha no índice, segue para a runx. Um ou mais: avaliação completa, de P2 a P5.

Os quatro vereditos

O VEREDITO.md traz sempre um campo de assinatura humana, preenchido pela pessoa, nunca pela skill.

Comandos

Regras invioláveis

1. “A skill não decide. Ela recomenda com evidência; humano assina.”
2. “Nenhum trabalho segue para sprintx ou runx sem veredito assinado.”
3. “A triagem nunca é pulada, e a avaliação completa nunca roda em pedido sem gatilho disparado.”
4. “A solução pedida nunca é tratada como o requisito. O requisito é o problema.”
5. “A verificação de existência é obrigatória e vem com evidência: tela, rota, arquivo ou relatório. ‘Acho que já tem’ não é resposta.”
6. “Escopo mínimo é campo obrigatório e nunca fica vazio.”
7. “Pedido rotulado como bug é verificado contra comportamento intencional antes de virar ocorrência.”
8. “Informação que falta vira pergunta, nunca suposição.”
9. “Pedido recusado não é apagado: a avaliação é ativo permanente.”
10. “O briefing não contém decisão técnica.”
11. “Nada de invenção no PRODUTO.md. O não verificável vira NAO DETERMINADO.”
12. “O campo de quem assina nunca fica vazio.”

Skill · orquestração

buildx

Recebe a descrição de um projeto inteiro em linguagem natural, faz uma única pergunta, e conduz as outras skills até o sistema estar construído, testado e validado. Uma descrição entra, um sistema sai.

A pergunta única

É a primeira coisa que acontece, antes de qualquer arquivo:

Relatar progresso não é perguntar: nos dois modos o usuário vê onde a cadeia está, sem precisar responder nada.

As seis etapas

O ciclo B4 → B5 repete enquanto houver pendência que a máquina resolve, com teto de três ciclos. O ciclo 2 resolve o que o B3 recortou mal; o 3 resolve o que o 2 criou. Do quarto em diante o que sobra normalmente não é falta de trabalho, é falta de decisão.

O que ela descobre que você não pediu

A varredura do B1 é a razão de a buildx existir em vez de você falar direto com a sprintx. Trinta e um eixos, percorridos sempre — cada um sai como pedido, descoberto ou descartado com o porquê registrado. Nenhum é pulado em silêncio.

Toda decisão fica auditável

Cada escolha feita em nome do usuário vira uma premissa com cinco campos, e o quinto é o que importa:

PR-07 — Autorização por papéis

Decisão:  papéis admin e usuario desde a primeira feature,
          verificados no servidor.
Por quê:  o sistema tem dado de mais de um usuário; sem papel,
          qualquer conta alcança o dado de qualquer outra.
O que
invalida: se todo usuário tiver exatamente o mesmo acesso aos
          mesmos dados, de forma permanente.

Como revisar vinte e três decisões em cinco minutos: leia só o campo o que invalida. Se aquilo é verdade no seu caso, a premissa merece atenção. Se não é, siga.

A fronteira que ela não atravessa

O que ela quebra de propósito

O modo autônomo viola regras que existem por bons motivos nas irmãs. Cada violação é restrita ao modo e registrada no artefato que ela toca.

Os padrões da casa

O que a buildx assume quando o usuário não diz nada. O usuário sempre ganha do padrão.

Comandos

Artefatos em disco

docs/projeto/
  PROJETO.md      o escopo: o pedido, o descoberto, o descartado
  PREMISSAS.md    toda decisão tomada em nome do humano
  MAPA.md         as features, em ordem de dependência
  RECURSAO.md     pendências por ciclo, e o teto
  VALIDACAO.md    a conferência final
  RELATORIO.md    o que o usuário lê no fim

São os únicos artefatos do método que descrevem um projeto e não um trabalho: usam projeto_id no lugar de trabalho_id. A ponte entre os dois níveis são as chaves origem_buildx e feature_id, que a cadeia acrescenta ao artefato de cada feature — é o que permite abrir um plano de sprint qualquer e saber de qual projeto ele veio.

O que o usuário lê no fim

1. O QUE VOCÊ PRECISA DECIDIR       as regras de negócio não declaradas
2. O QUE VOCÊ PRECISA PROVIDENCIAR  credenciais, acessos, contas
3. O QUE FOI DECIDIDO POR VOCÊ      as premissas, com o que invalida cada uma
4. O QUE FICOU PRONTO               features entregues, com os PRs
5. O QUE NÃO FICOU                  pendências, com o porquê
6. COMO RODAR                       instalar, subir, entrar com o usuário demo
7. O QUE FAZER AGORA                revisar os PRs e fazer merge

A ordem é deliberada: o que exige ação vem antes do que foi feito. Um relatório que abre com onze features entregues e esconde na página três que a regra de cálculo foi chutada é desonesto na estrutura, mesmo dizendo tudo.

Regras invioláveis

1. “Uma única pergunta ao usuário: o modo. No autônomo, nenhuma outra chega a ele, de nenhuma camada.”
2. “Toda decisão tomada no lugar do humano é registrada em PREMISSAS.md antes de ser usada, com o que a invalidaria.”
3. “A buildx não implementa, não planeja e não testa. Ela invoca a camada dona e verifica a saída.”
4. “Bloqueio nunca para o laço: registra, marca a feature, segue para a próxima.”
5. “O ciclo B4 → B5 tem teto declarado. Atingido, para e reporta.”
6. “Nenhuma feature entra no mapa sem entrega verificável e dependências explícitas.”
7. “Feature de fundação vem primeiro; nenhuma feature precede aquilo de que depende.”
8. “Merge é humano. Nunca invoca mergex-revisar, nem oferece.”
9. “O que não for derivável do projeto, das premissas ou das convenções vira premissa nova — nunca invenção silenciosa.”
10. “Todo artefato usa o frontmatter expx-schema v1.”
11. “Caminhos sempre relativos.”
12. “O relatório final declara toda pendência.”

Referência do CLI

Subcomandos

Sete subcomandos. O panel e o watch funcionam sem init: nenhum dos dois escreve no projeto.

O pacote publica três binários: expx e expxdev (o mesmo programa) e expx-painel, que sobe o painel direto.

init

expx init [--skills a,b] [--harness claude,opencode] [--yes]

Sem --skills e com terminal interativo, abre o assistente. Sem --yes e sem TTY, imprime o que instalaria e sai sem escrever. Uma skill que falha não derruba as outras: o erro dela é reportado nominalmente e o init segue com as demais.

add e remove

expx add memox prodx
expx remove legadox

Os dois leem o lock, ajustam a seleção e remontam o plugin do zero com o mesmo harness já registrado. Sem instalação válida, o CLI orienta a rodar o init. Remover a última skill é recusado: uma instalação vazia não é estado válido.

update

doctor

Não aceita flags. Sai com 0 quando não há nenhum achado de severidade erro — ou seja, só avisos ainda sai 0, mas a lista é impressa.

panel e watch

Os dois aceitam --ajuda, --help ou -h, e a forma --flag=valor.

Referência do CLI

Anatomia do init

O que roda, em que ordem, e por quê.

Para cada skill selecionada

1. Resolve a versão alvo

   Busca a maior tag de versão semântica do repositório — comparando número a número, porque ordenar como texto colocaria v1.10.0 antes de v1.2.0. Pré-lançamento (-rc.1) é ignorado: não é versão publicada. Sem nenhuma tag, cai para a branch padrão e registra travado: false no lock.

2. Busca o conteúdo

   Com git clone --depth 1 --branch <referência>, usando o git do sistema. É de propósito: assim aproveita a credencial já configurada na máquina e não esbarra em limite de requisição de API.

3. Detecta o layout

   Os repositórios não têm todos a mesma forma. O CLI não assume caminho: procura o SKILL.md mais raso e adota a pasta dele como raiz, depois confere que o name: do frontmatter é mesmo a skill pedida. Um layout novo passa a funcionar sem tocar nesta camada.

4. Verifica os caminhos

   Recusa qualquer skill que referencie caminho fora da própria pasta. A mensagem traz até três achados, no formato arquivo:linha → referência.

5. Calcula o hash de cada arquivo

   SHA-256 por arquivo, registrado no lock junto com repositório, referência, commit e a data de resolução.

Só depois é que a escrita acontece

E ela é atômica: a montagem inteira ocorre numa pasta temporária ao lado do destino — não em /tmp, porque rename só é atômico dentro do mesmo sistema de arquivos — e é trocada por rename ao final. Se falhar no meio, o .expx/ anterior é devolvido ao lugar e permanece intacto.

A configuração do harness

A configuração do Claude Code é mesclada, nunca reescrita: backup datado antes de qualquer alteração, todo o resto preservado, e recusa explícita de “consertar” JSON inválido — nesse caso o arquivo não é tocado e o init emite um aviso.

Duas particularidades medidas em execução, não presumidas:

• A lista de plugins habilitados é lida nos dois formatos — o array documentado e o objeto que o Claude Code realmente escreve — e sempre gravada como objeto.
• Os hooks só entram na configuração se houver hooks. Um projeto sem skill com hook não ganha uma seção vazia do nada. E a entrada é deduplicada pelo comando, porque o init roda de novo a cada atualização e a duplicata faria o hook rodar duas vezes por prompt.

Hooks no disco

Quando alguma skill traz hook, o CLI copia a skill inteira para .claude/skills/<nome>/ e o script para .claude/hooks/, com chmod 0755 — sem o bit de execução o hook não roda e não avisa. A skill vai junto porque o hook resolve o próprio motor como um caminho relativo a si mesmo.

Claude Code e OpenCode lado a lado

As skills vão somente para .claude/skills/, que o OpenCode lê nativamente. Copiar também para .opencode/skills/ criaria dois name iguais nas pastas que o OpenCode varre, e a duplicata é resolvida por último-a-escrever-vence com apenas um aviso no log — silenciosamente. É exatamente essa colisão que o doctor detecta.

Referência do CLI

/expx:onboarding

A primeira coisa a rodar depois do init. Sem ela, cada camada instalada roda em modo degradado na primeira vez que alguém a usa — e essa lacuna só aparece no meio de um plano, quando já custou tempo.

/expx:onboarding

Comando fixo do plugin, não de uma skill

Nenhuma camada é dona do onboarding — ele só orquestra as que já existem. Por isso ele mora em nucleo/commands/onboarding.md deste repositório, e viaja sempre para commands/ na raiz de todo plugin montado, junto com as skills selecionadas — do mesmo jeito que o resto do nucleo/ viaja por cópia. Está disponível mesmo que você não tenha escolhido nenhuma camada de mapeamento: nesse caso ele avisa, em uma linha, que não há nada para orquestrar.

Ele nunca reimplementa o critério de detecção de nenhuma camada — só lê o artefato que cada uma produz e chama o comando de verdade.

O que ele faz, em ordem

1. Descobre o que está instalado

   Entre as cinco camadas que produzem mapeamento inicial. runx, sprintx, mergex e buildx nunca entram nesta lista — elas só consomem o que essas cinco geram.

2. Verifica o que já foi mapeado

   Pela presença do artefato de cada camada. Camada já mapeada nunca é sobrescrita — redetecção é trabalho de cada uma (/stackx-atualizar e equivalentes), não deste comando.

3. Monta a fila só com o que é pendente

   Na ordem de dependência: prodx → stackx → designx → legadox → memox. designx só entra com sinal de UI no projeto; stackx só com sinal de código de verdade; legadox pergunta uma vez — legado é decisão de quem conhece o projeto, nenhuma evidência de código prova isso sozinha.

4. Executa uma camada de cada vez

   Nunca em paralelo: uma pode se apoiar no que a anterior deixou (designx referencia stackx, por exemplo). Camada que falha é registrada e não derruba as outras.

5. Fecha com uma tabela-resumo

   Instalada, estado antes, ação tomada, artefato gerado — e uma linha final dizendo o que mudou.

O gatilho de cada camada

Referência do CLI

Lock e atualização

A instalação é travada por lock; a atualização é um ato explícito. Quem clona o projeto recebe exatamente as mesmas skills que o time está usando, sem rede e sem rodar nada.

O formato do lock

{
  "lock_version": 1,
  "cli_version": "0.5.0",
  "harness": ["claude"],
  "skills": {
    "sprintx": {
      "repositorio":  "https://github.com/bittencourtthulio/sprintx",
      "referencia":   "main",
      "travado":      false,
      "commit":       "4e3570c9bb19b8e336a5ca9c22ea17e7394dc6e8",
      "resolvido_em": "2026-08-29",
      "arquivos": {
        "SKILL.md": "e3b0c442…b855"
      }
    }
  }
}

travado: false significa que a skill segue uma branch, e não uma tag publicada — é o estado atual de todas as oito, porque nenhum dos repositórios publica tag ainda. O doctor reporta isso como aviso, nunca como erro.

O que o update faz

1. Descobre a versão alvo de cada skill instalada
2. Compara com o lock — skill já em dia é reportada e não é tocada
3. Detecta modificação local: se os arquivos divergirem do lock, não sobrescreve
4. Mostra o resumo por skill: versão atual, versão nova, e os títulos dos commits entre as duas
5. Pede confirmação e aplica
6. Remonta o plugin do zero, reescreve o lock e valida

A aplicação remonta o plugin do zero com a seleção inteira do lock, em vez de editar a árvore montada. É mais lento e é de propósito: editar no lugar deixa arquivo órfão quando uma skill encolhe entre versões.

O que conta como modificação local

A comparação do disco contra os hashes do lock produz três listas — alterados, removidos e novos. A instalação só é considerada limpa quando as três estão vazias.

Rollback

Como o .expx/ é commitado, desfazer uma atualização é revertê-lo pelo versionador. O update imprime isso em toda execução que aplica:

git checkout -- .expx

Não existe comando de desfazer no CLI, e é uma decisão: guardar a versão anterior dentro do .expx/ duplicaria no repositório aquilo que o versionador já guarda melhor.

Referência do CLI

O que o doctor verifica

Dezesseis verificações, cada uma com severidade e correção sugerida. Achado de severidade aviso não derruba a saída; erro sim.

npx expxdev doctor

[erro] a skill memox tem hook instalado mas nao tem o motor ao lado
  correcao: rode expx init novamente para reinstalar a skill memox

[aviso] a skill sprintx nao esta travada em versao publicada
  correcao: nenhuma acao necessaria; o repositorio ainda nao publica tag

Referência do CLI

O painel

Lê a pasta docs/, descobre os trabalhos gravados pelas skills e mostra no navegador o que foi planejado, o que está em execução, o que travou e o histórico do que já foi entregue.

npx expxdev panel

Como ele lê o projeto

O que ele reconhece

O painel não varre todo .md do projeto: procura os nomes de arquivo do contrato. A razão é que muitos .md legítimos não têm frontmatter — 00-LACUNAS.md e 00-AUDITORIA.md, por contrato, não levam — e varrer por extensão encheria a tela de “fora do schema” com ruído.

Um trabalho é uma pasta com ORQUESTRADOR.md de frontmatter válido — a regra é sobre o conteúdo, não sobre o caminho. Pasta sem orquestrador é ignorada em silêncio. O 00-INDICE.md só conta quando está dentro de uma pasta base/.

Violação e rejeição são coisas diferentes

A distinção importa e tem duas telas separadas:

As dez regras de conformidade

Cada regra tem escopo estreito de propósito, porque violação falsa é pior que violação ausente: regressão não é cobrada de trabalho da sprintx nem de ocorrência que não é bug, e critério de saída não é exigido de fase que não o declara por não existir.

Os seis motivos de rejeição

A API

O websocket manda o estado inteiro, não um delta: o estado de um projeto documental é pequeno, e mandar tudo elimina a classe de bug em que servidor e tela discordam depois de uma mensagem perdida. Conexão caída fica visível na barra de status e reconecta sozinha — uma tela congelada mostrando dado velho é pior que um erro à mostra.

As telas

Toda tela exporta CSV. Um filtro de período global — 7d, 30d, 90d, mês, ano ou intervalo — recorta trabalhos, histórico, bloqueios e violações; data ausente nunca é filtrada para fora.

Por que o quadro kanban foi removido

O kanban pressupõe cartões movendo-se entre colunas por decisão de pessoas. Aqui o estágio é a máquina de estados do método: ele avança quando um artefato passa a existir no disco, não quando alguém arrasta um cartão. A tabela conta essa verdade; o quadro contava outra.

A tela de Memória não respeita o filtro de período

Ao contrário das demais, e de propósito: o valor do sinal é justamente o antigo. Um arquivo que regrediu há dois anos continua sendo um arquivo que regride. Os arquivos de risco são ordenados por regressões, depois reprovações de QA, depois número de trabalhos — nunca por movimento, porque um arquivo central é tocado por dezenas de trabalhos sem nunca ter falhado, e ordenar por contagem o colocaria no topo, enterrando embaixo o arquivo que já quebrou duas vezes.

Referência do CLI

O watch

Acompanha um trabalho no terminal, ao vivo, sem sair do lugar onde você está trabalhando. Como o painel, ele nunca escreve nos arquivos do projeto.

2 bloqueios abertos
  B-01 · T-02.03 · 3 dias · Falta o contrato do gateway de pagamento
  B-02 · sem task · hoje · Ambiente de homologacao fora do ar

OC-2026-0142 · runx · Arredondamento na faixa de peso
  e3 · 7/11 tasks · agora T-02.04
  raio medio · arquivos 2/3 · linhas 31/80
  fix/OC-2026-0142-arredondamento · pr aberto

[x] sprint-01 · Congelar o comportamento atual
  [x] F-01.1 · Caracterizacao
    [x] T-01.01 Teste de caracterizacao da faixa 0-5kg
    [x] T-01.02 Teste de caracterizacao da faixa 5-30kg
[>] sprint-02 · Corrigir o arredondamento
  [>] F-02.1 · Fix
    [x] T-02.01 Teste de regressao que reproduz o bug
    [x] T-02.02 Corrigir a funcao de arredondamento
    [!] T-02.03 Integrar com o gateway ← T-02.02
    [>] T-02.04 Atualizar o relatorio de fechamento <
    [ ] T-02.05 Revisar a documentacao de uso ||

eventos recentes
  14:32 task_concluida T-02.02 · suite verde, 14 testes
  14:28  suite_executada T-02.02 · 14 passed
  14:11 regra_violada T-02.02 escopo-da-task · arquivo fora do plano

ultimo evento há 3 min · 1 violacao em aviso

Uso

Sai com Ctrl+C, devolvendo o terminal ao estado anterior — cursor restaurado inclusive em encerramento por exceção.

Como ele escolhe o trabalho

A precedência é deliberada, e cada degrau existe para um caso real:

1. o id que você pediu na linha de comando
2. o trabalho do estado.json, se ele existir no disco observado — apontar para uma pasta apagada ou de outro repositório não trava o watch
3. entre os trabalhos em_andamento, o mais recente por atualizado_em
4. sem nenhum em andamento: o mais recente entre os abertos
5. nada aberto: o mais recente entre todos, inclusive concluídos

Três gatilhos, três custos

O watch não relê tudo a cada mudança. Ele separa o que mudou:

O rastro é lido pela cauda — só os últimos 64 KB, em linhas completas, descartando o fragmento cortado ao meio. O arquivo só rotaciona em 5 MB, e reler tudo a cada evento seria a chamada cara que a especificação proíbe.

O desenho

Bloqueio aberto sobe ao topo, acima até do cabeçalho. A ordem das seções é fixa: bloqueios, cabeçalho, árvore, eventos, rodapé.

A tela é redesenhada de forma incremental: as linhas anteriores são guardadas, comparadas, e só as que mudaram são reescritas. Se nada mudou, nada é escrito — por isso não pisca. O buffer alternativo do terminal foi descartado de propósito: ele apagaria o que estava na tela quando o watch sai.

São dois vocabulários porque os enums do contrato são mesmo diferentes para task e para grupo — e não são intercambiáveis. Além das marcas, || indica task paralelizável, ← lista as dependências e < aponta a task em foco.

Contratos

Convenções R1–R14

O documento raiz. Estas regras valem para todo artefato do método: frontmatter YAML, linha do rastro, configuração de hook, frontmatter de agente. Os contratos derivados não as repetem — citam por número.

R12 — os formatos de id

F-01 sozinho é forma antiga e não deve ser gerada.

R4 na prática

Modelo de linguagem não sabe que dia é hoje. Data escrita de memória é o erro mais comum e o mais silencioso do método:

date +%Y-%m-%d                  # data
date -u +%Y-%m-%dT%H:%M:%SZ     # timestamp do rastro

Contratos

expx-schema v1

O frontmatter YAML de todo arquivo de estado. As skills escrevem; o painel lê e nunca escreve. É a fonte da verdade sobre os kind, seus campos e seus enums quando skill e leitor divergirem.

O cabeçalho comum

Todo arquivo carrega estas quatro chaves antes das específicas:

---
expx_schema: 1
expx_tool: sprintx        # sprintx | runx — quem escreveu
kind: tasks
trabalho_id: exportacao-csv-relatorios
---

trabalho_id é o slug da feature (sprintx) ou o ID da ocorrência (runx). É a chave que costura tudo — um trabalho, um nome, do plano até a entrega. O único kind que não o carrega é o relatorios_indice, que é do projeto inteiro e não de um trabalho.

Os treze kinds

A anatomia de uma task

---
expx_schema: 1
expx_tool: runx
kind: tasks
trabalho_id: OC-2026-0142
sprint_id: sprint-01
atualizado_em: 2026-08-29
tasks:
  - id: T-01.02
    titulo: Corrigir o arredondamento na faixa de peso
    fase: F-01.1
    status: concluida
    objetivo: Fazer o calculo usar duas casas em vez de truncar
    arquivos:
      cria: []
      altera: [src/frete/calculo.ts]
    teste_regressao: test/frete/calculo.regressao.test.ts
    teste_integracao: test/frete/calculo.int.test.ts
    teste_funcional: test/frete/cotacao.func.test.ts
    criterio_aceite: O teste falha antes do fix e passa depois
    depende_de: [T-01.01]
    paralelizavel: false
    concluida_em: 2026-08-29
    suite: verde
---

O campo fase da task é o vínculo autoritativo entre task e fase — não a lista tasks[] da fase. Quando as duas discordam, vale o que a task diz.

arquivos aceita duas formas: o mapa {cria, altera} que as duas skills gravam, e a lista plana que o contrato descrevia. A lista plana é normalizada para o mapa na leitura.

Os enums

Onde o painel procura

Contratos

expx-eventos v1

O rastro append-only, e o comportamento de hooks e agentes. O estado responde “onde está”; o rastro responde “o que aconteceu e quando”.

A linha do rastro

Uma linha JSON por evento, em docs/eventos/<trabalho_id>.jsonl. Escrito por hooks e pelas skills nas transições de fase; ninguém edita à mão.

{"ts":"2026-08-29T14:32:10Z","expx_eventos":1,"trabalho_id":"OC-2026-0142",
 "ferramenta":"runx","origem":"hook","evento":"task_concluida","fase":"e3",
 "task":"T-01.02","agente":"principal","resultado":"ok",
 "detalhe":"suite verde, 14 testes","arquivos":["src/frete/calculo.ts"]}

As doze chaves são obrigatórias, nesta ordem, e nenhuma é omitida — por R6, o que não se aplica vai null, e arquivos vazio vai []:

Duas chaves extras são permitidas depois das doze: hook (o nome do hook que decidiu, quando a origem é hook) e faixa (a faixa de atenção do arquivo tocado).

O vocabulário de eventos

O campo agente nunca é null: quando não há subagente, o valor é principal.

Como os hooks funcionam

As sete regras que todo hook obedece

1. Rápido — acima de 200 ms o desenvolvedor sente
2. Silencioso quando passa — hook que fala sempre vira ruído e é ignorado
3. Falha aberta, exceto os de segurança
4. Sem rede
5. Mensagem acionável — dizer o que fazer, não só o que está errado
6. Sem estado próprio — o disco já é o estado
7. Sempre grava no rastro, inclusive quando permite

Versionamento e rotação

O rastro é ignorado pelo versionador por padrão. Acima de 5 MB o arquivo vira <trabalho_id>.1.jsonl e um novo começa; os leitores leem os dois.

Contratos

expx-estado v1

Um arquivo minúsculo em .expx/estado.json, lido pela barra de status e pelo expx watch. Derivado e descartável: apagá-lo não pode quebrar nada.

Os quinze campos

{
  "expx_estado": 1,
  "atualizado_em": "2026-08-29T14:32:10Z",
  "trabalho": "OC-2026-0142",
  "ferramenta": "runx",
  "titulo_curto": "Arredondamento na faixa",
  "fase": "e3",
  "task": "T-02.04",
  "tasks_concluidas": 7,
  "tasks_total": 11,
  "raio": "medio",
  "orcamento_arquivos": "2/3",
  "orcamento_linhas": "31/80",
  "branch": "fix/OC-2026-0142-arredondamento",
  "pr_estado": "aberto",
  "bloqueios": 2
}

Quem escreve o quê

Cada dono atualiza apenas os seus campos: ler, alterar o que é seu, gravar — nunca sobrescrever o arquivo inteiro.

As sete regras

1. Somente exibição — derivado e descartável; apagá-lo não pode quebrar nada
2. Chave nunca omitida — o que não se aplica vai null: raio fora do modo legado, pr_estado antes do push
3. Escrita atômica — temporário mais rename
4. Pequeno — abaixo de 1 KB, nada de listas
5. titulo_curto cabe em 30 caracteres — corte, não quebre linha
6. Sem trabalho aberto, trabalho, fase e task viram null e o arquivo continua existindo
7. Enums iguais aos do expx-schema — e3, não E3; alto, não ALTO

A barra de status é mecanismo do Claude Code. O OpenCode tem o seu, com formato possivelmente diferente — isso é lacuna a verificar, não paridade garantida.

Interno

Arquitetura

Camadas isoladas, uma pasta por responsabilidade. Nenhuma regra de negócio vive no código de linha de comando.

src/
  nucleo/     catálogo das skills, resolução de versão, busca, layout, lock, integridade
  plugin/     montagem do plugin e dos manifestos, com escrita atômica
  harness/    Claude Code e OpenCode, merge de configuração, backup
  doctor/     os verificadores e o efeito de cada achado
  update/     comparação com o lock, modificação local, compatibilidade de schema
  parser/     leitura do expx-schema e do índice da memox, com falha aberta
  servidor/   o painel: HTTP, websocket e o observador de arquivos
  watch/      o watch: fontes, visão, desenho puro e terminal
  cli/        roteamento de subcomando, flags e seleção interativa
ui/           a interface do painel (React + Vite)
docs/contrato/  os contratos compartilhados pelas oito skills

Padrões que atravessam o código

Escrita atômica em toda parte

O .expx/ é montado numa pasta temporária ao lado do destino e trocado por rename. O .expx/estado.json segue a mesma regra. Nunca há um estado intermediário visível no disco.

Falha aberta onde a ausência é normal

A leitura do índice da memox devolve null em quatro casos, e nenhum deles é erro: arquivo ausente (o índice é gitignorado — é o caso comum num clone novo), JSON inválido (o motor reescreve o arquivo inteiro, e ler no instante da gravação devolve truncado), raiz que não é objeto, e versão desconhecida. Degradar mostrando, nunca quebrar.

Dois observadores de arquivo, deliberadamente diferentes

O painel ignora o .expx/ porque é lá que a memox grava o índice: sem ignorá-lo, reindexar dispararia o observador, que recarregaria o estado, que releria o índice — realimentação sem dado novo nenhum. O watch, ao contrário, precisa do estado.json; e observa a pasta, não o arquivo, porque a escrita atômica substitui o inode e um observador preso ao arquivo antigo pararia de ver mudança depois da primeira.

O debounce não é conforto, é correção

As skills gravam tasks.md a cada transição de task. Ler no instante da gravação produz YAML truncado — uma rejeição transitória que apareceria e sumiria da tela “fora do schema”, assustando sem motivo.

Frontmatter lido com posição de linha

O leitor de YAML foi escolhido por dar a linha de cada campo — é o que permite ao painel dizer onde está o problema. A biblioteca mais comum para frontmatter foi descartada por dois motivos medidos: não dá posição, e mantém um cache global indexado pelo conteúdo, de modo que a segunda leitura da mesma string com YAML inválido devolvia dados vazios em silêncio.

Cor ANSI escrita à mão

Os pacotes de cor presentes em node_modules são dependências transitivas de ferramentas de desenvolvimento, e somem na instalação de produção. Seis papéis semânticos — sucesso, atenção, erro, destaque, apagado e neutro — cobrem tudo o que o watch precisa.

Largura contada em code points, com normalização

Nome de arquivo vindo do macOS chega decomposto, e contar caracteres como o JavaScript conta por padrão erraria o corte em 80 colunas. A limitação conhecida: caractere de largura dupla conta como uma coluna — aceitável porque a especificação proíbe emoji e a prosa é em português.

Interno

Decisões de arquitetura

Este projeto foi planejado e executado com o próprio método. Estas são algumas das decisões registradas, com a alternativa que foi descartada e o motivo — o formato do kind: decisoes.

O plano completo, a base de conhecimento e as decisões deste projeto vivem em docs/expx-cli/, e a integração da memória em docs/memox-painel/.

Interno

Desenvolvimento

npm install
npm test          # 441 testes em 92 arquivos, sem acesso à rede
npm run typecheck
npm run build

TypeScript estrito e ESM, Node ≥ 20.19, com o runner dividido em três projetos — servidor, ui e cli. A suíte roda contra repositórios git locais criados em tempo de teste: nenhum teste depende de rede nem do estado do GitHub.

Segurança e limites

• Nunca pede nem armazena credencial. Repositório privado usa a credencial de git já configurada na máquina
• Nunca escreve fora da raiz do projeto
• Nunca escreve uma skill. O CLI busca e empacota; jamais edita conteúdo de skill
• Escrita atômica. Se falhar no meio, o .expx/ anterior permanece intacto
• O painel e o watch são somente leitura, e o painel escuta apenas em 127.0.0.1
• Toda escrita destrutiva pede confirmação, com flag para pular em ambiente não interativo

Divergências conhecidas entre código e contrato

Registradas aqui porque quem for implementar um leitor precisa saber:

Licença

MIT.