Keysat
b7625c4e83
Promote STATUS.md from an opt-in offer to standard behavior: every /roundup run now writes the report to ~/Projects/standards/STATUS.md (overwritten), shows it inline, and commits + pushes only that file so the portfolio state is diffable over time — the same durability reflex as /capture. STATUS.md remains the only file roundup writes; all project repos stay read-only. Updates guide (new Phase 4), wrapper, ROADMAP item 2, README, and Current state.
49 lines
4.8 KiB
Markdown
49 lines
4.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 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.
|
|
|
|
Between tasks, ideas flow through the inbox: `/capture` logs an idea or bug for any repo to `INBOX.md` from wherever you are (no routing decision at capture time); `/triage`, run inside a project, drains that repo's items into its Current state or `ROADMAP.md`; and `/roundup` reads every repo's AGENTS.md/ROADMAP plus the inbox and compiles one priority-grouped to-do list across all projects, written to a tracked `STATUS.md` snapshot in the standards repo (it gathers and groups — deciding focus stays with you). Canonical home: `AGENTS.md` → "The capture → triage → roadmap loop."
|
|
|
|
Full daily rhythm: retrofit-playbook.md, Part 5.
|