Help us improve
Share bugs, ideas, or general feedback.
From webg-spec-to-goal
Convert a web game idea (even a vague one like "build a Raiden-type game" or "make a card game") into a complete Codex /goal-ready Phaser 3 project — runnable scaffold, goals-plan.md, and all goal folders (GOAL.md + VERIFY.md + PROGRESS.md) generated at once. Auto-detects genre (shoot-em-up, card game, platformer, tower defense, puzzle), asks clarifying questions in focused batches, scaffolds a runnable TypeScript + Vite + Phaser 3 skeleton with state bridge for automated verification via Playwright, decomposes into 5-7 goals following a universal build order, and emits tailored /goal commands. Handles bullet hell, endless runner, match-3, solitaire, shmup, side-scroller, defense, and other genre variants. For browser-based 2D Phaser 3 games only — not 3D, multiplayer, RPGs, or non-browser platforms.
npx claudepluginhub nathanonn/agent-skills --plugin webg-spec-to-goalHow this skill is triggered — by the user, by Claude, or both
Slash command
/webg-spec-to-goal:webg-spec-to-goalThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Turn a rough web game idea into a runnable Phaser 3 project scaffold plus every goal folder Codex `/goal` needs to build it autonomously:
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Explores codebases via GitNexus: discover repos, query execution flows, trace processes, inspect symbol callers/callees, and review architecture.
Share bugs, ideas, or general feedback.
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.
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:
window.__GAME_STATE__ + Playwright)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:
Genre determines: Phaser physics config, data structures in scaffold, goal decomposition order, state bridge fields, and verification patterns in every VERIFY.md.
goals-plan.md with goal sequence./goal commands.goals-plan.md + state bridge to understand current state.goals-plan.md./goal commands for the new goals only.Never write files until confidence is at 95%+.
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 |
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?
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:
goals-plan.md to determine: genre, variant, highest goal number, state bridge state.src/state-bridge.ts to see current fields.AGENTS.md for project conventions.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.
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:
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.
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.
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.
| 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 |
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.
<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
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).
The scaffold sets the Phaser physics config based on genre:
arcade physics, gravity per genre (0 for shmup, tuned for platformer)Never overwrite existing files without explicit user confirmation. If <slug>/ already exists as a directory, stop and ask.
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.
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.
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 skeletonreferences/genre-templates.md — per-genre goal decomposition sequences, ACs, state bridge fields, and variant mappingsreferences/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).
Every GOAL.md contains these sections:
window.__GAME_STATE__.{{placeholder}} with concrete values. Never leave one in./goal fills those at completion time.Not applicable. plus a one-line reason. Don't delete the section.AC-00.1, AC-01.1, AC-01.2, etc.{{ — fix before emitting.$imagegen guidelines:
AGENTS.md also documents the art pipeline so /goal knows the convention.Every VERIFY.md uses a three-tier system:
| Tier | Label | Method | Required? |
|---|---|---|---|
| MUST | Automated | State bridge assertions via page.evaluate() in Playwright | Yes — goal fails without these |
| SHOULD | Screenshot | page.screenshot() for human review | Yes — but human judges pass/fail |
| NICE | Edge case | Polish and edge-case checks | No — bonus quality |
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."
The dev server runs on localhost:8080. Playwright connects to it. If the harness sandboxes shell access, it needs:
npm install (one-time)No Docker, no container filesystem, no external services.
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.
| Condition | Reason |
|---|---|
| Multiplayer / networked gameplay | Requires server infrastructure, netcode, latency handling |
| 3D game (Three.js, Babylon, etc.) | Phaser is 2D only |
| Non-browser platform (mobile app, desktop exe) | Skill targets browser-only Phaser 3 |
| Content-heavy RPG (dialogue, quests, save system) | Too many interlocking systems for goal decomposition |
| Condition | Response |
|---|---|
| Unsupported genre variant | Explain which genres are supported; ask user to reframe |
| Very complex (>10 distinct mechanics) | Suggest trimming to MVP; offer to scope-cut |
| Mobile-only (touch controls, portrait mode) | Warn about Phaser mobile performance; proceed if user confirms |
| Phaser 4 / other engine requested | This skill targets Phaser 3; suggest manual setup for other engines |
| Condition | Action |
|---|---|
| Slug collision with existing directory | Ask user to rename or confirm overwrite |
| >3 question rounds and confidence < 95% | Tell user the spec needs more detail |
| Probe contradicts spec (e.g., existing Phaser project) | Surface the conflict; ask user to clarify |
When the user explicitly says they want to extend an existing game:
Read these files to understand current state:
goals-plan.md — genre, variant, goal count, state bridge growthsrc/state-bridge.ts — current GameState interface fieldsAGENTS.md — project conventionsgoals/ folder listing — highest goal numberRound 1:
references/genre-templates.md)Round 2 (if 3+ new goals):
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."
goals-plan.mdPrint only the new goal folders and /goal commands. Don't re-list existing files.
/goal's job./goal's job./goal to use $imagegen./goal directly.