🔨 FORGE Framework

A conversational AI-driven development framework that puts AI at the center of software development. A concise CLI under 200 lines that unlocks unlimited potential through natural dialogue.

Quick Start

Option 1: Local Installation (Recommended)

# Install FORGE directly in your project
npx forge-framework install

# Use the local forge command
./forge init
./forge new "user authentication"

Option 2: Global Installation

# Install globally (automatically configures Claude permissions)
npm install -g forge-framework

# Use from anywhere
forge init
forge new "user authentication"

Auto-Configuration: Global installation automatically sets up Claude Code permissions and specialized subagents for enhanced development capabilities.

After running forge init, ask Claude to:

• "Analyze my project and update forge.yaml"
• "Create CLAUDE.md for this project"
• "Detect frameworks and configure FORGE"

The AI handles all the complex detection and configuration!

Slash Commands (Claude Code)

When using Claude Code, you can use explicit slash commands:

• /forge init - Initialize FORGE
• /forge new <feature> - Start new cycle
• /forge status - Check status
• /forge complete - Complete cycle
• /forge learn - Access learnings
• /forge help - Get help

Both slash commands and natural language work equally well!

Claude Code Integration

FORGE automatically configures specialized Claude Code subagents during installation:

Available Subagents

• forge-architect - System architecture design and planning
• forge-developer - Code implementation and feature development
• forge-tester - Testing strategies and quality assurance
• forge-devops - Infrastructure and deployment automation
• forge-reviewer - Code review and quality assessment
• forge-analyzer - Codebase analysis and insights

Usage

Claude Code automatically delegates tasks to appropriate subagents based on context, or you can explicitly request:

"Use the forge-architect to design the authentication system"
"Have the forge-tester create test scenarios for the payment flow"

The subagents operate in separate contexts, preventing context pollution and enabling specialized expertise.

Team Mode

For collaborative development:

# Use team configuration
cp forge-team.yaml forge.yaml

# Multiple developers can work in parallel
forge new "payment system"    # Creates .forge/current/payment-system.md
forge new "user profile"      # Creates .forge/current/user-profile.md

# Check all active cycles
forge status                  # Shows all active features

# Complete specific cycle
forge complete payment-system.md

How It Works

FORGE guides development through 5 validated phases:

1. Focus - Understand and architect (with mandatory test scenarios)
2. Orchestrate - Plan and organize
3. Refine - Build and test
4. Generate - Deploy and deliver
5. Evaluate - Measure and improve

Phase Validation System

FORGE now enforces proper workflow progression:

• Mandatory Tasks: Critical items must be completed before phase transitions
• Visual Progress: See completion status with progress bars
• Smart Validation: Can't complete cycles with unfinished phases
• Override Options: Use --force flags when needed

Example workflow:

forge status              # See visual progress bars
forge phase status        # Detailed view with mandatory items
forge phase next          # Move to next phase (validates completion)
forge complete            # Only works when all phases are done

AI-First Design

Unlike traditional frameworks, FORGE is designed to be interpreted by AI:

• Simple markdown files for state
• Natural language configuration
• Flexible prompt templates
• No complex type systems

Usage with Claude

User: Let's add shopping cart functionality

Claude: I'll guide us through FORGE. Starting Focus phase...
[Reads .forge/current.md and agents/architect.md]

Based on the requirements, here's my architectural analysis...

Why Local Installation?

With local installation (npx forge-framework install):

• Visible Templates & Agents - Customize them for your project
• Version Control - Commit your customized agents with your code
• No Global Dependencies - Works even without npm global installs
• Project-Specific - Each project can have its own FORGE setup

File Structure

your-project/
├── forge              # Local FORGE command
├── forge.yaml         # Simple configuration
├── .forge/            # FORGE directory
│   ├── templates/     # Customizable templates
│   ├── agents/        # Your AI agents
│   ├── current.md     # Active cycle
│   └── history/       # Completed cycles

Commands

Core Commands

• forge init - Initialize FORGE in current directory
• forge new <feature> - Start a new development cycle
• forge status - Show current cycle progress (with visual progress bars)
• forge complete - Archive completed cycle (validates phase completion)
• forge learn - View and manage project learnings
• forge document - AI-powered documentation management

Phase Management (NEW)

• forge phase status - Detailed phase progress with mandatory items
• forge phase next - Move to next phase (with validation)
• forge phase complete - Mark current phase as complete

Command Options

• forge status --detailed - Show full cycle content
• forge complete --force - Skip phase validation
• forge phase next --force - Skip mandatory item validation

Configuration

Edit forge.yaml to customize:

project: your-app-name
description: Your project description

mode: conversational  # or structured

ai:
  primary: claude
  model: sonnet      # or opus for complex tasks

Agent Roles

FORGE includes 5 base AI agents that serve as templates for specialization:

Base Agents

• Architect - System design and planning → Can specialize as Solution/Security/Data Architect
• Developer - Code implementation → Can specialize as Frontend/Backend/Mobile/Data Engineer
• Tester - Quality assurance → Can specialize as QA/Performance/Security/Accessibility Tester
• DevOps - Infrastructure and deployment → Can specialize as Cloud/Platform/SRE Engineer
• Reviewer - Code and design review → Can specialize by focus area

Customization

Create specialized agents for your project's specific needs by extending the base templates. Examples included for common specializations. See Agent Customization Guide for details.

Dynamic Agents

Claude Code can automatically detect when specialized agents are needed and create them on the fly. See Dynamic Agents Guide for how this works.

Learning System

FORGE includes a continuous learning system that captures and applies knowledge:

• Automatic Learning - Agents consult and update .forge/LEARNINGS.md
• Retrospectives - Structured reflection after each cycle
• Pattern Library - Document and reuse successful solutions
• Team Knowledge - Share insights across developers
• Memory Integration - Leverages AI memory for cross-session learning

See Learning Process and Memory Integration for details.

Why This Approach?

• Minimal & Concise - Under 200 lines of focused code
• No compilation - Instant changes
• AI-native - Built for LLMs to understand
• Language agnostic - Works with any tech stack
• Flexible - Adapt to your workflow

Philosophy

FORGE embodies the principle that development frameworks should amplify human creativity, not constrain it. Our core beliefs:

• AI handles complexity, humans handle creativity - Let AI manage the tedious parts while developers focus on solving problems
• Structure enables freedom - Just enough organization to be productive, not so much that it becomes a burden
• Transparency builds trust - Everything visible in plain text, no hidden state or magic
• Conversation is the interface - Natural language is the most powerful API
• Progress over perfection - Ship working software, iterate based on real feedback

The framework provides minimal scaffolding - just enough to maintain best practices while letting AI intelligence and human intuition drive the development process.

📖 Read the full FORGE Philosophy - Understand the deeper principles behind our approach.

Documentation

• Philosophy - Core principles and beliefs
• AI-Driven Workflow - How AI handles all complexity
• Agent Customization - Creating specialized agents
• Dynamic Agents - How agents are created on-the-fly
• Claude Code Integration - Using with Claude Code
• Existing Project Integration - Add FORGE to existing projects
• PRD Guide - Product Requirements Documents in Focus phase
• Team Collaboration - Multi-developer workflows
• Learning Process - Continuous improvement system
• Memory Integration - AI memory system support
• MCP Integration - Model Context Protocol support
• Credits - Acknowledgments and inspirations

Example Workflow

1. Start a feature

   forge new "payment integration"

2. Focus Phase (with Claude)

   Claude: I'll act as the Architect Agent. Let me analyze the requirements...
      
   Based on the payment integration needs:
   - We'll need Stripe API integration
   - Secure webhook handling
   - Database schema for transactions

3. Orchestrate Phase

   Claude: Now I'll plan the tasks:
   1. Set up Stripe SDK
   2. Create payment endpoints
   3. Implement webhook handler
   4. Add transaction logging

4. Continue through remaining phases...

Templates

FORGE includes several templates to help structure your work:

• cycle.md - Main development cycle template (used by forge new)
• feature.md - Detailed feature specification template
• task.md - Individual task breakdown template

You can use these templates manually or let AI agents reference them during conversation.

Author

FORGE Framework was created by Scott Feltham.

Contributing

FORGE is designed to be simple enough that anyone can contribute. Edit the markdown templates or add new agent prompts to extend functionality.

See CONTRIBUTING.md for guidelines.

Credits

FORGE Framework was created by Scott Feltham, inspired by Modern Software Engineering principles, the BMAD Method, and Agent-OS architecture. See Credits for detailed acknowledgments.

Feedback

We're actively seeking feedback to improve FORGE.

• Report Issues: GitHub Issues
• Join Discussions: GitHub Discussions
• Share Examples: Show us what you build!

Roadmap

v0.6.0 (Current)

• ✅ Core 5-phase cycle
• ✅ AI agent system
• ✅ TDD enforcement
• ✅ Documentation management
• ✅ Team collaboration
• ✅ Learning system

v0.2.0 (Planned)

• Enhanced MCP integration
• Agent marketplace
• Performance metrics
• Extended templates

v1.0.0 (Future)

• Stable API
• Plugin system
• Enterprise features
• Full documentation site

License

MIT License - Use freely in your projects!