a429b30448
Claude Code (>= 2.1.277) and opencode both read AGENTS.md, but Claude
Code reads it only when no CLAUDE.md exists in its cwd or above. So
this is a plain rename with no CLAUDE.md stub left behind.
- hive-agent/src/agents_md_migrate.rs: new. At harness start, before
the first turn, renames state/CLAUDE.md to state/AGENTS.md when only
the former exists; logs an error naming both paths when both exist
and touches neither; does nothing otherwise. Idempotent.
- hive-agent/src/main.rs: calls it in serve_main; checkpoint prompt
and a comment name AGENTS.md.
- hive-agent/src/claude_md_watch.rs: the size watch reads AGENTS.md;
todo text, doc comments and tests follow. Module name, todo
subsystem key ("claude_md") and metric name
(hyperhive.agent.claude_md.lines) are unchanged so existing todo
rows and dashboard history carry over.
- hive-agent/src/turn.rs, hive-agent/prompts/system.md: prompts tell
the agent its file is AGENTS.md.
- hive-agent/src/{otel_turn_metrics,stats}.rs,
frontend/packages/agent/src/stats.js, hive-subagent-mcp/src/*.rs:
comments and a tool parameter description naming the agent's file.
- nix/host-modules/swarm-grafana/dashboards/agents.json: panel title
and description.
- claude-plugins skills claude-subagents, state-hygiene: they mean the
agent's own state file.
- CLAUDE.md -> AGENTS.md at the repo root; docs/crates/README.md link
(checked by check-doc-refs.sh), hive-c0re/README.md,
.prettierignore and the nix/sources.nix comment follow.
- docs/: every prose mention of the agent's file; persistence.md
documents the boot-time rename, claude-invocation.md the shadowing.
Fixes #5509
49 lines
3 KiB
Markdown
49 lines
3 KiB
Markdown
---
|
|
name: state-hygiene
|
|
description: Enforces safe handling of an agent's own durable state/notes files (e.g. state/notes.md, state/TODO.md, or anything else under state/ meant to survive a container restart) - read the file before archiving, overwriting, or pruning it, split resolved work into small dated archive files instead of growing one giant live file, and never shell-pipe-append (>>) into a notes file. Use this whenever you are about to write to a durable notes/state file, especially right before a context-compaction checkpoint, when told to "flush state" or "write down anything relevant", or when a live notes file has grown large and needs an archive pass.
|
|
---
|
|
|
|
# State Hygiene
|
|
|
|
Durable notes/state files (your `AGENTS.md`, `state/notes.md`, `state/TODO.md`,
|
|
and anything else under `state/`) are your memory across container resets and
|
|
context compactions. They only work if you actually read them before you
|
|
change them - writing blind is how history gets silently destroyed or
|
|
duplicated.
|
|
|
|
## Before writing to any durable notes file
|
|
|
|
1. **Read it first.** Never overwrite or append to a notes/state file based
|
|
on memory or assumption of its current contents - the file may have moved
|
|
on since your last read (another turn, another agent touched shared
|
|
space, a prior session ended mid-edit). Read (or re-read the relevant
|
|
section) immediately before editing.
|
|
2. **Never pipe-append.** Don't do `echo "..." >> state/notes.md` (or
|
|
equivalent) from a shell command. That's a blind write with no chance to
|
|
see - and reconcile with - what's already there. Use your file-edit tool
|
|
(read, then edit/write) instead.
|
|
3. **Prefer a targeted edit over a full rewrite** for anything long-lived: an
|
|
edit is less likely to accidentally clobber unrelated content than
|
|
regenerating the whole file from your current context.
|
|
|
|
## Keeping a notes file lean
|
|
|
|
- Split into a **live file** (only what's currently active/gated/relevant -
|
|
this is what you re-read every turn, keep it short) and an **archive
|
|
subdirectory** (e.g. `state/notes-archive/`) for resolved/closed work,
|
|
moved out of the hot path, never deleted. Don't drop archived files
|
|
loose at the top level of `state/` alongside the live files - a
|
|
dedicated subdir keeps `ls state/` showing only what's live.
|
|
- Archive in **dated, per-topic chunks** - `YYYY-MM-DD-<topic>.md` - not one
|
|
ever-growing archive blob. `ls` on the archive subdir should read like a
|
|
timeline.
|
|
- When you finish a piece of work, collapse its entry in the live file to a
|
|
one-line "done" summary and move the full detail into a new dated
|
|
archive file.
|
|
- A live file well past ~500 lines (or into four figures) is overdue for an
|
|
archive pass - do it at a natural checkpoint (finishing a task, a
|
|
context-compaction prompt, or whenever you notice it).
|
|
|
|
If your environment ships its own hive-wide/repo-wide notes convention doc,
|
|
treat that as the canonical source and this skill as a reminder to follow
|
|
it - don't duplicate its rationale into your own notes either.
|