msw-planning

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` 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`) 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` 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` 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` 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`). 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` 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` 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`).
• 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`: 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`.
• 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`

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 · Milestone-complete: 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` — 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` — the GDD output structure + milestone-roadmap template (STEP 5) + per-phase detailed-plan template (STEP 6) + As-built log template.
• `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` — map-type↔Body table + game-system → MSW component/skill mapping cheat sheet.