standards/retrofit-playbook.md

# Retrofit Runbook — Terminal Edition

**Goal:** move each project's brain out of its single endless chat and onto disk, so any fresh session starts already knowing the project *and* what to do next.

**How to read this:**
- Lines in `code blocks` → type into Terminal and press Enter
- Lines in *quote blocks* → paste into Claude once it's running
- Commands starting with `/` (like `/init`) → type inside a Claude session
- Claude will ask permission before running commands. Approving those prompts is normal — expect a lot of them during the retrofit.

---

## Part 1 — One-time setup (5 min)

1. Open Terminal: **Cmd+Space**, type `Terminal`, press Enter.
2. Check the Claude Code CLI is installed:

```
claude --version
```

A version number means you're set (run `claude update` if it's old — auto memory needs 2.1.59+). If you get "command not found," follow the install steps at https://code.claude.com/docs/en/setup — or ask Claude in the desktop app to walk you through it.

3. **Terminal survival kit** (all you actually need):
   - `cd some-folder` moves into a folder. Press **Tab** to autocomplete names, or type `cd ` and drag a folder from Finder into the window to paste its path.
   - `ls` lists what's in the current folder.
   - **Up-arrow** repeats your previous command.
   - Inside Claude, type `/exit` to leave and return to the normal Terminal prompt.

---

## Part 2 — The survey (once, 2 min)

```
cd ~/Projects
claude
```

Paste:

> For each folder in here, tell me whether it's a git repo, whether it has uncommitted changes, and the date of its last commit — as a table. Don't change anything yet.

Read the table — now you know which projects are protected, which are repos in name only, and which old chats to mine first. Then `/exit`.

---

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

```
cd ~/Projects/PROJECT-NAME
claude
```

Paste:

> Is this a git repo? If not: git init, write a .gitignore covering .env/.env.*, a deny-by-default .claude/* with the shared wiring allow-listed (rules/agents/commands/skills/settings.json), and OS cruft — the canonical block in portability.md's "What git tracks" — and make an initial commit. If it is: tell me whether there are uncommitted changes and when the last commit was, then commit anything outstanding.

Approve the git commands it proposes. Then `/exit`. (A repo existing isn't the same as work being saved in it — uncommitted changes are exactly as unprotected as no repo at all.)

### Step 1 — Mine the old chat (the perishable asset)

Still in the project folder:

```
claude --resume
```

Pick your long-running chat from the list. Desktop-app sessions live on this same Mac, so it should appear; if it doesn't, do this one step from the desktop app instead — the output is written to disk either way, which is all that matters.

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. Also add this line near the top so captured items surface in future sessions: "Inbox check: at session start, if ~/Projects/standards/INBOX.md exists, scan it for items tagged (this-repo) and surface them before proposing next steps; triage with /triage." 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 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. Anything longer-term than those next steps — backlog, someday ideas, deferred decisions — goes in a separate ROADMAP.md at the repo root; create it now if there's any such backlog to capture.

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

(Caveat: repeated `/compact` has summarized away some early detail, so treat this as a strong draft — the next step checks it against reality.)

**More than one chat worth mining?** The prompts above *create* AGENTS.md and ROADMAP.md, so run A/B/C only on the first chat. For each additional conversation, `claude --resume` it and paste this *merge* prompt instead — it reconciles into the files rather than overwriting them:

> **Merge from another chat:** First read the current AGENTS.md and ROADMAP.md from disk (and any docs/guides/* they reference) so you know what's already captured. Now go through everything we did in *this* conversation and find what those files don't already have: durable facts (stack, commands, conventions, gotchas, decisions), longer-term backlog, and anything that changes what's currently true. Then reconcile — don't overwrite: add genuinely new durable knowledge to AGENTS.md, add longer-term items to ROADMAP.md (create it if it doesn't exist), and update the "## Current state" section only if this chat reflects more recent state than what's there. Where this chat contradicts what's on disk, don't silently pick one — show me both and ask. Then sweep anything you wrote for secrets and replace them with env-var names. Tell me exactly what you added or changed in each file.

Mine every chat you care about now, while they're the perishable asset; then move to Step 2 and verify the merged result once. (A merged-in chat can be just as compacted as the first — Step 2 is still what checks it against reality.)

### Step 2 — Fresh session: cross-check and verify by running

```
claude
```

Type:

```
/init
```

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

> Review AGENTS.md. Keep only whole-repo, every-session facts, under 200 lines. Move subsystem-specific guidance into docs/guides/TOPIC.md files, each starting with paths: frontmatter scoped to the relevant files. Symlink each from .claude/rules/TOPIC.md so Claude Code lazy-loads it, and add a one-line index entry in AGENTS.md ("Before editing AREA, read docs/guides/TOPIC.md") so any other agent can find them too. Tell me what you moved where.

### Step 4 — Commit (same session)

> Commit everything — AGENTS.md, the CLAUDE.md symlink, .claude/, .gitignore — with a clear message. Push too if a remote is set up.

Then `/exit`.

### Step 5 — Validate (the moment of truth)

```
claude
```

Ask two things in a brand-new session: a question only the old chat "knew," and:

> What's the current state of this project and what should we do next?

Both answered correctly → the project now lives on disk, not in any chat. Anything missing → "add that to CLAUDE.md and commit," then `/exit`.

---

## Part 4 — One-time: the Gitea backup (~10 min)

Your Mac is now the single point of failure; this removes it. Gitea is just a git remote — almost nothing to learn.

1. In Gitea's web UI on your Start9: **New repository**, name it after the project, leave it empty, copy its URL.
2. In a Claude session in the project folder, paste:

> I want to push this repo to my self-hosted Gitea at PASTE-URL-HERE. Set up SSH authentication: generate a key if I don't have one, show me the public key and tell me exactly where to paste it in Gitea's settings, then add the remote and push. Don't ask me to type any secrets into this chat.

3. The SSH key is one-time; for each additional project, just create the empty Gitea repo and say "add my Gitea remote at URL and push."

**The one tradeoff:** Claude's cloud Code sessions (web, and the mobile app's cloud mode) can only clone from GitHub, so Gitea-only means no phone-initiated cloud sessions. Your phone can still monitor and steer sessions running on your Mac — type `/mobile` in a session for a QR code. Want both? Add GitHub as a second remote later; git pushes to both happily.

---

## Part 5 — The daily rhythm (what keeps this alive)

**Start a task** — one session per task; feature = a session, bug = a session:

```
cd ~/Projects/PROJECT-NAME
claude "describe the task here"
```

**Close out every session** (60 seconds — this is what makes closing feel safe instead of like loss): run `/handoff`. It updates the Current state section, commits, and pushes.

Then `/exit`.

**Dropped connection or closed by accident?**

```
claude -c
```

continues the most recent conversation in that folder. Nothing lost.

**Other rules:**
- **Stray ideas, any project:** `/capture` logs an idea or bug to the standards inbox without derailing the session; `/triage` inside a repo pulls its captured items into AGENTS.md/ROADMAP; `/roundup` from `~/Projects` gives one priority-grouped to-do list across all projects.
- `/compact` is for mid-task context overflow only. Task finished = close-out ritual + `/exit`. Never compact to extend a finished chat — that's the old habit sneaking back.
- `/memory` shows every CLAUDE.md and rules file loaded right now, and lets you browse what auto memory has saved. Auto memory lives in `~/.claude`, outside the repo — Gitea never backs it up — so promote anything important into CLAUDE.md.
- When **Current state** stops fitting in ~15 lines, it's accumulating history or backlog. Prune it: finished narrative lives in the git log, still-real longer-term items move to ROADMAP.md. Current state holds only what a session starting now would act on.
- **AGENTS.md is the real file; CLAUDE.md is a symlink to it.** AGENTS.md is the cross-vendor standard (Cursor, Copilot, Codex, Gemini CLI, and the open-source harnesses read it); Claude Code reads only CLAUDE.md, so the symlink serves it the same file under its preferred name. Either name edits the same file — every "update CLAUDE.md" in this runbook lands in AGENTS.md. If you ever switch providers or run self-hosted agents, the repo is already in their native format.
- **The portability principle, generalized:** knowledge lives in vendor-neutral files; vendor-named paths are symlinks into it. Root: AGENTS.md ← CLAUDE.md. Scoped guidance: docs/guides/*.md ← .claude/rules/*.md, indexed by one line each in AGENTS.md. To try a different provider, swap at a session boundary: run the close-out ritual, open the other tool, and it reads AGENTS.md + Current state and continues. The repo is brain-agnostic; sessions are visits. Full protocol: portability.md in the standards repo.

---

## Part 6 — After 2–3 retrofits: the level above the repos

No tool — Claude included — reads an AGENTS.md sitting *above* a repo. The standard is repo-scoped, and each tool keeps its own global file in its own config home (Claude: `~/.claude/CLAUDE.md`; Codex: a global AGENTS.md in `~/.codex/`; and so on). So the about-you layer gets the same treatment as everything else: **one neutral source file; vendor-named symlinks into it.**

The rule: **repo files describe the project; this file describes you.** When the same line shows up in its third repo's AGENTS.md, it moves up here.

Once a few repos are done:

```
cd ~/Projects
claude
```

Paste:

> In my git repo at ~/Projects/standards (create it if it doesn't exist yet), add a file called how-i-work.md. Read the AGENTS.md files in my other repos here and fill it with everything that's about me or repeated across all of them — how I like to work and communicate, workflow rules (the close-out ritual, never commit secrets, verify commands by running them), and the structural conventions (AGENTS.md canonical with a CLAUDE.md symlink, scoped guides in docs/guides with index lines). Around 50 lines. Then symlink ~/.claude/CLAUDE.md to it, commit, and push the repo to my Gitea. Don't change the other repos — they stay self-contained.

Notes:
- **Repos stay self-contained.** Cloud sessions and other machines never see this file. Anything a repo *needs* lives in the repo; this layer is preferences plus a safety net.
- **New projects start right.** A brand-new folder with no AGENTS.md yet still gets your conventions from the very first session.
- **Adopting another tool later costs one symlink:** point its global file at the same how-i-work.md.
- **Bonus:** the standards repo is backed up on Gitea like everything else — nothing else was backing up `~/.claude`. It's also a natural home for this playbook file.

---

## Part 7 — Subagents: delegation without the context cost

A subagent is a helper Claude that runs in its **own separate context window** and reports back only a summary. Files control what enters context at session start; subagents control what stays out of context while work happens. Use one whenever a task is mostly reading noise and you only need the conclusion:

- **Explorer** — "figure out how X works across this repo and report back." It reads forty files; your session receives twenty lines.
- **Reviewer** — fresh eyes before a commit. The separate context is the point: it isn't anchored by your build conversation.

Create them on demand: type `/agents` in a session, or just ask ("create a project subagent called reviewer that..."). Definitions live in `<repo>/.claude/agents/NAME.md` — a few lines of Claude-specific header plus a plain-prose role.

**Portability:** there is no cross-tool standard for subagents — each harness does delegation its own way — so the symlink trick has nothing to attach to. Instead: **thin wrapper, neutral substance.** The subagent file holds role and wiring only, and points at shared docs for the real content ("follow docs/guides/review-checklist.md"). Switching providers then means regenerating a five-line wrapper, not rewriting knowledge.

---

## Sequencing across many projects

Don't make it a migration. Retrofit the 1–2 projects you're actively building now; do the rest lazily — 15 minutes the next time you open one. One exception: if an old chat is near its context limit or heavily compacted, run Step 1 (the extractions) today even if you do nothing else. The extraction is the perishable part; everything else can wait.

## Reference docs

- CLI commands and flags: https://code.claude.com/docs/en/cli-reference
- Memory, CLAUDE.md, rules, auto memory: https://code.claude.com/docs/en/memory
- Claude Code on web/mobile: https://code.claude.com/docs/en/web-quickstart