| name | start |
| description | First-time onboarding — asks where you are, then guides you to the right workflow. No assumptions. |
| argument-hint | [no arguments] |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, AskUserQuestion |
Guided Onboarding
Local / OpenAI-compatible clients: read STUDIO.md and skill start-local
for the same routing without Claude Code /slash UI; skill names (setup-web, etc.) are stable command ids.
This skill is the entry point for new users. It does NOT assume you have a game
idea, a web framework preference, or any prior experience. It asks first, then routes
you to the right workflow.
Workflow
1. Detect Project State (Silent)
Before asking anything, silently gather context so you can tailor your guidance.
Do NOT show these results unprompted — they inform your recommendations, not
the conversation opener.
Check:
- Web stack configured? Read
.claude/docs/technical-preferences.md. If the
web stack still reads [TO BE CONFIGURED], run setup-web first.
- Game concept exists? Check for
design/gdd/game-concept.md.
- Source code exists? Glob for source under
src/web/, src/platforms/, packages/shared/ (*.ts, *.js, etc.).
- Prototypes exist? Check for subdirectories in
prototypes/.
- Design docs exist? Count markdown files in
design/gdd/.
- Production artifacts? Check for files in
production/sprints/ or
production/milestones/.
Store these findings internally. You will use them to validate the user's
self-assessment and to tailor follow-up recommendations.
2. Ask Where the User Is
This is the first thing the user sees. Present these 4 options clearly:
Welcome to the studio (H5 + Mini Games fork)!
Before I suggest anything, I'd like to understand where you're starting from.
Where are you at with your game idea right now?
A) No idea yet — I don't have a game concept at all. I want to explore
and figure out what to make.
B) Vague idea — I have a rough theme, feeling, or genre in mind
(e.g., "something with space" or "a cozy farming game") but nothing concrete.
C) Clear concept — I know the core idea — genre, basic mechanics, maybe
a pitch sentence — but haven't formalized it into documents yet.
D) Existing work — I already have design docs, prototypes, code, or
significant planning done. I want to organize or continue the work.
Wait for the user's answer. Do not proceed until they respond.
3. Route Based on Answer
If A: No idea yet
The user needs creative exploration before anything else. Engine choice,
technical setup — all of that comes later.
- Acknowledge that starting from zero is completely fine
- Briefly explain what
/brainstorm does (guided ideation using professional
frameworks — MDA, player psychology, verb-first design)
- Recommend running
/brainstorm open as the next step
- Show the recommended path:
/brainstorm — discover your game concept
/setup-web — pin the TypeScript web stack (and mini game skills when needed)
/map-systems — decompose the concept into systems and plan GDD writing order
/prototype — test the core mechanic
/sprint-plan — plan the first sprint
If B: Vague idea
The user has a seed but needs help growing it into a concept.
- Ask them to share their vague idea — even a few words is enough
- Validate the idea as a starting point (don't judge or redirect)
- Recommend running
/brainstorm [their hint] to develop it
- Show the recommended path:
/brainstorm [hint] — develop the idea into a full concept
/setup-web — configure the web stack
/map-systems — decompose the concept into systems and plan GDD writing order
/prototype — test the core mechanic
/sprint-plan — plan the first sprint
If C: Clear concept
The user knows what they want to make but hasn't documented it.
- Ask 2-3 follow-up questions to understand their concept:
- What's the genre and core mechanic? (one sentence)
- Do they have an engine preference, or need help choosing?
- What's the rough scope? (jam game, small project, large project)
- Based on their answers, offer two paths:
- Formalize first: Run
/brainstorm to structure the concept into a
proper game concept document with pillars, MDA analysis, and scope tiers
- Jump to web setup: If they're confident in their concept, go
straight to
/setup-web and write the GDD manually afterward
- Show the recommended path (adapted to their choice):
/brainstorm or /setup-web (their pick)
/design-review — validate the concept doc
/map-systems — decompose the concept into individual systems with dependencies and priorities
/design-system — author per-system GDDs (guided, section-by-section)
/architecture-decision — make first technical decisions
/sprint-plan — plan the first sprint
If D: Existing work
The user has artifacts already. Figure out what exists and what's missing.
- Share what you found in Step 1 (now it's relevant):
- "I can see you have [X source files / Y design docs / Z prototypes]..."
- "Your engine is [configured as X / not yet configured]..."
- Recommend running
/project-stage-detect for a full analysis
- If the web stack isn't configured, note that
/setup-web should come first
- Show the recommended path:
/project-stage-detect — full gap analysis
/setup-web — if not configured
/design-system — if systems index exists but GDDs are incomplete
/gate-check — validate readiness for next phase
/sprint-plan — organize the work
4. Confirm Before Proceeding
After presenting the recommended path, ask the user which step they'd like
to take first. Never auto-run the next skill.
"Would you like to start with [recommended first step], or would you prefer
to do something else first?"
5. Hand Off
When the user chooses their next step, let them invoke the skill themselves
or offer to run it for them. Either way, the /start skill's job is done
once the user has a clear next action.
Edge Cases
- User picks D but project is empty: Gently redirect — "It looks like the
project is a fresh template with no artifacts yet. Would Path A or B be a
better fit?"
- User picks A but project has code: Mention what you found — "I noticed
there's already code in
src/. Did you mean to pick D (existing work)? Or
would you like to start fresh with a new concept?"
- User is returning (web stack configured, concept exists): Skip onboarding
entirely — "It looks like you're already set up! Your stack is [X] and you
may have a game concept at
design/gdd/game-concept.md. Want to pick up where
you left off? Try /sprint-plan or just tell me what you'd like to work on."
- User doesn't fit any option: Let them describe their situation in their
own words and adapt. The 4 options are starting points, not a prison.
Collaborative Protocol
This skill follows the collaborative design principle:
- Ask first — never assume the user's state or intent
- Present options — give clear paths, not mandates
- User decides — they pick the direction
- No auto-execution — recommend the next skill, don't run it without asking
- Adapt — if the user's situation doesn't fit a template, listen and adjust