Per-project retrofit — orchestration guide

Substance file per the portability protocol. Vendor wrappers (e.g. adapters/claude/commands/retrofit.md) point here; this guide is self-contained and written as plain prose any orchestrating agent could follow. It automates Part 3 of retrofit-playbook.md — read that file for the why behind each step.

You are driving the per-project retrofit for the repository in the current working directory: moving the project's brain out of an old chat and onto disk. You run in the main thread, so you talk to the user and ask for the decisions that need their judgment — you are not a delegated subagent and must not behave like one.

The one thing you cannot do. Step 1 of the playbook mines a specific old conversation via claude --resume. You have no access to past conversations — only the user, from the terminal, can resume one. So the retrofit splits at that seam: you do the git audit before it and everything after it, but the mining itself is a gate you hand back to the user. Never fabricate AGENTS.md from your own fresh context to paper over this — the whole point is to capture what's in the old chat, which you cannot see.

Work through the phases in order. At each decision point, ask the user and wait — don't guess on anything that changes what lands on disk.

Phase 1 — Git audit (playbook Step 0)

If this is not a git repo: propose git init, a .gitignore (the canonical block from portability.md's "What git tracks" — .env, .claude/settings.local.json and *.local.*, OS cruft), and an initial commit. Get approval before running.
If it is: report whether there are uncommitted changes and when the last commit was, then propose committing anything outstanding (a repo existing isn't the same as work being saved — uncommitted changes are as unprotected as no repo at all).
Wait for approval before any commit.

Phase 2 — The mining gate (playbook Step 1)

Check the repo root for AGENTS.md with a CLAUDE.md symlink pointing at it.

If both already exist, the first chat has been mined — go to Phase 3. One thing this skip can't know is whether other conversations are still worth mining: you can't resume past chats any more than you could the first one, so if the user has additional chats to mine, that stays manual. Point them at the "merge from another chat" prompt in retrofit-playbook.md Step 1 (it reconciles into the existing files rather than overwriting them), then continue at Phase 3.

If they're missing, this is the manual seam. Do not proceed and do not invent the file. Instead, help the user mine the right chat, then stop:

Find this project's past conversations on disk. They live in ~/.claude/projects/<encoded-cwd>/*.jsonl, where <encoded-cwd> is the absolute project path with every / replaced by - (e.g. /Users/me/Projects/foo → -Users-me-Projects-foo). List the .jsonl files for this project and rank them by size (and line count) — the largest is almost certainly the long-running chat worth mining. Report the top few with their sizes and last-modified dates so the user can recognize which is which.
Tell the user exactly what to do, in their terminal:
- /exit this session, then claude --resume and pick the conversation you identified (if it doesn't appear, it was a desktop-app session — do this one step from the desktop app; the output lands on disk either way).
- In that resumed chat, paste the three extraction prompts from Part 3 Step 1 of retrofit-playbook.md (A — knowledge → AGENTS.md + the ln -s AGENTS.md CLAUDE.md symlink; B — the ## Current state section, plus seeding ROADMAP.md with any longer-term backlog; C — the secrets sweep).
- Then come back to a fresh session in this folder and run /retrofit again — you'll pick up here, at Phase 3.
Stop. This phase ends the run when the gate isn't satisfied.

Phase 3 — Verify by running (playbook Step 2)

AGENTS.md now exists but is a strong draft, not yet checked against reality.

If the harness has an /init-style refresh that proposes improvements to an existing AGENTS.md/CLAUDE.md without overwriting, suggest the user run it; otherwise propose the equivalent improvements yourself.
Actually run every build, test (including the single-test command), lint, and run command listed in AGENTS.md. Fix whatever's broken and update AGENTS.md to match reality. Resolve every TODO the same way — verify it by running it, then replace it.
Where a fix is ambiguous (more than one plausible correct value, or a command that doesn't exist and you can't infer the intent), ask the user rather than guessing.
Sweep everything you write for secrets — API keys, tokens, passwords, private URLs — and replace each with its env-var name and a note on where the real value lives.

Phase 4 — Trim and scope (playbook Step 3)

Review AGENTS.md. It should hold only whole-repo, every-session facts, under 200 lines.
Identify subsystem-specific guidance that should move out. For each, propose a docs/guides/<topic>.md file starting with paths: frontmatter scoped to the relevant files, a symlink from the harness's rules directory (.claude/rules/<topic>.md for Claude Code) so it lazy-loads, and a one-line index entry in AGENTS.md ("Before editing AREA, read docs/guides/.md").
Show the user the proposed split and wait for confirmation before moving anything — what's whole-repo versus subsystem is a judgment call that's theirs. Then report what moved where.
Ensure AGENTS.md carries the inbox-check line (the portable surfacing mechanism; see retrofit-playbook.md Step 1, and the canonical wording in the standards repo's own AGENTS.md). If it's missing, propose adding it.

Phase 5 — Independent checks (delegate)

Because you're the main thread, you can fan out to subagents here — this is the right division of labor:

Run portability-checker to confirm the structure follows the vendor-neutral / hot-swap standard (AGENTS.md canonical, CLAUDE.md symlink, guides symlinked from the rules directory with index lines). Especially important on repos retrofitted under an older playbook.
Run reviewer on the working diff before the commit.

Relay only what these surface that needs a decision; fold the rest into Phase 6.

Phase 6 — Commit (playbook Step 4)

Propose a single clear commit of everything — AGENTS.md, the CLAUDE.md symlink, .claude/, .gitignore, any new docs/guides/ files and rules symlinks.
Get approval, commit, and push if a remote is configured (don't add one if not — the user's default remote is self-hosted Gitea, not GitHub).

Phase 7 — Validate (playbook Step 5)

True validation is a cold session answering a question only the old chat knew — and you are not cold, you have this run's context. Be honest about that limit:

Re-read AGENTS.md from disk and confirm it alone answers "what's the current state and what should we do next?" If it can't, that's a gap — propose the fix and commit it.
Then recommend the user do the real test themselves: /exit, open a brand-new session in this folder, and ask both a question only the old chat knew and the current-state question. Anything missing → "add that to CLAUDE.md and commit."

Final report

Reply with a short summary: which phases ran, what got committed and pushed, what moved into docs/guides/, and any decisions still waiting on the user. If you stopped at the Phase 2 gate, make the next action unmistakable — which conversation to resume and the three prompts to paste. If blocked at any point, report exactly what blocked you — never guess or fabricate findings.

7.7 KiB Raw Blame History