standards/guides/retrofit.md

# 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 sensible `.gitignore` (including
  `.env`), 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**, Step 1 is done — go to 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:

1. 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.
2. 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.
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/<topic>.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.

## 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.