# FORGE Command Reference

FORGE commands are available as slash commands in Claude Code.

## Available Commands

### Core Commands

| Command | Description | Usage |
|---------|-------------|-------|
| `/forge:new-project` | Initialize a new FORGE project | `/forge:new-project [project-name]` |
| `/forge:init` | Initialize FORGE in current directory | `/forge:init [--quick]` |
| `/forge:status` | Show project progress | `/forge:status [-v]` |
| `/forge:config` | View/edit configuration | `/forge:config [key] [value]` |
| `/forge:generate` | Generate artifact from template | `/forge:generate <artifact> [-f]` |
| `/forge:help` | Show command reference | `/forge:help [command]` |

### Planning Commands

| Command | Description | Usage |
|---------|-------------|-------|
| `/forge:discuss` | Structured context gathering with decisions | `/forge:discuss <phase-name>` |
| `/forge:plan` | Research-first multi-plan generation | `/forge:plan <phase-name> [flags]` |
| `/forge:verify` | Verify plans + generate gap closure plans | `/forge:verify <phase-name>` |
| `/forge:execute` | Wave-based multi-plan execution | `/forge:execute <phase-name> [--gaps]` |

### Phase Management Commands

| Command | Description | Usage |
|---------|-------------|-------|
| `/forge:add-phase` | Add phase to end of current milestone | `/forge:add-phase <description>` |
| `/forge:insert-phase` | Insert urgent work as decimal phase | `/forge:insert-phase <after-phase> <description>` |
| `/forge:remove-phase` | Remove future phase and renumber | `/forge:remove-phase <phase-number>` |

### Milestone Commands

| Command | Description | Usage |
|---------|-------------|-------|
| `/forge:new-milestone` | Start new milestone cycle | `/forge:new-milestone` |
| `/forge:complete-milestone` | Archive completed milestone | `/forge:complete-milestone` |

### Workflow Commands

| Command | Description | Usage |
|---------|-------------|-------|
| `/forge:pause-work` | Create context handoff | `/forge:pause-work` |
| `/forge:resume` | Resume from previous session | `/forge:resume` |
| `/forge:quick` | Execute quick task with guarantees | `/forge:quick <task-description>` |
| `/forge:debug` | Systematic debugging | `/forge:debug [issue description]` |

### Team Commands

| Command | Description | Usage |
|---------|-------------|-------|
| `/forge:team-create` | Create agent team from AgentTeam.md | `/forge:team-create` |
| `/forge:team-view` | View team members and config | `/forge:team-view` |
| `/forge:team-add` | Add member to agent team | `/forge:team-add` |
| `/forge:team-remove` | Remove member from agent team | `/forge:team-remove` |
| `/forge:team-start` | Start all teammates | `/forge:team-start` |

## Command Lifecycle

```
forge:new-project
       ↓
forge:new-milestone
       ↓
forge:discuss ←──── Structured gray area identification
       ↓              Produces CONTEXT.md with:
       ↓              • Implementation Decisions (locked)
       ↓              • Claude's Discretion (flexible)
       ↓              • Deferred Ideas (out of scope)
       ↓
forge:plan ←─────── Research-first planning
       ↓              1. Research (→ RESEARCH.md)
       ↓              2. Multi-plan generation (→ *-PLAN.md files)
       ↓              3. Verification
       ↓
       ↓ ┌──────── If plans exist: add more / verify / execute / replan
       ↓ ↓
forge:verify ←───── Goal-backward verification
       ↓              Checks all *-PLAN.md files
       ↓              If gaps → generates gap closure *-PLAN.md files
       ↓
       ↓ (pass)                  ↓ (gaps found)
forge:execute              forge:execute --gaps
       ↓                         ↓
       ↓  Wave-based execution:
       ↓  • Discovers all *-PLAN.md files
       ↓  • Groups by wave from frontmatter
       ↓  • Executes waves sequentially
       ↓  • Plans within wave in parallel
       ↓  • Each plan → *-SUMMARY.md
       ↓
forge:verify ←───── Post-execution verification
       ↓
forge:complete-milestone
```

## Phase Directory Structure

After running the full workflow, a phase directory looks like:

```
.planning/phases/M2-planning-engine/
├── M2-CONTEXT.md                      # From /forge:discuss
├── M2-RESEARCH.md                     # From research step in /forge:plan
├── M2-01-PLAN.md                      # Wave 1 — Schema design (2-3 tasks)
├── M2-02-PLAN.md                      # Wave 1 — Event types (2-3 tasks)
├── M2-03-PLAN.md                      # Wave 2 — Merge logic (depends on 01, 02)
├── M2-04-PLAN.md                      # Wave 2 — CLI commands
├── M2-05-PLAN.md                      # Wave 3 — Integration (depends on 03, 04)
├── M2-01-SUMMARY.md                   # After plan 01 execution
├── M2-02-SUMMARY.md                   # After plan 02 execution
├── ...
├── VERIFICATION.md                    # From /forge:verify
├── M2-06-PLAN.md                      # Gap closure plan (gap_closure: true)
└── EXECUTION.md                       # Execution log with wave/plan status
```

## CONTEXT.md Sections

The discuss command produces CONTEXT.md with structured sections that downstream agents consume differently:

| Section | Researcher reads as | Planner reads as |
|---------|-------------------|-----------------|
| **Implementation Decisions** | Research deeply, no alternatives | Must implement exactly as specified |
| **Claude's Discretion** | Research options, recommend best | Can choose freely, pick best approach |
| **Deferred Ideas** | Ignore completely | Must NOT include in plans |
| **Specific Ideas** | Research referenced patterns | Incorporate user inspirations |

## Plan Frontmatter Reference

Every `*-PLAN.md` file starts with YAML frontmatter:

```yaml
---
phase: M2-planning-engine       # Phase identifier
plan: 01                        # Sequential plan number
wave: 1                         # Execution wave (parallel within wave)
depends_on: []                  # Plan numbers this depends on
files_modified: [src/foo.ts]    # Files this plan touches
autonomous: true                # false if has checkpoints needing user input
gap_closure: false              # true for gap remediation plans
---
```

**Wave assignment rules:**
- Plans with no dependencies → wave 1
- Plans with dependencies → `wave = max(waves[dep] for dep in depends_on) + 1`
- Plans in the same wave execute in parallel
- Waves execute sequentially

## Research Workflow

The `/forge:plan` command includes a research step that produces `RESEARCH.md`:

1. Researcher reads CONTEXT.md to scope the research
2. Uses WebSearch, WebFetch, and codebase analysis
3. Produces structured findings with confidence levels (HIGH/MEDIUM/LOW)
4. Each major finding may become a separate plan file

Control with flags:
- `--research` — force re-run even if RESEARCH.md exists
- `--skip-research` — skip research entirely

## Plan Flags Reference

| Flag | Command | Effect |
|------|---------|--------|
| `--research` | `/forge:plan` | Force re-run research |
| `--skip-research` | `/forge:plan` | Skip research step |
| `--skip-verify` | `/forge:plan` | Skip plan verification |
| `--gaps` | `/forge:plan` | Generate gap closure plans only |
| `--gaps` | `/forge:execute` | Execute only gap_closure plans |

## Quick Start

### 1. Initialize a New FORGE Project

```bash
/forge:new-project my-app
```

### 2. Gather Context

```bash
/forge:discuss M2-planning-engine
```

Identifies gray areas, asks focused questions, produces structured CONTEXT.md.

### 3. Plan the Phase

```bash
/forge:plan M2-planning-engine
```

Researches (→ RESEARCH.md), generates multiple numbered plan files with frontmatter and wave assignments.

Running `/forge:plan` again when plans exist gives options: add more, verify, execute, or replan.

### 4. Verify Plans

```bash
/forge:verify M2-planning-engine
```

Checks all plans against requirements. If gaps found, generates gap closure plan files (numbered after existing plans).

### 5. Execute the Phase

```bash
/forge:execute M2-planning-engine
```

Discovers all plan files, groups by wave, executes waves sequentially with plans in each wave running in parallel. Each completed plan produces a SUMMARY.md.

### 6. Execute Gap Remediation (if needed)

```bash
/forge:execute M2-planning-engine --gaps
```

Executes only plans with `gap_closure: true` in their frontmatter.

## Artifact Generation

```bash
/forge:generate claude          # CLAUDE.md
/forge:generate requirements    # REQUIREMENTS.md
/forge:generate roadmap         # ROADMAP.md
/forge:generate config          # forge.config.json
/forge:generate rules           # .claude/rules/*.md
```

## Configuration

```bash
/forge:config                   # View all settings
/forge:config maxTeammates 6    # Set a value
```

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

## FORGE Architecture

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

### Key Principles

- **Event-Sourced State**: Append-only event log
- **Single-Writer**: Only State Steward writes STATE.json
- **Contract-First**: API contracts negotiated before cross-domain work
- **File Ownership**: Each agent writes only within owned paths
- **Wipe Protocol**: Fresh agent context per task
- **Atomic Commits**: One task = one commit

## Getting Help

```bash
/forge:help              # Show all commands
/forge:help plan         # Detailed help for specific command
```

## Version

FORGE v1.0-M1 — Milestone 1: Foundation (COMPLETE)