From e13c143e50824448ae68a26cff0388546a8a19a6 Mon Sep 17 00:00:00 2001 From: Keysat Date: Fri, 12 Jun 2026 14:00:23 -0500 Subject: [PATCH] Add README index for the standards repo Top-level index and in-the-moment lookup: the four core documents, the decision tree for where each instruction goes, what loads when, and the session rhythm. --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1d52c8e --- /dev/null +++ b/README.md @@ -0,0 +1,40 @@ +# 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.md` symlink. +- **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/commands` and `~/.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. + +1. **True in every repo I work in?** → `how-i-work.md` (Claude reads it via the `~/.claude/CLAUDE.md` symlink; another tool symlinks its own global file here). +2. **True for this whole repo, every session?** → the repo's `AGENTS.md` (Claude reads it via the `CLAUDE.md` symlink). Keep under ~200 lines; when it grows, push detail down to a guide. +3. **Only relevant to one subsystem or file type?** → `docs/guides/.md` with `paths:` frontmatter, symlinked from `.claude/rules/.md`, plus one index line in AGENTS.md. Claude lazy-loads it; other tools find it via the index line. +4. **A multi-step procedure run occasionally?** → a skill. +5. **A verbose, self-contained side job whose output I won't reread?** → a subagent (see subagents-handbook.md). +6. **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. +7. **Discovered mid-work?** → auto memory holds it for now; promote durable facts into AGENTS.md, since auto memory is never committed or backed up. + +## 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** | +| `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.