CLI tool for instant Claude Code project scaffolding with context engineering best practices

Transform your project ideas into AI-ready applications with intelligent context engineering

🎯 Optimized for Claude Code with deep integration for slash commands, hooks, and PRPs
Also supports Cursor, Windsurf, Cline, Copilot, Gemini, and more AI coding assistants

Features • Quick Start • Documentation • Credits

# 1. Set up your AI provider (one-time setup)
context-forge ai-keys --provider openai
# OR
context-forge ai-keys --provider anthropic

# 2. Initialize project with AI-powered PRPs
context-forge init --ai-prp

# Your API keys are securely encrypted and stored in ~/.context-forge-keys

🤖 Generating AI PRP for: User Authentication & Authorization...
✅ AI content generated for: User Authentication & Authorization
📝 Generated: PRPs/feature-auth-prp.md

🤖 Generating AI PRP for: Google Drive Cloud Streaming...
✅ AI content generated for: Google Drive Cloud Streaming
📝 Generated: PRPs/feature-google-drive-cloud-streaming-prp.md

# TODO: Add implementation details
# TODO: Add data models based on requirements

### AI-Generated Implementation Strategy
Leverage Google Drive API for file organization, streaming, and redundancy. 
Use Google's Picker API for intelligent folder structure management. 
Implement JWT for access control.

### ⚠️ AI-Identified Gotchas
- Make sure to have proper error handling for API failures
- Ensure you're not exceeding Google Drive API's rate limits
- Be careful with user's OAuth tokens

### ✅ AI-Recommended Best Practices
- Encrypt OAuth tokens
- Use Google's recommended best practices for Drive API
- Always validate files before streaming

context-forge init
# Select "Enable Dart task integration? Yes"

# Generate project with hooks
context-forge init  # Select "Enable Claude Code hooks? Yes"

# Or copy hooks from another project
context-forge copy-hooks --source ../claude-hooks-repo/hooks

# Hooks are created in:
# .claude/hooks/

🛑 CHECKPOINT: Human Verification Required

Analytics Dashboard - I've completed database schema setup:

✅ What I've Accomplished:
- Created PostgreSQL schema with 5 tables
- Set up foreign key relationships
- Added indexes for query optimization

🧪 Please Test:
1. Run: npm run db:migrate
2. Check tables exist: psql -c "\dt"
3. Verify foreign keys: psql -c "\d+ users"

📋 Critical Verification Points:
- [ ] All tables created successfully
- [ ] Foreign keys properly linked
- [ ] No data loss from existing tables

Please respond:
- ✅ "Approved" - Continue to next task
- ❌ "Issues: [description]" - Fix before proceeding

# .context-forge/checkpoints.yaml
checkpoints:
  - name: "Database Migration"
    phase: "infrastructure"
    requires_approval: true
    validation_steps:
      - "Run migration scripts"
      - "Verify data integrity"
      - "Check rollback procedures"

npm install -g context-forge

# Initialize a new project
context-forge init

# Initialize with AI-powered PRPs (optional)
context-forge init --ai-prp

# Set up AI provider keys (optional)
context-forge ai-keys

# Or use npx without installation
npx context-forge init

# Initialize in current directory
context-forge init

# Specify output directory
context-forge init --output ./my-project

# Use with existing PRD file
context-forge init --prd ./requirements.md

# Skip interactive prompts with config
context-forge init --config ./context-forge.json

# Run validation on existing project
context-forge validate

# Retrofit existing projects with AI-optimized documentation
context-forge analyze

# Execute PRPs with Claude Code for one-pass implementation
context-forge run-prp feature-name

# NEW: Plan technology migration
context-forge migrate --target "Next.js"

# NEW: Copy Claude Code hooks from another project
context-forge copy-hooks --source ../claude-hooks-repo/hooks

# NEW: Set up AI provider keys for enhanced PRP generation
context-forge ai-keys --provider openai
context-forge ai-keys --provider anthropic

$ context-forge init

? Project name: Analytics Dashboard
? Project type: fullstack
? Project description: Real-time analytics dashboard with data visualization
? How would you like to provide the PRD? Create new PRD
? Frontend framework: nextjs
? Backend framework: fastapi
? Database: postgresql
? Select features: authentication, dashboard, realtime-updates, data-export
? Project timeline: standard
? Team size: small
? Enable PRP generation? Yes
? Enable AI-powered PRP generation? Yes
? Enable validation system? Yes
? Enable Human-in-the-Loop checkpoints? Yes
? Enable Claude Code hooks? Yes

✅ Project initialized successfully!

Generated files:
- CLAUDE.md (Next.js 15 specific configuration)
- Docs/Implementation.md (4 development stages)
- Docs/project_structure.md
- PRPs/base.md (Implementation prompt with validation gates)
- .claude/commands/ (20+ slash commands)
- .claude/hooks/ (4 Claude Code hooks)
- .context-forge/config.json

Next steps:
1. cd analytics-dashboard
2. Set up AI keys (optional): context-forge ai-keys
3. Review CLAUDE.md for project rules
4. Use /prime-context to load project knowledge and activate architect mode
5. Start with Stage 1 in Docs/Implementation.md

$ context-forge init --output user-service

? Project name: User Service
? Project type: api
? Project description: User management microservice with JWT auth
? Frontend framework: none
? Backend framework: express
? Database: mongodb
? Authentication method: jwt
? Enable Docker support? Yes
? Enable GitHub Actions? Yes

Generated structure:
user-service/
├── CLAUDE.md              # Express.js specific rules
├── Docs/
├── PRPs/
├── Dockerfile
├── docker-compose.yml
└── .github/workflows/

$ context-forge init --output nuxt-dashboard

? Project name: Analytics Dashboard  
? Project type: fullstack
? Project description: Modern analytics dashboard with real-time data
? Frontend framework: nuxt4  # NEW: Nuxt 4 option
? Styling framework: tailwind
? State management: pinia
? Backend framework: fastapi
? Database: postgresql
? Authentication method: jwt
? Enable AI-powered PRP generation? Yes

Generated structure:
nuxt-dashboard/
├── CLAUDE.md              # Nuxt 4 + Vue 3 specific rules
├── Docs/
├── PRPs/
│   ├── nuxt-dashboard-prp.md
│   └── feature-auth-prp.md  # AI-enhanced for Nuxt 4
└── .claude/commands/       # 25+ slash commands

✨ Nuxt 4 Features Included:
- New app/ directory structure documented
- Vue 3 Composition API guidelines  
- TypeScript integration with auto-imports
- SSR and data fetching best practices
- Pinia state management setup

# context-forge.json
{
  "projectName": "E-Commerce Platform",
  "projectType": "fullstack",
  "description": "Modern e-commerce platform with AI recommendations",
  "prd": {
    "content": "# E-Commerce Platform\n\n## Overview\n...",
    "features": [
      {
        "id": "auth",
        "name": "User Authentication",
        "priority": "must-have",
        "complexity": "medium"
      },
      {
        "id": "catalog",
        "name": "Product Catalog",
        "priority": "must-have",
        "complexity": "complex"
      },
      {
        "id": "cart",
        "name": "Shopping Cart",
        "priority": "must-have",
        "complexity": "medium"
      },
      {
        "id": "ai-recommendations",
        "name": "AI Product Recommendations",
        "priority": "should-have",
        "complexity": "complex"
      }
    ]
  },
  "techStack": {
    "frontend": "react",
    "backend": "django",
    "database": "postgresql",
    "cache": "redis",
    "search": "elasticsearch"
  },
  "extras": {
    "prp": true,
    "validation": true,
    "docker": true,
    "cicd": true,
    "testing": true
  }
}

# Run with config
$ context-forge init --config context-forge.json --output ecommerce-platform

# 1. Initialize with MVP timeline
context-forge init --preset startup-mvp

# 2. Review generated Implementation.md
cat Docs/Implementation.md
# Shows 2-week sprint plan with daily tasks

# 3. Start development with Claude Code
# Open CLAUDE.md in Claude Code
# Follow Stage 1 tasks systematically

# 4. Validate progress daily
context-forge validate --levels syntax,tests

# 1. Create detailed PRD first
context-forge init --prd legacy-migration-prd.md

# 2. Select enterprise options
# - Choose 'enterprise' timeline
# - Enable all validation options
# - Select comprehensive testing

# 3. Generated structure includes:
# - Migration strategy in Implementation.md
# - Rollback procedures
# - Comprehensive test suites
# - Security audit checklists

# 1. Quick setup
npx context-forge init --preset hackathon

# 2. Skip optional features
# - Disable PRP (too detailed for hackathon)
# - Basic validation only
# - Focus on core features

# 3. Get building in < 5 minutes
# CLAUDE.md has simplified rules for rapid development

# Run in your existing project directory
cd /path/to/your/project
context-forge analyze

# Specify output directory
context-forge analyze --output ./ai-docs

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

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

📁 Generated Files:
   ├── CLAUDE.md (UPDATED - appended retrofit section)
   ├── Docs/
   │   ├── Implementation.md
   │   ├── project_structure.md
   │   ├── UI_UX_doc.md
   │   └── Bug_tracking.md
   └── PRPs/
       ├── user-authentication-prp.md
       ├── payment-integration-prp.md
       └── api-v2-prp.md

# Interactive migration planning
context-forge migrate

# Specify target technology
context-forge migrate --target "Next.js"

# Quick mode (skip detailed analysis)
context-forge migrate --quick --target "FastAPI"

# Analyze only (no file generation)
context-forge migrate --analyze-only

🔄 Migration Analysis Complete!

Source: Flask + Jinja2 + SQLAlchemy
Target: Next.js + FastAPI + Prisma
Complexity: HIGH (Score: 78/100)
Recommended Strategy: parallel-run

📁 Generated Migration Files:
   ├── CLAUDE.md (Migration-aware configuration)
   ├── PRPs/
   │   ├── migration-overview.md
   │   ├── phase-1-infrastructure.md
   │   ├── phase-2-api-migration.md
   │   ├── phase-3-frontend-migration.md
   │   └── rollback-procedures.md
   └── .claude/
       ├── commands/migration/
       │   ├── migration-status.md
       │   ├── migration-checkpoint.md
       │   └── migration-rollback.md
       └── hooks/
           ├── MigrationCheckpoint.py
           └── DataIntegrityCheck.py

project-folder/
├── CLAUDE.md                    # Main context file with tech-stack specific rules
├── Docs/
│   ├── Implementation.md        # Staged development plan
│   ├── project_structure.md     # Folder organization
│   ├── UI_UX_doc.md            # Design specifications
│   └── Bug_tracking.md         # Bug tracking template
├── PRPs/                       # Product Requirement Prompts (if enabled)
│   ├── {project}-prp.md        # Base implementation PRP
│   ├── {project}-planning.md   # Architecture planning (if enterprise/team)
│   └── {feature}-prp.md        # Feature-specific PRPs (if retrofit)
├── .claude/                    # Claude Code specific configuration
│   ├── commands/               # Slash commands (20+ commands)
│   │   ├── PRPs/              # PRP management commands
│   │   ├── development/       # Development workflow commands
│   │   ├── checkpoints/       # Human-in-the-loop commands
│   │   └── migration/         # Migration commands (if applicable)
│   └── hooks/                 # Claude Code hooks (if enabled)
│       ├── PreCompact.py      # Context preservation hook
│       ├── ContextRotation.py # Smart file switching
│       ├── PreSubmit.py       # Quality gates
│       ├── PRPTracking.py     # Progress monitoring
│       ├── DartProgressUpdater.py # Dart task progress tracking
│       ├── AutoTaskCommenter.py   # Automated task documentation
│       └── TaskCodeMapper.py      # File-to-task mapping
└── ai_docs/                   # AI documentation curation (if enabled)
    └── README.md              # Documentation guide

project-folder/
├── .cursorrules               # Main Cursor rules file
└── .cursor/
    └── rules/
        ├── global.md         # Global development rules
        ├── project.md        # Project-specific rules
        ├── prp-overview.mdc  # PRP implementation overview
        ├── prp-stage-1.mdc   # Foundation setup tasks
        ├── prp-stage-2.mdc   # Core feature implementation
        ├── prp-stage-3.mdc   # Advanced features & polish
        └── prp-validation.mdc # Validation gates & checks

project-folder/
└── .clinerules/              # Configuration directory
    ├── README.md            # Main configuration
    ├── context.md           # Project context
    ├── rules.md             # Development rules
    ├── patterns.md          # Code patterns
    ├── prp-overview.md      # PRP implementation overview
    ├── prp-stage-1.md       # Foundation setup tasks
    ├── prp-stage-2.md       # Core feature implementation
    ├── prp-stage-3.md       # Advanced features & polish
    └── prp-validation.md    # Validation gates & checks

project-folder/
├── GEMINI.md                 # Main Gemini configuration
└── .gemini/
    ├── context/
    │   ├── project.md       # Project context
    │   ├── architecture.md  # Architecture docs
    │   └── guidelines.md    # Development guidelines
    ├── prp/                 # PRP files (if features defined)
    │   ├── overview.md      # PRP implementation overview
    │   ├── stage-1-foundation.md
    │   ├── stage-2-core.md
    │   ├── stage-3-advanced.md
    │   └── validation.md
    └── config.yaml          # Gemini config with PRP settings

# Run all critical validations
context-forge validate

# Run specific validation levels
context-forge validate --levels syntax,tests

# Run all validations including optional ones
context-forge validate --all

# Generate detailed report
context-forge validate --report

# Validate in specific directory
context-forge validate --path ./my-project

📊 Validation Report - Analytics Dashboard
==================================================
✅ Status: PASSED

Total: 5 | Passed: 5 | Failed: 0

✅ syntax:tsc --noEmit (342ms)
✅ syntax:eslint src --ext .ts,.tsx (567ms)
✅ tests:jest --coverage (4521ms)
✅ build:next build (8234ms)
✅ security:npm audit (1023ms)

Full report saved to: .validation-reports/latest-report.md

{
  "projectName": "My App",
  "projectType": "fullstack",
  "description": "A collaborative platform",
  "techStack": {
    "frontend": "nextjs",
    "backend": "fastapi",
    "database": "postgresql",
    "auth": "jwt"
  },
  "features": [
    {
      "id": "auth",
      "name": "Authentication",
      "priority": "must-have"
    }
  ],
  "extras": {
    "prp": true,
    "validation": true,
    "docker": true
  }
}

# Run the init command
context-forge init

# Answer the interactive prompts
# Context Forge will analyze your requirements and generate appropriate documentation

# 1. Start with CLAUDE.md
cat CLAUDE.md
# This is your project's "constitution" - rules Claude Code will follow

# 2. Check your implementation plan
cat Docs/Implementation.md
# This breaks down development into manageable stages

# 3. Review project structure
cat Docs/project_structure.md
# This defines how your code should be organized

# After completing each stage
context-forge validate

# Before committing code
context-forge validate --levels syntax,tests

# For comprehensive check
context-forge validate --all --report

# Custom tech stack template
~/.context-forge/templates/claude/my-stack.md

# Custom validation commands
~/.context-forge/templates/validation/my-validation.json

# pre-init.sh - Run before initialization
#!/bin/bash
echo "Setting up environment..."

# post-init.sh - Run after initialization
#!/bin/bash
echo "Installing dependencies..."
npm install

# .github/workflows/validate.yml
name: Context Forge Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install -g context-forge
      - run: context-forge validate --all

# Clone the repository
git clone https://github.com/webdevtodayjason/context-forge.git
cd context-forge

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run linting
npm run lint

context-forge/
├── src/
│   ├── cli/              # CLI entry point and commands
│   ├── commands/         # Command implementations
│   ├── generators/       # Document generators
│   ├── templates/        # Handlebars templates
│   ├── data/            # Tech stack configurations
│   └── types/           # TypeScript definitions
├── templates/           # Document templates
└── tests/              # Test files

Made with ❤️ by the Context Forge community

Empowering developers to build smarter, not harder