feat(agent): autonomous-loop infrastructure + roadmap rework

A git-tracked agent/ directory so AI agents can iterate on the distro
unattended (runner-agnostic: /loop, headless claude -p, or a fresh
manual session — all state lives in the checkout, per the distro's own
philosophy):

- LOOP.md — the iteration protocol: orient → pick one BACKLOG task →
  verify up the V0–V3 ladder → commit+push main → record. Safety rails
  (v1 untouchable, no force-push, no surprise lock bumps) and
  stop-and-escalate conditions.
- BACKLOG.md — the forward half of docs/ROADMAP.md reworked into a
  prioritized queue (5 NOW / 6 NEXT / LATER / PROPOSED / Decisions);
  ROADMAP.md stays the design/decision record + shipped log.
- GOALS.md — the four pillars (stable > reproducible/zero-hidden-state >
  effortless config > beautiful), quality bars, non-goals.
- CONVENTIONS.md — coding/design rules (in-flake state, menu placement,
  Waybar whole-swap parity, toggle-vs-package, no formatter).
- MEMORY.md — curated hard-won lessons (VM recipes, btrfs-assistant
  segfault watch, rofi/WirePlumber/hyprlock gotchas).
- HARDWARE-QUEUE.md — every pending V3 on-hardware check collected from
  the ROADMAP, with exact steps, split by machine.
- JOURNAL.md — append-only iteration log, seeded with this bootstrap.

Plus a root CLAUDE.md entry point and README/ROADMAP pointers.

Verified: V0 — docs-only; nix flake check --no-build green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Bernardo Magri
2026-07-04 08:51:11 +01:00
parent 9726ba3b2f
commit 6d70bba8e6
10 changed files with 584 additions and 4 deletions

25
CLAUDE.md Normal file
View File

@@ -0,0 +1,25 @@
# Nomarchy — agent entry point
Nomarchy is a NixOS-based distro: rock-stable, fully reproducible, themed
from one JSON, configured through a menu that writes into the user's own
flake checkout. Read the README for the architecture.
## If you're here to work autonomously (the loop)
Follow **`agent/LOOP.md`** — it defines one iteration: orient
(GOALS/BACKLOG/JOURNAL/MEMORY), take the top actionable BACKLOG item,
verify up the V0V3 ladder, commit+push on `main`, record. All loop state
is git-tracked in `agent/`.
## Rules that apply to every session, loop or not
- **Honesty rule** (docs/TESTING.md): for visual/interactive changes,
evaluation is not rendering — state exactly what you verified and at
which tier. Cheap check first, always: `nix flake check --no-build`.
- **Conventions** (`agent/CONVENTIONS.md`): in-flake state, menu
placement, Waybar parity with the summer whole-swaps, toggle-vs-package
discipline, commented template examples for opt-ins.
- **Git:** direct commits on `main`, pushed; `v1` is the human-only
release pointer — never touch it. Never run `nix flake update` unless
the task is a lock bump. No formatter — match the aligned
hand-formatting.
- Machine-specifics live in `hosts/`, the distro in `modules/`, data in
`themes/`, code in `pkgs/`, maintainer tools in `tools/`.