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

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:

Classify the state:

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)

Record the version you detect or install in engine_version (major.minor, or r187 for Three.js); note the exact patch version in the setup report.

Step 2: Wire GameForge into the project

Run mkdir -p .gameforge production/session-state production/session-logs, then write the files below. Creating .gameforge/ and production/session-state/ opts the project into GameForge's state hooks (pre-compact snapshot, recovery note, session and agent logs).

2a. .gameforge/project.json

{
  "name": "Ember Drift",
  "engine": "godot",
  "engine_version": "4.7",
  "phase": "concept",
  "pillars": [],
  "commit_convention": "conventional",
  "lfs_threshold_mb": 20
}

Phase defaults by state: Empty -> concept; Concept -> pre-production; In progress -> prototype or production (ask if unclear); Mature -> production or later.

2b. Session state and .gitignore

Write production/session-state/active.md; the session-start hook shows its first lines to Claude at the start of every session and after compaction:

# Active focus
**Now:** project setup with /gameforge:game-start (2026-11-05)
**Decisions:** engine Godot 4.7.2 (team knows GDScript); Git LFS for source art and audio
**Next:** /gameforge:game-brainstorm to pick the concept; then /gameforge:game-prototype
**Blocked on:** nothing

Append to .gitignore (create it if missing; never duplicate lines):

production/session-state/
production/session-logs/

2c. CLAUDE.md from the engine starter

• No CLAUDE.md yet: copy the starter (Read it, Write it to CLAUDE.md) and fill the bracketed placeholders from project.json.

• CLAUDE.md exists: merge. Keep every existing line. Add the starter's missing sections inside one delimited block so a re-run can update it in place:

  <!-- gameforge:start (managed by /gameforge:game-start; edit freely, re-runs update only this block) -->
  ...starter sections the project did not already have...
  <!-- gameforge:end -->

  Where the user's rules conflict with the starter (commit format, folder layout, naming), keep the user's and list the conflict in the report.

• If CLAUDE.md does not already say how to run and check the game near the top, add a short ## Run and check section as its first section (example in the agent-setup reference). Claude Code's own best-practice guidance is to keep CLAUDE.md short and lead with the check command; a long CLAUDE.md is followed less reliably, not more.

2d. Optional .claude/settings.json

If the user said yes, use ${CLAUDE_PLUGIN_ROOT}/starters/claude-config/settings.json. It enables the GameForge marketplace and plugin, allows read-only git and git lfs track, asks before push, merge and rebase, and denies force-push, reset --hard, rm -rf and reading .env or keystores. If a settings file exists, merge key by key: union the allow/ask/deny arrays, never remove a user rule, and never move a user's deny into allow.

Step 3: Version control and Git LFS

1. Init. If not a repository: git init -b main.
2. Ignore. Merge the engine's .gitignore block from ${CLAUDE_SKILL_DIR}/references/vcs-setup.md (read it now; it has per-engine .gitignore and .gitattributes blocks and the engine-specific traps).
3. LFS. Check git lfs version. If Git LFS is missing, tell the user how to install it (it is a system package) and continue; the commit hook will still block non-LFS files at or above lfs_threshold_mb. If present: git lfs install --local, merge the engine's .gitattributes block, then verify with git lfs track (lists patterns).

Step 4: Agent setup

Connect Claude Code to the engine so it can check its own work. Read ${CLAUDE_SKILL_DIR}/references/agent-setup.md before this step; it has the install commands, the check command per engine, and the security notes. Summary:

Rules: show the command and let the user run or approve it; every server stays on localhost; review a community server's repository before installing it; never put API keys in CLAUDE.md or committed config. The Godot Foundation's 2026 ban on AI-authored code applies to contributions to the engine itself, not to games made with Godot.

Step 5: Scaffold and assess

Add the GameForge overlay where it does not exist; keep the engine's own layout untouched:

design/            GDD, pillars, concept, balance data
docs/              architecture notes, ADRs
production/        sprints/, milestones/, session-state/ (ignored), session-logs/ (ignored)
prototypes/        throwaway experiments (never promoted to production code)

Engine layouts: Godot scenes/, scripts/, assets/, addons/ beside project.godot; Unity Assets/Scripts/, Assets/Scenes/, Assets/Prefabs/; Unreal Source/, Content/, Config/; web src/, public/. See ${CLAUDE_PLUGIN_ROOT}/docs/directory-conventions.md.

Then scale the assessment to the state from Step 0. Read ${CLAUDE_SKILL_DIR}/references/project-audit.md for States 3 and 4; it has the checklists.

For an AI-heavy prototype found in State 3 (one huge file, no tests, generated assets), say so plainly and recommend /gameforge:game-code-review before new features; that is vibe debt, and it compounds.

Step 6: Report and hand off

Write the report to production/setup-report.md, update active.md with the next step, and offer the first commit: chore: initialize GameForge project passes the default commit convention.

Working with AI Coding Agents

Setup is where an agent-built project is won or lost: the agent can only verify what the project lets it run.

• Delegate: scaffolding, .gitignore/.gitattributes merges, project.json, converting an existing README into the CLAUDE.md block, writing the check command into a script.
• Verify by hand: the engine opens the project without import errors; git lfs ls-files lists a test binary after the first commit; the MCP server answers only on 127.0.0.1; the check command in CLAUDE.md actually runs and fails when it should.
• Give the agent a pass/fail check on day one. A web game gets npm run build plus a Playwright screenshot test; Godot gets a headless test runner (GUT or gdUnit4); Unity gets edit-mode tests in batch mode; Unreal gets an automation test. Details per engine are in ${CLAUDE_SKILL_DIR}/references/agent-setup.md.
• Guardrails against vibe debt: the GameForge hooks already block edits to engine-generated files and oversized non-LFS binaries; add the folder layout and "one change per commit" to CLAUDE.md, and keep progress.md (decisions, TODOs) next to active.md for long agent runs.
• Originality: Claude Code declines to recreate specific existing games (since late October 2026). If the user's plan is "remake X", set the project up for an original game in X's genre and route the concept work to /gameforge:game-brainstorm.
• Assets: if the team plans AI-generated art, audio or voice, start the provenance log on day one with /gameforge:game-ai-assets; store disclosures are generated from it later.
• Fast path: a user who wants a playable tonight needs only Step 2 (two minutes) and the Playwright MCP line, then /gameforge:game-vibe-code. Do not run a State 4 audit on a weekend toy.

Prompt that works after setup: "Read CLAUDE.md and production/session-state/active.md, run the check command, and tell me what is broken before changing anything."

Output Format

# Project Setup Report: [Working title]
**Date:** [YYYY-MM-DD]   **State:** [Empty / Concept / In progress / Mature]
**Engine:** [Godot 4.7.2]   **Phase:** [concept]   **Goal:** [commercial / portfolio / jam / weekend]

## Wiring
| Item | Status | Notes |
|---|---|---|
| .gameforge/project.json | created / updated / unchanged | [values changed] |
| production/session-state/active.md | created | |
| .gitignore (state dirs + engine block) | merged | [lines added] |
| CLAUDE.md | copied / merged (gameforge block) | [conflicts kept as the user's] |
| .claude/settings.json | installed / merged / skipped | |
| Git | initialized / existing ([branch], [N] commits) | |
| Git LFS | tracking [patterns] / not installed | threshold [20] MB |
| Agent setup | [Playwright MCP, godot-mcp, Unity plugin...] | localhost only: [yes] |
| Check command | `[npm run build && npx playwright test]` | ran: [pass/fail/not yet] |

## What exists
- [What is already in good shape]

## Gaps
| Item | Severity | Recommended action |
|---|---|---|
| [No core loop defined] | Critical | /gameforge:game-brainstorm |

## Next three steps
1. [Highest-leverage action, with the skill to run]
2. [...]
3. [...]

Quality Criteria

• The detected state and engine match reality; nothing was assumed that could have been read.
• .gameforge/project.json is valid JSON with all seven keys and allowed values.
• production/session-state/ and production/session-logs/ are ignored by git.
• No existing file lost a line; every merge is listed in the report.
• Git LFS covers the engine's binary formats, or the report says why not.
• Every suggested MCP server is localhost-only, and code-execution risks are named.
• CLAUDE.md leads with a check command that actually runs.
• The user knows exactly what to run next.

Example Use Cases

1. "Set up a new Godot project for a 2D roguelike." Empty state, engine given. Writes the wiring, Godot .gitignore/LFS blocks, merges the Godot starter, suggests godot-mcp, creates a concept stub, points to ${CLAUDE_PLUGIN_ROOT}/genre-packs/roguelike/README.md and /gameforge:game-brainstorm.
2. "I inherited this Unity project." Mature state. Detects 6.3 from ProjectVersion.txt, checks Force Text and meta files, offers Unity's Claude Code plugin, runs the audit, routes to /gameforge:game-reverse-document.
3. "I want a little Three.js game this weekend." Two-minute wiring with engine: threejs, Playwright MCP, then /gameforge:game-vibe-code.
4. "Re-run setup; we moved to Unreal 5.8." Re-run: updates engine and engine_version, adds .uasset/.umap LFS tracking with locking, keeps everything else.