Webg Spec To Goal

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:

| Genre | Variants | Physics | Key Data Structures | |-------|----------|---------|-------------------| | shoot-em-up | bullet hell, shmup, Raiden-type, vertical/horizontal shooter | Arcade | bullet pools, wave spawners, hitboxes | | card-game | solitaire, matching, deck-builder, poker variant | None | deck, hand, discard pile, card state | | platformer | endless runner, side-scroller, precision platformer | Arcade | tilemap, player body, collectibles | | tower-defense | lane defense, creep wave, placement strategy | None (path-based) | tower registry, enemy path, wave queue | | puzzle | match-3, sliding, Tetris-type, word game | None or Arcade | grid state, match detection, gravity |

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.

| Signal | What it tells us | |--------|-----------------| | package.json | Existing project — check for Phaser in deps | | package.json → Phaser 3 in deps | Existing Phaser project → check if extend mode | | tsconfig.json | TypeScript already configured | | vite.config.* | Build tool already in place | | src/ with Phaser imports | Existing game code → check if extend mode | | goals/ folder | Previous goal runs; check for slug collision | | goals-plan.md | Existing roadmap → strong signal for extend mode | | AGENTS.md | Existing conventions to respect | | .gitignore | Check coverage for node_modules, dist/ | | index.html | Existing entry point | | tests/ with Playwright | Test infra already in place |

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

| Area | Heuristic | |------|-----------| | Name/slug | Kebab-case from game description; short and memorable | | Resolution | 800x600 unless user specifies widescreen or mobile | | Genre | Trust the variant mapping; ask only when ambiguous | | Scope | Narrowest scope that achieves the spec. Out-of-scope wins ties | | Art style | Pixel art default — fast to generate, scales cleanly | | Goal count | 5-7 goals; fewer for simple games, more for complex ones | | Mechanics | Genre defaults first; only add mechanics the user explicitly mentions |

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

/
├── 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 / already exists as a directory, stop and ask.

Step 5 — Plan

Write goals-plan.md at /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 | Purpose | |---|------|---------| | 00 | Foundation | Verify scaffold boots, customize constants, confirm state bridge works | | 01 | Core Mechanic | The one thing that makes this game this game (shooting, card play, jumping, placing towers, matching) | | 02 | Enemies / Content | Opposition or challenge content (enemy waves, card decks, level layouts, creep waves, puzzle boards) | | 03 | Progression | Scoring, levels, difficulty curve, win/lose conditions | | 04 | UI / HUD | Health bars, score display, menus, pause screen | | 05 | Polish | Art assets via $imagegen, sound effects, screen shake, particles, juice | | 06 | (Optional) Bonus | Tutorial, extra levels, achievements — only if user requested | | NN | QC Checkpoint | Final validation — gameplay loop cohesion, state bridge regression, difficulty balance, integration test |

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

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nathanonn
• Source: nathanonn/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.