widescreen-research: Command for Claude Code

Deterministic Workflow Hooks for Game Commands

Problem Statement

The game workflows (Ulysses Protocol, Feature Implementation Game, etc.) have explicit stage gates but rely on agent inference to determine if criteria are met. This creates non-determinism where we want determinism.

Solution: Enforced Stage Gates via Hooks

Use Claude Code's hook system to programmatically validate gate criteria before allowing workflow progression.

Architecture

Game Workflow State (.game-state/)
  ↓
Pre/Post Tool Hooks
  ↓
Gate Validation Scripts
  ↓
PASS → Allow progression
FAIL → Block + Provide actionable feedback

Hook Configuration

Add to your Claude settings (~/.config/claude-code/settings.json or project-local):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/commands/games/hooks/validate-gate.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/commands/games/hooks/record-action.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/commands/games/hooks/inject-game-state.sh"
          }
        ]
      }
    ]
  }
}

Hook Types

1. Gate Validation Hooks (PreToolUse)

Purpose: Block actions that violate current stage gate requirements

Example: In Ulysses Protocol Phase 2, block implementation tools until planning gate passes

# .claude/commands/games/hooks/validate-gate.sh
#!/bin/bash
# Reads tool call from stdin, checks current game state, blocks if gate not passed

STATE_FILE=".ulysses-protocol/state.json"

if [ ! -f "$STATE_FILE" ]; then
  # No active game, allow
  exit 0
fi

# Read tool call from stdin
TOOL_INPUT=$(cat)
TOOL_NAME=$(echo "$TOOL_INPUT" | jq -r '.toolName')
CURRENT_PHASE=$(jq -r '.phase' "$STATE_FILE")

# Enforce phase gates
case "$CURRENT_PHASE" in
  1) # Reconnaissance phase
     if [[ "$TOOL_NAME" == "Write" ]] || [[ "$TOOL_NAME" == "Edit" ]]; then
       GATE_PASSED=$(jq -r '.gates.reconnaissance.passed' "$STATE_FILE")
       if [ "$GATE_PASSED" != "true" ]; then
         # Block and provide feedback
         cat << EOF
{
  "block": true,
  "message": "🚫 Gate Violation: Cannot proceed to implementation. Reconnaissance gate not passed.\n\nMissing requirements:\n$(jq -r '.gates.reconnaissance.missing[]' "$STATE_FILE")\n\nRun: /ulysses-gate-check to see status"
}
EOF
         exit 1
       fi
     fi
     ;;
esac

exit 0  # Allow