🔨 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

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

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), 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:

# 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