mirror of
https://github.com/alirezarezvani/ClaudeForge.git
synced 2026-07-03 02:13:15 -04:00
feat: ClaudeForge 2.1.0 — installable plugin with 150-line cap, forked audit skills, /sync --weekly, and AGENTS.md export (#26)
This commit is contained in:
Alireza Rezvani
GitHub
@@ -0,0 +1,38 @@
|
||||
> Parent context: see the root [CLAUDE.md](../CLAUDE.md) for project-wide guidelines and behavioural rules.
|
||||
> Chained import: `@../CLAUDE.md`
|
||||
|
||||
# Slash Command Development
|
||||
|
||||
Guidelines for the `/enhance-claude-md` and `/sync-claude-md` slash commands.
|
||||
|
||||
## Files
|
||||
|
||||
- `command/enhance-claude-md.md` — interactive initialise / enhance workflow.
|
||||
- `command/sync-claude-md.md` — walks every CLAUDE.md, prunes stale references, enforces the 150-line cap, repairs the root ↔ sub chain.
|
||||
|
||||
Both install as top-level `~/.claude/commands/<name>.md` so they register as `/enhance-claude-md` and `/sync-claude-md`. There is no `enhance-claude-md/` bundle directory anymore — legacy bundles are backed up automatically on upgrade.
|
||||
|
||||
## Modifying `/enhance-claude-md`
|
||||
|
||||
1. Edit `command/enhance-claude-md.md`.
|
||||
2. Key phases:
|
||||
- **Phase 1 (Discovery)** — bash inventory + Explore-subagent delegation for deep codebase walks. Keep the calling session's context lean.
|
||||
- **Phase 2 (Analysis)** — branches initialise (no CLAUDE.md) vs. enhance (CLAUDE.md exists).
|
||||
- **Phase 3 (Task)** — invokes the `claude-md-enhancer` skill or `claude-md-guardian` agent.
|
||||
3. Always-on requirement: every generated/enhanced CLAUDE.md must include `## Behavioral Guidelines`. The skill inserts it automatically — do not strip it.
|
||||
4. Re-install for testing: `./install.sh` (project-level) or copy the file manually to `~/.claude/commands/enhance-claude-md.md`.
|
||||
5. Restart Claude Code (commands hot-reload, but restart guarantees a clean state) and test.
|
||||
|
||||
## Modifying `/sync-claude-md`
|
||||
|
||||
1. Edit `command/sync-claude-md.md`.
|
||||
2. Phases: inventory → per-file audit → enforce 150-line cap (split into sub-files via `generator.generate_context_file()`) → re-chain root ↔ subs → cleanup report.
|
||||
3. Sync should never commit on its own; leave the diff staged-but-uncommitted for the user.
|
||||
|
||||
## Skill ↔ Slash Command Integration
|
||||
|
||||
`command/enhance-claude-md.md` Phase 3 invokes the skill by name:
|
||||
|
||||
> I can invoke the `claude-md-enhancer` skill directly to handle the appropriate workflow based on what I discovered above.
|
||||
|
||||
Claude Code resolves `claude-md-enhancer` from the YAML frontmatter `name:` field in `skill/SKILL.md` (kept for backwards compatibility — the installed directory is `claudeforge-skill/`).
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
description: Convert the project's CLAUDE.md (and chained sub-files) into an AGENTS.md for Codex / Gemini Code Assist / other tools that follow the AGENTS.md convention. Three modes — symlink for one source of truth, copy for a snapshot, inline-chain for a self-contained flat file that doesn't depend on @-import resolution.
|
||||
argument-hint: "[--symlink | --copy | --inline-chain] [--force]"
|
||||
when_to_use: |
|
||||
Use when the user asks "make an AGENTS.md", "support codex", "support gemini",
|
||||
"convert CLAUDE.md", "share my instructions with non-Claude tools", or when
|
||||
adopting ClaudeForge in a repo that already has cross-tool contributors.
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Write
|
||||
- Glob
|
||||
- "Bash(python3:*)"
|
||||
- "Bash(ls:*)"
|
||||
- "Bash(test:*)"
|
||||
- "Bash(readlink:*)"
|
||||
disallowedTools:
|
||||
- WebFetch
|
||||
- WebSearch
|
||||
permissions:
|
||||
allow:
|
||||
- Read
|
||||
- Write
|
||||
- Glob
|
||||
- "Bash(python3:*)"
|
||||
- "Bash(ls:*)"
|
||||
- "Bash(test:*)"
|
||||
- "Bash(readlink:*)"
|
||||
---
|
||||
|
||||
# /claude-to-agents — convert CLAUDE.md → AGENTS.md
|
||||
|
||||
Wraps `hooks/claude-to-agents.py` so non-Claude tools (OpenAI Codex, Gemini Code Assist, anything else honouring the `AGENTS.md` convention) can read the same instructions as Claude.
|
||||
|
||||
## Mode selection
|
||||
|
||||
Decide first by asking which guarantee the user wants:
|
||||
|
||||
- **`--symlink`** (default on macOS / Linux): `AGENTS.md` becomes a symlink to `CLAUDE.md`. One source of truth — edits to CLAUDE.md show up in AGENTS.md instantly. Codex/Gemini read it transparently. On Windows the script falls back to `--copy` and prints a notice.
|
||||
- **`--copy`**: byte-for-byte snapshot. Use when the user wants to fork the instructions for non-Claude tooling (Codex/Gemini reading a different policy) or when their VCS / build pipeline doesn't follow symlinks.
|
||||
- **`--inline-chain`**: walk every `@path/.../CLAUDE.md` chain import recursively and write a single flat AGENTS.md with all sub-file content inlined. **Recommended for Codex/Gemini in modular projects** — those tools don't resolve `@`-imports, so without inlining they'd only see the root file.
|
||||
|
||||
If the user is silent on mode, default to `--symlink` for simple projects and recommend `--inline-chain` for projects with > 1 CLAUDE.md (run `find . -name CLAUDE.md -type f -not -path '*/.git/*' -not -path '*/node_modules/*' | wc -l` first to decide).
|
||||
|
||||
## Execution
|
||||
|
||||
1. **Pre-flight.** `test -f CLAUDE.md` — if missing, tell the user `/enhance-claude-md` is the right command first.
|
||||
2. **Run the script** with the chosen flags from the repo root:
|
||||
```bash
|
||||
python3 "${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/hooks/claude-to-agents.py" --mode <mode>
|
||||
```
|
||||
3. **Report.** Echo whether AGENTS.md was created or backed up, its size, and which mode produced it.
|
||||
4. **Verify** the result:
|
||||
- For `--symlink`: `readlink AGENTS.md` should print `CLAUDE.md`.
|
||||
- For `--copy`: `diff -q CLAUDE.md AGENTS.md` should return clean.
|
||||
- For `--inline-chain`: AGENTS.md must contain content from every chained sub-file; the script strips backlinks and `@`-import lines automatically.
|
||||
|
||||
## Safety
|
||||
|
||||
- An existing `AGENTS.md` is renamed to `AGENTS.md.backup.<UTC-timestamp>` before overwrite. Pass `--force` to skip the backup (destructive).
|
||||
- The script never writes outside the current directory tree.
|
||||
- Read-only modes (`--symlink`) leave CLAUDE.md untouched.
|
||||
@@ -1,18 +1,34 @@
|
||||
---
|
||||
description: Initialize or enhance CLAUDE.md files using the claude-md-enhancer skill with interactive workflow and 100% native format compliance
|
||||
description: Initialize or enhance a CLAUDE.md (and chained sub-CLAUDE.md files) for the current project using the claude-md-enhancer skill. Delegates deep codebase scans to the Explore subagent and stays within the 150-line cap.
|
||||
argument-hint: "[--init | --enhance | <path-to-CLAUDE.md>]"
|
||||
when_to_use: |
|
||||
Use whenever a project has no CLAUDE.md, when an existing one is over 150 lines,
|
||||
when an /init result needs to be hardened against context bloat, or when a repo
|
||||
already uses AGENTS.md / .cursorrules / .windsurfrules and you want a Claude-
|
||||
aware root that chains to them via @-imports instead of overwriting.
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Edit
|
||||
- Write
|
||||
- Glob
|
||||
- Grep
|
||||
- Skill
|
||||
- "Bash(ls:*)"
|
||||
- "Bash(find:*)"
|
||||
- "Bash(git status:*)"
|
||||
- "Bash(git diff:*)"
|
||||
- "Bash(wc:*)"
|
||||
disallowedTools:
|
||||
- WebFetch
|
||||
- WebSearch
|
||||
permissions:
|
||||
allow:
|
||||
- Bash(ls:*)
|
||||
- Bash(find:*)
|
||||
- Bash(git status:*)
|
||||
- "Bash(ls:*)"
|
||||
- "Bash(find:*)"
|
||||
- "Bash(git status:*)"
|
||||
- Read
|
||||
- Glob
|
||||
- Skill
|
||||
hooks:
|
||||
- matcher: ""
|
||||
once: true
|
||||
commands:
|
||||
- echo "Starting CLAUDE.md enhancement workflow"
|
||||
---
|
||||
|
||||
# CLAUDE.md Enhancer Command
|
||||
@@ -39,6 +55,20 @@ This command uses the `claude-md-enhancer` skill to initialize or enhance CLAUDE
|
||||
|
||||
!`ls -la`
|
||||
|
||||
### Check for sibling agent / rule files
|
||||
|
||||
If `AGENTS.md`, `.cursorrules`, or `.windsurfrules` exists, ClaudeForge will preserve it and chain it from the root CLAUDE.md via `@AGENTS.md` (or the equivalent) instead of overwriting. Detect them now:
|
||||
|
||||
!`for f in AGENTS.md .cursorrules .windsurfrules; do [ -f "$f" ] && echo "found: $f ($(wc -l < "$f") lines)" || echo "absent: $f"; done`
|
||||
|
||||
### Deep project scan via Explore agent
|
||||
|
||||
For non-trivial repositories, delegate the codebase walk to the **Explore** subagent so the discovery does not bloat this command's context window. Ask it a single, scoped question — for example:
|
||||
|
||||
> Walk this repository and report: project type (web_app / api / fullstack / cli / library / mobile / desktop), languages and frameworks detected, primary tech stack files (package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml), team-size indicators (number of contributors, CODEOWNERS), workflow indicators (.github/workflows, Dockerfile, CI configs), and any subdirectories that warrant their own CLAUDE.md (backend/, frontend/, database/, docs/, .github/). Return findings as a compact JSON object. Under 250 words.
|
||||
|
||||
Use the **general-purpose** subagent only for research that requires synthesising findings across multiple agents (e.g. comparing detected stack against template registry). Keep agent prompts self-contained and ask for short, structured reports.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Analysis - Determine Action
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
---
|
||||
description: Walk every CLAUDE.md in the project, prune stale references (removed deps, deleted paths, broken modular links), enforce the 150-line cap by splitting into sub-files, and repair the root ↔ subdirectory chain (markdown links + @path imports).
|
||||
argument-hint: "[--weekly | --dry-run | --paths-only | <directory>]"
|
||||
when_to_use: |
|
||||
Run after refactors, dependency changes, deleted directories, or when any single
|
||||
CLAUDE.md is near the 150-line cap. Use --weekly for a periodic audit pass that
|
||||
parallel-invokes the drift-audit, link-check, and dependency-rescan forked skills
|
||||
before doing the normal sync work. Also run before cutting a release so the
|
||||
documentation tag-snapshot is truthful.
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Edit
|
||||
- Write
|
||||
- Glob
|
||||
- Grep
|
||||
- Skill
|
||||
- "Bash(ls:*)"
|
||||
- "Bash(find:*)"
|
||||
- "Bash(git status:*)"
|
||||
- "Bash(git diff:*)"
|
||||
- "Bash(wc:*)"
|
||||
- "Bash(grep:*)"
|
||||
- "Bash(cat:*)"
|
||||
- "Bash(test:*)"
|
||||
disallowedTools:
|
||||
- WebFetch
|
||||
- WebSearch
|
||||
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
|
||||
---
|
||||
|
||||
# /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 0: Weekly Audit (only when `--weekly` is passed)
|
||||
|
||||
When the user invokes `/sync-claude-md --weekly`, run the three audit skills in parallel via the **Skill tool** before touching any file. Each is forked (`context: fork`, `agent: Explore`) so its work happens in an isolated context and only the summary returns:
|
||||
|
||||
1. `Skill(claude-md-drift-audit)` — references against last 7 days of git history.
|
||||
2. `Skill(claude-md-link-check)` — `@path` imports and markdown links resolve.
|
||||
3. `Skill(claude-md-dependency-rescan)` — Tech Stack sections vs. manifest files.
|
||||
|
||||
Issue all three in a single message so they execute concurrently. Wait for all three to return, then aggregate their findings into one report at the top of this run — `## Weekly Audit Summary` with one subsection per skill. If any audit returns findings, proceed to Phase 1 with those findings in mind so the sync work resolves them. If all three are clean, skip to Phase 4 (chain repair) — no edits required.
|
||||
|
||||
When `--weekly` is not passed, skip this phase entirely and start at Phase 1.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user