msw-planning

The full skill.

Original instructions from the publisher’s SKILL.md

# MSW New-Game Planning Mode (msw-planning)

## Purpose
When the user is at the "I want to make a game like this" stage, turn it into **what to build + how to build it in MSW**: a guided session produces a **GDD/roadmap**, then the skill **guides the phased build** — detailed Phase plans, progress tracking, and plan revisions — **until each milestone's build is ready to enter full implementation**. Someone who doesn't know game design can just follow the questions; for those who do, it documents decisions fast.

## Core principles (why it works this way)
- **Catalog grounding**: MSW is 2D · mLua (a Lua-extension scripting language) · cross-platform, so the space of "what you can build" is bounded. Map a vague idea onto the real genres/map-types/mechanics in [`references/genre-catalog.md`](references/genre-catalog.md) to get a *feasible* plan. Planning from generic game knowledge alone leads to designs MSW can't realize.
- **Right-size the build**: the catalog gives a **build-effort hint** (Low / Medium / High) per genre — a signal, not a verdict (baseline 1–5 maps · 10–20 units/items · basic-to-intermediate mLua; **tower defense sits at the top of comfortably-solo**). Use it to set expectations, not to refuse a genre. Size the first build by **build-effort + scope (maps/content), never by a calendar/development-time estimate** — the skill can't know the user's skill level or available hours, so it doesn't promise 'this takes N days/weeks.' **When the user's ambition is large** (a High-effort genre, or many systems/maps, or "I want everything"), don't plan it all at once — **scope the *first build* down to a small playable core (MVP)** and push the rest to later Phases. This applies to any genre.
- **Single pass (no ping-pong) + one direction check**: limit user touchpoints to **STEP 1 (batched questions)** and **STEP 3 (direction check)** — don't keep asking back in between. But **never skip STEP 3 (direction check) before writing the GDD**: don't just flash the grounding result and jump straight to the GDD. Once the direction is confirmed, produce the deliverable immediately.
- **Standardized deliverable**: drop the result into the fixed GDD structure ([`references/gdd-template.md`](references/gdd-template.md)) as markdown, so the implementation skills can pick it up and carry it to an MVP.
- **Single home for "later"**: a GDD covers ONLY its own milestone. Anything beyond it — cut features, later-milestone ideas, a "let's do that someday" request mid-discussion — is recorded **the moment it surfaces** in the standing **milestone roadmap** (`Docs/<game>-Roadmap.md`: a future-milestone slot, or its Backlog when the timing is unknown), and **never parked in the GDD**. One home, no duplication: the roadmap owns everything beyond the current milestone; the GDD owns everything inside it.
- **Carry the project forward**: after each deliverable, **propose the next step first** (e.g., "Shall I write the Phase 1 detailed plan next?"). Proceed if the user wants it, stop if they say stop — it's a suggestion, not a push. (This differs from endless mid-document ping-pong — it connects the flow *between* deliverables.)
- **Decision gates = selectable choices, not free text**: at each user decision gate — **STEP 3 direction check**, the **Phase handoff** (implement now vs write the next-Phase plan), and the **soft Phase gate** — present the options as a **structured selectable choice** via the agent's multiple-choice UI when available (e.g., Claude Code's `AskUserQuestion`), so the user clicks an option instead of typing a free-text reply. Mark the recommended option but don't force it; if the agent has no such UI, fall back to a clearly enumerated prose choice.

## On startup — check for an existing GDD (resume / new / blocked)
A build spans multiple sessions and **milestones — each milestone is one GDD**. Where things live (all project-root, outside RootDesk, to survive `refresh_workspace`):
- **Active** GDD + Phase plan → `Docs/`.
- **`Docs/<game>-Roadmap.md`** → the game's **standing milestone roadmap** (vision · release criteria · one slot per milestone · Backlog): the cross-milestone direction, created with the M1 GDD, permanent (never archived). It is **not** a GDD — the active milestone's contract stays in its `-M<n>-GDD.md`.
- **Completed** GDD → `Archive/` (on milestone completion).
- **`Archive/As-built.md`** → the world's running implementation record: a curated current-state map kept by the skill, an **AI / handoff reference, not a user-facing planning doc** (maintained by the [`references/build-management.md`](references/build-management.md) cleanups; seeded via *Brownfield* below).

**Before running the flow below, detect the plan files** — check **both** `Docs/` and `Archive/` for a `<game>-M<n>-GDD.md`:
- **List the full contents** of those directories (capital `Docs/` / `Archive/`) — a directory-level listing that returns *everything* in them (e.g. the agent's file-lister / `Glob` with `Docs/*`) — then match names ending in `-GDD.md` / `-Phase<N>.md` **yourself, from that listing**. Do **not** detect via a narrowed pattern or content search (a `*-GDD.md` glob or grep is case-sensitive + scope-fragile: `*.md` is top-level only, `docs/` ≠ `Docs/` — a miss silently reads as "no GDD"), and not from memory.
- Conclude **"no GDD anywhere" only from genuinely empty `Docs/` + `Archive/` listings.**
- If **`Archive/As-built.md`** exists, **read it first** for the current-state map; if **`Docs/<game>-Roadmap.md`** exists, read it alongside for the cross-milestone direction (never mistake it for the active GDD).
- Normally there's at most one active GDD; **if several exist, ask which game this is about first**, then apply the rules below.

**Gating rule — a "continue" / "next task" / resume request only acts when a plan exists in `Docs/` or `Archive/`** (a `<game>-M<n>-GDD.md` / `<game>-M<n>-Phase<k>.md`, or a prior milestone + `Archive/As-built.md`). If **nothing exists in either**, the request must **not** be treated as a resume and must **not** auto-start the STEP 1 questionnaire — instead: if the request is a **continue / "what next" intent, or the user says they're building on their own existing work** (not a fresh template start), go to *Brownfield* below; otherwise (a new-game or unclear intent) tell the user there's no saved plan and ask whether to start a new game (then STEP 1). **Don't infer brownfield from workspace files** — templates ship samples, so a non-empty workspace is not evidence of prior work.

**If a GDD exists, judge how much is actually done from the GDD / Phase-doc task states (`⬜/🟡/✅`) — NOT from workspace files** (templates ship with `.mlua`/`.model`/`.ui`, so file presence is not a reliable progress signal). Then branch:

- **The user explicitly asked to continue/resume** → **resume** (steps below), regardless of state.
- **Every roadmap & Phase item is `⬜`** (a plan with zero progress) **AND it is the game's first milestone** — no same-`<game>` GDD in `Archive/` **and** the GDD's number is `M1`. (Check this before offering: an archived prior milestone, or an `M2+` number on the current GDD, is by itself proof that this world already contains built work — the zero-progress plan merely sits *on top of* it → that is the `🟡/✅` case below, **not** this one.) → offer a **selectable choice** (see Core principles): **① continue this plan (*[game]*)** / **② discard it and plan a new game**. If they choose discard, **first state exactly which files will be removed** — `Docs/<game>-M<n>-GDD.md`, that game's `Docs/<game>-M<n>-Phase<k>.md`, **and that game's `Docs/<game>-Roadmap.md`** (it was created with the M1 GDD, so it is discarded with it — leaving it behind would feed the discarded game's direction into the next planning session) — only those — delete them, then start fresh from STEP 1.
- **Any item is `🟡` or `✅` — or the GDD is all-`⬜` but a prior milestone of this game exists** (same-`<game>` GDD in `Archive/`, or an `M2+` number) — i.e., there is in-progress or already-built implementation in *this* world → do **NOT** discard and do **NOT** plan a new game here. **Inform** the user that this world already has a prototype underway, and that a genuinely new game must be built in a **new world** — this skill **cannot create a world**, so the user creates one and runs the skill there — then **stop**. (If they actually meant to continue this one, resume instead. Reworking a zero-progress next-milestone *plan* is a plan revision on top of `Archive/As-built.md` — still this game, never a new one.)
- **When the state is unclear** (missing or inconsistent Phase doc, ambiguous progress) → treat it as the `🟡/✅` case (don't discard, don't build over).

**To resume** an existing plan:
1. **Read the existing docs FIRST** — `Docs/<game>-M<n>-GDD.md` (+ **every** `Docs/<game>-M<n>-Phase<k>.md` present — several can coexist while earlier Phases await user tests, and their checklists may hold states §6 doesn't have yet; + `Docs/<game>-Roadmap.md` for the cross-milestone context). Do **not** re-run STEP 1–4; the plan already exists.
2. **Reconstruct state**: the GDD's `Stage` line + roadmap `⬜/🟡/✅`, any `🟡 Implemented (untested)` items (flag these for re-test / user confirmation), and recent `§9 Plan changes`.
3. **If the resumed work will touch implementation or any checklist state, Read [`references/build-management.md`](references/build-management.md) in full now** (see the hard gate under STEP 6) — resuming is the read-chain's weakest point, because the docs were written by past sessions. While reading the docs, also **modernize stale AI notes**: if a `Docs/` GDD/Phase doc's header AI-note predates the current templates (e.g. it lacks the build-management pointer that [`references/gdd-template.md`](references/gdd-template.md) now embeds), update that note line to the current template text as part of reconciling — old docs must not keep steering future sessions down an outdated read-chain.
4. **Briefly restate where things stand** — done so far / current Phase / what's still untested / next step — then continue from there.
- If `Docs/` has **no GDD** but `Archive/` has a completed one (+ `Archive/As-built.md`), the previous milestone finished. **Confirm** whether to start a **next milestone** — a new GDD in `Docs/` (`<game>-M<n+1>-GDD.md`, next number per STEP 5), planned **on top of the milestone roadmap's next slot (+ its Backlog) and `Archive/As-built.md`** — rather than assuming a brand-new game. (Before writing it, **reconcile the record against the workspace — see *Reconcile before a next milestone* below**. Writing the new GDD **promotes** that roadmap slot: its one-line theme expands into the GDD; the roadmap keeps only the one-liner.)
- **Phase-doc lifetime**: a Phase doc is deleted only when that Phase is **all-`✅`** (its stage cleanup) — the GDD roadmap is then its record. So the docs still in `Docs/` are the **current** Phase plus any earlier Phase parked at a **`⏳ user-test boundary`** (items still `🟡`, awaiting the user's test), and several can legitimately coexist. A leftover doc whose items are all `✅` is the one case that signals a missed cleanup.
- The `Docs/` files are the **source of truth across sessions**: the previous session's chat context does not carry over, so anything not written into the GDD/Phase docs is lost (which is why decisions and states are recorded there).

**No GDD in `Docs/` nor `Archive/` → before anything else, *classify the workspace, then decide* — mandatory, including for an explicit "new game" request: never jump straight to STEP 1 without first checking what's already built here.** (*Brownfield* = continuing the user's *own* already-built world; it is **user-driven, never inferred from raw file presence** — but the classification itself is **not** optional.) When real work exists, surface it; how prominently to offer brownfield is then decided by the user's *intent* (below), not the workspace.

A non-empty workspace is **not** a brownfield signal — a fresh template already ships scaffolding. **Treat known starter items as *zero progress*** (a known set, **not exhaustive** — template versions change and other templates differ; this is "things known to be scaffolding," not a complete manifest): tile dataset `RectTileData_Henesys`; `@Logic` `UIPopup`, `UIToast`; `@Component` `Monster`, `MonsterAttack`, `PlayerAttack`, `PlayerHit`; the **template monster-AI FSM sample** — `StateComponent` scripts `StateChaseMonster` / `StateMoveMonster` / `StateTypeChase` / `StateTypeWander`, condition scripts `ConditionHasTarget` / `ConditionIsAlive` / `ConditionIsDead` / `ConditionNoTarget`, the `.stateset`s `StateSetChaseMonsterAI` / `StateSetMoveMonsterAI`, and the `Global/` monster models `ChaseMonster` / `MoveMonster` (all shipped by the template into `RootDesk/MyDesk/` + `Global/` and wired into the `*Template` maps — their presence is **not** user-built monster AI); plus the always-present `Global/` defaults — DefaultPlayer, WorldConfig, the starter map.
- **Workspace ≈ only starter items (or less)** → fresh project → **proceed to STEP 1, no brownfield prompt.**
- **Work clearly *beyond* the starter items** (custom-named systems / maps / datasets / scripts suggesting real implementation) → a real game may be in progress. **How prominently to offer brownfield is decided by the user's *intent*, not the workspace:**
  - **Continue / "what next" intent** ("what should I do next?", "continue", "where were we?") → continuing the existing work *is* the natural reading → offer **brownfield as the recommended option** (alongside: start a separate new game; or just re-check / improve one specific system).
  - **Explicit new-game intent** ("I want to make a new game") → **honor it: the new game is the default / recommended choice.** Offer brownfield only as the **last, non-recommended** option (*"…or are you actually continuing a world you've already built?"*) — a safety-net, never recommended, never a mandatory fork that overrides what the user asked.
  - An explicit "build on my existing work" request → straight to the survey.
  Brownfield runs only if the user actually picks it.

When brownfield is chosen, don't plan in a vacuum — **light structural survey** (`map/` + `RootDesk/MyDesk/` — systems · models · datasets · UI; *structure only, not a line-by-line code read*; deep inspection is msw-general's job), present *"here's what I see already built — correct?"* with `⚠️confirm`, then **seed `Archive/As-built.md`** and plan the first milestone **on top of** the existing world (the milestone roadmap is created with that milestone's GDD as usual — STEP 5).

**Reconcile before a next milestone** — when planning a new milestone on top of `Archive/` records (arrived from startup, or just after completing one): `Archive/As-built.md` (or a legacy handoff note) is a **starting hint, not ground truth** — work may have happened in other sessions / manual edits without updating it. **Before writing the new GDD**, run the same light structural survey as *Brownfield* above, but to **verify** the record (not discover from scratch): check the **area the new milestone will touch** — plus a quick scan for obviously-untracked major systems — against what the record claims. If it has **drifted**, **surface it and reconcile with the user first**, **update `Archive/As-built.md`** to match reality, *then* plan on top. This stops a whole GDD being written on a stale premise and the drift only surfacing mid-implementation.

## Flow

### STEP 1 — Guided questions (batched)
Don't re-ask what the user already gave; batch only the gaps:
1. **Genre / reference** — what's the feel? Any similar game? (If unsure, start from "what kind of fun do you want?")
2. **Core fun / core loop** — what do you repeat in one session? (e.g., kill enemies → grow → stronger enemies)
3. **Target · platform** — PC/mobile? Solo/multi?
4. **Scope (first build)** — a quick prototype or something bigger? Roughly how many maps / how much content?
5. **Must-haves / cuttable**

Batch into ~5 questions. If the user says "you decide," proceed with reasonable defaults but **state the assumptions**.

### STEP 2 — Catalog grounding + feasibility check
Read [`references/genre-catalog.md`](references/genre-catalog.md) and:
- Find the **closest genre(s)** to the user's idea.
- Pull that genre's **recommended map type** and **core mechanic tags**.
- Pull the genre's **`MVP:` slice hint** (the smallest playable slice — seed for the scoped-down first build and STEP 4's Phase 1) and **`Growth:` axes** (what a finished core typically adds next — feeds later Phases and future milestones). Adapt them to the user's idea; they are hints, not fixed specs.
- **Read the `build-effort` hint** (Low/Medium/High) and gauge the user's ambition. If it's High-effort or the user is asking for a lot at once, say so plainly and **propose a scoped-down first build** (one map · core loop only — start from the genre's `MVP:` hint) that keeps the same fun, with the rest going to later Phases or the milestone roadmap — regardless of genre.
- If needed, pick and combine mechanic tags into a one-line concept.

### STEP 3 — Direction check (user confirmation gate) ⚑ Do not skip
**Always get the direction confirmed by the user before writing the GDD.** Briefly show the grounding result and **don't jump straight to the GDD** — genre and map type decide the whole stack, so if you write the entire GDD on a wrong choice you have to redo all of it.

**Present briefly and ask** the user:
- **Recommended direction**: the matched *sub-genre(s)* (1–2 candidates) + **recommended map type ↔ Body** (e.g., RectTile + `KinematicbodyComponent`) + **build-effort hint (Low/Medium/High)** + **one-line concept**.
- If it's High-effort or the user is over-scoping, present a **scoped-down first-build (MVP) option** alongside — the same fun in a smaller first slice, with the rest routed to later Phases / the milestone roadmap.
- Then ask, presenting the options **as a selectable choice** (see Core principles): **"Shall I build the GDD in this direction? Or are there other candidates / changes?"**
- **Only after the user confirms (or chooses)** move to STEP 4. (If they explicitly say "you decide," lock in the recommendation but state in one line what you chose.)
- Map type ↔ Body is nailed down here ([`references/msw-mapping.md`](references/msw-mapping.md)). Getting it wrong causes "doesn't move" / `[LEA-3004]` silent failures in implementation. It is *applied* at setup by **building in a map that already has this type if one exists** (e.g., a per-type template); otherwise the user sets it in Maker. The AI never switches a map's type itself (see STEP 5).

### STEP 4 — Produce the GDD/roadmap
**In the direction the user confirmed in STEP 3**, write markdown in the [`references/gdd-template.md`](references/gdd-template.md) structure:
**one-line concept / key-decisions table / core loop / core systems / system↔MSW mapping / Phase roadmap checklist / milestone-scoped decisions.**
- For the system↔MSW mapping, use [`references/msw-mapping.md`](references/msw-mapping.md) to connect each system to `@Logic`/`@Component`/`.model`/`.ui`/dataset (UserDataSet).
- Split the roadmap into stages **starting from the smallest playable build (Phase 1)**, like "move, hit, and it breaks." The matched genre's `MVP:` hint (STEP 2) is the natural Phase 1 seed; its `Growth:` axes suggest the later Phases. Track each roadmap item with three states — `⬜ Not started` / `🟡 Implemented (untested)` / `✅ Tested` (all start ⬜; state rules → [`references/build-management.md`](references/build-management.md)).
- **The roadmap checklist holds only items *required* for a handoff-ready prototype — and all of them must reach `✅`.** Polish / nice-to-have / later work goes to the **milestone roadmap** (`Docs/<game>-Roadmap.md` — a future-milestone slot, or its Backlog) **at planning time**, never as a checklist item and never parked anywhere in the GDD (see *Single home for "later"*). Discriminator: *would dropping it leave the full-implementation team a more incomplete base?* → required (checklist); *does production polish it anyway?* → milestone roadmap.
- For data-heavy games, state "data-driven (UserDataSet/CSV is the source of truth)" in the roadmap. Early Phases may hardcode values for speed, but once the value-set grows or stabilizes, **plan the hardcoded→dataset (UserDataSet/CSV) migration by horizon**: within this milestone → a later-Phase task in GDD §6; beyond it → a **milestone-roadmap entry** (slot or Backlog; §7 keeps only a pointer — an intent written only in GDD prose is buried when the GDD archives) — so balancing/content no longer needs code edits. Include this **only when warranted** (many tunable values · balance iteration expected · content scaling), not for a handful of constants. The dataset itself is authored via `msw-general` (see its `references/dataset.md`).
- **Coverage check before saving the GDD**: the §6 Phases must *collectively deliver* the §1 one-line concept (and, for M2+, the promoted roadmap-slot line) — trace each capability those lines claim to the checklist item(s) that will implement it. A claim with no item is a planning hole that no later rule can catch (unplanned tasks leave no `⬜` behind). **Verification limits don't shrink scope**: a flow the AI can't verify alone (real-multiplayer matches, on-device feel, commerce) is still planned as tasks — they will simply end `🟡 needs-user-test` — never silently left out because it can't be auto-verified. If the user agrees to exclude a claimed capability instead, reword §1 / the roadmap slot so the docs stop promising it.
- **If the project ships placeholder/sample entities**: include a task to **remove them before the prototype hands off to full implementation** so they don't carry into the real build. **Scope = the WHOLE project, not just the chosen build map** — **any** map in the project may carry its own samples (template-derived maps often do; some ship none), so the task's done-criteria is "**every map inspected and clean**": first **enumerate ALL maps** (a full `map/` listing), then inspect each; one map scanning clean is NOT evidence for the others. **Don't assume fixed names — identify each map's samples by inspection** (often `*Template`-named idle/move/chase monster samples, but names vary by template). They're useful early as AI-pattern references; actual deletion happens during implementation, via MapBuilder removing them from the `.map`. **Unused template maps are handoff residue too**: at handoff, **ask the user whether to delete or keep** each template map the game doesn't use (never delete unconfirmed) — and decide that **before** sample-cleaning them (don't clean a map about to be deleted); "every map clean" then applies to the maps that remain.

### STEP 5 — Save + next step
- Save the produced markdown **under the project-root `Docs/`** as **`Docs/<game>-M<n>-GDD.md`** — **`<game>`** is a short ASCII (English/romanized) slug (**never the raw non-English title**; CJK/non-ASCII filenames break globbing and cross-platform paths — e.g. `MapleIdle-M1-GDD.md`, not the raw CJK title) and **`<n>` is the milestone number**. **Milestone number**: the first milestone is **M1**; a later milestone takes **(the numerically highest existing `-M<n>-GDD.md` across `Docs/` + `Archive/`) + 1** — *parse the number, don't sort lexically* (so M9 → M10, not M2). The doc's **content stays in the user's language**; only the *filename* is ASCII. Phase docs inherit the same **`<game>-M<n>-` prefix** (STEP 6). Collect all planning deliverables (GDD · phase detail plans) here. Create the folder if missing. Kept as a file, the implementation skills can pick it up and carry it to an MVP.
- ⚠️ **Do NOT save under `RootDesk/`.** Maker's `refresh_workspace` cleans up (deletes) non-MSW files (.md etc.) under `RootDesk/`, so files there **vanish** when a refresh runs during implementation/playtesting. Always keep them outside RootDesk (project-root `Docs/`).
- **Create the milestone roadmap alongside the M1 GDD** — `Docs/<game>-Roadmap.md` (no `M<n>` in the name; one per game; permanent, never archived). Follow the **'Milestone roadmap template'** in [`references/gdd-template.md`](references/gdd-template.md): one-line **vision** + **release criteria** (what must be true to call the game releasable — criteria, not a feature dump), **one slot per milestone** (M1 = pointer to the active GDD; future M's = one-line theme + assigned features), and a **Backlog** for wanted-but-unslotted items. **Sort everything STEP 2–3 cut from the first build** (Growth axes · trimmed features · the user's "later" wishes) into a future slot or the Backlog. **Scale it to the game**: a single-milestone game's roadmap is a few lines (M1 = release). For a later milestone (M2+), don't create anew — **update** the existing roadmap (promote that slot).
- **When the base GDD is done, propose naturally first**: "Shall I write the **Phase 1 detailed plan** next?" → if the user agrees, go straight to STEP 6.
- Other branches to offer: if numbers/data-heavy, go to dataset design; if screen-heavy, author UI with `msw-ui-system`; to build right away, start implementation with `msw-general`·`msw-scripting`. The default recommended flow is 'detail Phase 1 → implement.'
- **Apply the map type — build in a matching map if one exists, otherwise the user sets it**: the prototype must be built in a map whose `TileMapMode` already equals the decided type. At setup, check existing maps with `MapBuilder.read().getTileMapMode()`, then:
  - **If a map already matches** — e.g., the project keeps **per-map-type template maps** (one TileMap / RectTile / SideView each) — **build the prototype in that map**, no switch needed (the destructive switch is avoided). *This shortcut applies only when such a matching map/template exists.*
  - **If no map matches** — no per-type template, or starting from scratch — fall back to the standard policy: **the user switches a map's type in Maker** (msw-general `tile.md`; the AI verifies with `getTileMapMode()` afterward).
  - **Either way, the AI never switches a map's `TileMapMode` itself.** (If built in a template, its sample `*Template` entities are removed later per the cleanup rule.)
  - **Rename the build map EARLY when it's a template**: if the prototype will live in a `*Template`-named map, plan a **Phase 1 task to rename it to a game-appropriate ASCII name** *before* real building starts — map references (sector registration · portals · `GetEntityByPath` paths · active-map) accumulate as Phases progress, so the rename is nearly free at Phase 1 and costly at handoff; and a game living in a `*Template`-named map pollutes the template-vs-game classification this skill itself relies on. Done-criteria: file renamed + every reference updated + refresh + entry verified. Mechanics belong to the implementation skills; **if a reference lives in read-only config (`Global/`), that part is the user's Maker action** — same policy as the `TileMapMode` switch.
  - **Switch the active map to the target map before building** (once it's fixed by either case above): move Maker's **active (open) map** to it with `maker_move_map` (AI-doable) so entity/tile edits and screenshots land on the right map. (This is **not** the forbidden `TileMapMode` switch.) Don't skip silently — otherwise the work targets the wrong map.

### STEP 6 — (Optional) Per-phase detailed plan
The base output (STEP 4) goes up to *the full roadmap + per-Phase checklist*. If the user wants the detailed plan for a specific Phase (e.g., "write the Phase 1 detailed plan," "break down stage 1"), generate an additional **detailed-plan markdown** that expands that Phase's checklist items in more depth.
- For each task, write: **goal · required systems/components** (`references/msw-mapping.md`) **· data (UserDataSet) · UI · done (verification) criteria · dependencies · skills to reference (predicted — skill + its reference doc, `references/msw-mapping.md` §4)**. Also record, near the top of the Phase doc, a **"Skills to reference (this Phase)"** summary — the implementing session reads it first.
- **Generate a status checklist** alongside the tasks — every item starts **Not started** and moves through three states as work proceeds:
  - `⬜ Not started` — not implemented yet.
  - `🟡 Implemented (untested)` — implementation done, not yet verified.
  - `✅ Tested` — implementation AND verification both done.
- Follow the **'Per-phase detailed plan template'** in [`references/gdd-template.md`](references/gdd-template.md).
- Save: `Docs/<game>-M<n>-Phase<k>.md` (same **`<game>-M<n>-` prefix** as the milestone's GDD — see STEP 5; `<k>` = phase number; project-root `Docs/`, **outside RootDesk** — avoids refresh deletion).
- This too goes only up to *detailed planning* — writing actual code (.mlua/.model etc.) is still the job of the implementation skills (msw-general/msw-scripting etc.); those skills update the checklist states as they implement and verify.

#### Build management (implementation-time rules) → [`references/build-management.md`](references/build-management.md)
The full rules for executing the plan — task-state handling, Phase/milestone completion procedures, and mid-development plan revisions — live in **[`references/build-management.md`](references/build-management.md)**. Read it **in full BEFORE implementing planned tasks, updating any checklist state, completing a Phase or milestone, or applying a plan revision** (pure planning sessions don't need it). **Hard gate: if you are about to edit any `⬜/🟡/✅` marker, run a Phase/milestone completion, or archive/delete a plan doc, and have NOT Read [`references/build-management.md`](references/build-management.md) in full THIS session — STOP and read it first.** Having loaded this SKILL.md (or having read the reference in an earlier session) is not a substitute. Non-negotiable invariants, restated here because breaking them corrupts the record:
- States are **`⬜` / `🟡` / `✅` ONLY**, updated in the Phase doc **immediately per task** — never batched to the end, never only in an ephemeral tool, never with invented markers.
- **Phase completion and milestone completion each have a MANDATORY cleanup procedure** ([Completed-stage](references/build-management.md#completed-stage-cleanup-mandatory) · [Milestone-complete](references/build-management.md#milestone-complete-cleanup-mandatory): mirror states into GDD §6 → As-built → roadmap → delete/archive). Never delete a Phase doc or archive a GDD without running it. **Completion is measured against the milestone's stated vision, not just the checklist** — the milestone-complete procedure starts with a vision-coverage check, and a milestone whose remaining items all await user tests is **`⏳ user-test pending`**, never "complete" and never a self-invented label.
- **Plan-change requests route through the revision flow there**; work beyond the current milestone goes straight to the milestone roadmap — and an intentionally stubbed/blocked code path must gain a tracked item the moment it's written.

## Boundaries (what this skill does NOT do)
- It does not write the actual code (.mlua/.model/.map/.ui) — that's the implementation skills' job. This skill **plans and manages the game's build across its milestones** (GDD · milestone roadmap · detailed Phase plans · progress tracking · plan revisions) and hands the code work off to msw-general/msw-scripting etc.
- A major improvement/expansion of an already-built, shipped world is out of scope (this skill plans the game's build — a new game and its successive milestones — up to readiness for full implementation).
- Reflect MSW platform rules (map-type↔Body, 1 unit = 100px, SpriteRUID, etc.) in the plan, but follow msw-general's platform references for the exact implementation rules.

## References
- [`references/genre-catalog.md`](references/genre-catalog.md) — 3 map types · build-effort baseline · 71 genres (build-effort hint · recommended map type · core mechanics · per-genre `MVP:`/`Growth:` hint line) · ~180 mechanic tags. **The heart of grounding — always read it in STEP 2.**
- [`references/gdd-template.md`](references/gdd-template.md) — the GDD output structure + milestone-roadmap template (STEP 5) + per-phase detailed-plan template (STEP 6) + As-built log template.
- [`references/build-management.md`](references/build-management.md) — implementation-time rules: task-state handling · Phase/milestone completion cleanups · plan-revision flow. **Read in full before implementing tasks or touching checklist states** (not needed for pure planning).
- [`references/msw-mapping.md`](references/msw-mapping.md) — map-type↔Body table + game-system → MSW component/skill mapping cheat sheet.