diff --git a/.claude/docs/hooks-reference.md b/.claude/docs/hooks-reference.md index 6bd57ee..46913a6 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 6a3f2f4..b3f4559 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 +**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/ diff --git a/.claude/docs/skills-reference.md b/.claude/docs/skills-reference.md index eabe470..19f1aff 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 ab633b9..c031f40 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 0000000..316d498 --- /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 64cc5da..b6058ee 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 138b5e4..96526a4 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 - ``` +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 | diff --git a/docs/WORKFLOW-GUIDE.md b/docs/WORKFLOW-GUIDE.md index 875ad65..48f1d93 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 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)