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 `.gitignore` (the canonical block from
  `portability.md`'s "What git tracks" — `.env`/`.env.*`, a deny-by-default `.claude/*` with
  the shared wiring allow-listed, 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:

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