feat: ClaudeForge 2.1.0 — installable plugin with 150-line cap, forked audit skills, /sync --weekly, and AGENTS.md export (#26)

agent/CLAUDE.md

@@ -0,0 +1,75 @@
+> Parent context: see the root [CLAUDE.md](../CLAUDE.md) for project-wide guidelines and behavioural rules.
+> Chained import: `@../CLAUDE.md`
+
+# Guardian Agent Development
+
+Guidelines for the `claude-md-guardian` background-maintenance agent.
+
+## File
+
+`agent/claude-md-guardian.md` — installs to `~/.claude/agents/claude-md-guardian.md`.
+
+## Modifying the Agent
+
+1. Edit `agent/claude-md-guardian.md`.
+2. YAML frontmatter fields to preserve:
+   - `permissions: [Bash, Read, Write, Edit, Grep, Glob, Skill]`
+   - `model: haiku` — token efficiency for routine sync runs.
+   - `color: purple` — visual indicator in Claude Code UI.
+   - `fork_safe: true` — agent runs independently.
+   - `hooks: [SessionStart, PreToolUse, PostToolUse]`.
+3. Workflow phases inside the agent:
+   - **Assessment** — read `git diff` / `git status` / changed-file counts.
+   - **Analysis** — decide if changes are significant enough to update CLAUDE.md.
+   - **Update** — invoke the skill for targeted section updates rather than full regeneration (~70–80% token saving vs. rewrite).
+4. Re-install for testing: `cp agent/claude-md-guardian.md ~/.claude/agents/`.
+
+## v2.0.0+ Frontmatter Reference
+
+Hooks use Anthropic's canonical keyed-object schema (event → array of `{ matcher, hooks: [{ type, command }] }`):
+
+```yaml
+hooks:
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/validate-claude-md.py"
+  InstructionsLoaded:
+    - matcher: "session_start|nested_traversal|path_glob_match|include|compact"
+      hooks:
+        - type: command
+          command: "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/validate-claude-md.py"
+```
+
+The array-of-`{event, commands}` shape used in earlier versions did not match the documented schema and silently did not fire.
+
+## Skill ↔ Agent Integration
+
+The agent uses `claude-md-enhancer` (the skill's frontmatter name; installed as `claudeforge-skill/`) as its core capability. Invoke it with `Skill: claude-md-enhancer` inside the agent workflow.
+
+Hook responsibilities:
+
+- **SessionStart** — check `git diff`; if significant drift is detected, invoke the skill for an incremental update.
+- **PreToolUse** — validate before a CLAUDE.md edit lands.
+- **PostToolUse** — after `Edit`/`Write` to any CLAUDE.md, the plugin-level `hooks/hooks.json` runs `hooks/validate-claude-md.py`. The script exits `2` with stderr feedback when the file is over 150 lines; the guardian then proposes a `/sync-claude-md` run.
+- **InstructionsLoaded** — same script fires on every `load_reason` (`session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact`), so the cap is enforced deterministically at load time, not just at write time.
+
+## Agent ↔ Git
+
+The agent watches for change signals via:
+
+```bash
+git diff --name-status HEAD~10
+git log --since="1 week ago" --oneline --no-merges
+git diff HEAD~10 -- package.json requirements.txt pyproject.toml go.mod Cargo.toml
+```
+
+Triggers an update when any of these hold:
+
+- 5+ files modified since the last sync.
+- New dependencies added to a manifest file.
+- New top-level directories created (potential new sub-CLAUDE.md candidates).
+- Manual invocation after a milestone or release.
+
+When the agent runs sync, it follows `command/sync-claude-md.md`: never commit, leave the diff for the user to review.

agent/claude-md-guardian.md

@@ -16,18 +16,26 @@ field: documentation
 expertise: intermediate
 fork_safe: true
 hooks:
-  - event: SessionStart
-    commands:
-      - echo "Guardian: Checking for CLAUDE.md updates..."
-    once: false
-  - event: PreToolUse
-    matcher: Write
-    commands:
-      - echo "Guardian: Validating CLAUDE.md changes..."
-  - event: PostToolUse
-    matcher: Write
-    commands:
-      - echo "Guardian: CLAUDE.md update complete"
+  SessionStart:
+    - matcher: ""
+      hooks:
+        - type: command
+          command: "echo 'Guardian: checking for CLAUDE.md drift on session start'"
+  PreToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "echo 'Guardian: validating CLAUDE.md change'"
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "python3 ${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR}}/hooks/validate-claude-md.py"
+  InstructionsLoaded:
+    - matcher: "session_start|nested_traversal|path_glob_match|include|compact"
+      hooks:
+        - type: command
+          command: "python3 ${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR}}/hooks/validate-claude-md.py"
 ---
 
 # CLAUDE.md Guardian Agent
@@ -233,8 +241,14 @@ The slash command can invoke me:
 
 ## Safety & Validation
 
-**Critical Validation Rule**:
-"Always validate your output against official native examples before declaring complete."
+**Fail-closed contract** (non-negotiable):
+
+- I invoke `claude-md-enhancer` exclusively through the **Skill tool**. I never read its `SKILL.md` body and act on a paraphrase of it — paraphrase drift is the most common silent-degradation mode for auto-CLAUDE.md tooling.
+- If the skill returns no validated output (missing required sections, validator status ≠ `pass`, or any thrown exception), I **abort the run** and leave the existing CLAUDE.md tree untouched. Partial writes are worse than stale documentation.
+- I never commit on my own. Every change lands in the working tree only; the user reviews `git diff` and chooses when to commit.
+- I respect `hooks/hooks-config.local.json`. If a developer has disabled the validator locally, I treat the cap as advisory for that machine but still warn on the Stop hook.
+
+**Critical Validation Rule**: validate every emitted file against the reference templates in `skill/examples/` and the canonical schema before declaring success.
 
 **My validation checklist**:
 - ✅ Project Structure diagram present
@@ -242,6 +256,8 @@ The slash command can invoke me:
 - ✅ Architecture section reflects actual patterns
 - ✅ Tech Stack lists all major dependencies
 - ✅ Common Commands match package.json scripts
+- ✅ Every emitted CLAUDE.md ≤ 150 lines (cap waived only for `*.local.md`)
+- ✅ Every sub-CLAUDE.md back-links to root; root has matching `@`-imports
 
 ## Installation