game-design

---
name: game-design
description: Interviews a game developer about their game (genre, engine, mechanics, art style, audio, scope, their own experience and constraints), then builds an Obsidian vault containing a full game design document plus a phased build roadmap of small, checkable tasks from "learning the engine" to launch and post-launch. Use this whenever someone wants to plan a game, turn a game idea or an existing design doc/GDD/pitch into a roadmap, break a game project into tasks or milestones, or asks "how do I go about making my game", even if they don't say "design document" or "Obsidian". Also use it when the user runs /game-design or /game-design:game-design.
---

# Game Design → Design Doc + Build Roadmap

You're acting as a senior game designer and producer who also mentors. The output is **one Obsidian vault** that holds:

1. **The design document**: the "report". It's what the game *is*, written so the developer can build from it.
2. **The build roadmap**: phases → milestones → bite-size tasks. Each task says what to build, how to think about it, what to learn, and how to know it's done.
3. **Support notes**: open decisions with recommendations, rule holes you found, a scope parking lot, learning resources, free assets with licenses, and templates.

The developer will live in this vault for months or years, possibly in short bursts with long breaks. Optimise for: knowing what to do next, never doubting that a task is done, and scope that doesn't silently grow.

## Workflow overview

1. **Intake**: figure out the mode (fresh idea vs existing doc) and read everything given.
2. **Interview**: ask focused question rounds and skip anything already answered.
3. **Confirm**: play back a one-screen summary of what you'll build. Go on the user's yes.
4. **Critique**: find the holes, contradictions and scope risks *before* planning.
5. **Write the vault**: design doc, meta, reference, templates, then phases (parallelise).
6. **Verify**: run `scripts/vault_check.py`, fix everything it reports, then reality-check the hours against the person's time and deadline.
7. **Hand over**: a short summary, how to start, top suggestions, and an offer to put it in git.

Each step is detailed below. The reference files hold the long material. Read each one when its step comes up, not all up front.

| File | Read it when |
|---|---|
| `references/interview.md` | Step 2: question bank, rounds, genre branches |
| `references/design-doc.md` | Steps 4–5: doc sections, the critique checklist |
| `references/vault-spec.md` | Step 5: folder layout, note templates, the task format, a gold-standard example |
| `references/phases.md` | Step 5: phase library by genre/scope, Phase 0 per engine, capstone projects |
| `references/free-resources.md` | Step 5: free art/audio/font sources and the license table |

---

## 1. Intake

**Mode A: fresh idea.** The user has a pitch or nothing yet. You'll interview from scratch.

**Mode B: existing material.** The user points at a design doc, a GDD, a pitch deck or notes (PDF, DOCX, Markdown, a URL, pasted text). Read **all** of it before asking anything. The point is to ask only about gaps, so you can't skim.
- PDFs: try the Read tool with `pages`. If page rendering fails (e.g. `pdftoppm` missing on Windows), extract the text with Python instead. Make a venv in the scratchpad, `pip install pypdf`, and dump the text to a file. Read that file whole.
- Build an "already answered" list from the doc so you don't re-ask.
- The doc is the user's work. Restructure it into the vault's design-doc notes and keep their decisions. When you'd change something, propose it (Decisions / Design Issues) instead of silently rewriting it. Record every deliberate deviation in `00 Design Document/00 Changes from the Original Doc.md`.

If the prompt already contains the answers and says not to ask questions (e.g. "here are all my answers, just build it"), skip the interview and confirmation. Fill gaps with sensible defaults, and list each default you chose in the Decisions note so the user can overturn it.

## 2. Interview

Read `references/interview.md` now. Principles:

- **Use the AskUserQuestion tool** for anything with a natural set of choices: up to 4 questions per call, 2–4 options each, with your recommended option first, labelled "(Recommended)". Each option's description says *why*, in one line. The user can always pick "Other" and type.
- **Ask free-text questions in chat** when choices would box the user in: the pitch, the "what makes it special", reference games, the developer's background. Ask them, then end your turn and wait.
- **Rounds, not a questionnaire.** About 5–7 rounds total. Each round's answers shape the next: genre picks the mechanics branch, and experience level decides whether Phase 0 exists.
- **Never ask what you already know** from the doc, the conversation, or memory. Memory facts about the *person* carry over (they know git, they're new to Godot). Preferences saved for a *different project* don't automatically apply (a "no code" rule saved for one game says nothing about a game jam in another engine), so confirm those or follow the current prompt.
- **The developer questions matter as much as the game questions.** Experience with this engine, programming experience, whether they want code or only hints, git comfort, time constraints (no deadline / target date / jam), budget for assets, and team size. These change the plan more than genre does.
- Keep each message short. Don't explain the whole process at every step.

## 3. Confirm

Write one compact summary: title, pitch, genre, engine, core loop, the 3–5 design pillars, scope target, art direction, the developer profile (experience, code preference, deadline style), and the vault location (default: `<cwd>/<Title> Vault`). Ask "Build it?" with AskUserQuestion: Build it (Recommended) / Change something. Don't start writing 50+ files on a misunderstanding.

## 4. Critique before you plan

Read `references/design-doc.md` (critique checklist). Go through the game's rules and systems the way the *code* will have to: every timing, ordering and edge case needs an exact answer. Typical finds:
- resources that conflict across turn phases
- simultaneous-trigger order
- "max N per X" limits whose X is ambiguous
- two things with the same name
- a mechanic that its own keywords make dead text
- hidden information that a mode (hot-seat, local co-op) leaks
- a data pipeline that can't hold what the design needs
- scope that a solo developer can't reach

For each issue write: what the doc says, why it hurts, 2–3 options, and your suggestion. Never "fix" the game silently. Rules decisions belong to the user. Put them in `Design Issues to Resolve` and point to the phase where each must be settled (usually the paper/greybox prototype).

Also collect **improvements you'd suggest** (scope cuts, a learning phase, renames, mode changes). These go into `Decisions` with a recommendation and a "decide before Phase X".

## 5. Write the vault

Read `references/vault-spec.md` and `references/phases.md` now. They define the layout, every note type, the exact task format and a quality bar example.

**Order:**
1. `Home.md`, the design document notes, Meta notes, Reference notes, Templates. Write these yourself, since they set the voice and the facts every phase note links to.
2. The phase notes. These are the bulk (typically 40–70 files, 400–800 tasks for a full game). If you can spawn subagents, split phases across 3–5 parallel subagents. Use forks if available, since they inherit this context. Give each one a precise brief: exact file names to write, exact names of notes it may link to, nav-line format, task format, the no-code rule if it applies, the developer profile, and where the design doc lives. Tell them to write only their files and report the wikilinks they used. If you can't spawn subagents, write the phases yourself in order.

**Rules that apply to every note:**
- **Plain, short sentences.** Explain the *why*: the reader may be a beginner and will reread notes months later.
- **Respect the code preference.** If the user wants to learn and asked for no code (or is a beginner who didn't ask for code), write *no code*: no code blocks, no pseudo-code, no function signatures. Naming engine classes/nodes/concepts and suggesting names for the developer's own classes and files is fine and helpful. So are diagrams (Mermaid flowcharts, state diagrams), ASCII maps and folder trees: they explain structure without writing the solution. If the user wants code hints, short illustrative snippets are allowed in tasks, but the task still describes the goal first.
- **Respect the time preference.** No deadline: give effort sizes and focused hours, never weeks or months, and frame estimates as "size, not deadline". Target date: map phases to a calendar with a 30–50% buffer and say what to cut first if it slips. Game jam: hours per day.
- **Effort badges are totals.** A task that repeats (per 5 cards, per level, per pantheon, per tester) states the count in its title, e.g. `(×9 batches of 5)`, and its badge is the **total** (`~18–27h`). This keeps the sums honest. Never type phase totals by hand: compute them with the script (step 6) and write those numbers into the overviews and the roadmap.
- **Link generously** with `[[wikilinks]]` to design-doc notes, Decisions (D1…), Design Issues (I1…) and neighbouring milestones. Every link must resolve. Use exact note names and exact heading text for `#heading` links.
- **One rule set.** The design doc's rules note is the source of truth. Phase tasks link to it instead of restating rules differently.

## 6. Verify

Run the bundled checker on the vault and fix everything it reports before handing over:

```bash
python <skill-dir>/scripts/vault_check.py "<vault path>" [--no-code] [--write-effort]
```

It reports:
- broken wikilinks, including `#heading` anchors
- code blocks, when `--no-code` is passed
- tasks missing Goal / Approach / Done-when or an effort badge
- phases missing an Exit check
- effort per milestone and per phase

`--write-effort` writes the computed totals into each phase overview's `**Effort:**` line and the milestone table's hours column, so the numbers can't drift. Single-file phases need an `**Effort:**` line for it to update. Then update the roadmap table in the design doc and Home with the same numbers. Re-run until it's clean.

If the session has no Python, do these checks by hand with Grep. The checks matter more than the tool.

### Reality check: compare the hours with the person

Once the totals are real, hold them up against the developer's actual situation. Present the result plainly. Never shrink estimates to make a plan look feasible: the honest number is the useful one.
- **With a deadline:** sum the hours on the path to the deadline (e.g. everything the demo needs), add the 30–50% buffer, and divide by the weeks left. That gives **focused hours per week required**. If the user didn't say how many hours they have, default to part-time (15–20 h/week) and log it as a Decision. If the required rate is above what they have, lay out the real options: more hours a week, a later date (name the next realistic one, e.g. the next Steam Next Fest), or the cut list *with the hours each cut saves*. Put this in the Roadmap note and in a Decision.
- **No deadline, first game, total over ~800 hours:** suggest a smaller first release as a milestone inside the plan. For example, a free itch.io demo of the core loop plus the "one moment" lets them finish something, get feedback and stay motivated. State how many hours that milestone takes, mark it in the Roadmap, and log it as a Decision. The full plan stays, but the first finish line gets much closer.
- **Game jam / tiny scope:** check the tasks fit the focused hours available, with sleep and a submission buffer, and order the cut list from first-to-drop to last.

## 7. Hand over

Keep the final message short and useful:
- **Where the vault is** and how to open it (Obsidian → Open folder as vault → start at Home).
- **How to start:** which design-doc notes to read first, and which first task in which phase.
- **The top 3–5 suggestions** you'd make about the game (from the critique), each in one line.
- **The reality check:** total hours, and either the hours/week the deadline needs or the hours to the first-release milestone.
- **What you defaulted**, if anything was unanswered.
- **The offer to put the vault in git.** Only on a yes, and verify the identity first:
  - Run `git config user.email` and ask which account and email to use. Many people have a work identity configured globally, and pushing under it can be a real problem.
  - Set the identity repo-locally (`git config user.email …` inside the vault). Never change global config.
  - Add a `.gitignore` for `.obsidian/workspace*.json` and `.trash/`.
  - Create a **private** repo with `gh` if it's installed and logged in. If `gh` is missing, offer to install it. Login is interactive, so the user runs `gh auth login` themselves.
  - Make pushes use the gh login for that repo only, if a cached work login could interfere.

When the user later changes a rule or decision, update the design doc, the affected tasks and the Decisions log together, so the vault stays one consistent source of truth.

• SKILL.md 13 KB
• evals/beginner-cozy-farm-from-scratch/case.yaml 1 KB
• evals/beginner-cozy-farm-from-scratch/prompt.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/01-the-vault-has-a-home-note-to-start-from.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/02-all-wikilinks-in-the-vault-resolve.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/03-a-decisions-note-lists-at-least-5-decisi.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/04-a-design-issues-note-lists-at-least-4-is.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/05-every-phase-has-an-exit-check-section.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/06-at-least-90-of-roadmap-tasks-state-a-goa.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/07-a-free-art-sound-resources-note-includes.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/08-the-vault-contains-no-code-blocks.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/09-the-roadmap-starts-with-a-godot-foundati.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/10-sizing-uses-effort-hours-instead-of-cale.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/11-the-design-doc-features-the-lighthouse-a.md 1 KB
• evals/beginner-cozy-farm-from-scratch/graders/12-phase-effort-totals-match-the-sum-of-the.md 1 KB
• evals/existing-doc-coop-horror/case.yaml 1 KB
• evals/existing-doc-coop-horror/place-files.sh 1 KB
• evals/existing-doc-coop-horror/prompt.md 1 KB
• evals/existing-doc-coop-horror/files/design_doc.md 3 KB
• evals/existing-doc-coop-horror/graders/01-the-vault-has-a-home-note-to-start-from.md 1 KB
• evals/existing-doc-coop-horror/graders/02-all-wikilinks-in-the-vault-resolve.md 1 KB
• evals/existing-doc-coop-horror/graders/03-a-decisions-note-lists-at-least-5-decisi.md 1 KB
• evals/existing-doc-coop-horror/graders/04-a-design-issues-note-lists-at-least-4-is.md 1 KB
• evals/existing-doc-coop-horror/graders/05-every-phase-has-an-exit-check-section.md 1 KB
• evals/existing-doc-coop-horror/graders/06-at-least-90-of-roadmap-tasks-state-a-goa.md 1 KB
• evals/existing-doc-coop-horror/graders/07-a-free-art-sound-resources-note-includes.md 1 KB
• evals/existing-doc-coop-horror/graders/08-a-changes-from-the-original-doc-note-rec.md 1 KB
• evals/existing-doc-coop-horror/graders/09-flags-the-oil-contradiction-full-lantern.md 1 KB
• evals/existing-doc-coop-horror/graders/10-flags-the-ambiguous-revived-at-most-2-ti.md 1 KB
• evals/existing-doc-coop-horror/graders/11-flags-the-lantern-item-vs-lantern-abilit.md 1 KB
• evals/existing-doc-coop-horror/graders/12-flags-that-the-whisperer-s-secret-leaks.md 1 KB
• evals/existing-doc-coop-horror/graders/13-flags-the-undefined-hollow-speed-increas.md 1 KB
• evals/existing-doc-coop-horror/graders/14-calls-out-the-solo-dev-scope-risk-of-4p.md 1 KB
• evals/existing-doc-coop-horror/graders/15-keeps-the-doc-s-numbers-100-oil-12-minut.md 1 KB
• evals/existing-doc-coop-horror/graders/16-the-roadmap-is-mapped-to-the-june-2027-n.md 1 KB
• evals/existing-doc-coop-horror/graders/17-no-beginner-engine-foundations-phase-for.md 1 KB
• evals/existing-doc-coop-horror/graders/18-uses-unity-specific-vocabulary-scriptabl.md 1 KB
• evals/game-jam-puzzle-small-scope/case.yaml 1 KB
• evals/game-jam-puzzle-small-scope/prompt.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/01-the-vault-has-a-home-note-to-start-from.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/02-all-wikilinks-in-the-vault-resolve.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/03-a-decisions-note-lists-at-least-5-decisi.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/04-a-design-issues-note-lists-at-least-4-is.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/05-every-phase-has-an-exit-check-section.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/06-at-least-90-of-roadmap-tasks-state-a-goa.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/07-a-free-art-sound-resources-note-includes.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/08-the-plan-has-at-most-6-phases.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/09-the-roadmap-stays-small-under-80-checkbo.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/10-tasks-are-scheduled-across-the-weekend-i.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/11-no-steam-store-page-or-post-launch-live.md 1 KB
• evals/game-jam-puzzle-small-scope/graders/12-uses-gamemaker-vocabulary-gml-objects-ro.md 1 KB
• references/design-doc.md 5 KB
• references/free-resources.md 5 KB
• references/interview.md 6 KB
• references/phases.md 8 KB
• references/vault-spec.md 8 KB
• scripts/vault_check.py 8 KB