t1k:agents-md-migrate
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | medium |
| Tools | — |
Keywords: agents-md-migrate, agents.md, AGENTS.md, claude.md to agents.md, instructions file, migrate claude.md, opencode, shim
How to invoke
Section titled “How to invoke”/t1k:agents-md-migrate[--decline]AGENTS.md Migration
Section titled “AGENTS.md Migration”Moves a consumer project to the Variant S end state decided in
plans/260920-agents-md-migration/decision-record.md row D2 (Plane T1K-46):
| File | End state |
|---|---|
AGENTS.md | ALL project instructions — the real file every harness reads |
CLAUDE.md | exactly one line: @AGENTS.md (the shim) |
.claude/CLAUDE.md | deleted, its content merged into AGENTS.md |
Why the shim stays. Claude Code reads AGENTS.md directly only on v2.1.281+, with the built-in
agents-md plugin enabled, and only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md
exists in the working directory or ANY directory above it
(https://code.claude.com/docs/en/memory.md § “AGENTS.md”). Every one of those failures is silent: the
session simply starts with no project instructions. A CLAUDE.md that imports AGENTS.md loads it
on every version and past every suppressor, and the import is never read twice. Removing the shim
(the full rename) is a separate, future opt-in — never do it here.
Triggered by [t1k:agents-md-migrate class=… root=… scope=… files=… pointerHash=… state=…] from
agents-md-migration-nudge.cjs, or by a direct request. On the frame, do not ask — the frame is
the standing approval (features.agentsMdMigrationFrame, on by default). The MAIN session runs
steps 0-1 itself, then spawns ONE background native sub-agent (t1k-lane-worker, native; never a routed hop or a bare fork)
for steps 2-8 inside the lane worktree, keeps serving the user’s request, and says in one line that
the PR is being prepared. scope=global means T1K lives only in ~/.claude and the repo has no
.claude/; the procedure is the same. root= and state= are JSON-quoted (paths may hold spaces);
always write the frame’s state= file — one per repository, shared by every worktree of it.
Class → what to do
Section titled “Class → what to do”| class | Meaning | Action |
|---|---|---|
no-agents-md | content in CLAUDE.md, no AGENTS.md | full migration |
pointer-only | AGENTS.md is the T1K pointer (pointerHash=match) | full migration; REPLACE the pointer text, never append to it |
both-real | AGENTS.md edited AND a real CLAUDE.md | merge both into AGENTS.md — Claude Code has been ignoring the AGENTS.md half; read it, it may contradict CLAUDE.md |
dot-claude-remains | root done, .claude/CLAUDE.md still present | merge .claude/CLAUDE.md in, delete it, keep the shim |
ancestor-blocker / local-md-present | no in-repo CLAUDE.md; a CLAUDE.md above the repo or CLAUDE.local.md suppresses AGENTS.md | add the one-line shim only; the suppressor is outside the repo or personal — report it, do not touch it. Read AGENTS.md first: if it still says the real instructions live in CLAUDE.md (a pointer stub of an older template, so pointerHash=edited), a shim alone is circular (CLAUDE.md=@AGENTS.md, AGENTS.md→CLAUDE.md, zero instructions loaded) — REPLACE the stub text with the real instructions, or one line stating this file is the instruction file when there is nothing to migrate |
Procedure
Section titled “Procedure”- Already in flight? (main session, BEFORE step 1) If
gh pr list --head chore/agents-md-migration --state openreturns a PR, record its URL instate=(step 8) and never open a second PR. A frame that fires while that PR is open means the base’s instruction files changed after the PR was cut: spawn the lane on the existing branch to mergeorigin/<base>in and fold the new lines into AGENTS.md (steps 2-7), instead of stopping. If the branchchore/agents-md-migrationexists with no open PR (an earlier lane failed), REUSE it in step 1 instead of creating it. - Lane (main session). Create the worktree —
git worktree add ../<repo>-agentsmd -b chore/agents-md-migration origin/<base>, or without-b(git worktree add ../<repo>-agentsmd chore/agents-md-migration) when step 0 found the branch, or use the existing worktree if it is already checked out — then spawn the lane sub-agent there (rules/worktree-session-pinning.md). The lane does NOT re-run step 0: the branch it stands on is expected to exist. A routed spawn dropsisolation: "worktree"; a write lane is aforkor a native agent, never a routed one. The branch is the PR head. - Merge content, lose nothing. AGENTS.md = root CLAUDE.md content, then
.claude/CLAUDE.mdcontent, then any consumer-authored AGENTS.md content not already covered (both-real). Keep headings and order; dedupe only exact duplicates.CLAUDE.local.mdis personal and gitignored — never read it into the repo. - Shim. Write
CLAUDE.mdas exactly@AGENTS.mdplus a newline. No symlink: Edit/Write refuse to write through one and Windows checks it out as a text file. - Delete
.claude/CLAUDE.mdwithgit rm, only after step 2 is saved. - Links. Repoint relative links that named
CLAUDE.md/.claude/CLAUDE.mdas the instruction file. Leave prose that names the product feature (“Claude Code reads CLAUDE.md”). - Verify, don’t assume. Byte-count check: every non-blank line of the old files appears in
AGENTS.md (
grep -Fxf). Then a sentinel probe from the lane root: add a temporary lineSentinel: <random word>to AGENTS.md, runT1K_SKIP_AGENTS_MD_MIGRATION=1 claude -p --model haiku "What is the sentinel word?"(the env var keeps the probe session from re-firing this frame), require the word back, remove the line. A missing word means the import is not loading — stop. - PR. Pathspec commit (
git commit -m "…" -- AGENTS.md CLAUDE.md .claude/CLAUDE.md <link files>), push, open a PR againststagingif it exists, else the default branch. The body lists the class, the files merged, and the probe result. Never arm auto-merge, and never merge. This lane ends at “PR opened” — and on a base with no required status checksgh pr merge --autodoes not wait, it merges on the spot, which is how a migration once landed unreviewed 28 seconds after opening. Leave the merge to a human. - Record
prUrlin the frame’sstate=file (~/.claude/session-state/agents-md-migration/<key>.json, one per repository; keep itsfingerprint) so the frame stays quiet (28 days) while the PR is open. Merging changes the fingerprint. An unrecorded run re-fires after 2 hours. - On any failure (probe fails, push/
ghfails, a step cannot complete): stop, and merge into thestate=filefailedAt: <ISO now>,failures: <previous + 1>,lastError: "<one line>", then report the failure to the user. The frame stays quiet 24h after a failure and goes silent after 3 until the instruction files change — a failing lane never retries every 2 hours.
Decline
Section titled “Decline”If the user declines: FIRST set "declined": true in the frame’s state= file (both scopes) — it
takes effect at the next session, before any PR merges, so a re-fired frame can never start a
migration the user refused. It holds for the repository even when CLAUDE.md is edited later; to
re-enable, delete that state file (or run this skill by hand). Then, for
scope=project, also set features.agentsMdMigrationFrame: false in the PROJECT
.claude/t1k-config-core.json and commit that through a PR, so the “no” is durable and visible. Turning the flag off in ~/.claude declines for
every project on the machine.
T1K_SKIP_AGENTS_MD_MIGRATION=1 silences it for one shell only.