context-forge/.claude/docs/basic-usage.md

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

# Basic Usage - Context Forge

**Updated for v3.2.0 - UX Enhancement Phase**

## Overview

Context Forge is a powerful CLI tool that helps you create AI-optimized documentation and configuration for your software projects. Version 3.2.0 introduces optional AI intelligence, enhanced user experience, comprehensive progress tracking, and intelligent error recovery.

## Installation

```bash
npm install -g context-forge
```

## Core Concepts

### 1. Project Types
- **New Projects**: Use `init` to bootstrap a new project with AI-ready documentation
- **Existing Projects**: Use `analyze` to add AI context to existing codebases
- **Migrations**: Use `migrate` to plan technology stack transitions
- **Enhancements**: Use `enhance` to add new features to existing projects

### 2. Multi-IDE Support
Context Forge generates configurations for multiple AI IDEs:
- Claude Code (primary focus with advanced features)
- Cursor
- WindSurf
- Cline
- Roo
- Gemini (upcoming)
- GitHub Copilot

## General Workflow

### For New Projects

```bash
# Initialize with enhanced setup wizard
context-forge init

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

# Setup without AI features
context-forge init --no-ai

# Follow the enhanced interactive prompts:
# 📋 Step 1: Project Information (with AI suggestions)
# 📱 Step 2: IDE Selection (with recommendations)
# 📝 Step 3: Product Requirements
# 🛠️ Step 4: Technology Stack (with smart detection)
# ⭐ Step 5: Feature Selection
# ⚙️ Step 6: Configuration
# ✅ Step 7: Validation & Generation
```

### For Existing Projects

```bash
# Analyze with AI-powered insights
context-forge analyze

# Skip AI analysis for faster processing
context-forge analyze --no-ai

# Plan new features for existing projects
context-forge enhance

# Create migration plans
context-forge migrate

# This will:
# 1. Scan your codebase
# 2. Detect frameworks and patterns
# 3. Generate AI-optimized documentation
# 4. Create IDE configurations
```

## Common Options

### Output Directory
```bash
context-forge init -o ./docs
context-forge analyze --output ./ai-docs
```

### IDE Selection
```bash
# Single IDE
context-forge init -i claude

# Multiple IDEs
context-forge init -i claude,cursor,windsurf
```

### Quick Mode
```bash
# Skip detailed prompts, use defaults
context-forge init --quick
context-forge enhance --quick
```

## Key Features

### 1. Project Requirement Prompts (PRPs)
PRPs are detailed specifications that guide AI assistants through implementation tasks:
- Base PRPs for general features
- Planning PRPs for architecture decisions
- Spec PRPs for detailed implementations

### 2. Slash Commands (Claude Code)
Custom commands for project-specific actions:
- `/project-status` - Check project progress
- `/run-tests` - Execute test suite
- `/deploy` - Run deployment scripts

### 3. Hooks (Claude Code)
Automated scripts that run at key points:
- Pre-commit validation
- Post-implementation testing
- Progress tracking

### 4. Checkpoints
Milestone validation points that ensure quality:
- Architecture reviews
- Security checks
- Performance benchmarks

## Best Practices

### 1. Start with Analysis
Always analyze your project first to understand:
- Current tech stack
- Code patterns
- Project structure

### 2. Use Appropriate Commands
- `init` - New projects from scratch
- `analyze` - Document existing projects
- `migrate` - Plan technology transitions
- `enhance` - Add new features systematically

### 3. Enable Advanced Features
For Claude Code users, always enable:
```bash
# During setup, select:
- ✓ Slash Commands
- ✓ Hooks
- ✓ Checkpoints
- ✓ AI Docs
```

### 4. Keep Documentation Updated
- Run `analyze` periodically to update docs
- Use `enhance` for new features instead of manual additions
- Version control your `.claude` directory

## File Structure

After running Context Forge, you'll have:

```
your-project/
├── .claude/                 # Claude Code specific files
│   ├── commands/           # Slash commands
│   ├── hooks/             # Automation scripts
│   └── docs/              # Extended documentation
├── CLAUDE.md               # Main AI context file
├── PRPs/                   # Project Requirement Prompts
│   ├── base/              # General implementation guides
│   ├── planning/          # Architecture plans
│   └── spec/              # Detailed specifications
└── ai_docs/               # Additional documentation
```

## Troubleshooting

### Command Not Found
```bash
# Ensure global installation
npm install -g context-forge

# Or use npx
npx context-forge init
```

### Permission Errors
```bash
# Use sudo for global install (if needed)
sudo npm install -g context-forge
```

### Build Errors
```bash
# Clone and build from source
git clone https://github.com/semmieboy/context-forge.git
cd context-forge
npm install
npm run build
npm link
```

## Next Steps

1. Explore command-specific guides:
   - [Retrofit Guide](./retrofit.md) - For existing projects
   - [Enhance Guide](./enhance.md) - For adding features
   - [Migrate Guide](./migrate.md) - For technology transitions
   - [Analyze Guide](./analyze.md) - For deep analysis

2. Learn about advanced features:
   - Custom slash commands
   - Hook automation
   - Checkpoint systems

3. Join the community:
   - Report issues on GitHub
   - Share your PRPs and templates
   - Contribute to the project