Add capture/triage inbox loop; dogfood AGENTS.md/ROADMAP; document git-tracking standard

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.
This commit is contained in:
Keysat
2026-06-14 10:36:36 -05:00
parent b9dd7288c4
commit 9e5c42c25f
11 changed files with 483 additions and 2 deletions
+96
View File
@@ -0,0 +1,96 @@
# Standards — AGENTS.md
The home of my agent-operating standards **and** the live global fleet that serves them.
This repo is both the documentation of how any coding agent works in my repos and the
actual source of the global agents, commands, and `how-i-work.md` that every project
inherits. Edit here and every repo on this machine feels it.
For a human-facing tour of the four standards documents, read `README.md` — this file is
the agent-facing orientation and does not restate it.
> **Inbox check (this repo):** At session start, if `INBOX.md` has unchecked items tagged
> `(standards)`, surface them before proposing next steps; triage with `/triage`.
## What this repo is the source of
The global layer lives here and is wired into `~/.claude` by **directory symlinks**, so a
file added under `adapters/` is live immediately — no per-file linking:
- `~/.claude/commands``adapters/claude/commands/` — global slash commands (`/retrofit`,
`/handoff`, `/full-eval`, `/capture`, `/triage`).
- `~/.claude/agents``adapters/claude/agents/` — global subagents (reviewer, evaluator,
security-auditor, doc-auditor, exerciser, researcher, janitor, portability-checker,
start9-spec-checker).
- `~/.claude/CLAUDE.md``how-i-work.md` — my universal preferences, loaded every session.
(Distinct from this repo's *root* `CLAUDE.md`, which → `AGENTS.md`: same filename, different
scopes — global preferences vs. this repo's orientation.)
Because these are *global*, decisions here are never scoped to this repo alone. The test
for anything proposed ("should we adopt linters / hooks / CI?", "is this skill worth
building?") is **whether it's generally best-in-class across all the repos I build** — this
repo is just where that cross-repo standard is authored and stored.
## Layout
- `README.md` — human index of the four standards docs.
- `how-i-work.md` — universal preferences (served as `~/.claude/CLAUDE.md`).
- `portability.md` — the vendor-neutral / hot-swap protocol.
- `retrofit-playbook.md` — terminal runbook for moving a project's brain onto disk.
- `subagents-handbook.md` — designing and running delegated agents.
- `guides/`**neutral substance**: the self-contained operating guide for each command
and agent, written as plain prose any vendor's harness could follow.
- `adapters/claude/{commands,agents}/`**thin Claude wrappers**: frontmatter + a pointer
to the matching `guides/` file. Substance never lives in a wrapper.
- `INBOX.md` — cross-project capture buffer for untriaged ideas/bugs (see below).
- `ROADMAP.md` — longer-term backlog for this repo (future agents, commands, standards).
## Conventions when editing
- **Substance in `guides/`, machinery in `adapters/`.** To add or change what a
command/agent *does*, edit its `guides/<name>.md`. The wrapper only carries frontmatter
and the "read your guide, then follow it exactly; if you can't read it, stop — don't
improvise" pointer. Match the existing wrappers exactly.
- **Portability first.** Knowledge lives in vendor-neutral files; vendor-named paths are
relative symlinks into them. Full protocol in `portability.md`; the `portability-checker`
agent verifies it.
- **Keep this file lean.** Whole-repo, every-session facts only. Subsystem detail goes in a
guide. Near-term status goes in `## Current state` below; longer-term backlog in
`ROADMAP.md`.
- Follow `how-i-work.md` for collaboration, git, and debugging defaults.
## The capture → triage → roadmap loop
A frictionless path from "random thought about some repo" to "on the right list," so ideas
stop scattering into phone notes:
- **`/capture`** appends one structured line to `INBOX.md` from *any* repo (you need not be
in the target repo) and commits+pushes the standards repo so the note is durable. Capture
is deliberately dumb and uniform — no routing decision at capture time.
- **`/triage`**, run *inside* a project, drains that project's `INBOX.md` items and routes
each — `Current state`, the repo's `ROADMAP.md`, a guide, or discard — with your
approval, then clears them from the inbox.
- **Inbox is upstream of every repo's ROADMAP.** ROADMAP is triaged, owned backlog for one
repo; the inbox is the raw, cross-project buffer that feeds the ROADMAPs.
**Inbox-check line (the portable surfacing mechanism).** Every project repo's `AGENTS.md`
should carry this so any vendor's agent surfaces pending items at session start:
> **Inbox check:** At session start, if `~/Projects/standards/INBOX.md` exists, scan it for
> items tagged `(this-repo)` and surface them before proposing next steps; triage with
> `/triage`.
## Current state
- The capture→triage→roadmap loop is built and live: `AGENTS.md` (+ `CLAUDE.md` symlink),
`ROADMAP.md`, `INBOX.md`, and the `/capture` + `/triage` commands. The repo dogfoods its
own standard, including the active inbox-check line above.
- `/capture` also handles **new-project ideas** (`(new)` / `(new:name)`, type `project`);
these wait for the new-repo bootstrap and are never triaged into an existing repo.
- The git-tracking standard ("What git tracks") is now in `portability.md`, and this repo's
`.gitignore` follows it.
- Specced in `ROADMAP.md`, not built: `roundup` (next up), the `new-project` bootstrap, the
cross-repo quality-gate standard (linters/hooks/CI), and the optional SessionStart hook.
- The portable inbox-check line is still not in *other* repos' AGENTS.md nor the retrofit
playbook template — threading it (and the canonical `.gitignore`) into bootstrapping is a
ROADMAP item.
- Next: build `roundup`, then thread the standards into `retrofit-playbook.md`.