Claude-Code-Game-Studios/.claude/skills/start/SKILL.md

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

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.

---

## 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:
- **Engine configured?** Read `.claude/docs/technical-preferences.md`. If the
  Engine field contains `[TO BE CONFIGURED]`, the engine is not set.
- **Game concept exists?** Check for `design/gdd/game-concept.md`.
- **Source code exists?** Glob for source files in `src/` (`*.gd`, `*.cs`,
  `*.cpp`, `*.h`, `*.rs`, `*.py`, `*.js`, `*.ts`).
- **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 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?
>
> **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.

1. Acknowledge that starting from zero is completely fine
2. Briefly explain what `/brainstorm` does (guided ideation using professional
   frameworks — MDA, player psychology, verb-first design)
3. Recommend running `/brainstorm open` as the next step
4. Show the recommended path:
   - `/brainstorm` — discover your game concept
   - `/setup-engine` — configure the engine (brainstorm will recommend one)
   - `/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.

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. Show the recommended path:
   - `/brainstorm [hint]` — develop the idea into a full concept
   - `/setup-engine` — configure the engine
   - `/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.

1. 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)
2. 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 engine setup**: If they're confident in their concept, go
     straight to `/setup-engine` and write the GDD manually afterward
3. Show the recommended path (adapted to their choice):
   - `/brainstorm` or `/setup-engine` (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. Two questions matter: what phase are they in,
and are their existing artifacts in a format the template's skills can use.

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

2. **Distinguish two sub-cases based on what exists:**

   **Sub-case D1 — Artifacts exist but engine is not configured / very early stage**
   (game concept exists but no GDDs or ADRs):
   - This is close to a greenfield project. Route normally:
   - Recommend `/setup-engine` first if engine not configured
   - Then `/project-stage-detect` for a gap inventory
   - Then pick up the normal pipeline from the detected phase

   **Sub-case D2 — GDDs, ADRs, or stories already exist** (non-trivial existing work):
   - The project needs a format compliance check, not just an existence check.
   - Explain the distinction clearly:
     > "Having files isn't the same as the template's skills being able to use them.
     > GDDs might be missing required sections. ADRs might lack Status fields that
     > story validation depends on. `/adopt` checks this specifically."
   - Recommend this two-step path:
     1. `/project-stage-detect` — understand what phase and what's missing entirely
     2. `/adopt` — audit whether existing artifacts are in the right internal format,
        and get a numbered migration plan to bring them up to standard
   - Note: `/adopt` is what produces the actionable "what to fix" plan. After that,
     existing skills handle each fix: `/design-system retrofit`, `/architecture-decision retrofit`, etc.

3. Show the recommended path for D2:
   - `/project-stage-detect` — phase detection + existence gaps
   - `/adopt` — **format compliance audit + migration plan** (the key brownfield tool)
   - `/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

---

### 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 (engine configured, concept exists)**: Skip onboarding
  entirely — "It looks like you're already set up! Your engine is [X] and you
  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:

1. **Ask first** — never assume the user's state or intent
2. **Present options** — give clear paths, not mandates
3. **User decides** — they pick the direction
4. **No auto-execution** — recommend the next skill, don't run it without asking
5. **Adapt** — if the user's situation doesn't fit a template, listen and adjust