Skip to content

Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.

Add /start onboarding skill and fresh-project detection

Donchitos4425d473ead9
diff --git a/.claude/docs/hooks-reference.md b/.claude/docs/hooks-reference.md
index 6bd57ee3..46913a6c 100644
--- a/.claude/docs/hooks-reference.md
+++ b/.claude/docs/hooks-reference.md
@@ -8,7 +8,7 @@ Hooks are configured in `.claude/settings.json` and fire automatically:
| `validate-push.sh` | PreToolUse (Bash) | `git push` commands | Warns on pushes to protected branches (develop/main) |
| `validate-assets.sh` | PostToolUse (Write/Edit) | Asset file changes | Checks naming conventions and JSON validity for files in `assets/` |
| `session-start.sh` | SessionStart | Session begins | Loads current sprint context, active milestone, recent git activity |
-| `detect-gaps.sh` | SessionStart | Session begins | Detects missing documentation when code/prototypes exist, suggests /reverse-document or /project-stage-detect |
+| `detect-gaps.sh` | SessionStart | Session begins | Detects fresh projects (suggests /start) and missing documentation when code/prototypes exist, suggests /reverse-document or /project-stage-detect |
| `pre-compact.sh` | PreCompact | Context compression | Logs session progress notes before context window compression |
| `session-stop.sh` | Stop | Session ends | Summarizes accomplishments and updates session log |
| `log-agent.sh` | SubagentStart | Agent spawned | Audit trail of all subagent invocations with timestamps |
diff --git a/.claude/docs/quick-start.md b/.claude/docs/quick-start.md
index 6a3f2f4d..b3f4559c 100644
--- a/.claude/docs/quick-start.md
+++ b/.claude/docs/quick-start.md
@@ -75,6 +75,7 @@ Ask yourself: "What department would handle this in a real studio?"
| Command | What it does |
|---------|-------------|
+| `/start` | First-time onboarding — asks where you are, guides you to the right workflow |
| `/design-review` | Reviews a design document |
| `/code-review` | Reviews code for quality and architecture |
| `/playtest-report` | Creates or analyzes playtest feedback |
@@ -145,12 +146,15 @@ Templates are in `.claude/docs/templates/`:
## First Steps for a New Project
-### Path A: "I have no idea what to build"
+**Don't know where to begin?** Run `/start`. It asks where you are and routes
+you to the right workflow. No assumptions about your game, engine, or experience level.
+
+If you already know what you need, jump directly to the relevant path:
-Start from zero — the system will guide you through the entire process:
+### Path A: "I have no idea what to build"
-1. **Discover your game** — Run `/brainstorm` (or `/brainstorm open`)
- - Guided creative exploration: what excites you, what you've played, your constraints
+1. **Run `/start`** (or `/brainstorm open`) — guided creative exploration:
+ what excites you, what you've played, your constraints
- Generates 3 concepts, helps you pick one, defines core loop and pillars
- Produces a game concept document and recommends an engine
2. **Set up the engine** — Run `/setup-engine` (uses the brainstorm recommendation)
@@ -186,6 +190,16 @@ If you have a concept but don't know which engine fits:
an engine based on your answers
2. Follow Path B from step 2 onward
+### Path D: "I have an existing project"
+
+If you have design docs, prototypes, or code already:
+
+1. **Run `/start`** (or `/project-stage-detect`) — analyzes what exists,
+ identifies gaps, and recommends next steps
+2. **Configure engine if needed** — Run `/setup-engine` if not yet configured
+3. **Validate phase readiness** — Run `/gate-check` to see where you stand
+4. **Plan the next sprint** — Run `/sprint-plan new`
+
## File Structure Reference
```
@@ -193,7 +207,7 @@ CLAUDE.md -- Master config (read this first, ~60 lines)
.claude/
settings.json -- Claude Code hooks and project settings
agents/ -- 48 agent definitions (YAML frontmatter)
- skills/ -- 34 slash command definitions (YAML frontmatter)
+ skills/ -- 35 slash command definitions (YAML frontmatter)
hooks/ -- 8 hook scripts (.sh) wired by settings.json
rules/ -- 11 path-specific rule files
docs/
diff --git a/.claude/docs/skills-reference.md b/.claude/docs/skills-reference.md
index eabe4704..19f1affc 100644
--- a/.claude/docs/skills-reference.md
+++ b/.claude/docs/skills-reference.md
@@ -2,6 +2,7 @@
| Command | Purpose |
|---------|---------|
+| `/start` | First-time onboarding — asks where you are, then guides you to the right workflow |
| `/design-review` | Review a game design document for completeness and consistency |
| `/code-review` | Architectural code review for a file or changeset |
| `/playtest-report` | Generate a structured playtest report template |
diff --git a/.claude/hooks/detect-gaps.sh b/.claude/hooks/detect-gaps.sh
index ab633b97..c031f40f 100644
--- a/.claude/hooks/detect-gaps.sh
+++ b/.claude/hooks/detect-gaps.sh
@@ -9,6 +9,40 @@ set +e
echo "=== Checking for Documentation Gaps ==="
+# --- Check 0: Fresh project detection (suggests /start) ---
+FRESH_PROJECT=true
+
+# Check if engine is configured
+if [ -f ".claude/docs/technical-preferences.md" ]; then
+ ENGINE_LINE=$(grep -E "^\- \*\*Engine\*\*:" .claude/docs/technical-preferences.md 2>/dev/null)
+ if echo "$ENGINE_LINE" | grep -qv "TO BE CONFIGURED" 2>/dev/null; then
+ FRESH_PROJECT=false
+ fi
+fi
+
+# Check if game concept exists
+if [ -f "design/gdd/game-concept.md" ]; then
+ FRESH_PROJECT=false
+fi
+
+# Check if source code exists
+if [ -d "src" ]; then
+ SRC_CHECK=$(find src -type f \( -name "*.gd" -o -name "*.cs" -o -name "*.cpp" -o -name "*.c" -o -name "*.h" -o -name "*.hpp" -o -name "*.rs" -o -name "*.py" -o -name "*.js" -o -name "*.ts" \) 2>/dev/null | head -1)
+ if [ -n "$SRC_CHECK" ]; then
+ FRESH_PROJECT=false
+ fi
+fi
+
+if [ "$FRESH_PROJECT" = true ]; then
+ echo ""
+ echo "🚀 NEW PROJECT: No engine configured, no game concept, no source code."
+ echo " This looks like a fresh start! Run: /start"
+ echo ""
+ echo "💡 To get a comprehensive project analysis, run: /project-stage-detect"
+ echo "==================================="
+ exit 0
+fi
+
# --- Check 1: Substantial codebase but sparse design docs ---
if [ -d "src" ]; then
# Count source files (cross-platform, handles Windows paths)
diff --git a/.claude/skills/start/SKILL.md b/.claude/skills/start/SKILL.md
new file mode 100644
index 00000000..316d4980
--- /dev/null
+++ b/.claude/skills/start/SKILL.md
@@ -0,0 +1,175 @@
+---
+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
+---
+
+# 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)
+ - `/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
+ - `/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
+ - `/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.
+
+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. Recommend running `/project-stage-detect` for a full analysis
+3. If the engine isn't configured, note that `/setup-engine` should come first
+4. Show the recommended path:
+ - `/project-stage-detect` — full gap analysis
+ - `/setup-engine` — if not configured
+ - `/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 (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
diff --git a/CLAUDE.md b/CLAUDE.md
index 64cc5daf..b6058eed 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -46,6 +46,9 @@ Every task follows: **Question -> Options -> Decision -> Draft -> Approval**
See `docs/COLLABORATIVE-DESIGN-PRINCIPLE.md` for full protocol and examples.
+> **First session?** If the project has no engine configured and no game concept,
+> run `/start` to begin the guided onboarding flow.
+
## Coding Standards & Review
@.claude/docs/coding-standards.md
diff --git a/README.md b/README.md
index 138b5e4e..96526a46 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# Claude Code Game Studios
-A production-ready [Claude Code](https://docs.anthropic.com/en/docs/claude-code) project template that turns a single AI session into a full game development studio. 48 specialized agents, 34 workflow skills, and a complete coordination system — all wired into Claude Code's native agent architecture.
+A production-ready [Claude Code](https://docs.anthropic.com/en/docs/claude-code) project template that turns a single AI session into a full game development studio. 48 specialized agents, 35 workflow skills, and a complete coordination system — all wired into Claude Code's native agent architecture.
Clone the repo, open Claude Code, and start building your game with a team of AI specialists that mirrors a real studio hierarchy: directors, department leads, and domain experts working together with defined roles, delegation rules, and quality gates.
@@ -9,7 +9,7 @@ Clone the repo, open Claude Code, and start building your game with a team of AI
| Category | Count | Description |
|----------|-------|-------------|
| **Agents** | 48 | Specialized subagents across design, programming, art, audio, narrative, QA, and production |
-| **Skills** | 34 | Slash commands for common workflows (`/sprint-plan`, `/code-review`, `/brainstorm`, etc.) |
+| **Skills** | 35 | Slash commands for common workflows (`/start`, `/sprint-plan`, `/code-review`, `/brainstorm`, etc.) |
| **Hooks** | 8 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit, and gap detection |
| **Rules** | 11 | Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, and more |
| **Templates** | 28 | Document templates for GDDs, ADRs, sprint plans, economy models, faction design, and more |
@@ -50,7 +50,7 @@ The template includes agent sets for all three major engines. Use the set that m
## Slash Commands
-Type `/` in Claude Code to access all 34 skills:
+Type `/` in Claude Code to access all 35 skills:
**Reviews & Analysis**
`/design-review` `/code-review` `/balance-check` `/asset-audit` `/scope-check` `/perf-profile` `/tech-debt`
@@ -59,7 +59,7 @@ Type `/` in Claude Code to access all 34 skills:
`/sprint-plan` `/milestone-review` `/estimate` `/retrospective` `/bug-report`
**Project Management**
-`/project-stage-detect` `/reverse-document` `/gate-check`
+`/start` `/project-stage-detect` `/reverse-document` `/gate-check`
**Release**
`/release-checklist` `/launch-checklist` `/changelog` `/patch-notes` `/hotfix`
@@ -88,33 +88,18 @@ All hooks fail gracefully if optional tools are missing — nothing breaks, you
cd my-game
```
-2. **Configure your engine** — run `/setup-engine` in Claude Code (or manually edit `CLAUDE.md`):
-
- ```bash
- /setup-engine godot 4.6
- ```
-
- This pins the engine, populates reference docs, and creates your technical preferences file.
-
-3. **Open Claude Code** and start working:
+2. **Open Claude Code** and start a session:
```bash
claude
```
-4. **Try a slash command** to see the system in action:
- ```
- /brainstorm roguelike
- ```
-
-### First Steps for a New Game
+3. **Run `/start`** — the system asks where you are (no idea, vague concept,
+ clear design, existing work) and guides you to the right workflow. No assumptions.
-1. Run `/setup-engine` to configure your engine and technical preferences
-2. Run `/brainstorm` to develop your game concept
-3. Create game pillars with the `creative-director` agent
-4. Record your architecture decisions with `/architecture-decision`
-5. Plan your first sprint with `/sprint-plan new`
-6. Prototype the core loop with `/prototype`
-7. Start building
+ Or jump directly to a specific skill if you already know what you need:
+ - `/brainstorm` — explore game ideas from scratch
+ - `/setup-engine godot 4.6` — configure your engine if you already know
+ - `/project-stage-detect` — analyze an existing project
## Project Structure
@@ -123,7 +108,7 @@ CLAUDE.md # Master configuration
.claude/
settings.json # Hooks, permissions, safety rules
agents/ # 48 agent definitions (markdown + YAML frontmatter)
- skills/ # 34 slash commands (subdirectory per skill)
+ skills/ # 35 slash commands (subdirectory per skill)
hooks/ # 8 hook scripts (bash, cross-platform)
rules/ # 11 path-scoped coding standards
docs/
@@ -164,7 +149,7 @@ Agents follow a structured delegation model:
| `validate-push.sh` | `git push` | Warns on pushes to protected branches |
| `validate-assets.sh` | File writes in `assets/` | Validates naming conventions and JSON structure |
| `session-start.sh` | Session open | Loads sprint context and recent git activity |
-| `detect-gaps.sh` | Session open | Detects missing documentation when code/prototypes exist, suggests `/reverse-document` or `/project-stage-detect` |
+| `detect-gaps.sh` | Session open | Detects fresh projects (suggests `/start`) and missing documentation when code/prototypes exist |
| `pre-compact.sh` | Context compression | Preserves session progress notes |
| `session-stop.sh` | Session close | Logs accomplishments |
| `log-agent.sh` | Agent spawned | Audit trail of all subagent invocations |
diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md
index 875ad650..48f1d93e 100644
--- a/docs/WORKFLOW-GUIDE.md
+++ b/docs/WORKFLOW-GUIDE.md
@@ -3,7 +3,7 @@
> **How to go from zero to a shipped game using the Agent Architecture.**
>
> This guide walks you through every phase of game development using the
-> 48-agent system, 34 slash commands, and automated hooks. It assumes you
+> 48-agent system, 35 slash commands, and automated hooks. It assumes you
> have Claude Code installed and are working from the project root.
---
@@ -47,7 +47,19 @@ git clone <repo-url> my-game
cd my-game
```
-### Step 0.2: Choose Your Engine
+### Step 0.2: Run /start (Recommended for New Users)
+
+If you're new to the project or don't yet know what game you're building:
+
+```
+/start
+```
+
+This guided onboarding asks where you are (no idea, vague idea, clear concept,
+existing work) and routes you to the right phase. Skip this if you already have
+a game concept and engine decision.
+
+### Step 0.3: Choose Your Engine
Run `/setup-engine` in Claude Code. This is the single most important
configuration step -- it tells every agent what engine, language, and toolchain
@@ -145,9 +157,12 @@ production/ # Sprint plans, milestones, releases
You go from "no idea" or "vague idea" to a structured game concept document.
This is where you figure out **what** you're making.
+> **Tip:** If you ran `/start` in Phase 0 and chose Path A or B, you're already
+> here. `/start` routes you to `/brainstorm` automatically.
+
### Step 1.1: Brainstorm With `/brainstorm`
-This is your starting point. Run the brainstorm skill:
+This is your starting point if you skipped `/start`. Run the brainstorm skill:
```
/brainstorm
@@ -1673,6 +1688,7 @@ conflicts go to `producer`.
| Stage | Commands |
|-------|----------|
+| **Onboarding** | `/start` |
| **Ideation** | `/brainstorm` |
| **Design** | `/design-review`, `/architecture-decision` |
| **Sprint** | `/sprint-plan`, `/estimate`, `/scope-check`, `/retrospective` |
@@ -1690,7 +1706,8 @@ conflicts go to `producer`.
### Workflow 1: "I just started and have no game idea"
```
-1. /brainstorm
+1. /start (asks where you are, routes you to the right workflow)
+ — or /brainstorm if you prefer to jump straight to ideation
2. Pick the best concept from the brainstorm output
3. Create a game concept doc (templates/game-concept.md)
4. Define game pillars (templates/game-pillars.md)