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:
@@ -2,12 +2,12 @@
|
||||
|
||||
How an AI agent works on Nomarchy unattended. One **iteration** = pick one
|
||||
task, do it, verify it, commit it, record it. The protocol is
|
||||
runner-agnostic; the same iteration works under any of:
|
||||
harness- and vendor-agnostic; the same iteration works under any of:
|
||||
|
||||
- **Interactive `/loop`** in a Claude Code session in this repo — the agent
|
||||
self-paces iterations until stopped.
|
||||
- **Headless** (`claude -p`, cron/systemd-timer) — one invocation runs one
|
||||
iteration (or a small fixed number) and exits.
|
||||
- **An interactive self-paced loop** in any agent harness (e.g. `/loop`
|
||||
in Claude Code) — the agent iterates until stopped.
|
||||
- **Headless** (a one-shot CLI invocation, cron/systemd-timer) — one
|
||||
invocation runs one iteration (or a small fixed number) and exits.
|
||||
- **A fresh manual session** — a human says "do a loop iteration"; the
|
||||
files below carry all the state, so any session can pick up where the
|
||||
last left off.
|
||||
@@ -26,23 +26,25 @@ outside the checkout (the distro's own philosophy, applied to its agents).
|
||||
| `HARDWARE-QUEUE.md` | Pending on-hardware checks only Bernardo can run | Agents append, human checks off |
|
||||
| `CONVENTIONS.md` | Repo/design conventions to follow while coding | Human (agents propose edits) |
|
||||
|
||||
Instructions live next to the state: `VERIFICATION.md` (enforcement),
|
||||
`DELEGATION.md` (tiers/roles/economy), `GOALS.md`, `THEME-DESIGN.md`.
|
||||
|
||||
## Model & token economy
|
||||
|
||||
Spend expensive tokens on judgment, not mechanics.
|
||||
Spend expensive tokens on judgment, not mechanics. Tiers, roles, and the
|
||||
full delegation rules are in **`DELEGATION.md`**; the loop-specific
|
||||
habits:
|
||||
|
||||
- **Plan and reason on the strong model.** Orientation, task selection,
|
||||
design, debugging, Nix eval semantics, verification judgment, and
|
||||
anything that would land in a commit unreviewed stay with the
|
||||
top-tier model running the loop (Fable 5).
|
||||
- **Delegate mechanical subtasks to cheaper models.** When a subtask is
|
||||
fully specified and needs no design judgment — grep/audit sweeps,
|
||||
frontier-tier model running the loop.
|
||||
- **Delegate mechanical subtasks down.** When a subtask is fully
|
||||
specified and needs no design judgment — grep/audit sweeps,
|
||||
README-option-table reconciliation, a repeated edit applied across
|
||||
files, summarizing long logs or check output — hand it to a subagent
|
||||
with a `model` override: `haiku` for search/summarize/audit, `sonnet`
|
||||
for routine well-specified edits. The strong model writes the spec,
|
||||
reviews the result, and owns the commit. Only delegate when writing
|
||||
the spec is cheaper than doing the work — a spawned agent starts cold
|
||||
and must re-derive context.
|
||||
files, summarizing long logs or check output — hand it to a
|
||||
light/standard-tier subagent per `DELEGATION.md`. The strong model
|
||||
writes the spec, reviews the result, and owns the commit.
|
||||
- **Read narrowly.** Step 0's list is the whole orientation read (the
|
||||
*last 3–5 entries* of the journal, never the full file). Read large
|
||||
files by section, don't re-read what's already in context, and tail
|
||||
@@ -50,7 +52,7 @@ Spend expensive tokens on judgment, not mechanics.
|
||||
- **Write tersely.** Journal entries follow the template and no more;
|
||||
commit bodies state what/why/tier, not a narrative.
|
||||
- **Headless runners** may run whole low-stakes iterations (QA sweeps,
|
||||
docs-drift passes) on a cheaper `--model`; iterations touching
|
||||
docs-drift passes) on a cheaper model; iterations touching
|
||||
`modules/` or `pkgs/` behavior keep the strong model.
|
||||
|
||||
## One iteration, step by step
|
||||
|
||||
Reference in New Issue
Block a user