4c656b1e73
All checks were successful
Check / eval (push) Successful in 4m45s
New standing rule (LOOP.md §5 step 4, echoed in AGENTS.md): when a task ships, grep its number/feature name across agent/ and docs/ and update or delete every cross-reference it made stale, in the same commit — including pruning checked-off [x] HARDWARE-QUEUE entries whose outcome is recorded (journal/ROADMAP; git history is the archive). First application: BACKLOG PROPOSED groomed (the auto time-of-day theme pitch was stale — shipped as #79; shipped/promoted placeholder lines removed; v1.0 pointer rewritten; FUTURE promoted-stub dropped); HARDWARE-QUEUE pruned of 29 checked entries (363→253 lines) with dangling references reworded and the prune rule documented in its header. Also closes the zram user-doc gap: README §3 now documents the zram default (zstd/50%/prio 100), hibernation working out of the box on new installs, and the MIGRATION.md runbook for existing machines. Verification: V0 (docs/meta only). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
66 lines
3.2 KiB
Markdown
66 lines
3.2 KiB
Markdown
# 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.
|
||
|
||
This file is the entry point for **any** AI coding agent, whatever the
|
||
vendor or harness. Everything agents need lives in vendor-neutral,
|
||
git-tracked markdown (`agent/`, `docs/`); harness-specific config is a
|
||
thin *adapter* (see bottom) and never holds shared content.
|
||
|
||
## Where things live (read this first)
|
||
|
||
| Path | Role |
|
||
|------|------|
|
||
| **`agent/`** | Agent instructions + loop state — **only executable queue is `BACKLOG.md`** |
|
||
| **`agent/README.md`** | Map of the agent files |
|
||
| **`docs/VISION.md`** | Product themes toward **v1.0** (not a queue) |
|
||
| **`docs/ROADMAP.md`** | Design history + shipped log |
|
||
| **`docs/README.md`** | Full documentation map |
|
||
| **`.claude/`** | Claude Code adapter only (permissions, subagent defs) — not the backlog |
|
||
|
||
## If you're here to work autonomously (the loop)
|
||
Follow **`agent/LOOP.md`** — one iteration: orient → pick one BACKLOG
|
||
item → work → verify → commit+push on `main` → record. All loop state is
|
||
git-tracked in `agent/`.
|
||
|
||
## Rules that apply to every session, loop or not
|
||
- **Before your first change, read `agent/VERIFICATION.md`** and follow
|
||
it — every change, however small, climbs its V0–V3 ladder. For theme
|
||
or visual work, also read `agent/THEME-DESIGN.md`; before any VM test,
|
||
`docs/TESTING.md`.
|
||
- **Honesty rule** (`agent/VERIFICATION.md`, `docs/TESTING.md`): for
|
||
visual/interactive changes, evaluation is not rendering — state the
|
||
tier you reached. Cheap first: `nix flake check --no-build`.
|
||
- **Conventions** (`agent/CONVENTIONS.md`): in-flake state, menu
|
||
placement, Waybar parity with whole-swaps, toggle-vs-package discipline,
|
||
template as SoT for opt-in comments (`templates/downstream`).
|
||
- **Sync sweep on completion** (`agent/LOOP.md` §5): when a task ships,
|
||
update or delete every cross-reference it made stale — BACKLOG
|
||
pitches/pointers, HARDWARE-QUEUE entries, docs — in the same commit.
|
||
No stale items, no unsynced information.
|
||
- **Git:** direct commits on `main`, pushed; **`v1` is human-only** —
|
||
never touch it. Never `nix flake update` unless the task is a lock bump.
|
||
No formatter — match aligned hand-formatting.
|
||
- Layout: `hosts/` machine · `modules/` distro · `themes/` data ·
|
||
`pkgs/` code · `tools/` maintainer · `agent/` loop · `docs/` human docs.
|
||
|
||
## Delegation & escalation
|
||
|
||
Push mechanical work down to cheaper models; keep judgment on the
|
||
strongest model available. Capability tiers, standing roles (scout /
|
||
runner), and per-harness model mappings: **`agent/DELEGATION.md`**.
|
||
Work above your tier? Return it — don't burn tokens.
|
||
|
||
## Harness adapters
|
||
|
||
One directory per harness, holding only what that harness *requires* in
|
||
its own format (permissions, subagent/skill registration). Adapters point
|
||
into `agent/`; they never carry policy, queue items, or vision text.
|
||
|
||
| Harness | Adapter |
|
||
|---------|---------|
|
||
| Claude Code | `.claude/` — `CLAUDE.md` is a symlink to this file |
|
||
| others | add a sibling dir + a row here; keep it a thin shim |
|