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>
59 lines
3.1 KiB
Markdown
59 lines
3.1 KiB
Markdown
# 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)
|
||
|
||
1. **Rock-stable.** A workstation you never fight. Everything is a NixOS/HM
|
||
generation — atomic, rollbackable, never partial. `nix flake check` is
|
||
green at every commit on `main`. Regressions are caught by the VM-test
|
||
suite (`checks.*`), not by users. `v1` only ever advances after human
|
||
on-hardware QA.
|
||
2. **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.json` `settings.*`) — never
|
||
`~/.local/state`, never `~/.config` side files. Re-cloning your flake
|
||
reproduces the machine, settings and all.
|
||
3. **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).
|
||
4. **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.jsonc` whole-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 a `nomarchy.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 deliberate `v2`, hand-edited by the
|
||
maintainer (the last attempt was discarded over a Hyprland OOM — see
|
||
agent/MEMORY.md).
|
||
- **No repo-wide reformat.** The `.nix` files 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.
|