mirror of
https://github.com/alirezarezvani/ClaudeForge.git
synced 2026-07-03 02:13:15 -04:00
Initial commit: ClaudeForge v1.0.0
This commit is contained in:
Reza Rezvani
@@ -0,0 +1,548 @@
|
||||
# Architecture Overview
|
||||
|
||||
Technical architecture and design decisions for ClaudeForge.
|
||||
|
||||
---
|
||||
|
||||
## System Design
|
||||
|
||||
### Component Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ User Project │
|
||||
│ │
|
||||
│ User runs: /enhance-claude-md │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Slash Command (enhance-claude-md.md) │
|
||||
│ │
|
||||
│ Phase 1: Discovery - Check CLAUDE.md existence │
|
||||
│ Phase 2: Analysis - Determine initialize/enhance │
|
||||
│ Phase 3: Task - Invoke skill or agent │
|
||||
└────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ │
|
||||
↓ ↓
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ Guardian Agent │ │ Direct Skill │
|
||||
│ (Background) │ │ Invocation │
|
||||
│ │ │ │
|
||||
│ • SessionStart │ │ • User request │
|
||||
│ • Manual invoke │ │ • One-time gen │
|
||||
└────────┬─────────┘ └─────────┬────────┘
|
||||
│ │
|
||||
└────────────┬───────────┘
|
||||
│
|
||||
↓
|
||||
┌────────────────────────┐
|
||||
│ Skill: claudeforge │
|
||||
│ │
|
||||
│ Python Modules: │
|
||||
│ • workflow.py │
|
||||
│ • analyzer.py │
|
||||
│ • validator.py │
|
||||
│ • template_selector │
|
||||
│ • generator.py │
|
||||
└────────────┬───────────┘
|
||||
│
|
||||
↓
|
||||
┌────────────────────────┐
|
||||
│ CLAUDE.md Output │
|
||||
│ │
|
||||
│ • Root file │
|
||||
│ • Context files │
|
||||
│ • Native format │
|
||||
└────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
### 1. New Project Initialization
|
||||
|
||||
```
|
||||
1. User → /enhance-claude-md
|
||||
2. Command checks: CLAUDE.md not found
|
||||
3. Command → Skill (initialize mode)
|
||||
4. Skill workflow.py:
|
||||
- generate_exploration_prompt()
|
||||
- Claude explores repository
|
||||
- analyze_discoveries(exploration_results)
|
||||
- Returns project_context
|
||||
5. Skill template_selector.py:
|
||||
- select_template(project_context)
|
||||
- Returns template configuration
|
||||
6. Skill generator.py:
|
||||
- generate_root_file(template)
|
||||
- Returns CLAUDE.md content
|
||||
7. Skill validator.py:
|
||||
- validate_all(generated_content)
|
||||
- Returns validation report
|
||||
8. Output → CLAUDE.md file(s) created
|
||||
```
|
||||
|
||||
### 2. Existing Project Enhancement
|
||||
|
||||
```
|
||||
1. User → /enhance-claude-md
|
||||
2. Command checks: CLAUDE.md exists
|
||||
3. Command → Skill (enhance mode)
|
||||
4. Skill analyzer.py:
|
||||
- analyze_file(current_content)
|
||||
- calculate_quality_score()
|
||||
- Returns analysis report
|
||||
5. Skill validator.py:
|
||||
- validate_all(current_content)
|
||||
- Returns validation results
|
||||
6. Skill shows user:
|
||||
- Quality score (0-100)
|
||||
- Missing sections
|
||||
- Recommendations
|
||||
7. User confirms enhancement
|
||||
8. Skill generator.py:
|
||||
- merge_with_existing(content, sections)
|
||||
- Returns enhanced content
|
||||
9. Output → CLAUDE.md updated
|
||||
```
|
||||
|
||||
### 3. Background Maintenance
|
||||
|
||||
```
|
||||
1. SessionStart event
|
||||
2. Guardian agent triggered
|
||||
3. Agent checks git changes:
|
||||
- git diff --name-status HEAD~10
|
||||
- git diff package.json requirements.txt
|
||||
4. Agent determines significance:
|
||||
- Files changed > 5?
|
||||
- New dependencies?
|
||||
- New directories?
|
||||
5. If significant:
|
||||
- Agent → Skill (enhance mode)
|
||||
- Skill updates specific sections
|
||||
- Agent validates changes
|
||||
6. Output → CLAUDE.md synced
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Module Design
|
||||
|
||||
### workflow.py
|
||||
|
||||
**Purpose:** Interactive initialization for new projects
|
||||
|
||||
**Key Classes:**
|
||||
- `InitializationWorkflow` - Main orchestrator
|
||||
|
||||
**Key Methods:**
|
||||
```python
|
||||
check_claude_md_exists() → bool
|
||||
generate_exploration_prompt() → str
|
||||
analyze_discoveries(results: Dict) → Dict[str, Any]
|
||||
_detect_project_type(results) → str
|
||||
_detect_tech_stack(results) → List[str]
|
||||
_estimate_team_size(results) → str
|
||||
_detect_development_phase(results) → str
|
||||
_detect_workflows(results) → List[str]
|
||||
_should_use_modular(results) → bool
|
||||
```
|
||||
|
||||
**Detection Logic:**
|
||||
- Project type: Check for frontend/, backend/, src/ patterns
|
||||
- Tech stack: Parse package.json, requirements.txt, go.mod
|
||||
- Team size: Analyze git contributors, project complexity
|
||||
- Phase: Check for CI/CD, production configs
|
||||
- Workflows: Detect test/, .github/, documentation patterns
|
||||
|
||||
---
|
||||
|
||||
### analyzer.py
|
||||
|
||||
**Purpose:** Analyze existing CLAUDE.md files
|
||||
|
||||
**Key Classes:**
|
||||
- `CLAUDEMDAnalyzer` - File analyzer
|
||||
|
||||
**Quality Scoring Algorithm:**
|
||||
```python
|
||||
def calculate_quality_score(self) → int:
|
||||
score = 0
|
||||
|
||||
# Length appropriateness (25 points)
|
||||
if 20 <= line_count <= 300:
|
||||
score += 25
|
||||
elif 300 < line_count <= 400:
|
||||
score += 15 # Warn: consider modular
|
||||
else:
|
||||
score += 5 # Poor: too short or too long
|
||||
|
||||
# Section completeness (25 points)
|
||||
required = ["Core Principles", "Tech Stack", "Workflow"]
|
||||
found = len([s for s in required if s in sections])
|
||||
score += (found / len(required)) * 25
|
||||
|
||||
# Formatting quality (20 points)
|
||||
# Check: headings, code blocks, lists, links
|
||||
score += formatting_score
|
||||
|
||||
# Content specificity (15 points)
|
||||
# Check: project-specific vs. generic
|
||||
score += specificity_score
|
||||
|
||||
# Modular organization (15 points)
|
||||
# Check: context files if needed
|
||||
score += modular_score
|
||||
|
||||
return min(score, 100)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### validator.py
|
||||
|
||||
**Purpose:** Validate against best practices
|
||||
|
||||
**Validation Categories:**
|
||||
|
||||
1. **Length Validation**
|
||||
- Recommended: 20-300 lines
|
||||
- Warning: 300-400 lines (suggest modular)
|
||||
- Error: < 20 or > 400 lines
|
||||
|
||||
2. **Structure Validation**
|
||||
- Required sections: Core Principles, Tech Stack, Workflow
|
||||
- Recommended sections: Testing, Error Handling
|
||||
- Heading hierarchy: H1 → H2 → H3 (no skips)
|
||||
|
||||
3. **Formatting Validation**
|
||||
- Balanced code blocks (open/close)
|
||||
- Valid markdown syntax
|
||||
- No broken links
|
||||
|
||||
4. **Completeness Validation**
|
||||
- Has code examples
|
||||
- Lists tech stack with versions
|
||||
- Includes setup instructions
|
||||
|
||||
5. **Anti-Pattern Detection**
|
||||
- No hardcoded secrets (API keys, tokens)
|
||||
- No TODO placeholders
|
||||
- No broken reference links
|
||||
|
||||
---
|
||||
|
||||
### template_selector.py
|
||||
|
||||
**Purpose:** Select appropriate template
|
||||
|
||||
**Selection Matrix:**
|
||||
|
||||
| Project Type | Team Size | Lines | Template |
|
||||
|--------------|-----------|-------|----------|
|
||||
| CLI/Library | Solo | 50-75 | minimal |
|
||||
| Web App | Small | 100-150 | core |
|
||||
| API | Small | 125-175 | api-focused |
|
||||
| Full-Stack | Medium | 200-300 | detailed |
|
||||
| Enterprise | Large | Modular | root + contexts |
|
||||
|
||||
**Modular Recommendation Logic:**
|
||||
```python
|
||||
def recommend_modular_structure(context: Dict) → bool:
|
||||
return (
|
||||
context['type'] == 'fullstack' or
|
||||
context['team_size'] in ['medium', 'large'] or
|
||||
context['phase'] in ['production', 'enterprise'] or
|
||||
len(context['tech_stack']) > 5
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### generator.py
|
||||
|
||||
**Purpose:** Generate CLAUDE.md content
|
||||
|
||||
**Generation Modes:**
|
||||
|
||||
1. **Root File (Navigation Hub)**
|
||||
- Quick Navigation section
|
||||
- Core Principles (high-level)
|
||||
- Tech Stack summary
|
||||
- Links to context files
|
||||
|
||||
2. **Context File (Specific Area)**
|
||||
- Detailed guidelines for backend/, frontend/, etc.
|
||||
- Tech-specific patterns
|
||||
- Common commands for that area
|
||||
|
||||
3. **Section Generation (Individual)**
|
||||
- Generate single section
|
||||
- Merge with existing content
|
||||
|
||||
**Native Format Template:**
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
[Overview paragraph]
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── src/
|
||||
│ ├── components/
|
||||
│ └── services/
|
||||
└── tests/
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
- `src/` - Source code
|
||||
- `tests/` - Test files
|
||||
|
||||
## Setup & Installation
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
[Key design decisions]
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. Principle one
|
||||
2. Principle two
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- React 18
|
||||
- TypeScript 5
|
||||
- Node.js 20
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
npm run build # Build project
|
||||
npm test # Run tests
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Skill ↔ Slash Command
|
||||
|
||||
**File:** `command/enhance-claude-md.md`
|
||||
|
||||
```yaml
|
||||
# YAML frontmatter
|
||||
allowed-tools: Bash, Read, Glob, Skill
|
||||
|
||||
# Phase 3: Task section
|
||||
I can invoke the `claude-md-enhancer` skill...
|
||||
```
|
||||
|
||||
Claude Code recognizes skill name and loads Python modules.
|
||||
|
||||
### Skill ↔ Guardian Agent
|
||||
|
||||
**File:** `agent/claude-md-guardian.md`
|
||||
|
||||
```yaml
|
||||
# YAML frontmatter
|
||||
tools: Bash, Read, Write, Edit, Grep, Glob, Skill
|
||||
model: haiku
|
||||
|
||||
# Agent workflow section
|
||||
I invoke the `claude-md-enhancer` skill...
|
||||
```
|
||||
|
||||
Agent uses `haiku` model for token efficiency, invokes skill for updates.
|
||||
|
||||
### Agent ↔ Git
|
||||
|
||||
Agent detects changes via bash commands:
|
||||
```bash
|
||||
git diff --name-status HEAD~10
|
||||
git log --since="1 week ago" --oneline
|
||||
git diff HEAD~10 -- package.json requirements.txt
|
||||
```
|
||||
|
||||
Triggers update if:
|
||||
- 5+ files changed
|
||||
- Dependencies modified
|
||||
- New directories created
|
||||
|
||||
---
|
||||
|
||||
## Design Decisions
|
||||
|
||||
### Why Python for Skill Modules?
|
||||
|
||||
- **Portability:** Standard library only, no dependencies
|
||||
- **Readability:** Clear logic for community contributions
|
||||
- **Performance:** Adequate for file analysis/generation
|
||||
- **Integration:** Claude Code supports Python natively
|
||||
|
||||
### Why Separate Slash Command and Agent?
|
||||
|
||||
- **Slash Command:** User-initiated, interactive, immediate feedback
|
||||
- **Agent:** Background, automatic, non-intrusive
|
||||
- **Flexibility:** User chooses explicit control vs. automation
|
||||
|
||||
### Why Quality Scoring Algorithm?
|
||||
|
||||
- **Objectivity:** Consistent evaluation across projects
|
||||
- **Actionable:** Specific areas to improve
|
||||
- **Educational:** Users learn best practices
|
||||
- **Gamification:** Encourages quality improvement
|
||||
|
||||
### Why Modular Architecture Support?
|
||||
|
||||
- **Scalability:** Large projects need organization
|
||||
- **Context:** Different areas have different needs
|
||||
- **Maintainability:** Easier to update specific sections
|
||||
- **Team:** Different teams own different files
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Token Efficiency
|
||||
|
||||
**Guardian Agent uses `haiku` model:**
|
||||
- Routine updates: ~500-1000 tokens
|
||||
- Targeted section updates only
|
||||
- Saves 70-80% tokens vs. full regeneration
|
||||
|
||||
**Slash Command uses default model (sonnet):**
|
||||
- Interactive, user-facing
|
||||
- Requires better understanding
|
||||
- More complex reasoning
|
||||
|
||||
### File Size Limits
|
||||
|
||||
- Single file: Max 400 lines (prefer 300)
|
||||
- Modular files: Each 150-300 lines
|
||||
- Total project: Unlimited with modular
|
||||
|
||||
### Caching Strategy
|
||||
|
||||
No caching implemented (stateless design):
|
||||
- Each invocation reads fresh files
|
||||
- Ensures accuracy with latest changes
|
||||
- Simple implementation
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Anti-Pattern Detection
|
||||
|
||||
**validator.py** checks for:
|
||||
- Hardcoded secrets: `API_KEY=`, `password=`, `token=`
|
||||
- Placeholder TODOs: `TODO`, `FIXME`, `XXX`
|
||||
- Broken links: Invalid URL patterns
|
||||
|
||||
### File Permissions
|
||||
|
||||
Installation respects user permissions:
|
||||
- User-level: `~/.claude/` (user writable)
|
||||
- Project-level: `./.claude/` (project writable)
|
||||
- No system-level changes
|
||||
|
||||
### Git Integration
|
||||
|
||||
Agent only reads git:
|
||||
- `git diff` (read-only)
|
||||
- `git log` (read-only)
|
||||
- `git status` (read-only)
|
||||
- No git write operations
|
||||
|
||||
---
|
||||
|
||||
## Extensibility
|
||||
|
||||
### Adding New Project Types
|
||||
|
||||
1. Update `workflow.py` → `_detect_project_type()`
|
||||
2. Add detection patterns
|
||||
3. Update `template_selector.py` → selection matrix
|
||||
4. Create new template in `skill/examples/`
|
||||
|
||||
### Adding New Tech Stacks
|
||||
|
||||
1. Update `workflow.py` → `_detect_tech_stack()`
|
||||
2. Add file detection (e.g., `Cargo.toml` for Rust)
|
||||
3. Update `generator.py` → tech-specific sections
|
||||
|
||||
### Adding New Validation Rules
|
||||
|
||||
1. Update `validator.py` → `validate_all()`
|
||||
2. Add new validation method
|
||||
3. Return validation result in standard format
|
||||
|
||||
---
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Manual Testing
|
||||
|
||||
See [QUICK_START.md](QUICK_START.md) for test scenarios.
|
||||
|
||||
### Integration Testing
|
||||
|
||||
Test entire flow:
|
||||
1. Install components
|
||||
2. Run slash command
|
||||
3. Verify output quality
|
||||
4. Test guardian agent
|
||||
5. Validate native format
|
||||
|
||||
### Unit Testing
|
||||
|
||||
(Not implemented in v1.0.0, planned for v1.1.0)
|
||||
- Test each Python module independently
|
||||
- Mock file I/O
|
||||
- Validate scoring algorithms
|
||||
|
||||
---
|
||||
|
||||
## Future Architecture
|
||||
|
||||
### Planned for v1.1.0
|
||||
|
||||
- **VS Code Extension:** Inline editing, real-time validation
|
||||
- **GitHub Action:** Auto-generate on repo creation
|
||||
- **Custom Templates:** User-defined template system
|
||||
- **Analytics:** Usage patterns, effectiveness metrics
|
||||
|
||||
### Planned for v2.0.0
|
||||
|
||||
- **AI-Powered Suggestions:** Context-aware recommendations
|
||||
- **Multi-Language Support:** i18n for generated content
|
||||
- **Web Dashboard:** Project-wide management
|
||||
- **Plugin System:** Third-party extensions
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Implementation Details:** [CLAUDE.md](../CLAUDE.md)
|
||||
- **Installation:** [INSTALLATION.md](INSTALLATION.md)
|
||||
- **Quick Start:** [QUICK_START.md](QUICK_START.md)
|
||||
- **Troubleshooting:** [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||
|
||||
---
|
||||
|
||||
**Questions about architecture?** Open an issue: https://github.com/alirezarezvani/ClaudeForge/issues
|
||||
@@ -0,0 +1,490 @@
|
||||
# Contributing to ClaudeForge
|
||||
|
||||
Thank you for your interest in contributing to ClaudeForge! This guide will help you get started.
|
||||
|
||||
---
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
By participating in this project, you agree to abide by our [Code of Conduct](../.github/CODE_OF_CONDUCT.md).
|
||||
|
||||
---
|
||||
|
||||
## How Can I Contribute?
|
||||
|
||||
### 1. Reporting Bugs
|
||||
|
||||
**Before submitting a bug report:**
|
||||
- Check existing issues to avoid duplicates
|
||||
- Collect information about the bug
|
||||
- Test with the latest version
|
||||
|
||||
**Submit a bug report:**
|
||||
- Use the bug report template
|
||||
- Provide clear title and description
|
||||
- Include steps to reproduce
|
||||
- Add relevant logs or screenshots
|
||||
- Mention your environment (OS, Claude Code version)
|
||||
|
||||
**Template:** https://github.com/alirezarezvani/ClaudeForge/issues/new?template=bug_report.md
|
||||
|
||||
---
|
||||
|
||||
### 2. Suggesting Enhancements
|
||||
|
||||
**Before submitting:**
|
||||
- Check if the feature already exists
|
||||
- Review planned features in CHANGELOG.md
|
||||
- Consider if it fits project scope
|
||||
|
||||
**Submit an enhancement:**
|
||||
- Use the feature request template
|
||||
- Explain the use case
|
||||
- Describe proposed solution
|
||||
- Consider alternatives
|
||||
|
||||
**Template:** https://github.com/alirezarezvani/ClaudeForge/issues/new?template=feature_request.md
|
||||
|
||||
---
|
||||
|
||||
### 3. Contributing Code
|
||||
|
||||
#### Quick Start
|
||||
|
||||
```bash
|
||||
# Fork the repository
|
||||
# Clone your fork
|
||||
git clone https://github.com/YOUR-USERNAME/ClaudeForge.git
|
||||
cd ClaudeForge
|
||||
|
||||
# Create a branch
|
||||
git checkout -b feature/amazing-feature
|
||||
|
||||
# Make your changes
|
||||
# Test your changes
|
||||
./install.sh # Test installation
|
||||
/enhance-claude-md # Test in Claude Code
|
||||
|
||||
# Commit your changes
|
||||
git commit -m "Add amazing feature"
|
||||
|
||||
# Push to your fork
|
||||
git push origin feature/amazing-feature
|
||||
|
||||
# Open a Pull Request
|
||||
```
|
||||
|
||||
#### Development Setup
|
||||
|
||||
```bash
|
||||
# Install development dependencies
|
||||
# (None required - Python standard library only)
|
||||
|
||||
# Test Python modules
|
||||
python3 -c "from skill.analyzer import CLAUDEMDAnalyzer; print('OK')"
|
||||
|
||||
# Test installation scripts
|
||||
./install.sh
|
||||
# Choose option 2 (project-level) for testing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Python Code Style
|
||||
|
||||
**Follow PEP 8:**
|
||||
```python
|
||||
# Good
|
||||
def analyze_file(self, content: str) -> Dict[str, Any]:
|
||||
"""Analyze CLAUDE.md file content."""
|
||||
pass
|
||||
|
||||
# Bad
|
||||
def analyzeFile(self,content):
|
||||
pass
|
||||
```
|
||||
|
||||
**Type Hints:**
|
||||
```python
|
||||
# Always use type hints
|
||||
def calculate_score(sections: List[str]) → int:
|
||||
return len(sections) * 10
|
||||
```
|
||||
|
||||
**Docstrings:**
|
||||
```python
|
||||
def validate_length(self, content: str) -> bool:
|
||||
"""
|
||||
Validate CLAUDE.md file length.
|
||||
|
||||
Args:
|
||||
content: File content as string
|
||||
|
||||
Returns:
|
||||
True if length is valid, False otherwise
|
||||
"""
|
||||
pass
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Markdown Style
|
||||
|
||||
**Headings:**
|
||||
```markdown
|
||||
# H1 - Document title
|
||||
## H2 - Main sections
|
||||
### H3 - Subsections
|
||||
```
|
||||
|
||||
**Code Blocks:**
|
||||
```markdown
|
||||
```bash
|
||||
# Use language-specific syntax highlighting
|
||||
command here
|
||||
```
|
||||
```
|
||||
|
||||
**Links:**
|
||||
```markdown
|
||||
# Prefer relative links for internal docs
|
||||
[Architecture](ARCHITECTURE.md)
|
||||
|
||||
# Use absolute URLs for external
|
||||
[GitHub](https://github.com/alirezarezvani/ClaudeForge)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Testing Your Changes
|
||||
|
||||
#### Test Python Modules
|
||||
|
||||
```bash
|
||||
# Test analyzer
|
||||
python3 << EOF
|
||||
from skill.analyzer import CLAUDEMDAnalyzer
|
||||
content = open('test-CLAUDE.md').read()
|
||||
analyzer = CLAUDEMDAnalyzer(content)
|
||||
report = analyzer.analyze_file()
|
||||
print(f"Quality Score: {report['quality_score']}")
|
||||
EOF
|
||||
```
|
||||
|
||||
#### Test Installation
|
||||
|
||||
```bash
|
||||
# Test install.sh
|
||||
./install.sh
|
||||
# Choose option 2 (project-level)
|
||||
# Verify all components copied correctly
|
||||
|
||||
# Test uninstall
|
||||
rm -rf ./.claude
|
||||
```
|
||||
|
||||
#### Test in Claude Code
|
||||
|
||||
```bash
|
||||
# Install your changes
|
||||
./install.sh
|
||||
|
||||
# Restart Claude Code
|
||||
|
||||
# Test slash command
|
||||
/enhance-claude-md
|
||||
|
||||
# Verify output matches expected behavior
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Contribution Areas
|
||||
|
||||
### 1. Adding New Templates
|
||||
|
||||
**Location:** `skill/examples/`
|
||||
|
||||
**Steps:**
|
||||
1. Create new template file (e.g., `rust-cli-CLAUDE.md`)
|
||||
2. Follow native format structure
|
||||
3. Update `skill/examples/README.md`
|
||||
4. Update `template_selector.py` detection logic
|
||||
5. Add test case to `sample_input.json`
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Create Rust template
|
||||
vim skill/examples/rust-cli-CLAUDE.md
|
||||
|
||||
# Update selector
|
||||
vim skill/template_selector.py
|
||||
# Add: if 'Cargo.toml' in files: return 'rust-cli'
|
||||
|
||||
# Test
|
||||
# Create test Rust project, run /enhance-claude-md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Improving Detection Logic
|
||||
|
||||
**Location:** `skill/workflow.py`
|
||||
|
||||
**Methods to enhance:**
|
||||
- `_detect_project_type()`
|
||||
- `_detect_tech_stack()`
|
||||
- `_estimate_team_size()`
|
||||
- `_detect_development_phase()`
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Add Flutter detection
|
||||
def _detect_project_type(self, results):
|
||||
files = results.get('files', [])
|
||||
|
||||
# Add Flutter check
|
||||
if 'pubspec.yaml' in files:
|
||||
return 'mobile'
|
||||
|
||||
# ... existing logic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Enhancing Quality Scoring
|
||||
|
||||
**Location:** `skill/analyzer.py`
|
||||
|
||||
**Method:** `calculate_quality_score()`
|
||||
|
||||
**Ideas:**
|
||||
- Add more granular checks
|
||||
- Weight sections by importance
|
||||
- Detect project-specific customization
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
def calculate_quality_score(self) -> int:
|
||||
score = 0
|
||||
|
||||
# Add new check: Has examples
|
||||
if self._has_code_examples():
|
||||
score += 5 # Bonus points
|
||||
|
||||
# ... existing logic
|
||||
return min(score, 100)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Adding New Validation Rules
|
||||
|
||||
**Location:** `skill/validator.py`
|
||||
|
||||
**Steps:**
|
||||
1. Add new validation method
|
||||
2. Call from `validate_all()`
|
||||
3. Return standard validation result
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
def validate_examples(self) -> Dict[str, Any]:
|
||||
"""Validate code examples are present."""
|
||||
code_blocks = re.findall(r'```.*?```', self.content, re.DOTALL)
|
||||
|
||||
return {
|
||||
'passed': len(code_blocks) >= 3,
|
||||
'message': 'At least 3 code examples required',
|
||||
'severity': 'low'
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Documentation Improvements
|
||||
|
||||
**Areas:**
|
||||
- Fix typos or unclear explanations
|
||||
- Add missing examples
|
||||
- Improve installation instructions
|
||||
- Translate to other languages (future)
|
||||
|
||||
**Process:**
|
||||
1. Edit markdown files in `docs/`
|
||||
2. Test markdown rendering locally
|
||||
3. Submit pull request
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
### 1. Before Submitting
|
||||
|
||||
- [ ] Code follows project style guidelines
|
||||
- [ ] All tests pass (manual testing required)
|
||||
- [ ] Documentation updated if needed
|
||||
- [ ] CHANGELOG.md updated with your changes
|
||||
- [ ] Commit messages are clear and descriptive
|
||||
|
||||
### 2. Submitting
|
||||
|
||||
1. **Create Pull Request** from your fork
|
||||
2. **Fill out PR template** completely
|
||||
3. **Link related issues** (if any)
|
||||
4. **Request review** from maintainers
|
||||
5. **Respond to feedback** promptly
|
||||
|
||||
### 3. After Submission
|
||||
|
||||
- **CI checks** will run automatically
|
||||
- **Maintainers** will review your code
|
||||
- **Address feedback** by pushing new commits
|
||||
- **Don't force-push** after review started
|
||||
- **Be patient** - reviews may take a few days
|
||||
|
||||
### 4. Merging
|
||||
|
||||
Once approved:
|
||||
- Maintainer will merge your PR
|
||||
- Your contribution will be in the next release
|
||||
- You'll be added to contributors list
|
||||
|
||||
---
|
||||
|
||||
## Commit Message Guidelines
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
type(scope): Short description
|
||||
|
||||
Longer description if needed.
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Code style changes (no logic change)
|
||||
- `refactor`: Code refactoring
|
||||
- `test`: Adding tests
|
||||
- `chore`: Maintenance tasks
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
feat(analyzer): Add code example detection
|
||||
|
||||
Adds check for code examples in CLAUDE.md files.
|
||||
Contributes to quality score calculation.
|
||||
|
||||
Fixes #45
|
||||
```
|
||||
|
||||
```
|
||||
fix(installer): Resolve Windows path issues
|
||||
|
||||
Fixes path separator issues on Windows platforms.
|
||||
Updates install.ps1 to use platform-specific paths.
|
||||
|
||||
Fixes #67
|
||||
```
|
||||
|
||||
```
|
||||
docs(quick-start): Clarify installation steps
|
||||
|
||||
Adds more detailed explanations for each step.
|
||||
Includes troubleshooting for common issues.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Release Process
|
||||
|
||||
(For maintainers)
|
||||
|
||||
### Version Numbering
|
||||
|
||||
Follow Semantic Versioning (MAJOR.MINOR.PATCH):
|
||||
- MAJOR: Breaking changes
|
||||
- MINOR: New features (backward compatible)
|
||||
- PATCH: Bug fixes (backward compatible)
|
||||
|
||||
### Release Checklist
|
||||
|
||||
1. **Update version:**
|
||||
- `CHANGELOG.md` - Add new version section
|
||||
- `README.md` - Update version badge
|
||||
- `skill/SKILL.md` - Update version footer
|
||||
|
||||
2. **Create release:**
|
||||
```bash
|
||||
git tag -a v1.1.0 -m "Release v1.1.0"
|
||||
git push origin v1.1.0
|
||||
```
|
||||
|
||||
3. **GitHub Release:**
|
||||
- Create release from tag
|
||||
- Copy CHANGELOG excerpt to description
|
||||
- Attach any binaries if needed
|
||||
|
||||
4. **Announce:**
|
||||
- GitHub Discussions
|
||||
- Social media (if applicable)
|
||||
- Update documentation site
|
||||
|
||||
---
|
||||
|
||||
## Community
|
||||
|
||||
### Getting Help
|
||||
|
||||
- **GitHub Discussions:** Ask questions, share ideas
|
||||
- **GitHub Issues:** Report bugs, request features
|
||||
- **Documentation:** Comprehensive guides in `docs/`
|
||||
|
||||
### Staying Updated
|
||||
|
||||
- **Watch Repository:** Get notifications for releases
|
||||
- **Star Repository:** Show support, stay informed
|
||||
- **Follow Updates:** Check CHANGELOG.md for changes
|
||||
|
||||
---
|
||||
|
||||
## Recognition
|
||||
|
||||
Contributors are recognized in:
|
||||
- **README.md** - Contributors section
|
||||
- **CHANGELOG.md** - Version-specific contributors
|
||||
- **GitHub** - Automatic contributors graph
|
||||
|
||||
Every contribution matters, from code to documentation to bug reports!
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
- **General Questions:** GitHub Discussions
|
||||
- **Bug Reports:** GitHub Issues
|
||||
- **Security Issues:** Email maintainers directly (see SECURITY.md if created)
|
||||
- **Feature Requests:** GitHub Issues with feature template
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
By contributing, you agree that your contributions will be licensed under the MIT License.
|
||||
|
||||
See [LICENSE](../LICENSE) for details.
|
||||
|
||||
---
|
||||
|
||||
**Thank you for contributing to ClaudeForge!** 🎉
|
||||
|
||||
Your contributions help make CLAUDE.md management better for everyone in the Claude Code community.
|
||||
@@ -0,0 +1,412 @@
|
||||
# Installation Guide
|
||||
|
||||
Complete installation instructions for ClaudeForge on all supported platforms.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required
|
||||
- **Claude Code** 2.0 or later
|
||||
- **Operating System:** macOS, Linux, or Windows
|
||||
|
||||
### Recommended
|
||||
- **Git** (for change detection by guardian agent)
|
||||
- Terminal access (macOS/Linux) or PowerShell (Windows)
|
||||
|
||||
---
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### Method 1: One-Line Install (Recommended)
|
||||
|
||||
#### macOS / Linux
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash
|
||||
```
|
||||
|
||||
#### Windows (PowerShell as Administrator)
|
||||
|
||||
```powershell
|
||||
iwr https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.ps1 -useb | iex
|
||||
```
|
||||
|
||||
**What this does:**
|
||||
1. Downloads the installer script
|
||||
2. Prompts for installation scope (user-level or project-level)
|
||||
3. Copies all components to appropriate directories
|
||||
4. Creates backups of any existing installations
|
||||
5. Optionally installs quality hooks
|
||||
|
||||
---
|
||||
|
||||
### Method 2: Manual Git Clone
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/alirezarezvani/ClaudeForge.git
|
||||
|
||||
# Navigate to directory
|
||||
cd ClaudeForge
|
||||
|
||||
# Run installer
|
||||
./install.sh # macOS/Linux
|
||||
# or
|
||||
.\install.ps1 # Windows
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Method 3: Manual Installation (Advanced)
|
||||
|
||||
If you prefer to manually copy files:
|
||||
|
||||
#### Step 1: Download Components
|
||||
|
||||
Download the latest release from:
|
||||
https://github.com/alirezarezvani/ClaudeForge/releases
|
||||
|
||||
#### Step 2: Choose Installation Scope
|
||||
|
||||
**User-Level (Recommended)** - Available in all Claude Code projects:
|
||||
```bash
|
||||
# macOS/Linux
|
||||
INSTALL_DIR="$HOME/.claude"
|
||||
|
||||
# Windows
|
||||
$INSTALL_DIR="$env:USERPROFILE\.claude"
|
||||
```
|
||||
|
||||
**Project-Level** - Available only in current project:
|
||||
```bash
|
||||
# macOS/Linux
|
||||
INSTALL_DIR="./.claude"
|
||||
|
||||
# Windows
|
||||
$INSTALL_DIR=".\.claude"
|
||||
```
|
||||
|
||||
#### Step 3: Copy Components
|
||||
|
||||
```bash
|
||||
# Create directories
|
||||
mkdir -p "$INSTALL_DIR/skills"
|
||||
mkdir -p "$INSTALL_DIR/commands"
|
||||
mkdir -p "$INSTALL_DIR/agents"
|
||||
|
||||
# Copy skill
|
||||
cp -r skill "$INSTALL_DIR/skills/claudeforge-skill"
|
||||
|
||||
# Copy slash command
|
||||
cp -r command "$INSTALL_DIR/commands/enhance-claude-md"
|
||||
|
||||
# Copy guardian agent
|
||||
cp agent/claude-md-guardian.md "$INSTALL_DIR/agents/"
|
||||
```
|
||||
|
||||
#### Step 4: Restart Claude Code
|
||||
|
||||
Close and restart Claude Code to load the new components.
|
||||
|
||||
---
|
||||
|
||||
## Installation Scopes
|
||||
|
||||
### User-Level Installation
|
||||
|
||||
**Location:** `~/.claude/` (or `%USERPROFILE%\.claude` on Windows)
|
||||
|
||||
**Advantages:**
|
||||
- ✅ Available in all Claude Code projects
|
||||
- ✅ Install once, use everywhere
|
||||
- ✅ Automatic updates apply globally
|
||||
|
||||
**Use When:**
|
||||
- You work on multiple projects
|
||||
- You want consistent CLAUDE.md standards across all projects
|
||||
- You're the primary developer on your machine
|
||||
|
||||
### Project-Level Installation
|
||||
|
||||
**Location:** `./.claude/` (in your project root)
|
||||
|
||||
**Advantages:**
|
||||
- ✅ Project-specific configuration
|
||||
- ✅ Version controlled with project (can commit to git)
|
||||
- ✅ Team members get same tools
|
||||
|
||||
**Use When:**
|
||||
- Different projects need different versions
|
||||
- You want to version control the tools
|
||||
- Team collaboration requires shared tooling
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
After installation, verify all components are installed correctly:
|
||||
|
||||
### Check Skill Installation
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
ls -la ~/.claude/skills/claudeforge-skill/
|
||||
|
||||
# Windows
|
||||
dir $env:USERPROFILE\.claude\skills\claudeforge-skill\
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
analyzer.py
|
||||
generator.py
|
||||
template_selector.py
|
||||
validator.py
|
||||
workflow.py
|
||||
SKILL.md
|
||||
README.md
|
||||
examples/
|
||||
```
|
||||
|
||||
### Check Command Installation
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
ls -la ~/.claude/commands/enhance-claude-md/
|
||||
|
||||
# Windows
|
||||
dir $env:USERPROFILE\.claude\commands\enhance-claude-md\
|
||||
```
|
||||
|
||||
**Expected output:**
|
||||
```
|
||||
enhance-claude-md.md
|
||||
README.md
|
||||
```
|
||||
|
||||
### Check Agent Installation
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
ls -la ~/.claude/agents/claude-md-guardian.md
|
||||
|
||||
# Windows
|
||||
dir $env:USERPROFILE\.claude\agents\claude-md-guardian.md
|
||||
```
|
||||
|
||||
### Test in Claude Code
|
||||
|
||||
1. Restart Claude Code
|
||||
2. Open any project
|
||||
3. Run the command:
|
||||
```
|
||||
/enhance-claude-md
|
||||
```
|
||||
4. You should see the multi-phase workflow start
|
||||
|
||||
---
|
||||
|
||||
## Quality Hooks (Optional)
|
||||
|
||||
During installation, you'll be asked if you want to install quality hooks.
|
||||
|
||||
**What are Quality Hooks?**
|
||||
- Pre-commit validation that checks CLAUDE.md quality before commits
|
||||
- Ensures best practices compliance
|
||||
- Only available for project-level installations
|
||||
|
||||
**To Install Hooks:**
|
||||
|
||||
```bash
|
||||
# During installer
|
||||
# When prompted: "Would you like to install quality hooks?"
|
||||
# Type: y
|
||||
|
||||
# Or manually:
|
||||
mkdir -p .claude/hooks
|
||||
cp hooks/pre-commit.sh .claude/hooks/
|
||||
chmod +x .claude/hooks/pre-commit.sh
|
||||
```
|
||||
|
||||
**To Use Hooks:**
|
||||
|
||||
Configure git to use the hook:
|
||||
```bash
|
||||
# Add to .git/config or use git config
|
||||
git config core.hooksPath .claude/hooks
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Installation
|
||||
|
||||
### Issue: "Installation files not found"
|
||||
|
||||
**Cause:** Running installer from wrong directory
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
cd ClaudeForge # Navigate to repository root
|
||||
./install.sh # Run from correct directory
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: "Permission denied"
|
||||
|
||||
**Cause:** Installer doesn't have execute permission
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
chmod +x install.sh # macOS/Linux
|
||||
# or run with bash explicitly
|
||||
bash install.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: "~/.claude directory not found"
|
||||
|
||||
**Cause:** Claude Code not installed or hasn't been run yet
|
||||
|
||||
**Solution:**
|
||||
1. Ensure Claude Code is installed
|
||||
2. Run Claude Code at least once to create directory structure
|
||||
3. Or let installer create directories (it will prompt)
|
||||
|
||||
---
|
||||
|
||||
### Issue: Command not recognized after installation
|
||||
|
||||
**Cause:** Claude Code hasn't reloaded components
|
||||
|
||||
**Solution:**
|
||||
1. Fully quit Claude Code (not just close window)
|
||||
2. Restart Claude Code
|
||||
3. Wait a few seconds for components to load
|
||||
4. Try command again: `/enhance-claude-md`
|
||||
|
||||
---
|
||||
|
||||
### Issue: "Skill not found" error
|
||||
|
||||
**Cause:** Skill directory name mismatch
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Verify skill directory name is exactly:
|
||||
ls ~/.claude/skills/
|
||||
# Should show: claudeforge-skill
|
||||
|
||||
# If different, rename:
|
||||
mv ~/.claude/skills/old-name ~/.claude/skills/claudeforge-skill
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: Windows installer fails with execution policy error
|
||||
|
||||
**Cause:** PowerShell execution policy restricts scripts
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Run PowerShell as Administrator
|
||||
# Set execution policy temporarily:
|
||||
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
|
||||
|
||||
# Then run installer:
|
||||
.\install.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Updating ClaudeForge
|
||||
|
||||
To update to a newer version:
|
||||
|
||||
### Method 1: Using Installer
|
||||
|
||||
```bash
|
||||
# Pull latest changes
|
||||
cd ClaudeForge
|
||||
git pull origin main
|
||||
|
||||
# Run installer (existing installation will be backed up)
|
||||
./install.sh
|
||||
```
|
||||
|
||||
### Method 2: Manual Update
|
||||
|
||||
```bash
|
||||
# Backup current installation
|
||||
mv ~/.claude/skills/claudeforge-skill ~/.claude/skills/claudeforge-skill.backup
|
||||
|
||||
# Copy new version
|
||||
cp -r skill ~/.claude/skills/claudeforge-skill
|
||||
|
||||
# Repeat for command and agent
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Uninstallation
|
||||
|
||||
To completely remove ClaudeForge:
|
||||
|
||||
### User-Level Uninstall
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
rm -rf ~/.claude/skills/claudeforge-skill
|
||||
rm -rf ~/.claude/commands/enhance-claude-md
|
||||
rm -f ~/.claude/agents/claude-md-guardian.md
|
||||
|
||||
# Windows (PowerShell)
|
||||
Remove-Item -Recurse -Force $env:USERPROFILE\.claude\skills\claudeforge-skill
|
||||
Remove-Item -Recurse -Force $env:USERPROFILE\.claude\commands\enhance-claude-md
|
||||
Remove-Item -Force $env:USERPROFILE\.claude\agents\claude-md-guardian.md
|
||||
```
|
||||
|
||||
### Project-Level Uninstall
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
rm -rf ./.claude/skills/claudeforge-skill
|
||||
rm -rf ./.claude/commands/enhance-claude-md
|
||||
rm -f ./.claude/agents/claude-md-guardian.md
|
||||
rm -rf ./.claude/hooks # If quality hooks were installed
|
||||
|
||||
# Windows (PowerShell)
|
||||
Remove-Item -Recurse -Force .\.claude\skills\claudeforge-skill
|
||||
Remove-Item -Recurse -Force .\.claude\commands\enhance-claude-md
|
||||
Remove-Item -Force .\.claude\agents\claude-md-guardian.md
|
||||
Remove-Item -Recurse -Force .\.claude\hooks
|
||||
```
|
||||
|
||||
After uninstalling, restart Claude Code.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After successful installation:
|
||||
|
||||
1. **Read Quick Start Guide:** [QUICK_START.md](QUICK_START.md)
|
||||
2. **Test the command:** Run `/enhance-claude-md` in a project
|
||||
3. **Review Architecture:** [ARCHITECTURE.md](ARCHITECTURE.md)
|
||||
4. **Explore Examples:** Check `examples/` directory
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter installation issues not covered here:
|
||||
|
||||
- **GitHub Issues:** https://github.com/alirezarezvani/ClaudeForge/issues
|
||||
- **Troubleshooting Guide:** [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||
- **Discussions:** https://github.com/alirezarezvani/ClaudeForge/discussions
|
||||
|
||||
---
|
||||
|
||||
**Installation successful?** Proceed to [Quick Start Guide](QUICK_START.md) →
|
||||
@@ -0,0 +1,407 @@
|
||||
# Quick Start Guide
|
||||
|
||||
Get started with ClaudeForge in 5 minutes. This guide walks you through your first CLAUDE.md creation.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 5-Minute Tutorial
|
||||
|
||||
### Step 1: Install ClaudeForge (1 minute)
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash
|
||||
|
||||
# Windows (PowerShell)
|
||||
iwr https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.ps1 -useb | iex
|
||||
```
|
||||
|
||||
**Choose:** Option 1 (user-level) for global availability
|
||||
|
||||
**Restart Claude Code** after installation
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Navigate to Your Project (30 seconds)
|
||||
|
||||
```bash
|
||||
cd /path/to/your/project
|
||||
```
|
||||
|
||||
**Requirements:**
|
||||
- Any code project (doesn't need to be git-initialized, but recommended)
|
||||
- Works with TypeScript, Python, Go, Java, Ruby, and more
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Run the Command (10 seconds)
|
||||
|
||||
In Claude Code, type:
|
||||
|
||||
```bash
|
||||
/enhance-claude-md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Interactive Workflow (3 minutes)
|
||||
|
||||
ClaudeForge will now:
|
||||
|
||||
#### Phase 1: Discovery ✓
|
||||
|
||||
Claude explores your project:
|
||||
```
|
||||
Checking for existing CLAUDE.md... Not found
|
||||
Exploring repository structure...
|
||||
Analyzing package.json, requirements.txt, etc...
|
||||
```
|
||||
|
||||
#### Phase 2: Analysis ✓
|
||||
|
||||
Claude shows discoveries:
|
||||
```
|
||||
Based on my exploration, here's what I discovered:
|
||||
|
||||
📦 Project Type: Full-Stack Application
|
||||
🛠️ Tech Stack: TypeScript, React, Node.js, PostgreSQL, Docker
|
||||
👥 Team Size: Small (5 developers detected from git history)
|
||||
🚀 Development Phase: MVP
|
||||
⚙️ Workflows: TDD, CI/CD
|
||||
|
||||
📋 Recommended Structure:
|
||||
- Root CLAUDE.md (navigation hub, ~100 lines)
|
||||
- backend/CLAUDE.md (API guidelines, ~150 lines)
|
||||
- frontend/CLAUDE.md (React guidelines, ~175 lines)
|
||||
```
|
||||
|
||||
#### Phase 3: Confirmation ✓
|
||||
|
||||
Claude asks for your approval:
|
||||
```
|
||||
Would you like me to create these files with these settings?
|
||||
```
|
||||
|
||||
**You respond:** `Yes` or `Yes, proceed`
|
||||
|
||||
#### Phase 4: Generation ✓
|
||||
|
||||
Claude creates your CLAUDE.md files:
|
||||
```
|
||||
Creating customized CLAUDE.md files...
|
||||
|
||||
✅ Created CLAUDE.md (108 lines)
|
||||
- Quick Navigation section
|
||||
- 5 Core Principles
|
||||
- Tech Stack summary
|
||||
- Common commands
|
||||
|
||||
✅ Created backend/CLAUDE.md (156 lines)
|
||||
- API design guidelines
|
||||
- Database operations
|
||||
- Testing requirements
|
||||
|
||||
✅ Created frontend/CLAUDE.md (182 lines)
|
||||
- Component standards
|
||||
- State management
|
||||
- Performance tips
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Review Your CLAUDE.md (1 minute)
|
||||
|
||||
Open the generated file:
|
||||
|
||||
```bash
|
||||
cat CLAUDE.md
|
||||
```
|
||||
|
||||
**You'll see:**
|
||||
- **Overview** - Project description
|
||||
- **Project Structure** - ASCII tree diagram
|
||||
- **Setup & Installation** - How to get started
|
||||
- **Architecture** - Key patterns and decisions
|
||||
- **Core Principles** - Development guidelines
|
||||
- **Tech Stack** - Technologies used
|
||||
- **Common Commands** - Build, test, lint
|
||||
- **Development Workflow** - How to contribute
|
||||
|
||||
All in **100% native Claude Code format**!
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What Just Happened?
|
||||
|
||||
1. **Explored** your codebase automatically
|
||||
2. **Detected** project type, tech stack, team size
|
||||
3. **Generated** customized CLAUDE.md with:
|
||||
- Native format compliance
|
||||
- Tech-specific best practices
|
||||
- Team-appropriate complexity
|
||||
4. **Created** modular files (if needed)
|
||||
|
||||
**Result:** Future Claude Code sessions now have perfect context about your project!
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Common Workflows
|
||||
|
||||
### Scenario A: New Project
|
||||
|
||||
```bash
|
||||
# You: Create a new project
|
||||
mkdir my-new-app && cd my-new-app
|
||||
npm init -y
|
||||
|
||||
# You: Run ClaudeForge
|
||||
/enhance-claude-md
|
||||
|
||||
# Claude: Explores → Analyzes → Creates CLAUDE.md
|
||||
```
|
||||
|
||||
**Time:** ~2 minutes
|
||||
|
||||
---
|
||||
|
||||
### Scenario B: Existing Project (No CLAUDE.md)
|
||||
|
||||
```bash
|
||||
# You: Navigate to existing project
|
||||
cd my-existing-project
|
||||
|
||||
# You: Run ClaudeForge
|
||||
/enhance-claude-md
|
||||
|
||||
# Claude: Explores → Detects tech → Creates CLAUDE.md
|
||||
```
|
||||
|
||||
**Time:** ~3 minutes
|
||||
|
||||
---
|
||||
|
||||
### Scenario C: Improve Existing CLAUDE.md
|
||||
|
||||
```bash
|
||||
# You: Have basic CLAUDE.md
|
||||
cat CLAUDE.md
|
||||
# Output: Basic file with just tech stack
|
||||
|
||||
# You: Run ClaudeForge
|
||||
/enhance-claude-md
|
||||
|
||||
# Claude: Analyzes current file
|
||||
# Shows: Quality Score: 55/100
|
||||
# Missing: Project Structure, Setup, Architecture
|
||||
# Claude: Adds missing sections
|
||||
|
||||
# Result: Quality Score: 55 → 88
|
||||
```
|
||||
|
||||
**Time:** ~2 minutes
|
||||
|
||||
---
|
||||
|
||||
### Scenario D: Automatic Maintenance
|
||||
|
||||
```bash
|
||||
# You: Make significant changes
|
||||
npm install react-query
|
||||
mkdir src/components/auth
|
||||
|
||||
# You: Start new Claude Code session
|
||||
# Guardian agent automatically checks changes
|
||||
|
||||
# Agent output:
|
||||
# ✅ CLAUDE.md updated:
|
||||
# - Tech Stack: Added react-query
|
||||
# - Project Structure: Updated diagram
|
||||
# Changes: 2 sections, 8 lines
|
||||
```
|
||||
|
||||
**Time:** Automatic, ~10 seconds
|
||||
|
||||
---
|
||||
|
||||
## 📚 Next Steps
|
||||
|
||||
### Learn More
|
||||
|
||||
- **Architecture:** [ARCHITECTURE.md](ARCHITECTURE.md) - How components work together
|
||||
- **Examples:** [../examples/](../examples/) - Real-world usage patterns
|
||||
- **Troubleshooting:** [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues
|
||||
|
||||
### Customize Your CLAUDE.md
|
||||
|
||||
After generation, you can:
|
||||
|
||||
1. **Edit Core Principles** - Add team-specific guidelines
|
||||
2. **Add Custom Sections** - Project-specific conventions
|
||||
3. **Update Tech Stack** - Add missing dependencies
|
||||
4. **Refine Workflows** - Adjust to your process
|
||||
|
||||
### Enable Automatic Maintenance
|
||||
|
||||
Set up the guardian agent to keep CLAUDE.md current:
|
||||
|
||||
```bash
|
||||
# Agent runs automatically at session start
|
||||
# Or invoke manually after major changes:
|
||||
Claude, invoke claude-md-guardian to update CLAUDE.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
### Tip 1: Use Modular Architecture for Large Projects
|
||||
|
||||
If your CLAUDE.md exceeds 300 lines, split it:
|
||||
|
||||
```bash
|
||||
/enhance-claude-md
|
||||
|
||||
# Tell Claude: "Use modular architecture"
|
||||
# Result: Separate files for backend/, frontend/, database/
|
||||
```
|
||||
|
||||
### Tip 2: Regenerate When Tech Stack Changes
|
||||
|
||||
```bash
|
||||
# You: Added new major framework
|
||||
npm install @nestjs/core
|
||||
|
||||
# You: Regenerate with new context
|
||||
/enhance-claude-md
|
||||
|
||||
# Claude: Updates Tech Stack and patterns
|
||||
```
|
||||
|
||||
### Tip 3: Validate Before Committing
|
||||
|
||||
```bash
|
||||
# You: Made manual edits to CLAUDE.md
|
||||
# You: Want to check quality
|
||||
|
||||
/enhance-claude-md
|
||||
|
||||
# Claude: Analyzes and shows quality score
|
||||
# If score < 80, Claude suggests improvements
|
||||
```
|
||||
|
||||
### Tip 4: Team Consistency
|
||||
|
||||
Install at user-level on all team machines:
|
||||
|
||||
```bash
|
||||
# Each team member runs:
|
||||
curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash
|
||||
|
||||
# Choose option 1 (user-level)
|
||||
# Result: Consistent CLAUDE.md standards across team
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Understanding the Output
|
||||
|
||||
### What's in a Generated CLAUDE.md?
|
||||
|
||||
**Native Format Sections (Always Included):**
|
||||
1. **Overview** - What this project does
|
||||
2. **Project Structure** - ASCII tree diagram
|
||||
3. **File Structure** - Directory explanations
|
||||
4. **Setup & Installation** - Getting started steps
|
||||
5. **Architecture** - Key design decisions (for complex projects)
|
||||
|
||||
**Team-Specific Sections:**
|
||||
6. **Core Principles** - Development guidelines
|
||||
7. **Tech Stack** - Technologies with versions
|
||||
8. **Development Workflow** - How to contribute
|
||||
9. **Testing Requirements** - Test standards
|
||||
10. **Common Commands** - Build, test, lint scripts
|
||||
|
||||
**Optional Sections (Based on Project Type):**
|
||||
- **Error Handling** - Error patterns
|
||||
- **Performance Guidelines** - Optimization tips
|
||||
- **Security Checklist** - Security requirements
|
||||
- **Deployment Process** - How to deploy
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Quick Reference
|
||||
|
||||
### Commands
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/enhance-claude-md` | Initialize or enhance CLAUDE.md |
|
||||
| `Claude, invoke claude-md-guardian` | Manually trigger maintenance |
|
||||
|
||||
### Quality Scores
|
||||
|
||||
| Score | Meaning | Action |
|
||||
|-------|---------|--------|
|
||||
| 0-40 | Poor | Major improvements needed |
|
||||
| 41-70 | Fair | Add missing sections |
|
||||
| 71-85 | Good | Minor improvements |
|
||||
| 86-100 | Excellent | Maintain current quality |
|
||||
|
||||
### File Size Guidelines
|
||||
|
||||
| Team Size | Recommended Lines | Structure |
|
||||
|-----------|-------------------|-----------|
|
||||
| Solo | 50-100 | Single file |
|
||||
| Small (2-9) | 100-200 | Single file |
|
||||
| Medium (10-50) | 200-300 | Single or modular |
|
||||
| Large (50+) | Modular | Multiple context files |
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Having Issues?
|
||||
|
||||
### Issue: Command not recognized
|
||||
|
||||
**Solution:** Restart Claude Code after installation
|
||||
|
||||
### Issue: Quality score too low
|
||||
|
||||
**Solution:** Run `/enhance-claude-md` and let Claude add missing sections
|
||||
|
||||
### Issue: Generated file too generic
|
||||
|
||||
**Solution:** Provide more context:
|
||||
```
|
||||
/enhance-claude-md
|
||||
|
||||
"This is a Python FastAPI microservice project with PostgreSQL"
|
||||
```
|
||||
|
||||
### More Help
|
||||
|
||||
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions.
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Success!
|
||||
|
||||
You now have a fully functional CLAUDE.md file that:
|
||||
- ✅ Follows native Claude Code format
|
||||
- ✅ Includes project-specific context
|
||||
- ✅ Provides clear development guidelines
|
||||
- ✅ Automatically maintains itself (via guardian agent)
|
||||
|
||||
**Future Claude Code sessions will be significantly more productive!**
|
||||
|
||||
---
|
||||
|
||||
## 📖 Further Reading
|
||||
|
||||
- **Installation Guide:** [INSTALLATION.md](INSTALLATION.md)
|
||||
- **Architecture Deep Dive:** [ARCHITECTURE.md](ARCHITECTURE.md)
|
||||
- **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- **GitHub Repository:** https://github.com/alirezarezvani/ClaudeForge
|
||||
|
||||
---
|
||||
|
||||
**Ready to create amazing projects with ClaudeForge? Let's build! 🚀**
|
||||
@@ -0,0 +1,551 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
Common issues and solutions for ClaudeForge.
|
||||
|
||||
---
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### Issue: Command not recognized after installation
|
||||
|
||||
**Symptoms:**
|
||||
- `/enhance-claude-md` shows "command not found"
|
||||
- Slash command doesn't autocomplete
|
||||
|
||||
**Causes:**
|
||||
- Claude Code hasn't reloaded components
|
||||
- Incorrect installation path
|
||||
- Insufficient permissions
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Restart Claude Code completely:**
|
||||
```bash
|
||||
# Quit Claude Code entirely (not just close window)
|
||||
# Reopen Claude Code
|
||||
# Wait 5-10 seconds for components to load
|
||||
```
|
||||
|
||||
2. **Verify installation paths:**
|
||||
```bash
|
||||
# macOS/Linux
|
||||
ls -la ~/.claude/commands/enhance-claude-md/
|
||||
ls -la ~/.claude/skills/claudeforge-skill/
|
||||
ls -la ~/.claude/agents/claude-md-guardian.md
|
||||
|
||||
# Windows
|
||||
dir %USERPROFILE%\.claude\commands\enhance-claude-md\
|
||||
dir %USERPROFILE%\.claude\skills\claudeforge-skill\
|
||||
dir %USERPROFILE%\.claude\agents\claude-md-guardian.md
|
||||
```
|
||||
|
||||
3. **Reinstall with correct permissions:**
|
||||
```bash
|
||||
chmod +x install.sh # macOS/Linux
|
||||
./install.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: "Skill not found" error
|
||||
|
||||
**Symptoms:**
|
||||
- Error message: "claude-md-enhancer skill not found"
|
||||
- Slash command runs but fails
|
||||
|
||||
**Cause:** Skill directory name mismatch or missing skill files
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check skill directory name (must be exact):**
|
||||
```bash
|
||||
ls ~/.claude/skills/
|
||||
# Must show: claudeforge-skill
|
||||
```
|
||||
|
||||
2. **Verify skill files exist:**
|
||||
```bash
|
||||
ls ~/.claude/skills/claudeforge-skill/
|
||||
# Must contain: SKILL.md, analyzer.py, generator.py, etc.
|
||||
```
|
||||
|
||||
3. **Reinstall skill only:**
|
||||
```bash
|
||||
rm -rf ~/.claude/skills/claudeforge-skill
|
||||
cp -r skill ~/.claude/skills/claudeforge-skill
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: Windows PowerShell execution policy error
|
||||
|
||||
**Symptoms:**
|
||||
- Error: "execution of scripts is disabled on this system"
|
||||
|
||||
**Cause:** PowerShell security settings
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Run PowerShell as Administrator
|
||||
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
|
||||
.\install.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Issues
|
||||
|
||||
### Issue: Quality score unexpectedly low
|
||||
|
||||
**Symptoms:**
|
||||
- Quality score < 50
|
||||
- Many "missing section" warnings
|
||||
|
||||
**Causes:**
|
||||
- Basic CLAUDE.md without native format sections
|
||||
- File too short (< 20 lines) or too long (> 400 lines)
|
||||
- Missing required sections
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Let ClaudeForge add missing sections:**
|
||||
```bash
|
||||
/enhance-claude-md
|
||||
# Claude will identify missing sections
|
||||
# Confirm enhancement
|
||||
# Quality score will improve
|
||||
```
|
||||
|
||||
2. **Check file length:**
|
||||
```bash
|
||||
wc -l CLAUDE.md
|
||||
# Recommended: 20-300 lines
|
||||
# If > 300: Consider modular architecture
|
||||
```
|
||||
|
||||
3. **Manually add required sections:**
|
||||
- Core Principles
|
||||
- Tech Stack
|
||||
- Workflow Instructions
|
||||
- Project Structure (ASCII diagram)
|
||||
- Setup & Installation
|
||||
|
||||
---
|
||||
|
||||
### Issue: Generated content too generic
|
||||
|
||||
**Symptoms:**
|
||||
- CLAUDE.md doesn't mention specific tech stack
|
||||
- No project-specific guidelines
|
||||
- Feels like template without customization
|
||||
|
||||
**Causes:**
|
||||
- Project detection failed (no package.json, requirements.txt, etc.)
|
||||
- Insufficient project context
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Provide explicit context:**
|
||||
```bash
|
||||
/enhance-claude-md
|
||||
|
||||
# When Claude asks, specify:
|
||||
"This is a Python FastAPI microservice with PostgreSQL, Redis, and Docker. Team of 8 developers, MVP phase."
|
||||
```
|
||||
|
||||
2. **Add project files before running:**
|
||||
```bash
|
||||
# Ensure detection files exist:
|
||||
touch package.json # Node.js
|
||||
touch requirements.txt # Python
|
||||
touch go.mod # Go
|
||||
touch Cargo.toml # Rust
|
||||
```
|
||||
|
||||
3. **Manual customization after generation:**
|
||||
- Edit generated CLAUDE.md
|
||||
- Add project-specific conventions
|
||||
- Include team standards
|
||||
|
||||
---
|
||||
|
||||
### Issue: Modular architecture not recommended
|
||||
|
||||
**Symptoms:**
|
||||
- Single CLAUDE.md generated for large project
|
||||
- File exceeds 300 lines
|
||||
|
||||
**Causes:**
|
||||
- Project type not detected as `fullstack`
|
||||
- Team size estimated as `small`
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Explicitly request modular:**
|
||||
```bash
|
||||
/enhance-claude-md
|
||||
|
||||
# Tell Claude:
|
||||
"Use modular architecture with separate files for backend, frontend, and database"
|
||||
```
|
||||
|
||||
2. **Create backend/ and frontend/ directories:**
|
||||
```bash
|
||||
mkdir -p backend frontend
|
||||
# Then run /enhance-claude-md
|
||||
```
|
||||
|
||||
3. **Manual split if needed:**
|
||||
```bash
|
||||
# Create context files manually:
|
||||
touch backend/CLAUDE.md
|
||||
touch frontend/CLAUDE.md
|
||||
|
||||
# Then run enhancement on each:
|
||||
cd backend && /enhance-claude-md
|
||||
cd frontend && /enhance-claude-md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: Guardian agent not updating automatically
|
||||
|
||||
**Symptoms:**
|
||||
- Made significant changes
|
||||
- Started new session
|
||||
- CLAUDE.md not updated
|
||||
|
||||
**Causes:**
|
||||
- Agent not installed
|
||||
- Changes below significance threshold
|
||||
- Git repository not initialized
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Verify agent installation:**
|
||||
```bash
|
||||
ls ~/.claude/agents/claude-md-guardian.md
|
||||
```
|
||||
|
||||
2. **Check git repository:**
|
||||
```bash
|
||||
git status
|
||||
# Agent requires git for change detection
|
||||
```
|
||||
|
||||
3. **Manually invoke agent:**
|
||||
```bash
|
||||
# In Claude Code:
|
||||
Claude, invoke claude-md-guardian to update CLAUDE.md
|
||||
```
|
||||
|
||||
4. **Lower significance threshold (if needed):**
|
||||
Edit `agent/claude-md-guardian.md`:
|
||||
```markdown
|
||||
# Change from 5 to 3 files minimum
|
||||
- Less than 5 files modified # Change to 3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Issues
|
||||
|
||||
### Issue: CLAUDE.md missing Project Structure diagram
|
||||
|
||||
**Symptoms:**
|
||||
- No ASCII tree diagram in output
|
||||
- Native format incomplete
|
||||
|
||||
**Cause:** Template generation skipped structure section
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Regenerate with explicit request:**
|
||||
```bash
|
||||
/enhance-claude-md
|
||||
|
||||
# Tell Claude:
|
||||
"Add Project Structure section with ASCII tree diagram"
|
||||
```
|
||||
|
||||
2. **Manual addition:**
|
||||
```markdown
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── src/
|
||||
│ ├── components/
|
||||
│ └── services/
|
||||
└── tests/
|
||||
```
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: Setup & Installation section generic
|
||||
|
||||
**Symptoms:**
|
||||
- Says "npm install" for Python project
|
||||
- Incorrect commands
|
||||
|
||||
**Cause:** Tech stack detection mismatch
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Verify tech stack detection:**
|
||||
```bash
|
||||
# Check project files:
|
||||
ls package.json requirements.txt go.mod
|
||||
```
|
||||
|
||||
2. **Regenerate with correct context:**
|
||||
```bash
|
||||
/enhance-claude-md
|
||||
|
||||
"This is a Python project, not Node.js"
|
||||
```
|
||||
|
||||
3. **Manual fix:**
|
||||
Edit CLAUDE.md and correct commands
|
||||
|
||||
---
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Issue: Guardian agent too slow
|
||||
|
||||
**Symptoms:**
|
||||
- Agent takes > 30 seconds
|
||||
- Multiple updates in single session
|
||||
|
||||
**Causes:**
|
||||
- Model set to sonnet instead of haiku
|
||||
- Full regeneration instead of targeted update
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Verify agent model:**
|
||||
```bash
|
||||
grep "model:" ~/.claude/agents/claude-md-guardian.md
|
||||
# Should be: model: haiku
|
||||
```
|
||||
|
||||
2. **Check agent workflow:**
|
||||
- Should use targeted section updates
|
||||
- Not full file regeneration
|
||||
|
||||
---
|
||||
|
||||
### Issue: Slash command timeout
|
||||
|
||||
**Symptoms:**
|
||||
- Command starts but never completes
|
||||
- "Timeout" error
|
||||
|
||||
**Causes:**
|
||||
- Large repository exploration
|
||||
- Network issues (if fetching remote content)
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Run in smaller scope:**
|
||||
```bash
|
||||
cd specific-directory
|
||||
/enhance-claude-md
|
||||
```
|
||||
|
||||
2. **Skip exploration, provide context directly:**
|
||||
```bash
|
||||
/enhance-claude-md
|
||||
|
||||
"Skip exploration. Create CLAUDE.md for TypeScript React app with PostgreSQL."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration Issues
|
||||
|
||||
### Issue: Git commands fail in agent
|
||||
|
||||
**Symptoms:**
|
||||
- Agent error: "git: command not found"
|
||||
- Agent can't detect changes
|
||||
|
||||
**Cause:** Git not installed or not in PATH
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Install git:**
|
||||
```bash
|
||||
# macOS
|
||||
brew install git
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install git
|
||||
|
||||
# Windows
|
||||
# Download from git-scm.com
|
||||
```
|
||||
|
||||
2. **Verify git installation:**
|
||||
```bash
|
||||
git --version
|
||||
# Should show: git version 2.x
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue: Quality hooks not working
|
||||
|
||||
**Symptoms:**
|
||||
- Pre-commit hook doesn't run
|
||||
- No validation before commit
|
||||
|
||||
**Causes:**
|
||||
- Hook not executable
|
||||
- Git not configured to use hooks
|
||||
- Wrong hooks directory
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Make hook executable:**
|
||||
```bash
|
||||
chmod +x .claude/hooks/pre-commit.sh
|
||||
```
|
||||
|
||||
2. **Configure git:**
|
||||
```bash
|
||||
git config core.hooksPath .claude/hooks
|
||||
```
|
||||
|
||||
3. **Test hook manually:**
|
||||
```bash
|
||||
./.claude/hooks/pre-commit.sh
|
||||
# Should validate CLAUDE.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Errors
|
||||
|
||||
### Issue: "File length exceeds recommended maximum"
|
||||
|
||||
**Symptoms:**
|
||||
- Validation warning: File > 300 lines
|
||||
- Quality score penalty
|
||||
|
||||
**Cause:** Single file too large
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Split into modular architecture:**
|
||||
```bash
|
||||
/enhance-claude-md
|
||||
|
||||
"Convert to modular architecture with separate backend and frontend files"
|
||||
```
|
||||
|
||||
2. **Remove unnecessary content:**
|
||||
- Delete redundant sections
|
||||
- Move detailed examples to separate docs
|
||||
- Link to external documentation
|
||||
|
||||
---
|
||||
|
||||
### Issue: "Missing required sections"
|
||||
|
||||
**Symptoms:**
|
||||
- Validation fails
|
||||
- Lists missing: Core Principles, Tech Stack, etc.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Let ClaudeForge add them:**
|
||||
```bash
|
||||
/enhance-claude-md
|
||||
# Claude will identify and add missing sections
|
||||
```
|
||||
|
||||
2. **Manual addition:**
|
||||
Add required sections following native format
|
||||
|
||||
---
|
||||
|
||||
## Common Error Messages
|
||||
|
||||
### "CLAUDE.md not found"
|
||||
|
||||
**Meaning:** File doesn't exist (expected for new projects)
|
||||
|
||||
**Action:** Continue with initialization workflow
|
||||
|
||||
---
|
||||
|
||||
### "Quality score: 0/100"
|
||||
|
||||
**Meaning:** Empty or invalid file
|
||||
|
||||
**Action:** Regenerate completely
|
||||
|
||||
---
|
||||
|
||||
### "Invalid project structure"
|
||||
|
||||
**Meaning:** Cannot detect project type
|
||||
|
||||
**Action:** Add project files (package.json, etc.) or provide context manually
|
||||
|
||||
---
|
||||
|
||||
### "Template selection failed"
|
||||
|
||||
**Meaning:** No matching template for project
|
||||
|
||||
**Action:** Provide more specific project context
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If your issue isn't covered here:
|
||||
|
||||
1. **Check GitHub Issues:**
|
||||
https://github.com/alirezarezvani/ClaudeForge/issues
|
||||
|
||||
2. **Search Discussions:**
|
||||
https://github.com/alirezarezvani/ClaudeForge/discussions
|
||||
|
||||
3. **Open New Issue:**
|
||||
- Describe the problem
|
||||
- Include steps to reproduce
|
||||
- Attach relevant logs or errors
|
||||
- Mention your OS and Claude Code version
|
||||
|
||||
4. **Review Documentation:**
|
||||
- [INSTALLATION.md](INSTALLATION.md)
|
||||
- [QUICK_START.md](QUICK_START.md)
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md)
|
||||
- [CLAUDE.md](../CLAUDE.md)
|
||||
|
||||
---
|
||||
|
||||
## Debug Mode
|
||||
|
||||
To get more detailed output:
|
||||
|
||||
```bash
|
||||
# Run installer with verbose output:
|
||||
bash -x install.sh
|
||||
|
||||
# Check Claude Code logs:
|
||||
# macOS: ~/Library/Logs/Claude Code/
|
||||
# Linux: ~/.config/claude-code/logs/
|
||||
# Windows: %APPDATA%\Claude Code\logs\
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Still having issues?** We're here to help!
|
||||
|
||||
Open an issue: https://github.com/alirezarezvani/ClaudeForge/issues/new
|
||||
Reference in New Issue
Block a user