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.
• 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/.
• 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 (see STEP 6 + Brownfield below).

Before running the flow below, detect the plan files — check both Docs/ and Archive/ for a <game>-GDD.md:

• List those directories (capital Docs/ / Archive/) and match files ending in -GDD.md / -Phase<N>.md — not by glob/grep (case-sensitive + scope-fragile: *.md is top-level only, docs/ ≠ Docs/) 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.
• 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>-GDD.md / <game>-Phase<N>.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) → 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>-GDD.md + that game's Docs/<game>-Phase<N>.md (only those) — delete them, then start fresh from STEP 1.
• Any item is 🟡 or ✅ (real progress — there is in-progress 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.)
• 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>-GDD.md (+ the current Docs/<game>-Phase<N>.md if present). 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. 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 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.)
• Completed Phases have no detail doc (deleted on completion by rule) — the GDD roadmap is their record; only the in-progress Phase has a Docs/<game>-Phase<N>.md.
• 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 (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.

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.
• 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) that keeps the same fun, with the rest deferred to later Phases — 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 deferred.
• 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 / decided·deferred items.

• 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." Track each roadmap item with three states — ⬜ Not started / 🟡 Implemented (untested) / ✅ Tested (all start ⬜; see STEP 6).
• 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 in §8 (Deferred) at planning time, neve

...