git:20260621.096f040 to git:20260621.08704b3

---

name: start

description: "First-time onboarding — asks where you are, then guides you to the right workflow or to pre-workflow exploration. No assumptions."

argument-hint: "[no arguments]"

user-invocable: true

allowed-tools: Read, Glob, Grep, Write, question

---

# Guided Onboarding

This skill writes up to two files:

- `production/stage.txt` — set to `exploration` when user picks Path E (pre-workflow exploration).

- `production/review-mode.txt` — review mode config (set in Phase 3b, skipped for Path E).

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.

---

## 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 `.opencode/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 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 `question` 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.

- `E) Multiple ideas` — I have 2-4 rough game ideas and want to prototype them quickly before committing to a specific workflow.

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

4. Show the recommended path:

**Concept phase:**

- `/setup-engine` — configure the engine (brainstorm will recommend one)

- `/art-bible` — define visual identity (uses the Visual Identity Anchor brainstorm produces)

- `/map-systems` — decompose the concept into systems

- `/design-system` — author a GDD for each MVP system

- `/review-all-gdds` — cross-system consistency check

- `/gate-check` — validate readiness before architecture work

**Architecture phase:**

- `/create-architecture` — produce the master architecture blueprint and Required ADR list

- `/architecture-decision (×N)` — record key technical decisions, following the Required ADR list

- `/create-control-manifest` — compile decisions into an actionable rules sheet

- `/architecture-review` — validate architecture coverage

**Pre-Production phase:**

- `/ux-design` — author UX specs for key screens (main menu, HUD, core interactions)

- `/prototype` — build a throwaway prototype to validate the core mechanic

- `/playtest-report (×1+)` — document each vertical slice playtest session

- `/create-epics` — map systems to epics

- `/create-stories` — break epics into implementable stories

- `/sprint-plan` — plan the first sprint

**Production phase:** → pick up stories with `/dev-story`

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

4. Show the recommended path:

**Concept phase:**

- `/setup-engine` — configure the engine

- `/art-bible` — define visual identity (uses the Visual Identity Anchor brainstorm produces)

- `/map-systems` — decompose the concept into systems

- `/design-system` — author a GDD for each MVP system

- `/review-all-gdds` — cross-system consistency check

- `/gate-check` — validate readiness before architecture work

**Architecture phase:**

- `/create-architecture` — produce the master architecture blueprint and Required ADR list

- `/architecture-decision (×N)` — record key technical decisions, following the Required ADR list

- `/create-control-manifest` — compile decisions into an actionable rules sheet

- `/architecture-review` — validate architecture coverage

**Pre-Production phase:**

- `/ux-design` — author UX specs for key screens (main menu, HUD, core interactions)

- `/prototype` — build a throwaway prototype to validate the core mechanic

- `/playtest-report (×1+)` — document each vertical slice playtest session

- `/create-epics` — map systems to epics

- `/create-stories` — break epics into implementable stories

- `/sprint-plan` — plan the first sprint

**Production phase:** → pick up stories with `/dev-story`

#### If C: Clear concept

1. Ask them to describe their concept in one sentence — genre and core mechanic. Use plain text, not question (it's an open response).

2. Acknowledge the concept, then use `question` to offer two paths:

- **Prompt**: "How would you like to proceed?"

- **Options**:

- `Jump straight in` — Go to `/setup-engine` now and write the GDD manually afterward

3. Show the recommended path:

**Concept phase:**

- `/art-bible` — define visual identity (after brainstorm if run, or after concept doc exists)

- `/design-review` — validate the concept doc

- `/map-systems` — decompose the concept into individual systems

- `/design-system` — author a GDD for each MVP system

- `/review-all-gdds` — cross-system consistency check

- `/gate-check` — validate readiness before architecture work

**Architecture phase:**

- `/create-architecture` — produce the master architecture blueprint and Required ADR list

- `/architecture-decision (×N)` — record key technical decisions, following the Required ADR list

- `/create-control-manifest` — compile decisions into an actionable rules sheet

- `/architecture-review` — validate architecture coverage

**Pre-Production phase:**

- `/ux-design` — author UX specs for key screens (main menu, HUD, core interactions)

- `/prototype` — build a throwaway prototype to validate the core mechanic

- `/playtest-report (×1+)` — document each vertical slice playtest session

- `/create-epics` — map systems to epics

- `/create-stories` — break epics into implementable stories

- `/sprint-plan` — plan the first sprint

**Production phase:** → pick up stories with `/dev-story`

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

#### If E: Multiple ideas to explore

The user wants to explore several rough ideas before committing to a workflow.

1. Acknowledge that prototyping before committing is a good approach

2. Briefly explain what `/explore` does (pre-workflow rapid prototyping — build throwaway prototypes in `prototypes/explore/`, produces lightweight `REPORT.md` per idea, no workflow commitment, 1-2 days per idea)

3. Recommend running `/explore [idea-name]` for their first idea, then more for subsequent ideas

4. Show the recommended path:

**Pre-workflow exploration:**

- `/explore idea-a` — build a prototype for the first idea (1-2 days)

- `/explore idea-b` — build a prototype for the second idea (1-2 days)

- `/explore idea-c` — (optional) build a prototype for the third idea

- Review reports in `prototypes/explore/*/REPORT.md`

- `/gate-check workflow-selection` — compare results and choose Hybrid or Full OCGS

5. **Do NOT** ask about engine preferences, review modes, or any workflow-specific setup. The user is in pre-workflow exploration.

6. Write `production/stage.txt` with value `exploration` so that `/help` and other skills know the project is in the exploration phase. Create the `production/` directory if it does not exist.

This is the only file Path E writes. No `production/review-mode.txt` is created.

---

## Phase 3b: Set Review Mode

**If the user chose Path E (exploration)**: Skip this phase entirely. No review mode is needed for pre-workflow exploration. Proceed directly to Phase 4.

**For all other paths**: Check if `production/review-mode.txt` already exists.

**If it exists**: Read it and show the current mode — "Review mode is set to `[current]`." — then proceed to Phase 4. Do not ask again.

**If it does not exist**: Use `question`:

- **Prompt**: "One setup choice: how much design review would you want as you work through the workflow?"

- **Options**:

- `Full` — Director specialists review at each key workflow step. Best for teams, learning the workflow, or when you want thorough feedback on every decision.

- `Lean (recommended)` — Directors only at phase gate transitions (/gate-check). Skips per-skill reviews. Balanced approach for solo devs and small teams.

- `Solo` — No director reviews at all. Maximum speed. Best for game jams, prototypes, or if the reviews feel like overhead.

Write the choice to `production/review-mode.txt` immediately after the user

selects — no separate "May I write?" needed, as the write is a direct

consequence of the selection:

- `Full` → write `full`

- `Lean (recommended)` → write `lean`

- `Solo` → write `solo`

Create the `production/` directory if it does not exist.

---

## Phase 4: Confirm Before Proceeding

After presenting the recommended path, use `question` to ask the user which step they'd like to take first. Never auto-run the next skill.

- **Prompt**: "Would you like to start with [recommended first step]?"

- **Options**:

- `Yes, let's start with [recommended first step]`

- `I'd like to do something else first`

---

## Phase 5: Hand Off

When the user confirms their next step, respond with a single short line: "Type `[skill command]` to begin." Nothing else. Do not re-explain the skill or add encouragement. The `/start` skill's job is done.

Verdict: **COMPLETE** — user oriented and handed off to next step.

---

## 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)?"

- **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`. Review mode: `[read from production/review-mode.txt, or 'lean (default)' if missing]`. Want to pick up where you left off? Try `/sprint-plan` or just tell me what you'd like to work on."

- **User is returning with exploration stage** (`production/stage.txt` reads `exploration`): Skip full onboarding — "It looks like you're exploring game ideas! You have [N] explore prototypes in `prototypes/explore/`. Want to run `/explore [another-idea]`, or are you ready to run `/gate-check workflow-selection` to choose a workflow?"

- **User picks E but has existing project artifacts**: Detect if `production/stage.txt` already has a non-exploration value. If so, warn: "It looks like you already have a project in the [phase] phase. Did you mean to continue that work (Path D) instead?"

- **User doesn't fit any option**: Let them describe their situation in their own words and adapt.

---

## Collaborative Protocol

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