claude-plugins: generalize state-hygiene into a shared base plugin for all agents

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

@@ -7,9 +7,9 @@
   },
   "plugins": [
     {
-      "name": "state-hygiene",
+      "name": "base",
-      "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.",
+      "description": "hyperhive's base plugin - skills every agent needs, regardless of role. Currently: state-hygiene (read-before-write discipline and dated-archive convention for durable agent notes/state files). Add a new skill here (not a new plugin) if it applies to all agents; give it its own specialized plugin if it doesn't.",
-      "source": "./plugins/state-hygiene",
+      "source": "./plugins/base",
       "category": "productivity"
     }
   ]

claude-plugins/plugins/base/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "base",
+  "description": "hyperhive's base plugin - skills every agent needs, regardless of role.",
+  "author": {
+    "name": "hyperhive"
+  }
+}

claude-plugins/plugins/base/skills/state-hygiene/SKILL.md

@@ -0,0 +1,48 @@
+---
+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 `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.

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

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

nix/agent-modules/claude-settings.nix

@@ -265,7 +265,7 @@ in
     type = lib.types.listOf lib.types.str;
     default = [
       "skill-creator@claude-plugins-official"
-      "state-hygiene@hyperhive"
+      "base@hyperhive"
     ];
     example = [
       "formatter@my-marketplace"
@@ -283,16 +283,20 @@ in
 
       Defaults to Anthropic's `skill-creator` (teaches an agent to
       write, refine, and evaluate its own skills) plus hyperhive's own
-      `state-hygiene` skill (read-before-write + dated-archive
+      `base` plugin — one plugin bundling every skill that applies to
-      discipline for durable notes/state files) — agents get both out
+      *all* agents regardless of role (currently just `state-hygiene`,
-      of the box, matching the default marketplaces above.
+      read-before-write + dated-archive discipline for durable
+      notes/state files; more all-agent skills land as additional
+      skills inside this same plugin, not new plugins — a skill that
+      only some agents need gets its own specialized plugin instead).
+      Agents get both out of the box, matching the default
+      marketplaces above.
 
       Note that a per-agent definition REPLACES this default rather
       than extending it (ordinary NixOS list-option semantics, same as
       `claudeMarketplaces`). An agent that wants extra plugins AND the
-      defaults should list both
+      defaults should list both `skill-creator@claude-plugins-official`
-      `skill-creator@claude-plugins-official` and
+      and `base@hyperhive` alongside them.
-      `state-hygiene@hyperhive` alongside them.
     '';
   };