standards/ROADMAP.md

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/<name>.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 (<name>)) → 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. Done (recap, 2026-06-17): recap was the first Case B (Extract) backfill — document-as-is. It validated the extract→reconcile path (previously untested — keysat was Case A/Import); the contract was distilled and the conformance cleanup shipped in two phases (recap app 0.2.161). Extract-phase Phase-D learnings landed in guides/design.md (commit 9031281); cleanup-execution learnings are now in guides/design-checker.md. Remaining backfill repos: recaps.cc, premier-gunner, ten31-database, ten31-transcripts. (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) — kept decoupled from the recap run so one untested thing moves at a time.

9. onboarding-tester — docs-only fresh-adopter agent ✅ BUILT (agent); harness pending (staged Path 1 → Path 2)

Built and live: guides/onboarding-tester.md + adapters/claude/agents/onboarding-tester.md. A global adopter agent: given a goal, a docs-corpus allowlist, a sandbox, and credentials/endpoint, it walks a product's published docs as a literal newcomer — never reading the product's source (needing to is itself a finding) — and reports every doc gap (Blocker/Stumble/Nit + the one-line fix). On a fully clean run (zero blockers, zero stumbles) it emits a second, publishable "all it took was X, Y, Z" walkthrough for marketing. Generic by design; keysat is the first instantiation. The dual output (friction report always; marketing walkthrough only on a clean run) makes it both a docs-QA tool and a source of agent-readiness copy.

First instantiation — keysat SDK integration (harness lives in keysat, not here): goal = gate proof-of-work behind a keysat license end-to-end under the least-privilege merchant-onboard scoped key (keysat shipped that role for this, commit d5885d1; covers catalog setup + manual license issuance). Harness = two disposable containers (keysat-server fixture booted fresh + developer-sandbox holding proof-of-work), master-key mints the scoped key, docs corpus = keysat.xyz / docs.keysat.xyz / the four SDK package pages.

Staged build:

• Stage 1 — Path 1, no payments (do first, unblocked now): catalog → tiers → manual license issuance → SDK integration → offline verify, all under merchant-onboard. Cheapest honest walkthrough; validates the agent + core integration docs before adding payment infra. Pending: build the harness + first live run in a keysat session.
• Stage 2 — Path 2, full buyer-pays on regtest (gated): depends on keysat shipping payment_providers:write (opt-in scope, never bundled into merchant-onboard) + a network gate (scoped connect = regtest/testnet/signet only; mainnet master-only; fail-closed) + a daemon-level sandbox-mode flag — greenlit with the keysat dev 2026-06-16 (plans/agent-payment-connect-scope.md). Then the harness adds a BTCPay regtest stack and the agent connects BTCPay (regtest) and drives a test buyer payment end-to-end, zero master-key steps. Walkthrough labeled regtest; production mainnet-connect stays the operator's one reserved step by design (a key that can repoint settlement is a fund-redirection key — surface the boundary as a security feature).

Other follow-up (captured to INBOX.md): a separate operator-onboarding agent for the StartOS install journey (stand up + run keysat from docs alone), vs. the developer SDK-integration journey this agent covers.

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.

10. adjudicate — debate low-priority backlog items to a verdict ✅ BUILT (2026-06-17)

Built and live: guides/adjudicate.md + adapters/claude/commands/adjudicate.md (the /adjudicate command). Solves backlog clutter the owner can't easily judge: low-priority (P2/P3) technical/backend items that may be necessary or may be bells-and-whistles, and that he shouldn't spend expertise on because they're low priority. Run inside a repo, it adjudicates that repo's ROADMAP items via a grounded debate and routes each to a verdict the owner ratifies instead of researching.

• Pipeline (per item): investigator (read-only — does the problem exist? already handled? what would it touch? + blast-radius classification) → build-advocate ∥ drop-advocate (argue from the investigator's findings, not speculation) → judge (rubric = how-i-work.md + repo AGENTS.md; biased to DROP on ties / low confidence, since these are already low-priority).
• Three verdicts: DROP (the only autonomously-applied call — ratified in one batch, owner needn't understand the tech), DO (worth it + LOW blast radius → annotated with a ready plan, recommend-only, not executed), ESCALATE (worth it but HIGH blast radius / low confidence / an epic → balanced brief for the owner's call).
• Autonomy is gated by blast radius, not priority — HIGH = touches data/auth/money/external surface or changes observable behavior (unclear ⇒ HIGH). It may auto-recommend dropping a HIGH item but never doing one.
• ROADMAP-only input. Nudges the owner to /triage first if untriaged inbox items exist for the repo, but never reads raw inbox items into the debate (that's /triage's routing job — duplicating it invites drift). Two gates: confirm the item set before fan-out (cost control), then approve the batch of ROADMAP edits. The ROADMAP diff + commit message is the audit trail (no separate report file).

Remaining options: (a) v2 — narrow auto-execution of the safe "DO + LOW blast radius + reversible + test-covered" class, once the owner has watched it make calls and trusts the verdicts (deliberately deferred — recommend-only first to build trust); (b) a thin /triage-then-/adjudicate combo if the two-command chaining friction proves real (YAGNI for now).