references/build-management.md
# Build Management — implementation-time rules (states · cleanups · plan revisions)
**When to read**: in full, BEFORE implementing planned tasks, updating any `⬜/🟡/✅` state, completing a Phase or milestone, or applying a plan revision. **Not needed for pure planning sessions** ([`../SKILL.md`](../SKILL.md) STEP 1–5) — don't load it there.
These rules are what keep the plan documents trustworthy across sessions: the previous session's chat context does not carry over, so anything not written into the docs — in the right doc, at the right moment — is lost.
## Which doc is the working truth
- While a Phase is active, **its Phase doc's checklist is the live record** for that Phase's task states; GDD §6 is the durable mirror, reconciled at the defined moments (soft-gate crossing · reaching a `⏳ user-test boundary` · last-`✅` cleanup · the archive gate). If they disagree at a checkpoint, reconcile **from the Phase doc** then and there — never let the disagreement survive past a checkpoint.
## Executing a Phase
- **Implement by Phase unit (continuous), not task-by-task**: when the user asks to implement a Phase, work through its tasks **in dependency order, end to end** — verify each inline, update its `⬜→🟡→✅` state, and keep going. **Don't stop after one task to ask whether to continue.** Pause only at: the Phase is **done as far as the AI can take it** — either **complete** (every item `✅`) or at a **⏳ user-test boundary** (only AI-unverifiable items left `🟡`); a **genuine blocker** (a decision or resource only the user can give, a user-test that gates the next task, or an unresolved failure); or a **context/output limit** (then do as much as possible, stop at a clean checkpoint, and state exactly what remains). ⚠️ **A `⏳ user-test boundary` is NOT completion**: [Completed-stage cleanup](#completed-stage-cleanup-mandatory) runs only on all-`✅`, so at this boundary the Phase doc **stays in `Docs/`** and is not deleted — mirror the current states into GDD §6, tell the user exactly which items need their test, and reflect their report back into the checklist (`✅`, or back to fixing). Never call it "complete", and never invent a label for it (the same closed-vocabulary rule as the milestone-level `⏳ user-test pending`). At a pause, give **one batched report**, not a per-task check-in. ("Phase unit" means continuous progress to a natural checkpoint — not necessarily one turn; implement everything implementable first and collect visual/feel/on-device user-tests to surface together at the Phase boundary.)
- **Update each task's state immediately as you build it — mandatory, not deferrable.** Per task, in order: write the code → **right away mark that item `🟡 Implemented (untested)` in the Phase doc** (before starting the next task and before verification) → verify → set `✅ Tested` (or send it back to fixing). **Never leave an implemented task at `⬜`** — if its files exist, it is at least `🟡`. **The checklist update comes before any other record**: don't log work into `Archive/As-built.md` (or anywhere else) whose checklist state you haven't updated yet. Don't batch the state updates to the end (that's how a Phase doc ends up all-`⬜` while the workspace is full of code, blocking the next session from knowing what's done). Tracking state only in an in-session/ephemeral tool (e.g. the harness's own TaskCreate/TaskUpdate list) does **not** count — it is discarded at session end; the Phase-doc checklist is the durable record, so mirror every `⬜→🟡→✅` change into it in the same step.
- **Untestable-by-AI items — be honest**: some items can't be verified by the AI alone (on-device feel, visual/audio judgment, real-player multiplayer, store/commerce — anything needing human eyes or a real client). Do NOT silently mark these `✅ Tested`. Tell the user plainly *which* items you couldn't test and *why*, leave them at `🟡 Implemented (untested)`, and ask the user to test; when they report back, reflect it into the checklist (`✅ Tested`, or send it back to fixing if it failed).
## State-mirroring triggers (Phase doc → GDD §6)
- **The all-`✅` check fires on the LAST `✅`, not later**: the moment a state update makes a Phase's items **all `✅ Tested`**, run **Completed-stage cleanup** (below) right then — before the next task, the next Phase, or its detailed plan. The condition has no other checkpoint, so if you skip it here it never runs. An all-`✅` Phase doc still sitting in `Docs/` means the cleanup was missed — run it on sight.
- **Phase gate (soft)**: if the user asks to start the **next Phase** while some items aren't yet `✅ Tested`, first **tell them which items are still untested**, then offer the choice **as a selectable prompt** (see [*Core principles*](../SKILL.md#core-principles-why-it-works-this-way) in SKILL.md): proceed to the next Phase anyway, or finish testing the untested items first. If the user still wants to proceed, **proceed** — it's a heads-up, not a block. **When proceeding, first mirror the leaving Phase's current per-item states (`🟡`/`✅`) into GDD §6**: §6 may lag only for the *active* Phase, never for a Phase you've moved on from (skipping this is how a GDD ends up all-`⬜` while several Phase docs hold the real states — and resume then misreads the milestone).
- **Mirroring is an in-place edit, never an append**: to mirror into GDD §6, update the existing rows (or rewrite that Phase's §6 block wholesale from the Phase doc) so the block ends with **exactly one row per task** and a Phase header that matches the rows. Never add an updated list next to the old one — duplicate rows with conflicting states corrupt the record worse than a lag would. **Self-heal §6 damage on sight**: duplicate task rows, markers outside `⬜/🟡/✅` (e.g. `⏭️`), or a Phase header whose "(k/n ✅)" count contradicts its rows get fixed the moment you notice them, **sourcing truth from that Phase's live doc**. ⚠️ **If the Phase doc is gone, do NOT reconstruct states from anything else** — `Archive/As-built.md` records systems, gotchas and log entries, **not per-task `⬜/🟡/✅`**, so reading states out of it means inventing them. A missing Phase doc means its stage cleanup already ran, which mirrored that Phase into §6 as all-`✅`; so repair is limited to **structural damage** (drop the duplicate row, replace an invented marker with the state its surviving row already carries, recount the header) — never change or fill in a state value that no surviving record evidences. If the structure alone doesn't settle it, state the ambiguity and **ask the user** rather than guessing; corroborating detail (what the As-built log or the workspace shows was actually built) may inform that question, but never silently decides it.
## Deferral & handoff
- **No silent deferral**: every checklist item is required (it wouldn't be in the checklist otherwise), so don't drop one mid-build with a "the prototype doesn't need it" rationale. If an item genuinely turns out non-required, **move it to the milestone roadmap (a future slot or the Backlog) via a plan revision** (user confirmation + GDD §9 log) — never leave it parked as "Deferred" inside the checklist or anywhere in the GDD. **Items moved out by a revision (to another Phase, the roadmap, or dropped) are REMOVED from the leaving checklist** — the §9 entry is their record; `⬜`/`🟡`/`✅` are the ONLY states, don't invent markers (`⏭️` etc.) to park them in place.
- **A stub or dead-end in code is a deferral too — it needs a tracked item the moment it's written**: an intentionally blocked code path (a "not supported yet" guard, a bootstrap that skips a case, a button that only shows an info message) defers real scope, so at the moment you write it, that scope must gain a home — a checklist task in the current or a later Phase (BOTH docs, per the revision flow below), or a milestone-roadmap entry when it lands beyond this milestone. A code comment, an in-game message, or a note inside another item's line is **NOT** a tracking location. Corollary — **no `✅` with an untracked "-followup"**: an item may not be marked `✅` while its own notes push part of its scope to a follow-up that exists nowhere; create the follow-up item first (checklist or roadmap), then mark `✅`.
- **Phase-detail handoff**: after finishing a Phase detailed plan, offer the next step **as a selectable choice** (see [*Core principles*](../SKILL.md#core-principles-why-it-works-this-way) in SKILL.md) — **implement this stage** vs **write the next Phase N+1 detailed plan**.
## Completed-stage cleanup (mandatory)
Runs **only when a Phase's items are all `✅ Tested`** — at a `⏳ user-test boundary` (some items still `🟡`) it does **not** run and the Phase doc stays put (see [*Executing a Phase*](#executing-a-phase) above). Once they are all `✅`, in order — (1) **mirror the Phase's final states into the GDD §6 checklist** — mark the Phase done AND set each of its §6 items to `✅` (**only `✅` is written here**: this procedure runs at all-`✅`, so a `🟡` appearing anywhere means you are not at completion — stop and take the `⏳ user-test boundary` path instead), **adding any items the Phase gained through revisions** so §6 lists every task actually run (cross-check against the Phase doc *before* it is deleted — §6 is the surviving record; a GDD whose Stage says complete while §6 reads `⬜` is a self-contradiction the next session inherits); (2) **distill its as-built facts into `Archive/As-built.md`** (update the current-state map + one Phase entry of **≤15 lines** — what/why/gotchas only, no verify dumps or file lists (git keeps those); a **recurring** issue updates its Standing-issues row — Count + last-seen — instead of gaining a new entry, and Count ≥ 3 means propose a root-cause task; see the [As-built log template](gdd-template.md#as-built-log-template) guide); (3) **update the milestone roadmap's active-slot marker** to exactly `🔨 active (Phase k/n done)` (Status cell only — no percentages, no free-text status, and the roadmap's `Last updated` stays date-only); (4) **delete that Phase's detailed-plan md (`Docs/<game>-M<n>-Phase<k>.md`)** — a transient artifact that must not linger. Nothing is lost: the GDD roadmap keeps progress, `Archive/As-built.md` keeps the as-built record. (Always do 1–3 *before* deleting.)
## Milestone-complete cleanup (mandatory)
**Step 0 — vision-coverage check (before ANY completion claim)**: re-read the GDD **§1 one-line concept** and the roadmap's **`M<n>` slot line**, and trace **each capability they claim** to the `✅` checklist item(s) that implement it. All-`✅` alone is NOT completion — a checklist can be fully green while the milestone's stated vision is not built, because **tasks that were never planned leave no `⬜` behind** (the decomposition itself can have holes, e.g. "online PvP" milestones whose phases built infrastructure but no task ever made two humans actually meet). A claim with no implementing item is a **planning hole**: surface it to the user and either add the missing tasks (revision flow — the milestone stays open), or, with the user's explicit agreement, narrow the milestone's stated scope (reword the roadmap slot line + GDD §1, log in §9). Never resolve the mismatch by relabeling "done" with softer words.
Once **every** GDD roadmap item is `✅ Tested` — **verified by READING GDD §6 itself, never from the Phase doc or session memory**; the final Phase's completion does NOT skip its own Completed-stage cleanup — if §6 still shows `⬜`/`🟡` for that Phase, run the stage cleanup (mirror states into §6) first, and only then proceed — finish up: (1) set the GDD's `Stage` to complete; (2) **finalize `Archive/As-built.md`** so its current-state map reflects the whole milestone — and **compact the Log**: compress this milestone's entries into ONE `M<n> complete — summary` entry (≤15 lines) and delete its per-Phase/per-fix entries (git + the archived GDD + regression docs keep the detail), refresh the Standing-issues table, and if the file exceeds ~500 lines / ~30KB compact on sight (it must stay readable in one full Read — resume depends on it); (3) **update the milestone roadmap** — mark `M<n>` `✅ done` (one-line summary; the archived GDD is the full record), promote/re-order the remaining slots, and **review the Backlog with the user** (slot, keep, or drop each item); (4) **move** `Docs/<game>-M<n>-GDD.md` into **`Archive/`** (project root, outside RootDesk; create if missing) — archived, not deleted, as this milestone's record. ⚠️ **Never overwrite an existing archived GDD**: if that name already exists in `Archive/` (shouldn't, under the `M<n>` rule), it signals a numbering error — **stop and flag it, don't silently rename**. **Leave `Docs/` in place** (the next milestone reuses it for a new GDD; the roadmap stays there permanently). Phase docs are **deleted by their own stage cleanup — never moved into `Archive/`**; if any still sit in `Docs/` at this point, their cleanup was missed — run it first. **A Phase doc found inside `Archive/` is residue of a missed cleanup too — heal on sight**: verify its final states are mirrored in the (archived) GDD's §6 (mirror them now if not), then delete the doc. Verify all items are truly `✅` first, then tell the user the milestone is complete + where things are. **A later milestone** follows the next-milestone flow in [*On startup*](../SKILL.md#on-startup--check-for-an-existing-gdd-resume--new--blocked) (new GDD promoted from the roadmap's next slot, reconcile first).
## Milestone blocked on user testing (`⏳ user-test pending`)
When everything the AI can do is done but items remain `🟡` awaiting user tests (real-multiplayer flows, on-device feel, commerce — every remaining non-`✅` item carries a "needs user test" note), the milestone is **NOT complete and gets no invented label** — statuses are a **closed set**, so never coin hybrids like "✅ code-complete". Do exactly this instead:
1. Run **Step 0 (vision-coverage check)** above now — user testing can only confirm what was built; it cannot fill a planning hole, so find holes *before* parking the milestone on the user.
2. **Mirror all current states into GDD §6** (in-place), including every Phase you're stepping away from.
3. Update `Archive/As-built.md`, stating **precisely which items await which user tests** — and what was NOT built, if Step 0 narrowed or flagged anything.
4. Set the roadmap's `M<n>` Status cell to exactly **`⏳ user-test pending`**. The GDD `Stage` stays active with a note (e.g. `Phase 3 — awaiting user tests`), the GDD stays in `Docs/`, and Phase docs holding `🟡` items stay in `Docs/` (their cleanup fires only on all-`✅`).
5. Tell the user **exactly which tests to run and what to look for**; when they report back, reflect the results (`✅ Tested`, or back to fixing) and re-enter the normal completion path above.
## Revising the plan mid-development (add / remove / change a rule)
Once the GDD exists and you're building phase by phase, the user may request changes to the plan. Handle the three kinds — **add**, **remove**, **modify** a planned rule/task — without breaking consistency with what's already built.
**First, check the horizon**: if the request adds work **beyond this milestone** ("later", "someday", "in the full version"), it is **not a GDD revision at all** — record it into the **milestone roadmap** right away (a future slot if the timing is known, the Backlog if not; adding an item is always allowed, no waiting for a controlled moment), confirm the placement with the user in one line, and stop; no checklist/state impact, **no §9 entry** — the roadmap is that item's record. Only changes to **this milestone's** plan go through the steps below. ⚠️ The dividing line is *this milestone*, not *the future*: work **leaving** the current GDD for the roadmap (a scope cut) **does** get a §9 entry, because it changes this milestone's checklist — the pure-future case above does not.
For any revision:
1. **Classify** it — add a new rule, remove an existing rule, or modify an existing rule.
2. **Locate** what it touches — which GDD section (key decisions / core systems / roadmap / data-driven) and/or which Phase doc + checklist item(s). A GDD prose item (§2/§4/§5/§7) has no state of its own; determine whether it's already built by tracing it to the roadmap/Phase checklist items that implement it, then apply the `🟡`/`✅` impact rules (step 3) to those.
3. **Assess impact honestly *before* applying** — especially when it touches work already built (`🟡`/`✅`):
- **Add**: the new item enters the checklist as `⬜ Not started`. If it belongs to a Phase already marked done, say so and place it in the current/next Phase rather than silently re-opening the done one.
- **Modify**: if the target was `🟡`/`✅`, the built work likely needs redo → reset that item to `⬜` (or `🟡` if only re-testing is needed) and tell the user it must be re-implemented/re-verified.
- **Remove**: if the target was already built, the code must be removed too → flag a removal task for the implementation skill, then drop the item from the plan/checklist.
- Note any **dependent** rules/tasks the change ripples into.
- ⚠️ If it touches a **core decision** (key-decisions table — e.g., map type ↔ Body, solo/multi & `@Sync`), warn strongly: it cascades through the whole stack and can invalidate much of what's built. Confirm before proceeding.
4. **Confirm scope when it affects built/tested work or a core decision** — surface the impact (which states reset, what code to remove, which dependents) and get the user's go-ahead. A pure addition to not-yet-started work can proceed directly.
5. **Apply to the docs** — update the relevant GDD section AND the Phase doc **together**: a task added/removed/modified in a Phase changes **BOTH** that Phase doc's checklist **and** the GDD §6 item list — never just one (an item that exists only in the Phase doc **vanishes** when that doc is deleted on completion; a §9 log entry alone does not put it in the checklist). Set the correct states, and **log the change in the GDD's "Plan changes" section** (type / what / why / impact) so the plan's history stays visible.
6. **Hand off code changes** — writing/removing/altering actual code (.mlua/.model etc.) is the implementation skills' job; this skill updates the plan, checklist states, and flags the implementation/cleanup tasks.
references/gdd-template.md
# GDD / Roadmap Deliverable Template
In STEP 4, write the markdown in this structure. Add/remove sections by game scale, but **always include the bold sections**. Rather than leaving blanks, mark "tentative"/"pending" to keep the decision flow visible (beyond-milestone work never stays in the GDD — it goes to the milestone roadmap).
```markdown
# [Game title] — [one-line genre description] design doc (GDD)
> 🔖 **AI note — resuming?** If you're reading this in a new session to continue/resume this game, load the `msw-planning` skill FIRST and follow its resume flow (read `[game]-Roadmap.md` + `Archive/As-built.md` → reconstruct state → reconcile) — don't edit or implement straight from this doc. **Before touching any `⬜/🟡/✅` state or running a completion, Read the skill's `references/build-management.md` IN FULL.**
> Last updated: [date] / Stage: [e.g., Phase 1 upcoming]
## 1. One-line concept
> "[who / what / how in one sentence. e.g., a top-down auto-attack 10–15 min roguelite survival.]"
## 2. Key decisions (immutable baseline) ← always include
| Item | Decision | Notes |
|---|---|---|
| Camera/map mode | [MapleTile / RectTile / SideViewRectTile] | State the Body component + which map it's built in (a matching template if the project has one) |
| Player | [DefaultPlayer-based, etc.] | |
| Session length | [minutes] | |
| Player count | [solo / multi] | Whether @Sync is used |
| Priority | [fun-first / content volume, etc.] | |
## 3. Core loop (one session) ← always include
[Entry → repeated action → reward → growth → repeat → end (win/lose), as arrows/diagram]
## 4. Core systems
[Per system — player / enemy / growth / reward / difficulty·spawn / UI — what, with what numbers]
## 5. System ↔ MSW mapping (real implementation) ← always include
| Game system | MSW implementation |
|---|---|
| [global state·timer] | @Logic ... |
| [player movement] | [Body matching the map type] ... |
| [enemy AI] | @Component ... |
| [data (stats etc.)] | UserDataSet (dataset) ... |
| [UI/HUD] | .ui + UIBuilder ... |
( fill in using references/msw-mapping.md )
## 6. Roadmap (Phases) ← always include
[From the smallest playable build, by stages — seed Phase 1 from the matched genre's `MVP:` hint and the later Phases from its `Growth:` axes (genre-catalog, as adapted in STEP 2–3). Each Phase is a checklist of items **required** for a handoff-ready prototype (all must reach ✅) — polish / nice-to-have / later work goes to the **milestone roadmap** (`Docs/[game]-Roadmap.md`), not here and not in §8. Track each item with ⬜ not started · 🟡 implemented (untested) · ✅ tested (all start ⬜).]
### Phase 1 — "[smallest working goal, e.g., move, hit, and it breaks]"
- ⬜ ...
### Phase 2 — "[next core]"
- ⬜ ...
### Phase 3+ — "[variety · difficulty · content]"
- ⬜ ...
## 7. Data-driven (if applicable)
[If values are many/tunable, move stats·balance into UserDataSet/CSV ("CSV is the source of truth"). Early Phases may hardcode; when the data grows/stabilizes, plan the migration **by horizon**: within this milestone → a later-Phase task in §6; **beyond this milestone → an entry in the milestone roadmap** (that M's slot or the Backlog), leaving only a pointer here — a migration promise written only in this section is buried when the GDD archives (next-milestone planning reads the roadmap + As-built, not archived GDDs). Leads into the detailed dataset-design stage (authored via msw-general → `references/dataset.md`).]
## 8. Decisions (this milestone)
| Item | Status |
|---|---|
| [decided] | Decided: [value] |
| [pending] | Pending → [decided when — within this milestone] |
> ⚠️ Nothing beyond this milestone lives here. Cut features / later-milestone work go to the **milestone roadmap** (`Docs/[game]-Roadmap.md` — a future-M slot or its Backlog) the moment they surface. "Pending" = a decision this milestone still owes (e.g., a value to lock at Phase 3), not deferred work. The GDD may *mention* a beyond-milestone item as **name + roadmap pointer only** (a boundary note like "excluded here → M4" is fine) — its plan content lives only in the roadmap; if they diverge, the roadmap wins.
## 9. Plan changes (revision log) ← append when the plan is revised mid-development
| When | Type | What changed | Reason | Impact |
|---|---|---|---|---|
| [date] | Add / Remove / Modify | [rule / task] | [why] | [states reset · code to remove · new/affected tasks] |
```
## Writing guide
- **Phase 1 must be the "smallest playable build."** Don't pack flashy features into #1 — confirm the game "runs" with just movement · core action · fail condition. The matched genre's `MVP:` hint (STEP 2 grounding) is the natural seed — adapt it to the confirmed direction, don't copy it verbatim.
- **Coverage check (before saving)**: §6's Phases must collectively deliver §1's one-line concept — trace each capability §1 (and, for M2+, the promoted roadmap-slot line) claims to the checklist item(s) that implement it, and fix any hole now (add the tasks, or reword the claim with the user's agreement). **Verification limits don't shrink scope**: a flow the AI can't verify alone (real multiplayer, on-device feel, commerce) is still planned as tasks that will end `🟡 needs-user-test` — never silently omitted. The milestone-complete procedure re-runs this same check ([*Milestone-complete cleanup*](build-management.md#milestone-complete-cleanup-mandatory) Step 0), so a hole left here WILL surface — later and more expensively.
- **The key-decisions table is for nailing things down.** Especially map type ↔ Body: once set, the whole stack follows, so lock it here.
- Ambitions beyond the **small first build (MVP)** (many maps · too many systems) go to the **milestone roadmap** — a future-milestone slot or its Backlog — never into this GDD. The genre's `Growth:` axes suggest what naturally lands there (later Phases of *this* milestone may still absorb some — §6).
- **Template cleanup (if the project ships sample entities)**: add a **late-Phase "remove sample entities" task** (before handing off to full implementation) so they don't carry into the real build. **Scope it project-wide**: enumerate ALL maps (full `map/` listing) and inspect each — samples can sit in **any** map (template-derived maps often carry them, some carry none), and one map scanning clean is not evidence for the others. Write the task's done-criteria as "every map enumerated and clean" and **name the scanned maps in the verification record**. **Don't assume fixed names** (often `*Template`-named idle/move/chase samples, but they vary). Useful early as AI-pattern references; removal happens during implementation via MapBuilder. Two more template-residue rules: **(a) rename the build map EARLY** — if building in a `*Template`-named map, put a **Phase 1 task** to rename it to a game-appropriate ASCII name (references are fewest at the start; done-criteria = rename + all references updated + entry verified; read-only `Global/` references are the user's Maker action); **(b) unused template maps** — at handoff, ask the user whether to **delete or keep** each template map the game doesn't use (never delete unconfirmed), deciding **before** sample-cleaning them — "every map clean" applies to the maps that remain.
- **Suggested file layout (recommendation, not a mandate)**: when this plan is implemented, organizing the `.mlua`/`.model` files into folders that **mirror the plan's systems** keeps the codebase clean — e.g. `Player/`, `Monsters/`, `Skills/`, `Projectile/`, `Data/` (UserDataSet), world-wide managers under `Game/` (@Logic), and `.model` under `Models/<type>/` (per the platform rule). The implementation skills do the actual foldering; if the project already has its own folder convention, follow that instead.
- Save the deliverable under the **project-root `Docs/`** (e.g., `Docs/<game>-M<n>-GDD.md`, where `<game>` is a short **ASCII English/romanized slug** — not the raw non-English title — and `<n>` is the **milestone number** (numbering rule in SKILL.md STEP 5: first = M1, later = numeric max + 1); the *content* stays in the user's language, only the filename is ASCII; create the folder if missing). **Do NOT put it under `RootDesk/`** — Maker's `refresh_workspace` deletes non-MSW files (.md) under RootDesk. Create/update the **milestone roadmap** (`Docs/<game>-Roadmap.md`, template below) alongside the GDD. After producing them, tell the user the save locations and the **next step** (phase detailed plan / dataset·UI design / start implementation).
- **Mid-development revisions** (add/remove/modify a planned rule) are logged in §9 and applied to the affected sections + checklist states — see [*Revising the plan mid-development*](build-management.md#revising-the-plan-mid-development-add--remove--change-a-rule). Append to history; don't silently rewrite past decisions.
---
## Milestone roadmap template (`Docs/<game>-Roadmap.md` — STEP 5)
One per game, **created together with the M1 GDD**, kept in `Docs/` permanently (never archived, outside RootDesk). The **single home for everything beyond the current milestone** — the GDD holds nothing beyond its own milestone, so this file is where cut features, later-milestone ideas, and mid-build "let's do that someday" requests land the moment they surface.
```markdown
# [Game] — Milestone roadmap
> 🔖 Cross-milestone direction: vision · release criteria · one slot per milestone · Backlog.
> This is NOT a GDD — the active milestone's contract is its `-M<n>-GDD.md`. Updated only at controlled moments (see guide).
> Last updated: [date] ← date only — no status/progress annotations on this line
## Vision & release criteria
- Vision: [one line — what this game is when it's done]
- Release criteria: [what must be true to call it releasable — criteria, not a feature dump]
## Milestones
| M | Theme (one line) | Status |
|---|---|---|
| M1 | [theme] → `[game]-M1-GDD.md` | 🔨 active |
| M2 | [theme + assigned features, one line] | planned |
| M3 | [theme + assigned features, one line] | candidate |
## Backlog (wanted, not yet slotted)
- [item] — [why it waits / what would trigger revisiting it]
```
**Writing guide**
- **One line per future milestone** — theme + assigned features only. Detailed design happens in that milestone's own GDD when it starts; a detailed future plan goes stale and then misleads (same principle as As-built).
- **Statuses (a CLOSED set — never coin new labels or hybrids like "✅ code-complete")**: `🔨 active` (its GDD is in `Docs/`) · `⏳ user-test pending` (all remaining items await user tests — see build-management.md "Milestone blocked on user testing") · `✅ done` (one-line summary; the archived GDD is the full record) · `planned` (next in line) · `candidate` (order may change). Slot an item into a milestone when the timing is known; otherwise Backlog — don't force day-one assignments (future milestones WILL be reshaped by what playtesting teaches).
- **Coarse progress marker (the only progress allowed here)**: the active slot's Status cell may read exactly **`🔨 active (Phase k/n done)`**, updated ONLY at phase-completion cleanup. No percentages, no free-text status, nowhere else in this file — real progress (which items, what states) lives in the GDD checklist. The `Last updated` line stays **date-only**, no status annotations.
- **Single-home rule**: whenever "later" work surfaces — during planning, mid-build discussion, or a user request — record it here immediately (slot or Backlog) and confirm placement in one line. Never park it in the GDD. The GDD may reference an item here as **name + pointer only** (boundary notes are fine) — never restate its plan content; on divergence, this file wins.
- **Update at controlled moments** (a stale roadmap misleads worse than none) — **adding an item is always one of them**: a new "later" item surfacing (append it to a slot or the Backlog the moment it comes up) · creation with the M1 GDD · each milestone completion (mark `✅ done`, promote/re-order slots, review the Backlog with the user) · next-milestone GDD creation (promote that slot into the new GDD) · a plan revision that changes long-term direction. What waits for a controlled moment is **re-shaping** — moving items between slots, changing statuses, promoting — not recording a new one. Not per edit.
- **§9 logging boundary**: a purely beyond-milestone change (a new future item, a Backlog reshuffle) gets **no GDD §9 entry** — this file is its record. Log in §9 only when the change also touches **this** milestone — e.g. work cut from the current GDD and moved here — because that changes the active checklist (see [*Revising the plan mid-development*](build-management.md#revising-the-plan-mid-development-add--remove--change-a-rule)).
- **Scale to the game**: a single-milestone game's roadmap is a few lines — M1 = release, empty Backlog. That's fine; it grows only if the game does.
---
## Per-phase detailed plan template (STEP 6 — optional)
Use this to expand a specific Phase's checklist into deeper work units. Save: `Docs/<game>-M<n>-Phase<k>.md` (same `<game>-M<n>-` prefix as the milestone's GDD; `<k>` = phase number; project root, **outside RootDesk**).
```markdown
# [Game] — Phase [N] detailed plan
> 🔖 **AI note — resuming?** If you're reading this in a new session to continue the build, load the `msw-planning` skill FIRST and resume through it (read `Archive/As-built.md` + the GDD → reconstruct state) — don't treat this as plain implementation and start editing straight from this doc. **Before implementing tasks or updating any `⬜/🟡/✅` state, Read the skill's `references/build-management.md` IN FULL** (state rules · completion cleanups · revision flow).
> Parent doc: [Game]-M<n>-GDD.md · This Phase's goal: [one line]
> **Skills to reference (this Phase)**: skills the implementing session should load for this Phase — predicted from GDD §5 / `references/msw-mapping.md` §4. Per-task specifics under each task below.
## Status checklist
> States: ⬜ not started · 🟡 implemented (untested) · ✅ tested.
> All items start ⬜. Mark 🟡 when built, ✅ only after verification passes.
> Items the AI cannot verify itself stay 🟡 with a "needs user test" note until the user reports back.
- ⬜ [Task 1 title]
- ⬜ [Task 2 title]
- ⬜ [Task 3 title] ⚠️ needs user test: [what the user must check — AI can't verify]
## Task detail
### [Task 1 title]
- **Goal**: what works / is complete when this task is done
- **Required systems·components**: @Logic/@Component/.model/.ui etc. (references/msw-mapping.md)
- **Data**: UserDataSet columns etc. (if applicable)
- **UI**: related .ui elements (if applicable)
- **Done (verification) criteria**: what you look at to call it done (log / screen / behavior) — and **who** can verify (AI-verifiable vs needs-user-test)
- **Dependencies**: prerequisite tasks · other items
- **Skills to reference (predicted)**: the skill(s) + reference doc this task needs (`references/msw-mapping.md` §4). The implementing session reads/loads these.
### [Task 2 title]
- ...
## Risks / cautions
- MSW silent-failure points to watch at this stage (map-type↔Body, empty SpriteRUID, 1 unit = 100px coordinates, etc.)
```
**Writing guide**
- Cut each task into "playably verifiable" units, with clear done (verification) criteria.
- So the doc can be carried straight into the implementation skills (`msw-general`·`msw-scripting` etc.), write down the needed components·data·verification points without gaps.
- **Track status, stay honest**: update each item ⬜ → 🟡 → ✅ as it's built and verified. Never mark ✅ on something the AI couldn't actually test — leave it 🟡, tell the user exactly what to check, and update it when they report back. If the user moves to the next Phase with items still untested, flag the incomplete ones but proceed if they want.
- **Document lifetime**: this detail doc is a transient artifact, but it is deleted **only at all-✅**. Once that Phase's items are **all ✅ tested**, reflect completion in the GDD roadmap, **distill its as-built facts into `Archive/As-built.md`** (see below), then **delete this doc (mandatory)** — it must not linger. While any item is still 🟡 awaiting a user test, this doc **stays in `Docs/`** (a `⏳ user-test boundary`), so the current Phase's doc and an earlier waiting one can coexist there. Progress history stays in the GDD; the as-built record stays in `Archive/As-built.md`.
---
## As-built log template
The file is `Archive/As-built.md` — standalone, in **project-root `Archive/`** (survives milestone cleanup + `refresh_workspace`). An **AI / handoff reference, not a user-facing planning doc**. Seeded by a brownfield survey when the skill is first adopted on an existing project; updated at each Phase / milestone completion. It is a **curated current-state map + why/gotchas — NOT a change-log** (git already records raw changes).
```markdown
# [Game] — As-built log
> Running record of the world's implementation. Survives across milestones. ⚠️confirm = survey guess to verify with the user.
## Current state (by system)
| System | Built | Where (key files) | Notes / gotchas |
|---|---|---|---|
| [system] | [@Logic / @Component / .model / .ui / dataset] | [folder · file] | [deviations · gotchas · ⚠️confirm] |
## Standing issues & handoff rules (update in place — never re-append)
| Issue / rule | Workaround / rule | Count | First → last seen |
|---|---|---|---|
| [recurring issue or standing handoff rule] | [what to do when it hits] | 2 | [mm-dd] → [mm-dd] |
## Log (entries: the ACTIVE milestone only + ONE summary per completed milestone)
### [date] Seed — surveyed on toolkit adoption (brownfield only)
[what the survey found · ⚠️confirm items]
### [date] Milestone M<n> complete — summary
[≤15 lines: what shipped · standing deviations · pointers to archived GDD / regression docs]
### [date] Phase N complete
[≤15 lines: what/why/gotchas]
```
**Writing guide**
- Keep "Built / Where" to a *map* (point to files), not copied code — code is the real artifact; this is the index + the *why/gotchas* the code doesn't state.
- **State scope precisely — including what was NOT done**: write "removed 3 samples from `RectTileMapTemplate.map` (other maps untouched)", never just "samples removed". A scope-less entry reads as project-wide and later becomes a false "already done" that downstream checks inherit.
- Update only at controlled moments (Phase / milestone completion, or brownfield seed) — **not per edit**. A stale As-built misleads worse than none.
- **Entry cap (~15 lines)**: a Log entry records *what / why / gotchas* only. Verify evidence, log dumps, and file-change lists do NOT belong here — git and the regression docs keep those. "Concise" failed as a soft word; treat the cap as the rule.
- **Recurring issues update in place — never re-append**: when an issue recurs (same symptom + same root cause + same fix), do NOT write a new Log entry restating it — update its **Standing issues** row instead: increment Count, refresh last-seen, refine the workaround wording only if something new was learned. Same symptom with a *different* root cause = a new row (link the old one). **Count ≥ 3 is an escalation trigger**: stop re-applying the workaround silently and propose a root-cause task to the user (a checklist item or roadmap entry). A standing handoff rule discovered once (e.g. a cache-regen procedure) also lives here, not in per-entry prose.
- **Milestone compaction (at milestone-complete cleanup)**: compress that milestone's Log entries into ONE `M<n> complete — summary` entry (≤15 lines) and delete the per-Phase/per-fix entries — git, the archived GDD, and the regression docs keep the detail. The Log therefore holds: the seed entry, one summary per completed milestone, and the active milestone's entries.
- **Size guardrail**: if this file exceeds **~500 lines / ~30KB** at any controlled moment, compact on sight (run the milestone compaction + Standing-issues dedup). The file must stay readable in **one full Read** — the resume flow depends on reading it whole; an As-built too big to read whole silently truncates the next session's knowledge of the world.
- **Scope of update-in-place**: this rule applies to As-built ONLY. The GDD's §9 Plan-changes log stays append-only — never rewrite decision history.
- The next milestone's GDD is planned **on top of** this file's current state **plus the milestone roadmap's next slot** (`Docs/<game>-Roadmap.md`).
references/genre-catalog.md
# MSW Buildable Game-Genre Catalog (grounding reference)
Organized by MSW's technical characteristics (2D · mLua scripting [a Lua-extension language] · Unity engine · PC/mobile cross-platform): the buildable genres, map types, and mechanics. Map a user's idea onto this to produce a **feasible** plan.
- **Build-effort hint (Low / Medium / High)**: a rough signal of how much work a *full* version takes — a signal, not a verdict. Baseline: **Low** = a tiny MVP (≈1 map · core loop only · basic mLua); **Medium** = moderate (a few maps/systems · intermediate mLua; **tower defense sits here — the top of comfortably-solo**); **High** = large (many maps/systems/data · advanced or team-scale). High-effort genres are still buildable — **plan a scoped-down first build (MVP) and defer the rest**, rather than refusing the genre.
- **`MVP:` / `Growth:` line (per genre)**: `MVP:` = the smallest playable slice that already delivers the genre's fun — the seed for **Phase 1 / milestone M1** scoping (STEP 3 scoped-down option · STEP 4 Phase 1). `Growth:` = the axes a finished core typically grows along, in rough order — the seed for **later Phases / next milestones**. Both are hints to adapt, not fixed specs.
- Example notation: `[MSW]` = an actual MSW world / `[ref]` = external reference.
## Contents
1. Map types (3) + selection guide
2. Genre list (by category, 71)
3. Core mechanic tags (by category)
---
## 1. Map types (3)
| Map type | View | Movement | Movement/Body component | Characteristics |
|---|---|---|---|---|
| **TileMap (MapleTile)** | Side-scroll | Left/right + jump | `RigidbodyComponent` | Foothold-based, like the original MapleStory. Gravity/jump/platforms built in |
| **RectTileMap (RectTile)** | Top-down | Free 4-directional | `KinematicbodyComponent` | Looking-down view. Suits RPG fields · strategy · puzzle · social |
| **SideViewRectTileMap** | Side-scroll | Left/right + jump | `SideviewbodyComponent` | Rect-tile side-scroll. Supports ladders/ropes; more terrain freedom than MapleTile |
**Selection guide**
- **TileMap** → MapleStory-style side-scroll. Required if you need jump/platform physics.
- **RectTileMap** → games that need top-down. Recommended for non-action like tycoon · strategy · puzzle · social.
- **SideViewRectTileMap** → side-scroll but with freely composed terrain. Custom-terrain action/platformer.
- **Multiple entries (/)** → both fit. E.g., a monster-collecting RPG works as side-scroll or top-down.
---
## 2. Genre list (by category)
Notation: sub-genre — `Build-effort` · recommended map type · `#core-mechanics` · examples, then an indented `MVP:` / `Growth:` hint line (see the legend above).
### Role-Playing
- **MMORPG** — High · TileMap · #leveling #gear-enhance #job-advance #party-play #exploration · [MSW] MapleLand / Artale / Rona World
- MVP: 1 field map + 1 town · 3 monster types · EXP/level + 1 starter job · one short quest chain — Growth: regions/maps → jobs + skill trees → party/boss content → gear economy & trade
- **Monster-collecting RPG** — High · TileMap/RectTile · #turn-based-combat #evolution #dex-collection #monster-capture #creature-raising · [MSW] Pictra Monster / [ref] Pokémon
- MVP: 1 route · 5 capturable species · 1v1 turn battle · party of 3 · capture item — Growth: dex expansion → evolution lines → trainers/gyms → trading & rare hunts
- **Action RPG** — High · TileMap/SideView · #real-time-combat #skill-combo #gear-progression #boss-fight · [MSW] Maple Slash / [ref] Zelda
- MVP: 1 dungeon map · basic attack combo + 2 skills · 3 enemy types + 1 mini-boss · HP/potion — Growth: skill tree → gear drops/enhance → dungeon list → classes/difficulties
- **Dungeon crawler** — Medium · TileMap/SideView · #floor-progression #loot-drop #dungeon-exploration #turn-based-movement · [ref] Torneko's Great Adventure
- MVP: 3 floors · descend-to-goal · 5 enemy types · HP/hunger + random loot — Growth: deeper floors/themes → item variety & identify → classes → daily runs
- **Story-driven RPG** — High · TileMap/RectTile · #npc-dialog #branching-choices #quest-progression #multiple-endings · [ref] Undertale
- MVP: 1 chapter · dialog + choice engine (dataset-driven) · one branch → 2 endings — Growth: chapters → branch depth/flags → set-piece minigames → collectible lore
- **Boss-raid RPG** — High · TileMap · #boss-patterns #loot-drop #multiplayer-co-op #role-split · [ref] Monster Hunter
- MVP: 1 boss with 3 telegraphed patterns · 4-player co-op · basic role kits · clear reward — Growth: boss roster → pattern/enrage depth → gear & enhance loop → weekly reset economy
### Action
- **Hack-and-slash** — High · TileMap/SideView · #skill-combo #mass-kill #loot-drop #fast-combat · [ref] Diablo
- MVP: 1 arena · mob waves · combo attack + 1 AoE skill · loot drops — Growth: skill/gear depth → stage list → difficulty tiers → item sets/builds
- **Battle royale** — High · TileMap/RectTile · #real-time-pvp #item-looting #last-one-standing #shrinking-map · [ref] PUBG / Fortnite
- MVP: 1 mid-size map · 8–16 players · loot spawns · shrinking zone · last-alive wins — Growth: map size/POIs → item meta → squads/revive → ranked seasons
- **Boss rush** — Medium · TileMap · #boss-patterns #pattern-memorization #consecutive-battles #rising-difficulty · [ref] Cuphead
- MVP: 3 bosses back-to-back · 1 fixed player kit · retry + clear time score — Growth: boss roster → pattern tiers/EX modes → time-attack ranking → unlockable kits
- **Fighting / PvP** — High · TileMap/SideView · #skill-use #hit-detection #combo-system #real-time-pvp · [ref] Brawlhalla
- MVP: 1 stage · 2 characters · hit/guard/combo core · best-of-3 rounds — Growth: roster → move-set depth → ranked & replays → balance via data
- **Co-op PvE** — High · TileMap/RectTile · #stage-clear #multiplayer-co-op #role-split #boss-fight · [ref] Castle Crashers
- MVP: 1 stage · 2–4 players · 3 enemy types + stage boss · shared lives — Growth: stage list → classes/roles → difficulty modifiers → co-op-only mechanics
- **Vampire-survivors-like** — Low · RectTile · #auto-attack #mass-kill #level-up-choice #skill-combination #time-limit · [MSW] Meso Warrior / Million Aing / The Last Maple / [ref] Vampire Survivors
- MVP: 1 open map · 1 auto-attack weapon · 10-min survival timer · 3-choice level-ups — Growth: weapon/synergy pool → characters → meta upgrades → stages/bosses
- **io-style arena** — Medium · RectTile · #real-time-pvp #many-player-competition #survival-time #mass-kill #score-competition · [ref] Agar.io / Slither.io (Agar-style scale growth syncs cheaply; Slither-style body-segment trails are sync-heavy — caution)
- MVP: 1 arena · grow-by-eating loop · 8+ players (bots to fill) · live leaderboard — Growth: skins → abilities/classes → team & timed modes → season ranking
### Adventure
- **Point-and-click adventure** — Medium · TileMap/RectTile · #map-search #item-combine #npc-dialog #story-presentation · [ref] The Secret of Monkey Island
- MVP: 3 rooms · pick-up/combine items · one puzzle chain to the exit — Growth: chapters → inventory-puzzle depth → dialog NPCs → hint system
- **Escape room** — Low · TileMap/RectTile · #item-combine #clue-search #unlocking #story-presentation
- MVP: 1 room · 4–5 linked puzzles · unlock the door to escape — Growth: themed rooms → mechanism variety → co-op mode → clear-time ranking
- **Maze exploration** — Low · RectTile · #inventory #pathfinding #limited-vision #enemy-avoidance · [ref] Pac-Man
- MVP: 1 maze · limited vision · reach-the-exit + 1 chaser — Growth: maze generator → items/traps → floor progression → multiplayer race
- **Resource-gathering survival** — High · TileMap/RectTile · #resource-gathering #building #stamina-management #crafting #exploration · [MSW] Durango / [ref] Terraria, Don't Starve
- MVP: 1 map · gather 2 resource types · 3 craft recipes · hunger + day/night — Growth: tech tree → base building → threats/seasons → multiplayer world
- **Visual novel** — Medium · RectTile · #story-presentation #branching-choices #multiple-endings #npc-affinity · [ref] Ace Attorney
- MVP: 1 episode · text + portrait engine (dataset script) · 3 choices → 2 endings — Growth: episodes → affinity routes → CG/gallery unlocks → sound & presentation polish
### Casual & Arcade
- **Typing action** — Low · TileMap/RectTile · #text-input #enemy-kill #time-limit #rising-difficulty · [ref] The Typing of the Dead
- MVP: 1 lane · word-tagged enemies (dataset) · type-to-kill · HP + speed ramp — Growth: word packs → enemy types → boss words → ranking
- **Fishing game** — Low · TileMap/RectTile · #gear-enhance #dex-collection #timing-input #rarity-system
- MVP: 1 spot · timing-bar catch · 5 fish rarities · sell → rod upgrade — Growth: spots/biomes → gear tree → fish dex & records → seasonal events
- **Dodging (Dodge)** — Low · TileMap/RectTile · #obstacle-avoidance #survival-time #rising-difficulty #score-competition
- MVP: 1 arena · falling/homing hazards · survival timer + best score — Growth: hazard patterns → characters/perks → stages → daily ranking
- **Merging/combining** — Low · RectTile · #dex-collection #item-merge #recipe-discovery #physics-reaction · [ref] Suika Game, Little Alchemy
- MVP: 1 board · drop-and-merge one 5-tier chain · score + fail line — Growth: merge-tree depth → boosters → dex/quests → events
- **Match-3 puzzle** — Low · RectTile · #block-swap #match-3 #chain-reaction #special-blocks · [ref] Candy Crush, Anipang
- MVP: 6×8 board · swap-match core · 20 dataset levels · move limit — Growth: blockers/special pieces → level packs → lives/boosters → events
- **Memory card matching** — Low · RectTile · #memory #pair-matching #turn-limit #rising-difficulty
- MVP: 4×4 pair grid · turn limit · 10 stages — Growth: grid sizes → themes → versus mode → daily challenge
- **Number/deduction** — Low · RectTile · #logic-deduction #hint #grid-fill #attempt-limit · [ref] Wordle, Mastermind
- MVP: one rule (Wordle-style) · daily answer dataset · shareable result — Growth: rule variants → difficulty tiers → streak/ranking → hint economy
- **Sliding puzzle** — Low · RectTile · #block-slide #merge #min-moves · [ref] 2048, 15-puzzle
- MVP: 4×4 2048 board · merge scoring · best record — Growth: board variants → obstacles → daily challenge → skins
- **Falling-block puzzle** — Low · RectTile · #block-rotate #line-clear #rising-fall-speed #chain-reaction · [ref] Tetris, Puyo Puyo
- MVP: 1 well · 7 pieces · line clear + speed ramp — Growth: modes (sprint/marathon) → versus garbage battle → ranking → skins
- **Gacha simulator** — Low · RectTile · #probability-sim #enhance-attempts #result-presentation #stats-logging · [ref] StarForce sim
- MVP: 1 banner · rate table (dataset) · pull animation + history log — Growth: enhance/star systems → collection goals → leaderboards → parody events
- **Rhythm/music game** — Medium · TileMap/RectTile · #music-sync #note-timing #combo #accuracy · [ref] O2Jam
- MVP: 1 song · 4-key notes from a dataset chart · judgement + combo — Growth: song/chart list → difficulties → note skins → accuracy ranking
- **Board/card game** — Medium · RectTile · #multiplayer #turn-based-flow #rule-based #win-condition · [ref] Blue Marble, One Card (chess/go need high AI difficulty — caution)
- MVP: one ruleset · 2–4 players · turn flow + win check — Growth: rule variants → AI opponent → items/boards → ranking
- **O/X quiz / elimination** — Low · RectTile · #round-progression #ox-choice #many-players #elimination
- MVP: O/X floor zones · question dataset · elimination rounds → last survivors — Growth: question packs → twist modes → rewards → live/event hosting
- **Endless runner** — Low · TileMap/SideView · #auto-run #obstacle-avoidance #coin-collection #rising-difficulty #score-competition · [ref] Cookie Run, Jetpack Joyride
- MVP: auto-run 1 course · jump/slide inputs · coins + distance score — Growth: obstacle patterns → characters/pets → missions → seasonal maps
- **Classic arcade remake** — Low · RectTile · #physics-reaction #score-competition #rising-difficulty #chain-reaction · [ref] Breakout, Snake, Pong
- MVP: one classic loop (e.g., Breakout) on 1 screen · lives + score — Growth: level packs → modifiers/power-ups → 2P versus → remix mechanics
### Simulation
- **Gathering/mining sim** — Medium · TileMap/SideView · #gear-enhance #resource-gathering #stamina-management #depth-exploration · [MSW] Miner Simulator
- MVP: 1 vertical mine · pickaxe tiers 1–3 · ore → sell → upgrade loop — Growth: depth layers → auto tools/helpers → quotas & quests → prestige reset
- **Management tycoon** — Medium · RectTile · #upgrade #revenue-management #customer-service #menu-product-management · [MSW] ChuChu Burger Branch 1
- MVP: 1 shop · 1 product line · buy → serve → profit → upgrade loop — Growth: menu/staff → interior & expansion → branches → VIP/events
- **Housing/interior** — Medium · RectTile · #inventory #object-placement #free-placement #housing · [MSW] Maple Toytown / [ref] Animal Crossing
- MVP: 1 room · ~20 furniture items · place/rotate + save (DataStorage) — Growth: item catalog → more rooms/lot → visits & likes → gifting/trade
- **Dress-up/styling** — Medium · RectTile · #inventory #item-combine #theme-mission #outfit-rating · [ref] Love Nikki
- MVP: ~20-item closet · one theme mission · save the look — Growth: wardrobe expansion → rating/contests → gacha closet → social showcase
- **Farming/ranch** — High · RectTile · #crop-farming #animal-husbandry #time-passage #season-system · [ref] Stardew Valley
- MVP: 1 field · 3 crops · plant → timed growth → harvest → sell — Growth: animals → seasons → processing/recipes → town requests & relationships
- **Life simulation** — High · RectTile · #npc-affinity #daily-activities #relationship-system #open-endedness · [ref] Animal Crossing, The Sims
- MVP: 1 town map · day cycle · 3 NPCs with affinity · 2 daily activities — Growth: NPC depth/events → jobs/hobbies → housing → festivals
- **Pet raising** — Low · RectTile · #creature-raising #stamina-management #daily-activities #evolution · [ref] Tamagotchi, Pou
- MVP: 1 pet · feed/play/clean meters · growth stages over real time — Growth: species & evolution branches → care minigames → room decor → breeding
- **Kitchen co-op action** — Medium · RectTile · #multiplayer-co-op #customer-service #time-limit #role-split · [ref] Overcooked
- MVP: 1 kitchen · 3 recipes · order timer · 2P co-op serving loop — Growth: recipes/stations → stage gimmicks → 4P chaos → star ratings
### Strategy
- **Auto-battler** — Medium · TileMap/RectTile · #round-progression #auto-combat #unit-composition #synergy-combos · [ref] Auto Chess
- MVP: 1 board · 8 units in 3 cost tiers · rounds vs AI waves · gold/reroll economy — Growth: synergy traits → 4–8P PvP → items → rotating sets
- **Card strategy/battle** — High · RectTile · #turn-based-combat #card-collection #deckbuilding #mana-management · [MSW] Maple Duel / [ref] Hearthstone
- MVP: ~20-card pool · 1v1 vs AI · mana + attack/defense rules — Growth: card sets → PvP → classes/archetypes → ranked & drafts
- **Turn-based artillery** — Medium · TileMap/SideView · #angle-adjust #power-adjust #wind-variable #terrain-destruction · [ref] Fortress, Gunbound, Worms
- MVP: 1 terrain · angle + power shot · wind · 2P hotseat or vs AI — Growth: weapon variety → destructible terrain depth → items/buffs → team modes
- **Resource-management strategy** — High · RectTile · #resource-allocation #tech-tree #territory-expansion #ai-opponent · [ref] Civilization
- MVP: 1 small map · 2 resources · build 3 structure types · one win condition — Growth: tech tree → smarter AI opponent → map generation → factions
- **Grid tactics (SRPG)** — Medium · RectTile · #turn-based-combat #turn-based-movement #unit-composition #role-split · [ref] Fire Emblem, Into the Breach
- MVP: one grid battle · 3 units vs 3 · move + attack turn order · terrain blocks — Growth: campaign missions → classes/skills → terrain effects → permadeath/hard modes
### Social
- **Party mini-games** — Medium · RectTile · #round-progression #random-game #many-player-competition #elimination · [ref] Mario Party, Fall Guys
- MVP: 3 minigames · lobby rotation · cumulative score across rounds — Growth: minigame pool → items/interference → team modes → season ranking
- **Hide-and-seek/chase** — High · TileMap/RectTile · #it-tagging #stealth #real-time-chase #map-search · [ref] Prop Hunt, Red Light Green Light
- MVP: 1 map · seeker vs hiders · round timer + tag-out — Growth: maps → roles/skills → prop-disguise mode → ranking
- **Social deduction** — High · RectTile · #social-deduction #many-players #elimination #map-search · [ref] Among Us, Mafia
- MVP: 1 base map · crew vs 1 impostor · simple tasks · meeting + vote-out — Growth: role variety → maps/tasks → sabotage depth → ranked lobbies
- **Hangout/role-play world** — Low · TileMap/RectTile · #many-players #housing #daily-activities #outfit-rating · [ref] Habbo, ZEP
- MVP: 1 themed lounge map · chat + emotes · seats & photo spots — Growth: zones/activities → personal rooms & shops → scheduled events → creator/staff roles
### Education
- **Quiz game** — Low · RectTile · #question-serving #answer-checking #score-competition #time-limit · [MSW] QPlay Archive
- MVP: ~50-question dataset · 4-choice answering · score + timer — Growth: categories → modes (speed/battle) → ranking → user-submitted packs
- **Typing practice** — Low · RectTile · #text-input #wpm-measure #accuracy-check #rising-difficulty
- MVP: sentence dataset · WPM + accuracy result screen — Growth: courses/lessons → tests & records → race mode → stat tracking
- **Word battle** — Low · RectTile · #text-input #answer-checking #many-player-competition #time-limit · [ref] Kkutu (Korean word-chain) (dictionary = a curated dataset subset, not a full national dictionary — caution)
- MVP: word-chain 1v1 · dictionary dataset · turn timer + lives — Growth: modes (theme/speed) → many-player rooms → ranking → item twists
### Defense
- **Side-view wave defense** — Medium · TileMap/SideView · #wave-progression #real-time-combat #skill-use #rising-difficulty · [ref] Orcs Must Die
- MVP: 1 lane · base HP · 5 waves · 1 hero with a skill — Growth: units/skills → wave & boss variety → maps → endless mode
- **Tower defense** — Medium · RectTile · #wave-progression #unit-enhance #resource-management #unit-placement #path-based · [MSW] Maple Random Defense / [ref] Kingdom Rush (**top of comfortably-solo**)
- MVP: 1 map · 1 path · 3 tower types · 5 waves · leak = lose — Growth: tower tiers/synergies → new maps → heroes/abilities → endless & ranking
- **Base defense** — Medium · TileMap/RectTile · #wave-progression #object-placement #base-hp #omnidirectional-defense · [ref] Dungeon Defenders
- MVP: 1 base · omnidirectional 5 waves · place walls/turrets between waves — Growth: buildable variety → enemy types → tech upgrades → co-op
- **Random defense** — Medium · RectTile · #wave-progression #random-draw #unit-merge #unit-placement · [ref] Random Dice
- MVP: 1 board · random unit draw · merge same-kind to upgrade · shared waves — Growth: unit pool/grades → synergies → PvP race mode → seasons
### Shooter
- **Shoot-'em-up** — Low · TileMap/SideView · #projectile #enemy-patterns #power-up #score-competition #boss-fight · [ref] Galaga, 1945
- MVP: 1 scrolling stage · 1 ship · 3 enemy patterns + 1 boss · score — Growth: stage list → power-ups/bombs → bullet-pattern depth → 2P mode
### Sports & Racing
- **Sports game** — Medium · TileMap/RectTile · #rule-based #score-competition #real-time-pvp #turn-based-flow · [ref] heading soccer
- MVP: 1 court · 1v1 (vs AI ok) · minimal rules + score to win — Growth: teams → skills/stats → tournaments → ranking
- **Racing/running** — Medium · TileMap/RectTile · #async-pvp #speed-competition #track-design #score-competition · [ref] KartRider
- MVP: 1 track · 2–4 racers · lap timer + finish order — Growth: track list → items (kart-style) → vehicles/tuning → ghost records & ranking
### Platformer
- **Obstacle run (obby)** — Low · TileMap/SideView · #stage-clear #timing-jump #moving-obstacles #rising-difficulty · [MSW] Maple Luck Run / [ref] Geometry Dash
- MVP: ~10 obstacle sections · checkpoints · clear timer — Growth: stages/themes → moving gimmicks → race mode → records
- **Hardcore climbing** — Low · TileMap · #physics-movement #special-controls #fall-reset #extreme-difficulty · [MSW] Jar Game Returns / [ref] Getting Over It
- MVP: 1 tall map · one special control scheme · fall-reset · height record — Growth: taller/harder routes → new control twists → ranking → spectate/replay
- **Jump quest (jumpquest)** — Low · TileMap · #precision-jump #fall-penalty #patience-repetition · [ref] Forest of Patience
- MVP: 1 course · precision jumps · fall penalty · goal reward — Growth: course list → themes → clear records → hard variants
### Metroidvania
- **Metroidvania** — High · TileMap/SideView · #ability-unlock #backtracking #exploration #boss-fight · [ref] Hollow Knight, Ori
- MVP: 3 connected rooms · 1 ability gate (e.g., double jump) · 1 boss — Growth: map regions → ability set → bosses → secrets/completion
### Roguelite
- **Run-based roguelite** — Medium · TileMap/RectTile · #run-repetition #random-skills #permanent-upgrade #boss-fight #build-variety · [ref] Hades, Dead Cells
- MVP: 3-room run · random skill offer per room · death = restart + 1 meta upgrade — Growth: room/skill pool → characters → meta tree → bosses/acts
- **Deckbuilding roguelike** — High · RectTile · #run-repetition #path-choice #turn-based-combat #card-acquire #deck-construction · [ref] Slay the Spire
- MVP: 10-card starter · 8-node path · add/remove cards · 1 act boss — Growth: card pool → relics/events → acts → ascension levels
- **Dungeon roguelike** — Medium · TileMap/RectTile · #floor-progression #procedural-generation #permanent-upgrade #item-combine #death-reset · [ref] The Binding of Isaac, Rogue Legacy
- MVP: 3 procedural floors · permadeath · 5 items — Growth: floor themes → item synergies → classes → daily seed runs
### Idle
- **Idle RPG** — Medium · TileMap/RectTile · #auto-combat #prestige #offline-rewards #hero-hiring · [ref] Tap Titans
- MVP: auto-battle stage line · gold → stat upgrades · offline gains — Growth: heroes/skills → prestige loop → dungeons/raids → events
- **Clicker/idle** — Low · RectTile · #upgrade #prestige #click #auto-accumulate · [ref] Cookie Clicker
- MVP: click → currency · 5 upgrades · 1 auto-generator — Growth: generator chain → prestige → achievements → events
### Horror
- **Story horror** — Medium · TileMap/RectTile · #story-presentation #branching-choices #clue-search #unlocking · [ref] The Witch's House, Ib
- MVP: 1 house · limited vision/flashlight · 3 scare events · one escape route — Growth: chapters → chase sequences → endings → lore collectibles
- **Horror escape** — Medium · TileMap/RectTile · #real-time-chase #clue-search #unlocking #stamina-management · [ref] Granny, Ao Oni
- MVP: 1 map · 1 chaser AI · find 3 keys to exit — Growth: maps/chasers → co-op → difficulty tiers → randomized item spots
> **Low-effort picks (good first projects)**: Dodging · Falling-block puzzle · Match-3 · Jump quest · Obstacle run · Gacha sim · Vampire-survivors-like · Shoot-'em-up · Endless runner · Classic arcade remake · Pet raising · Hangout world · Word battle. (Tower defense is the natural next step up — Medium, the top of comfortably-solo.)
---
## 3. Core mechanic tags (by category)
Use these to combine genres or build a one-line concept.
**Progression/structure**: `#wave-progression` (enemies in stronger and stronger batches) `#round-progression` (independent rounds) `#stage-clear` (next on goal reached) `#floor-progression` (going up/down floors) `#run-repetition` (restart from scratch when done) `#path-choice` (pick branches)
**Movement/control**: `#timing-jump` `#precision-jump` `#auto-run` (auto-advance, dodge only) `#physics-movement` `#special-controls` `#obstacle-avoidance` `#moving-obstacles`
**Collection/resource**: `#dex-collection` `#inventory` `#item-combine` `#item-merge` (merge same kinds) `#loot-drop` `#item-looting` `#resource-management` `#resource-gathering` `#resource-allocation` `#coin-collection` `#revenue-management`
**Puzzle/logic**: `#block-rotate` `#block-swap` `#block-slide` `#line-clear` `#rising-fall-speed` `#match-3` `#chain-reaction` `#merge` `#special-blocks` `#logic-deduction` `#hint` `#grid-fill` `#min-moves` `#clue-search` `#unlocking`
**Cards/deck**: `#card-collection` `#card-acquire` `#deckbuilding` (build a combat deck) `#deck-construction` (add/remove during a run) `#mana-management`
**Reset/penalty**: `#death-reset` `#fall-reset` `#fall-penalty` `#elimination`
**Input/judgment**: `#text-input` `#wpm-measure` `#accuracy-check` `#music-sync` `#note-timing` `#combo` `#question-serving` `#answer-checking` `#ox-choice`
**Survival/state**: `#stamina-management` (hunger/HP) `#base-hp` `#survival-time` `#last-one-standing` `#shrinking-map` (shrinking safe zone)
**Random/probability**: `#procedural-generation` `#random-draw` `#random-skills` `#random-game` `#probability-sim` `#unit-merge`
**Shooting/firing**: `#projectile` `#enemy-patterns` `#power-up` `#angle-adjust` `#power-adjust` `#wind-variable` `#terrain-destruction`
**Combat/action**: `#real-time-combat` `#turn-based-combat` `#auto-combat` (composition/strategy only) `#auto-attack` `#skill-use` `#skill-combo` `#boss-patterns` `#pattern-memorization` `#hit-detection` `#combo-system` `#mass-kill` `#real-time-pvp` `#async-pvp`
**Growth/enhancement**: `#leveling` `#level-up-choice` (choices on level-up) `#gear-enhance` `#gear-progression` `#unit-enhance` `#upgrade` `#permanent-upgrade` `#prestige` (permanent bonus after reset) `#job-advance` `#evolution`
**Placement/construction**: `#unit-placement` `#unit-composition` `#synergy-combos` `#placement-strategy` `#object-placement` `#free-placement` `#building`
**Social/multi**: `#party-play` `#multiplayer-co-op` `#role-split` (tank/dps/heal) `#multiplayer` `#many-player-competition` `#many-players` `#it-tagging` `#social-deduction` (hidden roles · discussion · vote-out) `#customer-service` `#npc-dialog` `#npc-affinity`
**Decoration/appearance**: `#housing` `#theme-mission` `#outfit-rating`
**Misc (commonly used)**: `#time-limit` `#attempt-limit` `#turn-limit` `#rising-difficulty` `#score-competition` `#extreme-difficulty` `#patience-repetition` `#speed-competition` `#path-based` (enemies on a set path) `#pathfinding` `#limited-vision` `#stealth` `#map-search` `#exploration` `#ability-unlock` `#backtracking` `#enemy-avoidance` `#omnidirectional-defense` `#story-presentation` `#real-time-chase` `#multi-map` `#branching-choices` `#multiple-endings` `#quest-progression` `#turn-based-movement` `#fast-combat` `#rarity-system` (common/rare/legendary) `#hero-hiring` `#crafting` `#depth-exploration` `#season-system` `#time-passage` `#daily-activities` `#relationship-system` `#open-endedness` `#rule-based` `#win-condition` `#timing-input` `#memory` `#pair-matching` `#enemy-kill` `#track-design` `#menu-product-management` `#animal-husbandry` `#crop-farming` `#recipe-discovery` `#physics-reaction` `#enhance-attempts` `#result-presentation` `#stats-logging` `#click` `#auto-accumulate` `#offline-rewards` `#tech-tree` `#territory-expansion` `#ai-opponent` `#build-variety` `#monster-capture` `#creature-raising` `#skill-combination` `#boss-fight` `#consecutive-battles` `#dungeon-exploration`
references/msw-mapping.md
# Game System → MSW Implementation Mapping Cheat Sheet
Use this to fill the "System ↔ MSW mapping" section of a planning deliverable. Connect each game system to MSW's real implementation means (components · files · skills).
## 1. Map type ↔ camera/physics/movement (nail this down first)
The table that decides the whole stack. **If an entity's Body doesn't match the map type, it won't move or you get `[LEA-3004]` (a silent failure).**
| TileMapMode | View | Body component | Map structure | Gravity | Movement |
|---|---|---|---|---|---|
| `MapleTile` (0) | Side-scroll | `RigidbodyComponent` | `FootholdComponent` platforms | Yes | Left/right + jump |
| `RectTile` (1) | Top-down | `KinematicbodyComponent` | `RectTileMapComponent` tiles | No | Free 4-directional |
| `SideViewRectTile` (2) | Side-scroll | `SideviewbodyComponent` | `RectTileMapComponent` tiles | Yes | Left/right + jump (tile) + ladder/rope |
> For the exact rules · coordinate system (1 unit = 100px) · SpriteRUID etc., follow **msw-general's `references/platform.md`** and `platform-{maple|rect|sideview}.md` during implementation. At the planning stage, only decide up to "pair and nail down the map type and Body."
## 2. System → MSW implementation means
| Game system | MSW implementation | Notes |
|---|---|---|
| Global state · timer · game flow · pause | `@Logic` (GameDirector-style) | Lives the whole world session · survives map transitions |
| Enemy spawn · wave · director | `@Logic` or map-entity `@Component` | If map-scoped, use a map `@Component` |
| Player stats · input · skills · UI control | `@Logic` (PlayerLogic) or player `@Component` | If DefaultPlayer-based, msw-defaultplayer |
| Per enemy/NPC/object behavior | that entity's `@Component` | Lifetime tied to the actor |
| Player movement | per-map-type Body + DefaultPlayer or MovementComponent | See table 1 · **msw-defaultplayer** |
| Avatar appearance · costume · custom action / attack motion | CostumeManagerComponent (17 slots) + AvatarStateAnimationComponent / AvatarRendererComponent | msw-avatar (any avatar entity — player · NPC · monster) |
| Combat (attack · hit · damage · knockback · hit-stop) | msw-combat-system | Includes HP bar · effects. Refs: monster setup & **facing** → msw-general `monster.md`; projectile → `projectile.md`; HP → `hp-gauge.md` |
| Behavior-tree (BT) AI / FSM | msw-behaviourtree / StateComponent | |
| Data (stats · economy · drops · difficulty curve) | UserDataSet (dataset, CSV) | "Data-driven": CSV is the source of truth, update without code changes. Migrate hardcoded values → dataset when the value-set grows (plan it as a §6 later-Phase task, or a milestone-roadmap entry when it lands beyond the milestone) |
| Localized text | LocaleDataSet | Mind ClientOnly |
| Persistent save (save · progress) | `_DataStorageService` | Key-value persistence |
| UI (HUD · popup · button · card select etc.) | `.ui` + UIBuilder (msw-ui-system) | Never edit raw JSON |
| Camera · screen-transition effects | CameraComponent/CameraService · ScreenTransitionService | |
| Particles · effects | ParticleService · EffectService | |
| Sound · BGM | SoundComponent · SoundService + msw-search | |
| Sprite · animation resources | search a RUID via msw-search → **assign it to the renderer (msw-sprite-ruid)** | If none found, draw directly with msw-painter |
| Model (entity appearance · physics · motion) | `.model` + ModelBuilder | |
| Entity placement · map | `.map` + MapBuilder | SpawnByModelId parent ≠ nil |
| Shop · item · badge (commerce) | world_item / world_badge / WorldShopService | Connect with BM deliverables |
| Standard game systems (inventory · ranking · quest etc.) | **check the msw-packages catalog first** | Don't build from scratch |
## 3. Scope rule — @Logic vs @Component
- **@Logic**: one per world, survives map transitions. For game flow · global managers. (Putting map-only state in @Logic leaks into the next map → reset it in `OnMapLeave`.)
- **Map-entity @Component**: content that lives only in that map (wave spawner · mini-game · NPC dialog). Cleaned up on map unload.
- **Actor @Component**: behavior of a specific entity (monster AI · item pickup). Lifetime tied to that actor.
- Decision test: *"Should it keep running when you move to another map?"* → Yes = @Logic / this map only = map @Component / this actor only = actor @Component.
## 4. Skills to reference when moving to implementation
> Point to the **specific reference doc**, not just the skill — that's where the silent-failure gotchas live (e.g. enemy facing). Don't copy the rules here; link to them.
- `msw-general` — platform/authoring foundation. Map-type/coords/SpriteRUID → `references/platform.md` (+ `platform-{maple|rect|sideview}.md`); **monster `.model` & facing → `references/monster.md`**; animation/FSM state → `references/animation-state.md`; tiles → `references/tile.md`; `.model` → `references/model.md`; entity placement/`.map` → `references/entity.md`; dataset (UserDataSet/LocaleDataSet · hardcoded→data) → `references/dataset.md`.
- `msw-scripting` — `.mlua` authoring · lifecycle · events; verify loop → `references/verify-checklist.md`; save/persist → `references/datastorage.md`.
- `msw-defaultplayer` — DefaultPlayer-based player: move speed · jump · HP · camera · auto/programmatic (AI-driven) control.
- `msw-avatar` — costume (17 equip slots) · avatar animation states · custom shoot/cast/dance · weapon-specific attack motion; any avatar-bearing entity (not only DefaultPlayer).
- `msw-ui-system` — `.ui` builder · HUD/popup/toast; component API → `references/component-api.md`; runtime patterns → `references/runtime-patterns.md`.
- `msw-combat-system` — combat concepts; **monster setup → `msw-general/references/monster.md`**; HP gauge → `references/hp-gauge.md`; projectile → `references/projectile.md`; BT/AI → `references/ai-bt.md`; FSM/state → `msw-general/references/animation-state.md`.
- `msw-behaviourtree` — authors `.behaviourtree` files (node graph · Blackboard · nodeProperties) + per-project bt-spec. (Combat-AI *concepts* → msw-combat-system `references/ai-bt.md`.)
- `msw-packages` — standard-systems catalog (inventory/shop/ranking/quest) — check before building.
- `msw-search` / `msw-painter` — resource search / draw a sprite directly.
- `msw-sprite-ruid` — assign a RUID to a renderer (`SpriteRUID` world / `ImageRUID` UI) · `thumbnail://` item & avatar icons. msw-search **finds** → msw-sprite-ruid **applies** (fixes empty-SpriteRUID → invisible).
SKILL.md
---
name: msw-planning
description: "MSW (MapleStory Worlds) game-planning mode — for BOTH starting a brand-new game from scratch AND continuing/resuming an in-progress prototype. Narrow the idea with guided questions, ground it in the MSW genre catalog (3 map types, ~180 core mechanic tags, build-effort hints), and produce or advance an implementation-ready GDD / roadmap (markdown). Trigger proactively (even without the word 'planning') whenever the user wants to decide WHAT to build, scope an MVP, or continue/resume a phased build — INCLUDING when a Docs/*-GDD.md or *-Phase*.md already exists and the user says to continue: do NOT treat that as plain implementation and jump straight into the phase doc; a continue/resume runs through this skill's resume flow first. Match triggers by intent, not exact wording — variants like 'what now?', 'where were we?', and their equivalents in ANY language fire it too. A comprehensive build request spanning multiple implementation pieces, made while no GDD exists, is ALSO a planning trigger — not a plain implementation request, with NO 'small/simple game' exception; implementing that without a plan is the exact failure mode this skill prevents. Triggers: 'plan a new game', 'GDD', 'what game should I make', 'scope an MVP', 'planning mode', 'continue my game', 'resume my game', 'what should I work on next', 'next task'. (Plans & manages the game's build across its milestones — GDD · standing milestone roadmap · phase plans · progress · revisions; does NOT write code — implementation (.mlua/.model etc.) uses msw-general/msw-scripting.)"
---
# 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.