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).
- `~/.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

- **The fleet is built and live.** Commands `/capture`, `/triage`, `/roundup`,
  `/new-project`, `/handoff`, `/retrofit`, `/full-eval` (substance in `guides/`, thin wrappers
  in `adapters/claude/`, symlinked into `~/.claude`). The repo dogfoods its own standard:
  inbox-check line, deny-by-default `.gitignore`, relative symlinks, capture→triage→roadmap loop.
- `/roundup` writes a tracked `STATUS.md` snapshot each run (overwritten, committed + pushed —
  diffable over time); latest snapshot dated 2026-06-16.
- **Design system built (2026-06-16, ROADMAP item 8).** `/design` (main-thread command) runs
  the inspiration-first design round-trip → a vendor-neutral on-disk contract (`design/DESIGN.md`
  nine-section brief + `design/tokens.tokens.json` DTCG tokens); `design-checker` (read-only
  subagent) audits a repo's UI against its own contract. Claude Design (cloud-only/experimental)
  is the interchangeable front-end, never a dependency — its export is inline-hardcoded HTML/CSS,
  so Phase-C token distillation is agent-mediated (research-verified 2026-06-16). `/new-project`
  now scaffolds `design/` for user-facing projects.
- `/new-project` is the inverse of `/retrofit`: workshops a captured `(new)` idea into a
  standards-compliant repo and publishes to Gitea via a manual-create gate; the stack quality
  gate is deferred to a future `/harden`. Now carries a **form-factor gate** (is this even a
  standalone repo, or a feature/skill/agent of something that exists? — bail + reroute if so),
  a **worth-building gate** at sign-off (build effort + ongoing tax → BUILD/PARK/ADOPT), a
  **placement** step that walks `guides/placement.md`, the falsifiable-exit "substance rule,"
  and a posture section — all harvested from a retired `idea-workshop` skill. A new project's
  architectural decisions live in its `AGENTS.md` `## Decisions` section (no separate ADR file).
- `guides/placement.md` is a shared reference (where a project should run / which model /
  what data layer). **Its infra facts were verified with me 2026-06-15** (ROADMAP item 7 done):
  x86 StartOS 0.4.0 box + full service list; the two-Spark role split (LLM vs audio/speech,
  Qdrant on the audio Spark, matrix-bridge hosted there); route via the Spark Control gateway
  and query the active model rather than hardcoding one; LAN/WireGuard/StartTunnel networking.
  UNVERIFIED banner dropped.
- **The upgraded `/new-project` flow has had its first live end-to-end run** —
  scaffolded `~/Projects/matrix-bridge` (a Matrix→Claude Code bridge bot) from a prior
  scoping package, folding its SPEC/DECISIONS into the new AGENTS.md `## Decisions` scheme.
  The form-factor gate (worthy of its own repo) and the placement step worked cleanly in
  practice; portability-checker passed. Good worked example of the flow.
- Cross-repo git-hygiene audit done: 9 repos audited, no leaks, 6 remediated + pushed; the
  canonical `.claude/` block is now **deny-by-default** (in `portability.md`; full detail in
  git log + ROADMAP item 6).
- This session: ran `/roundup` (STATUS.md snapshot 2026-06-15); verified & corrected
  `guides/placement.md` with me and committed it (ROADMAP item 7 done); captured a
  `(ten31-database)` networking-doc fix to `INBOX.md`; and resolved the `how-i-work.md`
  consolidation — promoted the **instruction-file-structure** convention and added a
  **promote-without-trim** principle (commit `f7e9e29`), and decided against any fleet-wide
  trimming (per-repo AGENTS.md files aren't bloated, and in-repo copies aid self-containment).
- **Next steps:** (1) the cross-repo quality-gate standard + `/harden` (ROADMAP item 1 — also
  unblocks `/new-project`'s deferred quality-gate step); (2) the non-git-folder sweep under
  `~/Projects` (item-6 residual; count ~13); (3) first live `/design` run + `design-checker`
  backfill on a user-facing repo, which will also confirm what Claude Design's export actually
  contains and let us tune Phase-C distillation (ROADMAP item 8 remaining options).
- Queued elsewhere / specced-not-built: the `ten31-transcripts` mini-retrofit and a new
  `(ten31-database)` networking-doc fix wait in `INBOX.md` for those repos' `/triage`; the
  SessionStart hook (item 3) and inbox-line bootstrap threading (item 4) remain on the ROADMAP.