---
description: Initialize Forge in a new or existing project
allowed-tools: Read, Write, Bash, Task
---

# /forge:init — Initialize Forge

## Purpose

Set up the Forge development system for this project. Creates the `.planning/` knowledge base, runs an initial domain discovery conversation, and records foundational decisions.

## Before You Begin

Check if `.planning/` already exists. If it does, warn the user:

> "This project already has a `.planning/` directory. Running init again will overwrite it. Do you want to continue, or did you mean `/forge:continue`?"

## Workflow

### Step 1: Project Type

Ask the user:

> **Is this a new project (greenfield) or an existing codebase (brownfield)?**

- **Greenfield**: We'll start from scratch — domain discovery, tech stack decisions, then you're ready to build.
- **Brownfield**: We'll set up Forge's knowledge base around your existing code. After init, you can run `/forge:map-codebase` to analyze what's already built.

Store the answer. Brownfield projects will need `map-codebase` later (not part of init).

### Step 2: Product Vision

Ask the user to describe their product in plain language:

> **What are you building? Who is it for? What problem does it solve?**

Capture this as 3-5 sentences. This becomes the opening section of DOMAIN.md and ARCHITECTURE.md. Don't over-formalize — keep the user's own words. This should feel like talking to a co-founder, not filling out a form.

### Step 3: Domain Discovery

This is the most important step. Spawn the **forge-domain-modeler** agent to run an interactive domain discovery conversation.

```xml
<task>
  <agent>forge-domain-modeler</agent>
  <context>
    Read .claude/skills/domain-modeling.md for methodology.
    Read .claude/templates/DOMAIN.md for output format.
  </context>
  <instructions>
    Run domain discovery for this product:

    Product vision: {{product_vision from step 2}}
    Project type: {{greenfield or brownfield}}

    Have a conversation with the user to understand:
    1. Core domain — what is the essential business this software models?
    2. Key entities — what are the main "things" in the system?
    3. Relationships — how do entities connect?
    4. Business rules — what constraints exist? What can/can't happen?
    5. Regulatory requirements — any legal/compliance concerns?
    6. User roles — who uses this system and what do they do?
    7. Ubiquitous language — what terms does the business use? (Use THEIR language, not generic software terms)

    Ask questions conversationally, not as a checklist. Follow the user's energy — if they're excited about one area, go deeper there. You can always fill gaps later.

    Output a completed DOMAIN.md following the template format.
  </instructions>
</task>
```

### Step 4: Tech Stack & Architecture

Ask the user about their technical choices. Adapt questions based on greenfield vs brownfield:

**Greenfield questions:**

> - What's your tech stack? (framework, language, database, deployment)
> - Monorepo or single package?
> - Any strong opinions on patterns? (REST vs GraphQL, ORM vs raw queries, etc.)
> - What's your deployment target? (Vercel, AWS, self-hosted, etc.)

**Brownfield questions:**

> - I'll learn your tech stack from the codebase when you run `/forge:map-codebase`. For now, anything important I should know about your architecture?
> - Any architectural decisions you've made that you want to preserve?
> - Any technical debt or patterns you want to move away from?

Record each significant decision as an ADR entry in DECISIONS.md:

```markdown
## ADR-001: Tech Stack Selection

- **Date**: {{today}}
- **Status**: Accepted
- **Context**: Starting a new {{product type}} project
- **Decision**: {{what they chose}}
- **Rationale**: {{why, in their words}}
```

### Step 5: Create .planning/ Structure

Create the following directory structure and files:

```
.planning/
├── DOMAIN.md                    ← filled from domain discovery (step 3)
├── ARCHITECTURE.md              ← filled from tech stack decisions (step 4)
├── DECISIONS.md                 ← initial ADRs from step 4
├── LANDSCAPE.md                 ← initialized empty (features grow as you build)
├── IDEAS.md                     ← initialized empty
├── STATE.md                     ← initialized with "just created" state
├── DEPENDENCY-GRAPH.yaml        ← initialized empty
├── CHANGE-IMPACT-MAP.yaml       ← initialized empty
├── research/
│   ├── domain/                  ← empty, for future domain research
│   └── technical/               ← empty, for future technical research
├── work/                        ← empty, work items appear as you build
└── archive/                     ← empty, completed/pivoted work goes here
```

For files not yet filled by conversation (LANDSCAPE.md, IDEAS.md, etc.), use the templates from `.claude/templates/` and initialize them with sensible defaults.

### Step 6: Initialize Config

If `.claude/config/forge.yaml` doesn't exist with project-specific overrides, note that the default config applies. The user can customize later.

### Step 7: Summary & Next Steps

Present a clear summary:

> **Forge is set up.** Here's what I created:
>
> 📂 `.planning/` — Your project knowledge base
>
> - **DOMAIN.md** — {{number}} entities, {{number}} bounded contexts, {{number}} business rules captured
> - **ARCHITECTURE.md** — {{tech stack summary}}
> - **DECISIONS.md** — {{number}} initial decisions recorded
> - Plus: LANDSCAPE.md, IDEAS.md, STATE.md, and tracking files (all ready to grow)
>
> **What's next:**
>
> - `/forge:build <description>` — Start building something. Describe what you want in plain language.
> - `/forge:idea <description>` — Capture a feature idea for later.
> - `/forge:map-codebase` — _(brownfield only)_ Analyze your existing code.
> - `/forge:help` — See all available commands.

## Tone

This is the user's first interaction with Forge. It should feel like onboarding with a smart co-founder — curious, efficient, opinionated when helpful, never bureaucratic. Ask good questions, move fast, don't over-formalize.

## Error Handling

- If the user wants to skip domain discovery: let them, but note that DOMAIN.md will be sparse and suggest revisiting before building complex features.
- If the user gives minimal answers: work with what you have. A thin DOMAIN.md is better than no DOMAIN.md. It grows over time.
- If the user already has strong opinions about architecture: great, record them as ADRs. Don't argue unless you see a genuine risk.