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

View File

@@ -76,7 +76,9 @@ Flat on purpose. Two module trees, one options file each, no hidden layers.
├── templates/downstream/ # `nix flake init -t` starter for users
├── docs/TESTING.md # how to verify changes (incl. AI-agent rules)
├── docs/OVERRIDES.md # how downstream users override defaults
├── docs/ROADMAP.md # forward-looking plans + shipped-fixes log
├── docs/ROADMAP.md # design/decision records + shipped-fixes log
├── agent/ # autonomous-agent loop: protocol (LOOP.md),
│ # prioritized BACKLOG, journal, memory
└── tools/ # maintainer-only
├── import-palettes.py # converts old-distro themes → JSON + assets
├── test-live-iso.sh # build the ISO + boot it in QEMU
@@ -395,6 +397,9 @@ reload # exec zsh (reload the shell)
## Roadmap & known issues
See **[docs/ROADMAP.md](docs/ROADMAP.md)** — forward-looking plans plus the
log of shipped fixes. Kept out of the README so this stays a focused entry
point.
The prioritized queue of what's next lives in
**[agent/BACKLOG.md](agent/BACKLOG.md)**; the detailed design/decision
records and the log of shipped fixes stay in
**[docs/ROADMAP.md](docs/ROADMAP.md)**. Development runs on an
agent-driven loop — see **[agent/LOOP.md](agent/LOOP.md)**. Kept out of
the README so this stays a focused entry point.