Start

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.review_mode, 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/.
• Still wired to the template repo? Read .git/config if it is a file. If its [remote "origin"] url contains donchitos/claude-code-game-studios, compared case-insensitively, the user cloned the template and origin still points at it — so git push and gh pr create target the CCGS repo, not their game. A fork (the same repo name under another owner) is the user's own and does not count. Note it: it is reported on every path, the returning user's included. Read only; never run git.

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 — unless Phase 1 found a returning user (engine configured, and a concept or brief present): then ask nothing here and answer as the User is returning edge case below. Otherwise, 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.

3. Recommend running /brainstorm open as the next step, but invite them to use a hint if something comes to mind

4. Name the immediate next step only — /brainstorm open. Do not list the 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."

If B: Vague idea

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 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."

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 write it down: a one-page brief at rigor: minimal (the default), a full concept document above it
     • Jump straight in — Go to /setup-engine now and write the design down afterward
3. Name the immediate next step only — their pick from step 2. Do not 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."

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]..."

2. 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

3. For D2, name the immediate next step only — /project-stage-detect. The rest of the D2 path depends on rigor, which Phase 3d has not asked yet, so Phase 4 prints it. Say: "I'll lay out the full path once I know how much process you want — two quick questions away."

---

Phase 3c: Write Initial Stage

Ask before the project.yaml write: "May I write project.stage: [stage] to project.yaml (and the legacy mirror production/stage.txt)?" Take [stage] from the Stage mapping below; say the file will be created when there is none, and that the Phase 3d and 3e answers will go there too when those questions are still to be asked. That one approval covers this write and the Phase 3d and 3e writes. If the user declines, write neither file, keep the stage and those answers for this run only, and say they were not saved.

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].

• If project.yaml already exists: Read it first (the Edit tool requires the 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.
• If project.yaml does not exist at the repo root: create it with the Write tool using this v1.1 minimal template (replace [value] and the date):

  # CCGS project configuration — single source of truth for project settings.
  # Schema: grep the `## <key>` section of .claude/docs/effects-map.md —
  # it is ~31k tokens whole, ~900 per section. Do not open it entire.
  
  schema_version: 1
  
  framework:
    version: 1.1.2
    last_upgraded: <YYYY-MM-DD>
  
  project:
    stage: [value]

  Do not seed modes.review_mode here. It is a rigor-fronted knob — modes.rigor supplies its value, so an explicit value here would shadow the rigor expansion and pin the review mode regardless of the rigor the user picks in Phase 3d. modes.rigor itself is omitted for a related reason: Phase 3d skips its question when the key is already set, so seeding it would suppress that question. The other knobs modes.rigor fronts — modes.workflow, docs.density, qa.level, modes.story_granularity, team.size — are never written by /start either, here or in Phase 3d: each would pin its value over the rigor expansion.

Then also write the same single-line stage name to production/stage.txt (no trailing newline) so legacy tooling still works.

Stage mapping:

• Path A, B, or C (starting from scratch): write Concept
• Path D, existing project, engine not configured or only a game concept exists: write Concept
• Path D, existing project with GDDs but no architecture documents: write Systems Design
• Path D, existing project with full architecture (ADRs, architecture doc): write Technical Setup

production/stage.txt is covered by the same ask: it is a one-line legacy mirror of the stage approved for project.yaml, kept for hooks that have not migrated.

Say: "I've set project.stage to [stage] (and updated production/stage.txt) — this anchors your status line and stage detection."

---

Phase 3d: Set Rigor

Check whether modes.rigor is already set in project.yaml. If it is, show it — "Rigor is set to [current]." — and proceed to Phase 3e. Do not ask again. Either way, carry the resolved value forward — Phase 4 branches its recommended path on it.

If it is not set: first pick a recommendation, then ask.

Seed the recommendation from what the user described in Phase 2, using the archetype presets in .claude/docs/settings-guidance.md § 2–3:

• Map their concept to an archetype (e.g. "open-world RPG with crafting and factions" → systems-heavy → full; "a small weekend puzzler" → minimal).
• If the user has no concept at all (Path A, or a Path B hint with nothing in §3's signal table), recommend the jam/prototype option (minimal) and add: "You can raise this after /brainstorm once the concept is clearer — /settings changes it anytime."
• A Path B hint still counts as a description. "Still exploring" is about having no signal, not about which path the user picked. If the vague idea trips §3's signals — "some kind of open-world survival sim" hits open-world, sim and survival — seed from the signal, not from the path, and say why in the user's own terms. Recommending minimal for a described systems-heavy game is the mismatch Phase 4 would then have to flag, caused here.
• If nothing in the description points either way, recommend minimal, the documented default, and add: "/settings raises it once the game shows it needs more."

Then use AskUserQuestion. Order the options so the recommended archetype is first and append (Recommended) to its label (per the AskUserQuestion convention); the other two follow in any order.

• Prompt: "What best describes what you're building? This sets how much process the project carries — you can change it anytime with /settings."
• Options (base labels — the recommended one also gets (Recommended)):
  • Jam / prototype / first game — Short docs, coarse stories, tests optional — the screenshot of what you built is not. ~4 steps to your first line of code instead of ~18. Shipping beats recording; design lives in your head. The trade: no GDDs, so design problems surface in code rather than before it.
  • Several systems that affect each other — Balanced docs, normal story size, standard QA evidence. Expect ~8 design documents and roughly an hour of design work before your first line of code. Worth paying when systems interact and a design mistake is expensive to unpick once it is in code. Intending to finish is not the test — most small games ship faster on the jam path and can move up later with /settings.
  • Big systems-heavy or team project — Thorough docs, fine-grained stories, evidence required everywhere. Many interacting systems (open-world, sim, RPG), a firm release date, or shared ownership.

Value mapping (ignore any (Recommended) suffix on the first option): Jam / prototype / first game → minimal, Several systems that affect each other → standard, Big systems-heavy or team project → full.

Write modes.rigor to project.yaml immediately after the user selects — no separate "May I write?" needed, as the write is a direct consequence of the selection. Use the Edit tool to add it under the modes: block. There is no legacy mirror file for this setting, so this is a single write, not a dual-write. If the Phase 3c project.yaml write was declined, do not write this one either — carry the answer forward and say it was not saved.

Then say: "Set modes.rigor to [choice]. That drives six settings — modes.workflow, docs.density, qa.level, modes.story_granularity, modes.review_mode (director-review depth), and team.size (how many agents are active on team tasks) — a lighter rigor means fewer reviews, a smaller active team, and fewer tokens. Run /settings to see the exact value each one takes, or set any of them explicitly to override just that one."

Why this is asked here. These six knobs each change what skills produce, and before rigor existed /start never asked about any of them — so every project silently ran at defaults the user had never seen. Asking once, at onboarding, is the only point where the answer is cheap; skipping this question puts the project back where it was.

---