justin/ClaudeForge
1
0
Fork 0
mirror of https://github.com/alirezarezvani/ClaudeForge.git synced 2026-07-04 10:53:16 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
e7512689c18cf78b0421e778852f0089ed20bab6
ClaudeForge/CHANGELOG.md
T

339 lines
13 KiB
Markdown
Raw Blame History

# 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]
---
## [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**
Reference in New Issue View Git Blame Copy Permalink