Keysat
3bb67d0ea7
ROADMAP.md was named as a destination in two places but never created, indexed, or read back. Add the convention to how-i-work.md, note it after the README decision tree and in the loads-when table, give it a row in the portability layer table, make the retrofit prompt create it, and have handoff seed it and pull from it when Current state's next steps run thin.
44 lines
3.8 KiB
Markdown
44 lines
3.8 KiB
Markdown
# 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/<topic>.md` with `paths:` 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.
|
|
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.
|
|
|
|
*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.
|