Game Studio Agent Architecture — complete setup (Phases 1-7)

48 coordinated Claude Code subagents for indie game development:
- 3 leadership agents (creative-director, technical-director, producer)
- 10 department leads (game-designer, lead-programmer, art-director, etc.)
- 23 specialist agents (gameplay, engine, AI, networking, UI, tools, etc.)
- 12 engine-specific agents (Godot, Unity, Unreal with sub-specialists)

Infrastructure:
- 34 skills (slash commands) for workflows, reviews, and team orchestration
- 8 hooks for commit validation, asset checks, session management
- 11 path-scoped rules enforcing domain-specific standards
- 28 templates for design docs, reports, and collaborative protocols

Key features:
- User-driven collaboration protocol (Question → Options → Decision → Draft → Approval)
- Engine version awareness with knowledge-gap detection (Godot 4.6 pinned)
- Phase gate system for development milestone validation
- CLAUDE.md kept under 80 lines with extracted doc imports

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Donchitos
2026-02-13 21:04:24 +11:00
commit ad540fe75d
211 changed files with 32726 additions and 0 deletions

View File

@@ -0,0 +1,119 @@
#!/bin/bash
# Hook: detect-gaps.sh
# Event: SessionStart
# Purpose: Detect missing documentation when code/prototypes exist
# Cross-platform: Windows Git Bash compatible (uses grep -E, not -P)
# Exit on error for debugging (but don't fail the session)
set +e
echo "=== Checking for Documentation Gaps ==="
# --- Check 1: Substantial codebase but sparse design docs ---
if [ -d "src" ]; then
# Count source files (cross-platform, handles Windows paths)
SRC_FILES=$(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 | wc -l)
else
SRC_FILES=0
fi
if [ -d "design/gdd" ]; then
DESIGN_FILES=$(find design/gdd -type f -name "*.md" 2>/dev/null | wc -l)
else
DESIGN_FILES=0
fi
# Normalize whitespace from wc output
SRC_FILES=$(echo "$SRC_FILES" | tr -d ' ')
DESIGN_FILES=$(echo "$DESIGN_FILES" | tr -d ' ')
if [ "$SRC_FILES" -gt 50 ] && [ "$DESIGN_FILES" -lt 5 ]; then
echo "⚠️ GAP: Substantial codebase ($SRC_FILES source files) but sparse design docs ($DESIGN_FILES files)"
echo " Suggested action: /reverse-document design src/[system]"
echo " Or run: /project-stage-detect to get full analysis"
fi
# --- Check 2: Prototypes without documentation ---
if [ -d "prototypes" ]; then
PROTOTYPE_DIRS=$(find prototypes -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
UNDOCUMENTED_PROTOS=()
if [ -n "$PROTOTYPE_DIRS" ]; then
while IFS= read -r proto_dir; do
# Normalize path separators for Windows
proto_dir=$(echo "$proto_dir" | sed 's|\\|/|g')
# Check for README.md or CONCEPT.md
if [ ! -f "${proto_dir}/README.md" ] && [ ! -f "${proto_dir}/CONCEPT.md" ]; then
proto_name=$(basename "$proto_dir")
UNDOCUMENTED_PROTOS+=("$proto_name")
fi
done <<< "$PROTOTYPE_DIRS"
if [ ${#UNDOCUMENTED_PROTOS[@]} -gt 0 ]; then
echo "⚠️ GAP: ${#UNDOCUMENTED_PROTOS[@]} undocumented prototype(s) found:"
for proto in "${UNDOCUMENTED_PROTOS[@]}"; do
echo " - prototypes/$proto/ (no README or CONCEPT doc)"
done
echo " Suggested action: /reverse-document concept prototypes/[name]"
fi
fi
fi
# --- Check 3: Core systems without architecture docs ---
if [ -d "src/core" ] || [ -d "src/engine" ]; then
if [ ! -d "docs/architecture" ]; then
echo "⚠️ GAP: Core engine/systems exist but no docs/architecture/ directory"
echo " Suggested action: Create docs/architecture/ and run /architecture-decision"
else
ADR_COUNT=$(find docs/architecture -type f -name "*.md" 2>/dev/null | wc -l)
ADR_COUNT=$(echo "$ADR_COUNT" | tr -d ' ')
if [ "$ADR_COUNT" -lt 3 ]; then
echo "⚠️ GAP: Core systems exist but only $ADR_COUNT ADR(s) documented"
echo " Suggested action: /reverse-document architecture src/core/[system]"
fi
fi
fi
# --- Check 4: Gameplay systems without design docs ---
if [ -d "src/gameplay" ]; then
# Find major gameplay subdirectories (those with 5+ files)
GAMEPLAY_SYSTEMS=$(find src/gameplay -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
if [ -n "$GAMEPLAY_SYSTEMS" ]; then
while IFS= read -r system_dir; do
system_dir=$(echo "$system_dir" | sed 's|\\|/|g')
system_name=$(basename "$system_dir")
file_count=$(find "$system_dir" -type f 2>/dev/null | wc -l)
file_count=$(echo "$file_count" | tr -d ' ')
# If system has 5+ files, check for corresponding design doc
if [ "$file_count" -ge 5 ]; then
# Check for design doc (allow variations: combat-system.md, combat.md)
design_doc_1="design/gdd/${system_name}-system.md"
design_doc_2="design/gdd/${system_name}.md"
if [ ! -f "$design_doc_1" ] && [ ! -f "$design_doc_2" ]; then
echo "⚠️ GAP: Gameplay system 'src/gameplay/$system_name/' ($file_count files) has no design doc"
echo " Expected: design/gdd/${system_name}-system.md or design/gdd/${system_name}.md"
echo " Suggested action: /reverse-document design src/gameplay/$system_name"
fi
fi
done <<< "$GAMEPLAY_SYSTEMS"
fi
fi
# --- Check 5: Production planning ---
if [ "$SRC_FILES" -gt 100 ]; then
# For projects with substantial code, check for production planning
if [ ! -d "production/sprints" ] && [ ! -d "production/milestones" ]; then
echo "⚠️ GAP: Large codebase ($SRC_FILES files) but no production planning found"
echo " Suggested action: /sprint-plan or create production/ directory"
fi
fi
# --- Summary ---
echo ""
echo "💡 To get a comprehensive project analysis, run: /project-stage-detect"
echo "==================================="

View File

@@ -0,0 +1,25 @@
#!/bin/bash
# Claude Code SubagentStart hook: Log agent invocations for audit trail
# Tracks which agents are being used and when
#
# Input schema (SubagentStart):
# { "agent_name": "game-designer", "model": "sonnet", ... }
INPUT=$(cat)
# Parse agent name -- use jq if available, fall back to grep
if command -v jq >/dev/null 2>&1; then
AGENT_NAME=$(echo "$INPUT" | jq -r '.agent_name // "unknown"' 2>/dev/null)
else
AGENT_NAME=$(echo "$INPUT" | grep -oE '"agent_name"\s*:\s*"[^"]*"' | sed 's/"agent_name"\s*:\s*"//;s/"$//')
[ -z "$AGENT_NAME" ] && AGENT_NAME="unknown"
fi
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
SESSION_LOG_DIR="production/session-logs"
mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
echo "$TIMESTAMP | Agent invoked: $AGENT_NAME" >> "$SESSION_LOG_DIR/agent-audit.log" 2>/dev/null
exit 0

View File

@@ -0,0 +1,15 @@
#!/bin/bash
# Claude Code PreCompact hook: Save session state before context compression
# Ensures progress notes survive context window compression
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
SESSION_LOG_DIR="production/session-logs"
# Create session log directory if it doesn't exist
mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
# Save a marker file noting that compaction occurred
echo "Context compaction occurred at $(date). Session state may have been compressed." \
>> "$SESSION_LOG_DIR/compaction-log.txt" 2>/dev/null
exit 0

View File

@@ -0,0 +1,58 @@
#!/bin/bash
# Claude Code SessionStart hook: Load project context at session start
# Outputs context information that Claude sees when a session begins
#
# Input schema (SessionStart): No stdin input
echo "=== Claude Code Game Studios — Session Context ==="
# Current branch
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
if [ -n "$BRANCH" ]; then
echo "Branch: $BRANCH"
# Recent commits
echo ""
echo "Recent commits:"
git log --oneline -5 2>/dev/null | while read -r line; do
echo " $line"
done
fi
# Current sprint (find most recent sprint file)
LATEST_SPRINT=$(ls -t production/sprints/sprint-*.md 2>/dev/null | head -1)
if [ -n "$LATEST_SPRINT" ]; then
echo ""
echo "Active sprint: $(basename "$LATEST_SPRINT" .md)"
fi
# Current milestone
LATEST_MILESTONE=$(ls -t production/milestones/*.md 2>/dev/null | head -1)
if [ -n "$LATEST_MILESTONE" ]; then
echo "Active milestone: $(basename "$LATEST_MILESTONE" .md)"
fi
# Open bug count
BUG_COUNT=0
for dir in tests/playtest production; do
if [ -d "$dir" ]; then
count=$(find "$dir" -name "BUG-*.md" 2>/dev/null | wc -l)
BUG_COUNT=$((BUG_COUNT + count))
fi
done
if [ "$BUG_COUNT" -gt 0 ]; then
echo "Open bugs: $BUG_COUNT"
fi
# Code health quick check
if [ -d "src" ]; then
TODO_COUNT=$(grep -r "TODO" src/ 2>/dev/null | wc -l)
FIXME_COUNT=$(grep -r "FIXME" src/ 2>/dev/null | wc -l)
if [ "$TODO_COUNT" -gt 0 ] || [ "$FIXME_COUNT" -gt 0 ]; then
echo ""
echo "Code health: ${TODO_COUNT} TODOs, ${FIXME_COUNT} FIXMEs in src/"
fi
fi
echo "==================================="
exit 0

View File

@@ -0,0 +1,30 @@
#!/bin/bash
# Claude Code Stop hook: Log session summary when Claude finishes
# Records what was worked on for audit trail and sprint tracking
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
SESSION_LOG_DIR="production/session-logs"
mkdir -p "$SESSION_LOG_DIR" 2>/dev/null
# Log recent git activity from this session
RECENT_COMMITS=$(git log --oneline --since="1 hour ago" 2>/dev/null)
MODIFIED_FILES=$(git diff --name-only 2>/dev/null)
if [ -n "$RECENT_COMMITS" ] || [ -n "$MODIFIED_FILES" ]; then
{
echo "## Session End: $TIMESTAMP"
if [ -n "$RECENT_COMMITS" ]; then
echo "### Commits"
echo "$RECENT_COMMITS"
fi
if [ -n "$MODIFIED_FILES" ]; then
echo "### Uncommitted Changes"
echo "$MODIFIED_FILES"
fi
echo "---"
echo ""
} >> "$SESSION_LOG_DIR/session-log.md" 2>/dev/null
fi
exit 0

View File

@@ -0,0 +1,58 @@
#!/bin/bash
# Claude Code PostToolUse hook: Validates asset files after Write/Edit
# Checks naming conventions for files in assets/ directory
# Exit 0 = success (non-blocking, PostToolUse cannot block)
#
# Input schema (PostToolUse for Write/Edit):
# { "tool_name": "Write", "tool_input": { "file_path": "assets/data/foo.json", "content": "..." } }
INPUT=$(cat)
# Parse file path -- use jq if available, fall back to grep
if command -v jq >/dev/null 2>&1; then
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
else
FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"\s*:\s*"[^"]*"' | sed 's/"file_path"\s*:\s*"//;s/"$//')
fi
# Normalize path separators (Windows backslash to forward slash)
FILE_PATH=$(echo "$FILE_PATH" | sed 's|\\|/|g')
# Only check files in assets/
if ! echo "$FILE_PATH" | grep -qE '(^|/)assets/'; then
exit 0
fi
FILENAME=$(basename "$FILE_PATH")
WARNINGS=""
# Check naming convention (lowercase with underscores only) -- uses grep -E instead of grep -P
if echo "$FILENAME" | grep -qE '[A-Z[:space:]-]'; then
WARNINGS="$WARNINGS\nNAMING: $FILE_PATH must be lowercase with underscores (got: $FILENAME)"
fi
# Check JSON validity for data files
if echo "$FILE_PATH" | grep -qE '(^|/)assets/data/.*\.json$'; then
if [ -f "$FILE_PATH" ]; then
# Find a working Python command
PYTHON_CMD=""
for cmd in python python3 py; do
if command -v "$cmd" >/dev/null 2>&1; then
PYTHON_CMD="$cmd"
break
fi
done
if [ -n "$PYTHON_CMD" ]; then
if ! "$PYTHON_CMD" -m json.tool "$FILE_PATH" > /dev/null 2>&1; then
WARNINGS="$WARNINGS\nFORMAT: $FILE_PATH is not valid JSON"
fi
fi
fi
fi
if [ -n "$WARNINGS" ]; then
echo -e "=== Asset Validation ===$WARNINGS\n========================" >&2
fi
exit 0

View File

@@ -0,0 +1,101 @@
#!/bin/bash
# Claude Code PreToolUse hook: Validates git commit commands
# Receives JSON on stdin with tool_input.command
# Exit 0 = allow, Exit 2 = block (stderr shown to Claude)
#
# Input schema (PreToolUse for Bash):
# { "tool_name": "Bash", "tool_input": { "command": "git commit -m ..." } }
INPUT=$(cat)
# Parse command -- use jq if available, fall back to grep
if command -v jq >/dev/null 2>&1; then
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
else
COMMAND=$(echo "$INPUT" | grep -oE '"command"\s*:\s*"[^"]*"' | sed 's/"command"\s*:\s*"//;s/"$//')
fi
# Only process git commit commands
if ! echo "$COMMAND" | grep -qE '^git[[:space:]]+commit'; then
exit 0
fi
# Get staged files
STAGED=$(git diff --cached --name-only 2>/dev/null)
if [ -z "$STAGED" ]; then
exit 0
fi
WARNINGS=""
# Check design documents for required sections
DESIGN_FILES=$(echo "$STAGED" | grep -E '^design/gdd/')
if [ -n "$DESIGN_FILES" ]; then
for file in $DESIGN_FILES; do
if [[ "$file" == *.md ]] && [ -f "$file" ]; then
for section in "Overview" "Detailed" "Edge Cases" "Dependencies" "Acceptance Criteria"; do
if ! grep -qi "$section" "$file"; then
WARNINGS="$WARNINGS\nDESIGN: $file missing required section: $section"
fi
done
fi
done
fi
# Validate JSON data files -- block invalid JSON
DATA_FILES=$(echo "$STAGED" | grep -E '^assets/data/.*\.json$')
if [ -n "$DATA_FILES" ]; then
# Find a working Python command
PYTHON_CMD=""
for cmd in python python3 py; do
if command -v "$cmd" >/dev/null 2>&1; then
PYTHON_CMD="$cmd"
break
fi
done
for file in $DATA_FILES; do
if [ -f "$file" ]; then
if [ -n "$PYTHON_CMD" ]; then
if ! "$PYTHON_CMD" -m json.tool "$file" > /dev/null 2>&1; then
echo "BLOCKED: $file is not valid JSON" >&2
exit 2
fi
else
echo "WARNING: Cannot validate JSON (python not found): $file" >&2
fi
fi
done
fi
# Check for hardcoded gameplay values in gameplay code
# Uses grep -E (POSIX extended) instead of grep -P (Perl) for cross-platform compatibility
CODE_FILES=$(echo "$STAGED" | grep -E '^src/gameplay/')
if [ -n "$CODE_FILES" ]; then
for file in $CODE_FILES; do
if [ -f "$file" ]; then
if grep -nE '(damage|health|speed|rate|chance|cost|duration)[[:space:]]*[:=][[:space:]]*[0-9]+' "$file" 2>/dev/null; then
WARNINGS="$WARNINGS\nCODE: $file may contain hardcoded gameplay values. Use data files."
fi
fi
done
fi
# Check for TODO/FIXME without assignee -- uses grep -E instead of grep -P
SRC_FILES=$(echo "$STAGED" | grep -E '^src/')
if [ -n "$SRC_FILES" ]; then
for file in $SRC_FILES; do
if [ -f "$file" ]; then
if grep -nE '(TODO|FIXME|HACK)[^(]' "$file" 2>/dev/null; then
WARNINGS="$WARNINGS\nSTYLE: $file has TODO/FIXME without owner tag. Use TODO(name) format."
fi
fi
done
fi
# Print warnings (non-blocking) and allow commit
if [ -n "$WARNINGS" ]; then
echo -e "=== Commit Validation Warnings ===$WARNINGS\n================================" >&2
fi
exit 0

View File

@@ -0,0 +1,47 @@
#!/bin/bash
# Claude Code PreToolUse hook: Validates git push commands
# Warns on pushes to protected branches
# Exit 0 = allow, Exit 2 = block
#
# Input schema (PreToolUse for Bash):
# { "tool_name": "Bash", "tool_input": { "command": "git push origin main" } }
INPUT=$(cat)
# Parse command -- use jq if available, fall back to grep
if command -v jq >/dev/null 2>&1; then
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
else
COMMAND=$(echo "$INPUT" | grep -oE '"command"\s*:\s*"[^"]*"' | sed 's/"command"\s*:\s*"//;s/"$//')
fi
# Only process git push commands
if ! echo "$COMMAND" | grep -qE '^git[[:space:]]+push'; then
exit 0
fi
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
FULL_GATE=false
# Check if pushing to a protected branch
for branch in develop main master; do
if [ "$CURRENT_BRANCH" = "$branch" ]; then
FULL_GATE=true
break
fi
# Also check if pushing to a protected branch explicitly (quote branch name for safety)
if echo "$COMMAND" | grep -qE "[[:space:]]${branch}([[:space:]]|$)"; then
FULL_GATE=true
break
fi
done
if [ "$FULL_GATE" = true ]; then
echo "Push to protected branch '$CURRENT_BRANCH' detected." >&2
echo "Reminder: Ensure build passes, unit tests pass, and no S1/S2 bugs exist." >&2
# Allow the push but warn -- uncomment below to block instead:
# echo "BLOCKED: Run tests before pushing to $CURRENT_BRANCH" >&2
# exit 2
fi
exit 0