Cross-tool adoption. Codex, Gemini Code Assist, and any AI tool honouring
the AGENTS.md convention can now read the same instructions as Claude,
without the user maintaining two files by hand.
hooks/claude-to-agents.py (new, standalone, idempotent):
- argparse: --mode={symlink,copy,inline-chain} (default symlink),
--source (default CLAUDE.md), --output (default AGENTS.md), --force.
- Symlink mode: ln -s CLAUDE.md AGENTS.md. Windows falls back to
--copy with a stderr notice.
- Copy mode: byte-for-byte snapshot via shutil.copyfile.
- Inline-chain mode: depth-first walk of @path imports, recursive,
cycle-safe (each file read at most once). Output flattens every
chained sub-file under <!-- inlined from <rel> --> markers and
strips two flavours of Claude-only scaffolding:
• The @path import lines themselves (other tools don't resolve
them).
• Backlink quote-blocks ("> Parent context: ..." /
"> Chained import: `@../CLAUDE.md`") that we emit on every
sub-CLAUDE.md.
- Safety: existing AGENTS.md (file or symlink) is renamed to
AGENTS.md.backup.<UTC-ts> before overwrite. --force skips the
backup. Microsecond timestamp precision so back-to-back writes
don't collide.
- Exit codes: 0 success, 1 user error (missing source / unknown
mode), 2 filesystem error (symlink failure).
command/claude-to-agents.md (new slash command):
- allowed-tools: Read, Write, Glob, Bash(python3:*), Bash(ls:*),
Bash(test:*), Bash(readlink:*).
- disallowedTools: WebFetch, WebSearch (no exfiltration vector).
- argument-hint and when_to_use surface the three modes.
- Body specifies a heuristic: default to --symlink for single-file
projects, recommend --inline-chain when find . -name CLAUDE.md
returns more than one. Documents per-mode verification commands.
.claude-plugin/plugin.json:
Registers ./command/claude-to-agents.md alongside the existing two.
install.sh + install.ps1:
Banner and uninstall sections list the new command. The command
install loop already iterates command/*.md so the file itself is
copied automatically.
README.md:
/claude-to-agents added to "What's Included" under Slash commands
with a one-paragraph description covering all three modes.
Quick Stats: "2 slash commands" -> "3 slash commands".
CHANGELOG.md:
New "wave 5" entry under [Unreleased].
Verified (7/7 integration checks):
- Plugin manifest registers the command; all 9 referenced paths
resolve on disk.
- Slash command frontmatter has all required fields including
WebFetch in disallowedTools.
- Script has executable bit set.
- Both install scripts list claude-to-agents.md.
- install.sh passes bash -n.
- End-to-end against a synthetic chained CLAUDE.md tree with a
deliberate back-import cycle: symlink mode creates valid symlink;
copy mode produces bytewise-identical AGENTS.md and backs up the
prior symlink (1 backup); inline-chain mode inlines both
sub-files, strips backlinks AND chain-import lines, handles the
cycle (each file read once), backs up the prior file (2 backups
total).
- Missing source returns rc=1 with stderr message.
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.
CRITICAL FIX:
- Save original directory before downloading from GitHub
- For project-level installation via curl/remote, install to original directory
- Prevents .claude/ folder from being created in temp directory and deleted
- Fixes both bash (install.sh) and PowerShell (install.ps1) installers
- Quality hooks also install to correct directory
Before: curl | bash with option 2 would install to temp dir and delete it
After: curl | bash with option 2 installs to directory where command was run
This fixes the issue where users couldn't see .claude/ after installation.
- Add automatic download from GitHub when files not present locally
- Support both local and remote installation modes
- Download v1.0.0 release tarball/zip automatically
- Clean up temporary files after remote installation
- Update both install.sh (macOS/Linux) and install.ps1 (Windows)
Now the one-line install works correctly:
curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash
Fixes#1 (if issue exists)
Claude
Alireza Rezvani
Alireza Rezvani