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:

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).
Seed prompt — synthesize the workshop into a concrete project brief / initial build prompt plus a scaffolding plan; get the user's sign-off.
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.
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.

7.8 KiB Raw Blame History