Keysat
9e5c42c25f
Introduce the cross-project capture->triage->roadmap loop: /capture appends an idea or bug to INBOX.md from any repo (new-project ideas included), /triage drains a project's items into its AGENTS.md or ROADMAP.md. Give the standards repo its own AGENTS.md (+ CLAUDE.md symlink) and ROADMAP.md so it follows its own standard, and add a 'What git tracks' section to portability.md plus the canonical .gitignore block answering what is committed vs gitignored around .claude and symlinks.
45 lines
4.3 KiB
Markdown
45 lines
4.3 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 documents below; nothing here is restated there. (`AGENTS.md` is the agent-facing counterpart — loaded every session via the `CLAUDE.md` symlink — and orients an agent *working in* this repo rather than reading about the standards.)
|
|
|
|
## 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`).
|
|
- **INBOX.md** — cross-project capture buffer. `/capture` appends an idea or bug to it from any repo without acting on it; `/triage`, run inside a project, drains that project's items into its `AGENTS.md` Current state or `ROADMAP.md`. The inbox sits upstream of every repo's ROADMAP.
|
|
|
|
## 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.
|