Add /retrofit command for Part 3 of the playbook

Automate the per-project retrofit (git audit, verify, scope, commit,
validate) as a main-thread slash command that asks for the judgment
calls. Step 1 (mining a past chat) stays manual — the command surfaces
which conversation to mine and hands back, since it can't resume one.

adapters/claude/commands/retrofit.md

@@ -0,0 +1,25 @@
+---
+description: Per-project retrofit — git audit, then mine/verify/scope/commit/validate a project's brain onto disk (Part 3 of the retrofit playbook)
+argument-hint: [optional notes, e.g. "old chat already mined"]
+allowed-tools: Bash, Read, Edit, Write, Grep, Glob, Agent
+---
+
+Run the per-project retrofit for the repository in the current working directory.
+Optional notes from me (may be empty): $ARGUMENTS
+
+Your complete orchestration guide — the phases, the mining gate you must hand back to me,
+the decisions to ask about, and the final report format — is at:
+
+    ~/Projects/standards/guides/retrofit.md
+
+Read it in full first, then follow it exactly. If you cannot read that file, stop and
+report precisely that — do not improvise the retrofit.
+
+This runs in the main thread on purpose: ask me the judgment calls (which old chat to
+mine, ambiguous command fixes, the whole-repo-vs-subsystem split, commit/push approval)
+and wait — don't guess on anything that lands on disk. You cannot resume a past
+conversation yourself, so when AGENTS.md doesn't exist yet, surface which conversation to
+mine and stop, per Phase 2.
+
+For Phase 5, delegate to the portability-checker and reviewer subagents (the foreground
+is fine; they're read-only).

guides/retrofit.md

@@ -0,0 +1,123 @@
+# 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; 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.

retrofit-playbook.md

@@ -46,6 +46,13 @@ Read the table — now you know which projects are protected, which are repos in
 
 ## Part 3 — Per-project retrofit (~20–25 min each)
 
+> **Shortcut once you know the why:** the `/retrofit` command drives this whole part for
+> you — git audit, then verify/scope/commit/validate — pausing to ask you the judgment
+> calls. The one step it can't do is Step 1: it can't resume a past conversation, so it
+> surfaces *which* old chat to mine and hands back to you. Read the steps below at least
+> once (the point is learning the rhythm); reach for `/retrofit` on repo #3 onward.
+> Guide: `guides/retrofit.md`.
+
 ### Step 0 — Open the project and audit git
 
 ```
@@ -73,9 +80,9 @@ Paste, one after another:
 
 > **A — knowledge:** Based on everything we've done in this project, write an AGENTS.md at the repo root that a fresh coding-agent session could read and be immediately productive with. Include: a one-line description; the stack/versions that matter; the exact build, test (including how to run a single test), lint, and run commands; the directory layout worth knowing on day one; the conventions you've learned I follow here; and an Always/Never list of the gotchas and decisions we hit — especially anything you got wrong earlier that I corrected. Under 200 lines, markdown headers and short bullets, concrete and verifiable, no history. Don't invent commands or paths — mark anything you're unsure of as TODO. No API keys, tokens, or secrets — reference env-var names instead. Write the file now, then create a symlink so Claude Code loads it: ln -s AGENTS.md CLAUDE.md
 
-> **B — state:** Now append a "## Current state" section to the bottom of CLAUDE.md: what's built and working, what's in progress and exactly where it stands, decisions we made that aren't implemented yet, known bugs, and the next 3–5 concrete steps. 15 lines max, present tense, no history. Longer-term backlog goes in a separate ROADMAP.md.
+> **B — state:** Now append a "## Current state" section to the bottom of AGENTS.md: what's built and working, what's in progress and exactly where it stands, decisions we made that aren't implemented yet, known bugs, and the next 3–5 concrete steps. 15 lines max, present tense, no history. Longer-term backlog goes in a separate ROADMAP.md.
 
-> **C — secrets sweep:** Scan CLAUDE.md and anything else you just wrote for secrets — API keys, tokens, passwords, account numbers, private URLs. Replace each with its env-var name and a note about where the real value lives.
+> **C — secrets sweep:** Scan AGENTS.md and anything else you just wrote for secrets — API keys, tokens, passwords, account numbers, private URLs. Replace each with its env-var name and a note about where the real value lives.
 
 Then `/exit`. The old chat's job is done forever.
 
@@ -95,7 +102,7 @@ Type:
 
 Because a CLAUDE.md already exists, it proposes improvements instead of overwriting — accept what looks right. Then paste:
 
-> Now actually run every build, test, lint, and run command listed in CLAUDE.md and fix whatever's wrong, updating CLAUDE.md to match reality. Resolve every TODO the same way: verify it by running it, then replace it.
+> Now actually run every build, test, lint, and run command listed in AGENTS.md and fix whatever's wrong, updating AGENTS.md to match reality. Resolve every TODO the same way: verify it by running it, then replace it.
 
 ### Step 3 — Trim and scope (same session)