context-forge/.claude/docs/retrofit.md

AI orchestration platform with autonomous teams, enhancement planning, migration tools, 25+ slash commands, checkpoints & hooks. Multi-IDE: Claude, Cursor, Windsurf, Cline, Copilot

# Retrofit Guide - Context Forge

## What is Retrofit?

The retrofit feature (via the `analyze` command) allows you to add AI-optimized documentation and configuration to existing projects. It's designed to seamlessly integrate Context Forge into established codebases without disrupting your current workflow.

## When to Use Retrofit

Use the `analyze` command when you have:
- An existing project that needs AI documentation
- A legacy codebase you want to modernize with AI assistance
- A project you're inheriting and need to understand
- A codebase that lacks proper documentation

## Step-by-Step Workflow

### 1. Initial Analysis

```bash
# Basic analysis
context-forge analyze

# With specific output directory
context-forge analyze -o ./ai-docs

# Target specific IDEs
context-forge analyze -i claude,cursor
```

### 2. What Gets Analyzed

The analyzer examines:
- **Project Structure**: Directory layout, file organization
- **Tech Stack**: Frameworks, libraries, dependencies
- **Code Patterns**: Architecture, design patterns
- **Quality Metrics**: Complexity, test coverage
- **Documentation**: Existing docs, comments, READMEs

### 3. Interactive Configuration

During analysis, you'll be asked about:
1. **Project Confirmation**
   - Verify detected tech stack
   - Confirm project type
   - Set project name and description

2. **Documentation Preferences**
   - Choose documentation depth
   - Select target AI IDEs
   - Enable advanced features

3. **Integration Options**
   - Slash commands (Claude Code)
   - Hooks and automation
   - Checkpoint system

### 4. Generated Outputs

#### Standard Files
```
your-project/
├── CLAUDE.md              # Main context file
├── PRPs/                  # Implementation guides
│   └── retrofit/         # Retrofit-specific PRPs
└── .gitignore            # Updated with AI files
```

#### Claude Code Specific
```
.claude/
├── commands/             # Custom slash commands
│   ├── run-tests.md
│   ├── check-lint.md
│   └── project-status.md
├── hooks/               # Automation scripts
│   ├── pre-commit.py
│   └── post-test.py
└── docs/               # Extended documentation
```

## Common Retrofit Patterns

### 1. Minimal Integration
For projects that just need basic AI context:
```bash
context-forge analyze --quick
```

### 2. Full Integration
For comprehensive AI assistance:
```bash
context-forge analyze --deep
```

### 3. Incremental Adoption
Start small and expand:
```bash
# Phase 1: Basic documentation
context-forge analyze --quick

# Phase 2: Add PRPs
context-forge analyze --prp

# Phase 3: Enable automation
context-forge analyze --hooks --checkpoints
```

## Handling Special Cases

### 1. Monorepos
```bash
# Analyze from monorepo root
cd my-monorepo
context-forge analyze

# Or analyze specific package
cd packages/api
context-forge analyze --scope package
```

### 2. Legacy Codebases
```bash
# Use legacy mode for older projects
context-forge analyze --legacy

# This enables:
# - Broader framework detection
# - Legacy pattern recognition
# - Compatibility documentation
```

### 3. Mixed Tech Stacks
```bash
# Explicitly specify primary stack
context-forge analyze --primary-stack react

# For full-stack projects
context-forge analyze --full-stack
```

## Advanced Usage

### 1. Custom Analysis Depth
```bash
# Shallow analysis (faster)
context-forge analyze --depth shallow

# Deep analysis (comprehensive)
context-forge analyze --depth deep

# With AI-powered insights
context-forge analyze --ai-insights
```

### 2. Excluding Paths
```bash
# Exclude specific directories
context-forge analyze --exclude node_modules,dist,build

# Use .cfignore file
echo "*.test.js" >> .cfignore
context-forge analyze
```

### 3. Framework-Specific Options
```bash
# React projects
context-forge analyze --framework react --detect-patterns hooks,context

# Node.js APIs
context-forge analyze --framework express --detect-patterns middleware,routes
```

## Integration with Existing Tools

### 1. Preserving Existing Documentation
Context Forge appends to existing files rather than overwriting:
- Existing CLAUDE.md files are backed up
- READMEs are preserved
- Comments in code remain untouched

### 2. Git Integration
```bash
# See what will be added
context-forge analyze --dry-run

# Commit AI documentation separately
git add .claude CLAUDE.md PRPs/
git commit -m "Add AI development context"
```

### 3. CI/CD Compatibility
Add to your CI pipeline:
```yaml
# .github/workflows/ai-docs.yml
- name: Update AI Documentation
  run: |
    npx context-forge analyze --ci
    git add .
    git commit -m "Update AI context" || true
```

## Best Practices

### 1. Initial Setup
- Run analysis on a clean working directory
- Review detected tech stack carefully
- Enable all Claude Code features if using Claude

### 2. Maintenance
- Re-run analysis after major changes
- Update PRPs when adding features
- Keep slash commands synchronized

### 3. Team Adoption
- Share generated docs with team
- Document custom patterns in ai_docs/
- Create team-specific PRPs

## Example: Retrofitting a React App

```bash
# 1. Navigate to your React project
cd my-react-app

# 2. Run comprehensive analysis
context-forge analyze -i claude --deep

# 3. During prompts:
# - Confirm React + TypeScript stack
# - Enable hooks, commands, checkpoints
# - Select comprehensive documentation

# 4. Review generated files
cat CLAUDE.md
ls -la .claude/commands/
ls -la PRPs/

# 5. Test with Claude Code
# Open project in Claude Code
# Try: /project-status
# Try: /run-tests
```

## Troubleshooting

### Detection Issues
```bash
# Force framework detection
context-forge analyze --force-detect

# Specify frameworks manually
context-forge analyze --frameworks react,typescript,jest
```

### Performance
```bash
# For large codebases
context-forge analyze --parallel

# Limit file scanning
context-forge analyze --max-files 1000
```

### Integration Problems
```bash
# Check compatibility
context-forge analyze --check-only

# Generate report
context-forge analyze --report-only
```

## Next Steps

After retrofitting your project:

1. **Test AI Integration**
   - Open in your AI IDE
   - Test slash commands
   - Verify context understanding

2. **Enhance Documentation**
   - Add project-specific PRPs
   - Document unique patterns
   - Create custom commands

3. **Plan Improvements**
   - Use `enhance` for new features
   - Consider `migrate` for tech updates
   - Keep context current with regular analysis