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:
@@ -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`.
|
||||
Reference in New Issue
Block a user