4c656b1e73
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>
3.2 KiB
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.mdand follow it — every change, however small, climbs its V0–V3 ladder. For theme or visual work, also readagent/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;v1is human-only — never touch it. Nevernix flake updateunless 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 |