Architecture Overview

November 12, 2025 · View on GitHub

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:

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:

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:

Length Validation
- Recommended: 20-300 lines
- Warning: 300-400 lines (suggest modular)
- Error: < 20 or > 400 lines
Structure Validation
- Required sections: Core Principles, Tech Stack, Workflow
- Recommended sections: Testing, Error Handling
- Heading hierarchy: H1 → H2 → H3 (no skips)
Formatting Validation
- Balanced code blocks (open/close)
- Valid markdown syntax
- No broken links
Completeness Validation
- Has code examples
- Lists tech stack with versions
- Includes setup instructions
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:

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:

Root File (Navigation Hub)
- Quick Navigation section
- Core Principles (high-level)
- Tech Stack summary
- Links to context files
Context File (Specific Area)
- Detailed guidelines for backend/, frontend/, etc.
- Tech-specific patterns
- Common commands for that area
Section Generation (Individual)
- Generate single section
- Merge with existing content

Native Format Template:

# 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

Principle one
Principle two

Tech Stack

React 18
TypeScript 5
Node.js 20

Common Commands

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 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:

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

Update workflow.py → _detect_project_type()
Add detection patterns
Update template_selector.py → selection matrix
Create new template in skill/examples/

Adding New Tech Stacks

Update workflow.py → _detect_tech_stack()
Add file detection (e.g., Cargo.toml for Rust)
Update generator.py → tech-specific sections

Adding New Validation Rules

Update validator.py → validate_all()
Add new validation method
Return validation result in standard format

Testing Strategy

Manual Testing

See QUICK_START.md for test scenarios.

Integration Testing

Test entire flow:

Install components
Run slash command
Verify output quality
Test guardian agent
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

Implementation Details: CLAUDE.md
Installation: INSTALLATION.md
Quick Start: QUICK_START.md
Troubleshooting: TROUBLESHOOTING.md

Questions about architecture? Open an issue: https://github.com/alirezarezvani/ClaudeForge/issues