claude-plugins: ship a hyperhive-authored notes-hygiene skill by default

claude-plugins/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "hyperhive",
+  "description": "hyperhive-authored Claude Code plugins, shipped hive-wide via the default hyperhive.claudeMarketplaces/claudePlugins nix options (nix/agent-modules/claude-settings.nix). Built as a nix store path and added with `claude plugin marketplace add <path>` - no forge repo or git remote needed. Add a new plugins/<name>/ subtree + one entry below to ship another.",
+  "owner": {
+    "name": "hyperhive"
+  },
+  "plugins": [
+    {
+      "name": "notes-hygiene",
+      "description": "Read-before-write discipline and dated-archive convention for durable agent notes/state files - use before archiving, overwriting, or pruning any notes/state file.",
+      "source": "./plugins/notes-hygiene",
+      "category": "productivity"
+    }
+  ]
+}

claude-plugins/plugins/notes-hygiene/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "notes-hygiene",
+  "description": "Read-before-write discipline and dated-archive convention for durable agent notes/state files.",
+  "author": {
+    "name": "hyperhive"
+  }
+}

claude-plugins/plugins/notes-hygiene/skills/notes-hygiene/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: notes-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.
+---
+
+# Notes Hygiene
+
+Durable notes/state files (your `CLAUDE.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**
+  (resolved/closed work, moved out of the hot path, never deleted).
+- Archive in **dated, per-topic chunks** - `YYYY-MM-DD-<topic>.md` - not one
+  ever-growing archive blob. `ls` on the archive dir 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).
+
+## Full convention
+
+The hive-wide version of these rules (read-only reference - don't duplicate
+it into your own notes) lives at `/knowledge/notes-hygiene.md`; read that for
+the complete rationale.