feat(v2.0.0): migrate to Claude Code v2.1.4+ architecture (#22)

CHANGELOG.md

@@ -9,16 +9,129 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+---
+
+## [2.0.0] - 2026-01-08
+
+### 🎉 Major Update: Claude Code v2.1.4+ Support
+
+ClaudeForge v2.0.0 modernizes the toolkit for Claude Code v2.1.4+ with hooks, modern permission syntax, and enhanced automation capabilities.
+
+### Added
+
+#### Claude Code v2.1.4+ Features
+- **Lifecycle Hooks**: Guardian agent now uses SessionStart, PreToolUse, and PostToolUse hooks for automatic maintenance
+  - SessionStart hook checks for CLAUDE.md updates on every new session
+  - PreToolUse hook validates changes before writing
+  - PostToolUse hook confirms successful updates
+- **Modern Permission Syntax**: All components migrated to `permissions:` array format
+  - Skill uses `permissions.allow:` array with wildcard support
+  - Command uses `permissions.allow:` with tool-specific wildcards
+  - Agent uses `permissions.allow:` with comprehensive tool access
+- **Fork-Safe Mode**: Guardian agent configured with `fork_safe: true` for independent execution
+- **Hot-Reload Support**: Skills automatically reload when modified (Claude Code 2.1.0+ feature)
+- **Version Detection**: Installers now detect Claude Code version and validate compatibility
+  - Warns if Claude Code < 2.1.0 (limited features)
+  - Recommends Claude Code 2.1.4+ for full functionality
+  - Exits if Claude Code < 2.0
+- **Auto-Migration System**: Automatic migration from v1.x with timestamped backups
+  - Detects v1.x installations using syntax analysis
+  - Creates dated backups before upgrading
+  - Validates v2.1.4 compatibility after installation
+
+#### Documentation
+- **Migration Guide**: Comprehensive `docs/MIGRATION_V2.md` with step-by-step instructions
+  - Covers permission syntax changes
+  - Documents hooks functionality
+  - Provides troubleshooting guide
+  - Includes rollback procedures
+- **Testing Scripts**: Complete test suite in `test/` directory
+  - `test/validate_migration.sh` - 18 automated validation tests
+  - `test/rollback.sh` - One-command rollback to v1.x
+  - `test/README.md` - Testing documentation and workflows
+  - `test/LOCAL_TESTING_GUIDE.md` - Step-by-step local testing guide
+- **Updated Documentation**: All docs now reference Claude Code v2.1.4+ features
+  - `CLAUDE.md` - Updated with v2.0.0 features and permission syntax examples
+  - `README.md` - Added "New in v2.0" section highlighting features
+
+### Changed
+
+- **Skill Frontmatter** (`skill/SKILL.md`):
+  - ~~`tools:` field~~ → `permissions.allow:` array
+  - Added wildcard Bash permissions: `Bash(ls:*)`, `Bash(find:*)`, `Bash(git:*)`
+
+- **Command Frontmatter** (`command/enhance-claude-md.md`):
+  - ~~`allowed-tools:` field~~ → `permissions.allow:` array
+  - Added startup hook for workflow initiation
+
+- **Agent Frontmatter** (`agent/claude-md-guardian.md`):
+  - ~~`tools:` field~~ → `permissions.allow:` array
+  - Added `fork_safe: true` for independent operation
+  - Added SessionStart hook for auto-updates
+  - Added PreToolUse/PostToolUse hooks for Write validation
+  - Removed obsolete `mcp_tools: none` field
+
+- **Installation Scripts**:
+  - `install.sh`: Added Claude Code version detection and validation
+  - `install.ps1`: Added Claude Code version detection and validation
+  - Both scripts now include post-installation compatibility checks
+
+- **Version Requirements**:
+  - **Minimum**: Claude Code 2.1.0
+  - **Recommended**: Claude Code 2.1.4+
+  - **Previous**: Claude Code 2.0+
+
 ### Fixed
-- **Installation Script:** Fixed bash syntax error in `install.sh` caused by missing quotes around color variables in `read -p` commands (#13)
+- **Installation Script:** Fixed bash syntax error in `install.sh` caused by missing quotes around color variables in `read -p` commands (#13, #19)
   - Added proper quoting around `${BLUE}` and `${NC}` variables in command substitution
   - Prevents "syntax error near unexpected token" during installation on macOS
-  - Affects lines 132 and 179 in install.sh
+  - Credit to @bartdorlandt for original fix
+
 - **CI Workflow:** Removed strict branch naming requirement for PRs into dev (#17)
   - Contributors can now use any branch name when creating PRs
   - Reduces friction for external contributors and fork PRs
   - Maintains PR title validation (Conventional Commits) for commit hygiene
 
+- **Compatibility**: All components now fully compatible with Claude Code v2.1.4+
+  - Hooks work correctly with SessionStart events
+  - Permission wildcards properly recognized
+  - Hot-reload enabled for skill modifications
+
+### Deprecated
+
+- **Old Permission Syntax**: `tools:` and `allowed-tools:` fields deprecated in favor of `permissions:`
+  - Still backward compatible for existing installations
+  - Migration guide provides upgrade path
+
+### Breaking Changes
+
+- **Minimum Claude Code Version**: Now requires Claude Code 2.1.0+ (was 2.0+)
+- **Frontmatter Syntax**: Old `tools:` and `allowed-tools:` syntax deprecated
+- **Users on Claude Code < 2.1.0**: Should remain on ClaudeForge v1.0.0
+
+### Migration
+
+👉 **Upgrading from v1.0.0?** See [docs/MIGRATION_V2.md](docs/MIGRATION_V2.md) for detailed migration instructions.
+
+**Quick Migration:**
+```bash
+# Backup first
+cp -r ~/.claude/skills/claudeforge-skill ~/.claude/skills/claudeforge-skill.backup
+
+# Run installer (auto-migrates)
+./install.sh
+
+# Restart Claude Code
+exit
+claude
+```
+
+### Notes
+
+- **Python Modules**: All 5 Python modules (analyzer.py, validator.py, generator.py, template_selector.py, workflow.py) remain unchanged and backward compatible
+- **Examples**: All 7 reference CLAUDE.md templates unchanged
+- **Functionality**: Core analysis, generation, and validation features identical to v1.0.0
+
 ---
 
 ## [1.0.0] - 2025-11-12

CLAUDE.md

@@ -14,6 +14,19 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ---
 
+## What's New in v2.0.0
+
+**Claude Code v2.1.4+ Support:**
+- **Lifecycle Hooks**: Guardian agent uses SessionStart, PreToolUse, PostToolUse hooks
+- **Modern Permissions**: Updated to `permissions:` array syntax
+- **Hot-Reload**: Skills auto-reload when modified (no restart needed)
+- **Fork-Safe Mode**: Guardian runs independently with `fork_safe: true`
+- **Auto-Migration**: Seamless upgrade from v1.x with automatic backups
+
+**Migration:** See `docs/MIGRATION_V2.md` for upgrading from v1.0.0.
+
+---
+
 ## Architecture
 
 ### Component Interaction Flow
@@ -152,15 +165,32 @@ When updating `claude-md-guardian` agent:
 
 1. Edit `agent/claude-md-guardian.md`
 2. Key YAML frontmatter fields:
-   - `tools`: Limited to Bash, Read, Write, Edit, Grep, Glob, Skill
+   - `permissions`: [Bash, Read, Write, Edit, Grep, Glob, Skill]
    - `model`: Set to `haiku` for token efficiency
    - `color`: Visual indicator (purple)
+   - `fork_safe`: Set to `true` for independent execution
+   - `hooks`: Array of lifecycle hooks (SessionStart, PreToolUse, PostToolUse)
 3. Agent workflow phases:
    - Phase 1: Assessment (check git changes)
    - Phase 2: Analysis (determine scope)
    - Phase 3: Update (invoke skill for targeted updates)
 4. Test: `cp agent/claude-md-guardian.md ~/.claude/agents/`
 
+**Example Agent Definition with v2.0.0 Syntax:**
+```yaml
+---
+name: claude-md-guardian
+permissions: [Bash, Read, Write, Edit, Grep, Glob, Skill]
+model: haiku
+color: purple
+fork_safe: true
+hooks:
+  - SessionStart
+  - PreToolUse
+  - PostToolUse
+---
+```
+
 ### Adding New Templates
 
 To add a new reference template (e.g., Rust, mobile):
@@ -382,11 +412,28 @@ Claude Code recognizes the skill name `claude-md-enhancer` and calls Python modu
 The agent uses the skill as its core capability:
 ```yaml
 # In agent/claude-md-guardian.md:
-tools: Bash, Read, Write, Edit, Grep, Glob, Skill
+permissions: [Bash, Read, Write, Edit, Grep, Glob, Skill]
+hooks:
+  - SessionStart  # Detects project changes on session start
+  - PreToolUse    # Validates before tool execution
+  - PostToolUse   # Validates after CLAUDE.md updates
 ```
 
 Agent invokes skill with: `Skill: claude-md-enhancer` in agent workflow.
 
+**Example Hook Usage:**
+```markdown
+# When SessionStart hook triggers:
+1. Check git diff for changes
+2. If significant changes detected → invoke skill
+3. Update CLAUDE.md automatically
+
+# When PostToolUse hook triggers after Edit/Write to CLAUDE.md:
+1. Validate updated content with validator.py
+2. Report quality score
+3. Suggest improvements if needed
+```
+
 ### Agent ↔ Git
 
 Agent detects changes via git commands:
@@ -448,15 +495,15 @@ When updating references:
 
 ## Version Management
 
-**Current Version:** 1.0.0 (see CHANGELOG.md)
+**Current Version:** 2.0.0 (see CHANGELOG.md)
 **Versioning:** Semantic Versioning (MAJOR.MINOR.PATCH)
 
 When releasing new version:
 1. Update `CHANGELOG.md` with changes under new version header
 2. Update version in `README.md` badge
 3. Update version in `skill/SKILL.md` bottom section
-4. Create git tag: `git tag -a v1.1.0 -m "Release v1.1.0"`
+4. Create git tag: `git tag -a v2.1.0 -m "Release v2.1.0"`
-5. Push tag: `git push origin v1.1.0`
+5. Push tag: `git push origin v2.1.0`
 6. Create GitHub release with CHANGELOG excerpt
 
 ---

README.md

@@ -3,8 +3,8 @@
 > **Automated CLAUDE.md creation, enhancement, and maintenance for Claude Code projects**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/alirezarezvani/ClaudeForge/releases)
+[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/alirezarezvani/ClaudeForge/releases)
-[![Claude Code](https://img.shields.io/badge/Claude_Code-2.0%2B-purple.svg)](https://claude.com/claude-code)
+[![Claude Code](https://img.shields.io/badge/Claude_Code-2.1.4%2B-purple.svg)](https://claude.com/claude-code)
 [![CI/CD](https://img.shields.io/badge/CI/CD-GitHub_Actions-2088FF.svg)](https://github.com/alirezarezvani/ClaudeForge/actions)
 [![Quality Gates](https://img.shields.io/badge/Quality_Gates-Automated-success.svg)](docs/GITHUB_WORKFLOWS.md)
 
@@ -12,6 +12,19 @@ ClaudeForge is a comprehensive toolkit that eliminates the tedious process of ma
 
 ---
 
+## 🆕 New in v2.0 (Claude Code v2.1.4+ Support)
+
+- **Lifecycle Hooks**: Guardian agent automatically checks for updates at session start using SessionStart hooks
+- **Modern Permissions**: All components now use `permissions:` syntax for fine-grained control
+- **Hot-Reload**: Skills automatically reload when modified (no restart needed)
+- **Fork-Safe Mode**: Guardian runs independently with `fork_safe: true` without blocking operations
+- **Version Detection**: Installers validate Claude Code version and ensure compatibility
+- **Auto-Migration**: Seamless upgrade from v1.x with automatic backups
+
+👉 **Upgrading from v1.x?** See [docs/MIGRATION_V2.md](docs/MIGRATION_V2.md) for migration guide.
+
+---
+
 ## ✨ Features
 
 - 🚀 **Interactive Initialization** - Explores your repository, detects project context, and creates customized CLAUDE.md files through conversational workflow

agent/README.md

@@ -45,7 +45,7 @@ Available in all your Claude Code projects:
 
 ```bash
 # Copy agent to user directory
-cp generated-agents/claude-md-guardian/claude-md-guardian.md ~/.claude/agents/
+cp agent/claude-md-guardian.md ~/.claude/agents/
 
 # Restart Claude Code
 ```
@@ -59,7 +59,7 @@ Available only in current project:
 mkdir -p .claude/agents
 
 # Copy agent
-cp generated-agents/claude-md-guardian/claude-md-guardian.md .claude/agents/
+cp agent/claude-md-guardian.md .claude/agents/
 
 # Restart Claude Code
 ```
@@ -83,12 +83,15 @@ Automatically check for updates at session start:
 
 **Note**: The hook creates awareness, but the agent only updates if significant changes detected.
 
+**v2.0.0 Update**: Hooks now support advanced features like `run_in_background`, environment variables, and conditional execution. See [docs/MIGRATION_V2.md](../docs/MIGRATION_V2.md) for details.
+
 ## Prerequisites
 
 **Required**:
-- `claude-md-enhancer` skill must be installed
+- `claudeforge-skill` must be installed
-  - User-level: `~/.claude/skills/claude-md-enhancer/`
+  - User-level: `~/.claude/skills/claudeforge-skill/`
-  - Project-level: `.claude/skills/claude-md-enhancer/`
+  - Project-level: `.claude/skills/claudeforge-skill/`
+  - **v2.0.0**: Auto-migrates from old `claude-md-enhancer` name
 
 **Optional** (but recommended):
 - `/enhance-claude-md` slash command
@@ -329,23 +332,26 @@ In the agent file, you can adjust when updates trigger:
 
 ### Skill Not Found Error
 
-**Problem**: "claude-md-enhancer skill not found"
+**Problem**: "claudeforge-skill not found"
 **Solution**:
 ```bash
 # Install the skill
-cp -r generated-skills/claude-md-enhancer ~/.claude/skills/
+cp -r skill ~/.claude/skills/claudeforge-skill/
 # Restart Claude Code
+# Note: v2.0.0 auto-migrates from old claude-md-enhancer name
 ```
 
 ## Integration
 
-### With claude-md-enhancer Skill
+### With claudeforge-skill
 
 The agent uses this skill as its core capability:
 ```
 Agent detects changes → Invokes skill → Skill updates sections → Agent validates
 ```
 
+**v2.0.0**: Uses new `permissions:` syntax for tool access control.
+
 ### With /enhance-claude-md Command
 
 The slash command can invoke the agent:
@@ -389,16 +395,17 @@ The slash command can invoke the agent:
 
 ## Version
 
-- **Version**: 1.0.0
+- **Version**: 2.0.0
-- **Last Updated**: November 2025
+- **Last Updated**: January 2026
-- **Compatible**: Claude Code 2.0+
+- **Compatible**: Claude Code 2.1.4+
-- **Dependencies**: claude-md-enhancer skill v1.0.0+
+- **Dependencies**: claudeforge-skill v2.0.0+
+- **Migration**: See [docs/MIGRATION_V2.md](../docs/MIGRATION_V2.md) for upgrade guide
 
 ## Related Resources
 
-- **Skill**: `generated-skills/claude-md-enhancer/`
+- **Skill**: `skill/` (claudeforge-skill)
-- **Slash Command**: `generated-commands/enhance-claude-md/`
+- **Slash Command**: `command/` (enhance-claude-md)
-- **Agent File**: `generated-agents/claude-md-guardian/claude-md-guardian.md`
+- **Agent File**: `agent/claude-md-guardian.md`
 
 ---
 

agent/claude-md-guardian.md

@@ -1,12 +1,33 @@
 ---
 name: claude-md-guardian
 description: Background agent that maintains and updates CLAUDE.md files based on project changes. Invoked at session start and after major milestones (feature completion, refactoring, new dependencies, architecture changes). Works independently without interrupting other agents.
-tools: Bash, Read, Write, Edit, Grep, Glob, Skill
+permissions:
+  allow:
+    - Bash
+    - Read
+    - Write
+    - Edit
+    - Grep
+    - Glob
+    - Skill
 model: haiku
 color: purple
 field: documentation
 expertise: intermediate
-mcp_tools: none
+fork_safe: true
+hooks:
+  - event: SessionStart
+    commands:
+      - echo "Guardian: Checking for CLAUDE.md updates..."
+    once: false
+  - event: PreToolUse
+    matcher: Write
+    commands:
+      - echo "Guardian: Validating CLAUDE.md changes..."
+  - event: PostToolUse
+    matcher: Write
+    commands:
+      - echo "Guardian: CLAUDE.md update complete"
 ---
 
 # CLAUDE.md Guardian Agent

command/README.md

@@ -9,6 +9,7 @@ Initialize or enhance CLAUDE.md files using the `claude-md-enhancer` skill with
 - **Quality Analysis**: For existing projects, analyzes current CLAUDE.md and provides actionable recommendations
 - **100% Native Format Compliance**: Generates files with project structure diagrams, setup instructions, architecture sections
 - **Modular Architecture Support**: Creates context-specific CLAUDE.md files (backend/, frontend/, database/)
+- **v2.0.0**: Enhanced hooks support with background execution and conditional triggers
 
 ## Installation
 
@@ -16,17 +17,17 @@ Initialize or enhance CLAUDE.md files using the `claude-md-enhancer` skill with
 
 ```bash
 # Copy command to your project
-cp -r generated-commands/enhance-claude-md /path/to/your/project/.claude/commands/
+cp -r command /path/to/your/project/.claude/commands/
 
 # Or create symlink
-ln -s $(pwd)/generated-commands/enhance-claude-md /path/to/your/project/.claude/commands/enhance-claude-md
+ln -s $(pwd)/command /path/to/your/project/.claude/commands/enhance-claude-md
 ```
 
 ### Option 2: User-Level (All Projects)
 
 ```bash
 # Copy command to user commands directory
-cp -r generated-commands/enhance-claude-md ~/.claude/commands/
+cp -r command ~/.claude/commands/
 
 # Restart Claude Code
 ```
@@ -140,9 +141,10 @@ The command follows the **Multi-Phase Pattern** (similar to `codebase-analyze`):
 ## Prerequisites
 
 **Required**:
-- `claude-md-enhancer` skill must be installed
+- `claudeforge-skill` must be installed
-  - Project-level: `.claude/skills/claude-md-enhancer/`
+  - Project-level: `.claude/skills/claudeforge-skill/`
-  - User-level: `~/.claude/skills/claude-md-enhancer/`
+  - User-level: `~/.claude/skills/claudeforge-skill/`
+  - **v2.0.0**: Auto-migrates from old `claude-md-enhancer` name
 
 **Recommended**:
 - Git repository (for better context detection)
@@ -184,7 +186,7 @@ The command follows the **Multi-Phase Pattern** (similar to `codebase-analyze`):
 
 ## Output
 
-The command can invoke either the `claude-md-enhancer` skill directly OR the `claude-md-guardian` agent (recommended for maintenance).
+The command can invoke either the `claudeforge-skill` directly OR the `claude-md-guardian` agent (recommended for maintenance).
 
 ### Option A: Direct Skill Invocation
 
@@ -316,9 +318,10 @@ Proceed?
 
 ### "Skill not found" error
 
-**Solution**: Install the `claude-md-enhancer` skill first:
+**Solution**: Install the `claudeforge-skill` first:
 ```bash
-cp -r generated-skills/claude-md-enhancer ~/.claude/skills/
+cp -r skill ~/.claude/skills/claudeforge-skill/
+# Note: v2.0.0 auto-migrates from old claude-md-enhancer name
 ```
 
 ### Command not recognized
@@ -350,11 +353,26 @@ Discovery → Analysis → Task
     ↓
 Invokes claude-md-guardian (agent)
     ↓
-Agent uses claude-md-enhancer (skill)
+Agent uses claudeforge-skill (skill)
     ↓
 CLAUDE.md updated and synchronized
 ```
 
+**v2.0.0 Enhancement**: Hooks can now trigger background validation checks. Example:
+
+```json
+{
+  "hooks": {
+    "AfterCommit": {
+      "command": "/enhance-claude-md",
+      "run_in_background": true,
+      "timeout": 10000,
+      "description": "Validate CLAUDE.md after commits"
+    }
+  }
+}
+```
+
 ### When to Use the Agent
 
 **Via this command**:
@@ -369,21 +387,22 @@ CLAUDE.md updated and synchronized
 - Silent if no significant changes
 - Updates only when needed
 
-**See**: `generated-agents/claude-md-guardian-README.md` for complete agent documentation
+**See**: [agent/README.md](../agent/README.md) for complete agent documentation
 
 ## Related Resources
 
-- **Skill Documentation**: `generated-skills/claude-md-enhancer/README.md`
+- **Skill Documentation**: [../skill/README.md](../skill/README.md)
-- **Skill Examples**: `generated-skills/claude-md-enhancer/examples/`
+- **Skill Examples**: [../skill/examples/](../skill/examples/)
-- **Agent Documentation**: `generated-agents/claude-md-guardian-README.md`
+- **Agent Documentation**: [../agent/README.md](../agent/README.md)
 - **Official Slash Command Reference**: `documentation/references/slash-command-update-claude-md-example.md`
 
 ## Version
 
-- **Version**: 1.0.0
+- **Version**: 2.0.0
-- **Last Updated**: November 2025
+- **Last Updated**: January 2026
-- **Compatible**: Claude Code 2.0+
+- **Compatible**: Claude Code 2.1.4+
-- **Dependencies**: claude-md-enhancer skill v1.0.0+
+- **Dependencies**: claudeforge-skill v2.0.0+
+- **Migration**: See [docs/MIGRATION_V2.md](../docs/MIGRATION_V2.md) for upgrade guide
 
 ---
 

command/enhance-claude-md.md

@@ -1,6 +1,18 @@
 ---
-allowed-tools: Bash(ls:*), Bash(find:*), Bash(git status:*), Read, Glob, Skill
 description: Initialize or enhance CLAUDE.md files using the claude-md-enhancer skill with interactive workflow and 100% native format compliance
+permissions:
+  allow:
+    - 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

docs/MIGRATION_V2.md

@@ -0,0 +1,311 @@
+# 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):**
+```yaml
+tools: Bash, Read, Write
+allowed-tools: Bash(ls:*), Read, Glob
+```
+
+**After (v2.0):**
+```yaml
+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:
+```yaml
+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
+
+```bash
+# 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
+```
+
+```powershell
+# 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
+
+```bash
+# macOS/Linux
+./install.sh
+```
+
+```powershell
+# 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:
+
+```bash
+# Exit and restart
+exit
+claude
+```
+
+### 4. Test the Migration
+
+```bash
+# 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:
+```yaml
+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:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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](https://code.claude.com/docs)
+- [Claude Code Hooks Guide](https://code.claude.com/docs/en/hooks)
+- [ClaudeForge GitHub](https://github.com/alirezarezvani/ClaudeForge)
+- [ClaudeForge Changelog](https://github.com/alirezarezvani/ClaudeForge/blob/main/CHANGELOG.md)

install.ps1

@@ -1,6 +1,6 @@
 # ClaudeForge Installer for Windows
 # PowerShell installation script
-# Version: 1.0.0
+# Version: 2.0.0
 
 #Requires -Version 5.1
 
@@ -36,7 +36,7 @@ Write-Host "ClaudeForge Installer" -NoNewline -ForegroundColor Green
 Write-Host "         ║" -ForegroundColor Blue
 Write-Host "║                                        ║" -ForegroundColor Blue
 Write-Host "║  Automated CLAUDE.md Management Tool   ║" -ForegroundColor Blue
-Write-Host "║            Version 1.0.0               ║" -ForegroundColor Blue
+Write-Host "║            Version 2.0.0               ║" -ForegroundColor Blue
 Write-Host "║                                        ║" -ForegroundColor Blue
 Write-Host "╚════════════════════════════════════════╝" -ForegroundColor Blue
 Write-Host ""
@@ -53,10 +53,10 @@ if (-not (Test-Path "skill") -or -not (Test-Path "command") -or -not (Test-Path
     $TempDir = New-Item -ItemType Directory -Path ([System.IO.Path]::Combine([System.IO.Path]::GetTempPath(), [System.Guid]::NewGuid().ToString())) -Force
     Set-Location $TempDir
 
-    Write-Info "Downloading ClaudeForge v1.0.0..."
+    Write-Info "Downloading ClaudeForge v2.0.0..."
 
     # Download archive
-    $archiveUrl = "https://github.com/alirezarezvani/ClaudeForge/archive/refs/tags/v1.0.0.zip"
+    $archiveUrl = "https://github.com/alirezarezvani/ClaudeForge/archive/refs/heads/main.zip"
     $archivePath = Join-Path $TempDir "claudeforge.zip"
 
     try {
@@ -68,7 +68,7 @@ if (-not (Test-Path "skill") -or -not (Test-Path "command") -or -not (Test-Path
 
     Write-Info "Extracting files..."
     Expand-Archive -Path $archivePath -DestinationPath $TempDir -Force
-    Set-Location (Join-Path $TempDir "ClaudeForge-1.0.0")
+    Set-Location (Join-Path $TempDir "ClaudeForge-main")
 
     Write-Success "Downloaded ClaudeForge successfully"
 }
@@ -86,6 +86,50 @@ if (-not (Test-Path $claudeDir)) {
     Write-Success "Directory structure created"
 }
 
+# Check Claude Code version
+function Check-ClaudeCodeVersion {
+    $version = $null
+
+    try {
+        $output = & claude --version 2>&1
+        if ($output -match '\d+\.\d+\.\d+') {
+            $version = $matches[0]
+        }
+    } catch {
+        Write-Warning "Could not detect Claude Code version"
+        Write-Info "ClaudeForge v2.0 requires Claude Code 2.1.0 or later"
+        Write-Info "Continuing with installation (compatibility not guaranteed)"
+        return $true
+    }
+
+    if ([string]::IsNullOrEmpty($version)) {
+        Write-Warning "Could not detect Claude Code version"
+        Write-Info "Continuing with installation (compatibility not guaranteed)"
+        return $true
+    }
+
+    $parts = $version.Split('.')
+    $major = [int]$parts[0]
+    $minor = [int]$parts[1]
+
+    if ($major -lt 2) {
+        Write-Error-Custom "Claude Code version $version is not supported"
+        Write-Error-Custom "Please upgrade to Claude Code 2.1.0 or later"
+        return $false
+    } elseif ($major -eq 2 -and $minor -lt 1) {
+        Write-Warning "Claude Code version $version may have limited features"
+        Write-Info "Recommended: Claude Code 2.1.4 or later for full hook support"
+    }
+
+    Write-Success "Claude Code version $version detected"
+    return $true
+}
+
+Write-Info "Checking Claude Code version..."
+if (-not (Check-ClaudeCodeVersion)) {
+    exit 1
+}
+
 # Ask for installation scope
 Write-Host ""
 Write-Info "Where would you like to install ClaudeForge?"
@@ -213,6 +257,46 @@ if ($installHooks -match "^[Yy]$") {
     }
 }
 
+# Validate v2.1.4 compatibility
+function Validate-V214Compatibility {
+    param(
+        [string]$skillsDir,
+        [string]$agentsDir
+    )
+
+    Write-Info "Validating v2.1.4 compatibility..."
+
+    $skillFile = Join-Path $skillsDir "claudeforge-skill\SKILL.md"
+    $agentFile = Join-Path $agentsDir "claude-md-guardian.md"
+
+    # Verify new syntax is present
+    if (-not (Select-String -Path $skillFile -Pattern "permissions:" -Quiet)) {
+        Write-Error-Custom "Skill missing v2.1.4 permissions syntax"
+        return $false
+    }
+
+    if (-not (Select-String -Path $agentFile -Pattern "permissions:" -Quiet)) {
+        Write-Error-Custom "Agent missing v2.1.4 permissions syntax"
+        return $false
+    }
+
+    # Check for hooks
+    if (Select-String -Path $agentFile -Pattern "hooks:" -Quiet) {
+        Write-Success "Guardian agent hooks configured"
+    } else {
+        Write-Warning "Guardian agent has no hooks (optional)"
+    }
+
+    Write-Success "v2.1.4 compatibility validated"
+    return $true
+}
+
+Write-Host ""
+if (-not (Validate-V214Compatibility -skillsDir $skillsDir -agentsDir $agentsDir)) {
+    Write-Error-Custom "Installation validation failed"
+    exit 1
+}
+
 # Installation complete
 Write-Host ""
 Write-Host "╔════════════════════════════════════════╗" -ForegroundColor Green

install.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # ClaudeForge Installer
 # Automated installation script for macOS and Linux
-# Version: 1.0.0
+# Version: 2.0.0
 
 set -e
 
@@ -36,7 +36,7 @@ echo -e "${BLUE}║                                        ║${NC}"
 echo -e "${BLUE}║         ${GREEN}ClaudeForge Installer${BLUE}         ║${NC}"
 echo -e "${BLUE}║                                        ║${NC}"
 echo -e "${BLUE}║  Automated CLAUDE.md Management Tool   ║${NC}"
-echo -e "${BLUE}║            Version 1.0.0               ║${NC}"
+echo -e "${BLUE}║            Version 2.0.0               ║${NC}"
 echo -e "${BLUE}║                                        ║${NC}"
 echo -e "${BLUE}╚════════════════════════════════════════╝${NC}"
 echo ""
@@ -53,13 +53,13 @@ if [ ! -d "skill" ] || [ ! -d "command" ] || [ ! -d "agent" ]; then
     TEMP_DIR=$(mktemp -d)
     cd "$TEMP_DIR"
 
-    print_info "Downloading ClaudeForge v1.0.0..."
+    print_info "Downloading ClaudeForge v2.0.0..."
 
     # Download using curl or wget
     if command -v curl &> /dev/null; then
-        curl -fsSL https://github.com/alirezarezvani/ClaudeForge/archive/refs/tags/v1.0.0.tar.gz -o claudeforge.tar.gz
+        curl -fsSL https://github.com/alirezarezvani/ClaudeForge/archive/refs/heads/main.tar.gz -o claudeforge.tar.gz
     elif command -v wget &> /dev/null; then
-        wget -q https://github.com/alirezarezvani/ClaudeForge/archive/refs/tags/v1.0.0.tar.gz -O claudeforge.tar.gz
+        wget -q https://github.com/alirezarezvani/ClaudeForge/archive/refs/heads/main.tar.gz -O claudeforge.tar.gz
     else
         print_error "Neither curl nor wget found. Please install one of them."
         exit 1
@@ -67,7 +67,7 @@ if [ ! -d "skill" ] || [ ! -d "command" ] || [ ! -d "agent" ]; then
 
     print_info "Extracting files..."
     tar -xzf claudeforge.tar.gz
-    cd ClaudeForge-1.0.0
+    cd ClaudeForge-main
 
     print_success "Downloaded ClaudeForge successfully"
 fi
@@ -82,6 +82,40 @@ if [ ! -d "$HOME/.claude" ]; then
     print_success "Directory structure created"
 fi
 
+# Check Claude Code version
+check_claude_code_version() {
+    local version=""
+
+    if command -v claude &> /dev/null; then
+        version=$(claude --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+    fi
+
+    if [ -z "$version" ]; then
+        print_warning "Could not detect Claude Code version"
+        print_info "ClaudeForge v2.0 requires Claude Code 2.1.0 or later"
+        print_info "Continuing with installation (compatibility not guaranteed)"
+        return 0
+    fi
+
+    local major=$(echo "$version" | cut -d. -f1)
+    local minor=$(echo "$version" | cut -d. -f2)
+
+    if [ "$major" -lt 2 ]; then
+        print_error "Claude Code version $version is not supported"
+        print_error "Please upgrade to Claude Code 2.1.0 or later"
+        return 1
+    elif [ "$major" -eq 2 ] && [ "$minor" -lt 1 ]; then
+        print_warning "Claude Code version $version may have limited features"
+        print_info "Recommended: Claude Code 2.1.4 or later for full hook support"
+    fi
+
+    print_success "Claude Code version $version detected"
+    return 0
+}
+
+print_info "Checking Claude Code version..."
+check_claude_code_version || exit 1
+
 # Ask for installation scope
 echo ""
 print_info "Where would you like to install ClaudeForge?"
@@ -197,6 +231,41 @@ if [[ $install_hooks =~ ^[Yy]$ ]]; then
     fi
 fi
 
+# Validate v2.1.4 compatibility
+validate_v214_compatibility() {
+    print_info "Validating v2.1.4 compatibility..."
+
+    local skill_file="$SKILLS_DIR/claudeforge-skill/SKILL.md"
+    local agent_file="$AGENTS_DIR/claude-md-guardian.md"
+
+    # Verify new syntax is present
+    if ! grep -q "permissions:" "$skill_file"; then
+        print_error "Skill missing v2.1.4 permissions syntax"
+        return 1
+    fi
+
+    if ! grep -q "permissions:" "$agent_file"; then
+        print_error "Agent missing v2.1.4 permissions syntax"
+        return 1
+    fi
+
+    # Check for hooks
+    if grep -q "hooks:" "$agent_file"; then
+        print_success "Guardian agent hooks configured"
+    else
+        print_warning "Guardian agent has no hooks (optional)"
+    fi
+
+    print_success "v2.1.4 compatibility validated"
+    return 0
+}
+
+echo ""
+validate_v214_compatibility || {
+    print_error "Installation validation failed"
+    exit 1
+}
+
 # Installation complete
 echo ""
 echo -e "${GREEN}╔════════════════════════════════════════╗${NC}"

skill/README.md

@@ -1,9 +1,11 @@
-# claude-md-enhancer
+# claudeforge-skill
 
 > **Analyze, generate, and enhance CLAUDE.md files for any project type with intelligent templates and best practices.**
 
 A comprehensive Claude Code skill that helps teams create and maintain high-quality CLAUDE.md files. Supports analysis, validation, generation, and enhancement with tech stack customization, team size adaptation, and modular architecture.
 
+**v2.0.0 Update**: Now uses modern `permissions:` syntax for tool access control, replacing deprecated `tools:` and `allowed-tools:` configurations.
+
 ## Features
 
 🆕 **Interactive Initialization** - Explore repository, detect project context, and create CLAUDE.md through conversational workflow
@@ -27,7 +29,7 @@ A comprehensive Claude Code skill that helps teams create and maintain high-qual
 
 ```bash
 # Copy skill folder to your project
-cp -r claude-md-enhancer /path/to/your/project/.claude/skills/
+cp -r skill /path/to/your/project/.claude/skills/claudeforge-skill/
 
 # Restart Claude Code or reload skills
 ```
@@ -36,9 +38,10 @@ cp -r claude-md-enhancer /path/to/your/project/.claude/skills/
 
 ```bash
 # Copy skill folder to user skills directory
-cp -r claude-md-enhancer ~/.claude/skills/
+cp -r skill ~/.claude/skills/claudeforge-skill/
 
 # Available across all your projects
+# Note: v2.0.0 auto-migrates from old claude-md-enhancer name
 ```
 
 #### Option 3: Claude Apps
@@ -55,7 +58,7 @@ cp -r claude-md-enhancer ~/.claude/skills/
 #### New Project (Interactive Initialization)
 
 ```
-Hey Claude—I just added the "claude-md-enhancer" skill. I don't have a CLAUDE.md file yet. Can you help me create one for this project?
+Hey Claude—I just added the "claudeforge-skill". I don't have a CLAUDE.md file yet. Can you help me create one for this project?
 ```
 
 Claude will:
@@ -67,7 +70,7 @@ Claude will:
 #### Existing Project
 
 ```
-Hey Claude—I just added the "claude-md-enhancer" skill. Can you analyze my CLAUDE.md and suggest improvements?
+Hey Claude—I just added the "claudeforge-skill". Can you analyze my CLAUDE.md and suggest improvements?
 ```
 
 See [HOW_TO_USE.md](HOW_TO_USE.md) for comprehensive examples.
@@ -79,18 +82,21 @@ See [HOW_TO_USE.md](HOW_TO_USE.md) for comprehensive examples.
 ### Module Overview
 
 ```
-claude-md-enhancer/
+claudeforge-skill/
 ├── SKILL.md                    # Skill definition with YAML frontmatter
 ├── analyzer.py                 # Analyzes existing CLAUDE.md files
 ├── validator.py                # Validates against best practices
 ├── generator.py                # Generates new content
 ├── template_selector.py        # Selects appropriate templates
+├── workflow.py                 # Interactive initialization workflow
 ├── sample_input.json           # Example inputs
 ├── expected_output.json        # Expected outputs
 ├── HOW_TO_USE.md               # Usage examples
 └── README.md                   # This file
 ```
 
+**v2.0.0**: Updated SKILL.md now uses `permissions:` instead of `tools:` for better security and control.
+
 ### Python Modules
 
 #### `workflow.py` - Initialization Workflow (New!)
@@ -459,9 +465,10 @@ Before finalizing any CLAUDE.md generation:
 
 ## Version
 
-**Version**: 1.0.0
+**Version**: 2.0.0
-**Last Updated**: November 2025
+**Last Updated**: January 2026
-**Compatible**: Claude Code 2.0+, Claude Apps, Claude API
+**Compatible**: Claude Code 2.1.4+, Claude Apps, Claude API
+**Migration**: See [../docs/MIGRATION_V2.md](../docs/MIGRATION_V2.md) for upgrade guide from v1.x
 
 ---
 
@@ -505,23 +512,34 @@ For automatic CLAUDE.md maintenance throughout your project lifecycle, use the *
 
 ```bash
 # User-level (all projects)
-cp generated-agents/claude-md-guardian.md ~/.claude/agents/
+cp agent/claude-md-guardian.md ~/.claude/agents/
 
 # Project-level (current project)
-cp generated-agents/claude-md-guardian.md .claude/agents/
+cp agent/claude-md-guardian.md .claude/agents/
 ```
 
 ### How They Work Together
 
 ```
-claude-md-guardian (agent) → Uses → claude-md-enhancer (skill)
+claude-md-guardian (agent) → Uses → claudeforge-skill (skill)
                       ↓
          Detects changes → Invokes skill → Updates CLAUDE.md
 ```
 
 **Result**: Your CLAUDE.md stays synchronized with your codebase automatically!
 
-See `generated-agents/claude-md-guardian-README.md` for complete agent documentation.
+**v2.0.0**: Agent now uses `permissions:` syntax for controlled tool access. Example:
+
+```yaml
+permissions:
+  allow:
+    - Bash(git:*)
+    - Read
+    - Write
+    - Skill(claudeforge-skill)
+```
+
+See `agent/README.md` for complete agent documentation.
 
 ---
 
@@ -529,8 +547,9 @@ See `generated-agents/claude-md-guardian-README.md` for complete agent documenta
 
 - **Documentation**: See [SKILL.md](SKILL.md) for complete documentation
 - **Examples**: See [HOW_TO_USE.md](HOW_TO_USE.md) for usage examples
-- **Companion Agent**: See `../../generated-agents/claude-md-guardian-README.md`
+- **Companion Agent**: See [../agent/README.md](../agent/README.md)
-- **Slash Command**: See `../../generated-commands/enhance-claude-md/README.md`
+- **Slash Command**: See [../command/README.md](../command/README.md)
+- **Migration Guide**: See [../docs/MIGRATION_V2.md](../docs/MIGRATION_V2.md)
 - **Issues**: Report bugs in the main repository
 - **Community**: Share your CLAUDE.md setups and best practices
 

skill/SKILL.md

@@ -1,6 +1,16 @@
 ---
 name: claude-md-enhancer
 description: Analyzes, generates, and enhances CLAUDE.md files for any project type using best practices, modular architecture support, and tech stack customization. Use when setting up new projects, improving existing CLAUDE.md files, or establishing AI-assisted development standards.
+permissions:
+  allow:
+    - Read
+    - Write
+    - Edit
+    - Glob
+    - Grep
+    - Bash(ls:*)
+    - Bash(find:*)
+    - Bash(git:*)
 ---
 
 # CLAUDE.md File Enhancer

skill/examples/README.md

@@ -2,7 +2,9 @@
 
 This folder contains reference implementations of CLAUDE.md files for different project types and team sizes.
 
-**✨ NEW**: All examples now follow **100% native Claude Code format** with proper project structure diagrams, setup instructions, architecture sections, and file structure explanations - matching the official `/update-claude-md` slash command format.
+**✨ v2.0.0 Update**: All examples now follow **100% native Claude Code format** with proper project structure diagrams, setup instructions, architecture sections, and file structure explanations - matching the official `/update-claude-md` slash command format.
+
+**New in v2.0.0**: Examples demonstrate modern `permissions:` syntax for skills and agents, replacing deprecated `tools:` configurations.
 
 ## Available Examples
 
@@ -59,16 +61,18 @@ cp examples/modular-backend-CLAUDE.md /path/to/your/project/backend/CLAUDE.md
 cp examples/modular-frontend-CLAUDE.md /path/to/your/project/frontend/CLAUDE.md
 ```
 
-### 3. Using with claude-md-enhancer Skill
+### 3. Using with claudeforge-skill
 
 These examples demonstrate the output quality you can expect from the skill:
 
 ```
-Hey Claude—I just added the "claude-md-enhancer" skill.
+Hey Claude—I just added the "claudeforge-skill".
 Can you create a CLAUDE.md similar to the core-small-team example
 but customized for my Go API project?
 ```
 
+**v2.0.0**: The skill now uses `permissions:` syntax for secure tool access control.
+
 ## Template Selection Guide
 
 ### Choose Minimal Template When:
@@ -114,6 +118,8 @@ All examples now include these **native Claude Code sections**:
 
 **Why This Matters**: These sections match the official `/update-claude-md` slash command format, ensuring Claude Code can navigate and understand your codebase efficiently.
 
+**v2.0.0 Compatibility**: All examples are compatible with Claude Code 2.1.4+ and use modern permission syntax where applicable.
+
 ### Expected Quality Scores
 
 | Example | Quality Score |
@@ -132,7 +138,22 @@ All examples now include these **native Claude Code sections**:
 3. **Add Team Standards**: Include team-specific conventions
 4. **Update Commands**: Replace commands with your actual npm/yarn/poetry scripts
 5. **Add Context**: Include project-specific context that helps Claude understand your goals
+6. **v2.0.0**: Use `permissions:` syntax in skills/agents instead of deprecated `tools:` or `allowed-tools:`
 
 ## Contributing
 
-These examples represent best practices as of November 2025. If you have improvements or additional examples, please contribute them!
+These examples represent best practices as of January 2026. If you have improvements or additional examples, please contribute them!
+
+## Version
+
+- **Version**: 2.0.0
+- **Last Updated**: January 2026
+- **Compatible**: Claude Code 2.1.4+
+- **Migration Guide**: See [../../docs/MIGRATION_V2.md](../../docs/MIGRATION_V2.md) for upgrade instructions
+
+## Related Documentation
+
+- **Skill Documentation**: [../README.md](../README.md)
+- **Agent Documentation**: [../../agent/README.md](../../agent/README.md)
+- **Command Documentation**: [../../command/README.md](../../command/README.md)
+- **Migration Guide**: [../../docs/MIGRATION_V2.md](../../docs/MIGRATION_V2.md)

test/LOCAL_TESTING_GUIDE.md

@@ -0,0 +1,449 @@
+# Local Testing Guide for ClaudeForge v2.0.0
+
+This guide walks you through testing the v2.1.4 migration on your local machine before creating a PR.
+
+---
+
+## Prerequisites
+
+- Claude Code 2.1.0+ installed
+- Current working directory: `/Users/rezarezvani/projects/ClaudeForge`
+- Feature branch checked out: `feature/migrate-v2.1.4-architecture`
+
+---
+
+## Testing Workflow
+
+### Step 1: Backup Your Current ClaudeForge Installation
+
+If you have ClaudeForge installed, back it up first:
+
+```bash
+# Check if you have existing installation
+ls -la ~/.claude/skills/claudeforge-skill 2>/dev/null && echo "Found existing installation"
+
+# Backup (if exists)
+cp -r ~/.claude/skills/claudeforge-skill ~/.claude/skills/claudeforge-skill.pre-v2-test 2>/dev/null
+cp -r ~/.claude/commands/enhance-claude-md ~/.claude/commands/enhance-claude-md.pre-v2-test 2>/dev/null
+cp ~/.claude/agents/claude-md-guardian.md ~/.claude/agents/claude-md-guardian.md.pre-v2-test 2>/dev/null
+
+echo "✓ Backup complete (if installation existed)"
+```
+
+---
+
+### Step 2: Test Fresh Installation
+
+Test installing from scratch:
+
+```bash
+# Remove any existing installation
+rm -rf ~/.claude/skills/claudeforge-skill
+rm -rf ~/.claude/commands/enhance-claude-md
+rm ~/.claude/agents/claude-md-guardian.md
+
+# Run the new installer
+./install.sh
+
+# Choose option 1 (user-level)
+# Press Y to confirm installation
+# Press N for quality hooks (we're just testing core features)
+```
+
+**Expected Output:**
+```
+ℹ  Checking Claude Code version...
+✓  Claude Code version 2.1.4 detected
+ℹ  Where would you like to install ClaudeForge?
+...
+ℹ  Validating v2.1.4 compatibility...
+✓  Guardian agent hooks configured
+✓  v2.1.4 compatibility validated
+✓  Installation completed successfully!
+```
+
+---
+
+### Step 3: Run Validation Script
+
+Verify the installation is correct:
+
+```bash
+# Run automated validation
+./test/validate_migration.sh
+```
+
+**Expected Output:**
+```
+=== ClaudeForge v2.1.4 Migration Validation ===
+
+Test 1: File Existence
+----------------------
+✓ Skill file exists
+✓ Command file exists
+✓ Agent file exists
+
+Test 2: v2.1.4 Syntax Validation
+---------------------------------
+✓ Skill uses permissions syntax
+✓ Command uses permissions syntax
+✓ Agent uses permissions syntax
+
+Test 3: Hooks Configuration
+---------------------------
+✓ Agent has hooks configured
+✓ SessionStart hook present
+✓ PreToolUse hook present
+✓ PostToolUse hook present
+
+Test 4: Fork-Safe Mode
+----------------------
+✓ Fork-safe mode enabled
+
+Test 5: Python Modules Integrity
+--------------------------------
+✓ analyzer.py present
+✓ validator.py present
+✓ generator.py present
+✓ template_selector.py present
+✓ workflow.py present
+
+Test 6: Legacy Syntax Cleanup
+-----------------------------
+✓ Agent has no legacy 'tools:' field
+✓ Command has no legacy 'allowed-tools:' field
+
+Test 7: Documentation
+--------------------
+✓ Migration guide exists
+✓ CHANGELOG has v2.0.0 entry
+✓ README references v2.1.4
+
+Test 8: Example Files Unchanged
+-------------------------------
+✓ Example files present
+
+===================================
+Validation Complete
+===================================
+Passed: 18
+Failed: 0
+
+✅ All tests passed! Migration successful.
+```
+
+---
+
+### Step 4: Test Functionality
+
+Test that the skill/command still works:
+
+```bash
+# Start Claude Code
+claude
+
+# Test the slash command
+/enhance-claude-md
+```
+
+**What to expect:**
+1. Hook message appears: `"Starting CLAUDE.md enhancement workflow"`
+2. 3-phase workflow runs normally (Discovery → Analysis → Task)
+3. Skill is invoked and works correctly
+
+**Exit Claude Code** when done testing:
+```
+exit
+```
+
+---
+
+### Step 5: Test SessionStart Hook
+
+Test that the guardian agent SessionStart hook fires:
+
+```bash
+# Start a new Claude Code session
+claude
+```
+
+**Expected on startup:**
+You should see:
+```
+Guardian: Checking for CLAUDE.md updates...
+```
+
+This confirms the SessionStart hook is working.
+
+**Exit when done:**
+```
+exit
+```
+
+---
+
+### Step 6: Manually Verify Files
+
+Double-check the installed files have correct syntax:
+
+```bash
+# Check skill frontmatter
+head -20 ~/.claude/skills/claudeforge-skill/SKILL.md
+
+# Should see:
+# ---
+# name: claude-md-enhancer
+# permissions:
+#   allow:
+#     - Read
+#     - Write
+#     ...
+
+# Check agent frontmatter
+head -30 ~/.claude/agents/claude-md-guardian.md
+
+# Should see:
+# ---
+# name: claude-md-guardian
+# permissions:
+#   allow:
+#     - Bash
+#     - Read
+#     ...
+# hooks:
+#   - event: SessionStart
+#     ...
+```
+
+---
+
+### Step 7: Test Migration from v1.x (Optional)
+
+If you want to test the migration logic:
+
+```bash
+# Create a mock v1.x installation
+mkdir -p ~/.claude/skills/claudeforge-skill-mock
+cat > ~/.claude/skills/claudeforge-skill-mock/SKILL.md <<'EOF'
+---
+name: claude-md-enhancer
+tools: Bash, Read, Write
+---
+Old v1.x syntax
+EOF
+
+# Temporarily rename to simulate v1.x
+mv ~/.claude/skills/claudeforge-skill ~/.claude/skills/claudeforge-skill-real
+mv ~/.claude/skills/claudeforge-skill-mock ~/.claude/skills/claudeforge-skill
+
+# Run installer (should detect and backup v1.x)
+./install.sh
+
+# Check backup was created
+ls ~/.claude/skills/claudeforge-skill.v1_backup* || ls ~/.claude/skills/claudeforge-skill.backup.*
+
+# Verify new syntax
+grep "permissions:" ~/.claude/skills/claudeforge-skill/SKILL.md
+
+# Restore real installation
+rm -rf ~/.claude/skills/claudeforge-skill
+mv ~/.claude/skills/claudeforge-skill-real ~/.claude/skills/claudeforge-skill
+```
+
+---
+
+### Step 8: Test Rollback Script
+
+Test that rollback works (using the backup from Step 7):
+
+```bash
+# If you have backups from Step 7
+./test/rollback.sh
+
+# Verify it restored v1.x syntax
+head -10 ~/.claude/skills/claudeforge-skill/SKILL.md
+
+# Then reinstall v2.0 for continued testing
+./install.sh
+```
+
+---
+
+### Step 9: Test Python Modules Still Work
+
+Verify Python modules weren't accidentally broken:
+
+```bash
+# Test Python compilation
+python3 -m py_compile skill/analyzer.py
+python3 -m py_compile skill/validator.py
+python3 -m py_compile skill/generator.py
+python3 -m py_compile skill/template_selector.py
+python3 -m py_compile skill/workflow.py
+
+echo "✓ All Python modules compile successfully"
+
+# Test imports (from skill directory)
+cd skill
+python3 -c "from analyzer import CLAUDEMDAnalyzer; print('✓ analyzer.py imports')"
+python3 -c "from validator import BestPracticesValidator; print('✓ validator.py imports')"
+python3 -c "from generator import ContentGenerator; print('✓ generator.py imports')"
+python3 -c "from template_selector import TemplateSelector; print('✓ template_selector.py imports')"
+python3 -c "from workflow import InitializationWorkflow; print('✓ workflow.py imports')"
+cd ..
+```
+
+---
+
+### Step 10: Test in a Real Project
+
+Test the skill on an actual project:
+
+```bash
+# Create a test project
+mkdir -p /tmp/test-claude-project
+cd /tmp/test-claude-project
+git init
+npm init -y  # Or create any project
+
+# Start Claude Code
+claude
+
+# Test the enhancement command
+/enhance-claude-md
+
+# Follow the workflow and verify:
+# 1. Discovery phase works
+# 2. Analysis runs correctly
+# 3. CLAUDE.md is generated with correct format
+# 4. No errors or warnings
+
+# Exit and clean up
+exit
+cd /Users/rezarezvani/projects/ClaudeForge
+rm -rf /tmp/test-claude-project
+```
+
+---
+
+## Quick Test Checklist
+
+Use this checklist for rapid validation:
+
+- [ ] `./install.sh` runs without errors
+- [ ] Version detection works (shows your Claude Code version)
+- [ ] `./test/validate_migration.sh` shows all tests passing (18/18)
+- [ ] `/enhance-claude-md` command works in Claude Code
+- [ ] SessionStart hook fires (see "Guardian: Checking..." on startup)
+- [ ] Python modules compile without errors
+- [ ] `./test/rollback.sh` successfully restores backups
+- [ ] Documentation renders correctly (`docs/MIGRATION_V2.md`)
+
+---
+
+## Troubleshooting Local Tests
+
+### "Command not found: claude"
+
+```bash
+# Check if Claude Code is installed
+which claude
+
+# If not found, install Claude Code first
+# Then retry testing
+```
+
+### "Permission denied" when running scripts
+
+```bash
+# Make scripts executable
+chmod +x test/validate_migration.sh
+chmod +x test/rollback.sh
+chmod +x install.sh
+```
+
+### "Python module import failed"
+
+```bash
+# Ensure you're in the skill directory
+cd skill
+python3 -c "import sys; print(sys.path)"
+cd ..
+```
+
+### Hooks don't fire
+
+- Hooks require Claude Code 2.1.0+
+- Check version: `claude --version`
+- Restart Claude Code completely (not just exit/claude)
+- Close terminal and open a new one
+
+---
+
+## After Testing Successfully
+
+Once all tests pass:
+
+1. **Restore your original installation** (if you want to keep using v1.x):
+   ```bash
+   ./test/rollback.sh
+   # Or manually restore from .pre-v2-test backups
+   ```
+
+2. **Keep v2.0 installed** (if you want to use the new version):
+   ```bash
+   # Already installed, just use it!
+   claude
+   /enhance-claude-md
+   ```
+
+3. **Create the PR**:
+   ```bash
+   gh pr create --base dev --title "feat(v2.0.0): migrate to Claude Code v2.1.4+ architecture"
+   ```
+
+---
+
+## Test Results Log
+
+Keep track of your test results:
+
+| Test | Result | Notes |
+|------|--------|-------|
+| Fresh install | ☐ Pass ☐ Fail | |
+| Validation script | ☐ Pass ☐ Fail | |
+| /enhance-claude-md command | ☐ Pass ☐ Fail | |
+| SessionStart hook | ☐ Pass ☐ Fail | |
+| Python modules | ☐ Pass ☐ Fail | |
+| Real project test | ☐ Pass ☐ Fail | |
+| Rollback script | ☐ Pass ☐ Fail | |
+
+---
+
+## Getting Help
+
+If you encounter issues during testing:
+
+1. Check the validation script output for specific failures
+2. Review `docs/MIGRATION_V2.md` troubleshooting section
+3. Check Claude Code version: `claude --version`
+4. Verify branch: `git branch` (should show `feature/migrate-v2.1.4-architecture`)
+
+---
+
+## Pro Tip: Test in a Docker Container
+
+For completely isolated testing:
+
+```bash
+# Use a Docker container with Claude Code installed
+docker run -it -v $(pwd):/workspace ubuntu:latest bash
+
+# Inside container:
+cd /workspace
+# Install Claude Code
+# Run ./install.sh
+# Run ./test/validate_migration.sh
+```
+
+This ensures no interference from your existing setup.

test/README.md

@@ -0,0 +1,180 @@
+# ClaudeForge Testing Scripts
+
+This directory contains validation and rollback scripts for the v2.0.0 migration.
+
+## Scripts
+
+### `validate_migration.sh`
+
+Validates that the ClaudeForge v2.0.0 migration completed successfully.
+
+**Tests:**
+1. File existence (skill, command, agent)
+2. v2.1.4 syntax validation (`permissions:` fields)
+3. Hooks configuration (SessionStart, PreToolUse, PostToolUse)
+4. Fork-safe mode enabled
+5. Python modules integrity
+6. Legacy syntax cleanup
+7. Documentation updates
+8. Example files unchanged
+
+**Usage:**
+```bash
+cd /path/to/ClaudeForge
+./test/validate_migration.sh
+```
+
+**Expected Output:**
+```
+=== ClaudeForge v2.1.4 Migration Validation ===
+
+Test 1: File Existence
+----------------------
+✓ Skill file exists
+✓ Command file exists
+✓ Agent file exists
+
+[... more tests ...]
+
+===================================
+Validation Complete
+===================================
+Passed: 18
+Failed: 0
+
+✅ All tests passed! Migration successful.
+```
+
+---
+
+### `rollback.sh`
+
+Rolls back ClaudeForge installation from v2.0.0 to v1.0.0 using automatic backups.
+
+**What it does:**
+- Searches for timestamped backups created by the installer
+- Restores skill, command, and agent from backups
+- Provides alternative manual rollback instructions if no backups found
+
+**Usage:**
+```bash
+cd /path/to/ClaudeForge
+./test/rollback.sh
+```
+
+**Expected Output:**
+```
+=== ClaudeForge Rollback to v1.x ===
+
+Searching for skill backup...
+Found backup: claudeforge-skill.backup.20260107_120000
+✓ Restored skill from: claudeforge-skill.backup.20260107_120000
+
+[... more restorations ...]
+
+====================================
+Rollback Summary
+====================================
+Components restored: 3
+
+✅ Rollback complete!
+
+Next steps:
+1. Restart Claude Code
+2. Test with: /enhance-claude-md
+```
+
+---
+
+## Testing Workflow
+
+### Before Installation
+
+1. **Backup manually** (extra safety):
+   ```bash
+   cp -r ~/.claude/skills/claudeforge-skill ~/.claude/skills/claudeforge-skill.manual.backup
+   ```
+
+2. **Note your current version**:
+   ```bash
+   grep "^name:" ~/.claude/skills/claudeforge-skill/SKILL.md
+   ```
+
+### After Installation
+
+1. **Run validation**:
+   ```bash
+   ./test/validate_migration.sh
+   ```
+
+2. **Test functionality**:
+   ```bash
+   claude
+   /enhance-claude-md
+   ```
+
+3. **Check hooks** (restart Claude Code first):
+   - Look for "Guardian: Checking for CLAUDE.md updates..." on startup
+
+### If Something Goes Wrong
+
+1. **Run rollback**:
+   ```bash
+   ./test/rollback.sh
+   ```
+
+2. **Or restore manual backup**:
+   ```bash
+   rm -rf ~/.claude/skills/claudeforge-skill
+   cp -r ~/.claude/skills/claudeforge-skill.manual.backup ~/.claude/skills/claudeforge-skill
+   ```
+
+---
+
+## Test Matrix for Installation
+
+| Scenario | Test Steps | Expected Result |
+|----------|-----------|-----------------|
+| **Fresh Install** | 1. No existing ClaudeForge<br>2. Run `./install.sh`<br>3. Validate | All files installed with v2.1.4 syntax |
+| **Upgrade from v1.x** | 1. Have v1.x installed<br>2. Run `./install.sh`<br>3. Validate | Auto-backup created, v2.0 installed |
+| **Version Check** | 1. Claude Code 2.1.4+<br>2. Run installer | Version detected, no warnings |
+| **Version Check** | 1. Claude Code < 2.1.0<br>2. Run installer | Warning displayed about limited features |
+| **Rollback** | 1. Run `./test/rollback.sh`<br>2. Restart Claude | v1.x restored, no hooks |
+
+---
+
+## Continuous Integration
+
+These test scripts can be integrated into CI/CD:
+
+```yaml
+# .github/workflows/validate-migration.yml
+name: Validate Migration
+
+on:
+  push:
+    branches: [feature/migrate-v2.1.4-architecture]
+
+jobs:
+  test-migration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run migration validation
+        run: |
+          # Install to temporary location
+          export HOME=/tmp/test-home
+          ./install.sh <<< "1"
+
+          # Run validation
+          ./test/validate_migration.sh
+```
+
+---
+
+## Notes
+
+- Test scripts are designed to be idempotent (can run multiple times)
+- All scripts exit with proper codes (0 = success, 1 = failure)
+- Scripts provide detailed output for debugging
+- Compatible with both macOS and Linux

test/rollback.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# ClaudeForge Rollback Script
+# Rolls back from v2.0.0 to v1.0.0 using automatic backups
+
+echo "=== ClaudeForge Rollback to v1.x ==="
+echo ""
+
+SKILLS_DIR="$HOME/.claude/skills"
+COMMANDS_DIR="$HOME/.claude/commands"
+AGENTS_DIR="$HOME/.claude/agents"
+
+RESTORED_COUNT=0
+
+# Find and restore skill backup
+echo "Searching for skill backup..."
+for backup in "$SKILLS_DIR"/claudeforge-skill.v1_backup_* "$SKILLS_DIR"/claudeforge-skill.backup.*; do
+    if [ -d "$backup" ]; then
+        echo "Found backup: $(basename $backup)"
+        rm -rf "$SKILLS_DIR/claudeforge-skill"
+        mv "$backup" "$SKILLS_DIR/claudeforge-skill"
+        echo "✓ Restored skill from: $(basename $backup)"
+        ((RESTORED_COUNT++))
+        break
+    fi
+done
+
+# Find and restore command backup
+echo ""
+echo "Searching for command backup..."
+for backup in "$COMMANDS_DIR"/enhance-claude-md.v1_backup_* "$COMMANDS_DIR"/enhance-claude-md.backup.*; do
+    if [ -d "$backup" ]; then
+        echo "Found backup: $(basename $backup)"
+        rm -rf "$COMMANDS_DIR/enhance-claude-md"
+        mv "$backup" "$COMMANDS_DIR/enhance-claude-md"
+        echo "✓ Restored command from: $(basename $backup)"
+        ((RESTORED_COUNT++))
+        break
+    fi
+done
+
+# Find and restore agent backup
+echo ""
+echo "Searching for agent backup..."
+for backup in "$AGENTS_DIR"/claude-md-guardian.md.v1_backup_* "$AGENTS_DIR"/claude-md-guardian.md.backup.*; do
+    if [ -f "$backup" ]; then
+        echo "Found backup: $(basename $backup)"
+        rm -f "$AGENTS_DIR/claude-md-guardian.md"
+        mv "$backup" "$AGENTS_DIR/claude-md-guardian.md"
+        echo "✓ Restored agent from: $(basename $backup)"
+        ((RESTORED_COUNT++))
+        break
+    fi
+done
+
+# Summary
+echo ""
+echo "===================================="
+echo "Rollback Summary"
+echo "===================================="
+echo "Components restored: $RESTORED_COUNT"
+echo ""
+
+if [ $RESTORED_COUNT -eq 0 ]; then
+    echo "⚠️  No backups found. Cannot rollback."
+    echo ""
+    echo "To manually install v1.0.0:"
+    echo "  curl -fsSL https://github.com/alirezarezvani/ClaudeForge/archive/refs/tags/v1.0.0.tar.gz | tar -xz"
+    echo "  cd ClaudeForge-1.0.0"
+    echo "  ./install.sh"
+    exit 1
+else
+    echo "✅ Rollback complete!"
+    echo ""
+    echo "Next steps:"
+    echo "1. Restart Claude Code"
+    echo "2. Test with: /enhance-claude-md"
+    exit 0
+fi

test/validate_migration.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# ClaudeForge v2.1.4 Migration Validation Script
+# Tests that the migration to v2.0.0 was successful
+
+echo "=== ClaudeForge v2.1.4 Migration Validation ==="
+echo ""
+
+SKILLS_DIR="$HOME/.claude/skills"
+COMMANDS_DIR="$HOME/.claude/commands"
+AGENTS_DIR="$HOME/.claude/agents"
+
+PASS_COUNT=0
+FAIL_COUNT=0
+
+# Helper functions
+pass() {
+    echo "✓ $1"
+    ((PASS_COUNT++))
+}
+
+fail() {
+    echo "✗ $1"
+    ((FAIL_COUNT++))
+}
+
+# Test 1: File Existence
+echo "Test 1: File Existence"
+echo "----------------------"
+[ -f "$SKILLS_DIR/claudeforge-skill/SKILL.md" ] && pass "Skill file exists" || fail "Skill file missing"
+[ -f "$COMMANDS_DIR/enhance-claude-md/enhance-claude-md.md" ] && pass "Command file exists" || fail "Command file missing"
+[ -f "$AGENTS_DIR/claude-md-guardian.md" ] && pass "Agent file exists" || fail "Agent file missing"
+
+# Test 2: v2.1.4 Syntax Validation
+echo ""
+echo "Test 2: v2.1.4 Syntax Validation"
+echo "---------------------------------"
+grep -q "permissions:" "$SKILLS_DIR/claudeforge-skill/SKILL.md" 2>/dev/null && pass "Skill uses permissions syntax" || fail "Skill uses old syntax"
+grep -q "permissions:" "$COMMANDS_DIR/enhance-claude-md/enhance-claude-md.md" 2>/dev/null && pass "Command uses permissions syntax" || fail "Command uses old syntax"
+grep -q "permissions:" "$AGENTS_DIR/claude-md-guardian.md" 2>/dev/null && pass "Agent uses permissions syntax" || fail "Agent uses old syntax"
+
+# Test 3: Hooks Configuration
+echo ""
+echo "Test 3: Hooks Configuration"
+echo "---------------------------"
+grep -q "hooks:" "$AGENTS_DIR/claude-md-guardian.md" 2>/dev/null && pass "Agent has hooks configured" || fail "Agent missing hooks"
+grep -q "SessionStart" "$AGENTS_DIR/claude-md-guardian.md" 2>/dev/null && pass "SessionStart hook present" || fail "SessionStart hook missing"
+grep -q "PreToolUse" "$AGENTS_DIR/claude-md-guardian.md" 2>/dev/null && pass "PreToolUse hook present" || fail "PreToolUse hook missing"
+grep -q "PostToolUse" "$AGENTS_DIR/claude-md-guardian.md" 2>/dev/null && pass "PostToolUse hook present" || fail "PostToolUse hook missing"
+
+# Test 4: Fork-Safe Mode
+echo ""
+echo "Test 4: Fork-Safe Mode"
+echo "----------------------"
+grep -q "fork_safe: true" "$AGENTS_DIR/claude-md-guardian.md" 2>/dev/null && pass "Fork-safe mode enabled" || fail "Fork-safe mode not configured"
+
+# Test 5: Python Modules Integrity
+echo ""
+echo "Test 5: Python Modules Integrity"
+echo "--------------------------------"
+[ -f "$SKILLS_DIR/claudeforge-skill/analyzer.py" ] && pass "analyzer.py present" || fail "analyzer.py missing"
+[ -f "$SKILLS_DIR/claudeforge-skill/validator.py" ] && pass "validator.py present" || fail "validator.py missing"
+[ -f "$SKILLS_DIR/claudeforge-skill/generator.py" ] && pass "generator.py present" || fail "generator.py missing"
+[ -f "$SKILLS_DIR/claudeforge-skill/template_selector.py" ] && pass "template_selector.py present" || fail "template_selector.py missing"
+[ -f "$SKILLS_DIR/claudeforge-skill/workflow.py" ] && pass "workflow.py present" || fail "workflow.py missing"
+
+# Test 6: Legacy Syntax Check (should NOT be present)
+echo ""
+echo "Test 6: Legacy Syntax Cleanup"
+echo "-----------------------------"
+! grep -q "^tools:" "$AGENTS_DIR/claude-md-guardian.md" 2>/dev/null && pass "Agent has no legacy 'tools:' field" || fail "Agent still has legacy 'tools:' field"
+! grep -q "^allowed-tools:" "$COMMANDS_DIR/enhance-claude-md/enhance-claude-md.md" 2>/dev/null && pass "Command has no legacy 'allowed-tools:' field" || fail "Command still has legacy 'allowed-tools:' field"
+
+# Test 7: Documentation
+echo ""
+echo "Test 7: Documentation"
+echo "--------------------"
+[ -f "docs/MIGRATION_V2.md" ] && pass "Migration guide exists" || fail "Migration guide missing"
+grep -q "2.0.0" "CHANGELOG.md" 2>/dev/null && pass "CHANGELOG has v2.0.0 entry" || fail "CHANGELOG missing v2.0.0 entry"
+grep -q "2.1.4" "README.md" 2>/dev/null && pass "README references v2.1.4" || fail "README missing v2.1.4 reference"
+
+# Test 8: Example Files
+echo ""
+echo "Test 8: Example Files Unchanged"
+echo "-------------------------------"
+[ -f "$SKILLS_DIR/claudeforge-skill/examples/minimal-solo-CLAUDE.md" ] && pass "Example files present" || fail "Example files missing"
+
+# Summary
+echo ""
+echo "==================================="
+echo "Validation Complete"
+echo "==================================="
+echo "Passed: $PASS_COUNT"
+echo "Failed: $FAIL_COUNT"
+echo ""
+
+if [ $FAIL_COUNT -eq 0 ]; then
+    echo "✅ All tests passed! Migration successful."
+    exit 0
+else
+    echo "❌ Some tests failed. Review errors above."
+    exit 1
+fi