# 🔨 Forge

**An AI development system for Claude Code.** Build complex, domain-rich applications with emergent planning, domain intelligence, and architectural coherence.

Forge is for solo founders building products over months — not weekend projects. It understands your business domain, remembers your decisions, tracks what's built and what's planned, and maintains architectural coherence as your codebase grows.

---

## What Forge Does

**You talk. Forge builds.**

Describe what you want in plain language. Forge figures out if it's a bug fix, a new feature, an idea to capture, or an exploration to research — and handles it.

```
You: "The vehicle filter is broken, the weight class dropdown doesn't filter correctly"
Forge: Locates the bug, diagnoses it, fixes it, verifies the fix.

You: "I had an idea — tours should support partial loads where multiple orders share a vehicle"
Forge: Captures the idea, connects it to the domain model, estimates impact, stores it for later.

You: "What should I focus on today?"
Forge: Gives you a briefing — what's in progress, what's blocked, what's highest impact.
```

### Key Concepts

- **Emergent Planning** — No upfront specification. Plan just enough for the current work. The roadmap emerges from what you build.
- **Domain-First Intelligence** — Forge builds a domain model (DDD-style) before any technical planning. Your code speaks the language of your business.
- **Architectural Coherence** — Every decision is recorded. Patterns are enforced across the entire codebase. No architectural drift.
- **Session Continuity** — No pause/resume. Forge remembers where you left off and orients itself when you return.
- **Living Knowledge Base** — Domain model, architecture decisions, feature landscape, idea backlog — all machine-maintained, all human-readable.

---

## Install

### Quick Start

```bash
# Clone the repo
git clone https://github.com/YOUR_ORG/forge.git
cd forge

# Install to your project
./install.sh

# Or install globally (available in all projects)
./install.sh --global
```

### Manual Install

Copy the `.claude/` directory and `CLAUDE.md` into your project root:

```bash
cp -r forge/.claude/ your-project/.claude/
cp forge/CLAUDE.md your-project/CLAUDE.md
```

### What Gets Installed

```
your-project/
├── CLAUDE.md                      # System prompt — makes Forge "alive"
└── .claude/
    ├── commands/forge/            # Slash commands
    │   ├── init.md                # /forge:init — set up your project
    │   └── help.md                # /forge:help — command reference
    ├── agents/                    # Role definitions
    │   ├── forge-orchestrator.md  # Routes work to specialists
    │   └── forge-domain-modeler.md # Domain discovery (DDD)
    ├── skills/                    # Reference knowledge
    │   ├── domain-modeling.md     # DDD patterns and discovery
    │   ├── session-state.md       # Session continuity
    │   └── decisions-log.md       # Architecture Decision Records
    ├── templates/                 # Artifact templates
    │   ├── DOMAIN.md              # Domain model
    │   ├── ARCHITECTURE.md        # Tech stack and patterns
    │   ├── DECISIONS.md           # ADR log
    │   ├── LANDSCAPE.md           # Feature map
    │   ├── IDEAS.md               # Idea backlog
    │   ├── STATE.md               # Session state
    │   ├── DEPENDENCY-GRAPH.yaml  # Feature dependencies
    │   ├── CHANGE-IMPACT-MAP.yaml # Change tracking
    │   └── TOKEN-LEDGER.yaml      # Cost tracking
    └── config/
        └── forge.yaml             # Configuration
```

---

## Getting Started

### 1. Initialize Your Project

Open Claude Code in your project directory and run:

```
/forge:init
```

Forge will walk you through:
1. **Project type** — Greenfield (new) or brownfield (existing code)?
2. **Product vision** — What are you building? Who is it for?
3. **Domain discovery** — Interactive conversation to understand your business domain, entities, rules, and vocabulary
4. **Tech stack** — Framework, database, deployment, patterns

This creates a `.planning/` directory — your project's living knowledge base.

### 2. Start Building

```
/forge:build Implement vehicle management with CRUD operations and filtering
```

Or just describe what you want naturally:

```
"I need a screen where dispatchers can see all vehicles, filter by weight class, and add new ones"
```

### 3. Capture Ideas

```
/forge:idea Tours should support Teilladungen where multiple orders share a vehicle
```

Ideas get enriched with domain connections, impact estimates, and dependency analysis. They're first-class citizens, not to-do items.

---

## Commands

| Command | What It Does |
|---------|-------------|
| `/forge:init` | Set up Forge for your project |
| `/forge:help` | Show all commands |
| `/forge:build` | Build something — describe it naturally *(coming soon)* |
| `/forge:continue` | Pick up where you left off *(coming soon)* |
| `/forge:review` | Review what was built *(coming soon)* |
| `/forge:idea` | Capture a product idea *(coming soon)* |
| `/forge:explore` | Research a question *(coming soon)* |
| `/forge:decide` | Make a structured decision *(coming soon)* |
| `/forge:status` | Morning briefing *(coming soon)* |
| `/forge:pivot` | Change direction gracefully *(coming soon)* |
| `/forge:scope` | See what's in v1 vs. later *(coming soon)* |
| `/forge:demo-mode` | Prep for a demo *(coming soon)* |

**You don't need commands.** Just talk naturally. Commands are shortcuts, not requirements.

---

## The .planning/ Knowledge Base

After initialization, your project has a `.planning/` directory:

| File | What It Tracks |
|------|---------------|
| `DOMAIN.md` | Business domain — entities, relationships, rules, ubiquitous language |
| `ARCHITECTURE.md` | Tech stack, patterns, conventions |
| `DECISIONS.md` | Architecture Decision Records — the *why* behind every choice |
| `LANDSCAPE.md` | Living feature map — what's built, in progress, planned |
| `IDEAS.md` | Weighted idea backlog with impact scoring |
| `STATE.md` | Session state for seamless continuity |
| `DEPENDENCY-GRAPH.yaml` | Feature dependencies for impact analysis |
| `CHANGE-IMPACT-MAP.yaml` | File-level change tracking for debugging |
| `TOKEN-LEDGER.yaml` | Token usage and cost tracking |

These files are machine-maintained but human-readable. Browse them anytime.

---

## How Forge Differs from GSD

If you've used [GSD (Get Shit Done)](https://github.com/aloshy-ai/gsd), Forge builds on its strengths while addressing its limitations:

| | GSD | Forge |
|---|---|---|
| **Planning** | Define everything upfront | Emergent — build and discover |
| **Domain** | Technical research only | Domain-first modeling (DDD) |
| **Interaction** | Slash commands for PM workflows | Natural language with intent detection |
| **Roadmap** | Static ordered phase list | Living dependency graph |
| **Architecture** | No cross-phase enforcement | Architecture Guardian + ADR log |
| **Sessions** | Manual pause/resume | Automatic continuity |
| **Target** | Solo dev, single project | Solo founder, product over months |

Forge keeps what GSD gets right: atomic commits, fresh context per agent, XML task structure, dual quality gates. It evolves what GSD gets wrong for complex, long-lived products.

---

## Configuration

Edit `.claude/config/forge.yaml` to customize:

```yaml
# Model profiles — balance quality vs cost
active_profile: balanced    # quality | balanced | budget

# Autonomy — how much Forge does without asking
autonomy:
  auto_commit: true         # commit after each task?
  proactive_warnings: true  # surface architectural concerns?

# Preferences
preferences:
  language: en              # documentation language (en/de)
  commit_style: conventional
```

---

## Project Status

Forge is in early development. The `init` command works. Other commands are being built iteratively — Forge is being used to build a Transport Management System, and new capabilities are added as needed.

**What works now:**
- ✅ `/forge:init` — Project initialization with domain discovery
- ✅ `/forge:help` — Command reference
- ✅ Living knowledge base (`.planning/`)
- ✅ Session state and continuity

**What's next:**
- 🔜 `/forge:build` — Natural language to working code
- 🔜 `/forge:status` — Morning briefings
- 🔜 `/forge:idea` — Idea capture and enrichment
- 🔜 Architecture Guardian agent
- 🔜 Agent Teams integration

---

## License

MIT