mirror of
https://github.com/alirezarezvani/ClaudeForge.git
synced 2026-07-03 18:33:16 -04:00
Claude
a45e6f5dbd
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.
116 lines
4.7 KiB
Markdown
116 lines
4.7 KiB
Markdown
---
|
|
description: Walk every CLAUDE.md in the project, prune stale references, enforce the 150-line cap, and re-chain root ↔ subdirectory files.
|
|
permissions:
|
|
allow:
|
|
- Bash(ls:*)
|
|
- Bash(find:*)
|
|
- Bash(git status:*)
|
|
- Bash(git diff:*)
|
|
- Bash(wc:*)
|
|
- Bash(grep:*)
|
|
- Bash(cat:*)
|
|
- Bash(test:*)
|
|
- Read
|
|
- Edit
|
|
- Write
|
|
- Glob
|
|
- Grep
|
|
- Skill
|
|
hooks:
|
|
- matcher: ""
|
|
once: true
|
|
commands:
|
|
- echo "Starting CLAUDE.md sync workflow"
|
|
---
|
|
|
|
# /sync-claude-md — CLAUDE.md Sync & Cleanup
|
|
|
|
This command keeps every CLAUDE.md in the project current, lean, and chained. Apply the Karpathy behavioural guidelines (`~/.claude/skills/karpathy-guidelines/SKILL.md`) while running it: state assumptions, keep changes surgical, define verification per step.
|
|
|
|
---
|
|
|
|
## Phase 1: Inventory
|
|
|
|
Discover every CLAUDE.md in the project (skipping vendor directories) and report sizes.
|
|
|
|
!`find . -name "CLAUDE.md" -type f -not -path "./node_modules/*" -not -path "./.git/*" -not -path "./vendor/*" -not -path "./dist/*" -not -path "./build/*" -print -exec wc -l {} \;`
|
|
|
|
Then capture the project signal that drives staleness checks:
|
|
|
|
!`ls -la package.json requirements.txt pyproject.toml go.mod Cargo.toml 2>/dev/null || true`
|
|
!`git status --short 2>/dev/null || echo "Not a git repository"`
|
|
!`git diff --name-status HEAD~10 -- . 2>/dev/null | head -50 || true`
|
|
|
|
---
|
|
|
|
## Phase 2: Per-File Audit
|
|
|
|
For each CLAUDE.md found, run the `claude-md-enhancer` skill's analyzer to compute:
|
|
|
|
- Current line count (hard cap: **150 lines**)
|
|
- Sections present and their freshness
|
|
- Anti-patterns (TODO/placeholder text, hardcoded secrets, generic content)
|
|
- References to files, directories, packages, or scripts that may be stale
|
|
|
|
Stale references to flag and remove unless the user objects:
|
|
|
|
1. **Dependency references** — packages mentioned in CLAUDE.md but absent from `package.json` / `requirements.txt` / `pyproject.toml` / `go.mod` / `Cargo.toml`.
|
|
2. **File / directory references** — paths in the project structure section that no longer exist on disk.
|
|
3. **Script references** — commands in Quick Reference / Common Operations that point to removed npm scripts or Makefile targets.
|
|
4. **Modular link targets** — `[Backend Guidelines](backend/CLAUDE.md)` or `@backend/CLAUDE.md` imports where the target file no longer exists.
|
|
5. **Version drift** — version numbers / "What's New in vX.Y" sections referencing releases older than what `CHANGELOG.md` shows as current.
|
|
|
|
For each finding, show the offending line(s) with file:line references before editing.
|
|
|
|
---
|
|
|
|
## Phase 3: Enforce the 150-Line Cap
|
|
|
|
Any CLAUDE.md exceeding 150 lines must be split. Prefer this order:
|
|
|
|
1. **Move detail to existing sub-files.** If `backend/CLAUDE.md` exists, push backend-specific content there.
|
|
2. **Create a new sub-file** in the appropriate directory (e.g. `database/CLAUDE.md`) using `claude-md-enhancer.generate_context_file()`. The generator automatically prepends a back-link to the root.
|
|
3. **Update the root file's navigation** — both the human-readable bullets and the `@path/to/CLAUDE.md` chain imports — using `claude-md-enhancer`.
|
|
|
|
After splitting, re-validate every modified file with `BestPracticesValidator` and confirm line count ≤ 150.
|
|
|
|
---
|
|
|
|
## Phase 4: Re-chain Root ↔ Sub Files
|
|
|
|
Verify the bidirectional chain:
|
|
|
|
- Root CLAUDE.md must contain a `Quick Navigation` block listing every existing sub-CLAUDE.md, plus a `@<relative-path>` import line for each.
|
|
- Every sub-CLAUDE.md must contain a back-link at the top pointing to `../CLAUDE.md` (or the correct relative path) with both a markdown link and a `@../CLAUDE.md` import.
|
|
|
|
Repair any missing or broken chain links. Remove chain entries for sub-files that have been deleted.
|
|
|
|
---
|
|
|
|
## Phase 5: Cleanup & Report
|
|
|
|
After edits, regenerate validator output for each file and show:
|
|
|
|
- Files modified
|
|
- Lines removed (stale content)
|
|
- Sections added / split / removed
|
|
- Final line count per file (must all be ≤ 150)
|
|
- Remaining warnings the user should review manually
|
|
|
|
Do not commit. Leave the diff staged-but-uncommitted so the user can review with `git diff` and choose when to commit.
|
|
|
|
---
|
|
|
|
## When to Run
|
|
|
|
- After completing a feature, major refactor, or dependency change.
|
|
- When `claude-md-guardian` flags drift on session start.
|
|
- Whenever any single CLAUDE.md grows past ~120 lines (warning threshold).
|
|
- Before cutting a release — keeps documentation truthful at the tag boundary.
|
|
|
|
## Companion Tools
|
|
|
|
- `/enhance-claude-md` — initialise or upgrade a CLAUDE.md when one is missing or thin.
|
|
- `claude-md-guardian` agent — runs sync automatically on session start when changes are detected.
|
|
- `karpathy-guidelines` skill — behavioural rules applied to every edit this command makes.
|