docs(agent): vendor-neutral agent docs — AGENTS.md entry, agent/ SoT, .claude shims
All checks were successful
Check / eval (push) Successful in 4m28s
All checks were successful
Check / eval (push) Successful in 4m28s
The repo is maintained by agents from multiple vendors, so agent instructions move out of vendor-specific locations into shared, git-tracked markdown: - AGENTS.md is the new entry point for any harness; CLAUDE.md becomes a symlink to it (Claude Code keeps working unchanged). - Skill bodies relocate to agent/: VERIFICATION.md (the enforcement rules, ex .claude/skills/nomarchy), DELEGATION.md (capability tiers light/standard/frontier, scout/runner role contracts, token economy, parallel fan-out — consolidates the CLAUDE.md model table, LOOP.md's economy section, and skill §6.5 into one place; vendor model names survive only in the per-harness mapping table), THEME-DESIGN.md (ex .claude/skills/theme, which previously lacked frontmatter). - .claude/ shrinks to a thin Claude Code adapter: settings, subagent defs, and skill shims that route into agent/. - Maps updated: agent/README.md (instructions vs state vs adapters), docs/README.md, README.md layout tree. Cleanup: stale old_distro .gitignore entry dropped (dir long gone); local result*/__pycache__ artifacts removed; JOURNAL.md rotated (29 recent entries kept, 120 older moved to agent/JOURNAL-ARCHIVE.md, rotation rule documented in the header). Verification: V0 (docs/meta only) — nix flake check --no-build exit 0 with the tracked symlink; grep sweep confirms no vendor model names outside DELEGATION.md's mapping table. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Bernardo Magri
@@ -5,268 +5,18 @@ description: Development and maintenance workflow for the Nomarchy NixOS-based d
|
||||
|
||||
# Nomarchy Development Skill
|
||||
|
||||
Nomarchy's promise to its user: a rock-stable, fully functional, beautiful
|
||||
workstation that is reproducible, easy to recover, and never requires the
|
||||
user to become a Nix expert. Every rule below exists to protect that promise.
|
||||
A change that works but degrades stability, aesthetics, or user-simplicity is
|
||||
a regression, not a feature.
|
||||
This repo is maintained by agents from multiple vendors, so the skill
|
||||
body lives vendor-neutrally in the repo — this file only routes you
|
||||
there. Read, then follow:
|
||||
|
||||
## 0. Read the authoritative docs first
|
||||
1. **`AGENTS.md`** — entry point: where everything lives, standing rules
|
||||
2. **`agent/LOOP.md`** — the iteration protocol + the V0–V3 ladder
|
||||
3. **`agent/VERIFICATION.md`** — the enforcement rules: preflight, the
|
||||
honesty rules, the visual verification protocol, hardware-blocked
|
||||
checks, maintenance work, the reporting format
|
||||
4. **`agent/DELEGATION.md`** — capability tiers, the scout/runner roles
|
||||
(Claude Code defs: `.claude/agents/`), token economy, parallel fan-out
|
||||
|
||||
This skill is an enforcer, not the workflow itself. The workflow lives in the
|
||||
repo and is the single source of truth:
|
||||
|
||||
- `CLAUDE.md` — entry point, project conventions
|
||||
- `agent/LOOP.md` — the iteration loop and the V0–V3 verification ladder
|
||||
- `agent/` (remaining files) — philosophy, conventions, memory, backlog
|
||||
- `docs/TESTING.md` — VM instructions, the regression checklist, known
|
||||
environment gotchas
|
||||
|
||||
At the start of any work session in this repo, read `CLAUDE.md` and
|
||||
`agent/LOOP.md` before touching code. Read `docs/TESTING.md` before running
|
||||
any VM test. If this skill and those docs ever disagree, the repo docs win —
|
||||
then fix the discrepancy in the same or a follow-up commit so they can't
|
||||
disagree twice.
|
||||
|
||||
## 1. Preflight (once per session)
|
||||
|
||||
Before starting work, establish what verification tier this environment can
|
||||
reach, so you never promise verification you can't deliver:
|
||||
|
||||
1. Linux x86_64 host? `/dev/kvm` present and readable?
|
||||
2. Enough free disk for an image/ISO build (multi-GB)?
|
||||
3. Network access for a cold Nix store?
|
||||
|
||||
If the environment cannot reach V2 (no KVM, no disk, etc.): say so
|
||||
immediately, do the V0/V1 work honestly, mark the change **"V2 pending"**
|
||||
exactly as you would mark a hardware-blocked change "V3 pending" (see §4),
|
||||
and stop short of claiming the change is done. Never simulate, guess, or
|
||||
describe what a VM test "would" show.
|
||||
|
||||
## 2. The verification ladder (enforcement rules)
|
||||
|
||||
Climb the V0–V3 ladder as defined in `agent/LOOP.md`. This skill adds three
|
||||
non-negotiable enforcement rules on top:
|
||||
|
||||
1. **V2 is mandatory for anything user-visible.** If a user of the installed
|
||||
system could perceive the change — behavior, layout, colors, keybinds,
|
||||
timing, error messages — it must be exercised in the local VM before
|
||||
commit. Docs-only, comment-only, or agent-notes changes may stop at the
|
||||
tier LOOP.md assigns them; user-visible changes may not.
|
||||
2. **Every "done" report names the tier reached and shows the evidence.**
|
||||
Evidence means: the command run and its relevant output, the checklist
|
||||
items exercised, and for visual work the screenshots viewed (§3). "It
|
||||
builds" is a V1 claim, not a V2 claim. Never let a report imply a higher
|
||||
tier than was actually reached.
|
||||
3. **A failed or flaky test is a result, not an obstacle.** Distinguish real
|
||||
failures from environment flakes using the known-gotchas section of
|
||||
`docs/TESTING.md` (e.g. no-KVM slowness, missing guest GL). If you cannot
|
||||
confidently classify a failure, report it as unresolved — do not retry
|
||||
until green and report only the green run.
|
||||
4. **VM runs are headless and unattended.** Use the repo's headless
|
||||
harness — `tools/test-live-iso.sh` and `tools/test-install.sh` for
|
||||
boot/install runs, `tools/vm/qmp.py` for programmatic VM control and
|
||||
`tools/vm/vncshot.py` for screen capture — never a graphical VM window
|
||||
or any flow that needs a human at the console. The human is not part of
|
||||
the test loop: do not pause mid-run to ask them to look at the VM, click
|
||||
something, or confirm what is on screen. A run must complete on its own
|
||||
and leave auditable artifacts behind (logs, serial console output, exit
|
||||
codes, screenshots), with every wait bounded by a timeout so a hang
|
||||
becomes a recorded failure instead of a stalled session. Prefer scripted
|
||||
assertions (process up, file exists, service/D-Bus state, the checks in
|
||||
`tools/`) over eyeballing; where judgment is genuinely needed — visual
|
||||
quality — *you* view the captured screenshots (§3), not the human. The
|
||||
human reviews evidence in the final report, never the live run.
|
||||
|
||||
### Regression scope after a change
|
||||
|
||||
Re-running the full checklist for every change wastes VM time; running
|
||||
nothing invites regressions. Default rule:
|
||||
|
||||
- Always: the session-sanity items (boot to session, bar renders).
|
||||
- Plus: every checklist item touching the layer you changed.
|
||||
- Plus: the theming end-to-end item whenever theming plumbing changed,
|
||||
even indirectly (palette generation, symlinks, reload hooks).
|
||||
- Lock bumps and toolchain changes: run the full checklist — their blast
|
||||
radius is unknowable by construction.
|
||||
|
||||
## 3. Visual verification protocol
|
||||
|
||||
Visual quality is a core feature of Nomarchy, so "it probably looks fine" is
|
||||
never verification. A visual/UI change is not V2-verified until all of the
|
||||
following are true:
|
||||
|
||||
1. **Before/after screenshots** of the changed surface were captured
|
||||
headlessly — `tools/theme-shot.nix` for reproducible theme renders,
|
||||
`tools/vm/vncshot.py` (driven via `tools/vm/qmp.py`) for captures from a
|
||||
running VM. No VM window, no human interaction. Capture the "before"
|
||||
from the base branch or prior generation, not from memory.
|
||||
2. **Scripted checks first**: run `tools/check-theme-contrast.py` and
|
||||
`tools/audit-theme-design.py` against the affected theme(s) before any
|
||||
eyeballing — machine-checkable legibility/design violations should never
|
||||
survive to the human-judgment stage. Use `tools/vm/gap-analysis.py`
|
||||
where it applies.
|
||||
3. **Two themes**: repeat the "after" capture under at least two themes, one
|
||||
with a generated palette and one whole-swap theme (e.g. summer-night).
|
||||
These exercise different code paths in the bar/launcher theming; a change
|
||||
that looks right under one can silently break the other.
|
||||
4. **You actually viewed the images** — open the screenshot files and look
|
||||
at them. State concretely what you inspected: alignment, spacing,
|
||||
contrast/legibility against the palette, icon rendering, no clipped or
|
||||
overlapping elements, and that the change looks intentional next to the
|
||||
"before".
|
||||
5. Keep the screenshots in the run's working area and reference their paths
|
||||
in the report, so the human can audit the same evidence.
|
||||
|
||||
If the VM cannot render the surface faithfully (known GL/compositor gaps in
|
||||
the guest — see `docs/TESTING.md`), that specific visual aspect is
|
||||
hardware-blocked: verify everything the VM *can* show, and queue the rest
|
||||
per §4.
|
||||
|
||||
## 4. Hardware-blocked checks
|
||||
|
||||
Some checks genuinely require real hardware (GPU behavior, multi-monitor
|
||||
hotplug, audio devices, power/suspend, firmware). For those:
|
||||
|
||||
1. Add an entry to `agent/HARDWARE-QUEUE.md` with: what changed, **exact**
|
||||
reproduction steps a human can follow verbatim, the expected observation
|
||||
(what "pass" looks like), and the commit hash once known.
|
||||
2. Mark the commit body **"V3 pending: <one-line summary>"**.
|
||||
3. Say it plainly in your report. A hardware-blocked check is not a failure
|
||||
and not something to hide — hiding it is the failure.
|
||||
4. When the human reports back, close the queue entry in the next commit and
|
||||
record the outcome; if it failed on hardware, that's a new bug at the top
|
||||
of the backlog.
|
||||
|
||||
Do not use the hardware queue as an escape hatch: if a check *can* be done
|
||||
in the VM, it must be. "The VM is slow" does not qualify.
|
||||
|
||||
## 5. Maintenance work
|
||||
|
||||
Maintenance is in scope for this skill and follows the same ladder:
|
||||
|
||||
- **Flake lock bumps**: treat as maximum-blast-radius changes. Build,
|
||||
boot the VM, run the full regression checklist, and do a visual
|
||||
spot-check of the session (themes can shift with upstream package
|
||||
changes). Never merge a lock bump on "it evaluates".
|
||||
- **Theme imports / new themes**: import via `tools/import-palettes.py`,
|
||||
then the full §3 visual protocol; additionally verify the theme-switch
|
||||
round trip (into the new theme and back out).
|
||||
- **Docs drift**: run `tools/check-option-docs.py` after any change that
|
||||
adds or modifies options, and fix drift in the same commit as the code
|
||||
change that created it. Doc-only fixes are V0 — but verify any command
|
||||
you document by actually running it.
|
||||
- **Backlog grooming / agent-notes**: V0; keep entries consistent with the
|
||||
conventions in `agent/`.
|
||||
|
||||
## 6. Guarding the philosophy
|
||||
|
||||
Before committing, check the change against the distro's promises:
|
||||
|
||||
- **User is not a Nix expert.** If the change requires the user to write or
|
||||
read Nix to use the feature day-to-day, redesign it. Configuration the
|
||||
user touches must stay in the simple, documented surface the repo defines.
|
||||
- **Rock-stable and recoverable.** Prefer boring, reproducible mechanisms
|
||||
over clever ones. Any change that could break boot or the session must
|
||||
have an obvious rollback story (NixOS generations count, but say so).
|
||||
- **Aesthetics are load-bearing.** A functionally correct but visually
|
||||
regressive change fails review by definition — that's what §3 is for.
|
||||
|
||||
When a requested change conflicts with these promises, stop and raise the
|
||||
conflict instead of implementing it quietly.
|
||||
|
||||
## 6.5 Token economy: delegate machinery, keep judgment
|
||||
|
||||
Not every step needs the smartest model. Use subagents to route mechanical
|
||||
work to cheap models and keep expensive reasoning where it pays. The repo
|
||||
defines two in `.claude/agents/`:
|
||||
|
||||
- **nomarchy-scout** (haiku, read-only): finding where things are defined,
|
||||
mapping which files touch a subsystem, scanning build logs and serial
|
||||
output for error lines, docs-vs-code drift sweeps. Use it for any pure
|
||||
information-gathering step instead of reading files into the main
|
||||
context yourself — it keeps the main context small, which matters more
|
||||
than the token price on long loops.
|
||||
- **nomarchy-runner** (haiku, executes the harness): builds, VM boots,
|
||||
screenshot capture, the scripted `tools/` checks. It runs commands and
|
||||
returns exit codes, logs, and artifact paths — nothing more.
|
||||
|
||||
The dividing line is **evidence vs. judgment**. Cheap models gather
|
||||
evidence; they never make verification claims. The following always stay
|
||||
with the main (smart) model and are never delegated downward:
|
||||
|
||||
- deciding what to test and what the regression scope is (§2)
|
||||
- interpreting an ambiguous or flaky failure (§2 rule 3)
|
||||
- viewing screenshots and judging visual quality (§3) — aesthetic judgment
|
||||
is exactly the kind of work small models do badly, and it's load-bearing
|
||||
for this distro
|
||||
- writing non-trivial Nix (module structure, overlays, cross-cutting
|
||||
refactors)
|
||||
- the final review of the diff and the §7 report
|
||||
|
||||
Practical guidance: delegation is not free — each subagent has its own
|
||||
context and the tokens multiply — so delegate when the work is mechanical
|
||||
*or* would pollute the main context with bulk (log files, wide file
|
||||
scans), not reflexively for every small step. A one-file read is cheaper
|
||||
done directly. When a scout/runner result surprises you, spot-check it
|
||||
yourself before building on it: cheap models are allowed to be wrong about
|
||||
hard things, which is precisely why they're not allowed to make claims.
|
||||
|
||||
### Fanning out worktree agents (parallel V0/V1 work)
|
||||
|
||||
When several NEXT items are independent and don't need the VM, spread them
|
||||
across worktree-isolated subagents that run in parallel — but keep the
|
||||
token cost down with these habits (each is a real lever, not a nicety):
|
||||
|
||||
- **Match the model to the task, not the tier.** A backlog item whose spec
|
||||
is already written (exact files, exact fixes) is *well-specified* →
|
||||
**sonnet**, not opus. Reserve opus for genuine multi-step reasoning
|
||||
(novel Nix, cross-cutting design, an ambiguous failure). Haiku for bulk
|
||||
mechanical. Picking sonnet over opus for a spec'd task is the single
|
||||
biggest saving.
|
||||
- **Point at the spec; don't restate it.** The brief should say "the spec
|
||||
is in `agent/BACKLOG.md` #NN — implement it, don't re-derive," plus only
|
||||
the *constraints* (scope files, branch, no-VM, no-push). A cold agent
|
||||
re-reading the whole design into its own context is the tokens you're
|
||||
trying to avoid.
|
||||
- **Disjoint file lanes.** Partition the items so no two agents touch the
|
||||
same file (map the touched files first). Zero shared files = zero merge
|
||||
conflicts at landing = no reconciliation tokens. If two items must share
|
||||
a file (README, flake.nix, rofi.nix), give both to one agent or keep one
|
||||
for yourself.
|
||||
- **Isolation + you own landing.** Run each agent with `isolation:
|
||||
worktree`; it commits to its own branch and **never pushes or touches
|
||||
`main`/`v1`**. You review each diff, cherry-pick onto `main`, and do the
|
||||
bookkeeping. Parallel pushers race on `main`; a single landing agent
|
||||
doesn't. (Clean up: `git worktree remove --force` + `git branch -D` the
|
||||
branch and its `worktree-…` sibling after landing.)
|
||||
- **Lean on scriptable checks as the primary evidence.** Where a
|
||||
deterministic `tools/` check or a `checks.*` guard already proves the
|
||||
property (e.g. `check-theme-contrast.py` for a palette fix,
|
||||
`option-docs` for a doc row), that near-free run *is* the V0/V1
|
||||
evidence — don't spend a VM render to re-confirm what the script already
|
||||
asserts.
|
||||
- **Batch V2 at the end, once.** Visual/behavioural items delegated at
|
||||
V0/V1 come back "V2 pending." Don't boot the VM per item — collect the
|
||||
landed changes and do **one** `theme-shot`/`test-install` pass covering
|
||||
all of them. The VM render + screenshot review is the most expensive
|
||||
token sink in the loop; amortise it.
|
||||
- **Re-verify on `main`, but leanly.** After cherry-picking, confirm the
|
||||
agent's V0/V1 on the merged tree — but a tiny, obviously-correct diff
|
||||
needs a targeted build, not a full re-run of everything. Trust-but-spot-
|
||||
check scales; blind re-running doesn't.
|
||||
|
||||
The judgment that never delegates (§ above) still holds: *you* review every
|
||||
diff before it lands, and *you* make the product calls (a "finish vs.
|
||||
quarantine" decision is yours or Bernardo's, never a cheap agent's).
|
||||
|
||||
## 7. Reporting format
|
||||
|
||||
End every unit of work with a short report containing:
|
||||
|
||||
1. What changed (one paragraph, plain language).
|
||||
2. Verification tier reached, with evidence (commands + key output,
|
||||
checklist items run, screenshot paths viewed).
|
||||
3. Anything pending: "V2 pending" (environment) or "V3 pending" (hardware,
|
||||
with queue entry reference).
|
||||
4. Follow-ups added to the backlog, if any.
|
||||
Before running any VM test, also read **`docs/TESTING.md`**. The repo
|
||||
docs always win over any cached summary of them; if docs disagree with
|
||||
each other, fix the discrepancy in the same or a follow-up commit.
|
||||
|
||||
@@ -1,21 +1,12 @@
|
||||
---
|
||||
name: theme
|
||||
description: Theme design and visual work for Nomarchy — use whenever the user asks to create, update, refine, or troubleshoot themes or visual design (palettes, Hyprland looks, Waybar, Ghostty, btop, rofi, wallpapers, typography, icons).
|
||||
---
|
||||
|
||||
# Nomarchy Theme Designer Skill
|
||||
|
||||
**Trigger:** Use this skill whenever the user requests to create, update, refine, or troubleshoot themes and visual designs for the Nomarchy distribution.
|
||||
|
||||
## System Prompt / Instructions
|
||||
|
||||
You are an elite UI/UX designer and Linux ricing expert specializing in Wayland environments. Your role is to create cohesive, innovative, and visually stunning desktop themes for "Nomarchy," a custom Linux distribution based on NixOS and the Hyprland window manager.
|
||||
|
||||
### Context & Architecture
|
||||
All theme configurations for Nomarchy live inside the `themes/` directory at the root of the repository. Before generating any new configurations, you MUST read and analyze the existing files in this directory. Learn how the current themes are structured, how the syntax is formatted for each application, and how they are integrated into the broader NixOS configuration. Always match this established architectural pattern.
|
||||
|
||||
### Your Design Responsibilities
|
||||
1. **Holistic Design:** Develop unified themes that span across Hyprland (borders, shadows, animations), Waybar, Ghostty terminal, btop, fastfetch, Rofi/fuzzel, and desktop wallpapers.
|
||||
2. **Color Theory & Aesthetics:** Create or adapt advanced color palettes. You may draw inspiration from established aesthetics (e.g., Everforest, Nord, Gruvbox) or r/unixporn trends, but you should innovate. Ensure perfect harmony between background, foreground, accents, and warning/error colors.
|
||||
3. **Typography & Iconography:** Select and pair fonts (UI vs. Monospace) and icon themes that match the specific vibe of the color palette.
|
||||
4. **Accessibility:** Follow best practices for UI design. Ensure high contrast for text readability and avoid eye strain.
|
||||
|
||||
### Process
|
||||
1. Read the `themes/` directory to understand the codebase.
|
||||
2. Explain the "vibe," primary color palette (with hex codes), and typography choices of your proposed design.
|
||||
3. Implement the theme by generating or updating the necessary files within the `themes/` structure.
|
||||
The skill body lives vendor-neutrally in the repo — read and follow
|
||||
**`agent/THEME-DESIGN.md`**. Visual work additionally climbs the
|
||||
verification ladder and visual protocol in **`agent/VERIFICATION.md`**
|
||||
(scripted contrast/design checks first, then headless screenshots you
|
||||
actually view).
|
||||
|
||||
Reference in New Issue
Block a user