# ROADMAP — Standards Longer-term backlog for the standards repo: future agents, commands, and cross-repo standards to hash out and build later. Near-term status lives in `AGENTS.md` → `## Current state`. Items here are parked, not committed — we iterate on them when we pick one up. Newly captured cross-repo ideas land in `INBOX.md` first and graduate here on triage. --- ## 1. Cross-repo quality-gate standard (linters / pre-commit hooks / CI) **Why:** with agents writing the code, these stop being developer conveniences and become the falsifiable rails that let an agent check its own work — write, get told exactly what's wrong, iterate, verify. The *standard* is authored here; *application* is per-repo (in each repo's AGENTS.md), because what's best-in-class differs by language/stack. **The principle to encode:** every code repo should give its agent a fast, deterministic, agent-runnable feedback loop — the subset of checks that run without a human and can't be skipped. Tier it: - **Linter/formatter** — per-stack (e.g. ruff/black, eslint/prettier, gofmt). Fast, runs on every change; the agent fixes before moving on. - **Pre-commit hook** — the unskippable gate: runs the linter + quick tests and blocks the commit if they fail. This is the highest-ROI piece and the first to add. - **CI on push** — the heavier rebuild + full test suite. Lower priority for solo repos on Gitea (Gitea Actions exists); add when a repo has real collaborators or releases. **This repo's own first instance:** it's Markdown + symlinks, so its quality gate isn't a code linter — it's a pre-commit hook that runs the **structural checks** this repo already has an agent for: relative-symlink integrity (`AGENTS.md ← CLAUDE.md`, `docs/guides/* ← .claude/rules/*`, the `adapters/` directory symlinks) and internal-link validity. The `portability-checker` agent encodes the invariants; the hook makes the deterministic subset unskippable. Build this as the worked example of the standard. Concrete checks to start with: (a) the `type` enum is identical across `guides/capture.md`, `INBOX.md`, and `AGENTS.md`; (b) `CLAUDE.md` is a relative symlink resolving to `AGENTS.md`; (c) every `adapters/claude/{commands,agents}/*.md` wrapper has a matching `guides/.md` substance file (no wrapper-without-guide drift). **Open questions:** one shared hook framework (pre-commit.com) vs. hand-rolled per repo; how the standard gets *adopted* into a repo (a `/harden` command that installs the right linter+hook for the detected stack?); whether to define a minimal "agentic-ops baseline" checklist doc alongside the other four standards docs. ## 2. `roundup` — cross-project status command ✅ BUILT Built and live: `guides/roundup.md` + `adapters/claude/commands/roundup.md`. Fans out a read-only reader per repo over AGENTS.md/ROADMAP.md, folds in the inbox, and synthesizes one priority-grouped to-do list across all projects (prioritizing stays with the user). Every run **writes the report to a tracked `~/Projects/standards/STATUS.md` snapshot** (overwritten each run, then committed + pushed) so the portfolio state is diffable over time — and shows the same report inline. That snapshot file is the *only* thing roundup writes; all project repos stay read-only. ## 3. Deterministic inbox surfacing — SessionStart hook (optional upgrade over the portable line) **Why:** the portable mechanism (the inbox-check line in every repo's AGENTS.md) is model-interpreted and therefore skippable. A Claude `SessionStart` hook that greps `INBOX.md` for the current repo's tag and prints matching items is deterministic and unskippable — the same quality-gate logic as item 1, applied to capture. **Tradeoff:** hooks are Claude-specific and per-repo, so they don't travel to other vendors. Decision already made: keep the AGENTS.md line as the **belt-and-suspenders portable default**, and offer the hook as an opt-in upgrade for repos where you want the guarantee. Possible form: a snippet the quality-gate `/harden` flow (item 1) installs alongside the linter hook. ## 4. Thread the inbox-check line into bootstrapping **Why:** right now adding the portable inbox-check line to a repo is manual. It should be automatic so every repo inherits it. - Add the line to the AGENTS.md template in `retrofit-playbook.md` (Step 1, prompt A) and to the `/retrofit` guide's Phase 4. - Thread the canonical `.gitignore` block (now in `portability.md` → "What git tracks") into `retrofit-playbook.md` Step 0 and the new-repo bootstrap, so every repo's committed `.gitignore` carries it rather than relying on a global excludesfile. - Consider a one-time sweep command that adds it to every existing repo's AGENTS.md. - Decide whether the canonical wording lives in `how-i-work.md` (so it's truly universal) or stays a per-repo line. ## 5. `new-project` — idea → scoped → scaffolded → Gitea repo ✅ BUILT Built and live: `guides/new-project.md` + `adapters/claude/commands/new-project.md`. The inverse of `/retrofit` — main-thread and collaborative, it turns a captured `(new)` inbox idea into a repo that's standards-compliant from line one. Phases: locate the inbox seed → workshop the scope (the high-value, interactive step) → brief + scaffolding-plan sign-off → scaffold (`AGENTS.md` + `CLAUDE.md` symlink, `ROADMAP.md`, `README.md`, canonical `.gitignore`, `.claude/`, minimal stack skeleton; inbox-check line tagged `()`) → publish (git init + commit, Gitea manual-create gate, remote + push) → close the loop (remove the `(new)` item from `INBOX.md`) → portability-checker verify. **Open questions, resolved:** (a) Gitea repo creation is a **manual web-UI gate** (no API token — matches retrofit-playbook Part 4); (b) the standards layer is always scaffolded, the stack skeleton stays minimal, and the **linter/pre-commit quality gate is deferred to the future `/harden`** (item 1) rather than hand-rolled; (c) the workshop **does** seed the first `## Current state` with the first milestone. **Remaining option:** once `/harden` (item 1) exists, call it as the scaffold's last step so a new repo gets its stack's quality gate installed automatically. ## 6. Cross-repo git-hygiene audit + remediation ✅ DONE (2026-06-14) Fanned out one read-only `portability-checker` per git repo under `~/Projects`. **No safety issues anywhere:** zero tracked `.env` / `.DS_Store` / `*.local.json`, and every in-repo symlink is relative. The gaps were consistency: the inbox-check line was missing in all 7 non-standards repos, and only `standards` had a complete canonical `.gitignore`. **Fixed — 6 repos, one commit each, pushed** (`CRM`, `premier-gunner`, `recap`, `spark-control`, `proof-of-work`; `recap-relay` committed locally — see residuals): added the repo-tagged inbox-check line and normalized `.gitignore`. **Standard improved by the audit:** the documented canonical `.claude/` block was allow-by-default and would have *un-ignored* `premier-gunner`'s password-bearing `.claude/launch.json`. Switched `portability.md` (and the two retrofit summaries) to a **deny-by-default `.claude/*` + allow-list** of the shared wiring. **Residual follow-ups:** - **`ten31-transcripts` (MAJOR) — needs its own mini-retrofit.** Despite the name it's an active Xcode/Swift app with no `.claude/` at all. Scaffold `.claude/settings.json`; decide whether to reorganize its flat `docs/NN_*.md` into `docs/guides/` + `.claude/rules/` symlinks. Too big for the mechanical pass — **captured to `INBOX.md`** (tagged `(ten31-transcripts)`) with step-by-step instructions, for pickup on the next `/triage` in that repo. - **`recap-relay` remote** ✅ Gitea `origin` added + pushed in a later session. - **`premier-gunner/s9pk/.gitignore`** lacks the secrets/Claude lines (low priority; the root `.gitignore` covers `.env` tree-wide already). - **Many non-git folders under `~/Projects` are unprotected work** (discount-watcher, expense-organizer, giga, heart-rate, licensing, one-river, satoshi-sleep, START9 PACKAGING, ten31-agents/-command-center/-signal-engine, timestamp-converter, timestamp-newspaper, website-landing, Grand-Cayman-paddleboard). Each needs `git init` + retrofit, or an explicit "scratch, don't track" decision. - **`start-os`** is an external upstream (Start9Labs/start-os) — out of scope, no action. ## 8. Design system — `/design` round-trip + `design-checker` agent ✅ BUILT (2026-06-16) Built and live: `guides/design.md` + `adapters/claude/commands/design.md` (the `/design` command) and `guides/design-checker.md` + `adapters/claude/agents/design-checker.md` (the `design-checker` subagent). The principle: branding/design for any user-facing repo is a **vendor-neutral on-disk contract** — `design/DESIGN.md` (nine-section brand brief) + `design/tokens.tokens.json` (W3C DTCG tokens) — that every agent reads before building UI. The cloud tool (Anthropic's **Claude Design**, cloud-only/experimental) is an interchangeable front-end, never a dependency. - **`/design`** (main-thread, interactive) runs the round-trip: inspiration-first scoping → `design/BRIEF.md` (the packet the user hand-carries to Claude Design) → user drives the cloud step → distill the export back into the `DESIGN.md` + tokens contract. Distillation is agent-mediated because Claude Design exports inline-hardcoded HTML/CSS, not DTCG tokens (verified by research, 2026-06-16) — worth a human glance the first few runs. - **`design-checker`** (read-only subagent) audits a repo's user-facing code against its *own* committed contract — off-palette colors, wrong type scale, magic-number spacing, matched "don'ts" — citing code `file:line` vs the contract rule. Reports "run `/design` first" if no contract exists; never imposes its own taste. - **`/new-project`** now scaffolds `design/` + the AGENTS.md Design line for user-facing projects (Phase 4). **Remaining options:** (a) `/retrofit` should backfill `design/` into existing user-facing repos (keysat, recap, recaps.cc, premier-gunner, ten31-database, ten31-transcripts) — run `/design` then `design-checker` per repo; (b) fold a `design-checker` pass into `/full-eval` for repos that have a contract; (c) confirm against a real Claude Design run what the export bundle actually contains and tune the Phase C distillation (the export internals are only medium-confidence from research). ## 7. Verify & correct the placement guide ✅ DONE (2026-06-15) Walked the "Infrastructure facts" section with the owner and corrected it against the real setup (cross-checked against the project repos + a Spark-control topology dump). Fixes: **x86** StartOS **0.4.0** box + full service inventory (Gitea, Nextcloud, Home Assistant, CLN + RTL, Open WebUI, Vaultwarden, Synapse, and every Claude-built app); the two-Spark **role split** (LLM Spark = vLLM; audio/speech Spark = Parakeet / Kokoro / Sortformer + TitaNet + bge-m3 + Qdrant, and it hosts matrix-bridge); **don't hardcode a model — query the Spark Control gateway** for the live one (daily driver Qwen3.6, hot-swappable); networking reduced to LAN / WireGuard / StartTunnel (Proton VPN + Tor were legacy, dropped). UNVERIFIED banner replaced with a "verified 2026-06-15" note; decision steps 4 and 6 aligned. Commit `ee5c8bb`.