ClaudeForge/CHANGELOG.md

# Changelog

All notable changes to ClaudeForge will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [Unreleased]

### Added

- **Claude Code plugin manifest** (`.claude-plugin/plugin.json`): ClaudeForge is now installable as a Claude Code plugin via `/plugin marketplace add alirezarezvani/ClaudeForge && /plugin install claudeforge`. Manifest registers all skills, commands, and the guardian agent in one bundle.
- **`/sync-claude-md` slash command** (`command/sync-claude-md.md`): walks every CLAUDE.md in the project, prunes stale references (removed dependencies, deleted paths, broken modular links), enforces the 150-line cap, and repairs the root ↔ sub chain. Designed to run after refactors, dependency changes, or before a release.
- **Karpathy Guidelines skill** (`skill/karpathy-guidelines/SKILL.md`): behavioural-guardrail skill applied to every coding, review, and refactoring task. Covers four principles — Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution — adapted with attribution from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) repository.
- **Automatic embedding into every CLAUDE.md**: `skill/template_selector.py` and `skill/generator.py` insert a `## Behavioral Guidelines` section into every generated and enhanced CLAUDE.md.
- **Modular chaining via `@path` imports**: the modular root generator emits both human-readable markdown links and Claude Code `@path/to/CLAUDE.md` imports for every sub-CLAUDE.md. Sub-files now get a back-link header pointing to the root file so navigation is bidirectional.
- **Explore-agent delegation in `/enhance-claude-md`**: deep project scans are delegated to the Explore subagent to keep the calling session's context lean.

### Changed

- **Hard 150-line cap per CLAUDE.md**: `validator.MAX_RECOMMENDED_LINES` lowered from 300 to 150 (warning at 120). `template_selector.TEAM_SIZE_TEMPLATES` target lines lowered to fit (solo 75 / small 100 / medium 125 / large 150). `analyzer` length thresholds and quality scoring rebased on the new cap. Projects that need more content split it across chained sub-files instead of growing the root.
- **Installers register commands as top-level files**: `install.sh` and `install.ps1` now install each `.md` under `command/` as its own `~/.claude/commands/<name>.md` (registering as `/<name>`) rather than bundling the whole directory under one path. Legacy `~/.claude/commands/enhance-claude-md/` bundles are backed up automatically on upgrade.

### Verified

- Smoke tests: validator constants, all four team-size templates, generator output for solo/small/medium/large + library presets (all ≤ 150 lines), context files with back-links, `@`-import chain in modular root, idempotent `merge_with_existing`, validator status transitions (pass / warning / fail) at the new cap, analyzer quality score differential between compliant and bloated files, plugin manifest JSON shape and that every referenced path exists on disk.

---

## [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, #19)
  - Added proper quoting around `${BLUE}` and `${NC}` variables in command substitution
  - Prevents "syntax error near unexpected token" during installation on macOS
  - 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

### 🎉 Initial Release

ClaudeForge v1.0.0 marks the first stable release of the automated CLAUDE.md management toolkit for Claude Code projects.

### Added

#### Core Features
- **Interactive Initialization Workflow** - Conversational workflow that explores repositories, detects project context, and creates customized CLAUDE.md files
- **100% Native Format Compliance** - All generated files follow official Claude Code format with project structure diagrams, setup instructions, and architecture sections
- **Intelligent Analysis** - Comprehensive file analysis with quality scoring (0-100) and actionable recommendations
- **Smart Enhancement** - Automatic addition of missing sections and structure improvements
- **Best Practice Validation** - Validation against Anthropic guidelines and community standards

#### Components
- **Skill:** `claudeforge-skill` v1.0.0
  - `analyzer.py` - File analysis and quality scoring (382 lines)
  - `validator.py` - Best practices validation (429 lines)
  - `generator.py` - Content generation (480 lines)
  - `template_selector.py` - Template selection logic (467 lines)
  - `workflow.py` - Interactive initialization workflow (432 lines)

- **Slash Command:** `/enhance-claude-md` v1.0.0
  - Multi-phase discovery workflow (Discovery → Analysis → Task)
  - Auto-detection of initialization vs. enhancement scenarios
  - Integration with skill and guardian agent

- **Guardian Agent:** `claude-md-guardian` v1.0.0
  - Background maintenance and auto-sync
  - Smart change detection (git-based)
  - Token-efficient updates using haiku model
  - Milestone-aware triggering

#### Templates
- **7 Reference CLAUDE.md Templates:**
  - `minimal-solo-CLAUDE.md` - Solo developer projects
  - `core-small-team-CLAUDE.md` - Small team projects (2-9 devs)
  - `python-api-CLAUDE.md` - Python API projects
  - `modular-root-CLAUDE.md` - Root navigation for modular setups
  - `modular-backend-CLAUDE.md` - Backend-specific guidelines
  - `modular-frontend-CLAUDE.md` - Frontend-specific guidelines
  - Reference examples covering TypeScript, Python, React, FastAPI, and more

#### Tech Stack Support
- **Frontend:** React, Vue, Angular, TypeScript, JavaScript
- **Backend:** Node.js, Python (Django, FastAPI, Flask), Go, Java (Spring Boot), Ruby (Rails)
- **Databases:** PostgreSQL, MongoDB, Redis, MySQL
- **Infrastructure:** Docker, Kubernetes, CI/CD systems

#### Team Size Adaptation
- **Solo** - Minimal guidelines (50-75 lines)
- **Small (<10)** - Core guidelines (100-150 lines)
- **Medium (10-50)** - Detailed guidelines (200-300 lines)
- **Large (50+)** - Comprehensive guidelines (modular architecture)

#### Installation
- **Automated Installers:**
  - `install.sh` - macOS/Linux bash installer
  - `install.ps1` - Windows PowerShell installer
- **Installation Options:**
  - User-level (`~/.claude/`) - Available in all projects
  - Project-level (`./.claude/`) - Current project only
- **One-line Installation:**
  ```bash
  curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash
  ```

#### Documentation
- **Root Documentation:**
  - `README.md` - Comprehensive project overview with badges and quick start
  - `CHANGELOG.md` - Version history (this file)
  - `LICENSE` - MIT License

- **Detailed Guides:**
  - `docs/INSTALLATION.md` - Installation guide with troubleshooting
  - `docs/QUICK_START.md` - 5-minute tutorial
  - `docs/ARCHITECTURE.md` - Component architecture and data flow
  - `docs/TROUBLESHOOTING.md` - Common issues and solutions
  - `docs/CONTRIBUTING.md` - Contribution guidelines

- **Usage Examples:**
  - `examples/basic-usage.md` - Basic usage scenarios
  - `examples/modular-setup.md` - Modular architecture examples
  - `examples/integration-examples.md` - Integration patterns

#### GitHub Integration
- **CI/CD:**
  - `.github/workflows/validate.yml` - Automated validation workflow
  - Quality checks on pull requests

- **Community Templates:**
  - `.github/ISSUE_TEMPLATE/bug_report.md` - Bug report template
  - `.github/ISSUE_TEMPLATE/feature_request.md` - Feature request template
  - `.github/PULL_REQUEST_TEMPLATE.md` - Pull request template
  - `.github/CODE_OF_CONDUCT.md` - Code of conduct

#### Quality Hooks
- **Pre-commit Hook** - `hooks/pre-commit.sh`
  - Validates CLAUDE.md file quality before commits
  - Ensures best practices compliance
  - Optional installation during setup

### Quality Metrics

- **Quality Score Calculation (0-100):**
  - Length appropriateness: 25 points
  - Section completeness: 25 points
  - Formatting quality: 20 points
  - Content specificity: 15 points
  - Modular organization: 15 points

- **Validation Checks (5 categories):**
  - File length (20-300 lines recommended)
  - Structure (required sections present)
  - Formatting (markdown quality)
  - Completeness (essential content)
  - Anti-patterns (security, placeholders)

### Technical Details

- **Python Version:** 3.7+ compatible
- **Dependencies:** Standard library only (no external dependencies)
- **Total Code:** ~2,190 lines across 5 modules
- **Claude Code Compatibility:** 2.0+
- **Operating Systems:** macOS, Linux, Windows

### What's Next

See [Unreleased](#unreleased) section for planned features.

---

## [Unreleased]

### Planned for v1.1.0
- **Additional Templates:**
  - Rust/Cargo projects
  - Mobile (React Native, Flutter)
  - Desktop (Electron, Tauri)
  - Microservices architecture template

- **Enhanced Detection:**
  - Improved tech stack detection accuracy
  - Project phase detection from git history
  - Team size estimation from commit patterns

- **Quality Improvements:**
  - More granular quality scoring
  - Section-specific recommendations
  - Automated fix suggestions

### Planned for v1.2.0
- **VS Code Extension** (Future)
  - Inline CLAUDE.md editing
  - Real-time validation
  - Quick actions panel

- **GitHub Actions** (Enhanced)
  - Automated CLAUDE.md generation on repo creation
  - PR checks for CLAUDE.md quality
  - Auto-update on dependency changes

- **Advanced Hooks:**
  - Pre-push validation
  - Post-merge synchronization
  - Automated quality reports

### Under Consideration
- **Multi-language Support** - i18n for generated content
- **Custom Template Creation** - User-defined templates
- **AI-Powered Suggestions** - Context-aware recommendations
- **Integration with Other Tools** - Slack, Discord notifications
- **Web Dashboard** - Project-wide CLAUDE.md management
- **Analytics** - Usage patterns and effectiveness metrics

---

## Version History

| Version | Date | Status | Highlights |
|---------|------|--------|------------|
| 1.0.0 | 2025-11-12 | ✅ Stable | Initial release with full feature set |

---

## Contributing

See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for details on how to contribute to ClaudeForge.

---

## Links

- **Repository:** https://github.com/alirezarezvani/ClaudeForge
- **Issues:** https://github.com/alirezarezvani/ClaudeForge/issues
- **Discussions:** https://github.com/alirezarezvani/ClaudeForge/discussions
- **Releases:** https://github.com/alirezarezvani/ClaudeForge/releases

---

**Made with ❤️ for the Claude Code community**