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

$3

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

$3

``bash
npm install -g gameforge-cli
`

$3

`bash


Clone the repository

git clone
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:

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

Then build and link the CLI:

`bash


Build the project

npm run build

Link the CLI globally (makes 'gameforge' command available)

npm link
`

$3

`bash


Check available commands

gameforge --help

List available templates

gameforge templates
`

$3

For active development with auto-rebuilding:

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

$3

`bash


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
`

$3

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

$3

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

$3

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

$3

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)

$3

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

$3

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

$3

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

$3

`
.gameforge/output//
├── 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

$3

`markdown


Weapon Crafting

Epic: EPIC-005: Core Crafting Loop

$3

Create long-term resource loops and player investment

$3

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

$3

Data Structure:
`cpp
struct CraftingRecipe {
List 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

$3

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

$3

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

$3

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

$3

`bash
npm run build
`

$3

`bash
npm run dev
`

$3

`bash


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.

$3

`bash
npm run lint
`

Advanced Usage

$3

`bash


List all saved sessions

gameforge sessions

View details for a specific session

gameforge session
`

$3

`bash


Resume from the latest checkpoint of a session

gameforge resume

Resume from a specific checkpoint

gameforge resume
`

$3

`bash


Modify an existing Game Design Document

gameforge modify

Enable debug logging

gameforge modify --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:

$3

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

$3

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

$3

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

$3

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

$3

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