/game-start

name: game-start
description: >
  Sets up a game project for GameForge: detects engine and project state, writes
  .gameforge/project.json and session state, merges the engine starter CLAUDE.md, configures Git and
  Git LFS, and connects coding agents to the engine (MCP, llms.txt). Use for "start a new game",
  "set up my project", "initialize GameForge". Not for finding an idea (use game-brainstorm).
argument-hint: "[engine: godot|unity|unreal|threejs|web2d] [working title]"
effort: high
allowed-tools: Read, Glob, Grep, Write, Edit, AskUserQuestion, Bash(git init *), Bash(git lfs *), Bash(git status *), Bash(git log *), Bash(git rev-parse *), Bash(mkdir *)

AlterLab GameForge -- Project Setup and Onboarding

This is the front door of a GameForge project. In one pass it finds out where the project stands, wires the plugin into it so the hooks and other skills work, sets up version control the way the engine needs, connects Claude Code to the engine, and leaves a clear next step. It meets the project where it lives: an empty folder, a design doc with no code, or an inherited codebase all start here.

Two jobs, in this order:

1. **Wire the project** (always): `.gameforge/project.json`, `production/session-state/active.md`, `.gitignore` entries, a merged `CLAUDE.md`, Git and Git LFS, agent setup. 2. **Assess the project** (scaled to what exists): gaps, structure, and the next three actions.

When NOT to use me

| The user wants... | Route to | |---|---| | Something playable tonight, built with an AI agent, minimal setup | `/gameforge:game-vibe-code` (offer the 2-minute wiring below first) | | A 48-72 hour jam entry | `/gameforge:game-jam-mode` | | A game idea, not a project | `/gameforge:game-brainstorm` | | A deep engine choice debate | `/gameforge:game-technical-director` with `${CLAUDE_PLUGIN_ROOT}/docs/engine-comparison.md` | | Documentation for code that already exists | `/gameforge:game-reverse-document` | | "Which skill do I need?" | `/gameforge:game-help` |

Critical Rules

1. **Never overwrite.** Existing `CLAUDE.md`, `.gitignore`, `.gitattributes`, `.claude/settings.json` and `.gameforge/project.json` are merged, never replaced. Show what you will add before writing. 2. **Detect before prescribing.** Read the project first. Do not assume an empty project or a tidy one. 3. **Ask only what you cannot detect.** If the engine is detectable, do not ask for it. 4. **Re-runs are updates.** If `.gameforge/project.json` exists, this is a re-run: show the current values, change only what the user asks, and re-check the wiring. 5. **Localhost-only agent tooling.** Every MCP server you suggest binds to `127.0.0.1`. Tools that execute code (Blender MCP, engine scripting bridges) are arbitrary code execution; say so. 6. **No destructive git.** `git init` and `git lfs` setup only. Offer the first commit; do not make it without the user's OK. 7. **Scope honesty.** If the user describes a 200-hour game and three weekends, say so now, kindly, and route to `/gameforge:game-scope-check`.

Step 0: Read the room

Gather silently before saying anything:

| Check | How | Tells you | |---|---|---| | GameForge config | Read `.gameforge/project.json` | Re-run vs. first run | | Godot | Glob `project.godot`; read `config/features` for the version | engine `godot` | | Unity | Read `ProjectSettings/ProjectVersion.txt` (`m_EditorVersion: 6000.3...` = 6.3) | engine `unity` | | Unreal | Glob `*.uproject`; read `EngineAssociation` | engine `unreal` | | Web | Read `package.json` dependencies: `three`, `@react-three/fiber`, `@babylonjs/core`, `playcanvas`, `phaser`, `pixi.js`, `kaplay`, `excalibur` | engine id from the table below | | Other | `Cargo.toml` with `bevy`, `*.yyp` (GameMaker), `game.project` (Defold), `main.lua` + `conf.lua` (LOVE) | `bevy` or `other` | | Git | `git rev-parse --is-inside-work-tree`, `git status --short`, `git log --oneline -5` | History, dirty files | | LFS | Read `.gitattributes`; `git lfs version` | LFS installed / tracked | | Docs and code | Glob `design/**`, `docs/**`, `src/**`, `scripts/**`, `Source/**`, `Assets/Scripts/**`, `tests/**` | Project state | | Agent config | Read `CLAUDE.md`, `.claude/settings.json`, `.mcp.json` | What is already wired | | Focus | Read `production/session-state/active.md` | Where the last session stopped |

Classify the state:

| State | Signals | Assessment depth | |---|---|---| | 1. Empty | No engine files, no code, no docs | Setup + concept stub | | 2. Concept | Design docs, no code | Setup + doc gap analysis | | 3. In progress | Code and some docs | Setup + structural health check | | 4. Mature | Code, CI, tests, history | Setup + audit |

Step 1: Ask the few questions that matter

Use one AskUserQuestion call with at most four questions, each with a recommended default:

1. **Engine** (only if not detected). Offer the two or three that fit what they said, with the recommended one first. Defaults: 2D web or jam -> Phaser 4; 3D web -> Three.js; 2D or stylized 3D desktop -> Godot 4.7; broad platform reach or mobile -> Unity 6.3 LTS; high-end 3D -> Unreal 5.8. 2. **Working title** (default: the folder name). 3. **Goal**: weekend or jam game / portfolio piece / commercial release. A weekend web game gets the 2-minute wiring and a hand-off to `/gameforge:game-vibe-code`; a jam goes to `/gameforge:game-jam-mode`. 4. **Permissions file**: install the GameForge `.claude/settings.json` starter? (default: yes if none exists).

The best engine is the one the team already knows. Switching mid-project costs more than a suboptimal first choice. For anything beyond these defaults, route to `/gameforge:game-technical-director`.

Current engine versions (as of November 2026)

| Engine | Start new projects on | Know before you pick | |---|---|---| | Godot | **4.7.2** stable (4.7 released 2026-06-18) | 4.8 is in beta; its .NET build needs .NET 10. Web export uses the Compatibility renderer (WebGL 2) only, and C