Keysat
b9dd7288c4
The playbook assumed one canonical chat per project. Add a merge prompt to Step 1 for reconciling further conversations into the existing AGENTS.md/ ROADMAP.md without overwriting, and note in the retrofit guide that the "files exist" skip can't mine other chats — that stays manual.
Standards
My agent-operating standards: how context and knowledge are organized so any coding agent — Claude Code today, another tomorrow — is productive in my repos immediately, with everything it needs and nothing it doesn't.
This file is the index and the in-the-moment lookup. The depth lives in the four documents below; nothing here is restated there.
The documents
- how-i-work.md — my universal preferences (collaboration, debugging, git). Served to Claude every session via the
~/.claude/CLAUDE.mdsymlink. - portability.md — the hot-swap protocol: how every layer stays vendor-neutral, and the checklist for adopting a new provider.
- retrofit-playbook.md — the one-time, terminal-by-terminal runbook for moving an existing project out of a single long chat onto disk.
- subagents-handbook.md — designing and running delegated agents.
- guides/ — neutral substance (checklists, role knowledge). adapters/ — vendor machinery (symlink targets for
~/.claude/commandsand~/.claude/agents).
Where does this instruction go?
The governing question: would a different agent need this to work on the repo? Yes → it's knowledge, and goes in a neutral file. No → it configures how one tool operates, and goes in that tool's execution layer.
- True in every repo I work in? →
how-i-work.md(Claude reads it via the~/.claude/CLAUDE.mdsymlink; another tool symlinks its own global file here). - True for this whole repo, every session? → the repo's
AGENTS.md(Claude reads it via theCLAUDE.mdsymlink). Keep under ~200 lines; when it grows, push detail down to a guide. - Only relevant to one subsystem or file type? →
docs/guides/<topic>.mdwithpaths:frontmatter, symlinked from.claude/rules/<topic>.md, plus one index line in AGENTS.md. Claude lazy-loads it; other tools find it via the index line. - A multi-step procedure run occasionally? → a skill.
- A verbose, self-contained side job whose output I won't reread? → a subagent (see subagents-handbook.md).
- Must happen deterministically, every time, no matter what the model decides? → a hook (
.claude/settings.json), not markdown. Markdown is guidance a model can interpret; a hook is a shell command the harness always runs. Advanced and Claude-specific — an execution-layer tool to reach for only when guidance-that-can-be-ignored isn't enough. Not needed to start. - Discovered mid-work? → auto memory holds it for now; promote durable facts into AGENTS.md, since auto memory is never committed or backed up.
The tree above routes durable guidance. Project state is tracked separately: near-term status and next steps in AGENTS.md's ## Current state section; longer-term backlog in ROADMAP.md at the repo root.
What loads when
| Layer | Loads | After /compact |
|---|---|---|
how-i-work.md (via ~/.claude/CLAUDE.md) |
In full, every session | Re-read |
AGENTS.md (via CLAUDE.md symlink) |
In full, every session | Re-read from disk |
ROADMAP.md |
Only when you open it deliberately | n/a — never auto-loaded |
docs/guides/* (via .claude/rules/ symlinks) |
Only when files matching paths: are opened |
Not re-injected — promote anything chat-only into AGENTS.md before compacting |
| Skills | On invocation / relevance | n/a |
| Subagents | Isolated context window; returns a summary | n/a |
| Auto memory | Indexed each session | Local only; not portable |
The rhythm (canonical homes elsewhere)
One session = one task. Close every session with /handoff (updates Current state in AGENTS.md, commits, pushes). /compact is for mid-task overflow only, never to extend a finished chat. Dropped or closed by accident? claude -c resumes the latest session in that folder. Full daily rhythm: retrofit-playbook.md, Part 5.