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

[![npm version](https://badge.fury.io/js/forge-dev-framework.svg)](https://www.npmjs.com/package/forge-dev-framework)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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)

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

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

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

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

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

```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

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

# Install dependencies
npm install

# Build project
npm run build
```

### Scripts

```bash
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](./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](https://github.com/Alzarak)

## Links

- **Documentation**: [CLAUDE.md](./CLAUDE.md)
- **Requirements**: [REQUIREMENTS.md](./REQUIREMENTS.md)
- **Roadmap**: [ROADMAP.md](./ROADMAP.md)
- **Issues**: [GitHub Issues](https://github.com/Alzarak/forge/issues)

---

**Built with ❤️ by the FORGE Agent Team**