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; reads and reports only (prioritizing stays
with the user). **Remaining option:** output is shown inline by default — decide later
whether to also persist a `STATUS.md` in the standards repo for diffing over time like
`EVALUATION.md`.

## 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

**Why:** the inverse of `/retrofit`. Retrofit moves an *existing* project onto disk; this
takes a captured `(new)` inbox idea and turns it into a real, standards-compliant repo. It
closes the capture loop: `/capture (new) …` → bootstrap → a repo that already has AGENTS.md,
the CLAUDE.md symlink, ROADMAP.md, the canonical `.gitignore`, and the inbox-check line.

**Shape:** a command (`/new-project`, run from `~/Projects`), main-thread and collaborative
— scoping is a conversation, not a delegated job. Phases:

1. **Workshop the scope** — back-and-forth to sharpen objectives, non-goals, stack, and the
   key early decisions. Pull the seed from the `(new)` inbox item if one exists. This is the
   high-value step and stays interactive (like roundup, the reasoning is the user's).
2. **Seed prompt** — synthesize the workshop into a concrete project brief / initial build
   prompt plus a scaffolding plan; get the user's sign-off.
3. **Scaffold** — create the new folder under `~/Projects`, write the initial AGENTS.md
   (from the brief) + CLAUDE.md symlink, ROADMAP.md, README, the canonical `.gitignore`,
   `.claude/` wiring, and the starting directory structure. Compliant from line one.
4. **Publish** — `git init` + initial commit, create the Gitea repo, add the remote, push
   (reuse retrofit-playbook Part 4; if no Gitea API token is available, hand back the manual
   "create empty repo, copy URL" step). Then remove the `(new)` item from the inbox.

**Open questions:** Gitea repo creation — API token vs. manual UI step; how much scaffolding
is generic vs. stack-specific (does it call a `/harden` step from item 1 to install the
stack's linter+hook?); whether the workshop output also seeds the first `## Current state`.

## 6. Cross-repo git-hygiene audit + remediation — HIGH PRIORITY

**Why:** a shallow scan of `~/Projects` (2026-06-14) shows the `.claude`/git setup is *not*
consistent across repos. Git repos with the full AGENTS.md + `.claude` + `.gitignore` setup:
`CRM`, `premier-gunner`, `recap-relay`, `recap`, `spark-control`, `standards`, `Workout-log`.
Outliers: `ten31-transcripts` has a `CLAUDE.md` but **no `.claude/` dir** (possible real file
instead of an AGENTS.md symlink — the stale-retrofit failure); `start-os` has neither (likely
an external/upstream repo). Plus many non-git folders (unprotected work). We don't yet know,
per repo, what inside `.claude/` is committed vs gitignored, or whether in-repo symlinks are
relative.

**Do:** fan out one read-only `portability-checker` (or `Explore`) per git repo under
`~/Projects`, each reporting: is `CLAUDE.md` a relative symlink to `AGENTS.md` or a real
file; what's in `.claude/` and which of it is tracked vs gitignored (esp. `settings.local.json`
committed by mistake, or shared `settings.json`/rules symlinks missing); whether `.gitignore`
carries the canonical block; any absolute in-repo symlinks. Synthesize one compliance matrix +
a prioritized remediation list, then a follow-up pass fixes each repo (its own commit).

**Open questions:** treat non-git folders (flag for retrofit) vs. external upstreams
(`start-os`?) differently; report-only first vs. auto-fix.