Add /start onboarding skill and fresh-project detection

New users no longer get pushed toward /setup-engine before they even
have a game idea. The /start skill asks where they are (no idea, vague
idea, clear concept, existing work) and routes to the right workflow.
The detect-gaps hook now detects fresh projects and suggests /start.
All docs updated: README, quick-start, workflow guide, skills/hooks
references, CLAUDE.md (skill count 34→35).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
2026-02-14 08:53:37 +11:00
parent ad540fe75d
commit 4425d473ea
8 changed files with 267 additions and 38 deletions

View File

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

View File

@@ -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
**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:
### Path A: "I have no idea what to build"
Start from zero — the system will guide you through the entire process:
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/

View File

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

View File

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

View File

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

View File

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

View File

@@ -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
```
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.
### First Steps for a New Game
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 |

View File

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