start skill

Guided Onboarding

This skill writes project.yaml — the project.stage, modes.rigor and modes.automation settings — plus one legacy mirror, production/stage.txt, for backward compatibility with hooks that have not migrated. modes.rigor and modes.automation have no legacy mirror; they are written to project.yaml only.

/start never writes modes.reviewmode, in either location.** It is a

rigor-fronted knob: writing it explicitly pins it and shadows the modes.rigor

expansion, so the Phase 3d question would stop changing director-review depth

(see Phase 3d, and the same rule in project.yaml's header comment). It must

not write production/review-mode.txt either — the legacy step sits

above the rigor expansion in the resolution chain, deliberately, so a genuine

v1.0 project's explicit choice survives migration. On a new project that

ordering works against you: a mirror file written here would outrank the

expansion permanently. Verified: rigor: minimal plus a review-mode.txt

containing lean resolves to lean, not the expected solo.

This skill is the entry point for new users. It does NOT assume you have a game idea, an engine preference, or any prior experience. It asks first, then routes you to the right workflow.

Automation mode: Resolve modes.automation (project.local.yaml → project.yaml → default collaborative). Note: on a fresh project no modes.automation is set yet, so /start runs collaboratively — it is creating the config. Its core onboarding questions (starting point, rigor, automation) are project-shaping and always prompt regardless of mode. Engine choice is not among them — it is deferred to /setup-engine, which Phase 4 hands off to. If /start is re-run on an already-configured project, the resolved mode applies per .claude/docs/automation-modes.md.

Phase 1: Detect Project State

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:

• Engine configured? Read engine.name from project.yaml; if that key is absent or empty (including when project.yaml has no engine: block), fall back to .claude/docs/technical-preferences.md (an Engine field of [TO BE CONFIGURED], or no file, means not set). The engine is configured if either source yields a real engine name.
• Game concept exists? Check for design/gdd/game-concept.md (or design/game-brief.md at the minimal tier).
• Source code exists? Resolve the code root from the engine.name read above (src/ Godot, Assets/ Unity, Source/ Unreal; full order in .claude/docs/code-root-resolution.md), then Glob it for source files (.gd, .cs, .cpp, .h, .rs, .py, .js, .ts). If the code root is unresolved, say so rather than concluding there is no code — a Unity or Unreal project scanned as src/ returns zero files and reads as greenfield.
• 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 to validate the user's self-assessment and tailor recommendations.

Phase 2: Ask Where the User Is

This is the first thing the user sees. Use AskUserQuestion with these exact options so the user can click rather than type:

• Prompt: "Welcome to Claude Code Game Studios! Before I suggest anything, I'd like to understand where you're starting from. Where are you at with your game idea right now?"
• Options:
• 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 selection. Do not proceed until they respond.

Phase 3: Route Based on Answer

If A: No idea yet

The user needs creative exploration before anything else.

1. Acknowledge that starting from zero is completely fine
2. Briefly explain what /brainstorm does: it turns "no idea" into a written design your next step can build from. Mention that it has two modes: /brainstorm open for fully open exploration, or /brainstorm [hint] if they have even a vague theme (e.g., "space", "cozy", "horror").

Describe it tier-neutrally here. Phase 3d has not run, so you do not yet

know how much process this project wants — and /brainstorm changes shape

completely on that answer. At minimal it runs a short Lean Brief flow and

stops, producing a one-page design/game-brief.md; at standard/full it

runs the full ideation walk (MDA, player psychology, verb-first design) and

produces the concept document. Naming the full walk here, then having Phase 4

describe the same skill as "produce the one-page brief", gives the user two

contradicting accounts of one skill inside a single /start run. Phase 4 is

where the tier-specific description belongs.

full pipeline here. Phase 3d has not yet asked how much process the user wants, and that answer changes the path substantially. Say: "I'll lay out the full path once I know how much process you want — two quick questions away."

1. Recommend running /brainstorm open as the next step, but invite them to use a hint if something comes to mind
2. Name the immediate next step only — /brainstorm open. Do not list the

If B: Vague idea

list the full pipeline here; Phase 3d has not yet asked how much process the user wants, and that answer changes the path. Say: "I'll lay out the full path once I know how much process you want — two quick questions away."

1. Ask them to share their vague idea — even a few words is enough
2. Validate the idea as a starting point (don't judge or redirect)
3. Recommend running /brainstorm [their hint] to develop it
4. Name the immediate next step only — /brainstorm [their hint]. Do not

If C: Clear concept

1. Ask them to describe their concept in one sentence — genre and core mechanic. Use plain text, not AskUserQuestion (it's an open response).
2. Acknowledge the concept, then use AskUserQuestion to offer two paths:

• Prompt: "How would you like to proceed?"
• Options:
• Formalize it first — Run /brainstorm [concept] to structure it into a proper game concept document
• Jump straight in — Go to /setup-engine now and write the GDD manually afterward

the full pipeline here; Phase 3d has not yet asked how much process the user wants, and that answer changes the path. Say: "I'll lay out the full path once I know how much process you want — two quick questions away."

1. Name the immediate next step only — their pick from step 2. Do not list

If D: Existing work

1. Share what you found in Phase 1:

• "I can see you have [X source files / Y design docs / Z prototypes]..."
• "Your engine is [configured as X / not yet configured]..."

1. Sub-case D1 — Early stage (engine not configured or only a game concept exists):

• Recommend /setup-engine first if engine not configured
• Then /project-stage-detect for a gap inventory

Sub-case D2 — GDDs, ADRs, or stories already exist:

• Explain: "Having files isn't the same as the template's skills being able to use them. GDDs might be missing required sections. /adopt checks this specifically."
• Recommend:

1. /project-stage-detect — understand what phase and what's missing entirely
2. /adopt — audit whether existing artifacts are in the right internal format

1. Show the recommended path for D2:

• /project-stage-detect — phase detection + existence gaps
• /adopt — format compliance audit + migration plan
• /setup-engine — if engine not configured
• /design-system retrofit [path] — fill missing GDD sections
• /architecture-decision retrofit [path] — add missing ADR sections
• /architecture-review — bootstrap the TR requirement registry
• /gate-check — validate readiness for next phase

Phase 3c: Write Initial Stage

After confirming the starting path, write the initial stage to BOTH project.yaml (primary) AND production/stage.txt (legacy fallback for hooks that haven't migrated yet). Create the production/ directory if it does not exist.

In project.yaml, ensure a project: block exists with stage: [value].

file to have been read in this session), then use the Edit tool to add/update the project: block, placing it immediately after the framework: block.