webg-spec-to-goal — Vague Game Idea → Complete Codex /goal Project

Turn a rough web game idea into a runnable Phaser 3 project scaffold plus every goal folder Codex /goal needs to build it autonomously:

my-game/
├── AGENTS.md
├── goals-plan.md
├── goals/
│   ├── 00-foundation/    GOAL.md  VERIFY.md  PROGRESS.md
│   ├── 01-core-mechanic/ GOAL.md  VERIFY.md  PROGRESS.md
│   ├── ...
│   └── NN-polish/        GOAL.md  VERIFY.md  PROGRESS.md
├── src/                  runnable game skeleton
├── tests/                Playwright config + helpers
└── public/               assets directories

Games naturally decompose into 5-8 goals following a universal build order. This skill generates all goals at once — no checkpoint between plan and generation.

Extend mode: This skill also supports extending an existing game with new features. When the user explicitly states they want to extend an existing game, the skill reads the current project state and generates additional goals that continue the sequence.

Why this skill exists

Games have a predictable build order: scaffold → core mechanic → enemies/content → progression → UI → polish. This skill exploits that pattern to collapse the entire "idea → goal bundle" pipeline into one conversation that:

• auto-detects genre from the description and tailors everything to it
• asks 2-3 rounds of clarifying questions (each with options + recommendation)
• writes a runnable scaffold (boots to a blank Phaser scene out of the box)
• generates all goal folders at once with genre-aware decomposition
• bakes in state bridge verification (window.__GAME_STATE__ + Playwright)

Genre system

Five base genres, each with known variants:

Variant mapping: Map the user's description to a base genre. "Bullet hell" → shoot-em-up. "Endless runner" → platformer. "Match-3" → puzzle. "Solitaire" → card-game. Confirm with the user.

Unsupported types — hard stop:

• RPG / JRPG (content-heavy, dialogue trees, save systems)
• Simulation (open-ended state)
• Racing (continuous physics, track design)
• 3D games (Phaser is 2D only)

Genre determines: Phaser physics config, data structures in scaffold, goal decomposition order, state bridge fields, and verification patterns in every VERIFY.md.

Core flow — 7 steps

New game mode (default)

1. Probe — inspect cwd for existing projects, conflicts, or extend intent.
2. Classify — auto-detect genre from description, ask user to confirm.
3. Ask — 2-3 rounds of clarifying questions (max 3 rounds).
4. Scaffold — write runnable game skeleton.
5. Plan — write goals-plan.md with goal sequence.
6. Write — generate all goal folders at once (including QC checkpoint as the final goal).
7. Hand off — print file paths + /goal commands.

Extend mode (user explicitly states intent)

1. Probe — detect existing project, read goals-plan.md + state bridge to understand current state.
2. Classify — identify what genre the existing project is (from its goals-plan.md or AGENTS.md).
3. Ask — 1-2 rounds: what features to add, scope, whether to include QC checkpoint.
4. (Skip scaffold — project already exists.)
5. Plan — append new goals to existing goals-plan.md.
6. Write — generate new goal folders only (continuing goal numbering from highest existing).
7. Hand off — print new file paths + /goal commands for the new goals only.

Never write files until confidence is at 95%+.

Step 1 — Probe

Before asking the user anything, inspect the cwd.

New game mode

Existing Phaser project detected AND user did NOT express extend intent? Stop. Print:

This directory already contains a Phaser project. Would you like to extend it with new features (extend mode), or should we scaffold a new game in a different directory?

Extend mode detection

The user explicitly states they want to extend an existing game (e.g., "add a boss fight to my shmup", "extend the game with a new level", "add power-ups to the existing game"). When this happens:

1. Read goals-plan.md to determine: genre, variant, highest goal number, state bridge state.
2. Read src/state-bridge.ts to see current fields.
3. Read AGENTS.md for project conventions.
4. Note the highest existing goal number (e.g., 08) — new goals start at N+1.

If goals-plan.md doesn't exist but it's clearly a Phaser project made by this skill (has state-bridge.ts, goals/ folder), reconstruct the context from the goal folders.

Step 2 — Classify

Read the user's game description and auto-detect the genre. The variant mapping table in references/genre-templates.md has the full mapping. Quick process:

1. Scan for genre keywords (see genre table above).
2. Map variants to base genre.
3. Present the detection to the user for confirmation:

Based on your description, this sounds like a shoot-em-up (Raiden-type vertical shooter). Is that right, or should I classify it differently?

If the description is ambiguous, present 2-3 candidate genres with reasoning and ask the user to pick.

If the description maps to an unsupported type (RPG, simulation, racing, 3D), stop immediately with a clear explanation of why it's out of scope.

Step 3 — Ask clarifying questions

Use the AskUserQuestion tool when available. Fall back to natural-language Q&A with the same shape: 2-4 questions per round, recommended option first and labeled (Recommended), plus a one-line reason.

Aim for 2-3 rounds. Max 3 rounds. Skip questions already answered by the spec or probe.

Round 1 — Identity + Resolution

• Game name / slug: Suggest kebab-case from the game description (e.g., "space-raiders"). Must be a valid npm package name and directory name.
• Resolution: 800x600 (Recommended — standard 4:3, works on most screens) / 1024x768 / 960x540 (16:9) / Custom.
• Confirm genre: "I detected [genre]. Correct? If not, which genre fits better?"

Round 2 — Mechanics + Scope

• Acceptance criteria: Draft 4-6 AC bullets from the spec, then ask the user to confirm, edit, or add. Don't make them write ACs from scratch.
• Out of scope: Suggest boundaries (multiplayer, mobile-specific controls, save/load, procedural generation, online leaderboards).
• Genre-specific mechanics: Tailor to the genre:
  • shoot-em-up: weapon types, power-up system, boss fights?
  • card-game: hand size, draw rules, win condition?
  • platformer: jump physics, wall-jump, double-jump?
  • tower-defense: tower types, upgrade tiers, enemy variety?
  • puzzle: grid size, match rules, scoring?

Round 3 — Art + Audio + Optional Goals

• Art style: Pixel art (Recommended for most games — clear at small sizes, fast to generate) / Flat vector / Painted / Placeholder-only (colored rectangles).
• Audio: Include sound effects + music goal (Recommended) / Skip audio entirely.
• Optional goals: Any extra goals beyond the standard decomposition? (e.g., "add a tutorial level", "add screen shake effects").

Confidence check after each round

After each round: "If I started writing files now, what could go wrong?" If "not much" → proceed. If meaningful unknowns → ask one more focused round. If 3 rounds done and still under 95% → tell the user rather than guessing.

Recommendation heuristics

Step 4 — Scaffold

Always scaffold. This is mandatory (unlike WP/CLI skills where it's optional). Templates live in references/scaffold-templates.md (file contents) and references/agents-template.md (AGENTS.md content). Read both when scaffolding.

Generated file tree

<slug>/
├── index.html              Vite entry, mounts #game-container
├── package.json            phaser@3, typescript, vite, playwright
├── tsconfig.json           strict, es2022, DOM lib
├── vite.config.ts          dev server on port 8080
├── .gitignore              node_modules, dist/, test-results/
├── AGENTS.md               stack + Phaser conventions + state bridge docs
├── public/
│   ├── style.css           minimal reset, #game-container centered
│   └── assets/
│       ├── images/         sprite sheets, backgrounds
│       ├── audio/          sfx, music
│       └── data/           level JSON, wave definitions
├── src/
│   ├── main.ts             Vite entry → creates Phaser.Game
│   ├── state-bridge.ts     exposes window.__GAME_STATE__ for Playwright
│   └── game/
│       ├── main.ts         Phaser.Types.Core.GameConfig (genre-aware physics)
│       ├── configs/
│       │   └── constants.ts  resolution, colors, physics tuning
│       └── scenes/
│           ├── BootScene.ts      asset loading + progress bar
│           ├── MenuScene.ts      title screen + "Press Start"
│           ├── GameScene.ts      main gameplay (empty shell)
│           └── GameOverScene.ts  score display + restart
└── tests/
    ├── playwright.config.ts  baseURL: localhost:8080, webServer config
    └── game/
        ├── helpers.ts        waitForGameState(), getState() utilities
        └── boot.spec.ts      verifies game boots + scenes registered

State bridge

The state bridge is the key verification mechanism. src/state-bridge.ts exposes a typed window.__GAME_STATE__ object that Playwright tests read via page.evaluate().

Base fields (always present):

interface GameState {
  scene: string;       // current active scene key
  ready: boolean;      // true after BootScene completes
  score: number;
  gameOver: boolean;
}

Genre-specific fields are added by each goal (documented in the goal's "State Bridge Additions" section).

Genre-aware physics config

The scaffold sets the Phaser physics config based on genre:

• shoot-em-up / platformer: arcade physics, gravity per genre (0 for shmup, tuned for platformer)
• card-game / tower-defense / puzzle: no physics (or minimal arcade for drag-and-drop)

Collision handling

Never overwrite existing files without explicit user confirmation. If <slug>/ already exists as a directory, stop and ask.

Step 5 — Plan

Write goals-plan.md at <slug>/goals-plan.md. Template lives in references/goals-plan-template.md. Read it when generating. This is the master roadmap.

Universal build order

Every game follows this progression (some goals may be merged for simple games):

Goal 00 is always lightweight: verify the scaffold boots, tweak constants, confirm the state bridge reports correctly. The real work starts at Goal 01.

QC Checkpoint is always the last goal (whatever number that ends up being). It validates the entire game as a cohesive experience: complete gameplay loop, clean restarts, state bridge correctness, and difficulty balance. Template lives in references/qc-checkpoint-template.md.

The plan file includes: goal number, goal name, 1-2 line description, key ACs for that goal, and dependencies.

Step 6 — Write all goal folders

Generate all goal folders at once under <slug>/goals/. Each folder contains GOAL.md + VERIFY.md + PROGRESS.md.

Templates live in:

• references/goal-template.md — full GOAL.md template (13 sections)
• references/verify-template.md — full VERIFY.md template (tiered verification)
• references/progress-template.md — initial PROGRESS.md skeleton
• references/genre-templates.md — per-genre goal decomposition sequences, ACs, state bridge fields, and variant mappings
• references/qc-checkpoint-template.md — QC checkpoint goal (always last)

Read these reference files when generating. Substitute placeholders with everything confirmed in Steps 2-3. Use references/genre-templates.md to determine the goal sequence, ACs, and state bridge fields for the detected genre. Always generate the QC checkpoint as the final goal (use references/qc-checkpoint-template.md).

GOAL.md — 13 sections

Every GOAL.md contains these sections:

1. Objective — one-paragraph summary of what this goal achieves.
2. Genre & Physics Config — genre name, physics system, relevant Phaser config.
3. Scope — in-scope and out-of-scope bullets.
4. Depends On — which previous goals must be complete.
5. Allowed Files — explicit list of files this goal may create or modify.
6. Scene Architecture — which scenes this goal touches and how.
7. Game Systems — classes, managers, or patterns to implement.
8. State Bridge Additions — new fields to add to window.__GAME_STATE__.
9. Acceptance Criteria — numbered AC list (AC-XX.1, AC-XX.2, ...).
10. Asset Requirements — sprites, sounds, data files needed (placeholders OK for non-Polish goals).
11. Definition of Done — checklist including "all previous tests still pass."
12. Completion Audit Checklist — table mapping each AC to evidence.
13. Stop Conditions — when to stop and ask instead of guessing.

Filling rules

• Replace every {{placeholder}} with concrete values. Never leave one in.
• Leave audit evidence cells empty — /goal fills those at completion time.
• If a section doesn't apply, write Not applicable. plus a one-line reason. Don't delete the section.
• Give every AC a stable ID: AC-00.1, AC-01.1, AC-01.2, etc.
• Match the user's stated scope literally.
• Before writing, scan for any remaining {{ — fix before emitting.

Art strategy — hybrid

• Goals 00-04: use placeholder assets (colored rectangles, simple shapes). Note in each goal's Asset Requirements: "Placeholder OK — final art ships in Polish goal."
• Goal 05 (Polish): consolidated art goal. Include general $imagegen guidelines:
  • Use magenta (#FF00FF) background for sprites that need transparency
  • Remove magenta via chromakey after generation
  • Generate at 2x target resolution for downscale quality
  • Specify art style consistent with Round 3 answer (pixel art / flat vector / painted)
• AGENTS.md also documents the art pipeline so /goal knows the convention.

Verification — tiered

Every VERIFY.md uses a three-tier system:

Each VERIFY.md describes the test scenarios. /goal writes the actual .spec.ts files in tests/game/.

Regression rule: every goal's VERIFY.md includes "Run all previous goals' tests — they must still pass."

Sandbox rule

The dev server runs on localhost:8080. Playwright connects to it. If the harness sandboxes shell access, it needs:

• localhost:8080 for the Vite dev server
• Network access for npm install (one-time)

No Docker, no container filesystem, no external services.

Step 7 — Hand off

After writing all files, print:

Scaffolded:
  <slug>/index.html
  <slug>/package.json
  <slug>/tsconfig.json
  <slug>/vite.config.ts
  <slug>/.gitignore
  <slug>/AGENTS.md
  <slug>/public/style.css
  <slug>/public/assets/{images,audio,data}/
  <slug>/src/main.ts
  <slug>/src/state-bridge.ts
  <slug>/src/game/main.ts
  <slug>/src/game/configs/constants.ts
  <slug>/src/game/scenes/{Boot,Menu,Game,GameOver}Scene.ts
  <slug>/tests/playwright.config.ts
  <slug>/tests/game/helpers.ts
  <slug>/tests/game/boot.spec.ts

Goals plan:
  <slug>/goals-plan.md

Goal folders:
  <slug>/goals/00-foundation/   GOAL.md  VERIFY.md  PROGRESS.md
  <slug>/goals/01-core-mechanic/ GOAL.md  VERIFY.md  PROGRESS.md
  ...
  <slug>/goals/NN-polish/       GOAL.md  VERIFY.md  PROGRESS.md

To run goals sequentially with Codex /goal:
  /goal Complete <slug>/goals/00-foundation/GOAL.md. Use VERIFY.md as the verification contract. Update PROGRESS.md continuously. Treat uncertainty as incomplete.

  (after each goal completes, run the next:)
  /goal Complete <slug>/goals/01-core-mechanic/GOAL.md. Use VERIFY.md as ...

How to run:
  1. cd <slug> && npm install
  2. npm run dev              # boots game at localhost:8080
  3. npm test                 # runs Playwright tests
  4. Open Codex and paste the first /goal command.
  5. Review changes via `git diff` before committing.

Stop conditions

Hard stops — refuse and explain

Soft stops — warn and offer alternatives

Standard stops — ask instead of guessing

Extend mode — detailed behavior

When the user explicitly says they want to extend an existing game:

Step 1 (Probe) — Read existing project

Read these files to understand current state:

• goals-plan.md — genre, variant, goal count, state bridge growth
• src/state-bridge.ts — current GameState interface fields
• AGENTS.md — project conventions
• goals/ folder listing — highest goal number

Step 3 (Ask) — Extend-specific questions

Round 1:

• What to add: "What features or content do you want to add?" (draft suggestions based on the genre's Optional Goals in references/genre-templates.md)
• Scope: "How large is this extension?" (1-2 new goals / 3-5 new goals / 6+ new goals)

Round 2 (if 3+ new goals):

• QC checkpoint: "Since this extension adds 3+ goals, I recommend including a QC checkpoint as the final goal to validate everything integrates well. Include it?" (Yes, include QC checkpoint (Recommended) / No, skip it)

For extensions with <3 new goals, mention QC is available but default to skipping:

"This is a small extension (1-2 goals). I'll skip the QC checkpoint by default — let me know if you'd like to include it anyway."

Step 5 (Plan) — Append to existing plan

• Read the existing goals-plan.md
• Determine highest goal number (e.g., 08 if QC checkpoint was 08)
• New goals continue from N+1 (e.g., 09, 10, 11...)
• Append new goal rows to the Goal Sequence table
• Append new state bridge fields to the State Bridge Growth table
• If QC checkpoint is included, it's always the last goal in the new sequence

Step 6 (Write) — New folders only

• Only generate goal folders for the new goals
• AC IDs continue the sequence: if last existing AC was AC-08.7, new goals start at AC-09.1
• State bridge additions build on the current cumulative state
• Dependencies reference the last existing goal (or a specific existing goal if relevant)

Step 7 (Hand off) — New goals only

Print only the new goal folders and /goal commands. Don't re-list existing files.

What this skill does not do

• It does not implement the game. That's /goal's job.
• It does not run tests. That's /goal's job.
• It does not work for 3D games, multiplayer games, or non-browser platforms.
• It does not work for non-Phaser engines (Unity, Godot, Pixi.js, etc.).
• It does not generate actual art assets. It sets up the pipeline for /goal to use $imagegen.
• It does not fix bugs. For bug fixes, use /goal directly.
• It does not handle deployment (hosting, CDN, itch.io upload). That's post-goal work.