Turn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Shell ai-agentsai-assisted-developmentanthropicclaudeclaude-codegame-designgame-developmentgamedevgodotindie-game-devunityunreal-engine
Add /start onboarding skill and fresh-project detection
Donchitos4425d473ead9
diff --git a/.claude/docs/hooks-reference.md b/.claude/docs/hooks-reference.mdindex 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.mdindex 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 engine2. **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 answers2. 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 settingsagents/ -- 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.jsonrules/ -- 11 path-specific rule filesdocs/diff --git a/.claude/docs/skills-reference.md b/.claude/docs/skills-reference.mdindex 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.shindex ab633b97..c031f40f 100644--- a/.claude/hooks/detect-gaps.sh+++ b/.claude/hooks/detect-gaps.sh@@ -9,6 +9,40 @@ set +eecho "=== 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.mdnew file mode 100644index 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 adjustdiff --git a/CLAUDE.md b/CLAUDE.mdindex 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.mddiff --git a/README.md b/README.mdindex 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, youcd 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:```bashclaude```-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 rulesagents/ # 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 standardsdocs/@@ -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.mdindex 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-gamecd 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 EngineRun `/setup-engine` in Claude Code. This is the single most importantconfiguration step -- it tells every agent what engine, language, and toolchain@@ -145,9 +157,12 @@ production/ # Sprint plans, milestones, releasesYou 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 ideation2. Pick the best concept from the brainstorm output3. Create a game concept doc (templates/game-concept.md)4. Define game pillars (templates/game-pillars.md)