TCGEngine

Use when debugging a specific SWUSim in-game bug or unexpected behavior tied to a real game (e.g. "game 2619 auto-resolves this leader ability wrong", "why did this prompt appear", "this ability should have auto-passed", "the shield popped when it shouldn't"). For reproducing and root-cause-fixing a live-game defect from its saved gamestate.

Use when starting a NEW SWU set to generate its consolidated SWUSim/docs/<set>-implement.md plan (for swusim-implement-set-plan to drive). Scans the generated card dictionaries, classifies every card, surveys for unbuilt core mechanics (hard-stops if found), then batches needs-work cards autonomy-first. Generate-only; one set abbreviation as input.

Use when implementing SWU card abilities — looks up card text, writes all DSL tests first, then self peer-reviews against the CR + game logic + card data and implements; only stops for the user on a card it can't verify to 98% alone. Supports single cards and batches.

Use when the user wants to drive a whole multi-batch SWUSim implementation plan doc (e.g. docs/<set>-complex-plan.md) to completion in one session — "run/execute the <set> plan", "work through the remaining phases". For many card batches across phases at once; for a single batch use swusim-implement-card.

Use when asked to verify a SWU set is "card complete" / review a set for implementation gaps (e.g. "is JTL card complete?", "validate the SOR set", "what's left in LOF?"). Runs two independent completeness checks — a dictionary-vs-Done-list diff AND an inverse-stub sweep that proves every trigger stub has a real handler — classifies each finding as a real gap or a false positive, and reports. Read-only validation; hand real gaps to swusim-implement-card.

Use at the end of a SWUDeck (NOT overall TCGEngine work) working session to run a short retro, capture durable lessons, and hand off cleanly. Invoke when the user says they're wrapping up, asks to "close the session", "run the retro", or asks "what were the lessons learned this session".

Use at the START of a SWUDeck (NOT overall TCGEngine) working session to get oriented — recall past gotchas/lessons, confirm the local dev environment + cross-browser verification tooling are ready, and surface in-flight work — before making changes. Invoke when the user signals they're beginning SWUDeck work ("let's work on SWUDeck", "start a SWUDeck session") or runs /swudeck-session-start.

Use before pushing a branch straight to main in this monolith — when the user asks "what does this branch touch", "what could this break", "check blast radius", or wants to confirm a change is safe for other sims before merging without a PR review. Classifies the diff against origin/main by which products/sims it can affect.

Use when creating a new design-system theme for the SWU sites — a new SharedUI/Themes/<name>.tokens.css that reskins buttons/inputs/panels/dialogs, including signature styled-button themes (chamfer / octagon / slash geometry + honeycomb/ember/scanline textures), or adding a theme to the zzDesignSystemPreview.php preview. Not for editing shared components.

Find which cards in a SWU set are reprints of earlier-set cards and add the mappings to AppCore/SWU/Overrides.php. Use when a new set is released and its reprints need to be aliased back to their earliest printing for deck stats. Takes a set code (e.g. ASH, LAW, SEC).

Bump the UILibraries cache-busting datestamp. Use when shipping UI/client changes that must reach users immediately past Cloudflare's CDN cache, or when references to Core/UILibrariesYYYYMMDD.js are stale / out of sync with the actual file. Renames the bundle to today's date and rewrites every UILibrariesYYYYMMDD reference repo-wide. Orchestrates DevTools/bump-uilibraries-cache.py.

Convert a PNG (or other Pillow-readable image) to WebP — the enforced image format for SWUStats assets. Use when adding/replacing any raster asset (board backgrounds, icons, art) that is currently a .png/.jpg, or when asked to "make this a webp". Supports a quality param (1-100, default 70), optional resize, and producing the <base>.webp / <base>-mobile.webp board pair. Orchestrates DevTools/png-to-webp.py.

Use when turning a Kling-generated .mov (an effect/keyword animation on a pure-black background) into a SWUSim counter icon — a small 60x60 animated transparent .webp. Runs the mov->transparent-webp conversion then resizes to icon size. Input is one .mov path (usually under Assets/Icons/).

Use when adding a new TCGEngine root application to the docker-compose environment (e.g. a new game). Walks through duplicating the web/mysql/phpmyadmin/redis services, assigning unique ports and env vars, and validating the new app comes up.