Planning Loop

Planning Loop

Generate the infrastructure to run Claude Code in an autonomous game design loop. Each iteration starts a fresh session, assesses the game vision's maturity, does one type of deep creative work (expand mechanics, deepen systems, research competitors, critique design, refine scope, or plan implementation), and exits. Fresh context per iteration avoids context window degradation and brings genuinely fresh game design perspective each time.

The user provides a game concept (a paragraph or two). The loop autonomously develops it into a comprehensive game design document and detailed implementation plan.

Reference Files

| File | Read When | |------|-----------| | references/vision-format.md | Creating or updating VISION.md — contains the template and evolution rules | | references/ideation-strategies.md | During Phase 4 when writing the loop prompt's expansion guidance | | references/systems-validation.md | During Phase 4 when writing the DEEPEN, CRITIQUE, and review agent sections of the loop prompt |

Workflow

Phase 1: Detect Existing State

1. Search for VISION.md in the project root, then docs/, then recursively.
2. Search for IMPLEMENTATION_PLAN.md in the same locations.
3. Search for planning-loop.sh in the project root.

If VISION.md exists:

• Report current state (phase, iterations completed, dimensions explored).
• Ask: continue from where it left off, or start fresh?
• If continuing and planning-loop.sh exists, skip to Phase 5.

If IMPLEMENTATION_PLAN.md exists but no VISION.md:

• Ask what the user wants — the plan may be from a previous single-pass planning session.

If nothing exists: Proceed to Phase 2.

Phase 2: Gather Seed Idea

If the user already provided the idea, use it directly. Otherwise ask:

> Describe your game idea in a paragraph or two. What's the core fantasy? What makes it different? > Don't worry about details — that's what this loop will figure out.

Also gather:

• Project name: Short name for the vision document title.
• Max iterations: How many planning iterations to run.

Default: 30. Suggest 20-30 for moderate ideas, 40-60 for ambitious ones.

Phase 3: Create VISION.md

Read references/vision-format.md for the template. Create VISION.md in the project root with the seed idea, initialized status, and empty sections ready for the loop to fill.

Phase 4: Generate planning-loop.sh

Read references/ideation-strategies.md for background context on creative expansion techniques. The loop prompt template below already incorporates the key strategies — the reference file provides additional depth if you need to customize the prompt further.

Generate planning-loop.sh in the project root:

#!/usr/bin/env bash
# Autonomous planning loop — expands a seed idea into a vision and implementation plan
# Usage: bash ./planning-loop.sh [max_iterations] [resume_session_id]
set -euo pipefail

# Ensure Git Bash utilities are on PATH when invoked from PowerShell on Windows
export PATH="/usr/bin:/mingw64/bin:$PATH"

MAX="${1:-DEFAULT_MAX}"
RESUME_ID="${2:-}"

if [ ! -f "VISION.md" ]; then
  echo "Missing VISION.md — run the planning-loop skill first to create it."
  exit 1
fi

if head -5 VISION.md 2>/dev/null | grep -q "PLANNING_COMPLETE"; then
  echo "VISION.md is marked PLANNING_COMPLETE. Remove the marker to re-run planning."
  exit 0
fi

BRANCH=$(git branch --show-current)
PROMPT_FILE=".claude/planning-prompt.txt"
ITER_FILE=".claude/planning-prompt-iter.txt"
i=0

# --- Interrupt handling ---
IN_SESSION=false
LAST_SESSION_ID=""

cleanup() {
    echo ""
    if [ "$IN_SESSION" = true ]; then
        echo "=== Loop interrupted mid-iteration ==="
        echo "Uncommitted work may exist. Check: git status"
        if [ -n "$LAST_SESSION_ID" ] && [ "$LAST_SESSION_ID" != "" ]; then
            echo "Resume: claude --resume $LAST_SESSION_ID"
            echo "Or restart: bash ./planning-loop.sh $MAX $LAST_SESSION_ID"
        else
            echo "Start a new iteration to continue."
        fi
    else
        echo "=== Loop stopped between iterations ==="
        echo "All completed work is committed."
    fi
    exit 0
}
trap cleanup INT

# --- UUID generator (cross-platform) ---
gen_uuid() {
    python3 -c "import uuid; print(uuid.uuid4())" 2>/dev/null || \
    python -c "import uuid; print(uuid.uuid4())" 2>/dev/null || \
    echo ""
}

mkdir -p .claude

cat > "$PROMPT_FILE" = consumption?
- Calculate timing: How long to acquire one unit vs. how long one unit lasts? Include travel time, gathering time, and any delays.
- What happens during disruption periods (seasonal changes, enemy attacks, environment changes)? Can entities survive on stockpiled resources? Show the buffer math.
- Is there a death spiral? (Running out of A makes it harder to get B, which makes A worse...)
- What is the recovery path when resources are critically low?

For SPATIAL/MOVEMENT systems (pathfinding, collision, positioning):
- Can entities physically reach every position they need for every interaction? Check movement step size vs. required precision.
- Does collision avoidance conflict with any required behaviors? (e.g., multiple entities entering a building, fleeing to the same shelter)
- When entities crowd around a target (resource, building entrance, item), what happens? Is there queuing, do they give up, or do they deadlock?
- Priority: When survival behavior (flee to shelter) conflicts with movement rules (collision avoidance), which wins? Define explicit priority ordering.

For ANY system, answer: "If I mentally simulate an entity interacting with this system for 10 minutes straight, at what point does it break?"

RESEARCH — Game mechanics exist but aren't grounded in what works.
Use web search to investigate:
- Direct competitors — what games exist in this space? What do they nail or miss?
- Genre analysis — what are the established patterns players expect? Where can we subvert them?
- Adjacent inspiration — what mechanics from other genres could cross-pollinate?
- Technical feasibility — what engines, frameworks, or approaches suit this? Known hard problems?
Cite findings. Record detailed research in vision/competitor-research.md (or similar detail file) and update the brief summary in VISION.md.
Use research to STRENGTHEN the game design, not water it down to match existing games.

CRITIQUE — Vision is broad and deep but hasn't been stress-tested.
Be the skeptic. Think like a player, not a designer:
- Is the core game loop actually FUN? Would you play this for hours?
- Which mechanics are derivative? Make them unique or cut them.
- Which systems conflict or create unfun interactions?
- What's the weakest part of the player experience? Fix it or cut it.
- Is the scope realistic for the tech stack? What's truly core vs nice-to-have?
- What's the hook in one sentence — why would a player choose THIS over everything else on Steam/itch.io?
Move cut features to Cutting Room Floor with clear reasoning.

MANDATORY GAMEPLAY WALKTHROUGH (required during every CRITIQUE):
Mentally simulate a complete play session from launch to 30 minutes in. Write it out step by step:
"The player opens the game. They see X. They click Y. Entity A does Z. Meanwhile, entity B is doing W..."
At each step ask: Is this clear? Is this fun? Does the math work? What could go wrong?
Document every issue found — timing conflicts, impossible situations, confusing moments, missing feedback.

MANDATORY UX COMPLETENESS CHECK (required during every CRITIQUE):
Go through this checklist and flag anything missing or inadequate:
- [ ] Can the player restart/reset the game without closing the application?
- [ ] Can the player pause the game?
- [ ] Is there a menu with essential options (restart, settings, quit)?
- [ ] Can UI elements be repositioned if they might obstruct the player's view or other applications?
- [ ] For every player interaction: how does the player LEARN this control exists? Is it documented in a help screen, tooltip, or tutorial?
- [ ] For every game event: does the player receive visible feedback that it happened?
- [ ] If the game can end (win or lose), is there a clear end screen with options to continue?
- [ ] Are controls discoverable through standard conventions, or do they require explanation?
- [ ] For idle/background games: Can the game be minimized, moved, or repositioned without breaking?
- [ ] For idle/background games: Does the game respect the player's workspace and not obstruct other applications?
Add missing items as features in the Feature Map or as notes in Open Questions.

REFINE — Vision is comprehensive and battle-tested.
Organize for building as PLAYABLE VERTICAL SLICES:
- Milestone 1: Bare minimum game loop — player performs core action, sees a result. Fastest path to "you can play this."
- Milestone 2: Core mechanic end-to-end with basic content. The central fantasy is playable.
- Milestone 3+: One major system at a time. Each adds ONE capability plus everything to make it work and testable.
- NEVER front-load infrastructure — only build what the CURRENT milestone needs.
- Within each milestone, order tasks: setup for THIS feature → implement → test → minimum polish.
- Tasks that "prepare for future milestones" belong in those future milestones, not here.
- Each milestone must be fun (or at least interesting) to play, not just technically runnable.
- Define MVP as the first milestone where a player would choose to keep playing.

PLAN — Vision is refined and organized, ready for implementation.
Create or update the implementation plan as a set of files:
- IMPLEMENTATION_PLAN.md is the HUB — Goal, milestone list (status + links to task files), Decision Log, Issues Found, and a "How to Use" section for the dev loop agent.
- Create plans/milestone-N-name.md for each milestone with flat checkbox tasks: - [ ] Task — file path — approach
- Header: 
- If plans already exist, update rather than recreate.
- When complete, add  as the FIRST line of VISION.md.

TESTABILITY — CRITICAL:
Everything planned must be testable by an AI agent. No feature should require human playtesting to verify.
- Separate game logic from rendering. Core mechanics in pure, testable code — the engine renders state, it doesn't compute it.
- Game state must be observable — every action/event must produce checkable World state.
- Prefer deterministic behavior: seeded PRNG, tick-based time (advanceTicks), reproducible scenarios.
- Test infrastructure is first-class — helpers, scenario builders, and fixtures are planned as tasks alongside features.
- Every milestone task file must include test tasks. If a mechanic can't be tested by the dev agent, the plan is incomplete.

FILE MANAGEMENT — CRITICAL:
- VISION.md is a hub — keep under ~500 lines. Extract substantial sections to vision/ detail files with a summary + link.
- IMPLEMENTATION_PLAN.md is a hub pointing to plans/milestone-N-name.md task files.
- Never put hundreds of items in a single file.

EXPERT REVIEW PANEL — after completing your primary creative work, spawn the relevant review sub-agents.
Each agent brings a different perspective. Spawn them IN PARALLEL for speed.

WHICH AGENTS TO SPAWN (spawn all that apply for the current phase):

| Phase | Senior Developer | Systems Integration Analyst | Player Experience Designer |
|-------|:---:|:---:|:---:|
| EXPAND (first ~5 iterations) | Skip | Skip | Skip |
| EXPAND (5+ iterations) | Yes | Skip | Skip |
| DEEPEN | Yes | YES (critical) | Skip |
| RESEARCH | Skip | Skip | Skip |
| CRITIQUE | Yes | Yes | YES (critical) |
| REFINE | Yes | Yes | Yes |
| PLAN | Yes | Yes | Yes |

When in doubt, spawn them — a "No concerns" review is cheap. Spawn all applicable agents in parallel using multiple Agent tool calls in a single response.

--- AGENT 1: Senior Developer ---
Spawn with the Agent tool using this prompt:

"You are a Senior Game Developer reviewing a game vision in progress.
Read VISION.md and any vision/ detail files it links to. Read the git diff of the latest uncommitted changes (git diff) to see what was just added or modified.

Provide a brief, structured technical review:

FEASIBILITY: Flag anything fundamentally impossible or requiring technology that does not exist. 'Hard to build' is fine and expected — only flag 'cannot be built.' Be specific about WHY something is impossible if you flag it.

ARCHITECTURE: Note concerns about how game systems would be structured. Flag testability issues — can an AI agent verify this mechanic works without human playtesting? Suggest the engine/renderer firewall pattern (no game logic in engine code) if the vision doesn't already account for it.

EFFORT FLAGS: For major new features or systems, note rough complexity (simple / moderate / complex / massive). Do not say 'don't do it' — just flag what is big so the planning phase can sequence milestones wisely.

SMARTER PATHS: If you see a simpler way to achieve the same player experience, suggest it. Do not water down the vision — find cleverer engineering paths to the same creative goal.

Keep the review concise. Focus only on things that matter — do not nitpick style or minor details. The creative vision is not yours to judge; your job is to help make it buildable and testable.

Return your review as a structured list under those four headings. If a section has no concerns, write 'No concerns.'"

--- AGENT 2: Systems Integration Analyst ---
Spawn with the Agent tool using this prompt:

"You are a Systems Integration Analyst reviewing a game design for internal consistency and mechanical soundness.
Read VISION.md and all vision/ detail files it links to. Read the git diff (git diff) to see recent changes.

Your job is to find places where game systems BREAK EACH OTHER. Designers often create systems in isolation that conflict when combined. You must catch these before they reach implementation.

Analyze each of these areas and report findings:

RESOURCE LOOP MATH:
For every resource in the game (food, energy, health, money, materials, etc.):
- List all sources and all drains
- Calculate: at steady state, does production >= consumption? Show approximate numbers
- Calculate timing: acquisition time (including travel) vs. consumption rate
- Identify disruption periods (seasons, events, enemy attacks) — can entities survive them on reserves?
- Flag any death spirals where scarcity accelerates further scarcity with no recovery path

SPATIAL CONFLICTS:
For every entity that moves and interacts with locations:
- Can entities reach every position required for every interaction? Check movement granularity vs. required precision
- Does collision/pathfinding conflict with required behaviors? (multiple entities entering buildings, crowding at resources, fleeing to shelter)
- When N entities need the same spot, what happens? Flag potential deadlocks or permanent blockage
- Are interaction trigger zones compatible with movement step sizes?

SYSTEM vs. SYSTEM CONFLICTS:
For every pair of systems that could interact:
- Does System A's rules ever make System B impossible or impractical?
- When two systems compete for an entity's action, is the priority clear and correct?
- Can an entity get stuck in a loop between competing system demands?
- What happens at system boundaries and edge cases?

TIMING CONFLICTS:
- Are any timers or cycles incompatible? (e.g., resource consumption faster than replenishment under any normal condition)
- Do day/night, seasonal, or event cycles create periods where critical systems become impossible?
- Are cooldowns, travel times, and action durations consistent and survivable?

For each issue found, provide:
1. The specific conflict (which systems, what goes wrong)
2. A concrete scenario showing how it manifests in gameplay
3. One or two suggested fixes

Return findings grouped by severity: CRITICAL (game-breaking, will always happen), WARNING (problematic under common conditions), NOTE (edge case or minor concern). If no issues in a catego

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [RiccardoGrin](https://github.com/RiccardoGrin)
- **Source:** [RiccardoGrin/skills](https://github.com/RiccardoGrin/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.