FORGE

Full Orchestration for Rapid Git Engineering

A multi-agent development framework for Claude Code Agent Teams that forges production-quality code through parallel specialization, adversarial verification, and bulletproof context engineering.

Features

• 🏗️ Event-Sourced State Engine — Append-only event log with single-writer merge
• 🤖 Multi-Agent Coordination — Contract-first protocol for parallel execution
• 📝 Template-Based Artifacts — Generate CLAUDE.md, REQUIREMENTS.md, ROADMAP.md
• 🌳 Git Worktree Isolation — Parallel task execution without conflicts
• ⚡ Slash Commands — Use /forge:plan, /forge:execute directly in Claude Code
• 🎯 5-6 Task Limit — Enforced atomic task breakdown for optimal LLM performance

Installation

Global Installation (Recommended)

# Install globally via npm
npm install -g forge-dev-framework

# Commands are automatically installed to ~/.claude/commands/forge/
# Available from any project in Claude Code

Per-Project Installation

# Install in a specific project
cd /path/to/your/project
npm install forge-dev-framework

# Commands installed to project .claude/commands/forge/
# Available only in this project

Development Installation

# Clone the repository
git clone https://github.com/Alzarak/forge.git
cd forge

# Install dependencies
npm install

# Build the project
npm run build

# Install commands (global mode)
node dist/scripts/install.js --mode=global

# Or install to current project (project mode)
node dist/scripts/install.js --mode=project

Quick Start

Using Slash Commands (Recommended)

After installation, FORGE commands are available directly in Claude Code:

# Start a new FORGE project
/forge:new-project my-app

# Plan a phase
/forge:discuss M2-planning-engine
/forge:plan M2-planning-engine

# Execute with agent teams
/forge:execute M2-planning-engine

# Check progress
/forge:status

Using CLI

# Initialize FORGE in current directory
forge init

# Show project status
forge status

# Generate artifacts
forge generate requirements
forge generate roadmap

# View configuration
forge config

Available Commands

| Command | Description | Milestone | |---------|-------------|-----------| | /forge:new-project | Initialize a new FORGE project | M1 ✅ | | /forge:init | Initialize FORGE in current directory | M1 ✅ | | /forge:status | Show project progress | M1 ✅ | | /forge:config | View/edit configuration | M1 ✅ | | /forge:discuss | Capture phase context | M2 🚧 | | /forge:plan | Generate task breakdown | M2 🚧 | | /forge:verify | Verify plan against requirements | M2 🚧 | | /forge:execute | Execute phase with agent teams | M3 📋 | | /forge:generate | Generate artifacts from templates | M1 ✅ | | /forge:help | Show command reference | M1 ✅ |

Legend: ✅ Complete | 🚧 In Progress | 📋 Planned

Architecture

Event-Sourced State

FORGE uses an append-only event log with single-writer state derivation:

All Agents → state/events/*.json (append-only)
                        ↓
              State Steward (single writer)
                        ↓
                  state/STATE.json (canonical)

Contract-First Protocol

Cross-domain work requires published contracts first:

1. Agent needs interface from another domain
2. Write REQUEST_CONTRACT event
3. Provider publishes contract to contracts/
4. Both agents work against agreed contract
5. Integration happens at merge time

File Ownership Boundaries

Each teammate writes only within their owned paths:

| Role | Owned Paths | |---|---| | ARCHITECT | Root artifacts, .claude/rules/, STATE.json (single-writer) | | STATE-ENGINE | STATE.schema.json, event schemas, merge logic | | CLI-ENGINE | src/cli/, src/commands/, bin/ | | TEMPLATES | src/templates/, src/generators/ | | GIT-OPS | src/git/, .github/ |

Wipe Protocol

Agent context is ephemeral, git is persistent:

1. Hydrate — Agent reads CLAUDE.md + STATE.json + task + contracts
2. Execute — Agent writes code, runs tests
3. Commit — Atomic git commit (one task = one commit)
4. Terminate — Session ends, context wiped
5. Reincarnate — Next task starts with fresh context

Configuration

FORGE configuration is stored in .planning/forge.config.json:

{
  "mode": "interactive",
  "depth": "standard",
  "maxTeammates": 5,
  "taskLimit": 6,
  "conventionalCommits": true,
  "worktreeIsolation": true
}

Available Settings

| Key | Type | Default | Description | |-----|------|---------|-------------| | mode | enum | interactive | yolo, interactive, standard | | depth | enum | standard | quick, standard, comprehensive | | maxTeammates | int | 5 | Max agents per phase (2-10) | | taskLimit | int | 6 | Max tasks per phase (5-6 recommended) | | conventionalCommits | bool | true | Enforce commit format | | worktreeIsolation | bool | true | Use worktrees for tasks |

Development

Setup

# Clone repository
git clone https://github.com/Alzarak/forge.git
cd forge

# Install dependencies
npm install

# Build project
npm run build

Scripts

npm run build          # Build TypeScript to dist/
npm run dev            # Run CLI in development mode
npm test              # Run tests
npm run test:watch     # Run tests in watch mode
npm run test:coverage  # Run tests with coverage

Project Structure

forge/
├── .claude/
│   ├── commands/          # Slash command definitions
│   └── rules/            # Scoped rules (api-patterns, etc.)
├── src/
│   ├── cli/              # CLI entry point
│   ├── commands/         # Command implementations
│   ├── generators/        # Template engine & XML generator
│   ├── git/              # Git operations (worktrees, hooks)
│   ├── types/            # TypeScript type definitions
│   ├── utils/            # Utilities (logger, state-api, etc.)
│   └── scripts/          # Installation scripts
├── templates/            # Artifact templates
├── bin/                 # Executable entry point
├── state/              # State engine (events, STATE.json)
└── contracts/          # API contracts

Contributing

Contributions are welcome! Please read CLAUDE.md for project patterns and conventions.

Development Workflow

1. Make changes following FORGE patterns
2. Run tests: npm test
3. Build: npm run build
4. Commit: type(scope): description
5. Push: PR review required

License

MIT © Alzarak

Links

• Documentation: CLAUDE.md
• Requirements: REQUIREMENTS.md
• Roadmap: ROADMAP.md
• Issues: GitHub Issues

Built with ❤️ by the FORGE Agent Team