User-facing documentation drifted behind several waves of feature work
(plugin manifest, hooks, sync command, --weekly, audit skills, Karpathy
skill, CLAUDE.local.md tier, layered hook config). Refresh + fix one
real install bug. Surgical edits only — no rewrites.
README.md:
- "What's New" block now reflects the plugin manifest, --weekly,
InstructionsLoaded hook, AGENTS.md interop, CLAUDE.local.md tier,
layered hook config, and the fail-closed guardian.
- "What's Included" expanded from 5 numbered bullets to a structured
list grouping the 5 skills (incl. three forked audit skills),
2 slash commands, 1 agent, and 3 hook scripts.
- Components Deep Dive: /sync-claude-md and the guardian's fail-closed
contract now documented.
- Project Status: 1.0.0 -> 2.1.0; Quick Stats updated to reflect
actual component counts.
- Acknowledgments: attribution to MIT-licensed forrestchang and
shanraisshan source repos for adapted patterns.
docs/ARCHITECTURE.md, docs/QUICK_START.md, docs/TROUBLESHOOTING.md,
docs/INSTALLATION.md, examples/modular-setup.md, examples/integration-
examples.md:
- Every "20-300 lines" / ">300 lines" / "exceeds 300 lines" reference
rewritten to the actual 150-line hard cap.
- Every ls/Remove-Item path that pointed at the legacy
~/.claude/commands/enhance-claude-md/ bundle now points at the
top-level enhance-claude-md.md + sync-claude-md.md files.
- integration-examples.md line-bounds shell guard now uses 20..150.
docs/CLAUDE.md:
- Install-verify ls list extended with the three new audit-skill
directories so docs match what install.sh actually creates.
install.sh + install.ps1 (REAL FIX, not just docs):
- The three forked audit skills (claude-md-drift-audit, link-check,
dependency-rescan) were registered in plugin.json but never copied
by the direct-install path. Both installers now iterate over them
after the karpathy-guidelines block, mirroring the same backup +
nested-duplicate-cleanup pattern. Banner section and uninstall
instructions list all 5 skills.
Verified:
- All 5 CLAUDE.md files in this repo still <= 150 lines after edits.
- install.sh passes bash -n syntax check.
- Plugin manifest still resolves all 8 referenced paths on disk.
- README invariants present: 2.1.0, --weekly, hooks/hooks.json,
both source-repo attributions, three audit skill names.
- Stale-claim sweep: zero "20-300" / ">300" / "exceeds 300" refs
remain in docs/ or examples/.
Turns ClaudeForge into an installable Claude Code plugin and adds the
missing pieces for a clean lifecycle: hard line-cap enforcement, modular
chaining via @path imports, a sync/cleanup command, and Explore-agent
delegation for project discovery.
- .claude-plugin/plugin.json: plugin manifest registering both skills,
both commands, and the guardian agent (installable via /plugin marketplace
add alirezarezvani/ClaudeForge && /plugin install claudeforge)
- skill/validator.py: MAX_RECOMMENDED_LINES 300 -> 150 (warning at 120)
- skill/template_selector.py: target_lines capped at 150 across all
team sizes (solo 75 / small 100 / medium 125 / large 150) so any
single CLAUDE.md fits within the cap; bigger projects spread content
across modular sub-files
- skill/analyzer.py: length thresholds, quality scoring, and recommendations
rebased on the 150 cap (was 300/400)
- skill/generator.py: modular root now emits @path imports next to the
human-readable links; every sub-CLAUDE.md gets a back-link header
pointing to ../CLAUDE.md (markdown + @import) for bidirectional chaining
- command/sync-claude-md.md: new /sync-claude-md command that inventories
every CLAUDE.md, prunes stale references, enforces the 150 cap by
splitting into sub-files, and repairs the root <-> sub chain
- command/enhance-claude-md.md: discovery phase now delegates the deep
codebase scan to the Explore subagent to keep context lean
- install.sh / install.ps1: each command in command/ installs as its own
~/.claude/commands/<name>.md (legacy bundle backed up on upgrade)
- skill/SKILL.md, CLAUDE.md, README.md, CHANGELOG.md: docs updated for
the plugin install path, sync command, and new line cap
Verified via smoke test: validator constants, template targets, generator
output line counts across 5 presets (all <= 150), context files with
backlinks, @-import chain in modular root, idempotent merge_with_existing,
validator status transitions at the new cap, analyzer quality differential,
and plugin manifest JSON shape with all referenced paths existing on disk.
Claude
Alireza Rezvani
Alireza Rezvani