GameForge CLI

Transform game ideas into production-ready Game Design Documents using AI

GameForge CLI is a terminal-based AI pipeline that turns raw game ideas into comprehensive, structured Game Design Documents (GDDs). It features an interactive interview process, strict validation, multi-agent generation, and outputs both JSON and Markdown documentation.

Features

• 🤖 AI-Powered Interview: Hybrid question system with smart defaults
• ❓ Disambiguation: Agents ask clarifying questions when needed
• 📊 Structured Output: Valid JSON + readable Markdown
• 💰 Cost Tracking: Real-time budget monitoring and warnings
• 💾 Checkpoint System: Save and resume at any phase
• 📚 Genre Templates: Quick-start templates for common game types
• ✅ Validation: Consistency checking + adversarial gap analysis + interactive issue review
• 🎯 Technical Specs: Math formulas, data structures, user stories
• 🎨 Multi-Agent System: Specialized agents for features, entities, creative, and technical specs
• 🔧 Modifier Agent: Edit existing GDDs with natural language requests

Installation

Prerequisites

• Node.js 18+ installed
• Anthropic API key (get one here)

Install via NPM (when published)

npm install -g gameforge-cli

Local Development Setup

# Clone the repository
git clone <repository-url>
cd GameForgeCLI

# Install dependencies
npm install

# Create .env file from template
cp .env.example .env

Edit the .env file and add your Anthropic API key:

ANTHROPIC_API_KEY=sk-ant-xxxxx  # Required: Your Anthropic API key

Then build and link the CLI:

# Build the project
npm run build

# Link the CLI globally (makes 'gameforge' command available)
npm link

Verify Installation

# Check available commands
gameforge --help

# List available templates
gameforge templates

Development Mode

For active development with auto-rebuilding:

npm run dev

Note: When using npm run dev, you'll need to run commands via node dist/index.js or keep npm link active after each rebuild.

Quick Start

Basic Usage

# Create a new GDD with standard budget
gameforge create

# Use quick budget (cheaper, less detail)
gameforge create --budget quick

# Use deep budget (more comprehensive)
gameforge create --budget deep

# Start from a template
gameforge create --template roguelike

Budget Tiers

| Tier | Cost Limit | Model | Description | |------|-----------|-------|-------------| | quick | $2.00 | Haiku | Fast draft with minimal detail | | standard | $10.00 | Sonnet 4.5 | Balanced quality and cost (recommended) | | deep | $25.00 | Sonnet 4.5 | Maximum detail and depth |

Available Templates

• roguelike - Procedural dungeons, permadeath, run-based progression
• farming-sim - Resource management, crop cycles, NPC relationships
• fps - Fast-paced combat, weapon variety, multiplayer
• soulslike - Stamina combat, difficult bosses, bonfire checkpoints
• metroidvania - Interconnected world, ability-gated progression

How It Works

GameForge CLI follows a structured pipeline with user review gates:

Phase 1: Discovery

Interactive interview with 10 carefully designed questions. Features:

• Multiple choice with suggested answers
• ✨ AI Decide: Let the AI suggest smart defaults based on your answers
• ✏️ Custom Answer: Enter free-form text
• Real-time cost tracking

Phase 2: Architecture

The Architect Agent transforms your answers into a validated GameBible JSON structure containing:

• Metadata (title, genre, scope, platforms)
• Features with technical specs, user stories, and dependencies
• Game objects (NPCs, items, monsters)
• Creative direction (art style, audio, assets)
• Technical requirements (engine, tools, localization)

Phase 3: Production

Four specialist agents run in sequence to generate detailed Markdown docs:

1. Creative Specialist - Art style, asset lists, pipeline
2. Feature Specialist - Mermaid diagrams, math formulas, data structures
3. Entity Specialist - NPC/Item/Monster stat tables
4. Tech Specialist - Engine setup, tools, directory structure

Phase 4: Validation & Remediation

Three-layer validation with interactive issue review:

1. Consistency Agent - Checks dependencies, naming conventions, circular refs
2. Chaos Agent - Adversarial critic finding gameplay gaps and scope issues
3. Interactive Issue Review - Review each issue one-by-one and select which to fix
4. Remediation Agent - Automatically fixes selected issues (up to 3 attempts per issue)

At the review gate, you can:

• Review issues individually with context and descriptions
• Select which issues to fix and which to keep
• Run the Remediation Agent on selected issues only
• Export the final GDD with gap analysis showing any unfixable issues

Disambiguation System

Throughout the pipeline, agents can ask clarifying questions when they encounter ambiguity. This ensures the final GDD accurately reflects your vision.

When Disambiguation Triggers:

• Architect: Vague scope, unclear monetization, minimal art direction
• Chaos: Critical issues with vague recommendations
• Feature Specialist: Features marked as "Very High" complexity
• Entity Specialist: Entity count exceeds reasonable scope
• Creative Specialist: Asset requirements seem unrealistic for scope
• Tech Specialist: Multi-platform targeting in early projects

Question Format: Each disambiguation question provides:

1. 2 AI-generated suggestions - Context-aware options based on your game
2. ✨ AI Decide - Let AI choose with reasoning
3. ✏️ Custom Answer - Use your system editor for detailed input

Example:

❓ The feature "Multiplayer Networking" is marked as "Very High" complexity.

Select an option:
› Keep it as-is and proceed
  Simplify to peer-to-peer only
  ✨ AI Decide (Smart Default)
  ✏️  Custom Answer

The AI Decide option provides reasoning:

🤖 AI Suggests: Simplify to peer-to-peer only
   Reasoning: For a Prototype scope, full client-server architecture 
   would significantly increase complexity. P2P is faster to implement.

Accept this suggestion? (Y/n)

Output Structure

.gameforge/output/<session-id>/
├── 00_Cover.md                 # Title page with concept
├── Creative_Direction.md       # Art, audio, assets
├── Feature_Specifications.md   # All features with diagrams
├── Entity_Specifications.md    # NPCs, items, monsters
├── Technical_Specifications.md # Engine, tools, build
├── 99_Gap_Analysis.md          # Unfixable validation issues (if any)
├── game_bible.json             # Complete structured data
└── Game_Design_Document.md     # Combined GDD with table of contents

Example Output

Feature Specification

## Weapon Crafting

**Epic**: EPIC-005: Core Crafting Loop

### Intent
Create long-term resource loops and player investment

### Gameplay Loop
```mermaid
sequenceDiagram
    participant Step0 as Collect Resources
    participant Step1 as Open Crafting Menu
    participant Step2 as Select Recipe
    participant Step3 as Confirm Craft
    participant Step4 as Receive Item

Technical Specification

Data Structure:

struct CraftingRecipe {
  List<ItemRequirement> inputs;
  Item output;
  float craftTime;
  int skillRequired;
}

Math Formulas:

• CraftTime = BaseTime * (1.0 - SkillLevel * 0.1)
  • Variables: BaseTime (float), SkillLevel (int 0-10)

File Location: Source/Game/Crafting/ Complexity: High

## Configuration

### Environment Variables

Create a `.env` file in the project root:

```env
ANTHROPIC_API_KEY=your_api_key_here
DEFAULT_MODEL=claude-sonnet-4-5-20250929
FALLBACK_MODEL=claude-haiku-4-5-20251001
MAX_BUDGET_USD=10.00
CHECKPOINT_DIR=.gameforge/checkpoints
OUTPUT_DIR=.gameforge/output

Architecture

Core Components

src/
├── agents/              # AI-powered agents
│   ├── base/           # BaseAgent with Anthropic SDK integration
│   ├── core/           # Inquisitor, Architect, Consistency, Chaos, Remediation
│   └── specialists/    # Feature, Entity, Tech, Creative specialists
├── config/             # Schemas, budgets, templates
│   ├── schema.ts       # Zod schemas (Game Bible SSOT)
│   ├── budget.ts       # Cost tiers and model pricing
│   └── templates.ts    # Genre templates
├── core/               # Infrastructure
│   ├── StateMachine.ts # Phase flow control
│   ├── SessionManager.ts # Save/resume & session tracking
│   └── Orchestrator.ts # Parallel specialist execution
├── utils/              # Utilities
│   ├── costTracker.ts  # Budget monitoring
│   ├── modelSelector.ts # Intelligent model selection
│   └── fileManager.ts  # File I/O
└── index.ts            # CLI entry point

Key Design Patterns

1. Single Source of Truth: All data flows through the GameBible schema
2. Multi-Agent System: Specialized agents for different domains
3. Progressive Enhancement: Start simple, AI fills in details
4. Validation Layers: Structural (Zod) + Logical (Consistency) + Design (Chaos)
5. Cost Awareness: Model selection based on complexity + budget

Development

Build

npm run build

Run in Development Mode

npm run dev

Run Tests

# Run all tests (18 unit tests + integration tests)
npm test

# Run specific test suites
npm test tests/unit
npm test tests/integration

# Watch mode
npm test -- --watch

See tests/README.md for detailed testing documentation.

Lint

npm run lint

Advanced Usage

Session Management

# List all saved sessions
gameforge sessions

# View details for a specific session
gameforge session <session-id>

Resume from Checkpoint

# Resume from the latest checkpoint of a session
gameforge resume <session-id>

# Resume from a specific checkpoint
gameforge resume <checkpoint-id>

Modify Existing GDD

# Modify an existing Game Design Document
gameforge modify <session-id>

# Enable debug logging
gameforge modify <session-id> --debug

The modify command allows you to make changes to previously generated GDDs using natural language. The Modifier agent will:

• Understand your requested changes
• Update the GameBible while preserving design intent
• Maintain ID naming conventions and dependency integrity
• Regenerate affected documentation sections

Limitations & Known Issues

• PDF export not yet available (Markdown only)
• Limited to 10 discovery questions (can extend in code)
• English only (no i18n support)
• Requires stable internet connection for API calls

Roadmap

GameForge aims to be a complete Game Idea → Production-Ready Tasks pipeline:

✅ Phase 1: Game Design Document (Complete)

• [x] Interactive discovery interview
• [x] Multi-agent GDD generation
• [x] Validation & remediation system
• [x] Interactive issue review system
• [x] Interactive editing mode (Modifier agent)
• [x] Genre templates

🎨 Phase 2: Art Design Document

Transform the GDD into a comprehensive Art Design Document (ADD):

• [ ] UI/UX specifications with AI-generated mockups
• [ ] AI-generated concept art for characters, environments, items
• [ ] Branding guidelines (logo concepts, color palettes, typography)
• [ ] Sound design specifications
• [ ] Music direction and composition guidelines
• [ ] Asset pipeline and naming conventions

🔧 Phase 3: Technical Design Document

Generate a detailed Technical Design Document (TDD) from the GDD:

• [ ] Comprehensive codebase architecture breakdown
• [ ] Major systems design (rendering, physics, networking, AI, etc.)
• [ ] AI-generated flow charts as Mermaid diagrams
• [ ] API specifications and data models
• [ ] Performance budgets and optimization strategies
• [ ] Platform-specific implementation notes

📋 Phase 4: Task Management Integration

Populate a task management system with implementation tasks using Beads:

• [ ] Auto-generate tasks from TDD and ADD specifications
• [ ] Dependency mapping between tasks
• [ ] Priority and complexity estimation
• [ ] Sprint/milestone organization
• [ ] Integration with existing project management tools

🔮 Future Enhancements

• [ ] PDF export
• [ ] Notion/Confluence integration
• [ ] Team collaboration features
• [ ] Multi-language support
• [ ] Real-time asset generation previews

Contributing

Contributions welcome! Please open an issue or PR.

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with Anthropic Claude (Sonnet 4.5 & Haiku)
• Powered by Zod for schema validation
• CLI built with Commander and Enquirer

Made with ❤️ for game developers