makelore/.opencode/skills/nianxxgame-skill/SKILL.md

name, description

name	description
nianxxgame-skill	nianXXgame skill designs, builds, debugs, playtests, polishes, and ships practical 2D or 3D web games through a lightweight, evidence-driven workflow that joins game design, project delivery, and engineering. Use Phaser 3.90 for the default 2D path or Three.js with TypeScript for an explicitly chosen 3D path.

nianXXgame skill

Turn an informal game idea or an existing 2D/3D web game project into one verified playable result at a time. Keep design intent, delivery state, and runtime behavior aligned without creating process for its own sake.

Apply the three pillars

Treat these pillars as equally important across the game lifecycle:

1. Design: define the intended player experience, rules, choices, feedback, and testable risks.
2. Delivery: constrain scope, select one player-visible result, and keep project state recoverable.
3. Engineering: implement safely in the selected engine, verify in a real browser, and preserve project conventions.

Apply only the depth relevant to the request: design-only work still needs scope and testable outcomes, while runtime work needs all three pillars. Do not let technical completion substitute for a coherent experience. When implementation is in scope, do not let design documentation substitute for a playable build.

Coordinate the game asset workflow

In a project where the user has manually configured and bound the project-owned game-assets Skill, only the responsible Agent directly uses that Skill and its Meowa adapter. Other Agents should make the workflow useful through shared artifacts:

• game-design records the visual intent, player-facing purpose, priority, and acceptance context in GDD.md and TASKS.md when a new asset gap appears.
• game-art checks Works Square/open-source sources first, then uses game-assets for a clear gap, records the generated run and license state in ASSET_PLAN.md, and submits candidates for review.
• game-development integrates only assets whose project-local review state is approved; without one, use a reversible placeholder and keep the gap visible.
• game-test-release verifies the approved asset's real path, metadata, readability, and runtime behavior, then sends defects back to game-art.

No role should call Meowa directly, expose a Key, bypass the local quota, or treat a candidate as a formal asset. The product-operations role only describes assets that are already real, approved, and evidenced; it does not enter this generation handoff.

Select the rendering path

• Keep 2D as the default: use Phaser 3.90.0 and read references/phaser3-standards.md.
• Support 3D when the user explicitly chooses or insists on it: record Rendering Mode: 3D and an exact pinned Three.js version in TECH_STACK.md, use TypeScript, and read references/web3d-standards.md.
• Do not silently force a 3D request into 2D, and do not silently migrate an existing 2D game to 3D. If the mode changes, update GDD.md, TECH_STACK.md, TASKS.md, and the relevant asset plan before implementation.
• Meowa game-assets currently generates 2D pixel/HD raster assets only. A 3D path may still use Meowa for reviewed 2D textures or UI, but models must come from user-provided, open-source, or otherwise authorized project-local sources recorded in ASSET_PLAN.md.

Route bundled resources

Load only the resources required by the work:

• Read the game-design standards before ideation, GDD work, mechanic or economy design, progression, balancing, controls, game feel, UI/feedback, accessibility, playtest planning, or design review.
• Read the Phaser 3 standards before creating or changing the 2D Phaser architecture, scenes, game objects, state, input, physics, camera, animation, audio, asset loading, lifecycle behavior, scaling, persistence, performance, tests, or build configuration. Also read it when diagnosing a 2D runtime defect.
• Read the Web 3D standards before creating or changing the 3D Three.js renderer, scene graph, camera, controls, model loading, materials, animation, disposal, resize behavior, performance, tests, or build configuration. Also read it when diagnosing a 3D runtime defect.
• Read the selected engine reference together with the design standards when a playable result combines design decisions and implementation.
• For a new game or an engine/mode change, create or update TECH_STACK.md with the selected rendering mode, exact engine version, browser target, asset formats, and verification plan before implementation.
• Copy and adapt the GDD template for a new game, a design deliverable, or ongoing development that lacks an equivalent design document. For an isolated fix with clear intent, use a concise defect note instead of creating a full GDD.
• Copy and adapt the task template when ongoing implementation, release, or handoff work needs an active queue and the project lacks an equivalent tracker. Do not create it for a standalone design deliverable or isolated fix when no continuation state is useful.

Preserve an established equivalent document instead of creating duplicates. Draft the needed content for the user; do not hand a beginner a blank template as a questionnaire. Never edit the bundled templates while working on a game.

When present, use the project's GDD and task tracker as the canonical project memory. Do not create parallel planning, findings, progress, devlog, or handoff files unless the user, repository, or host environment explicitly requires them. When such files are mandatory, keep them brief and point back to the canonical document instead of duplicating design decisions, acceptance checks, or status.

Detect the working mode

Inspect the request and project before proposing work. Confirm the rendering mode and engine from GDD.md, TECH_STACK.md, dependency metadata, imports, or runtime code. Use Phaser 3.90.0 for 2D and Three.js for an explicitly selected 3D path; do not silently migrate another engine or major version.

Choose the dominant mode:

• Concept/new: start from an idea, an empty directory, or no runnable game.
• Existing/build: extend, change, refactor, balance, or polish a runnable Phaser 3 or Three.js project.
• Bug: reproduce and repair behavior that conflicts with the intended or established design.
• Resume: continue from an active task, partial implementation, handoff, or interrupted session.

State the detected mode and current stage briefly. If evidence conflicts, resolve it by inspecting the project before asking the user.

Ask at most three high-impact questions in one decision round. Include a recommended default when useful. Infer reversible details from context and record the assumption; pause only when alternatives would materially change the game, scope, or existing user work. Translate game-development jargon into concrete player outcomes for non-expert users.

Use four adaptive stages

Treat stages as risk lenses, not approval gates. Enter the stage that matches the current goal; do not force an existing feature or isolated bug through earlier stages.

Concept

Define the smallest coherent game promise. Establish the player fantasy, audience and platform, session shape, design pillars, player verbs, core loop, win/loss or outcome flow, scope boundary, and riskiest unproven assumption. Seed the GDD only as far as needed to make the next prototype falsifiable.

Exit with one explicit prototype question and a playable acceptance target.

Prototype

Build the cheapest playable test of the highest design or technical risk. Prefer placeholder assets, exposed tuning values, and a complete micro-loop over production architecture or content volume. Test whether the intended choice, challenge, control, or feedback is legible and satisfying.

Exit by deciding to keep, revise, or discard the tested assumption, and update the GDD with evidence.

Build

Deliver vertical slices that cross input, rules, state, feedback, and outcome. Keep the game runnable after each slice. Add only the architecture and content needed by the current result, while preserving extension points supported by near-term evidence.

Exit each slice with verified acceptance checks, synchronized applicable documents, and exactly one recommended next result.

Ship

Stabilize the complete intended loop. Prioritize blockers, clarity, feel, accessibility, performance, device/browser behavior, asset and save integrity, release configuration, and regression coverage. Freeze optional scope before adding polish.

Exit only with a reproducible production build and recorded playthrough evidence.

Use the shared project workspace

Treat the project directory as the durable context shared by every Agent. At the start of work, inspect relevant existing design, task, asset, code, test, release, knowledge, and status artifacts. At the end, leave concrete progress, assumptions, evidence, risks, and recommended next work in the artifacts owned by the current Agent's system prompt.

This Skill does not assign role ownership or mandate filenames. The Agent system prompt is the sole authority for which artifacts the Agent reads and maintains. Do not create duplicate process documents when the project already has an equivalent source of truth.

Chat summaries and cross-session messages are not substitutes for project files. Do not depend on automatic dispatch. A downstream Agent should be able to reconstruct the current state by reading the project workspace.

Missing upstream artifacts are not approval gates. Inspect the project facts, proceed with the smallest safe and reversible assumption when possible, and record that assumption in the current Agent's owned artifact. Ask the user only when the missing decision would materially change the result or overwrite existing work.

Keep version context synchronized

When the project has VERSION.md and TASKS.md, read both before working. Treat VERSION.md as the authoritative current project version and TASKS.md as the shared current-version work index maintained by every Agent.

Update only tasks related to the current work: owner, status, observable acceptance, evidence summary, blockers, source artifact, and next action. Keep specialized design, asset, engineering, test, and release facts in the Agent-owned artifacts named by its system prompt; link or summarize them from TASKS.md instead of duplicating them.

When updating a role-owned Markdown artifact, synchronize its Project Version, increment its Document Revision for a material edit, and set Last Updated By to the current stable Agent id. Do not change the project version unless the Agent system prompt or the user grants version-owner authority. Otherwise record a PATCH, MINOR, or MAJOR proposal in TASKS.md with reason and affected artifacts.

Keep root artifacts focused on the current version. Historical versions belong in incremental docs/versions/<version>/ snapshots with VERSION_SUMMARY.md; do not copy unchanged artifacts merely to make an archive look complete. Archived artifacts are read-only except for explicit errata.

Check design readiness

Before editing runtime code, confirm that the current result answers:

1. What should the player perceive, decide, or accomplish?
2. What inputs, states, rules, outcomes, and feedback produce that experience?
3. What observable evidence will show that the result works and feels understandable?

For a small defect, use a reproducible failure, expected behavior, and regression check instead of expanding a full system specification. If a missing design decision would change implementation materially, resolve it in the current Agent's owned project artifact first. Otherwise proceed with the smallest reversible assumption and record it.

Honor the requested depth

Stop at design when the user asks only for ideation, GDD work, system design, balancing analysis, playtest planning, or design review. Do not scaffold or change runtime code merely because implementation could follow.

Complete design-only work when the affected design artifact is coherent, contradictions and assumptions are explicit, the next risky question is testable, and any proposed implementation has observable acceptance checks. Recommend one next step without starting it. Enter the playable-result loop only when the user requests implementation, repair, runtime verification, or release work.

Execute one playable-result loop

Repeat this loop for only the current result:

1. Inspect: read project instructions, dependency metadata, structure, existing design/task documents, relevant code, available checks, and current uncommitted work. Preserve established patterns and unrelated changes.
2. Frame: state the player-visible result, linked design intent, one to three acceptance checks, primary risk, and smallest vertical slice.
3. Prepare context: update only the current Agent's role-owned artifact needed to remove ambiguity and preserve the result for other Agents.
4. Implement: make the smallest coherent change that completes the slice. Keep tunable design values discoverable and avoid speculative frameworks.
5. Check mechanically: run the project's applicable static checks, tests, and production build. Fix new failures caused by the change.
6. Play in a real browser: launch the actual game and exercise the affected path. Do not infer playability from compilation, unit tests, or screenshots alone.
7. Observe: inspect visible behavior, controls, scene/state transitions, feedback timing, layout and scaling, console errors, and relevant edge cases. Capture concrete evidence.
8. Iterate: repair the highest-impact gap and repeat implementation and verification until acceptance checks pass or a genuine blocker remains.
9. Reconcile: update the current Agent's owned project artifacts with confirmed changes and findings; close or rescope tracked work when one exists; leave one recommended next playable result.

For the core loop, verify an appropriate version of start -> act -> receive feedback -> reach an outcome -> restart or continue. For a defect, reproduce before the fix when practical and prove the same path after it.

Never claim a result is complete when browser playtesting was unavailable. Record it as implemented but unverified, state why, and provide exact manual verification steps.

Require completion evidence

Mark a playable result complete only when all applicable evidence exists:

• each acceptance check has an observed pass;
• the affected gameplay path has been exercised in an actual browser;
• applicable automated checks and the production build pass;
• no new relevant runtime or console errors remain;
• affected input, resize, pause/resume, restart, and scene transitions behave correctly;
• applicable role-owned project artifacts match the implemented behavior;
• known limitations and unverified environments are explicit.

Report completion with: the playable result, material design decisions, changed areas, verification evidence, remaining risks, and one recommended next result. Distinguish observed facts from assumptions.

Recover interrupted work

When resuming, inspect the relevant role-owned artifacts plus project status, uncommitted changes, recent verification output, and runnable behavior before editing. Reconstruct the last confirmed checkpoint and continue from the first unmet acceptance check. Do not repeat completed work, overwrite unexplained changes, or trust stale status over runtime evidence.

If code and project artifacts disagree, preserve user work, establish what currently runs, identify the smallest discrepancy, and reconcile the current Agent's owned artifacts as part of the next verified result. If safe continuation is impossible, stop with the concrete blocker, evidence already gathered, and the smallest decision needed from the user.