Um projeto que nasceu fora ganha o harness.

Uma operação, dois estados de partida

Não são dois comandos. O que os distingue é o stamp de proveniência; o resto do procedimento é o mesmo. A skill decide: qual fonte, qual blueprint, se é seguro escrever. Quase todo byte é escrito depois pelo modo determinístico export, a partir de um manifesto de dados.

# the example in docs/en/10-arch-adopt.md; the ref, counts and file names are illustrative
› /arch-adopt --ref latest-tag --blueprint hexagonal

✅ updated — blueprint hexagonal, ref v0.9.3 (a1b2c3d)

Source ....... codeload.github.com, fetched at 14:22
Files ........ 136 written · 118 unchanged · 4 overwritten
Warnings ..... none
Schema ....... exit 0
Provenance ... ⚠️ 2 files edited locally since the stamp:
               .claude/rules/persistence.md
               .claude/settings.json
Bounded ctx .. already declared
Migrations ... 1 below, to paste when you choose

Review: git diff · Undo: git checkout -- .claude
Next: /arch-doctor for the full diagnosis

A saída é o exemplo dos docs do nerviz. O ref, as contagens e os nomes de arquivo são ilustrativos.

O que o procedimento promete

• Recusa worktree suja. Não é repositório git, ou o git status --porcelain veio não vazio: para. Uma atualização sobrescreve, então o git diff é como você revisa e o git checkout como desfaz. Ela diz o que rodar e não faz commit por você.
• Nenhum dos quatro valores de source é escrito de memória. base_url, git_url, auth_env e default_ref são dados no extensions.json. O auth_env nomeia uma variável de ambiente e nunca carrega o valor; um repositório público não precisa de credencial.
• Proveniência é escrita, não prometida. O stamp registra ref, sha, blueprint e o hash de cada arquivo escrito. O /arch-doctor compara esses hashes com o disco e nomeia os arquivos que você editou à mão antes de a próxima atualização sobrescrevê-los.

O que entra no projeto e o que fica de fora

Tudo isso é o bloco export do extensions.json: dado, não prosa. O ArchHook.java schema confere o manifesto contra o disco, então uma skill ou um agente que não está nem em include nem em exclude falha pelo nome.

Um projeto que já tem o próprio .claude/ mantém o que tem caminho diferente do manifesto. Rode --dry-run antes: ele lista o que seria sobrescrito e não escreve nada.

Quatro situações, e o piso é uma delas

O /arch-adopt não avalia o código do projeto. Ele só decide se é seguro escrever em .claude/.

O piso é só um piso: não há teto. O Spring Boot 5.x passa, e as normas escritas para a linha 4 podem divergir dela sem aviso. Um build que esconde a versão, como um parent corporativo ou um BOM externo, também passa.

Abaixo do piso? O guia do /platform-upgrade →

Um prompt para colar, nunca uma edição

Quando as normas mudam de um jeito que deixa para trás o código gerado antes, a mudança chega como uma entrada no bloco migrations do extensions.json. Numa atualização, a skill mostra cada entrada que o projeto ainda não viu e que vale para o blueprint dele: uma nota e um prompt para colar no Claude Code, no projeto. Ela nunca o executa. A cópia do extensions.json do próprio projeto é o registro do que foi mostrado, então um projeto gerado depois de uma entrada nunca a vê.

Revisar, desfazer, diagnosticar

Ela deixa a árvore com o diff pronto para revisão e diz como desfazer. Depois, o /arch-doctor faz o diagnóstico completo. O que ele encontra vira uma linha de relatório; só as linhas de doctor.gate.labels quebram o CI.

• Gerar um projeto. Sem pom.xml nem build.gradle, o que você quer é o /init-project.
• Escrever código de negócio, ou tocar em src/.
• Fazer commit.
• Pedir o blueprint de novo quando o stamp já registra um: numa atualização, ele é um fato do projeto.

# review
git diff
# undo
git checkout -- .claude && git clean -fd .claude
# then the full diagnosis
› /arch-doctor