6d70bba8e6
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>
3.1 KiB
3.1 KiB
Goals — what "done" looks like for Nomarchy
The north star every loop iteration serves. When two options conflict, the earlier pillar wins.
The four pillars (in priority order)
- Rock-stable. A workstation you never fight. Everything is a NixOS/HM
generation — atomic, rollbackable, never partial.
nix flake checkis green at every commit onmain. Regressions are caught by the VM-test suite (checks.*), not by users.v1only ever advances after human on-hardware QA. - Reproducible, with zero hidden state. The downstream flake checkout
is the machine. All user-settable config is menu-writable into the
git-tracked state file (
theme-state.jsonsettings.*) — never~/.local/state, never~/.configside files. Re-cloning your flake reproduces the machine, settings and all. - Effortless to configure. The user never has to learn Nix. Every
common knob is reachable from
nomarchy-menu(SUPER+M); the menu is an ergonomic writer for the flake. Where a toggle can take effect without a rebuild, it must (--no-switch+ flip the running service). - Beautiful. One JSON themes the entire desktop coherently — Hyprland, Waybar, Ghostty, btop, rofi, GTK/Qt, boot splash, greeter. Every new surface follows the palette. Informative, self-gating Waybar modules (they hide when irrelevant). No unthemed corner survives contact with the theme switcher.
Quality bars (non-negotiable)
- The honesty rule (docs/TESTING.md): for anything visual, "the Nix evaluates" is not "it renders". Verify at the highest tier you can reach (see LOOP.md's verification ladder) and state the tier you reached. Never claim a check you didn't run.
- Parity rule: any module added to the generated Waybar config must
also be added to the summer-day/night
waybar.jsoncwhole-swaps. - Menu placement: new menu entries go in the right category submenu
(Tools › / System ›), with a direct
SUPER+CTRL+<mnemonic>bind and self-gating where applicable. The root picker stays six entries. - Opt-in features ship a commented example in
templates/downstream/{home,system}.nix. - Option surface discipline: a toggle exists only when there is real
config behind it. Bare package installs go in the template's
home.packages(opt-out = delete the line), never anomarchy.apps.*.
Non-goals (do not drift into these)
- No binary cache. Compile-from-source is a deliberate values call; automation targets the config/lock channel, not artifact distribution.
- No second theming pipeline. The dispatcher owns menu structure; the renderer (rofi) stays swappable. No GTK4 launcher.
- No nixpkgs major bump on
main. Lock updates stay within the pinned release branch; a release jump is a deliberatev2, hand-edited by the maintainer (the last attempt was discarded over a Hyprland OOM — see agent/MEMORY.md). - No repo-wide reformat. The
.nixfiles use deliberate aligned hand-formatting; adopting a formatter is an open maintainer decision (BACKLOG.md § Decisions), not a cleanup. - No multi-DE. Hyprland is the desktop.