standards/AGENTS.md

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, /roundup, /new-project, /design).
• ~/.claude/agents → adapters/claude/agents/ — global subagents (reviewer, evaluator, security-auditor, doc-auditor, exerciser, researcher, janitor, portability-checker, start9-spec-checker, design-checker, onboarding-tester).
• ~/.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.)
• ~/.claude/statusline.sh → adapters/claude/statusline.sh — the Claude Code CLI terminal status-line script (invoked by ~/.claude/settings.json).

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. Also holds shared reference docs that aren't tied to one command — e.g. placement.md (where a new project should live), which /new-project and how-i-work.md both point at.
• 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).
• STATUS.md — latest cross-project roundup snapshot, overwritten + committed by /roundup each run (git history is the diff over time).

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

• Fleet built and live — commands /capture /triage /roundup /new-project /handoff /retrofit /full-eval /design; subagents incl. design-checker (substance in guides/, thin wrappers in adapters/claude/, symlinked into ~/.claude). The repo dogfoods its own standard. Finished-work detail (/new-project upgrade, placement.md verification, git-hygiene audit) lives in git log + ROADMAP items 5–7. Latest /roundup snapshot: STATUS.md 2026-06-16.
• Design system shipped this session (ROADMAP item 8). /design (main-thread) runs the round-trip → a vendor-neutral on-disk contract (design/DESIGN.md nine-section + design/tokens.tokens.json DTCG); design-checker (read-only subagent) audits a repo's UI against its own contract; /new-project scaffolds design/ for user-facing projects. The on-ramp handles fresh / import / extract / refine with a document-vs-redesign posture and a Phase-D learning loop (Field notes accrete in guides/design.md). The guide is vendor-agnostic about the harness — Claude Design is the named default visual tool, not an assumption; the contract never depends on a proprietary export.
• First live pilot ran end-to-end: keysat backfill (import, document-as-is). Contract committed to keysat-root (532229d); the prior Claude Design system relocated to keysat's design/_imports/ as provenance; design-checker produced a clean backlog (3 gold-as-fill / pill-radius blockers + token gaps) → in keysat ROADMAP and captured to INBOX.md (P2).
• Also this session: deleted start-os (it was a pristine external Start9 upstream clone — none of our work); fixed premier-gunner's stale "set a real password" next-step (already set).
• Onboarding-tester agent built (this session). Global docs-only adopter agent (guides/onboarding-tester.md + wrapper, live via the adapters/ symlink): walks a product's published docs as a literal newcomer, never reading the product's source (needing to is itself a finding), reports doc gaps (Blocker/Stumble/Nit + the one-line fix), and on a fully clean run emits a publishable "all it took was X, Y, Z" walkthrough for marketing. Generic; first target is keysat SDK integration (gate proof-of-work behind a license) under keysat's new least-privilege merchant-onboard scoped key (keysat commit d5885d1). Pending: wire the keysat-side harness (two disposable containers + key minting + docs-corpus URLs) and run it live — built next in a keysat session. ROADMAP item 9.
• Next steps: (1) backfill design into recaps.cc / recap — the extract→reconcile Case B path (organic aesthetic, no prior guidelines), the on-ramp not yet tested; (2) cross-repo quality-gate standard + /harden (ROADMAP item 1); (3) non-git-folder sweep under ~/Projects (~13); (4) wire + run the keysat onboarding-tester harness (ROADMAP item 9).
• Open: a fresh Claude Design run is still needed to confirm what its export actually contains and tune Phase-C distillation — keysat was an import of a prior artifact, not a live export; the related Field-note seeds stay marked "confirm on first live run."
• Queued in INBOX.md for other repos' /triage: keysat design cleanup (P2), ten31-transcripts mini-retrofit, ten31-database networking-doc + oversized-icon items.