swipi-workflow

name	swipi-workflow
description	Authoritative 6-phase workflow for building a playable Phaser web game from a user prompt. Use whenever the user asks Claude to "build a game", "make a game", "scaffold a game", or triggers the /swipi-new slash command. Orchestrates classification, scaffolding, GDD generation, asset generation, config wiring, code implementation, and verification.

swipi 6-phase game-building workflow

You are building a playable 2D web game from a user prompt. Work autonomously through these six phases in order. Do not skip phases or reorder them. Context discipline is load-bearing: do not read heavy template source files before Phase 5.

Plugin root (use these absolute paths for every file operation):

• Templates: ${CLAUDE_PLUGIN_ROOT}/templates/
• Docs: ${CLAUDE_PLUGIN_ROOT}/docs/

Create a todo list with TodoWrite at the very start covering all six phases, then expand Phase 5 into per-file todos once the GDD exists.

---

Phase 1 — Classify + Scaffold

1. Invoke the swipi-classify-game skill to pick one of five archetypes: platformer, top_down, grid_logic, tower_defense, ui_heavy. The classifier uses physics-first logic — do not classify by genre name.

2. Scaffold the project into the current working directory by copying these four sources in order:

   cp -r "${CLAUDE_PLUGIN_ROOT}/templates/core/." ./
   cp -r "${CLAUDE_PLUGIN_ROOT}/templates/modules/<archetype>/src/." ./src/
   mkdir -p docs/gdd docs/modules/<archetype>
   cp "${CLAUDE_PLUGIN_ROOT}/docs/gdd/core.md" docs/gdd/
   cp "${CLAUDE_PLUGIN_ROOT}/docs/asset_protocol.md" "${CLAUDE_PLUGIN_ROOT}/docs/debug_protocol.md" docs/
   cp -r "${CLAUDE_PLUGIN_ROOT}/docs/modules/<archetype>/." docs/modules/<archetype>/
   

3. Proceed directly to Phase 2. Do not read any source files yet — that happens in Phase 5.

Phase 2 — Generate the GDD

1. Invoke the swipi-gdd-schema skill for the universal 6-section GDD format.
2. Invoke swipi-module-<archetype> to load archetype-specific design rules and the template API summary.
3. Draft the GDD in memory, then write GAME_DESIGN.md at the project root.
4. Expand the todo list with per-file todos derived from GDD Section 5 (Roadmap).

Phase 3 — Assets

1. Invoke the swipi-asset-protocol skill for the asset-generation contract.
2. Produce every texture/audio asset listed in GDD Section 1 and every tilemap listed in GDD Section 4. Tilemaps do not apply to ui_heavy.
3. Read the generated public/assets/asset-pack.json so you know the exact keys for Phase 5.

Phase 4 — Config + Registration

All three files below are read-then-update:

1. src/gameConfig.json — MERGE, do not overwrite. Preserve the existing screenSize, debugConfig, renderConfig fields. Add game-specific fields from GDD Section 2. Every value uses the { "value": X, "type": "...", "description": "..." } wrapper. If the final JSON is missing screenSize, you replaced instead of merged — redo.
2. src/LevelManager.ts — set LEVEL_ORDER from GDD Section 0.
3. src/main.ts — import and game.scene.add() every game scene from GDD Section 0. Keep the existing UI scene registrations.
4. src/scenes/TitleScreen.ts — replace the placeholder title with the game's actual name.

Phase 5 — Code implementation

Use a 3-layer reading strategy. Do not invert this order.

• Layer 1 (API summary): Read docs/modules/<archetype>/template_api.md.
• Layer 2 (targeted source): Read every _Template*.ts you will copy and every Base*.ts you will extend, as identified from GDD Section 5.
• Layer 3 (implementation guide): Read docs/modules/<archetype>/<archetype>.md last, so it stays freshest in context.

Hard constraints:

• Never invent type names, hook names, or function signatures. If it is not in a source file or in template_api.md, it does not exist.
• Never modify KEEP files (Base*.ts, behaviors/*, systems/*, ui/*, utils.ts). Create new files instead.
• Always base new scenes on _Template*.ts (COPY) or Base*.ts (EXTEND).
• Always call super.create() / super.update() when overriding.
• Override visibility must match the base class — use protected override when the base is protected.

Before writing any code, emit a pre-implementation plan listing every file you will MODIFY and every file you will CREATE, with the hook/class each one uses. Re-check the plan against GDD Section 5.

Phase 6 — Verify

1. Invoke the swipi-debug-protocol skill and run every applicable checklist item.
2. npm install if needed, then npm run build — fix every TypeScript error before proceeding.
3. npm run test for headless tests.
4. npm run dev and verify the game renders.

If build fails, read the full error, open the exact file at the exact line, fix the root cause. Never guess.

---

TypeScript rules (recurring causes of bugs)

Import rule — classes are value imports, interfaces/types must use type:

// correct
import { BasePlayer, type PlayerConfig } from './BasePlayer';
// wrong — build error
import { BasePlayer, PlayerConfig } from './BasePlayer';

Config access rule — every gameConfig value is { value: X }; access via .value:

const hp = config.battleConfig.playerMaxHP.value;

Final consistency checklist (run before declaring done)

1. Asset-code consistency: every texture/audio key used in code exists in asset-pack.json with exact spelling.
2. Scene registration: every scene.start() / scene.launch() target is registered in main.ts and in LEVEL_ORDER where applicable.
3. Config wrappers: every gameConfig.json field uses { value, type, description } and every access uses .value.
4. Title screen: TitleScreen.ts displays the game's real name, not a placeholder.