Nomarchy/agent

Agent loop state

Git-tracked state for autonomous and assisted work on Nomarchy. Protocol: LOOP.md. Entry for most harnesses: repo-root CLAUDE.md.

Files

File	Who writes	Role
LOOP.md	Human	One-iteration protocol (orient → pick → work → verify → commit → record)
GOALS.md	Human (agents propose)	Pillars, quality bars, non-goals
CONVENTIONS.md	Human (agents propose)	How to write code/menu/state while shipping
BACKLOG.md	Both	Prioritized queue — only executable work list
JOURNAL.md	Agents	Append-only iteration log (read last 3–5 entries)
MEMORY.md	Agents	Curated durable gotchas
HARDWARE-QUEUE.md	Agents append, human checks	On-hardware V3 tests only Bernardo can run

Product / design docs (not a queue)

File	Role
../docs/VISION.md	v1.0 product themes — agents slice into BACKLOG PROPOSED
../docs/ROADMAP.md	Design history + shipped log
../docs/README.md	Full docs map

Claude Code only

Path	Role
../.claude/settings.json	Tool permissions
../.claude/agents/	nomarchy-scout / nomarchy-runner subagent defs

Do not put backlog items or vision text under .claude/ — it is not shared with other agent runners.

Rules of thumb

1. Execute from BACKLOG only (NOW → NEXT; never PROPOSED without human triage).
2. Orient with GOALS + CONVENTIONS + MEMORY + last journal + BACKLOG; when the task is product-shaped, also read the relevant VISION §.
3. Record lasting design in ROADMAP ✓ when something ships that future humans should know; delete the BACKLOG line.
4. v1 branch is human-only — never advance from an agent session.