A project born elsewhere gets the harness.

One operation, two starting states

It is not two commands. What tells them apart is the provenance stamp; the rest of the procedure is the same. The skill decides: which source, which blueprint, whether it is safe to write. Almost every byte is then written by the deterministic export mode, from a manifest of data.

# 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

The output is the example in nerviz's docs. The ref, the counts and the file names are illustrative.

What the procedure promises

• It refuses a dirty worktree. Not a git repository, or a non-empty git status --porcelain: it stops. An update overwrites, so git diff is how you review it and git checkout how you undo it. It says what to run and does not commit for you.
• None of the four source values is written from memory. base_url, git_url, auth_env and default_ref are data in extensions.json. auth_env names an environment variable and never carries its value; a public repository needs no credential.
• Provenance is written, not promised. The stamp records ref, sha, blueprint and the hash of every file written. /arch-doctor compares those hashes with the disk and names the files you edited by hand before the next update overwrites them.

What goes into the project, and what stays out

All of it is the export block of extensions.json: data, not prose. ArchHook.java schema checks the manifest against the disk, so a skill or agent that is in neither the include list nor the exclude list fails by name.

A project that already has its own .claude/ keeps whatever has a different path from the manifest's. Run --dry-run first: it lists what would be overwritten and writes nothing.

Four situations, and the floor is one

/arch-adopt does not judge the project's code. It only decides whether it is safe to write into .claude/.

The floor is only a floor: there is no ceiling. Spring Boot 5.x passes, and the norms written for the 4 line may diverge from it with no warning. A build that hides its version, such as a corporate parent or an external BOM, passes too.

Below the floor? The /platform-upgrade guide →

A prompt to paste, never an edit

When the norms change in a way that leaves code generated before behind, the change ships as an entry in the migrations block of extensions.json. On an update, the skill prints every entry the project has not seen yet and that applies to its blueprint: a note, and a prompt to paste into Claude Code in the project. It never runs it. The project's own copy of extensions.json is the record of what it was shown, so a project generated after an entry never sees it.

Review, undo, diagnose

It leaves the tree with the diff ready for review and says how to undo it. Then /arch-doctor gives the full diagnosis. What it finds becomes a report line; only the lines of doctor.gate.labels fail CI.

• Generate a project. With no pom.xml or build.gradle, /init-project is what you want.
• Write business code, or touch src/.
• Commit.
• Ask for a blueprint again when the stamp already records one: on an update, it is a fact of the project.

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