Skip to content

t1k:agents-md-migrate

FieldValue
Modulet1k-base
Version5.15.36
Effortmedium
Tools—

Keywords: agents-md-migrate, agents.md, AGENTS.md, claude.md to agents.md, instructions file, migrate claude.md, opencode, shim

/t1k:agents-md-migrate
[--decline]

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):

FileEnd state
AGENTS.mdALL project instructions — the real file every harness reads
CLAUDE.mdexactly one line: @AGENTS.md (the shim)
.claude/CLAUDE.mddeleted, 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.

classMeaningAction
no-agents-mdcontent in CLAUDE.md, no AGENTS.mdfull migration
pointer-onlyAGENTS.md is the T1K pointer (pointerHash=match)full migration; REPLACE the pointer text, never append to it
both-realAGENTS.md edited AND a real CLAUDE.mdmerge both into AGENTS.md — Claude Code has been ignoring the AGENTS.md half; read it, it may contradict CLAUDE.md
dot-claude-remainsroot done, .claude/CLAUDE.md still presentmerge .claude/CLAUDE.md in, delete it, keep the shim
ancestor-blocker / local-md-presentno in-repo CLAUDE.md; a CLAUDE.md above the repo or CLAUDE.local.md suppresses AGENTS.mdadd 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
  1. Already in flight? (main session, BEFORE step 1) If gh pr list --head chore/agents-md-migration --state open returns a PR, record its URL in state= (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 merge origin/<base> in and fold the new lines into AGENTS.md (steps 2-7), instead of stopping. If the branch chore/agents-md-migration exists with no open PR (an earlier lane failed), REUSE it in step 1 instead of creating it.
  2. 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 drops isolation: "worktree"; a write lane is a fork or a native agent, never a routed one. The branch is the PR head.
  3. Merge content, lose nothing. AGENTS.md = root CLAUDE.md content, then .claude/CLAUDE.md content, then any consumer-authored AGENTS.md content not already covered (both-real). Keep headings and order; dedupe only exact duplicates. CLAUDE.local.md is personal and gitignored — never read it into the repo.
  4. Shim. Write CLAUDE.md as exactly @AGENTS.md plus a newline. No symlink: Edit/Write refuse to write through one and Windows checks it out as a text file.
  5. Delete .claude/CLAUDE.md with git rm, only after step 2 is saved.
  6. Links. Repoint relative links that named CLAUDE.md / .claude/CLAUDE.md as the instruction file. Leave prose that names the product feature (“Claude Code reads CLAUDE.md”).
  7. 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 line Sentinel: <random word> to AGENTS.md, run T1K_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.
  8. PR. Pathspec commit (git commit -m "…" -- AGENTS.md CLAUDE.md .claude/CLAUDE.md <link files>), push, open a PR against staging if 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 checks gh pr merge --auto does 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.
  9. Record prUrl in the frame’s state= file (~/.claude/session-state/agents-md-migration/<key>.json, one per repository; keep its fingerprint) so the frame stays quiet (28 days) while the PR is open. Merging changes the fingerprint. An unrecorded run re-fires after 2 hours.
  10. On any failure (probe fails, push/gh fails, a step cannot complete): stop, and merge into the state= file failedAt: <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.

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.