AlterLab GameForge -- Project Onboarding Workflow

Every game project has a beginning, but not every beginning looks the same. You might be standing in front of an empty folder with nothing but ambition. You might have a thick design document but zero lines of code. You might be stepping into a codebase someone else started six months ago. This workflow detects where you are and gets you moving without wasting time on steps you have already completed.

The core philosophy: meet the project where it lives. Diagnose the current state, fill in the gaps, point toward the next meaningful action. Hollow Knight started as a game jam sketch. Stardew Valley started as a learning exercise. Undertale started as an EarthBound-inspired demo. None followed a textbook "correct" beginning -- but each had a moment where scattered ambition became structured execution. This workflow is that moment.

Purpose & Triggers

Use this workflow when:

• A developer says "I want to start a new game" or "help me set up my project"
• Someone joins an existing project and needs to get oriented
• A team wants a health check on their current project structure
• A solo dev has scattered files and wants to organize into a production-ready layout
• Anyone asks "where do I even begin?" in a game development context

Problems this solves:

• Analysis paralysis at the start of a new project
• Disorganized file structures that become unmanageable at scale
• Missing documentation that causes confusion later
• Skipped foundational decisions that create technical debt from day one
• New team members spending days figuring out where things live

Critical Rules

1. Never overwrite existing work. If the project already has files, structures, or docs, preserve them. Suggest reorganization, never deletion without explicit confirmation.

2. Detect before prescribing. Always scan the project state before recommending actions. Do not assume an empty project. Do not assume an existing one is well-organized.

3. Engine-agnostic until confirmed. If no engine is detected from project files, ask. Do not guess. The wrong engine assumption wastes enormous time.

4. Documents are not optional. Every project needs at minimum: a concept document, a technical architecture note, and a task tracking system. These are not bureaucracy -- they are the memory your future self will desperately need. ConcernedApe kept a running design doc throughout Stardew Valley's development, even as a solo dev. That document prevented drift across four years of work.

5. Scope honesty from minute one. If someone describes a 200-hour project and says they have 3 weekends, flag it immediately. Kindly, but immediately. The graveyard of abandoned indie games is filled with projects that were "almost done" for two years.

6. Reference shared standards. All structural decisions should align with the conventions documented in docs/collaboration-protocol.md. All design terminology should follow docs/game-design-theory.md.

Project Detection (Auto-populated)

These values are injected automatically via shell preprocessing before the skill content reaches Claude. They provide real-time project data so state detection starts from facts, not assumptions.

• Engine: !ls project.godot *.unity *.uproject 2>/dev/null | head -1 || echo "No engine project file detected"
• Git status: !git log --oneline -5 2>/dev/null || echo "No git history"
• Source file count: !find . -name "*.gd" -o -name "*.cs" -o -name "*.cpp" -o -name "*.h" -o -name "*.rs" -o -name "*.js" 2>/dev/null | wc -l
• Existing docs: !ls -1 docs/ 2>/dev/null || echo "No docs directory"
• Design directory: !ls -1 design/ 2>/dev/null || echo "No design directory"
• Test directory: !ls -1 tests/ 2>/dev/null || echo "No tests directory"
• Build config: !ls Makefile CMakeLists.txt SConstruct *.sln package.json Cargo.toml 2>/dev/null | head -3 || echo "No build config detected"
• Project age: !git log --reverse --format="%ar" 2>/dev/null | head -1 || echo "Unknown — no git history"
• Active contributors: !git shortlog -sn --no-merges 2>/dev/null | head -5 || echo "Unknown — no git history"
• TODO/FIXME count: !grep -r "TODO\|FIXME\|HACK\|XXX" src/ 2>/dev/null | wc -l || echo "0"

Use this auto-populated data to shortcut Step 0 below. If the engine field shows a detected project file, skip the engine detection prompts. If source file count is zero, you are in State 1 (Empty Project). If source file count is nonzero but docs directory is empty, the project likely has documentation gaps. The git history age and contributor count help distinguish solo dev projects from team projects, which affects recommended workflow complexity.

Workflow

Step 0: Project State Detection

Before any recommendations, assess the current state by scanning for these signals. Cross-reference against the auto-populated data above — much of this may already be answered.

STATE DETECTION MATRIX
---------------------------------------------------------------
Signal                          | Indicates
---------------------------------------------------------------
No files / empty directory      | State 1: Empty Project
Design docs but no source code  | State 2: Concept Exists
Source code + design docs       | State 3: In-Progress
Mature codebase + CI + tests    | State 4: Existing Project
---------------------------------------------------------------

Engine Detection Signals:
- project.godot, *.gd, *.tscn        --> Godot Engine
- *.unity, *.cs, ProjectSettings/     --> Unity
- *.uproject, *.cpp + UE macros       --> Unreal Engine
- package.json + Phaser/PixiJS        --> Web-based engine
- Cargo.toml + Bevy/macroquad         --> Rust-based engine
- No recognizable engine files        --> Ask the user

Run the detection, report findings, then branch to the appropriate state handler.

State 1: Empty Project

The blank canvas. This is where most solo devs and small teams start.

Step 1.1 -- Choose your engine (if not already decided):

• Present tradeoffs honestly, not engine fanboyism
• For 2D pixel art: Godot is lightweight and fast to prototype -- Cassette Beasts and Dome Keeper prove it ships commercial-quality games
• For 3D with asset store needs: Unity has the broadest ecosystem and the largest pool of learning resources
• For AAA-quality visuals: Unreal delivers but demands more hardware and expertise
• For web distribution: Phaser, PixiJS, or PlayCanvas
• The best engine is the one your team already knows. Switching engines mid-project kills more games than bad engine choices do
• Route to the appropriate engine specialist skill after selection

Step 1.2 -- Define the concept (route to game-brainstorm if needed):

• At minimum capture: working title, genre, platform, core mechanic, target audience
• If the user already has a concept, capture it in structured format
• If the user has no concept, route them to game-brainstorm before continuing

Step 1.3 -- Create the initial file structure:

The following is the recommended generic starting point. Adapt it to your engine.

project-root/
  design/
    gdd/                  -- Game Design Document and sub-documents
    narrative/            -- Story outlines, dialogue scripts, lore bibles
    levels/               -- Level layouts, progression maps, zone designs
    balance/              -- Economy spreadsheets, difficulty curves, tuning tables
  docs/
    architecture/         -- Technical architecture decisions and diagrams
    api/                  -- Internal API documentation for game systems
  src/
    core/                 -- Engine initialization, main loop, global managers
    gameplay/             -- Player mechanics, enemy behaviors, interaction systems
    ai/                   -- NPC behavior trees, pathfinding, decision-making
    ui/                   -- Menus, HUD, in-game UI components
    tools/                -- Editor extensions, debug to