Make Game

Make Games

When working with a user to create a video game, reference the skills/pipelines/commands provided to help the user create a perfect pipeline for their game development.

Based on the state of the user's request, current codebase, and stage of development, choose the proper steps to take with the user to complete their request.

When to Use

Use this skill when:

• The user is brainstorming or describing a game idea (no project directory required — the idea phase exists exactly for this)
• The current working directory is a game project (has docs/, source files, or an engine config like package.json with Phaser/Three.js, a Unity Assets/, a Godot project.godot, etc.)
• The user wants to add gameplay features, fix gameplay bugs, work on assets, or iterate on game design

Do not use this skill when:

• The user's request is unrelated to game development (general web apps, CLI tools, libraries, infrastructure, data work, etc.)
• The user explicitly asks for a non-game artifact (e.g. "build me a chat app")
• The user wants a one-shot viral game from a tweet, news story, or short prompt — shipped end-to-end in a single session with no milestone planning. Use `/viral-game` instead. That pipeline is opinionated (Phaser/Three.js, here.now, Play.fun) and trades the planning rigor of this skill for ~10-minute time-to-deploy. If a /viral-game session outgrows itself (the user starts asking for milestones, ADRs, or long-term iteration), they should switch back to this skill.

Table of Contents

1. Rules 2. Phases 3. Milestones 4. Important Files 5. Templates 6. Sub-pipelines 7. Other Skills

1. Rules

• No code before plan. If docs/gameplan.md does not exist, you MUST run the idea-phase pipeline to completion — gameplan, docs/tech.md, and ADR-0001 written and user-confirmed — before creating any source files, running engine scaffolders, installing dependencies, or otherwise touching code. A detailed-sounding user prompt is not a substitute for the idea-phase questions: even if the user says "3D racing game with pixel art shaders," you do not yet know the gameplay loop, win condition, controls, scope, or target session length, and improvising those choices is the single biggest cause of refactoring later. Treat this as a hard tripwire — if you find yourself about to scaffold a project without a written gameplan the user has signed off on, stop and run the idea phase first. The clarifying-questions checklist in idea.md is the minimum bar; do not skip items because the prompt "seems clear."
• Always run the [session-start sub-pipeline](sub-pipelines/session-start.md) first when entering a session in an existing project directory. It recovers context (docs/STATE.md, docs/gameplan.md, docs/tech.md, milestones), determines the current phase, and confirms the next step with the user. Skip only if there is no project directory yet (idea-phase brand-new conversation).
• When asking the user questions, use the AskUserQuestion tool. If you can provide some recommendations as multiple choice answers, with the option for the user to provide their own answer, that would be optimal.
• When asking questions, keep them focused, clear, and detailed. If the question may have some logical answers you can think of, provide those as possible answers for the user. This will help if they want to think of a solution themselves as well since they can pull from the different options you provided to curate the perfect answer.
• If you have prior memory or experience with the user, guage their technical ability/expertise, and shape your questions around that. If they do not seem technically advanced, make sure to ask questions in a way they would understand. Offering explanations for more advanced topics along with the question so they aren't answering them blindly.
• Based on the current state of the codebase, the users request, and architectural decisions such as game engine, art style, etc. decide which phase of development the game is in, and start with the pipeline outlined for said phase. They are described in the next section.
• When scaffolding a new project, do not use your embedded knowledge of how to setup the project — many things might have changed since you were trained. Find the newest version of the documentation, or ask the user to find a link and provide it to you. Read the newest installation instructions for the frameworks/libraries you are working with, and follow them according to the stack and setup the project already has set.
• Always prefer the engine's or framework's official scaffolding command over hand-rolling files. Examples: npm create @phaserjs/game@latest for Phaser; npm create vite@latest (then npm install three) for Three.js; Unity's -createProject CLI ("C:\Program Files\Unity\Hub\Editor\<version>\Editor\Unity.exe" -createProject "<path>" -quit on Windows, /Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/MacOS/Unity -createProject <path> -quit on macOS) or Unity Hub's "New project" dialog. For Godot/Unreal, ask the user to create the project from the editor. Hand-written package.json, bundler configs, or engine entry points cause version mismatches the moment a second library is added — do not do it. If you cannot find an official scaffolder and the user cannot point you to one, ask the user to initialize the project themselves and resume the session once it's ready, rather than improvising a setup. Full guidance and per-engine examples live in scaffold.md step 3.
• If the user has a large change to anything regarding core gameplay loop, architecture, etc., ensure that the relevant documentation in the docs/ folder is updated to reflect their changes. For large architecture decisions, we should write to docs/architectural-decisions that can be referenced later with the changelogs. These changelogs must be detailed and include the reason for changing them. The docs/gameplan.md file must also be updated when these decisions are made, with referenced to the AD documents behind the changes.
• After every code change in the development phase, run the [live-iterate sub-pipeline](sub-pipelines/live-iterate.md). It is the canonical real-time verification loop (console → render_game_to_text() → advanceTime() → screenshot if visual → user check). A change is not "done" until it has been iterated on.
• Write failing tests before writing the implementation. Tests are the executable form of acceptance criteria — every checkable AC for the active milestone must have at least one test that asserts it, written first and confirmed to fail for the right reason before any implementation code is touched. Use Playwright (per /qa-game) for gameplay logic and visual baselines; unit tests for pure helpers; multi-client Playwright for multiplayer. Visual/feel AC that can't be meaningfully asserted (juice, polish) must be explicitly marked "verified by user playtest" in the milestone — never silently skipped. If the AC is too vague to write a test against, run playtest / repro first to make it checkable. Loosening a failing test to make it pass is forbidden — fix the implementation, or update the milestone AC and rewrite the test.
• Keep every session focused on a single feature. When the user's request implies more than one independent feature or change, run the scope-triage sub-pipeline before any coding: enumerate the asks, write the deferred ones to docs/backlog.md, and pick the single best balance of important and easy to ship in one focused session via AskUserQuestion. Sessions that try to carry multiple unrelated features cause context drift, make live-iterate verification ambiguous (which feature broke?), and leave milestones half-checked. Bundling features is allowed only when the user explicitly insists and acknowledges the trade-off.
• Nothing the user mentions gets silently dropped. If a feature, polish item, refactor, or open question surfaces during a session but is out of scope, it must be appended to docs/backlog.md using the shape from `templates/backlog.md`. The backlog is the single home for "later" — never rely on conversation memory or docs/STATE.md notes to remember future work. The development pipeline and milestone planning both read this file.
• When the user needs a roadmap, run [milestone planning](sub-pipelines/milestone-planning.md), don't improvise. Whenever the user asks "what's next?" / "what milestones do we need?" / "what's left to ship?" — or whenever open milestones run out before docs/gameplan.md is satisfied — derive the next 1–3 milestones from the gap between the gameplan and current state + backlog, ordered architecture-enabling first, then confirm via AskUserQuestion before writing any milestone files. Cap proposals at three: future milestones will look different once the next ones ship, so over-committing wastes planning effort. Never propose a milestone whose exit condition can't be written as "User does X → observes Y" — vague targets produce vague milestones.
• `AGENTS.md` must exist at the project root for any project past the idea phase. It is the cross-tool, unconditionally-read enforcement file that guarantees future sessions follow this skill's rules even when the skill itself doesn't auto-trigger. If you find a project past the idea phase without an AGENTS.md, run the agents-bootstrap sub-pipeline before continuing other work.
• You MUST follow the pipelines outlined by each phase when working on the project based on the phase the project is in.

Minimum-viable doc mode

If the user pushes back on documentation overhead ("just code it", "skip the docs"), do not silently abandon the doc rules — that is exactly how cross-session drift starts. Instead, downgrade to minimum-viable doc mode and tell the user you're doing so:

• One-line milestone entry (title + one-line AC) is acceptable in place of a full milestone doc.
• docs/STATE.md updates remain mandatory — even one line.
• docs/gameplan.md and docs/tech.md remain mandatory if they don't yet exist (otherwise the next session has no source of truth).
• ADRs may be deferred only if the change is _not_ a top-level architectural decision. Engine, language, and stack ADRs cannot be skipped.

The point is to compress the docs, not delete them. If the user wants no docs at all, that signals they want a different tool — say so honestly rather than running this skill in a degraded state.

2. Phases

Idea Phase

The user has an idea for a game, but no codebase or documentation around it yet. Maybe there is concept art or some sort of lore they've come up with. In this phase, you should help the user brainstorm, develop, and iron out their game idea and gameplay loop.

Pipeline

Refer to this document for the idea phase pipeline. Follow it.

Requirements for Phase Completion

• [ ] docs/ folder is created in the project directory
• [ ] docs/gameplan.md is written with detailed game information based on brainstorming and planning with the user
• [ ] docs/tech.md is written with detailed tech stack information, with the use of each library/framework included
• [ ] docs/architectural-decisions/ folder exists with 0001-engine-and-stack.md locking the engine, language, and art-style decisions

If the project directory has not been created yet, ask the user for permission to create a new project directory and write the folders/files there. Before moving to the next phase, ask the user to start a new session in the project directory so it becomes your CWD. Provide a resume prompt for the new session.

Scaffold Phase

After the idea for the game has been solidified, help the user scaffold the project. The methods used to scaffold said project will depend on the tech stack used for the project.

Pipeline

Refer to this document for the scaffold phase pipeline. Follow it.

Requirements for Phase Completion

• [ ] Initial project files exist in the project directory
• [ ] Dependencies are installed
• [ ] Game boots in the browser (or the engine's play mode), the initial scene renders, and the console is error-free
• [ ] AGENTS.md and CLAUDE.md exist at the project root (see agents-bootstrap sub-pipeline)
• [ ] A future agent can run the project with one well-known command (npm run dev, engine equivalent) without further setup

"No compilation errors" alone is not sufficient — projects often build clean and crash on boot. The smoke test in `scaffold.md` is mandatory before declaring this phase complete.

Development Phase

This phase is the longest, and possibly never ending phase. The pipeline here is extremely important, and should be applied to any and all feature work in this project. If the user is asking you to fix a bug, you can defer this pipeline to quickly fix said bug and focus on bug fixing.

Pipeline

Refer to this document for the development phase pipeline. Follow it.

There are no requirements for phase completion, as this is an active phase which possibly never ends, and the milestones within the pipeline document requirements and acceptance criteria.

3. Milestones

Within the development phase pipeline, you will use milestones as a source of truth for different large scoped tasks. These milestones live within docs/milestones/*.md.

Every milestone should include but not be limited to the following:

• Objective: The main goal of the milestone, with a detailed description of what the changes being made are.
• Scope: List of changes scoped to the task
• Acceptance Criteria: Checkbox list of sub-tasks within the milestone that must be verified and completed before the milestone can be marked as done.
• Exit Condition: The bottom line condition that must be verified by the user to have the milestone marked as complete.

You MUST ground all large changes in a milestone document, or ensure your changes are grounded in an existing milestone document. The only exceptions to this are small changes that would not require extreme planning, general bug fixes, or follow up changes that the user asks you to make, so long as they are within the scope of the milestone you're working on.

Small feature additions or changes that would not warrant a milestone may be deferred. If the changes would matter in the future, they must be documented in a milestone. You can revise milestone documents for cases like this.

At the end of implementation, you must ensure we keep milestone documentation updated and AC boxes checked off, otherwise future sessions will assume the milestones are incomplete, when they are complete. Ensure the user tests the exit condition of each milestone before moving on or marking as complete.

Rules

1. Milestones must be ordered and each one must have the required sections listed above 2. Choose the smallest milestone set that explains delivery order 3. Put architecture enabling work before UX polish 4. If milestones depend on each other, it's important to mention the order in which they must be completed within the milestone documents

Append vs spawn a new milestone

When new work surfaces during a session, decide whether to extend the current milestone or open a new one:

• Append AC to the current milestone when the work is in-scope refinement of the milestone's existing objective — clarifying behavior, tightening a check, splitting an existing AC into two checkable items.
• Spawn a new milestone when the work is out of scope for the current objective but related to the project — a new system, a new feature area, a refactor that enables future milestones. Use the Depends on: field in the new milestone's frontmatter to capture the ordering relationship.
• Open a follow-up issue (no milestone) when the work is small, isolated, and would never be planned ahead of time — a typo, a one-line fix, an obvious cleanup. These can ride on the current milestone if they're trivially adjacent.

When in doubt, prefer spawning a new milestone over inflating the current one. A bloated milestone hides progress and makes the exit condition harder to test.

4. Important Files

docs/gameplan.md

The main source of truth around the game and idea of the game. Includes gameplay loop, rules, main game idea, art style, etc.

When to read

At the start of every session. When reading through milestones. When gathering context about the game around the user's request.

When to write

When the user wants to change how the game works, when rules change, etc. This is the main source of truth for how the game should work.

docs/tech.md

The main source of truth on the tech stack.

When to read

At the start of every session. When planning out milestones and architectural decisions.

When to write

When adding new tech to the stack or changing out the core game engines/libraries/frameworks being used.

docs/milestones/*.md

Detailed milestones for different features and tasks that eventually build the game.

When to read

Prior to implementation. When users ask for you to perform changes to the codebase. Anytime you need relevant prior information to what's been done so far.

When to write

When a user asks for new features, changes, etc. that have not yet been implemented in the codebase. When the user wants a full refactor to an older milestone, etc.

You should not have to update milestones once written unless there are explicit changes requested by the user, or if you are checking off acceptance criteria.

docs/architectural-decisions/*.md

Detailed ADRs for different top-level architectural decisions. Use `templates/adr.md` when creating one. The first ADR (0001) should be created at the end of the idea phase to lock in engine / language / art-style decisions.

docs/backlog.md

Single-file, append-only catalog of every feature, polish item, refactor, or open question the user has mentioned but that was deferred out of the session that captured it. The home for "later". Created from `templates/backlog.md` the first time scope triage defers an item.

Promoted entries get a checkbox tick and a link to the milestone that absorbed them — they are not deleted. Rejected entries are struck through with a one-line reason. The history matters: future sessions need to see what was considered, when, and why it was deferred or rejected.

When to read

• Before creating any new milestone (development pipeline step 2).
• During scope-triage step 2, to avoid duplicating items.
• During session-start, to surface items the user may want to promote.
• When the user asks "what's next?" and the open milestones don't have an obvious answer.

When to write

• Whenever scope triage defers an item.
• Whenever a feature/polish/refactor surfaces mid-session but is out of scope for the current milestone.
• Whenever the user mentions an idea in passing ("oh, eventually we should…"). Capture it immediately so it isn't lost.

docs/STATE.md

Single-file session handoff. The previous session's last action, current milestone, and the next concrete step. Read first by the session-start sub-pipeline, updated at the end of any session that made progress. Use `templates/state.md`.

When to read

At the very start of every session in an existing project, before any other doc.

When to write

At the end of any session that changed code, docs, or decisions. Even one line is better than nothing — the goal is continuity for the next session.

AGENTS.md and CLAUDE.md (project root)

The cross-session, cross-tool enforcement file. AGENTS.md is read unconditionally by Cursor, Aider, Codex, Claude, and other agent tools at session start — a stronger guarantee than skill description matching. CLAUDE.md is a one-line pointer to AGENTS.md so the two files never drift.

Generated by the agents-bootstrap sub-pipeline using `templates/agents.md`.

When to read

AGENTS.md is read by other agents — you don't need to read it during a normal make-game session because the source of truth lives in docs/. Read it when auditing for drift, when the user reports an outside agent ignored the rules, or before regenerating it.

When to write

• End of the scaffold phase (mandatory).
• During the doc-backfill branch of session-start, once gameplan.md and tech.md exist.
• After a top-level stack or architecture change — regenerate.
• When the doc-drift audit flags AGENTS.md as stale.

Every architecture rule in AGENTS.md must also live in docs/tech.md or an ADR. AGENTS.md is a reflection of the source-of-truth docs, not its own source.

5. Templates

When creating any of the docs the skill mandates (gameplan.md, tech.md, milestones, ADRs, STATE.md), copy the structure from `templates/` rather than improvising. Consistent structure across sessions is the highest-leverage anti-drift mechanism in this skill.

6. Sub-pipelines

These sub-pipelines can be used for individual steps during development, such as asset genration, lore building, gameplay loop building, research, etc.

Refer to this document to see all currently available sub-pipelines. Use them when necessary only if the task calls for it. Always refer to sub-pipelines to see if there's one available to use before starting your own pipeline of work.

7. Other Skills

It may be useful to install other skills to the project. There are many other skills in the game-creator Skill suite and plugin that can interlace with this skill.

Refer to this document to see skills you can install to the project directory that will help with development, planning, asset generation, etc based on what project you're working on.

Development phase

The longest, possibly never-ending phase. The pipeline below applies to every feature addition, change, or refactor while the project is in this phase.

For unambiguous bug fixes, defer to the focused bug-fix sub-pipeline rather than running this full pipeline. For vague gameplay feedback ("feels floaty", "combat is boring"), run playtest / repro first to convert it into a checkable AC.

When to use

• Project has source files and dependencies installed (development phase confirmed by session-start)
• The user has asked for a feature, change, or improvement
• An open milestone has unchecked acceptance criteria

Inputs

• docs/STATE.md (last session handoff)
• docs/gameplan.md (gameplay source of truth)
• docs/tech.md (stack source of truth)
• docs/milestones/ (current and pending milestones)
• docs/backlog.md (deferred features and open questions from past sessions)
• The user's request, however phrased

Steps

1. Ground the task or feature

• Read relevant docs/gameplan.md and docs/tech.md sections.
• Read docs/backlog.md (or note that it doesn't exist yet). Items relevant to the current request should be linked from — not duplicated by — the new milestone.
• Identify whether the task belongs to an existing milestone in docs/milestones/.
• Identify whether the task deliberately deviates from existing ADRs.
• Identify whether the task changes core gameplay, the gameplay loop, rules, or state-machine contracts.

1a. Triage scope before going further

If the user's request implies more than one independent feature, change, or "while you're in there" addition — or if it is open-ended brainstorming — run the scope-triage sub-pipeline now, before step 2. The output is exactly one chosen feature plus a docs/backlog.md updated with everything else. The rest of this pipeline operates on that single chosen feature.

If the request is already a single, scoped feature that fits the current milestone, skip to step 2.

2. Update relevant documentation before coding

If the task introduces new scope:

• Add or revise milestone acceptance criteria in docs/milestones/. Use the append vs spawn rule from SKILL.md §3.
• Add or revise gameloop / rules in docs/gameplan.md.
• Add or revise stack changes in docs/tech.md.
• Add an ADR in docs/architectural-decisions/ for any top-level architectural change.
• If docs/backlog.md items influenced (or were promoted into) this milestone, tick their checkboxes and append → milestone NN-<slug>.md. The trail must be preserved, not deleted.

If the work does not fit an existing milestone, create a new milestone document before coding. Re-read `docs/backlog.md` first so you don't duplicate or contradict deferred items. If you're authoring more than one milestone in this step, or the user has asked for a roadmap rather than a single feature, switch to the milestone-planning sub-pipeline — it handles gameplan-delta analysis, dependency ordering, and proposal confirmation so the milestones you write actually move the gameplan forward. If the user has invoked minimum-viable doc mode (SKILL.md §1), at least add a one-line milestone entry — never skip the doc step entirely.

3. Write failing tests first

Before changing implementation code, write the tests that will prove the milestone's acceptance criteria are satisfied — and watch them fail. Tests are the executable form of AC; if a piece of AC has no corresponding test, it isn't really checkable. The work for this step is "done" when:

• Every checkable AC for the active milestone has at least one test that asserts it.
• Each new test runs and fails for the right reason (asserts the missing behavior, not a typo, missing file, or unrelated error). Run the test suite and inspect the failure message — a green-from-the-start test or a test that fails with ModuleNotFoundError is a bug in the test, not a baseline.
• The failing tests are committed (or at least staged) so the red-to-green transition is visible in diff history.

What to write where:

• Gameplay logic, state transitions, scoring, collision rules, win/lose conditions → Playwright tests using the patterns in /qa-game (the game-test fixture, render_game_to_text() for state assertions, advanceTime() / page.clock for deterministic timing). These are the default and cover almost everything.
• Pure functions that don't depend on the game runtime (math helpers, formatters, RNG wrappers) → unit tests next to the source if the project already has a unit test runner. Don't introduce a new test framework just for one helper.
• Visual-only changes (palette tweaks, particle counts, juice, transitions) → a Playwright screenshot test that captures the current baseline before the change, then a second assertion that the post-change screenshot differs (or matches a reviewed new baseline). For polish where "differs" isn't a meaningful assertion, fall back to live-iterate (step 5) and explicitly note in the milestone that the AC is verified by user playtest, not automated test — do not silently skip the test step.
• Multiplayer behavior → tests that boot two clients via Playwright and assert state convergence. The add-multiplayer skill has scaffolding patterns.

If the milestone AC is too vague to write a test against ("combat should feel snappy", "menus should be polished"), stop and run playtest / repro to convert the AC into something checkable before continuing.

If the project has no test harness yet, run /qa-game to set one up before writing the milestone's first test — do not hand-roll Playwright config when the skill exists.

4. Implement the smallest correct change

• Implement only behavior outlined by the relevant milestone — the goal is to turn the failing tests from step 3 green.
• Avoid introducing top-level architecture changes without consulting the user first and updating docs.
• Preserve game rules captured in docs/gameplan.md.
• If blocked, surface possible unblock paths to the user rather than guessing.
• Run the test suite frequently. The transition from red → green on the AC tests is the primary signal that the implementation is on track. If a test goes green before you intended (because something else covered it), inspect — do not assume the milestone is done.
• Do not edit a failing test to make it pass unless the test itself is wrong. If you find yourself loosening assertions, the implementation is still incomplete or the AC needs to change first (update the milestone, not the test).

Task → slash command quick reference. Match the work to an installed user-invocable skill rather than improvising. See `useful-skills.md` for the full menu.

5. Live iterate (mandatory after every code change)

Run the live-iterate sub-pipeline. Do not skip — a change is not "done" until it has been verified through the live loop. This is the primary mechanism for tight, real-time feedback with the user. Live-iterate complements the automated tests from step 3: tests prove the AC; live-iterate catches the things tests can't see (feel, juice, surprise interactions, console warnings, regressions in adjacent features).

6. Verify against the milestone

Before considering the task complete:

• All AC tests written in step 3 are green. Run the full suite, not just the new tests — confirm no regressions.
• Milestone docs reflect the new state, with AC checkboxes ticked off. Each ticked AC should reference the test that covers it (or be explicitly marked "verified by user playtest" if it's a visual/feel AC).
• Any deliberate deviations are documented and were called out to the user.
• The exit condition is testable by the user (or has been tested live during step 5).

7. Hand back to the user

If the change includes visual or logical behavior the user can experience, give them clear, ordered testing instructions — one workflow at a time. Pair this with the screenshot or state snapshot from step 5 so they have something concrete to compare against. Use AskUserQuestion when the next decision is multiple choice. Mention which AC are now covered by automated tests so the user knows which behaviors are protected from regression and which still rely on manual playtest.

If the user surfaces new feature ideas or adjacent improvements during this hand-back ("oh, while we're at it, can you also…"), do not silently bundle them into the current session. Append them to docs/backlog.md immediately, then run scope triage at the start of the next session. The current session ends when its single feature is verified.

8. Update `docs/STATE.md`

Even one-line updates are better than nothing. Capture last action, current milestone, next step, and any blockers.

Outputs

• New tests committed (red → green) covering every checkable AC for the milestone
• Code change scoped to the milestone
• Full test suite passing, no regressions
• Updated milestone (AC ticked, each tick referencing the test that covers it)
• Live-iterate verdict (state snapshot or screenshot)
• Updated docs/STATE.md

Exit criteria

• The change satisfies the milestone AC the user agreed to (or the user has explicitly accepted a deviation).
• Every checkable AC has a corresponding green test; AC verified by user playtest are explicitly marked as such in the milestone.
• Full test suite green; console is error-free; no adjacent regressions surfaced in step 5.
• docs/STATE.md reflects the new state.
• The user has clear next-step testing instructions and knows which behaviors are now regression-protected.

Figuring out what to work on next

When the user asks "what's next?":

1. Open milestone docs in docs/milestones/. 2. Pick the earliest milestone with incomplete acceptance criteria. 3. Within the milestone, choose the smallest missing requirement that unlocks later work. 4. Cross-check against the codebase. If AC has drifted from reality, update the AC and return to step 2. 5. If all open milestones are complete (or only have polish AC remaining) and docs/gameplan.md is not yet satisfied, hand off to the milestone-planning sub-pipeline to derive the next 1–3 milestones from the gameplan delta + backlog. Do not invent scope here. 6. If docs/gameplan.md is satisfied (loop, rules, win/lose, player goals all delivered), surface the highest value × ease item from docs/backlog.md via AskUserQuestion and ask the user whether it should be promoted into a stretch milestone or whether the gameplan itself needs to grow.

Priority rules:

• First, incomplete milestone acceptance criteria.
• Then, architecture-enabling work.
• Then, gaps that unblock core gameplay loops.
• Then, milestones derived from the gameplan delta via milestone planning.
• Then, the best value × ease item from docs/backlog.md.
• Defer polish unless it closes a milestone exit condition.

Always present the chosen next step to the user via AskUserQuestion with one or two backlog runners-up as alternatives, so the user owns priority.

Idea phase

Help the user shape a fuzzy idea into a concrete plan: gameplay loop, art style, engine choice, and a written docs/gameplan.md + docs/tech.md + first ADR. This phase ends when those docs exist and the user is ready to scaffold.

When to use

• The user has a game idea but no codebase yet
• A project directory exists but docs/gameplan.md is missing
• The user wants to revisit the core concept (rare — usually triggers an ADR rather than a re-run of this phase)

Inputs

• The user's idea, however vague
• (Optional) Concept art, lore, mood references the user provides
• The user's prior experience with engines, languages, art tooling

Steps

Hard rule: you must ask the user — and receive answers for — every item in the checklists below before writing docs/gameplan.md. A detailed-sounding initial prompt does not exempt any item. If the user already answered something in their opening message, restate your understanding back to them and confirm before checking it off; do not assume.

>

Use AskUserQuestion (or, if your tool harness lacks it, plain numbered questions and an explicit "wait for answers before continuing" pause). Where reasonable, offer 2–4 multiple-choice options plus an "other / let me explain" escape — concrete options help the user sharpen vague intuitions.

1. Discuss the gameplay loop

This is the highest-leverage step in the whole skill. Misalignment here causes the most refactoring later. You MUST get an explicit answer for each of:

• [ ] Core loop verbs — what does the player do moment-to-moment? (e.g. "drive, drift, overtake, finish lap")
• [ ] Session shape — single run? story campaign? endless? roguelike with permadeath? board-like turns?
• [ ] Win / lose / progression condition — how does a session end, and what carries between sessions?
• [ ] Target session length — 60 seconds? 5 minutes? 30 minutes? affects scope and pacing.
• [ ] Hook / differentiator — one sentence on why this isn't just "another <genre> game."
• [ ] Anti-goals — what is this game explicitly not? (Helps reject scope creep later.)

2. Discuss the art style

You MUST get an explicit answer for each of:

• [ ] Perspective / dimensionality — 2D top-down, 2D side-scroller, 2.5D, 3D first-person, 3D third-person, isometric, text-based.
• [ ] Visual style — pixel art, low-poly, hand-drawn, photoreal, vector. If hybrid (e.g. 2D sprites in 3D world, billboarded), confirm specifics: facing rules, shader expectations, post-processing.
• [ ] Palette / mood — bright/saturated? muted? high-contrast? reference games or images if the user has them.
• [ ] Asset sourcing — user makes their own? AI-generated placeholders OK? store-bought packs? code-only primitives during prototyping?
• [ ] Audio direction — chiptune? orchestral? procedural Web Audio? silence-for-now? (Light touch here, but ask — silence is a valid answer; "haven't thought about it" is not.)

3. Discuss controls and scope

Often skipped, often the source of mid-development pivots. You MUST get an explicit answer for each of:

• [ ] Input model — keyboard, mouse, touch, gamepad, mixed? Mobile-friendly required?
• [ ] Control scheme specifics — for the core verb (drive, jump, attack, etc.), what does the input feel like? arcade-floaty? sim-realistic? one-button?
• [ ] Scope ceiling — how many levels / tracks / characters / enemies for v1? "Ship a vertical slice with one X" is usually right; "ten of everything" is usually wrong.
• [ ] Multiplayer? — single-player only? local co-op? online? (Affects engine and architecture from day one.)

4. Discuss the engine and stack

Use answers from steps 1–3 to narrow engine candidates. Also factor in the user's existing experience — a JS/TS dev with no game-engine background is usually better off with Phaser or Three.js than starting fresh in Unity. Present 2–3 options with pros/cons (language, GUI editor, ecosystem, asset pipeline) and let the user choose. Confirm:

• [ ] Engine + language chosen with the user (not assumed).
• [ ] Test framework (Playwright for browser games is the default in this skill).
• [ ] Deployment target — browser, Steam, mobile store, itch.io? Affects engine choice.

5. Solidify the plan

Resolve any open questions, then write the plan. The plan must include:

• Pitch — 1–2 sentences with a hook
• Core gameplay loop — start to finish, named verbs
• Game rules — only those a player or developer must know
• Art style — perspective, palette, mood, references
• Tech stack — engine, language, libraries, test framework
• Open questions — anything still unresolved

Write this to docs/gameplan.md using the doc skeleton. Write the stack to docs/tech.md using its skeleton. Create docs/architectural-decisions/ and write 0001-engine-and-stack.md using the ADR skeleton — locking engine/language/art-style here is the highest-leverage anti-drift act in the whole project.

6. Hand off to scaffold phase

If the project directory does not exist yet, ask the user for permission to create it, then write docs/ there. Tell the user to start a new session in that directory and provide a short prompt to resume from. Do not start scaffolding from a different working directory.

Outputs

• docs/gameplan.md
• docs/tech.md
• docs/architectural-decisions/0001-engine-and-stack.md
• (If new directory) the project directory with docs/ populated
• A handoff prompt for the next session

Exit criteria

• All four bullets above exist on disk
• The user agrees the gameplan reflects their idea
• The user knows the next step is scaffolding (and, if they need to switch directories, has the resume prompt)

Scaffold phase

After the idea has been solidified, scaffold the project. The exact steps depend on the tech stack chosen in docs/tech.md.

When to use

• Idea phase exit criteria are met (docs/gameplan.md, docs/tech.md, ADR-0001 exist)
• Project source files do not yet exist, or dependencies are not installed
• The user is ready to start building

Inputs

• docs/gameplan.md (game definition)
• docs/tech.md (engine, language, libraries, tooling)
• docs/architectural-decisions/0001-*.md (locked engine/language/art-style)
• The current working directory

Disambiguation: two kinds of "templates"

Two folders in this plugin both contain the word templates. They are different things — do not confuse them:

• Project starters at the repo root templates/ (e.g. templates/phaser-2d/, templates/threejs-3d/). Runnable starter projects to clone or scaffold from. _This step uses these._
• Doc skeletons at skills/make-game/templates/ (gameplan.md, tech.md, milestone.md, adr.md, state.md). Empty markdown shells the skill mandates. _Used in idea/development phases for writing docs._

When this pipeline says "starter," it means the first; when it says "doc skeleton," it means the second.

Steps

1. Re-read `docs/tech.md`

Confirm the engine, language, and tooling. The scaffold method follows directly from this file.

2. Prefer `/use-template` if a starter matches and `/use-template` is available

If templates/phaser-2d/ or templates/threejs-3d/ (or any other starter in the repo root templates/ folder) matches the project's stack, run /use-template <starter-id> [project-name]. This is a ~10-second copy + npm install and avoids latent setup bugs from improvised scaffolding.

Use /use-template when:

• Stack matches a starter (Phaser 4 / Three.js browser games)
• The project does not need a custom build pipeline

Skip to step 3 when:

• No starter matches the chosen engine (Unity, Unreal, Godot, custom stacks)
• The project requires a non-standard build setup

3. If no starter matches, find the engine's official scaffolding tool

Do not scaffold by hand. Hand-rolled package.json, vite.config.js, tsconfig.json, engine entry points, etc. drift from the framework's current expectations and cause version mismatches the moment a second library is added. The correct move is always to use the engine/framework's official scaffolding command (or its official editor flow).

Order of preference:

1. The engine's official `create` / `init` / `-createProject` command. Search the official docs (or ask the user for a link) for the _current_ recommended command — installation patterns shift between versions, so do not rely on embedded knowledge. 2. The build tool's official scaffolder when the engine is "just a library" loaded into a JS project (e.g. Three.js). Use npm create vite@latest (or the framework's recommended bundler init), then npm install three (or the relevant library) on top. Do not hand-write Vite/Webpack/Rollup config when an official template exists. 3. Ask the user to run the editor/installer themselves when the engine has a GUI-driven setup or requires a license/seat (Unity Hub, Unreal launcher, Godot editor's "New Project" dialog). Provide exact menu steps and the directory you want the project created in, then wait for them to confirm before continuing.

Examples of correct scaffolding commands (always re-check the official docs for the current syntax before running):

• Phaser 4 (browser): npm create @phaserjs/game@latest (also available via npx @phaserjs/create-game@latest, yarn create @phaserjs/game, pnpm create @phaserjs/game@latest, bun create @phaserjs/game@latest).
• Three.js (browser, library on top of a bundler): npm create vite@latest → pick the appropriate template (e.g. vanilla, vanilla-ts, react) → cd <project> → npm install three. Do not write vite.config.js from scratch unless a non-default plugin is required.
• Unity (CLI project creation):
• Windows: "C:\Program Files\Unity\Hub\Editor\<version>\Editor\Unity.exe" -createProject "C:\path\to\NewProject" -quit
• macOS: /Applications/Unity/Hub/Editor/<version>/Unity.app/Contents/MacOS/Unity -createProject ~/path/to/NewProject -quit
• Linux: ~/Unity/Hub/Editor/<version>/Editor/Unity -createProject ~/path/to/NewProject -quit
• If the Unity version, Hub install path, or license is unknown, ask the user to create the project from Unity Hub's "New project" dialog instead.
• Godot: ask the user to create the project from the Godot editor's Project Manager. The CLI godot --headless workflow is fragile across versions; the editor flow is the supported path.
• Unreal: ask the user to create the project from Unreal Engine's Project Browser. Do not attempt CLI scaffolding.

4. Scaffold the project

• Never roll your own configuration when an official scaffolder exists. Hand-written configs are the #1 source of version-mismatch bugs (TypeScript ↔ bundler, engine ↔ runtime, plugin ↔ build tool). Run the official command and let it generate package.json, lockfile, build config, entry point, and .gitignore.
• Never write configuration files that the framework auto-generates — let the tool generate them, then commit them.
• For files you must write yourself, copy from the framework's _current_ official example before improvising.
• For GUI-editor scaffolds: produce step-by-step instructions and, if the project ends up in a different directory, give the user a follow-up prompt to start a new session there. Do not proceed to step 5 until the user confirms scaffolding finished and you can `ls` the generated project files.
• If you cannot find an official scaffolder _and_ the user cannot point you to one, stop and ask the user how they want to initialize the project rather than improvising a hand-rolled setup.

5. Set up asset and binary conventions early

Run the asset-pipeline sub-pipeline once during scaffold. Establishing folder layout, naming, and Git LFS now is much cheaper than retrofitting later.

6. Smoke test

Boot the game in the browser (or the engine's play mode). Confirm:

• No build errors
• No console errors at startup
• The initial scene renders something — even a placeholder cube or empty scene with the camera live counts

If the smoke test fails, fix it before declaring scaffold done. A "compiles clean but crashes on boot" state is the most common scaffold-phase trap.

7. Bootstrap `AGENTS.md` and `CLAUDE.md`

Run the agents-bootstrap sub-pipeline. This produces the project-root files that enforce make-game rules across every future session and every agent tool. Do not skip — it's the strongest cross-session enforcement mechanism in the skill, and it's much cheaper to write now than to retrofit later.

8. Update `docs/STATE.md`

Phase: scaffold → development. Set the next step to the first AC of milestone 01.

Outputs

• Initial project files committed
• Dependencies installed
• Asset folder layout in place
• Boot smoke test passing
• AGENTS.md and CLAUDE.md at project root (filled, no placeholders)
• docs/STATE.md flipped to development phase

Exit criteria

• Game boots in browser (or engine play mode); initial scene renders
• No console errors
• AGENTS.md exists at the project root and is filled in
• CLAUDE.md points to AGENTS.md
• A future agent can run the project with one well-known command (npm run dev, engine-specific equivalent) without further setup

Agents bootstrap

Generate the project-root AGENTS.md (and CLAUDE.md pointer) that enforces the make-game skill rules across every future session and every agent tool. Run once at the end of the scaffold phase, and again whenever the stack or core architecture changes.

AGENTS.md is a cross-tool standard read unconditionally by Cursor, Aider, Codex, Claude, and others — it's a stronger enforcement guarantee than skill description matching.

When to use

• End of the scaffold phase, before flipping docs/STATE.md to development
• During the doc-backfill branch of session-start, once gameplan.md and tech.md exist
• After a top-level stack or architecture change (new engine, new state-machine pattern, new mandatory file convention) — regenerate
• When the doc-drift audit flags AGENTS.md as stale

Inputs

• docs/gameplan.md — pitch, genre, gameplay loop
• docs/tech.md — engine, language, libraries, tooling, package manager, dev/test/build commands
• docs/architectural-decisions/0001-*.md — locked engine/language/art-style
• (Optional) any project-specific architecture rules already documented

Steps

1. Confirm the inputs exist. If docs/gameplan.md or docs/tech.md is missing, stop and run the appropriate phase pipeline first. Do not synthesize an AGENTS.md from guesses.

2. Copy the template. Start from `templates/agents.md`. Do not improvise structure.

3. Fill the project overview from docs/gameplan.md and docs/tech.md:

• Title, pitch, genre, engine + version, language, target platform.

4. Fill the architecture rules based on the engine. Defaults:

• Phaser 3 / Three.js (browser): EventBus singleton, GameState singleton, Constants.js, window.render_game_to_text(), window.advanceTime(ms). These are mandatory for the live-iterate loop and must be called out.
• Unity: ScriptableObject for shared state; UnityEvent or signal-bus for cross-component messaging; Constants/Settings as ScriptableObjects; expose a debug state-dump method on a singleton MonoBehaviour for agent inspection.
• Godot: Autoload singletons for state and event bus; Globals script for constants; _unhandled_input discipline; expose a debug state_to_text() on a global node.
• Other / custom: ask the user what patterns the project will use, write them down, and add an ADR if no architecture-pattern ADR exists yet.

Rule of thumb: every architecture rule in AGENTS.md should map to either an ADR or a clear convention captured in docs/tech.md. If it can't, surface it to the user before writing it.

5. Fill stack-specific commands from docs/tech.md tooling section:

• Dev server, tests, build, lint/format. Use the exact commands the project uses — copy from package.json scripts, the engine's run target, etc. Mark "n/a" rather than inventing a command.

6. Confirm with the user before writing. Show the filled-in file in chat. Get explicit go-ahead. This file will be the front door for every future session — getting it right is worth a confirmation.

7. Write `AGENTS.md` to the project root. Stamp the Last regenerated field with today's date and your agent identity (e.g. 2026-05-04 by Claude / make-game scaffold).

8. Write `CLAUDE.md` to the project root with a single line:

   > This project follows AGENTS.md. See ./AGENTS.md.

Do not duplicate content. A pointer file avoids drift between the two.

9. Commit both files in a single commit titled chore: bootstrap AGENTS.md and CLAUDE.md (or follow the project's commit conventions if different).

Outputs

• AGENTS.md at the project root, fully filled in (no remaining <placeholder> text)
• CLAUDE.md at the project root with the one-line pointer
• Both committed
• Confirmation in docs/STATE.md that the bootstrap ran (one line under "Last action" is enough)

Exit criteria

• AGENTS.md exists at project root and contains no unfilled placeholders
• CLAUDE.md exists and points to AGENTS.md
• Every architecture rule listed in AGENTS.md is also captured in docs/tech.md or an ADR — no rule lives only in AGENTS.md
• The user has approved the file content
• A future agent opening this project finds AGENTS.md first and can act on it without further setup

Asset pipeline

Conventions and flow for adding, organizing, and swapping game assets (art, audio, fonts, models, shaders, data).

When to use

• Adding any new asset to the project
• The user wants to swap AI or placeholder assets for final art
• Asset folders are getting messy
• Setting up a new project (run during scaffold phase to establish conventions early)

Inputs

• docs/tech.md — engine determines folder conventions
• docs/gameplan.md — art style determines what asset categories are expected
• The asset(s) being added or replaced

Steps

1. Use the engine's expected asset layout. Unity uses Assets/, Unreal uses Content/, Godot uses res://, web/JS projects typically use public/assets/ or src/assets/. Match what the engine expects — do not invent a layout. 2. Use category subfolders. Standard categories:

• art/{sprites,textures,models,vfx}
• audio/{sfx,music,vo}
• fonts/
• shaders/
• data/ (configs, JSON, balance tables)

Create only what's needed. Don't pre-create empty category folders. 3. Apply the project naming convention. Default: <category>_<subject>_<variant>.<ext> — for example sfx_jump_01.wav, sprite_player_idle.png, tex_grass_tileable.png. Lowercase, snake_case, no spaces. If the project already has a different convention in use, follow that and note it in docs/tech.md. 4. Tag placeholders unambiguously. Any AI or temporary asset gets a _placeholder suffix or lives in art/_placeholder/. This makes the "swap to final" step trivially greppable later. 5. Configure binary storage if needed. For projects with binary assets >1MB or more than ~50 binary files: set up Git LFS and add the relevant patterns to .gitattributes. Do this once per project, early — retrofitting is painful. 6. Capture import settings as code or data where possible. Unity .meta files, Unreal asset properties, Godot .import files — commit them. Do not rely on agents or users reconfiguring import settings each time an asset is added. 7. Update `docs/gameplan.md` if a new asset category is being introduced (e.g. first time adding voice-over or shaders). This signals to future sessions that the category is expected.

Outputs

• Asset(s) added in the correct folder with the correct name
• LFS configured if it wasn't already
• (Optional, on first run) docs/assets.md capturing conventions if the project doesn't already have them documented in docs/tech.md

Exit criteria

• The asset is loadable in-engine without further setup
• A future agent can find the asset by following the naming convention without asking the user
• Placeholders are clearly distinguishable from final art

Bug fix

A focused pipeline for fixing reported bugs. Use this instead of the full development phase pipeline only when the bug is unambiguous and small in scope.

When to use

• The user reports unexpected behavior
• A test or playtest surfaced a regression
• An exception or crash is reproducible

Inputs

• A bug description from the user (may be vague)
• Access to the relevant code

Steps

1. Get a repro. If the description is vague, run the Playtest / repro sub-pipeline first. Do not start fixing until you can describe the bug as: given <state>, doing <action> produces <wrong result> instead of <right result>. 2. Locate the smallest scope of the bug. Read the relevant module(s). Do not refactor surrounding code on the way through. 3. Confirm root cause before changing code. Especially for timing, physics, and state bugs, the visible symptom is often distant from the cause. State your hypothesis to the user first. 4. Apply the minimal change. No collateral cleanup. No new abstractions. No "while I'm here" edits. 5. Verify the repro is gone. Run the exact repro steps from step 1. If you cannot run them yourself, give the user a clear set of steps to run. 6. Regression check. Look at code that touches the same state or system and confirm you haven't broken it. If a test exists for the affected behavior, run it. 7. Decide if a milestone update is needed. Most bug fixes do not warrant milestone changes. If the bug reveals a flawed AC or a missing exit condition in an existing milestone, update that milestone.

Outputs

• A code change scoped to the bug
• (Optional) A new regression test if the system already has tests
• (Optional) An updated milestone AC if the bug exposed a documentation gap

Exit criteria

• The original repro no longer reproduces
• No adjacent behavior is broken
• The user has been told what to test

Doc drift audit

Verify the docs/ folder still reflects what the code actually does. Run periodically, or when the user asks "is anything stale?".

When to use

• After several milestones have closed without a doc review
• Before starting major feature work where you need to trust the docs
• The user reports the docs feel out of date
• Before pitching the game externally or onboarding a collaborator

Inputs

• All of docs/
• The current codebase

Steps

1. Cross-check `docs/gameplan.md` rules vs code. Pick each rule in the gameplan. Find where it's enforced in code. Flag any rule with no enforcement, and any rule in code with no doc. 2. Cross-check `docs/tech.md` vs the actual stack. Read package manifests / project files. Flag any library used in code but missing from tech.md, and any library in tech.md no longer in use. 3. Audit milestones.

• Any milestone with all AC checked but exit condition unverified → flag.
• Any milestone marked open where the work appears done in code → flag.
• Any milestone older than the current one with no progress → flag for cancellation or revision.

4. Audit ADRs. For each ADR, find the code it governs. If the code now violates the ADR, either the ADR is wrong or the code is. Flag, do not silently reconcile. 5. Cross-check `AGENTS.md` against `tech.md` and the codebase. Confirm:

• Engine, language, and platform fields match tech.md.
• Stack-specific commands (dev, test, build, lint) match the project's actual scripts/targets.
• Architecture rules listed in AGENTS.md are still in force in the code.
• The "Last regenerated" date is not absurdly old relative to the most recent stack ADR.

If AGENTS.md is missing entirely on a project past the idea phase, flag it as a top-priority drift item and recommend running the agents-bootstrap sub-pipeline. 6. Write a drift report to the user. Group findings as:

• Stale — doc is behind code
• Aspirational — doc is ahead of code
• Contradiction — doc and code actively disagree

7. Get user direction on each finding before editing docs. Drift resolution is opinionated — the agent does not silently rewrite history.

Outputs

• A drift report (delivered in chat, or written to docs/drift-report-<YYYY-MM-DD>.md if the user wants it persisted)
• Doc edits, only after user direction

Exit criteria

• Every drift finding has a user decision: fix doc, fix code, or accept
• (Optional) Docs marked "current as of <date>" if the user wants that signal

Live iterate

The canonical post-edit verification loop during the development phase. Run after every meaningful code change so changes are validated before handing the keyboard back to the user. This is the primary mechanism for tight, real-time feedback between agent and player.

When to use

• A code change has just been made during the development phase
• A milestone implementation step has been completed
• A bug fix has been applied (use this and the repro from bug-fix.md)
• The user has asked "did that work?" or "can you check?"

Do not skip this loop. A change is not "done" until it has been iterated on. If the dev server is not running, start it first.

Inputs

• A running dev server (e.g. npm run dev) reachable at a known URL
• Project exposes window.render_game_to_text() and window.advanceTime(ms) per the parent project's architecture rules. If they are missing, add them as part of the change before continuing — they are mandatory for this loop.
• The change just made (file paths + intent)
• The most relevant acceptance criterion or bug repro from the milestone or bug report

Steps

1. Confirm the dev server is live. If it isn't, start it (npm run dev or equivalent for the engine) and wait for the ready signal. Do not assume HMR caught the change — for non-HMR setups (production build, some frameworks), force a reload.

2. Check console errors first. Open the page (or use the existing Playwright session) and read the browser console. Any uncaught error means stop and triage — do not move forward to behavior checks while errors are present.

3. Read the game state without pixels. Call window.render_game_to_text() and inspect the returned JSON. This is faster, cheaper, and more reliable than screenshots for verifying state-shape changes (mode, score, entity counts, player position). Quote the relevant fields back to yourself.

4. Step time deterministically when needed. For changes that depend on time-based behavior (physics, animations, timers, AI), use window.advanceTime(ms) to step the simulation in known increments. Re-read render_game_to_text() after each step. For Playwright-driven verification, prefer page.clock.install() + runFor() for frame-precise control.

5. Drive input via the iterate client (optional but recommended for input-driven changes). Run node scripts/iterate-client.js --url <dev-url> --actions-json '<actions>' from the repo root to play scripted input, capture screenshots, dump state, and surface console errors in one pass. See scripts/example-actions.json for the action shape.

6. Take a screenshot if the change is visual. Save it under output/iterate/<YYYY-MM-DD>-<short-tag>.png (or the project's existing screenshot location). Compare to a prior screenshot if one exists for the same scene.

7. Regression-check adjacent state. For every system that shares state with the changed code, run a one-action smoke test: does the score still increment? Do collisions still fire? Does restart still reset cleanly? This catches the "while I'm here" class of regression early.

8. Decide the verdict. One of three outcomes:

• Verified — change matches the AC, no regressions, no console errors. Move on.
• Off-target — change runs but doesn't match the AC. Diagnose, edit, re-loop. Do not declare done.
• Broken — console errors or crashes. Stop, triage, fix. Do not paper over with try/catch.

9. Hand back to the user with a focused question. Don't dump the whole state object — give a one-line verdict, link the screenshot if visual, and ask one specific question. Examples:

• "Jump apex now peaks at 0.38s (target was ≤0.4s). Try it — does the landing feel right, or still floaty?"
• "Score increments correctly but the HUD doesn't redraw until the next frame. Want me to fix the redraw, or is the one-frame delay acceptable?"

Use the AskUserQuestion tool when the answer is multiple choice.

Outputs

• A console-clean game running at the dev URL
• A render_game_to_text() snapshot (in chat or saved alongside the screenshot)
• (If visual) A screenshot saved to output/iterate/
• A one-line verdict and a single targeted question for the user

Exit criteria

• Console is error-free
• render_game_to_text() reflects the expected state for the change
• The relevant AC or bug repro is satisfied (or explicitly deferred with the user's agreement)
• The user has been handed a clear, narrow question — not a wall of state

Milestone planning

Use this sub-pipeline when the user needs help deciding which milestones to author next based on the gap between docs/gameplan.md (where the game is going) and the current state (open milestones + the codebase + docs/backlog.md). Output: a small, ordered set of milestone proposals that the user can confirm before any files are written.

This is a distinct activity from scope-triage:

• Scope triage narrows a single user request into one in-scope feature.
• Milestone planning looks across the whole project and proposes the next 1–3 milestones to add to docs/milestones/.

Both can run back-to-back: triage handles "what should this session do?", planning handles "what should the next several sessions do?".

When to use

• The user asks "what milestones should we have next?" / "what's the roadmap from here?" / "what's left before we can ship?".
• All open milestones are complete (or only have polish AC remaining) and the project still doesn't satisfy the gameplan.
• The gameplan changed materially (new loop, new mode, new win condition) and existing milestones no longer cover the delta.
• A backlog item is large enough that it warrants being broken into several milestones rather than absorbed into one.
• During doc-drift audit when the audit finds gameplan capabilities with no covering milestone.

Do not use this sub-pipeline for a single in-flight feature or a clear bug — those go through development.md directly.

Inputs

• docs/gameplan.md (target state — the game the user actually wants to ship)
• docs/milestones/ (every milestone, including done, in-progress, and planned)
• docs/backlog.md (deferred items and open questions)
• docs/architectural-decisions/ (locked-in constraints — engine, language, art style, etc.)
• The codebase itself (what's actually been built, regardless of what AC says)

Steps

1. Restate the target state from the gameplan

In your own words, list the gameplay capabilities docs/gameplan.md requires — the verbs in the core loop, the rules, the win/lose conditions, the player goals. Keep it short (one bullet per capability). This is the target inventory.

If a capability in the gameplan is vague enough that it can't be turned into a checkable AC ("combat should feel snappy"), flag it for the playtest / repro sub-pipeline rather than trying to plan it as a milestone — vague targets produce vague milestones.

2. Inventory current state

Walk three sources and produce a flat list of what's covered:

• Done milestones: every milestone with all AC ticked. List the capability each delivered.
• Open milestones: for each, list the capabilities it will deliver when complete and the AC still outstanding. Spot-check the codebase — if an AC is unchecked but the code clearly satisfies it, note the drift; if the code is missing despite an AC being ticked, also note that.
• Codebase reality: capabilities that exist in code but aren't claimed by any milestone (common in projects that started outside the skill).

3. Compute the gameplan delta

Subtract step 2 from step 1. The remainder is the delta: gameplay capabilities the gameplan requires that no done or open milestone covers.

Cross-check the delta against docs/backlog.md. For each delta item:

• If the backlog already has an entry, link to it rather than restating.
• If the backlog has notes (constraints, dependencies, references), pull them in — they are the user's prior thinking and should not be re-litigated.
• If the delta is not in the backlog and not in any milestone, it's a brand-new gap.

4. Slice the delta into milestone-sized pieces

A good milestone has all of these properties:

• One shippable capability. A single thing the user can play and verify in a session. If the milestone needs multiple unrelated playtests to verify, it's two milestones.
• A testable exit condition. "User does X → observes Y." If you can't phrase the exit this way, the milestone isn't ready — the underlying capability needs more thought first (push to backlog "Open questions").
• Sized to fit a focused session. Roughly 1–3 live-iterate cycles of work. Bigger milestones hide progress; smaller milestones are usually ACs of a parent milestone, not standalone ones.
• Independent of polish. Polish (juice, particles, transitions, audio refinement) belongs in its own milestone or in docs/backlog.md "Polish & juice", not bundled with mechanics work.

If a delta item is too big, split it. If it's too small, group it with adjacent items into one milestone. The right grain is "the smallest thing that is independently meaningful to the player".

5. Order by dependency and architecture-enabling first

Apply these priority rules in order:

1. Architecture-enabling work first. State machines, save/load, multiplayer scaffolding, asset loading pipelines — anything later milestones will read from or build on. Do these before content or polish. 2. Core loop second. Until the player can play one full loop start-to-finish, nothing else matters. If the loop is already shippable, skip. 3. Loop refinements third. Difficulty, balancing, content depth — anything that makes the loop feel finished. 4. Polish, audio, juice fourth. Only after the loop is mechanically solid. 5. Stretch and meta-features last. Achievements, cosmetics, leaderboards, monetization integration, etc. These often live in docs/backlog.md permanently and only graduate to milestones once the user explicitly wants to ship them.

For each proposed milestone, write down:

• Depends on: earlier milestones or ADRs it requires.
• Blocks: later milestones that need it first.

If a proposed milestone depends on a decision the user hasn't made yet (engine extension, multiplayer transport, monetization model), surface that as an open question rather than guessing — open questions belong in the backlog, and the milestone waits.

6. Right-size and sanity-check the proposal set

Aim for the next 1–3 milestones, not the whole roadmap.

• More than 3 proposals at a time is hard for the user to reason about and almost always wrong on items 4+. Future milestones will look different once 1–3 are shipped — don't over-commit.
• Less than 1 proposal means there's nothing to plan; either the gameplan is satisfied (suggest the user update the gameplan, ship, or move to a stretch goal from the backlog) or you missed delta in step 3.

For each proposed milestone, draft (do not yet write to disk):

• Title (verb-led, short — e.g. "Player can wall-jump", not "Wall jump system").
• One-paragraph objective.
• 3–6 acceptance criteria (concrete, checkable; copy the shape from `templates/milestone.md`).
• Exit condition in "User does X → observes Y" form.
• Dependencies (Depends on / Blocks).
• Rough size: S / M / L (so the user can compare cost vs. value).

7. Confirm with the user via `AskUserQuestion`

Present the proposal as a multiple-choice question. Recommended option set:

• Adopt the proposed set as-is — write all proposed milestones in order.
• Adopt only milestone NN-... first — write just the first one, defer the rest until it ships.
• Reorder or revise — let the user move items, drop items, or pull in a backlog item that didn't make the cut.
• Pick a different scope entirely — escape hatch if the user disagrees with the gap analysis itself.

Show the user:

• The capability delta you computed in step 3 (so they can challenge it).
• The runners-up from the backlog you considered but didn't propose (so nothing visibly disappeared).

8. Write the confirmed milestones to `docs/milestones/`

Only after the user confirms:

• Use `templates/milestone.md` for each file.
• Number them sequentially after the highest existing milestone (05-..., 06-..., etc.); never reuse numbers.
• Set Status: planned.
• Fill in every section — empty Test plan and Out of scope sections invite drift later.
• Tick promoted backlog items in docs/backlog.md and append → milestone NN-<slug>.md.
• Update docs/STATE.md with the new "next milestone" pointer.

If a milestone you proposed depends on an unresolved open question, write the milestone with Status: blocked and a clear Blockers note rather than starting it. The user must resolve the question before it leaves blocked.

9. Hand back to the development pipeline

The first proposed milestone now becomes the active scope. Return to `development.md` step 1 with that milestone — do not start coding inside this sub-pipeline.

Outputs

• 1–3 new milestone documents in docs/milestones/, in dependency order, all sections filled.
• docs/backlog.md updated: promoted items ticked with milestone links; nothing silently removed.
• docs/STATE.md updated: next-milestone pointer reflects the new state.
• A clear "why these, why now, why in this order" justification, written into each milestone's Objective section and confirmed by the user.

Exit criteria

• The proposed set covers the most pressing gameplan delta the user agreed to address now.
• Each milestone has a testable exit condition and is independently shippable.
• Dependencies form a DAG, not a cycle.
• The user has explicitly approved the order and scope.
• The next active milestone is unambiguous and pointed to from docs/STATE.md.

Anti-patterns to avoid

• Roadmap padding. Proposing 6+ milestones to look thorough. Future you will rewrite items 4+ once 1–3 ship; the planning effort is wasted.
• Mechanics-and-polish bundles. "Implement combat and add hit feedback" is two milestones. Polish always slips, and bundling it makes the mechanic milestone look incomplete.
• Architecture-enabling milestones with no consumer. If a state machine or asset pipeline isn't consumed by an immediately following milestone, it's speculative — defer it to the backlog with a Why: note.
• Skipping the gameplan re-read. If you don't restate the target state in step 1, the proposal is just a re-shuffle of the backlog. The gameplan is what makes planning purposeful.
• Inventing scope the user didn't ask for. This sub-pipeline turns existing gameplan + backlog content into milestones. New gameplay ideas come from the user; if you find yourself wanting to propose one, write it to the backlog and surface it as an open question instead.
• Writing files before confirmation. The proposal is a draft until step 7 succeeds. Files written prematurely create churn if the user rejects the plan.

Playtest / repro

Convert vague gameplay feedback ("feels floaty", "combat is boring", "the jump is off") into observable, testable acceptance criteria.

When to use

• The user describes a feel, balance, or UX problem in subjective terms
• A bug report has no clear repro steps
• You're considering a change to game feel and need to define "better" before touching code

Inputs

• The user's description, however vague
• The current relevant code or config (jump curves, damage numbers, animation timings, hitbox sizes, etc.)

Steps

1. Reflect back what you heard, narrowly. "When you say floaty, do you mean the jump arc, the landing, or air control?" Use the AskUserQuestion tool with the most likely interpretations as options. 2. Identify the measurable variables behind the feel. Examples:

• "Floaty" → jump apex height, hang time, gravity scale, air friction
• "Combat is boring" → hits-to-kill, hitstop duration, screen shake, damage variance, telegraph length
• "Off" → input lag, animation startup frames, hitbox size, coyote time, input buffer window

3. Read the current values from code or config. Quote them back to the user. 4. Propose target values or a target observation. State as observable: "After change, a max-height jump should peak in ≤0.4s and the player should regain ground control within 0.1s of landing." 5. Get the user to confirm the target. That confirmed statement becomes the new acceptance criterion. 6. Hand off to Bug fix or the development phase pipeline with the AC in hand.

Outputs

• A concrete, observable acceptance criterion the user has confirmed
• (Optional) A new milestone or a milestone update capturing the AC

Exit criteria

• The vague feedback is now stated as <observable change> with a number, frame count, or yes/no observation
• The user has agreed with that statement

Sub-pipelines

Reusable pipelines for specific tasks during game development. Use these when the task fits — do not invent your own pipeline if one is already defined here.

How to use

Before starting work that fits a sub-pipeline below, read that sub-pipeline document and follow it. If your task spans multiple sub-pipelines, name them in your plan and run them in order.

Standard sub-pipeline shape

Every sub-pipeline doc follows this structure. When adding a new sub-pipeline, follow the same shape so behavior stays consistent across sessions.

• When to use — concrete trigger conditions
• Inputs — what must exist before starting (docs, codebase state, user info)
• Steps — ordered, numbered actions
• Outputs — files written or changed, decisions captured
• Exit criteria — how you know the sub-pipeline is done

Available sub-pipelines

Process

• Session start — entry point for every session in an existing project; recovers context and decides the current phase
• Scope triage — narrow a multi-feature request down to a single focused session; defer the rest to docs/backlog.md
• Milestone planning — propose the next 1–3 milestones from the gap between docs/gameplan.md and current state + docs/backlog.md
• Bug fix — triage, repro, minimal-scope fix, regression check
• Playtest / repro — convert vague gameplay feedback into testable acceptance criteria
• Doc drift audit — verify docs/ still reflects code reality

Setup

• Agents bootstrap — generate AGENTS.md + CLAUDE.md at the project root to enforce skill use across every future session. Run at end of scaffold phase, after stack changes, or when drift is flagged.

Verification

• Live iterate — post-edit verification loop: console → render_game_to_text() → advanceTime() → screenshot → user check. Run after every code change in the development phase.

Authoring

• Asset pipeline — naming, folder layout, placeholder→final swap, binary storage rules

Systems

• State machine — canonical FSM pattern; prevents ad-hoc booleans-as-state

Scope triage

Use this sub-pipeline whenever the user's request would balloon a single session's scope: a multi-feature dump ("add inventory, crafting, and a shop"), a vague ambition ("make combat feel better, add bosses, and balance the early game"), or a bug fix that keeps growing into adjacent features. The job is to land on one focused next step, write everything else into the backlog, and confirm the choice with the user before touching code.

Sessions that try to carry two or more independent features at once cause:

• Context drift — the agent loses track of which file change belongs to which feature.
• Iteration paralysis — the user can't tell which feature broke when the live-iterate loop fails.
• Doc drift — milestones get half-completed and AC checkboxes lie about the state of the code.

Narrow scope per session is the cheapest defense.

When to use

• The user's request mentions more than one independent feature or change.
• The user is brainstorming open-endedly ("here's a bunch of stuff I want to do").
• The current milestone's AC is still open but the user is asking for something orthogonal.
• A bug fix has surfaced adjacent improvements the user wants "while you're in there".
• During milestone creation in the development pipeline step 2.

Skip this sub-pipeline only when the request is already a single, scoped feature that fits the current milestone.

Inputs

• The user's full request (read it carefully — list every distinct feature or change it implies)
• docs/STATE.md (current phase, current milestone, next AC)
• docs/milestones/ (open milestones and their AC)
• docs/backlog.md (existing deferred items — must not be duplicated)
• docs/gameplan.md (so the prioritization is grounded in the actual game)

Steps

1. Enumerate every distinct ask

Restate the user's request as a flat, numbered list of independent features or changes — one bullet per thing that could ship on its own. Resist combining items "because they're related"; the point is to make hidden scope visible.

If two items truly cannot be tested independently (e.g. "add a weapon slot" and "add a weapon"), call that out explicitly and treat them as one.

2. Cross-check against the backlog and open milestones

For each item:

• If it already exists in docs/backlog.md, link to that entry rather than re-listing.
• If it's already covered by an open milestone's AC, point at that AC.
• If it's brand new, it's a backlog candidate.

This step prevents the backlog from accumulating duplicates and surfaces items that were already deferred in a previous session.

3. Score each new item on value × ease

Tag each new item with rough value (S / M / L: how much it moves the game forward toward the gameplan) and rough ease (S / M / L: how cheap it is to implement and verify). These are gut estimates, not formal estimates — the goal is to make the trade-off legible to the user.

4. Recommend the single next feature

Pick the one item with the best balance of important enough to matter and easy enough to ship in one focused session. Bias toward:

• Items that unblock later work (architecture-enabling > polish).
• Items that close out the current milestone's exit condition.
• Items the user can verify in 30 seconds via live-iterate.

Avoid:

• Items requiring a top-level architecture change without an ADR conversation first.
• Items that span multiple systems and would need parallel changes in art, audio, and gameplay code in one go.
• Items the user hasn't decided the design of yet (push those to "Open questions" in the backlog).

5. Write the deferred items to `docs/backlog.md`

For every other item, append an entry to docs/backlog.md under the appropriate section using the shape from `templates/backlog.md`. Include:

• Short title and one-sentence description
• Source (today's date and a phrase from the user's message)
• Rough size and value tags from step 3
• Notes (constraints, dependencies, references the user mentioned)

If docs/backlog.md does not exist yet, create it from the template now.

6. Confirm with the user via `AskUserQuestion`

Present the recommendation as a multiple-choice question with at least these options:

• Recommended: the single feature you chose, with a one-line "why this one first" justification.
• Pick a different deferred item: list 2–3 of the runners-up so the user can override.
• All-in: acknowledge the user can ask to bundle items, but warn explicitly that the session will lose focus and live-iterate verification will be harder. Only take this path if the user insists.

Show the user the deferred-items list you wrote to the backlog so they can sanity-check that nothing was lost.

7. Promote the chosen item into the milestone flow

Once the user confirms:

• If the chosen item fits an existing open milestone, append AC to that milestone (use the append vs spawn rule from SKILL.md §3).
• If it doesn't fit, spawn a new milestone using `templates/milestone.md`.
• If the chosen item is large enough to span more than one milestone (multi-system feature, new mode, big refactor), hand off to the milestone-planning sub-pipeline to slice it into ordered milestones rather than authoring one mega-milestone.
• Either way, return to `development.md` step 3 with that single feature as the scope.

Do not start coding until this step is done — the milestone is what gives live-iterate something to verify against.

Outputs

• docs/backlog.md updated with every deferred item (created if it didn't exist)
• A single chosen feature, confirmed by the user, written into a milestone
• A clear "why this one first" justification logged in the milestone's Objective section
• Runners-up still discoverable in the backlog for future sessions

Exit criteria

• Exactly one feature is in scope for the rest of the session.
• Every other item from the user's request is in docs/backlog.md (or already linked from there).
• The user has confirmed the chosen scope.
• The next step is a concrete AC inside a real milestone document.

Anti-patterns to avoid

• Silently dropping items. If the user mentioned five features and you only address one without writing the other four to the backlog, the user has to remember them — that's a recipe for the same dump landing again next session.
• Calling everything "small enough to bundle". Two features in one session is already a smell. Three is almost always wrong.
• Skipping the user confirmation. The recommendation is a proposal, not a unilateral decision. The user owns priority.
• Treating the backlog as a graveyard. Backlog entries must be re-read at the start of every milestone-creation conversation (step 2). If items rot for many sessions in a row, ask the user whether they should be rejected (struck through with a reason) rather than living forever.

Session start

The first thing to run at the start of every session in an existing project. Builds context and aligns on what to do next before any other work.

When to use

• The current working directory is a project directory (has docs/ or game source files)
• You have not yet read project docs in this conversation
• The user has just opened a new session

Inputs

• The current working directory
• Any docs/ folder that exists in it

Steps

1. Check for `docs/STATE.md`. If it exists, read it first. This is the previous session's handoff and tells you exactly where to resume. 2. Read `docs/gameplan.md` if it exists. This is the source of truth for what the game is. 3. Read `docs/tech.md` if it exists. This is the source of truth for the stack. 4. List `docs/milestones/`. Identify the earliest milestone with incomplete acceptance criteria. Read its full content. 5. Read `docs/backlog.md` if it exists. You don't need to action items, but you must know what was deferred. If the user opens the session with a request that matches a backlog item, treat the backlog entry as the source of truth (description, notes, prior context) rather than starting from scratch. 6. Spot-check the codebase against the open milestone. Has work been done that hasn't been ticked off? Has the AC drifted from reality? 7. Decide the phase:

• No docs/ and no project source files → Idea phase
• docs/ exists but no project source / dependencies installed → Scaffold phase
• Project source files exist and docs/ exists → Development phase
• Project source files exist but docs/ is missing or near-empty → Development phase + doc backfill. The project was started outside this skill (or by an earlier non-skill session). Before continuing feature work, offer to bootstrap docs/gameplan.md and docs/tech.md from the existing code: read the entry point, package manifest, and a representative scene/system; draft the docs; confirm with the user; then run the agents-bootstrap sub-pipeline so future sessions enforce the skill regardless of which agent tool is used. Do not silently start coding new features in a project with no docs — that's how drift starts.
• Project has docs/ but no AGENTS.md at the project root → same phase as detected, plus agents-bootstrap. Run the agents-bootstrap sub-pipeline before continuing other work. AGENTS.md is the cross-session enforcement file and is mandatory for any project past the idea phase.

8. Confirm with the user before acting. Summarize: "We're in <phase>, current milestone is <X>, next open AC is <Y>. Proceed?" Use the AskUserQuestion tool with the proposed next step as one of the options. For the doc-backfill branch, the question is: "Bootstrap docs/ from existing code now, or skip the backfill and start coding (you'll be in minimum-viable doc mode — see SKILL.md §1)?" If docs/backlog.md has items the user might want to promote ahead of the next AC, include the top one or two as alternative options in the question.

Outputs

• An internal understanding of phase, current milestone, and the next concrete step
• A user confirmation (or correction) of that summary
• (At the end of the session, not the start) An updated docs/STATE.md once progress was made — see `templates/state.md`

Exit criteria

• You can name the current phase, current milestone, and the next acceptance criterion to work on
• The user has confirmed (or corrected) that summary and given a go-ahead

State machine

Canonical pattern for any state-driven gameplay system: player controllers, enemy AI, UI screens, game flow, dialog systems.

When to use

• Adding a system whose behavior depends on what mode or state it's in
• Refactoring a system that uses booleans (isJumping && !isFalling && canMove) to track state
• Adding a new state to an existing state-driven system

Inputs

• The system being designed
• Any existing FSM utilities or libraries already in use in the project (docs/tech.md)

Steps

1. Check for an existing FSM convention in the project. If one is already in use (XState, Unity Animator, custom enum-switch, behavior tree library), follow it. Do not introduce a second pattern in the same project — that's the drift you're trying to prevent. 2. If no convention exists, propose one to the user before coding. Default recommendations:

• Small systems (3–5 states): typed enum + switch in an update() / tick.
• Medium systems (5–10 states with side effects): explicit State interface with enter / update / exit methods.
• Large or branching systems (parallel states, hierarchical states, AI): a real FSM library — XState in JS/TS, Unity Animator state machines, or behavior trees / GOAP for NPC AI.

3. Define states and transitions in data, not control flow. A list of (from, event, to) triples is far easier to reason about than nested ifs. This is what a future agent will read first. 4. Forbid implicit state. Booleans like isJumping, isAttacking, isStunned are a smell — they multiply combinatorially. If you find them, replace with a single state enum. 5. Document the state graph. A short markdown table or mermaid diagram in the system's milestone file or in docs/systems/<system>.md. Future agents will reach for this before reading code. 6. Add at least one invalid-transition log. When the state machine receives an event from a state that doesn't accept it, log it. This catches drift fast during playtests when new states are added without updating transitions.

Outputs

• The system implemented as an FSM following the project's chosen pattern
• The state graph captured in docs (table or diagram)
• (If introducing a new convention) docs/tech.md updated to mention the FSM pattern in use

Exit criteria

• All state for the system lives in a single named field, not scattered across booleans
• Every transition is a named event with a single source state and target state
• An agent reading only the state graph can predict behavior without reading the implementation

ADR <NNNN>: <Title>

Status

<proposed | accepted | superseded by ADR-NNNN>

Date

<YYYY-MM-DD>

Context

<What forces are in play. Why does this decision need to be made now? What constraints (technical, scheduling, scope, user preference) apply?>

Decision

<The decision, stated plainly. One paragraph max. The reader should be able to act on this without reading anything else.>

Consequences

Positive

• <What this enables or makes easier>

Negative

• <What this costs, constrains, or makes harder>

Alternatives considered

• <Alternative 1>: <why rejected>
• <Alternative 2>: <why rejected>

Related

• <Links to milestones this enables, prior ADRs this supersedes, or external references>

AGENTS.md

Lean enforcement file for any AI agent working in this repository. Read this file first, every session, before any other action. Cross-tool standard (Cursor, Aider, Codex, Claude, etc.). Claude users: CLAUDE.md points here.

This project follows the `make-game` pipeline. Do not improvise process — follow the rules below.

Project overview

• Title: <Game title>
• Pitch: <1–2 sentence pitch from docs/gameplan.md>
• Genre / type: <e.g. roguelike deckbuilder, 2.5D pixel-art blackjack>
• Engine: <engine + version, from docs/tech.md>
• Language: <e.g. TypeScript, C#>
• Target platform: <e.g. Browser (desktop + mobile web)>

Hard gate: no code before plan

If docs/gameplan.md does not exist in this repo, you are in the idea phase — do not create source files, run engine scaffolders, or install dependencies. Your only job is to walk the user through the idea-phase clarifying-questions checklist (gameplay loop, art style, controls/scope, engine/stack — see make-game skill phase-pipelines/idea.md) and produce docs/gameplan.md, docs/tech.md, and docs/architectural-decisions/0001-engine-and-stack.md. A detailed-sounding initial prompt is not a substitute for the checklist; ask every item even if the user "seems clear."

Mandatory: run the make-game skill

Every session in this directory must run the make-game skill's session-start sub-pipeline before any other work. The skill enforces phase awareness, doc continuity, milestone discipline, and the live-iterate verification loop.

If the skill is not installed in your environment:

npx skills add opusgamelabs/game-creator --skill make-game -p -y

If the skill cannot be installed (e.g. unsupported agent tool), apply the rules in this file manually and tell the user the skill is missing.

Source-of-truth files

These docs are the agreed state of the project. Read them at session start; do not unilaterally edit them — propose changes and get user confirmation first.

• docs/STATE.md — last session handoff. Read first, every session.
• docs/gameplan.md — game definition (loop, rules, art, audio, anti-goals).
• docs/tech.md — stack, tooling, conventions.
• docs/milestones/ — feature work breakdown with acceptance criteria.
• docs/architectural-decisions/ — locked top-level decisions (engine, language, art-style, state-machine pattern, etc.).

Architecture rules

<Filled in per-stack at scaffold time. Examples:>

<For browser games (Phaser 3 / Three.js):>

• EventBus singleton — all cross-module communication via pub/sub. Modules never import each other directly. Events use domain:action naming.
• GameState singleton — single centralized state object. Systems read; events trigger mutations.
• Constants.js — every magic number, color, timing, speed lives here. Zero hardcoded values in game logic.
• `window.render_game_to_text()` — exposes a JSON snapshot of current game state for agent inspection without screenshots.
• `window.advanceTime(ms)` — steps the simulation deterministically for verification.

<For Unity / Unreal / Godot: replace with engine-appropriate patterns.>

Stack-specific commands

• Dev server: <command>
• Tests: <command>
• Build: <command>
• Lint / format: <command> (or "n/a")

Live iterate (after every code change)

After any meaningful code change in the development phase:

1. Confirm dev server is live; check console — must be error-free. 2. Call render_game_to_text() and verify state matches the change. 3. For time-dependent changes, step with advanceTime(ms) and re-read. 4. If visual, take a screenshot; save under output/iterate/. 5. Smoke-check adjacent state for regressions. 6. Hand back to the user with a one-line verdict and one focused question.

A change is not done until this loop has run.

Append vs spawn a new milestone

When new work surfaces:

• Append an AC to the current milestone if the work is in-scope refinement.
• Spawn a new milestone if the work is out of scope but related; use Depends on: to capture ordering.
• Inline trivial fixes (typos, one-liners) on the current milestone.

When in doubt, prefer spawning. Do not bloat milestones.

Minimum-viable doc mode

If the user pushes back on documentation overhead, downgrade — do not skip:

• One-line milestone entry (title + AC) is acceptable.
• docs/STATE.md updates remain mandatory.
• docs/gameplan.md and docs/tech.md must exist.
• Engine / language / stack ADRs cannot be skipped.

What to do if make-game isn't loaded

If the skill is missing or didn't trigger this session:

1. Stop. Do not start coding. 2. Read this file in full. 3. Read docs/STATE.md, then docs/gameplan.md, then docs/tech.md. 4. Identify the current phase and the open milestone. 5. Tell the user the skill isn't loaded and recommend they install it. 6. If proceeding without the skill, apply the rules above manually and update docs/STATE.md at the end of the session.

Last regenerated

<YYYY-MM-DD by <agent or user>. Regenerate when the engine, primary commands, or architecture rules change. The doc-drift audit will flag staleness.>

Backlog

Out-of-scope ideas, feature requests, and follow-ups captured during sessions but not worked on in the session that captured them. Read at the start of every milestone-creation conversation. Append-only — promoted items get a checkbox tick and a link to the milestone that absorbed them, not a deletion.

>

If an item turns out to be wrong / no longer wanted, mark it ~~struck through~~ with a one-line reason rather than removing it; future sessions need to see that it was considered and rejected.

How to write a backlog entry

Each entry is a bullet under one of the sections below with this shape:

- [ ] <short title> — <one-sentence description of the desired behavior or change>
  - Source: <session date or user message that introduced it>
  - Rough size: <S | M | L> · Rough value: <S | M | L>
  - Notes: <optional — constraints, dependencies, related milestones, references>

Keep titles short enough to scan in one pass. Put the detail in the description and notes.

When an entry is promoted into a milestone, replace [ ] with [x] and append → milestone NN-<slug>.md so the trail is preserved.

When an entry is rejected, wrap the title in ~~strikethrough~~ and add a one-line Rejected: <reason> note.

Gameplay & features

<append new ideas here — gameplay loops, mechanics, modes, levels, characters, content>

Polish & juice

<visual polish, particles, transitions, screen shake, audio cues that aren't load-bearing for the loop>

Tech & refactors

<refactors, architecture clean-up, dependency upgrades, perf work that isn't a current bottleneck>

Tooling & QA

<test coverage, dev ergonomics, CI, debugging affordances>

Open questions

<things the user hasn't decided yet — design questions, scoping questions, monetization questions. Not features, but things that need an answer before related features can be planned.>

<Game Title>

Pitch

<1–2 sentence pitch with a hook. The hook is what makes someone want to play.>

Core gameplay loop

<What the player does, start to finish, in a single play session. Be specific — name the verbs.>

Game rules

<Concrete rules. Include only those a player or another developer must know to reason about the game.>

Win / lose conditions

<How a session ends. Skip if not applicable (e.g. open-ended sandbox).>

Art style

<Description and reference images. Note 2D/3D, perspective, palette, mood. Link concept art if available.>

Audio direction

<Tone of music and SFX. Diegetic vs. non-diegetic. Reference tracks if available.>

Player goals

<What the player is trying to achieve in the short term (per session) and long term (across sessions).>

Anti-goals

<Things this game is deliberately NOT trying to be. Useful for cutting scope creep later.>

References

<Other games, films, art, or systems that inform tone or mechanics. One line each.>

Open questions

<Anything not yet decided. Resolve before leaving the idea phase.>

Milestone <NN>: <Title>

Status

<planned | in-progress | done>

Objective

<One paragraph. What this milestone delivers and why it's being done now.>

Scope

• <In-scope item>
• <In-scope item>

Out of scope

• <Explicitly deferred item — write down what you considered but chose to leave out>

Dependencies

• Depends on: <milestone NN, ADR NNNN, or "none">
• Blocks: <milestone NN, or "none">

Acceptance criteria

Every checkable AC must reference the test that proves it. Format: - [ ] <AC> — test: <path/to/test.spec.js::test name>. AC that can only be verified by user playtest (juice, feel, polish) must be tagged — verified by user playtest so the absence of an automated test is intentional, not an oversight.

• [ ] <Concrete, checkable AC> — test: <path/to/test>::<test name>
• [ ] <Concrete, checkable AC> — verified by user playtest

Exit condition

<A single observable result a user can test. Format: "User does X → observes Y." If you can't write the exit condition this way, the milestone is not yet ready to start.>

Test plan

<How the user (and you) will verify the exit condition. List the failing tests written up front (red-then-green), the manual playtest steps for any AC verified by user playtest, and the regression-suite command (e.g. npm run test) the next session should run before declaring the milestone done.>

Notes

<Implementation notes, decisions made during the milestone, links to ADRs that govern this work. Update as the milestone progresses.>

Templates

Skeletons for the documents the make-games skill mandates. Copy these when creating new docs — do not improvise structure. Consistent structure across sessions is the single highest-leverage anti-drift mechanism.

When to use which

Naming

• Milestones: zero-padded number prefix (01-core-loop.md, 02-combat.md). Order is meaningful — milestones are intended to be completed in order unless dependencies say otherwise.
• ADRs: four-digit number prefix (0001-engine-choice.md, 0002-state-machine-pattern.md). Numbers are never reused, never reordered. Superseded ADRs stay with Status: superseded by ADR-NNNN.

When to write the first ADR

The very first ADR (0001) should be written at the end of the idea phase and capture the engine / language / art-style decisions. Locking those in early prevents the most common form of cross-session drift.

Session state

Updated at the end of each session that made progress. Read first at the start of each session by the session-start sub-pipeline.

Last updated

<YYYY-MM-DD by <agent or user>>

Current phase

<idea | scaffold | development>

Current milestone

<milestone NN — title, link to file>

Last action

<1–3 sentences on what the previous session actually changed. Concrete, not aspirational.>

Next step

<The single next concrete action. Should match the smallest open AC in the current milestone.>

Blockers

<Anything waiting on the user, an external decision, or an unresolved question. Write "none" if there are no blockers — don't omit the section.>

Notes for next session

<Optional. Things the previous agent wishes it had known at the start of this session: gotchas, partial implementations, hypotheses to test.>

Tech stack

Engine / runtime

• Engine: <name + version>
• Language(s): <e.g. C#, TypeScript, GDScript>
• Target platforms: <e.g. Web, Windows, Mac, Switch>

Libraries / frameworks

Tooling

• Package manager: <npm / pnpm / NuGet / Cargo / ...>
• Build: <Vite / Webpack / Unity build / Godot export / ...>
• Testing: <Jest / xUnit / pytest / GUT / ...>
• Linting / formatting: <ESLint+Prettier / dotnet format / ...>
• Asset / binary storage: <Git LFS configured? Y/N — if Y, list tracked patterns>

Project layout

<High-level folder map. Update when top-level structure changes.>

Conventions

• Code naming: <PascalCase for X, snake_case for Y, kebab-case for Z>
• State machines: <pattern in use — see sub-pipelines/state-machine.md>
• Asset naming: <see sub-pipelines/asset-pipeline.md or override here>
• File-per-component / file-per-system rules: <if any>

Out-of-scope dependencies

<Anything deliberately not used and why. Prevents future agents from re-introducing it.>

Useful Skills

A catalog of additional skills that pair well with make-game. The make-game pipeline itself is engine-agnostic, but most of the skills below assume a JavaScript browser game (Phaser 3 for 2D, Three.js for 3D) because that is what the rest of the game-creator plugin specializes in.

Use this document as a menu — install only the skills relevant to the project's tech stack and current phase. Re-check after big stack decisions land in docs/tech.md.

How to Install

Use the npx skills command:

npx skills add opusgamelabs/game-creator --skill <skill-name> -p -y

How to Choose

1. Read docs/tech.md to determine the engine, language, and platform. 2. Match the project to one of the stack groups below and install those skills. 3. Layer in cross-cutting skills based on the current phase or feature work (audio, design, QA, multiplayer, monetization, deployment, promo). 4. Reference skills (marked _reference_) are deep domain knowledge loaded by other skills — install them when you need the patterns directly, otherwise the user-invocable skill above will pull them in.

---

Generic — Any Game Project

Skills that apply regardless of engine, renderer, or platform. Safe to install on any game project.

• game-architecture _(reference)_ — Architecture patterns (EventBus, GameState, Constants, orchestrator) and structural best practices. Useful when planning systems, writing ADRs, or laying down docs/gameplan.md.
• review-game — Read-only code review for architecture, performance, and best practices. Run after milestones land or before refactors.
• improve-game — Holistic audit + implements the highest-impact improvements. Run repeatedly during the development phase.
• add-feature — Add a new gameplay feature following the project's existing patterns. The default tool for milestone implementation.
• fetch-tweet — Utility: fetch tweet content from an X/Twitter URL (used when scaffolding from a tweet-described game idea).

---

Stack: 2D Browser Games (Phaser / JS)

Install when docs/tech.md calls for Phaser or any 2D HTML5 canvas game.

• phaser _(reference)_ — Phaser 3 patterns: scenes, lifecycle, game objects, physics, UI, performance.
• add-assets — Replace geometric shapes with pixel art sprites (recognizable characters, enemies, items).
• game-assets _(reference)_ — Pixel art generation patterns, animation, spritesheets.

---

Stack: 3D Browser Games (Three.js)

Install when docs/tech.md calls for Three.js or any WebGL 3D game.

• threejs-game _(reference)_ — Three.js event-driven modular architecture, scene setup, camera/controls patterns.
• threejs-perf _(reference)_ — Performance patterns: instancing for static + moving geometry, draw call reduction, scene traversal.
• add-3d-assets — Replace primitive BoxGeometry/SphereGeometry with real GLB models.
• game-3d-assets _(reference)_ — 3D asset pipeline: GLB download, AssetLoader, animated characters, clip maps.
• meshyai — Generate custom GLB models from text or images via Meshy AI; auto-rig and animate. Preferred source for custom 3D assets.
• worldlabs — Generate photorealistic 3D environments (Gaussian Splat scenes) from prompts or reference images. Requires WLT_API_KEY.

---

Cross-Cutting: Audio

Browser-game audio via the Web Audio API (zero dependencies). Works with both Phaser and Three.js projects.

• add-audio — Add BGM and SFX using the Web Audio API.
• game-audio _(reference)_ — Procedural music patterns, step sequencer, SFX synthesis.

---

Cross-Cutting: Visual Design & Polish

Engine-agnostic for browser games — focuses on UI, particles, gradients, transitions, "juice".

• design-game — Audit and improve visual polish, atmosphere, and UI of an existing game.
• game-designer _(reference)_ — Visual polish patterns (gradients, particles, screen transitions, juice/feel).

---

Cross-Cutting: QA & Testing

Browser-game testing via Playwright. Applies to any game running in a browser.

• qa-game — Add Playwright tests: gameplay verification, visual regression, performance.
• game-qa _(reference)_ — Playwright patterns, fixtures, deterministic test setup, FPS measurement.

---

Cross-Cutting: Multiplayer

• add-multiplayer — Add real-time or turn-based multiplayer via PartyKit (Cloudflare Durable Objects). Scaffolds a room-based server, NetworkManager client, and extends the EventBus / GameState / render_game_to_text() shape.

---

Cross-Cutting: Deployment

• game-deploy — Deploy a built browser game to here.now (default), GitHub Pages, Vercel, etc.

---

Cross-Cutting: Promo & Recording

• record-promo — Record an autonomous 50 FPS promo video for social media.
• promo-video _(reference)_ — Playwright + FFmpeg gameplay capture pipeline.

---

Cross-Cutting: Monetization

Install once the gameplay loop is solid and the project is moving toward release.

• scaffold-gateables — Add monetization-agnostic gateable features (skin picker, continue-after-death, daily challenge, save slots) at silver/gold tiers with clean isEntitled hooks. Run before wiring a specific paywall.
• monetize-game — Register the game on Play.fun (OpenGameProtocol), add the browser SDK, get a monetized play.fun URL.
• sub-games — Integrate sub.games subscriptions for tier-gated features and recurring revenue.

---

Quickstart Alternatives

These skills bypass parts of the make-game pipeline. Reach for them when the user wants speed over rigor.

• viral-game — One-shot end-to-end pipeline (~10 minutes): tweet/story/concept → scaffold → assets → design → promo video → audio → deploy to here.now → monetize on Play.fun. Trades milestone planning, ADRs, and multi-session iteration for time-to-deploy. Reach for it when the user wants a sharable, monetized game now and is fine with an opinionated stack (Phaser 3 / Three.js).
• use-template — Clone an existing game from the template gallery as a starting point. ~10-second copy vs full-pipeline scaffold.
• quick-game — Rapidly scaffold a playable game with no assets/design/audio/deploy/monetize. For prototypes only.