🧱 Instalar o núcleo portátil
Você já tem AGENTS.md portátil (módulo 2.2). Agora entra a estrutura que carrega o contexto: context/, tasks/, handoffs/. Um script copia o esqueleto sem sobrescrever nada, você preenche com fatos datados, e um teste em clone isolado prova que o projeto funciona sozinho.
🧱 init-core.sh: criado vs mantido
O núcleo portátil é a pasta-esqueleto que o kit chama de template/: AGENTS.md, CLAUDE.md, README.md, context/, tasks/, handoffs/, .agents/skills/ e scripts/check.sh. O script init-core.sh copia esse esqueleto para o seu projeto com uma regra única: nunca sobrescreve o que já existe. Cada arquivo sai marcado como [criado] ou [mantido].
A caixa grande é o seu projeto. Os arquivos azuis são instrução e leitura humana; as pastas ciano guardam o conteúdo que viaja entre runtimes. Esses nomes são convenção do kit, nenhum runtime os carrega sozinho: é o AGENTS.md que manda ler.
💻 Exemplo copy-run: instalar o núcleo
Objetivo: copiar o esqueleto para um projeto seu sem tocar em nada que já exista.
cd ~/projetos/agente-claude-codex
scripts/init-core.sh ~/projetos/<seu-projeto>Como verificar: a saída lista cada arquivo com um dos dois rótulos. Num projeto que já tinha README e CLAUDE.md, o resultado esperado é parecido com este:
[criado] AGENTS.md
[mantido] CLAUDE.md
[mantido] README.md
[criado] context/overview.md
[criado] context/current-state.md
[criado] context/sources.md
[criado] context/decisions/0000-00-00-modelo.md
[criado] tasks/current.md
[criado] handoffs/latest.md
[criado] .agents/skills/.gitkeep
[criado] scripts/check.sh
Agora preencha: ~/projetos/<seu-projeto>/AGENTS.md, context/overview.md, tasks/current.mdPor que "mantido" importa: a primeira versão do kit sugeria cp -r template/. projeto/, que apagaria o README e o CLAUDE.md reais de um projeto. O script nasceu para fechar exatamente esse buraco. Cada passo do kit precisa ser reversível, e sobrescrever não é.
Conceitos-chave
O conjunto mínimo de arquivos que faz um projeto ser entendido por qualquer runtime.
A fonte do esqueleto, dentro do kit.
O contrato do script: cria o que falta, respeita o que existe.
Os nomes só funcionam porque o AGENTS.md manda lê-los.
📅 Preencher overview.md com fatos datados
O esqueleto está lá, mas vazio. O primeiro arquivo a preencher é context/overview.md: o que o projeto é, para quem, e os fatos verificados. Cada fato leva fonte e data, porque um agente que lê "o servidor roda na porta 8000" precisa saber se isso era verdade ontem ou há um ano. O template já traz o cabeçalho com ID, escopo, fonte, data de observação, status e "revisar em".
✓ Fato bem escrito
- ✓"Codex CLI 0.154.0 não tem comando
import; o import um clique é só no app desktop." (fonte:codex --help, 2026-09-13) - ✓"MCP no Claude: magnific, metricool. No Codex: nenhum." (fonte: audit.sh, 2026-09-13)
- ✓Seção separada para "Hipóteses (não verificadas)": "a classificação heurística de 71 skills está correta na maioria".
✗ Fato que vai enganar o agente
- ✗"O Codex tem import." Sem data nem fonte, e já era falso no CLI.
- ✗"Prefiro flux2-klein" misturado com fatos técnicos: preferência disfarçada de fato.
- ✗Copiar os 869 arquivos da memória do Claude para dentro do overview. Isso é matéria-prima, não fonte.
📄 O overview real do kit (resumido)
# Overview — agente-claude-codex
- ID: overview | Escopo: este repo | Fonte: docs/ (3 textos + PDF) e auditoria local
- Data: 2026-09-13 | Status: aceito | Revisar: ao mudar versão do Codex ou do Claude Code
## O que é
Kit de migração/agnosticismo: scripts de auditoria e adaptação + template de núcleo portátil.
## Fatos verificados (2026-09-13)
- Codex CLI 0.154.0 não tem comando `import`; o import "um clique" é do app desktop.
- Claude Code 2.1.270 com 116 skills; Codex com 27.
- MCP no Claude: magnific, metricool. No Codex: nenhum.
## Hipóteses (não verificadas)
- A classificação heurística de 71 skills como "reutilizável" está correta na maioria.Dica prática: a linha "Revisar: ao mudar versão do Codex" é um gatilho de refresh. Sem ela, o overview envelhece em silêncio e o agente passa a citar fatos mortos com a mesma confiança dos vivos.
Conceitos-chave
Afirmação + fonte + data de observação.
rascunho / aceito / revogado; o agente sabe em que confiar.
O que você acha, longe do que você verificou.
Quando o fato deve ser conferido de novo.
🎯 tasks/current.md: objetivo, dono, critério, próxima ação
O overview diz o que o projeto é. O tasks/current.md diz o que está sendo feito agora. É o arquivo que uma sessão nova lê para saber por onde continuar, e é também o que o teste de readback (módulo 2.5) vai cobrar: "qual é o objetivo e qual é a próxima ação concreta?". Cinco campos, sempre os mesmos: objetivo, dono, critério de pronto verificável, próxima ação, bloqueios.
📄 Exemplo preenchido: o tasks/current.md do próprio kit
# Tarefa atual
- Objetivo: validar o piloto — skill `session-handoff` portada pro Codex via polyskill
e readback passando nos dois runtimes.
- Dono: Nei (decide piloto e skills); agente executa.
- Critério de pronto: `scripts/readback-test.sh . both` gera respostas que citam
AGENTS.md/tasks/handoffs em ambos; `scripts/sync-skills.sh drift` sem DRIFT.
- Próxima ação concreta: Fase 0 do plano — `scripts/adapt-instructions.sh ~/.claude`,
revisar, gravar `~/.codex/AGENTS.md`, readback em `~/projetos/wifi`.
- Bloqueios: nenhum.Repare: o critério de pronto é um comando com resultado observável, não "quando estiver bom". A próxima ação começa com um verbo e cita o script exato.
Objetivo
Uma frase. Se precisar de duas, são duas tarefas.
Dono
Quem decide e quem executa. O humano define, o agente marca.
Critério de pronto
Um comando ou uma observação que qualquer runtime consegue reproduzir.
Próxima ação concreta
Verbo + arquivo ou comando. É o que a sessão nova faz primeiro.
Bloqueios
O que só o dono pode decidir. "Nenhum" também é resposta.
Conceitos-chave
O agente entende o trabalho atual, não só o histórico.
Comando com saída esperada, nunca sensação.
Evita que o agente decida o que é do humano.
Sempre os mesmos; o readback depende disso.
📜 Primeira decisão em context/decisions/
Decisão é diferente de fato. Fato se verifica; decisão se aceita. Por isso cada decisão vira um arquivo próprio em context/decisions/, com data no nome, status (proposta, aceita, revogada), contexto, a decisão em si e as consequências. Quando dois arquivos discordam, a decisão aceita vence o mais recente. Isso resolve o problema clássico: "qual das versões é a certa?".
📄 A primeira decisão real do kit
# context/decisions/2026-09-13-docs-fora-do-git.md
# Decisão: docs/ fica fora do git
- Data: 2026-09-13 | Status: proposta (aguarda dono) | Fonte: sessão de criação do repo
## Contexto
docs/ contém post traduzido e prompt library de terceiros. Publicar num repo
público redistribui esse material.
## Decisão
`.gitignore` exclui docs/ até o dono escolher: repo privado, ou manter só
reescritas próprias.O status ficou em "proposta" de propósito: o agente propôs, o dono ainda não bateu o martelo. No readback, o Codex apontou exatamente isso: "não há decisão aceita, só uma proposta". Era a leitura correta.
✓ Vira decisão
- ✓"Segredos ficam em
.enve são referenciados, nunca copiados." - ✓"Skills de adaptador só entram no Codex depois do MCP registrado."
- ✓"Autor de commit acompanha a conta de destino."
✗ Não é decisão
- ✗"O Codex tem 27 skills." Isso é fato; vai no overview.
- ✗"Rodar o sync-skills amanhã." Isso é próxima ação; vai em tasks.
- ✗"Acho que polyskill vai funcionar." Hipótese; overview, seção própria.
Regra de conflito: quando um handoff antigo diz A e uma decisão aceita diz B, vale B. Timestamp mais novo não vence; origem e aceite vencem. É a mesma lógica do superseded_by que você vai ver no Projeto 3 da Trilha 3.
Conceitos-chave
Um arquivo por decisão, com status explícito.
De onde veio e quem aceitou vencem a data.
O agente propõe; o dono aceita. Nunca o contrário.
AAAA-MM-DD-assunto.md: ordena sozinho.
✅ scripts/check.sh: a verificação mínima
O template traz um script de oito linhas que responde uma pergunta só: os arquivos obrigatórios existem e não estão vazios? Parece pouco, mas é a diferença entre "eu acho que preenchi" e "está preenchido". Ele confere AGENTS.md, README.md, os quatro de context/, tasks/current.md e handoffs/latest.md, e sai com código 1 se faltar qualquer um.
💻 Exemplo copy-run: rodar o check
Objetivo: confirmar que o núcleo está completo antes de qualquer readback.
cd ~/projetos/<seu-projeto>
bash scripts/check.sh; echo "exit=$?"Como verificar: tudo [ok] e exit=0. Um [FALTA] significa arquivo ausente ou vazio, e o exit vira 1, então dá pra usar num pipeline.
[ok] AGENTS.md
[ok] README.md
[ok] context/overview.md
[ok] context/current-state.md
[ok] context/sources.md
[ok] tasks/current.md
[ok] handoffs/latest.md
exit=0🔍 O script inteiro, pra você ver que não tem mágica
#!/usr/bin/env bash
set -e; cd "$(dirname "$0")/.."
for f in AGENTS.md README.md context/overview.md context/current-state.md \
context/sources.md tasks/current.md handoffs/latest.md; do
[ -s "$f" ] && echo "[ok] $f" || { echo "[FALTA] $f"; rc=1; }
done; exit ${rc:-0}O -s testa "existe e tem tamanho maior que zero". Um template copiado mas não preenchido ainda passa; por isso o check é mínimo, e o readback do módulo 2.5 é o teste de verdade.
Dica prática: acrescente ao check o que for específico do seu projeto (build, testes, lint). O kit deixa o arquivo curto de propósito: é seu para estender.
Conceitos-chave
Existe e não está vazio; nada além disso.
0 passou, 1 faltou; serve para automação.
Adicione os checks reais do projeto.
Arquivo existir ≠ agente ter usado. Isso é o readback.
📦 Clone isolado: o projeto funciona sozinho?
Aqui está a armadilha mais comum de um workspace "portátil": ele funciona na sua máquina porque depende de uma pasta vizinha, de um ../../knowledge, de um symlink para ~/.claude. O Prompt B exige explicitamente: copie ou clone o projeto sozinho num lugar limpo e verifique os arquivos e comandos. Se o check passa no clone, o contexto essencial está dentro do projeto. Se não passa, você achou uma dependência escondida.
À esquerda o projeto "funciona" porque se apoia em coisas fora dele (tracejado cinza). À direita, no clone, só existe o que foi commitado. Se o check passa aqui, o contexto é portátil de verdade.
💻 Exemplo copy-run: o teste de clone isolado
Objetivo: provar que o núcleo sobrevive fora da sua pasta original. Usa o próprio repo como origem do clone, sem rede.
cd ~/projetos/<seu-projeto>
git add -A && git commit -m "núcleo portátil" # o clone só vê o que está commitado
rm -rf /tmp/clone && git clone -q . /tmp/clone
bash /tmp/clone/scripts/check.sh; echo "exit=$?"Como verificar: sete [ok] e exit=0. Foi exatamente esse teste que o kit rodou em 2026-09-13 e passou. Se aparecer [FALTA] num arquivo que existe na sua pasta, ele não estava commitado ou era um symlink para fora.
init-core.sh
Esqueleto copiado sem sobrescrever.
overview + tasks + decisão
Fatos datados, tarefa com critério, primeira decisão com status.
check.sh local
Sete ok. Ainda não prova nada sobre portabilidade.
check.sh no clone
Sete ok de novo. Agora sim: o projeto anda sozinho. Próximo passo é o readback.
⚠️ O erro a evitar
Pular o clone porque "na minha máquina funciona". Um workspace que depende de ~/.claude/runbooks ou de uma pasta irmã vai quebrar no Codex, no dsh e em qualquer clone de outra pessoa. O teste custa trinta segundos e é a única prova de que a camada é portátil.
Conceitos-chave
Cópia num lugar limpo, só com o que está no git.
Pasta vizinha, symlink, config global.
Exigência do Prompt B: nada só em ../../.
Se algo vem de fora, o AGENTS.md diz como obter.
Auto-checagem (opcional): o check.sh passou na sua pasta mas falhou no clone isolado. O que isso mostra?
🎯 Resumo do módulo
Próximo módulo:
2.4 — Skills canônicas com polyskill: uma fonte, N runtimes