npm package: @neoforge/forge-framework
Description: AI-driven development framework - conversational, simple, powerful
Author: Scott Feltham
Latest version: 2.0.0

# 🔨 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.

> **💡 Best Used With**: FORGE is designed for AI-powered development tools like Claude Code, Cursor, Continue, and other AI coding assistants. While it can be used standalone, it shines when paired with AI that understands context and guides you through structured workflows.

[![npm version](https://img.shields.io/npm/v/forge-framework.svg)](https://www.npmjs.com/package/forge-framework)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-website-blue.svg)](https://scottfeltham.github.io/forge-framework/)

## Quick Start

### Option 1: Local Installation (Recommended)
```bash
# 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
```bash
# 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:
```bash
# 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:

| Phase | Purpose | Key Output |
|-------|---------|------------|
| **Focus** 🎯 | Clarity: What & Why | Problem statement, success criteria, C4 L1 |
| **Orchestrate** 📋 | Planning: Break It Down | C4 L2-L3, dependency map, session-sized tasks |
| **Refine** ✏️ | Precision: Define "Done" | Acceptance criteria, interfaces, edge cases |
| **Generate** ⚡ | Creation: TDD Code | RED → GREEN → REFACTOR |
| **Evaluate** ✅ | Verification | Criteria check, security review, disposition |

**Key Rule**: No code in Refine phase - specifications only.

### 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:
```bash
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:

```yaml
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](docs/AGENT_CUSTOMIZATION.md) for details.

### Dynamic Agents
Claude Code can automatically detect when specialized agents are needed and create them on the fly. See [Dynamic Agents Guide](docs/DYNAMIC_AGENTS.md) 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](docs/LEARNING_PROCESS.md) and [Memory Integration](docs/MEMORY_INTEGRATION.md) 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](docs/PHILOSOPHY.md)** - Understand the deeper principles behind our approach.

## Documentation

### Core Concepts
- **[Philosophy](docs/PHILOSOPHY.md)** - Core principles and beliefs
- **[AI-Driven Workflow](docs/AI_DRIVEN_WORKFLOW.md)** - How AI handles all complexity
- **[Conversational PRD Workflow](docs/conversational-prd-workflow.md)** - Interactive requirements gathering
- **[Agent Usage Guide](docs/AGENT_USAGE_GUIDE.md)** - How to work with FORGE agents

### Integration & Usage
- **[Claude Code Integration](docs/CLAUDE_CODE_INTEGRATION.md)** - Using with Claude Code
- **[MCP Integration](docs/MCP_INTEGRATION.md)** - Model Context Protocol support
- **[Existing Project Integration](docs/EXISTING_PROJECT_INTEGRATION.md)** - Add FORGE to existing projects

### Advanced Topics
- **[Agent Customization](docs/AGENT_CUSTOMIZATION.md)** - Creating specialized agents
- **[Dynamic Agents](docs/DYNAMIC_AGENTS.md)** - How agents are created on-the-fly
- **[PRD Guide](docs/PRD_GUIDE.md)** - Product Requirements Documents in Focus phase
- **[Team Collaboration](docs/TEAM_COLLABORATION.md)** - Multi-developer workflows
- **[Learning Process](docs/LEARNING_PROCESS.md)** - Continuous improvement system
- **[Memory Integration](docs/MEMORY_INTEGRATION.md)** - AI memory system support

### Reference
- **[Credits](docs/CREDITS.md)** - Acknowledgments and inspirations

## Example Workflow

1. **Start a feature**
   ```bash
   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](https://github.com/scottfeltham).

## 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](https://github.com/scottfeltham/forge-framework/blob/main/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](docs/CREDITS.md) for detailed acknowledgments.

## Feedback

We're actively seeking feedback to improve FORGE.

- **Report Issues**: [GitHub Issues](https://github.com/scottfeltham/forge-framework/issues)
- **Join Discussions**: [GitHub Discussions](https://github.com/scottfeltham/forge-framework/discussions)
- **Share Examples**: Show us what you build!

## Integration Options

FORGE offers multiple ways to integrate with your development workflow:

| Option | Best For | Setup |
|--------|----------|-------|
| **CLI** (forge-framework) | Quick start, any AI assistant | `npm install -g forge-framework` |
| **Skill** (forge-skill) | Claude Code, natural language | Copy to `~/.claude/skills/` |
| **MCP** (forge-mcp) | Automation, team environments | Configure in Claude settings |

All options implement the same IDD methodology and produce compatible `.forge/` state files.

## Roadmap

### v2.0.0 (Current)
- ✅ Core 5-phase IDD cycle
- ✅ AI agent system with subagents
- ✅ TDD enforcement (RED-GREEN-REFACTOR)
- ✅ Phase validation system
- ✅ Team collaboration
- ✅ Learning system
- ✅ Aligned with Intent-Driven Development book
- ✅ Version alignment across all FORGE implementations

### v2.1.0 (Planned)
- Enhanced MCP integration
- Agent marketplace
- Performance metrics
- Extended templates

### v3.0.0 (Future)
- Stable API
- Plugin system
- Enterprise features
- Full documentation site

## License

[MIT License](LICENSE) - Use freely in your projects!