context-forge/.claude/docs/command-reference.md

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

# Command Reference Guide

Complete reference for all Context Forge commands, options, and features in v3.2.0.

## Overview

Context Forge provides seven main commands:
- **`init`** - Initialize new projects with AI-optimized configurations
- **`analyze`** - Retrofit existing projects with Context Forge
- **`enhance`** - Plan and implement new features systematically  
- **`migrate`** - Execute technology stack migrations safely
- **`orchestrate`** - Deploy autonomous AI agent teams for 24/7 development
- **`dashboard`** - Monitor progress and track development workflow
- **`validate`** - Verify configurations and run quality checks

## Global Options

All commands support these global options:

```bash
-h, --help          # Show command help
-v, --version       # Show Context Forge version
```

## `context-forge init`

Initialize AI IDE configurations for new projects.

### Usage
```bash
context-forge init [options]
```

### Options
```bash
-o, --output <path>           # Output directory (default: current)
-p, --preset <preset>         # Use preset configuration
-c, --config <path>           # Load configuration from file
-i, --ide <ide>              # Target IDE(s) - comma separated
--no-ai                      # Disable AI-powered suggestions
--quick                      # Quick setup with smart defaults
```

### Supported IDEs
- `claude` - Claude Code (recommended)
- `cursor` - Cursor IDE
- `cline` - Cline VS Code extension
- `roo` - Roo Code
- `windsurf` - Windsurf IDE (coming soon)
- `copilot` - GitHub Copilot (coming soon)
- `gemini` - Google Gemini

### Presets
```bash
--preset nextjs-fastapi      # Next.js + FastAPI full-stack
--preset react-express       # React + Express.js
```

### Examples
```bash
# Basic setup with interactive wizard
context-forge init

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

# Target specific IDEs
context-forge init --ide claude,cursor

# Use preset configuration
context-forge init --preset nextjs-fastapi

# Disable AI features
context-forge init --no-ai

# Custom output directory
context-forge init --output ./my-project
```

### Generated Files
- `CLAUDE.md` - Main project context
- `Docs/` - Project documentation
- `PRPs/` - Implementation guides
- `.claude/` - Commands and hooks (if enabled)

---

## `context-forge analyze`

Retrofit existing projects with Context Forge documentation.

### Usage
```bash
context-forge analyze [options]
```

### Options
```bash
-o, --output <path>           # Output directory (default: current)
-i, --ide <ide>              # Target IDE(s) - comma separated
--no-ai                      # Skip AI analysis
--config-only                # Generate config only, no docs
```

### Examples
```bash
# Analyze existing project
context-forge analyze

# Skip AI analysis (faster)
context-forge analyze --no-ai

# Generate for specific IDEs
context-forge analyze --ide claude,cursor

# Configuration only
context-forge analyze --config-only
```

### Analysis Features
- **Project structure detection**
- **Technology stack identification**
- **Code quality assessment**
- **Documentation gap analysis**
- **AI-powered insights** (when enabled)

---

## `context-forge enhance`

Plan and implement new features for existing projects.

### Usage
```bash
context-forge enhance [options]
```

### Options
```bash
-o, --output <path>           # Output directory (default: current)
-i, --ide <ide>              # Target IDE(s) - comma separated
--analyze-only               # Show plan without generating files
--quick                      # Skip detailed analysis
```

### Features
- **Interactive feature definition**
- **Feasibility analysis**
- **Implementation planning**
- **Phase-based development**
- **Progress tracking**
- **Validation checkpoints**

### Examples
```bash
# Full enhancement workflow
context-forge enhance

# Analysis only (no file generation)
context-forge enhance --analyze-only

# Quick enhancement setup
context-forge enhance --quick
```

### Generated Artifacts
- `ENHANCEMENT_PLAN.md` - Complete strategy
- `PRPs/` - Feature-specific implementation guides
- `.claude/commands/enhancement/` - Progress tracking commands

---

## `context-forge migrate`

Create comprehensive migration plans for technology transitions.

### Usage
```bash
context-forge migrate [options]
```

### Options
```bash
-o, --output <path>           # Output directory (default: current)
-s, --source <stack>          # Source technology stack
-t, --target <stack>          # Target technology stack
-i, --ide <ide>              # Target IDE(s) - comma separated
--analyze-only               # Show complexity without generating files
--quick                      # Skip detailed analysis
```

### Migration Intelligence
- **Framework detection** with confidence scoring
- **Breaking change analysis** (200+ patterns)
- **Dependency compatibility** checking
- **Automated migration suggestions**
- **Risk assessment** and mitigation
- **Phase-based migration plans**

### Examples
```bash
# Full migration analysis and planning
context-forge migrate

# Specify source and target
context-forge migrate --source react --target nextjs

# Analysis only
context-forge migrate --analyze-only
```

### Generated Artifacts
- `MIGRATION_PLAN.md` - Complete migration strategy
- `PRPs/` - Phase-specific implementation guides
- `.claude/commands/migration/` - Migration tracking commands

---

## `context-forge orchestrate`

Deploy autonomous AI agent teams for 24/7 development.

### Usage
```bash
context-forge orchestrate [size] [options]
```

### Arguments
```bash
size                         # Team size: small, medium (default), or large
```

### Options
```bash
-s, --strategy <strategy>    # Deployment: big-bang, phased, or adaptive
-c, --communication <model>  # Communication: hub-and-spoke, hierarchical, or mesh
--no-git                     # Disable git auto-commit
--no-scheduling              # Disable self-scheduling
--commit-interval <minutes>  # Git commit interval (default: 30)
--check-interval <minutes>   # Self-scheduling interval (default: 15)
```

### Team Configurations
- **Small**: 1 Orchestrator, 1 PM, 2 Developers
- **Medium**: 1 Orchestrator, 1 PM, 2 Developers, 1 QA
- **Large**: 1 Orchestrator, 2 PMs, 4 Developers, 2 QA, 1 DevOps, 1 Reviewer

### Key Features
- **Autonomous operation** - Agents work continuously without intervention
- **Git discipline** - Auto-commits every 30 minutes prevent work loss
- **Self-scheduling** - Agents manage their own check-ins and workload
- **Team hierarchy** - Three-tier structure overcomes context limitations

### Prerequisites
- **tmux** installed for session management
- **Git** repository initialized
- **CLAUDE.md** and PRPs for agent context

### Examples
```bash
# Deploy default team
context-forge orchestrate

# Deploy small team
context-forge orchestrate small

# Deploy large team with phased strategy
context-forge orchestrate large --strategy phased

# Custom configuration
context-forge orchestrate --commit-interval 45 --check-interval 20

# Disable auto-features
context-forge orchestrate --no-git --no-scheduling
```

### Monitoring
```bash
# View agent sessions
tmux attach -t cf-projectname

# Check orchestration status
/orchestrate-status              # In Claude

# View agent logs
ls .claude/orchestration/logs/
```

### Generated Artifacts
- `.claude/orchestration/status.json` - Current orchestration status
- `.claude/orchestration/logs/` - Agent conversation logs
- `.claude/orchestration/schedule.sh` - Self-scheduling script
- `.claude/orchestration/auto-commit.sh` - Git auto-commit script

---

## `context-forge dashboard`

Monitor progress and track development workflow.

### Usage
```bash
context-forge dashboard [options]
```

### Options
```bash
-w, --watch                   # Real-time watch mode (updates every 2s)
-h, --history                 # Show full operation history
-s, --summary                 # Show summary statistics only
--clear-old [days]           # Clear operations older than N days (default: 30)
```

### Dashboard Features
- **Current operations** with step-by-step progress
- **Summary statistics** and success rates
- **Recent activity** (last 7 days)
- **Project health status**
- **Error tracking** and recovery
- **Performance metrics**

### Examples
```bash
# View main dashboard
context-forge dashboard

# Real-time monitoring
context-forge dashboard --watch

# Full operation history
context-forge dashboard --history

# Summary statistics only
context-forge dashboard --summary

# Clean up old operations
context-forge dashboard --clear-old 7
```

### Data Storage
Operations are tracked in `.context-forge/progress.json`:
- **Local storage** - never shared externally
- **Project-specific** tracking
- **Rich metadata** - files generated, AI usage, errors
- **Performance metrics** - duration, success rates

---

## `context-forge validate`

Validate configurations and run quality checks.

### Usage
```bash
context-forge validate [options]
```

### Validation Features
- **Configuration file validation**
- **Generated file integrity checks**
- **Project structure verification**
- **Dependency compatibility**
- **Best practice compliance**

---

## Common Workflows

### New Project Setup
```bash
# 1. Initialize with AI assistance
context-forge init --quick

# 2. Monitor progress
context-forge dashboard --watch

# 3. Validate setup
context-forge validate
```

### Existing Project Retrofit
```bash
# 1. Analyze existing project
context-forge analyze

# 2. Plan enhancements
context-forge enhance --analyze-only

# 3. Implement enhancements
context-forge enhance
```

### Technology Migration
```bash
# 1. Analyze migration complexity
context-forge migrate --analyze-only

# 2. Create migration plan
context-forge migrate

# 3. Monitor migration progress
context-forge dashboard --watch
```

### Team Development
```bash
# 1. Check project status
context-forge dashboard --summary

# 2. View recent team activity
context-forge dashboard --history

# 3. Plan new features
context-forge enhance
```

## Environment Variables

### AI Configuration
```bash
# Enable AI features
export ANTHROPIC_API_KEY=your_key_here

# Alternative providers
export CLAUDE_CODE_USE_BEDROCK=true    # Amazon Bedrock
export CLAUDE_CODE_USE_VERTEX=true     # Google Vertex AI

# Disable AI globally
export CONTEXT_FORGE_DISABLE_AI=true
```

### Debugging
```bash
export DEBUG=context-forge*            # Enable debug logging
export CF_LOG_LEVEL=verbose           # Verbose logging
```

## Configuration Files

### Project Configuration
```json
{
  "projectName": "My Project",
  "projectType": "fullstack",
  "targetIDEs": ["claude", "cursor"],
  "techStack": {
    "frontend": "nextjs",
    "backend": "fastapi",
    "database": "postgresql"
  },
  "extras": {
    "testing": true,
    "linting": true,
    "docker": true,
    "cicd": true
  }
}
```

### Preset Files
Located in `~/.context-forge/presets/`:
- `nextjs-fastapi.json`
- `react-express.json`
- `vue-django.json`

## Error Handling

### Intelligent Error Recovery
When commands fail, Context Forge provides:
- **Automated fixes** for common issues
- **Step-by-step recovery** instructions
- **AI-powered suggestions** (when available)
- **Fallback mechanisms** for offline use

### Common Error Categories
- **Permission errors** → Automatic file permission fixes
- **Missing dependencies** → Automated package installation
- **Configuration errors** → Smart config reset and recovery
- **Network errors** → Offline mode suggestions

## Performance Tips

### Faster Operations
```bash
# Use quick mode for faster setup
context-forge init --quick

# Skip AI analysis when not needed
context-forge analyze --no-ai

# Use specific IDE targets
context-forge init --ide claude
```

### Managing Large Projects
```bash
# Clean up old dashboard data
context-forge dashboard --clear-old 7

# Use targeted analysis
context-forge enhance --analyze-only
```

## Troubleshooting

### Common Issues

**"Command not found"**
```bash
npm install -g context-forge
```

**"AI features disabled"**
```bash
export ANTHROPIC_API_KEY=your_key_here
```

**"Permission denied"**
```bash
sudo chown -R $USER:$USER .
context-forge init
```

**"Operation failed"**
```bash
context-forge dashboard              # Check error details
context-forge validate              # Verify configuration
```

### Getting Help
```bash
context-forge --help                # General help
context-forge init --help           # Command-specific help
context-forge dashboard --history   # Check previous operations
```

## Integration Examples

### CI/CD Pipeline
```yaml
# GitHub Actions example
- name: Validate Context Forge setup
  run: |
    context-forge validate
    context-forge dashboard --summary
```

### Development Scripts
```bash
#!/bin/bash
# setup-new-feature.sh
context-forge enhance --analyze-only
context-forge dashboard --watch &
echo "Feature planning started - check dashboard for progress"
```

### Team Onboarding
```bash
# onboard-developer.sh
context-forge analyze
context-forge dashboard --summary
echo "Project analyzed - review CLAUDE.md for context"
```

---

This command reference covers all Context Forge functionality. For detailed workflows and use cases, see the specific guide documents for each command.