context-forge/.claude/docs/ai-integration.md

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

# AI Integration Guide

Context Forge v3.2.0 introduces optional AI-powered features that enhance your development workflow with intelligent suggestions and automated optimizations.

## Overview

AI integration in Context Forge provides:
- **Smart project analysis** with contextual suggestions
- **Intelligent error recovery** with automated fixes
- **Enhanced setup wizard** with AI-powered recommendations
- **Fallback mechanisms** ensuring full functionality without AI

## Setup & Configuration

### API Key Configuration

Context Forge supports multiple AI providers:

1. **Anthropic Claude** (Recommended)
   ```bash
   export ANTHROPIC_API_KEY=your_key_here
   ```

2. **Amazon Bedrock**
   ```bash
   export CLAUDE_CODE_USE_BEDROCK=true
   # Configure AWS credentials separately
   ```

3. **Google Vertex AI**
   ```bash
   export CLAUDE_CODE_USE_VERTEX=true
   # Configure GCP credentials separately
   ```

### Disabling AI Features

If you prefer to work without AI enhancements:

```bash
# Disable globally
export CONTEXT_FORGE_DISABLE_AI=true

# Or use command flags
context-forge init --no-ai
context-forge analyze --no-ai
```

## AI-Enhanced Features

### 1. Smart Project Analysis

When running any command, AI analyzes your project structure and provides intelligent suggestions:

```bash
context-forge init
# AI detects: React + TypeScript project
# Suggests: Testing framework, linting rules, deployment strategy
```

**What AI Analyzes:**
- Project structure and file patterns
- Package.json dependencies
- Code patterns and architecture
- Missing tools or configurations

### 2. Intelligent Setup Wizard

The interactive setup wizard uses AI to:
- Pre-populate smart defaults based on project analysis
- Suggest appropriate technology stacks
- Recommend best practices for your project type
- Provide contextual hints during configuration

```bash
context-forge init
# 🤖 AI detected the following about your project:
#    • React project with TypeScript - optimized config recommended
#    • Testing setup missing - Jest + Testing Library suggested
```

### 3. Error Recovery System

When commands fail, AI provides intelligent recovery suggestions:

```bash
# Command fails with permission error
# 🔧 AI suggestions:
#   1. Fix file permissions (automated)
#   2. Check directory ownership
#   3. Verify project access rights
```

**Recovery Capabilities:**
- **Automated fixes**: Permission errors, missing directories, dependency installation
- **Manual guidance**: Step-by-step instructions for complex issues
- **Contextual suggestions**: Solutions specific to your project and error

### 4. Enhanced Prompts

AI enriches interactive prompts with:
- **Smart validation**: Real-time feedback on input quality
- **Contextual suggestions**: Options tailored to your project
- **Best practice recommendations**: Industry-standard configurations

## AI Features by Command

### `context-forge init`

**AI Enhancements:**
- Project structure analysis
- Technology stack recommendations  
- Smart default generation
- Configuration optimization

**Usage:**
```bash
# Full AI enhancement
context-forge init

# Quick setup with AI defaults
context-forge init --quick

# Disable AI suggestions
context-forge init --no-ai
```

### `context-forge analyze`

**AI Enhancements:**
- Deep code analysis
- Architecture recommendations
- Quality improvements
- Performance optimizations

**Usage:**
```bash
# AI-powered analysis (requires confirmation)
context-forge analyze

# Skip AI analysis
context-forge analyze --no-ai
```

### `context-forge enhance`

**AI Enhancements:**
- Feature feasibility analysis
- Implementation strategy recommendations
- Risk assessment
- Complexity estimation

### `context-forge migrate`

**AI Enhancements:**
- Migration path analysis
- Breaking change detection
- Automated migration suggestions
- Risk mitigation strategies

## AI Confidence & Quality

### Confidence Scoring

AI suggestions include confidence scores (0-100%):
- **90-100%**: High confidence recommendations
- **70-89%**: Good suggestions worth considering
- **50-69%**: Moderate confidence, validate carefully
- **<50%**: Low confidence, use with caution

### Quality Indicators

Visual feedback helps you understand AI suggestion quality:
- 🟢 **High quality**: Based on strong patterns and best practices
- 🟡 **Good quality**: Reasonable suggestions, some validation needed
- 🔴 **Uncertain**: AI lacks confidence, manual review recommended

## Fallback Mechanisms

Context Forge maintains full functionality without AI:

### Pattern-Based Analysis
When AI is unavailable, Context Forge uses:
- File extension detection
- Package.json analysis
- Common project patterns
- Framework-specific heuristics

### Manual Configuration
All AI-suggested configurations can be:
- Manually customized
- Overridden with presets
- Configured through interactive prompts
- Loaded from configuration files

## Privacy & Security

### Data Handling
- **Local Analysis**: Project analysis happens locally first
- **Selective Sharing**: Only necessary context sent to AI providers
- **No Secrets**: API keys and sensitive data never shared
- **Opt-in Only**: AI features require explicit activation

### What's Shared
When AI is enabled, Context Forge may share:
- Project structure (file names, directories)
- Package.json contents (dependencies, scripts)
- Error messages and context
- Technology stack information

### What's Never Shared
- Source code contents
- API keys or secrets
- Personal or proprietary information
- Internal project details

## Performance Considerations

### AI Response Times
- **Fast operations**: Project analysis (1-3 seconds)
- **Medium operations**: Error analysis (2-5 seconds)
- **Complex operations**: Migration analysis (5-15 seconds)

### Optimization Tips
1. **Use caching**: AI results are cached for faster subsequent operations
2. **Quick mode**: Use `--quick` flags for faster setup
3. **Selective enablement**: Enable AI only when needed
4. **Fallback ready**: Always have manual workflows as backup

## Troubleshooting

### Common Issues

**AI Not Working**
```bash
# Check API key
echo $ANTHROPIC_API_KEY

# Verify AI status
context-forge init # Shows AI status at startup
```

**Slow AI Responses**
```bash
# Use quick mode
context-forge init --quick

# Skip AI analysis
context-forge analyze --no-ai
```

**Unexpected Suggestions**
- AI suggestions are recommendations, not requirements
- Always validate suggestions against your project needs
- Use manual configuration when AI suggestions don't fit

### Error Messages

**"AI features disabled - no API key found"**
- Solution: Set appropriate environment variables for your AI provider

**"AI analysis failed, using fallback"**
- This is normal - Context Forge continues with pattern-based analysis
- No action needed, functionality remains intact

**"Rate limit exceeded"**
- Wait and retry, or disable AI temporarily
- Consider using fallback mechanisms for immediate needs

## Best Practices

### When to Use AI
- ✅ New project setup and configuration
- ✅ Technology stack selection
- ✅ Error diagnosis and recovery
- ✅ Architecture recommendations

### When to Skip AI
- ❌ Highly specialized or niche projects
- ❌ Projects with strict security requirements
- ❌ When you need deterministic, repeatable setups
- ❌ Offline development environments

### Workflow Integration
1. **Start with AI**: Let AI analyze and suggest
2. **Validate suggestions**: Review recommendations carefully
3. **Customize as needed**: Modify suggestions to fit your needs
4. **Document decisions**: Note why you accepted/rejected suggestions

## Future Enhancements

Planned AI improvements include:
- **Learning from feedback**: AI suggestions improve based on usage
- **Project-specific models**: Customized recommendations for your tech stack
- **Advanced error recovery**: More sophisticated automated fixes
- **Performance optimization**: AI-driven performance analysis and improvements

---

*AI features are optional and designed to enhance, not replace, your development expertise. Always validate AI suggestions against your project requirements and security policies.*