docs(agent): vendor-neutral agent docs — AGENTS.md entry, agent/ SoT, .claude shims
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
2026-07-11 08:58:25 +01:00
parent 37615c85a4
commit c0fc16e25c
15 changed files with 2382 additions and 2258 deletions

View File

@@ -1,52 +0,0 @@
# 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.
## Where things live (read this first)
| Path | Role |
|------|------|
| **`agent/`** | Loop state — **only executable queue is `BACKLOG.md`** |
| **`docs/VISION.md`** | Product themes toward **v1.0** (not a queue) |
| **`docs/ROADMAP.md`** | Design history + shipped log |
| **`docs/README.md`** | Full documentation map |
| **`agent/README.md`** | Map of loop files |
| **`.claude/`** | Claude Code only (permissions + subagents) — 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
- **Honesty rule** (`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`).
- **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
Push mechanical work down; keep judgment. Brief every child cold.
| Model | Best for | Delegate? | Effort |
|---|---|---|---|
| Haiku | bulk mechanical | never | low |
| Sonnet | scoped research | when it helps | medium |
| Opus 4.8 | multi-step reasoning | on clear benefit | xhigh |
| Fable 5 | judgment, taste | by default | medium |
Fable goes xhigh only for the hardest calls. Skip high.
## Escalation
An Opus parent can spawn a Fable child for one hard call. Work above your
tier? Return it — don't burn tokens.

1
CLAUDE.md Symbolic link
View File

@@ -0,0 +1 @@
AGENTS.md