ClaudeForge/docs/MIGRATION_V2.md

Migrating to ClaudeForge v2.0 (Claude Code v2.1.4+)

Overview

ClaudeForge v2.0 adds support for Claude Code v2.1.4+ features including hooks, modern permission syntax, and hot-reload capabilities.

What Changed

Permissions Syntax

Before (v1.x):

tools: Bash, Read, Write
allowed-tools: Bash(ls:*), Read, Glob

After (v2.0):

permissions:
  allow:
    - Bash
    - Read
    - Write
    - Glob

Guardian Agent Hooks

The guardian agent now responds to lifecycle events:

• SessionStart: Checks for CLAUDE.md updates when Claude Code starts
• PreToolUse/PostToolUse: Validates changes before/after writing

Example hook configuration:

hooks:
  - event: SessionStart
    commands:
      - echo "Guardian: Checking for CLAUDE.md updates..."
    once: false

Hot-Reload

Skills now reload automatically when modified in Claude Code 2.1.0+ (no restart needed).

Fork-Safe Mode

Guardian agent now includes fork_safe: true to run independently without blocking other operations.

---

Migration Steps

1. Backup Your Existing Installation

# macOS/Linux
cp -r ~/.claude/skills/claudeforge-skill ~/.claude/skills/claudeforge-skill.backup
cp -r ~/.claude/commands/enhance-claude-md ~/.claude/commands/enhance-claude-md.backup
cp ~/.claude/agents/claude-md-guardian.md ~/.claude/agents/claude-md-guardian.md.backup

# Windows
Copy-Item -Path "$env:USERPROFILE\.claude\skills\claudeforge-skill" -Destination "$env:USERPROFILE\.claude\skills\claudeforge-skill.backup" -Recurse
Copy-Item -Path "$env:USERPROFILE\.claude\commands\enhance-claude-md" -Destination "$env:USERPROFILE\.claude\commands\enhance-claude-md.backup" -Recurse
Copy-Item -Path "$env:USERPROFILE\.claude\agents\claude-md-guardian.md" -Destination "$env:USERPROFILE\.claude\agents\claude-md-guardian.md.backup"

2. Run the Installer

# macOS/Linux
./install.sh

# Windows
.\install.ps1

The installer will:

• ✅ Detect your Claude Code version
• ✅ Automatically backup v1.x installations
• ✅ Install v2.0 with updated syntax
• ✅ Validate v2.1.4 compatibility

3. Restart Claude Code

Restart Claude Code to activate the SessionStart hooks:

# Exit and restart
exit
claude

4. Test the Migration

# Test the slash command
/enhance-claude-md

# Or invoke the skill directly
"Please enhance my CLAUDE.md file"

You should see:

• ✅ "Starting CLAUDE.md enhancement workflow" (command hook)
• ✅ "Guardian: Checking for CLAUDE.md updates..." (on session start)

---

Troubleshooting

"Permission denied" errors

Cause: Incorrect permission syntax in YAML frontmatter

Solution:

1. Check that permissions.allow array is properly formatted
2. Verify indentation (2 spaces for YAML)
3. Ensure each tool is on its own line with - prefix

Example:

permissions:
  allow:
    - Read
    - Write
    - Bash(git:*)

Hooks not firing

Cause: Claude Code version < 2.1.0 or hook syntax errors

Solution:

1. Verify Claude Code version: claude --version
2. Upgrade if needed: claude update
3. Check hook syntax matches valid event types:
   • SessionStart
   • PreToolUse
   • PostToolUse
   • Stop
4. Restart Claude Code to register hooks

Guardian agent not auto-updating

Cause: SessionStart hook not triggered or git changes not detected

Solution:

1. SessionStart requires new session (restart Claude Code completely)
2. Verify git repository is initialized: git status
3. Check agent is installed: ls ~/.claude/agents/claude-md-guardian.md
4. Check for git changes: git diff HEAD~10 --name-status

"Invalid YAML" errors

Cause: Syntax errors in frontmatter

Solution:

1. Validate YAML syntax online: https://www.yamllint.com/
2. Check for proper indentation (spaces, not tabs)
3. Ensure colons are followed by spaces
4. Verify array syntax with - prefix

Version detection fails

Cause: claude command not in PATH

Solution:

1. Check Claude Code installation: which claude
2. Add to PATH if needed
3. Restart terminal
4. Re-run installer

---

Rollback

If you need to rollback to v1.x:

Option 1: Restore from Auto-Backup

The installer creates timestamped backups:

# List backups
ls ~/.claude/skills/claudeforge-skill.backup.*
ls ~/.claude/commands/enhance-claude-md.backup.*

# Restore (replace timestamp with your backup)
mv ~/.claude/skills/claudeforge-skill.backup.20260107_120000 ~/.claude/skills/claudeforge-skill
mv ~/.claude/commands/enhance-claude-md.backup.20260107_120000 ~/.claude/commands/enhance-claude-md
mv ~/.claude/agents/claude-md-guardian.md.backup.20260107_120000 ~/.claude/agents/claude-md-guardian.md

Option 2: Restore from Manual Backup

# Restore from your manual backup
rm -rf ~/.claude/skills/claudeforge-skill
rm -rf ~/.claude/commands/enhance-claude-md
rm ~/.claude/agents/claude-md-guardian.md

cp -r ~/.claude/skills/claudeforge-skill.backup ~/.claude/skills/claudeforge-skill
cp -r ~/.claude/commands/enhance-claude-md.backup ~/.claude/commands/enhance-claude-md
cp ~/.claude/agents/claude-md-guardian.md.backup ~/.claude/agents/claude-md-guardian.md

Option 3: Reinstall v1.0.0

# Download v1.0.0
curl -fsSL https://github.com/alirezarezvani/ClaudeForge/archive/refs/tags/v1.0.0.tar.gz | tar -xz
cd ClaudeForge-1.0.0
./install.sh

---

What's Backward Compatible

✅ Python Modules: All 5 Python modules (analyzer.py, validator.py, generator.py, template_selector.py, workflow.py) work with both v1.x and v2.0

✅ Skill Invocation: The skill name (claude-md-enhancer) remains the same

✅ Command Invocation: /enhance-claude-md command works identically

✅ Examples: All 7 reference CLAUDE.md templates are unchanged

✅ Functionality: All analysis, generation, and validation features work the same

What's Not Backward Compatible

❌ Frontmatter Syntax: Old tools: and allowed-tools: fields are deprecated (but gracefully degraded)

❌ Hooks: Only work with Claude Code 2.1.0+

❌ Hot-Reload: Only works with Claude Code 2.1.0+

❌ Fork-Safe Mode: Only works with Claude Code 2.1.0+

---

Feature Comparison

Feature	v1.0	v2.0 (Claude Code 2.1.4+)
CLAUDE.md Analysis	✅	✅
CLAUDE.md Generation	✅	✅
Quality Validation	✅	✅
Template Selection	✅	✅
Modular Architecture	✅	✅
Permission System	Old syntax	Modern permissions: syntax
Lifecycle Hooks	❌	✅ SessionStart, Pre/PostToolUse
Hot-Reload	❌	✅ Automatic
Fork-Safe Mode	❌	✅ Independent execution
Auto-Update on Session	❌	✅ Via SessionStart hook

---

Verification

After migration, verify your installation:

# Check file locations
ls -la ~/.claude/skills/claudeforge-skill/SKILL.md
ls -la ~/.claude/commands/enhance-claude-md/enhance-claude-md.md
ls -la ~/.claude/agents/claude-md-guardian.md

# Check for new syntax
grep "permissions:" ~/.claude/skills/claudeforge-skill/SKILL.md
grep "permissions:" ~/.claude/agents/claude-md-guardian.md

# Check for hooks
grep "hooks:" ~/.claude/agents/claude-md-guardian.md

# Test the command
claude
/enhance-claude-md

Expected output on session start:

Guardian: Checking for CLAUDE.md updates...

---

Getting Help

If you encounter issues during migration:

1. Check the logs: Look for error messages during installation
2. Verify version: Run claude --version to confirm Claude Code 2.1.0+
3. Review this guide: Double-check each step
4. Rollback if needed: Use one of the rollback options above
5. Report issues: https://github.com/alirezarezvani/ClaudeForge/issues

---

Additional Resources

• Claude Code Documentation
• Claude Code Hooks Guide
• ClaudeForge GitHub
• ClaudeForge Changelog