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.