adopt
Skill2 starsChanged 42 days agoApache-2.0View on GitHub
Install the dot-claude-iff system into a target project, or upgrade an already-installed one. Invoke on "adopt this system into <path>", "set up my project like this", "install the claude system", "bootstrap .claude for <project>", or "/adopt --upgrade" to bring an installed project's system up to date. A rare, high-blast-radius operation: runs only when the user explicitly asks for it.
- Reads credentials
31 other projects use a version of this.
Adopted by
Most recently taken up by
- tatashbar/Economic-Modeling-Studiotheir own version, first seen Nov 16, 2026
- dmitribogatenkov/briefprooftheir own version, first seen Nov 15, 2026
- chuanglibs/Claude-Code-Game-Studios-Codextheir own version, first seen Nov 15, 2026
- HurricaHjz/second-yourselftheir own version, first seen Nov 9, 2026
- Donchitos/Claude-Code-Game-Studiostheir own version, first seen Nov 9, 2026
- maideps/ai-harness-frameworktheir own version, first seen Nov 8, 2026
Used with
Projects with it also use create-stories, story-done and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
lilangMaxSkillcreate-stories
Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic.
Also in 11 projects that use this
lilangMaxSkillstory-done
End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint.
Also in 11 projects that use this
- +10 more from lilangMax
Other versions31 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 31
- Donchitos/Claude-Code-Game-Studios★ 39ksame name
- HurricaHjz/second-yourself★ 150same name
- HurricaHjz/SecondSelf★ 150same name
- striderZA/OpenCodeGameStudios★ 124same name
- dmitribogatenkov/briefproof★ 68same name
- mrveiss/AutoBot-AI★ 44same name
- cenconq25/claude-code-app-studio★ 40same name
- dawn840705/codex-code-studios★ 17same name
- lilangMax/ClaudeCodeGameStudios★ 8same name
- hongyuanc/codex-game-studios★ 5same name
21 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository4 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- adhdSkill
- plan-taskSkill
- project-memorySkill
The file
We split this skill into the rules it gives an agent
12 rules. 0 are common, 3 are distinctive, and 9 are very specific to this project.
0
Common
Most of the 27 edited versions we read keep these.
3
Distinctive
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
Read before writing anything:
- Very specific: line 66
If the printed path contains Dropbox, OneDrive, iCloud, or Google Drive, say so explicitly as a WARNING before the gate closes: a …
- Distinctive: line 80
Do not proceed on silence.
- Very specific: line 90
Check git -C <source> status --short first: if the source has uncommitted changes, tell the user and prefer its last commit (or ask them to …
- Very specific: line 135
NOT copy <source>'s obs/anchor.json or any obs/rollups/*.json, those are the source project's own sealed totals and tamper-evidence head, …
- Very specific: line 153
Do not create RECORD_ROOT (the sibling <target-parent>/<target-name>_claude_iff/ folder) by hand: the first hook invocation creates it on …
- Distinctive: line 187
Sibling mode: When the Phase 2 gate found the target already running an agent operating system of its own (common when source and target …
- Very specific: line 242
system-map/layers.json: keep the shipped spines list as is, and keep flows: [] empty. - Very specific: line 245
Old-project state: if <source> is an adopted project rather than a pristine checkout, its .claude/tasks/, .claude/rules/, …
- Very specific: line 279
Do NOT preinstall speculative project-specific skills, rules, or agents, and tell the user so explicitly: the evolution protocol …
- Very specific: line 285
Run the checklist against reality, not against your memory of what you did.
- Very specific: line 358
Ask which work mode the user wants and record it with statectl.py mode <freestyle | guided-solo | fableous-orchestrated> (freestyle is the …
“Common” is measured: kept by at least 6 in 10 of the 27 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
adopt: install and upgrade the dot-claude-iff system
You are installing this operating system into a real project, or upgrading one that already has it. Install is a gated procedure: inventory first, one BLOCKING gate for the things only the human knows, then install, adapt, verify, and hand off. Never guess at mission or invariants, read the target's code, and ask.
Orient yourself before Phase 1:
<source>= the root of a dot-claude-iff checkout, or any project already running the system. This system ships ONE profile, everything, so a running project's own.claude/tree is a complete, valid asset to copy from, not a subset.<target>= the root of the project being adopted or upgraded. If you are running inside it,<target>is the current repo. If no<source>was given and you are running inside the target, ask for one (a local clone, or a URL to clone first).- On
/adopt --upgrade, skip Phases 1 to 2 (the target is already adopted; re-inventorying and re-confirming the frame would just repeat questions already answered) and go straight to the Upgrade procedure at the end of this file.
Phase 1: inventory the target
Read before writing anything:
<target>README and manifests (pyproject.toml,package.json,Cargo.toml,go.mod, Makefile, whatever exists). Detect language, package manager, test runner, lint command.- An existing
<target>/CLAUDE.mdor<target>/.claude/CLAUDE.md, if any: its content must survive as source material, not be clobbered. Nested folder guides (<folder>/CLAUDE.md) are noted, not folded: they stay where they are. - An existing
<target>/.claude/, if any: list every file. Anything already there (skills, agents, rules, config) belongs to the target, not to you. - Top-level layout: where code, scripts, configs, and outputs live.
Summarize the inventory to the user in a few lines (stack, commands found, what already exists). This feeds Phase 2 and Phase 4.
Phase 2: confirm the frame (BLOCKING gate)
Some facts only the human holds. This is a BLOCKING gate: use AskUserQuestion, recommended option first, before touching the target. Ask:
| Question | Why you can't infer it | Recommended default |
| Mission, 1 to 2 sentences: what is this project for? | Code shows what, not why | Draft one from the README and offer it for editing |
| What counts as an invariant here? | Load-bearing constraints live in the human's head | Offer candidates you spotted in Phase 1 (e.g. "single source-of-truth data file", "atomic writes") |
Visibility: commit .claude/ with the code (tracked), or keep it in this checkout only (ignored)? | Team and privacy call: the journal, the project log and the lessons hold the user's own words | Run gh repo view --json visibility in <target> first. When it answers PUBLIC, recommend ignored and say why in one sentence: the journal and the project log hold the user's own words, and a public remote would publish them. Otherwise (private, no remote, gh missing or signed out) ask plainly, tracked first as today's behaviour, without pushing either |
| Does this project already run an agent operating system of its own (a continuity engine, policy hooks, self-tests, a console)? | Phase 1 sees files, not systems; kinship flips the whole install mode | If yes, use Sibling mode (end of Phase 3) instead of the copy |
With the visibility question, recommend the pattern that makes the answer easy: work with the
agent in a private repository and publish releases to a public one with
python3 .claude/tools/distctl.py export --to <public-checkout>, which never carries the
record, the memory spine or secrets, and never commits or pushes. The whole pattern, and what
tracked and ignored mean for a team, is in .claude/reference/public-private.md.
Also compute and report the record root, and warn if it looks cloud-synced:
CLAUDE_PROJECT_DIR=<target> python3 <source>/.claude/tools/_lib.py --record-rootIf the printed path contains Dropbox, OneDrive, iCloud, or Google Drive, say so explicitly
as a WARNING before the gate closes: a cloud-synced RECORD_ROOT defeats the point of an
out-of-repo, out-of-git record (it gets synced somewhere else instead), and the user may want to
override policy.record_root before the first capture ever writes.
Two Windows notes. The substring test above can miss: Documents is often OneDrive-redirected
while the visible path still reads C:\Users\<name>\Documents (Known Folder Move), so on
Windows also check the registry before declaring the record root cloud-free:
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\User Shell Folders" /v Personal.
And if python3 --version does not answer usefully (on many Windows boxes python3 is the
Microsoft Store stub), use python for every command in this skill AND tell the user so
explicitly - the hooks' heredocs shell out to python3, so a stub there means the hooks
silently do nothing until the mismatch is resolved.
Do not proceed on silence. If the user answers "Other", capture their wording verbatim.
Phase 3: install
The copy manifest depends on what <source> is:
- An extracted kit (the adopt-kit or fresh zip, no
.gitin it): the kit IS the manifest. It was built from the source's tracked files minus everything below, so copy every file under its.claude/and.claude-iff/. - A git checkout (a clone, or a project running the system): adopt from a CLEAN source.
Check
git -C <source> status --shortfirst: if the source has uncommitted changes, tell the user and prefer its last commit (or ask them to commit first); an adoption snapshotted mid-edit can copy a file whose tests, producer or consumer moved on a minute later. Then copy only files git TRACKS - take the manifest fromgit -C <source> ls-files -- .claude .claude-iff, never from a directory walk. A cleangit statusdoes not vouch for gitignored content: a private, gitignored tree under.claude/(it happened withreference/private/) must never ride an adoption into someone else's repo.
Either way, skip reference/private/ even if a source carries it.
Copy that manifest into <target>/.claude/, file by file, using this rule:
Merge, never overwrite. A path that already exists in <target>/.claude/ is a conflict:
report it to the user (filename plus a one-line description of what each side has) and keep the
target's version unless told otherwise. A path <source> has that <target> lacks: copy it.
Skip __pycache__/ directories and any *.tmp files if present in <source>: build artifacts,
not shipped assets.
This system ships one profile: everything. Unlike systems that hold back machine-specific
files, hooks/ and settings.json ARE part of this install: they are written portably against
$CLAUDE_PROJECT_DIR (never a hardcoded path), so they carry cleanly into any target. Copy
them like every other file, subject to the same merge rule. settings.local.json is not in any
manifest and never travels: it is per-user and gitignored, and it is where the TARGET's own
keys go (.claude/reference/secrets.md). An existing <target>/.claude/settings.json is a
conflict: report it and KEEP THE TARGET'S, like every other collision. Never replace it
wholesale - that single write would unbind all of the target's hooks, bind this system's, and
silently drop the target's permissions and env blocks. Hook-wiring changes are individual
line merges the user approves one by one.
Exclude per-project state and identity, even from <source>. These paths hold that
project's own runtime history or its own voice, not shippable system content, and copying them
would hand the target another project's resume pointer, open loops, needs-human queue,
tamper-evidence anchor - or another project's live contract:
.claude/CLAUDE.md: NEVER copy the source's own filled guide. Kits ship it in placeholder form, but a clone or a running project carries a filled one - the wrong project's mission and invariants, and it activates by existing (Claude Code auto-loads it the moment it lands, no hook or invocation needed). Phase 4 instantiates the target's own guide fromCLAUDE.template.md..claude/state/: create the directory (andstate/handshakes/) empty in<target>. Copy no files from<source>'sjournal.jsonl,session.json,HANDOFF.md,heartbeat.json,needs-human.jsonl,generators.json,memory-run.json, or any stub/envelope underhandshakes/. The target's firstSessionStartand first ritual populate these fresh..claude-iff/: copy the top-level.claude-iff/README.mdonly (that is where the README lives;obs/holds no README). Createobs/with an emptyobs/rollups/beneath it; do NOT copy<source>'sobs/anchor.jsonor anyobs/rollups/*.json, those are the source project's own sealed totals and tamper-evidence head, meaningless (and actively misleading to retro-analyst's usage evidence, per its own agent file) if grafted onto a different project's record.
Also skip the derived files .claude/console/console.html and .claude/system-map/map.json
(both listed under derived_files in policy.json): Phase 5 regenerates both from scratch.
Also skip, on a clone or any running source, the paths that are the source's own build machinery rather than the system (the kits already leave all of them out):
.claude/dist/: the source's release zips. dot-claude-iff tracks them, so its manifest lists them, but they are build output, and a copy inside<target>would nest a stale system inside the installed one..claude/worktrees/: build-time scratch checkouts of the whole source repo. Gitignored, so the manifest should never list them; skip the tree even if it does..claude/reference/release-flow.md: dot-claude-iff's own dev/main release flow..claude/reference/brand-identity.md: dot-claude-iff's own look and voice.
Do not create RECORD_ROOT (the sibling <target-parent>/<target-name>_claude_iff/ folder) by
hand: the first hook invocation creates it on demand, empty, and that is the correct starting
state.
Line endings (.gitattributes) (every install path). The kit ships a root .gitattributes
(*.sh text eol=lf, .claude/hooks/* text eol=lf). When <target> has none, copy it; when it
has one, append the two rules it lacks. Without them Git for Windows (autocrlf=true) rewrites
the hooks CRLF on the first checkout that touches them and bash cannot run them; doctor
warns (gitattributes row) while the rule is missing.
Visibility and the managed .gitignore block (every install path: clone, fresh zip, kit).
Record the Phase 2 answer in <target>/.claude/config/memory.json as "visibility": "tracked"
or "visibility": "ignored" (kits ship tracked; a clone carries its source's value), then
write the block from inside <target>:
python3 .claude/tools/distctl.py gitignore --applyIt renders one block between two marker lines and appends it to <target>/.gitignore
(creating the file when absent), or rewrites it in place on a rerun; the target's own lines are
never touched. Both values carry the secrets safety net (.env, *.env, .env*.local,
settings.local.json) and the python caches; tracked adds the console runtime, the
heartbeat, the ritual ticket, .claude/worktrees/ and atomic-write leftovers, ignored
ignores .claude/ and .claude-iff/ whole. This command is the one writer: never copy a source's .gitignore (the
kit's dot-claude-iff-kit/.gitignore, a clone's root file) by hand. If the answer is ignored
and the target already tracks files under .claude/, tell the user that untracking them is
their git step (git rm -r --cached .claude .claude-iff, which keeps the files on disk); do not
run it. Under tracked, also check the target's EXISTING patterns for over-broad shadows: a
generic dist/, build/ or *.zip matches at any depth and silently untracks .claude/ paths
(checkctl's gitignore_shadowing check warns about this from then on, and is quiet under
ignored). RECORD_ROOT itself needs no gitignore entry: it is a sibling folder outside the
repo, already unreachable by git.
Sibling mode. When the Phase 2 gate found the target already running an agent operating system of its own (common when source and target share ancestry), do NOT run the copy above. The merge rule's model - "a path the target lacks → copy it" - assumes the target lacks the SYSTEM, not just the paths: on a sibling, functional counterparts exist under different names, so almost nothing collides and almost everything copies, and the literal outcome is a second operating system installed beside the first. Measured on a real sibling: 124 source files, 7 path collisions, 103 files would have landed, ONE genuinely additive - the rest a rival journal beside the target's own, a second record root its deny rules did not cover, decoy configs that look authoritative but are read by nothing, agents joining the roster on existence alone, and skills whose triggers ("resume", "where were we") hijack the target's own continuity. Instead, walk a concept bridge with the user: for each of this system's mechanisms - the generator registry/ledger (law 1), the evolution protocol's pruning half, the Task Brief, the honesty protocol, lessons rotation, the verifier role, the seal allowlist - ask whether the target already has it under its own name. Bridge only what is missing, implemented in the TARGET's own stores and idiom, never by copying this system's files. The bridge report IS the install; Phases 4-6 then apply only to what was bridged.
Phase 4: adapt
Turn the copied scaffold into this project's system:
.claude/CLAUDE.md: INSTANTIATE it from the template first, then fill it. Copy<target>/.claude/skills/adopt/CLAUDE.template.md(which Phase 3 just installed) to<target>/.claude/CLAUDE.md. Never copy<source>'s own filled.claude/CLAUDE.md: that is the wrong project's guide, and Phase 3's merge rule deliberately excludes it. Then fill every{{PLACEHOLDER}}the template declares (mission, stack summary, dev commands, invariants, domain notes) from the Phase 1 inventory and the Phase 2 answers, from repo reality, not guesses. If the target already had a rootCLAUDE.mdor a pre-existing.claude/CLAUDE.md, fold that content verbatim into the right sections (Domain notes is the usual home) and remove the redundant file with the user's OK: keep exactly ONE root guide (./CLAUDE.mdor./.claude/CLAUDE.md; two split the always-on instructions in two, andcontext_healthfails on it). Nested folder guides are a different thing: allowed, left in place, and mapped (python3 .claude/tools/mapctl.py contextlists them). A substantial fold will push the guide past the anatomist's ~80-line health threshold on day one; that is expected, not a defect - do not trim the user's content to satisfy the check. Note "condense in an early evolution pass" and move on; the anatomist's audit grants adoption-day folds that grace.- STATUS.md: rewrite to the project's true current state (its sections filled from the inventory and whatever the user says is in flight), not template text.
- Project-log.jsonl: this step, step 4 and step 6 remove content that arrived FROM
<source>in this install - NEVER the target's own past. If<target>already had a populated log, earned lessons, or live tasks before this install (entries predating the adoption are the tell), that is ITS history: keep it and append, do not replace. Otherwise: if<source>was a pristine checkout this file arrived empty; if<source>was an already-adopted project, Phase 3's merge just copied ITS populated log. Either way, REPLACE<target>/.claude/Project-log.jsonlwith exactly one milestone line, today's date, none of<source>'s history:{"date":"<today>","type":"milestone","title":"dot-claude-iff adopted","summary":"Installed the .claude operating system; CLAUDE.md and STATUS.md initialized.","artifacts":[".claude/"],"tags":["setup","tooling"],"source":"session"}(on a target with its own pre-existing log: APPEND that milestone line instead) and record the same fact in the journal so the continuity feed reflects it too:python3 .claude/tools/statectl.py milestone adopt-<today> --title "dot-claude-iff adopted". - LESSONS.jsonl: TRUNCATE to zero lines when its content came from
<source>- lessons are earned, not inherited. But lessons the TARGET earned itself (in any prior format,LESSONS.mdincluded) were paid for here: MIGRATE them intoLESSONS.jsonlrows instead of truncating them away. system-map/layers.json: keep the shippedspineslist as is, and keepflows: []empty. Flow layers are the project's own pipeline stages; they get named through evolution as the project accumulates components, never guessed at adoption from folder names.- Old-project state: if
<source>is an adopted project rather than a pristine checkout, its.claude/tasks/,.claude/rules/,.claude/research/,.claude/reference/, and.claude/system-map/cards/may hold ITS project-specific history, not the system's. Empty<target>/.claude/tasks/of everything that ARRIVED IN THIS INSTALL except the_-prefixed scaffolds (_template.md,_builder-brief.md), and remove an ARRIVEDtasks/archive/entirely (scaffolds are not history; the archive is all history) - a live task or archive the target already had keeps running, untouched, per the step-3 rule. Forsystem-map/cards/, drop ONLY cards whoselayernames one of<source>'s own flow layers (a layer not in the five spines and not null). Keep spine cards AND keeplayer: nullcards: unplaced system components (tool._lib,human.maintainer) are core anatomy that is honestly unplaced, not project residue - deleting them removes real system parts from every downstream adoption. Reviewrules/,research/,reference/and keep only what genuinely generalizes to any project running this system; drop the rest now. This is the one exception to the archive-never-delete convention, because none of it is<target>'s history yet. - Home-only generators stay off. Kits ship
memory.jsonwithdistribution.enabledalready false; when<source>was a clone or a running project, its copy arrived with the knob TRUE - set it tofalsein<target>/.claude/config/memory.jsonnow. It gatesdemo_build,anatomy_buildanddist_build, dot-claude-iff's own release machinery: in<target>they would zip its private.claude/into redistributable archives and render its real session state and system intodocs/, which many repos publish. checkctl reports them as SKIP with the reason named; that is the correct steady state everywhere except the source repo. In the same file, empty thecheckandpolishlists underproject_steps: a clone carries the source's own steps (dot-claude-iff runs its test suite as a CHECK step), and the kits already ship them empty. Likewise setincludeinconfig/publish.jsonto[]: a clone carries the source's own publishing list, the kits ship it empty. - Console port: leave it
"auto".config/console.jsonships"port": "auto": the port derives from the target's folder name (and the console answers athttp://<folder>.localhost:<port>/console.html), so two projects on one machine do not inherit one port.python3 .claude/tools/checkctl.py doctorprints the URL. Only if the session-start hook reports the port busy, pick a free one ONCE and write it into<target>/.claude/config/console.jsonwith a_commentnaming why, so a future/adopt --upgradereads it as intentional rather than drift.
Do NOT preinstall speculative project-specific skills, rules, or agents, and tell the user so
explicitly: the evolution protocol (.claude/protocols/evolution.md) adds tooling when evidence
appears, not before. An unused skill is negative value.
Phase 5: verify
Run the checklist against reality, not against your memory of what you did. Every command below
runs with <target> as the working directory (or CLAUDE_PROJECT_DIR=<target> set):
The ritual ticket. checkctl run (the CHECK and POLISH boxes below) refuses without a
fresh ticket in <target>/.claude/state/ritual-ticket.json. It works here because the user
typed /adopt: the target's prompt hook (hooks/ritual-ticket.sh) minted the ticket from
that prompt, and it counts for this adoption's runs the same way a typed /project-memory
would. That holds only when this session runs INSIDE <target> with its hooks trusted since
the session started (the fresh zip; START-HERE has the user type /adopt). When the user
typed /adopt in another project, or the hooks were installed during this session (the kit
path: hooks load at session start), the target has no ticket and checkctl run refuses. Never
write, copy or forge a ticket: the policy gate denies the file to you on purpose. Instead,
verify read-only with python3 .claude/tools/checkctl.py doctor and checkctl.py probe (no
ticket needed), mark the CHECK and POLISH boxes deferred to the first ritual, and in Phase 6
ask the user to open a new session in <target>, trust the hooks, and type /project-memory.
- Every file in the Phase 3 copy manifest (the kit's files, or git-tracked under
<source>/.claude/, minus the Phase 3 exclusions) exists at its matching path under<target>/.claude/, or was reported as a conflict and resolved with the user. python3 <target>/.claude/tools/checkctl.py doctorreports no FAIL (bash, python3, hook scripts and wiring, record root, console URL, secrets placement, the ritual ticket).grep -rnE "\{\{[A-Z_]+\}\}" <target>/.claude --include="*.md" | grep -v "skills/adopt/" | grep -v _templatereturns nothing. The pattern matches real placeholders only ({{PROJECT_NAME}}-shaped), scoped to markdown: a baregrep "{{"can NEVER return clean on a correct install, because Python f-strings in hooks, brace literals in test fixtures, and the adopt skill's own shipped template (kept placeholder-form on purpose, so the target can seed the next adoption) all contain{{forever. A checkbox that cannot pass teaches agents to reportpartialon every install, or worse, to stop reading the checklist.- Exactly one root guide exists:
<target>/.claude/CLAUDE.md, or a rootCLAUDE.mdif the user chose that, never both. Nested folder guides the target already had stay where they are;python3 .claude/tools/mapctl.py contextlists every guide and rule. - Every JSON/JSONL file under
<target>/.claude/parses (config, journal, Project-log, LESSONS, layers, registry). python3 <target>/.claude/tools/distctl.py gitignoreexits 0:<target>/.gitignorecarries the managed block for the visibility recorded inmemory.json.python3 <target>/.claude/tools/checkctl.py run --phase checkruns and its verdicts are legible (fresh install, so most checks pass trivially; report anything that doesn't).python3 <target>/.claude/tools/mapctl.py scanruns, then dispatch the anatomist agent unconditionally (never skip this, even on a clean install) to read the newly placed components and fill in relations: a map that ships with cards but no edges is worse than no map, because it looks complete and isn't. On a same-session install theanatomistagent TYPE does not exist yet - Claude Code registers agent types at session start, so dispatch by type fails with "agent type not found". That is expected, not a reason to restart mid-procedure or report partial: dispatch a general-purpose agent with<target>/.claude/agents/anatomist.mdas its contract (honor the frontmattermodelpin), and accept its handshake envelope as the anatomist's.python3 <target>/.claude/tools/checkctl.py run --phase polishruns clean. Run the generators through the RITUAL, not by invoking mapctl/consolectl directly: the ritual is what stampsstate/generators.json, and generators run outside it leave the freshness ledger reading "has never run through the ritual" on every CHECK from day one. This one command compiles the map, builds the story feed and builds the console, in order.- HOOKS-FIRE PROBE: trigger a real event through the real hook and look for its effect:
echo '{}' | bash <target>/.claude/hooks/heartbeat.sh, then confirm<target>/.claude/state/heartbeat.jsonexists and is fresh, and ask the user to make one ordinary tool call so Claude Code itself fires a hook (project hooks require the user to trust them before Claude Code executes them at all, so "installed but silently not firing" is a real state). Runningtest_hooks.pyis NOT this probe: it exercises the hook scripts against temp fixtures and passes on any correct file copy, telling you nothing about whether THIS project's hooks are trusted and firing.
Report to the user in Structured Return form: STATUS (done | partial | blocked), RESULT
(what was installed, what was merged, what was skipped and why), EVIDENCE (file listing, grep
output, the checkctl/mapctl/consolectl/test_hooks output), plus DEVIATIONS and QUESTIONS if
any. Any unchecked box means STATUS is partial: say so plainly. Boxes deferred for want of a
ticket count as unchecked: name them, and name the one step that closes them (the user types
/project-memory in a new session in <target>).
Phase 6: first ritual
Close by putting the system into motion:
- Set a pointer to the project's actual first move:
python3 <target>/.claude/tools/statectl.py pointer "<first real next action>". Ask which work mode the user wants and record it withstatectl.py mode <freestyle | guided-solo | fableous-orchestrated>(freestyle is the default); for fableous-orchestrated, point them to.claude/protocols/orchestration.md, which says who does what (the lead plans and merges, builders implement in worktrees, scouts research). - Show the console:
python3 <target>/.claude/tools/consolectl.py openprints the console'sfile://path and the one-line command to start the live server (consolectl.py serve). Recommend the half-screen layout: console in one half of the screen, Claude Code in the other, so state is visible while you work, per.claude/README.md. - Offer to run
/plan-taskon the project's first real task, right now. - Remind the user of the session ritual: the agent starts by reading
.claude/STATUS.md, the active task file, and Watch-outs; the user ends each session by typing/project-memory(the agent suggests it; only the user can open it). If Phase 5 deferred CHECK and POLISH for want of a ticket, ask the user to do that now, in a new session in<target>. - Set expectations for the first retro: it will likely return
NO-CHANGES, that is correct behavior, not a failure. The system grows from evidence the project hasn't generated yet.
Upgrade (/adopt --upgrade)
For a <target> that already has .claude/ installed:
- Diff every file of the Phase 3 manifest (the kit's files, or git-tracked under
<source>/.claude/; samereference/private/skip) against its counterpart in<target>/.claude/, with the same exclusions as Phase 3: never diff or touch.claude/state/(includinghandshakes/),.claude-iff/obs/anchor.json,.claude-iff/obs/rollups/, or the derived filesconsole/console.htmlandsystem-map/map.json. All of these are per-project runtime state, not shipped system content, on the target side as much as on the source side.- Missing in
<target>: a new asset in this version of the system, not conflicting with anything, copy it. - Byte-identical: already up to date, skip.
- Different: drift. Report it to the user (path, and a short description of what changed on the source side) and do NOT overwrite; a file the target customized is the target's, this system never clobbers a customized file on upgrade.
- Missing in
- Apply the non-conflicting updates (the "missing in target" set) the same way Phase 3 does:
merge-never-overwrite, portable against
$CLAUDE_PROJECT_DIR. - Once applied, update
system_versionin<target>/.claude/config/registry.jsonto match<source>'s value.checkctl's registry lint warns loudly wheneversystem_versionis behind what<source>ships, so an upgrade that skips this step leaves the warning firing even though the files are current. Then bring the managed.gitignoreblock up to date with the source's renderer:CLAUDE_PROJECT_DIR=<target> python3 <source>/.claude/tools/distctl.py gitignore --apply. An install from before the block existed readsvisibilityastrackedand gets the block appended (or swapped in for the old kit lines, when those are present verbatim); ask the Phase 2 visibility question first if the target'smemory.jsonhas novisibilityyet. - Re-run the Phase 5 verify checklist; an upgrade that adds new tools or agents still needs the
anatomist dispatched to place them and
consolectl.py buildto pick them up. - Report drift and what was applied in Structured Return form, same shape as Phase 5.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

