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

docs/ARCHITECTURE.md

@@ -211,9 +211,10 @@ def calculate_quality_score(self) → int:
 **Validation Categories:**
 
 1. **Length Validation**
-   - Recommended: 20-300 lines
-   - Warning: 300-400 lines (suggest modular)
-   - Error: < 20 or > 400 lines
+   - Recommended: 20–120 lines (sweet spot)
+   - Warning: 120–150 lines (approaching cap)
+   - **Hard cap: 150 lines** — enforced deterministically by `hooks/validate-claude-md.py` on `PostToolUse(Edit|Write)` *and* `InstructionsLoaded`. Files over the cap must be split into chained sub-CLAUDE.md files.
+   - Exempt: any file whose basename ends in `.local.md` (personal-tier override).
 
 2. **Structure Validation**
    - Required sections: Core Principles, Tech Stack, Workflow
@@ -432,9 +433,9 @@ Triggers update if:
 
 ### File Size Limits
 
-- Single file: Max 400 lines (prefer 300)
-- Modular files: Each 150-300 lines
-- Total project: Unlimited with modular
+- Every CLAUDE.md: hard cap 150 lines (no exceptions outside `*.local.md`).
+- Modular split via `@path/to/sub/CLAUDE.md` chain imports when content would exceed the cap.
+- Total project: unlimited via modular chaining + `.claude/rules/*.md` for path-scoped guidance.
 
 ### Caching Strategy
 

docs/CLAUDE.md

@@ -0,0 +1,112 @@
+> Parent context: see the root [CLAUDE.md](../CLAUDE.md) for project-wide guidelines and behavioural rules.
+> Chained import: `@../CLAUDE.md`
+
+# Installation, Testing & Release
+
+Operational guidance for installers, smoke tests, and release management.
+
+## Test Installation Scripts
+
+```bash
+# macOS/Linux
+./install.sh
+# Choose option 1 (user-level) or 2 (project-level)
+
+# Windows
+.\install.ps1
+# Same options as above
+
+# Verify after install:
+ls -la ~/.claude/skills/claudeforge-skill/
+ls -la ~/.claude/skills/karpathy-guidelines/
+ls -la ~/.claude/skills/claude-md-drift-audit/
+ls -la ~/.claude/skills/claude-md-link-check/
+ls -la ~/.claude/skills/claude-md-dependency-rescan/
+ls -la ~/.claude/commands/enhance-claude-md.md
+ls -la ~/.claude/commands/sync-claude-md.md
+ls -la ~/.claude/agents/claude-md-guardian.md
+```
+
+## Directory Layout After Install
+
+```
+~/.claude/                                  # user-level (project-level mirrors under ./.claude)
+├── skills/
+│   ├── claudeforge-skill/                  # from skill/
+│   │   ├── SKILL.md
+│   │   ├── analyzer.py
+│   │   ├── validator.py
+│   │   ├── generator.py
+│   │   ├── template_selector.py
+│   │   ├── workflow.py
+│   │   └── examples/
+│   └── karpathy-guidelines/                # from skill/karpathy-guidelines/
+│       └── SKILL.md
+├── commands/
+│   ├── enhance-claude-md.md
+│   └── sync-claude-md.md
+└── agents/
+    └── claude-md-guardian.md
+```
+
+## Smoke Test (run from repo root)
+
+```bash
+python3 - <<'PY'
+import sys; sys.path.insert(0, 'skill')
+from validator import BestPracticesValidator
+from template_selector import TemplateSelector
+from generator import ContentGenerator
+
+assert BestPracticesValidator.MAX_RECOMMENDED_LINES == 150
+for cfg in TemplateSelector.TEAM_SIZE_TEMPLATES.values():
+    assert cfg['target_lines'] <= 150
+
+ctx = {'type':'fullstack','tech_stack':['typescript','python'],
+       'team_size':'medium','phase':'production','workflows':['cicd']}
+out = ContentGenerator(ctx).generate_root_file()
+assert len(out.splitlines()) <= 150
+assert '## Behavioral Guidelines' in out
+print('smoke ok')
+PY
+```
+
+Run after any change to `skill/`, `command/`, or `agent/`.
+
+## Manual End-to-End Tests
+
+**Fresh project init:**
+1. `mkdir test-project && cd test-project && git init && npm init -y`
+2. Run `/enhance-claude-md`.
+3. Confirm generated CLAUDE.md ≤ 150 lines, contains `## Behavioral Guidelines`, has tech detection right.
+
+**Existing project enhance:**
+1. Seed `CLAUDE.md` with one short section.
+2. Run `/enhance-claude-md`; confirm quality score reported, missing sections proposed, `## Behavioral Guidelines` appended if absent.
+
+**Guardian agent sync:**
+1. Add a new dependency and create a new directory.
+2. Open a new Claude Code session — `SessionStart` fires.
+3. Confirm the agent updates Tech Stack / Project Structure and quality re-validates.
+
+**Sync command:**
+1. In a repo with stale CLAUDE.md references, run `/sync-claude-md`.
+2. Confirm stale lines flagged, 150-cap enforced via split, root ↔ sub chain repaired, diff left staged for the user.
+
+## Common Operations
+
+**Update a reference template:** edit `skill/examples/<name>-CLAUDE.md`, then add a matching scenario to `skill/sample_input.json`.
+
+**Update quality scoring:** edit `skill/analyzer.py` → `calculate_quality_score()`. Re-run the smoke test.
+
+**Update installer:** edit `install.sh` / `install.ps1` (paths, copy logic, backup logic, hooks). Test both user-level and project-level on a throwaway directory.
+
+## Release Process
+
+1. Update `CHANGELOG.md` under a new version header.
+2. Bump the version in `README.md`, `skill/SKILL.md`, and `.claude-plugin/plugin.json`.
+3. `git tag -a vX.Y.Z -m "Release vX.Y.Z"`.
+4. `git push origin vX.Y.Z`.
+5. Create the GitHub release with a CHANGELOG excerpt.
+
+Versioning is semver. See `docs/MIGRATION_V2.md` for the v1 → v2 upgrade path.

docs/INSTALLATION.md

@@ -173,7 +173,7 @@ examples/
 
 ```bash
 # macOS/Linux
-ls -la ~/.claude/commands/enhance-claude-md/
+ls -la ~/.claude/commands/enhance-claude-md.md ~/.claude/commands/sync-claude-md.md
 
 # Windows
 dir $env:USERPROFILE\.claude\commands\enhance-claude-md\

docs/QUICK_START.md

@@ -256,7 +256,7 @@ Claude, invoke claude-md-guardian to update CLAUDE.md
 
 ### Tip 1: Use Modular Architecture for Large Projects
 
-If your CLAUDE.md exceeds 300 lines, split it:
+If your CLAUDE.md approaches or exceeds the 150-line cap, split it (or run `/sync-claude-md` to split for you):
 
 ```bash
 /enhance-claude-md

docs/TROUBLESHOOTING.md

@@ -29,7 +29,7 @@ Common issues and solutions for ClaudeForge.
 2. **Verify installation paths:**
    ```bash
    # macOS/Linux
-   ls -la ~/.claude/commands/enhance-claude-md/
+   ls -la ~/.claude/commands/enhance-claude-md.md ~/.claude/commands/sync-claude-md.md
    ls -la ~/.claude/skills/claudeforge-skill/
    ls -la ~/.claude/agents/claude-md-guardian.md
 
@@ -119,7 +119,7 @@ Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
 2. **Check file length:**
    ```bash
    wc -l CLAUDE.md
-   # Recommended: 20-300 lines
+   # Hard cap: 150 lines. Sweet spot: 50-120.
    # If > 300: Consider modular architecture
    ```
 
@@ -173,7 +173,7 @@ Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
 
 **Symptoms:**
 - Single CLAUDE.md generated for large project
-- File exceeds 300 lines
+- File exceeds the 150-line cap (validator hook will surface this)
 
 **Causes:**
 - Project type not detected as `fullstack`