Metro Tycoon — Zach-like Metro Station Puzzle Game (Bevy/Rust) Work Plan

metro-tycoon.md

Metro Tycoon — Zach-like Metro Station Puzzle Game

TL;DR

Quick Summary: Build a Zach-like puzzle game where players construct metro stations in restricted city spaces using Bevy 0.18 (Rust). The game features a diamond isometric grid, multi-size prefab facilities, need-based passenger AI with A* pathfinding, and a 3-axis optimization scoring system (Cost/Time/Space) with histogram comparison.

Deliverables:

• Playable tutorial level with build/simulate/optimize loop
• Diamond isometric grid map with restricted/unbuildable areas and existing railway
• Building placement system for large/medium/small prefabs + floor tiles
• Need-based passenger AI with random demands and A* pathfinding
• 3-axis scoring system (Cost/Time/Space) with histogram display
• Core logic unit tests (pathfinding, scoring, grid validation)
• Placeholder geometry visuals (colored shapes)

Estimated Effort: Large Parallel Execution: YES - 5 waves Critical Path: Grid/Core Types → Floor/Pathfinding → Building System → Passenger AI → Simulation → Scoring/UI → Tutorial Level

---

Context

Original Request

Build a 2.5D isometric construction game similar to RollerCoaster Tycoon using Bevy (Rust), which evolved into a Zach-like puzzle game where each level is a city space with restricted areas and an existing metro route. Players build a station to meet requirements, then run a flow simulation test that scores on multiple conflicting metrics.

Interview Summary

Key Discussions:

• Genre pivot: From tycoon to Zach-like puzzle (inspired by Infinifactory + Opus Magnum)
• Grid system: Diamond isometric (菱形格子)
• Facility sizes: Large prefabs (Platform, Entrance/Exit, Hall, Shop), Medium (Elevator, Escalator), Small (Ticket Machine, Vending Machine)
• Connection model: Facility footprints = walkable area; adjacent facilities auto-connect; 2 floors (B1 + 1F) with elevator/escalator portals
• Passenger AI: Need-based with random 1-3 needs per passenger
• Scoring: 3 conflicting dimensions (Cost/Time/Space) — classic Zach-like optimization triangle
• Pass condition: Path exists = pass; low happiness = complaints = money deduction
• Build/Sim flow: Free switching (Opus Magnum style)
• MVP scope: 1 hand-crafted tutorial level
• Art: Placeholder geometry (colored shapes)
• Developer: Experienced with Rust + Bevy

Research Findings:

• bevy_ecs_tilemap v0.18 supports isometric diamond grid, Y-sort, chunked rendering
• Kilowatt Tycoon is a production Bevy reference for building placement + grid validation
• Bevy 0.18 has first-party PanCameraPlugin for pan/zoom
• Opus Magnum/Infinifactory are primary design references for Zach-like mechanics
• Market gap: No existing Zach-like focused on station construction

Metis Review

Key Risks Identified:

• Isometric coordinate conversion bugs → Mitigate: centralize conversions + property tests
• Multi-floor pathfinding blowup → Mitigate: single-floor MVP or strict 2-floor + fixed rules
• Agent pathfinding cost with many passengers → Mitigate: lock MVP to 30 passengers
• Non-determinism in sim → Mitigate: fixed timestep, seeded RNG, single-thread in tests

Metis Directives Incorporated:

• Keep core logic pure (non-Bevy modules) for maximum unit test coverage
• Use Bevy State-driven mode switching: GameMode with run_if(in_state(...))
• Define exact tile adjacency, walkability, max counts as hard caps
• Build mode freezes simulation completely
• Follow existing XPlugin style from codebase

Auto-Resolved Gaps (sensible defaults applied):

• Simulation duration: Fixed time window (e.g., 90 seconds game time)
• Happiness model: Simple — decreases with wait time + walking distance
• Undo/demolish: Included (essential UX, not optional)
• Camera bounds: Bounded to level area
• Save/load: Explicitly NOT in MVP
• Economy: Build cost only + complaint penalty (simple formula)
• Movement: Tile-to-tile per tick (discrete, deterministic)
• Passenger spawn: Fixed steady rate from entrance prefab location
• Passenger count cap: 30 for tutorial level

Decisions Needed (from Metis — requires user input):

• Grid adjacency → RESOLVED: 4-neighbor (diamond four directions)
• Multi-floor → RESOLVED: 2 floors (underground B1 + ground level 1F), elevators/escalators are functional inter-floor portals
• Connected definition → RESOLVED: Facilities provide implicit walkable area; adjacent facilities auto-connect (no separate floor tiles needed)
• Concrete passenger needs → RESOLVED: Random 0-3 needs from a pool (buy ticket, buy snack, etc.)

Architecture Impact (from resolved decisions):

• NO floor tile system — walkability = union of all facility footprints
• 2-layer grid: GridCoord { x, y, floor } where floor ∈ {B1, 1F}
• Elevators/Escalators: Portal entities connecting B1 ↔ 1F at specific grid positions
• Pathfinding: A* on 3D grid (x, y, floor) with portals as inter-floor edges
• Adjacency: 4-neighbor within same floor; portals bridge floors
• Placement: Player places facilities, their footprint creates walkable tiles automatically

---

Work Objectives

Core Objective

Create a playable Zach-like metro station puzzle game with one complete tutorial level, featuring the full build → simulate → optimize gameplay loop with 3-axis scoring.

Concrete Deliverables

• Working Bevy 0.18 app with diamond isometric rendering
• Grid system with buildable/unbuildable/restricted tiles
• Building placement system supporting 3 size categories of prefabs + floor tiles
• A* pathfinding on the floor tile grid
• Need-based passenger AI that pathfinds through the station
• Simulation mode with passenger flow visualization and speed controls
• 3-axis scoring system with histogram display
• Unit tests for core game logic
• One hand-crafted tutorial level

Definition of Done

• cargo run launches the game showing the tutorial level
• Player can place/remove floor tiles and all facility types
• Player can switch between Build and Simulate modes freely
• In Simulate mode, passengers spawn, pathfind, and complete their journeys
• After simulation, scoring screen shows Cost/Time/Space metrics
• cargo test passes all unit tests for core logic
• No as any, unwrap() in production code, no console logging

Must Have

• Diamond isometric grid rendering
• 8 facility types (4 large + 2 medium + 2 small) + floor tiles
• Multi-tile placement validation (no overlaps, no restricted areas)
• A* pathfinding on floor tiles
• Passenger AI with random needs
• Free build/simulate mode switching
• 3-axis scoring with visual display
• Undo/demolish for placed items
• Unit tests for pathfinding, scoring, grid validation
• Placeholder geometry visuals

Must NOT Have (Guardrails)

• ❌ Multi-floor/vertical levels (post-MVP)
• ❌ Procedural level generation (post-MVP)
• ❌ Save/load system (post-MVP)
• ❌ Full economy/tycoon systems (post-MVP)
• ❌ Polished art assets (placeholder only)
• ❌ Sound effects or music (post-MVP)
• ❌ Multiple levels or level select screen (post-MVP)
• ❌ Tutorial text/walkthrough system (post-MVP — tutorial level design itself IS the tutorial)
• ❌ Leaderboard/online histogram comparison (use placeholder static data)
• ❌ AI slop: over-abstracted ECS, excessive comments, generic naming
• ❌ External map editor integration (Tiled/LDtk) — define levels in code/RON for MVP

---

Verification Strategy

ZERO HUMAN INTERVENTION — ALL verification is agent-executed. No exceptions.

Test Decision

• Infrastructure exists: NO (new project)
• Automated tests: YES — Unit tests for core logic (pathfinding, scoring, grid validation)
• Framework: Rust built-in #[cfg(test)] + cargo test
• Scope: Game logic modules only (not Bevy rendering/systems)

QA Policy

Every task MUST include agent-executed QA scenarios. Evidence saved to .sisyphus/evidence/task-{N}-{scenario-slug}.{ext}.

• Game App: Use interactive_bash (tmux) — Launch game, verify window opens, check logs
• Unit Tests: Use Bash — Run cargo test, verify pass count
• Core Logic: Use Bash — Run specific test suites, verify output
• Build Verification: Use Bash — Run cargo build, verify no errors

---

Execution Strategy

Parallel Execution Waves

Wave 1 (Start Immediately — foundation types + project scaffolding):
├── Task 1:  Project scaffolding + Bevy setup + dependencies [quick]
├── Task 2:  Core type definitions + grid data structures [quick]
├── Task 3:  Isometric camera + basic rendering setup [quick]
└── Task 4:  Level definition format + tutorial level data [quick]

Wave 2 (After Wave 1 — core systems, MAX PARALLEL):
├── Task 5:  Grid rendering system (depends: 2, 3) [unspecified-high]
├── Task 6:  Navigation graph + A* pathfinding (depends: 2) [deep]
├── Task 7:  Building placement system (depends: 2, 3) [deep]
├── Task 8:  Passenger data types + needs system (depends: 2) [unspecified-high]
└── Task 9:  UI framework — toolbar + HUD + mode indicator (depends: 3) [visual-engineering]

Wave 3 (After Wave 2 — simulation + interaction):
├── Task 10: Passenger AI — spawn, pathfind, fulfill needs (depends: 6, 8) [deep]
├── Task 11: Simulation controller — play/pause/speed (depends: 8) [unspecified-high]
├── Task 12: Demolish/undo system (depends: 7) [quick]
└── Task 13: Prefab visual rendering — placeholder geometry (depends: 5, 7) [visual-engineering]

Wave 4 (After Wave 3 — scoring + integration):
├── Task 14: Scoring system — Cost/Time/Space calculation (depends: 7, 10, 11) [deep]
├── Task 15: Scoring UI — histogram display + results screen (depends: 9, 14) [visual-engineering]
├── Task 16: Game state machine — Build ↔ Simulate transitions (depends: 11, 14) [unspecified-high]
└── Task 17: Tutorial level assembly + gameplay integration test (depends: 10, 12, 13, 16) [deep]

Wave FINAL (After ALL tasks — 4 parallel reviews):
├── F1: Plan compliance audit (oracle)
├── F2: Code quality review (unspecified-high)
├── F3: Real manual QA — play through tutorial level (unspecified-high)
└── F4: Scope fidelity check (deep)
→ Present results → Get explicit user okay

Critical Path: T2 → T6 → T10 → T14 → T16 → T17 → FINAL
Parallel Speedup: ~60% faster than sequential
Max Concurrent: 5 (Wave 2)

Dependency Matrix

Task	Depends On	Blocks	Wave
1	—	2, 3, 4	1
2	1	5, 6, 7, 8	1
3	1	5, 7, 9	1
4	1	17	1
5	2, 3	13	2
6	2	10	2
7	2, 3	12, 13, 14	2
8	2	10, 11	2
9	3	13, 15	2
10	6, 8	14, 17	3
11	8	14, 16	3
12	7	17	3
13	5, 7, 9	17	3
14	7, 10, 11	15, 16	4
15	9, 14	—	4
16	11, 14	17	4
17	10, 12, 13, 16	FINAL	4

Agent Dispatch Summary

• Wave 1 (4 tasks): T1 → quick, T2 → quick, T3 → quick, T4 → quick
• Wave 2 (5 tasks): T5 → unspecified-high, T6 → deep, T7 → deep, T8 → unspecified-high, T9 → visual-engineering
• Wave 3 (4 tasks): T10 → deep, T11 → unspecified-high, T12 → quick, T13 → visual-engineering
• Wave 4 (4 tasks): T14 → deep, T15 → visual-engineering, T16 → unspecified-high, T17 → deep
• FINAL (4 tasks): F1 → oracle, F2 → unspecified-high, F3 → unspecified-high, F4 → deep

---

TODOs

• 1. Project Scaffolding + Bevy Setup + Dependencies

  What to do:

  • Update Cargo.toml to add required dependencies: bevy = "0.18", bevy_ecs_tilemap = "0.18", pathfinding crate (for A*)
  • Restructure src/ into module hierarchy: main.rs with mod declarations for grid/, building/, passenger/, pathfinding/, scoring/, simulation/, ui/, level/, camera/, state/, types/
  • Create placeholder mod.rs for each module with basic plugin stubs
  • Set up Bevy App with DefaultPlugins, custom plugins for each module
  • Configure bevy_ecs_tilemap plugin
  • Remove the existing hello-world example code from main.rs

  Must NOT do:

  • Don't add unnecessary dependencies (sound, physics, etc.)
  • Don't create complex plugin architectures — keep it simple

  Recommended Agent Profile:

  • Category: quick
    • Reason: Standard project scaffolding, well-defined structure
  • Skills: []
  • Skills Evaluated but Omitted:
    • No skills needed for scaffolding

  Parallelization:

  • Can Run In Parallel: YES
  • Parallel Group: Wave 1 (with Tasks 2, 3, 4 — but this task should finish first as others depend on it)
  • Blocks: Tasks 2, 3, 4
  • Blocked By: None (can start immediately)

  References: Pattern References:

  • Cargo.toml — Current project config, needs dependency additions
  • src/main.rs — Current Bevy setup, needs restructuring

  External References:

  • bevy_ecs_tilemap crate: https://docs.rs/bevy_ecs_tilemap/latest — For version compatibility with Bevy 0.18
  • pathfinding crate: https://docs.rs/pathfinding/latest — For A* algorithm

  WHY Each Reference Matters:

  • Cargo.toml: Must add correct dependency versions that are compatible with Bevy 0.18
  • main.rs: Current code needs full replacement — it's just the Bevy tutorial example

  Acceptance Criteria:

  • cargo build succeeds with all new dependencies
  • Module structure exists: src/{grid,building,passenger,pathfinding,scoring,simulation,ui,level,camera,state,types}/mod.rs
  • main.rs sets up Bevy App with plugin stubs, no hello-world code
  • Each module has a Plugin struct implementing Plugin trait

  QA Scenarios:

  Scenario: Build succeeds with new structure
    Tool: Bash
    Preconditions: Clean project state
    Steps:
      1. Run `cargo build`
      2. Check exit code is 0
    Expected Result: Build succeeds with no errors
    Failure Indicators: Compilation errors, missing dependencies
    Evidence: .sisyphus/evidence/task-1-build-success.txt
  
  Scenario: Module structure is correct
    Tool: Bash
    Preconditions: Build succeeded
    Steps:
      1. Run `find src -name "mod.rs" | sort`
      2. Verify output contains all expected modules
    Expected Result: 11 mod.rs files in expected directories
    Failure Indicators: Missing modules, wrong directory structure
    Evidence: .sisyphus/evidence/task-1-module-structure.txt
  

  Commit: YES

  • Message: feat(scaffold): initialize Bevy project with module structure and dependencies
  • Files: Cargo.toml, Cargo.lock, src/main.rs, src/*/mod.rs
  • Pre-commit: cargo build

• 2. Core Type Definitions + Grid Data Structures

  What to do:

  • Define core types in src/types/:
    • GridCoord (x, y as i32) — diamond isometric grid coordinate
    • TileType enum: Buildable, Restricted, Railway, Floor, Occupied
    • FacilityType enum with size info: Platform(3x2), Entrance(2x2), Hall(3x3), Shop(2x2), Elevator(1x2), Escalator(1x2), TicketMachine(1x1), VendingMachine(1x1)
    • FacilityCategory enum: Large, Medium, Small
    • PlacementResult enum: Valid, Invalid(reason)
    • GameMode enum: Building, Simulating
    • SimulationSpeed enum: Paused, Normal, Fast, UltraFast
  • Define GridMap struct in src/grid/:
    • Internal storage: HashMap<GridCoord, TileType> or 2D array
    • Methods: get_tile(coord), set_tile(coord, type), is_buildable(coord), can_place_prefab(origin, size), place_prefab(origin, facility), remove_prefab(origin)
  • Define Facility component: type, grid_origin, rotation, cost
  • Define FloorTile component: position
  • Write unit tests for GridMap:
    • Test can_place_prefab with valid/invalid positions (overlaps, restricted, out of bounds)
    • Test place_prefab / remove_prefab correctly update grid state
    • Test multi-tile prefab footprint calculation

  Must NOT do:

  • Don't implement rendering (Wave 2)
  • Don't add pathfinding logic (separate task)
  • Don't over-abstract — use concrete types, not trait objects

  Recommended Agent Profile:

  • Category: quick
    • Reason: Type definitions and data structures, well-defined scope
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES (after Task 1)
  • Parallel Group: Wave 1 (with Tasks 3, 4)
  • Blocks: Tasks 5, 6, 7, 8
  • Blocked By: Task 1

  References: Pattern References:

  • Kilowatt Tycoon src/components/site.rs — Grid validation pattern: can_place_footprint(), world_to_grid() conversion
  • Kilowatt Tycoon src/systems/build_input.rs — Placement validation with size variants

  External References:

  • bevy_ecs_tilemap isometric diamond coordinate system: https://docs.rs/bevy_ecs_tilemap/latest — TilemapType::Isometric(IsoCoordSystem::Diamond)

  WHY Each Reference Matters:

  • Kilowatt Tycoon: Shows production pattern for multi-tile building validation in Bevy ECS
  • bevy_ecs_tilemap: Defines the coordinate system our grid types must align with

  Acceptance Criteria:

  • All types defined with proper #[derive] macros (Component, Clone, Debug, etc.)
  • GridMap methods work correctly for single and multi-tile operations
  • cargo test passes all grid validation unit tests (at least 5 test cases)
  • No unwrap() in GridMap methods — proper error handling

  QA Scenarios:

  Scenario: Grid validation unit tests pass
    Tool: Bash
    Preconditions: Task 1 completed
    Steps:
      1. Run `cargo test grid`
      2. Check all tests pass
    Expected Result: 5+ tests pass, 0 failures
    Failure Indicators: Any test failure
    Evidence: .sisyphus/evidence/task-2-grid-tests.txt
  
  Scenario: Multi-tile placement validation edge cases
    Tool: Bash
    Preconditions: GridMap implemented
    Steps:
      1. Run `cargo test grid::can_place_prefab`
      2. Verify tests cover: overlap, restricted area, out-of-bounds, boundary case
    Expected Result: All placement validation tests pass
    Failure Indicators: Missing edge case coverage
    Evidence: .sisyphus/evidence/task-2-placement-tests.txt
  

  Commit: YES

  • Message: feat(types): core grid, facility, and game state types with unit tests
  • Files: src/types/, src/grid/
  • Pre-commit: cargo test

• 3. Isometric Camera + Basic Rendering Setup

  What to do:

  • Create isometric camera system in src/camera/:
    • Spawn Camera2d with OrthographicProjection configured for isometric view
    • Implement camera pan (WASD + mouse drag) and zoom (scroll wheel)
    • Set initial camera position for good overview of tutorial level
    • Bound camera movement to level area
  • Configure ScalingMode for consistent tile sizing
  • Add PanCameraPlugin (Bevy 0.18 built-in) or custom pan/zoom system
  • Verify the camera setup works with isometric grid coordinates

  Must NOT do:

  • Don't implement tile rendering (Wave 2)
  • Don't add UI elements (separate task)

  Recommended Agent Profile:

  • Category: quick
    • Reason: Standard Bevy camera setup, well-documented pattern
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES (after Task 1)
  • Parallel Group: Wave 1 (with Tasks 2, 4)
  • Blocks: Tasks 5, 7, 9
  • Blocked By: Task 1

  References: External References:

  • Bevy 0.18 PanCamera: https://docs.rs/bevy/latest/bevy/camera_controller/pan_camera/ — Built-in pan/zoom for 2D
  • Bevy OrthographicProjection: https://docs.rs/bevy/latest/bevy/render/camera/struct.OrthographicProjection.html — For isometric setup

  WHY Each Reference Matters:

  • PanCamera: Provides the exact API for camera pan/zoom that we need
  • OrthographicProjection: Must configure scaling mode correctly for isometric tiles

  Acceptance Criteria:

  • cargo run shows a window with isometric camera
  • WASD/arrow keys pan the camera
  • Mouse wheel zooms in/out
  • Camera is bounded to a reasonable area
  • Camera plugin registered in main App

  QA Scenarios:

  Scenario: Camera system launches
    Tool: Bash
    Preconditions: Task 1 completed
    Steps:
      1. Run `cargo build`
      2. Verify compilation succeeds
    Expected Result: Build succeeds, no camera-related errors
    Failure Indicators: Compilation errors in camera module
    Evidence: .sisyphus/evidence/task-3-camera-build.txt
  
  Scenario: Camera plugin registered
    Tool: Bash
    Preconditions: Build succeeds
    Steps:
      1. Grep main.rs for camera plugin registration
      2. Verify CameraPlugin is added to App
    Expected Result: CameraPlugin appears in app builder chain
    Failure Indicators: Plugin not registered
    Evidence: .sisyphus/evidence/task-3-camera-plugin.txt
  

  Commit: YES

  • Message: feat(camera): isometric diamond camera with pan/zoom
  • Files: src/camera/
  • Pre-commit: cargo build

• 4. Level Definition Format + Tutorial Level Data

  What to do:

  • Define level data format in src/level/:
    • LevelData struct: name, grid_size, tiles (Vec of restricted/railway positions), railway_path, buildable_area_bounds, passenger_config
    • RailwaySegment struct: start/end GridCoord, direction
    • PassengerConfig struct: spawn_rate, needs_pool, total_passengers, time_limit
    • LevelObjective struct: minimum_passenger_count, target_metrics
  • Create tutorial level data:
    • Grid size: ~20x20 diamond tiles
    • Railway: One horizontal line through the middle (e.g., y=10)
    • Restricted areas: Some city blocks (buildings, roads) around the edges
    • Buildable area: Open area adjacent to railway for station construction
    • Passenger config: Slow spawn rate, 1-2 needs per passenger, 30 passengers total
    • Objective: Successfully route passengers to the platform
  • Implement level loader that converts LevelData into ECS entities
  • Write unit tests for level data validation

  Must NOT do:

  • Don't implement procedural generation (post-MVP)
  • Don't create multiple levels (just tutorial)
  • Don't use external file formats — define in Rust code for MVP

  Recommended Agent Profile:

  • Category: quick
    • Reason: Data definitions and static level data, straightforward
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES (after Task 1)
  • Parallel Group: Wave 1 (with Tasks 2, 3)
  • Blocks: Task 17
  • Blocked By: Task 1

  References: Pattern References:

  • Kilowatt Tycoon level/site structure — How they define buildable grids with constraints

  WHY Each Reference Matters:

  • Need to understand how to represent restricted areas and railway segments as level data

  Acceptance Criteria:

  • LevelData struct with all fields defined
  • Tutorial level data created with concrete values
  • Level loader converts data to tile entities
  • Unit tests verify level data is valid (no overlapping restrictions, railway is connected)
  • cargo test level passes

  QA Scenarios:

  Scenario: Level data validation tests pass
    Tool: Bash
    Preconditions: Task 1 completed
    Steps:
      1. Run `cargo test level`
      2. Verify all level validation tests pass
    Expected Result: Tests confirm level data is structurally valid
    Failure Indicators: Overlapping tiles, disconnected railway
    Evidence: .sisyphus/evidence/task-4-level-tests.txt
  
  Scenario: Tutorial level has required elements
    Tool: Bash
    Preconditions: Level data defined
    Steps:
      1. Grep for tutorial level definition
      2. Verify: grid_size, railway segments, restricted areas, buildable area all present
    Expected Result: All required elements defined with concrete values
    Failure Indicators: Missing fields, zero-sized grid, no railway
    Evidence: .sisyphus/evidence/task-4-tutorial-data.txt
  

  Commit: YES

  • Message: feat(level): level definition format and tutorial level data
  • Files: src/level/
  • Pre-commit: cargo test

• 5. Grid Rendering System

  What to do:

  • Implement isometric grid rendering in src/grid/:
    • Use bevy_ecs_tilemap with TilemapType::Isometric(IsoCoordSystem::Diamond) for the tilemap
    • Render 2 floor layers (B1 underground, 1F ground) with different visual treatment
    • Color-code tiles: grey=buildable, dark=restricted, blue=railway, green=walkable (facility footprint)
    • Support tile hover highlighting (show which tile the mouse is over)
  • Implement screen↔grid coordinate conversion:
    • Screen-to-world via camera viewport conversion
    • World-to-grid using diamond isometric formulas
    • Centralize all conversion in one module to prevent bugs (Metis risk mitigation)
  • Handle multi-floor rendering: render both floors, B1 tiles slightly transparent/darker
  • Write property tests for coordinate roundtrips (screen→grid→screen)

  Must NOT do:

  • Don't render facility sprites (Wave 3)
  • Don't implement pathfinding visualization

  Recommended Agent Profile:

  • Category: unspecified-high
    • Reason: bevy_ecs_tilemap isometric setup requires careful coordinate handling
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES
  • Parallel Group: Wave 2 (with Tasks 6, 7, 8, 9)
  • Blocks: Task 13
  • Blocked By: Tasks 2, 3

  References: Pattern References:

  • bevy_ecs_tilemap examples: iso_diamond.rs — Diamond isometric setup with TilemapBundle
  • bevy_ecs_tilemap examples: mouse_to_tile.rs — Screen-to-tile coordinate conversion via TilePos::from_world_pos()

  External References:

  • bevy_ecs_tilemap isometric docs: https://docs.rs/bevy_ecs_tilemap/latest — TilemapType::Isometric(IsoCoordSystem::Diamond)

  WHY Each Reference Matters:

  • iso_diamond.rs: Shows exact TilemapBundle configuration for diamond iso grid
  • mouse_to_tile.rs: Shows the correct API for screen-to-tile conversion in isometric mode

  Acceptance Criteria:

  • cargo run shows diamond isometric grid with colored tiles
  • Mouse hover highlights the correct tile under cursor
  • Both floor layers render (B1 and 1F)
  • Coordinate roundtrip property tests pass (cargo test grid::conversions)
  • Restricted/railway/buildable tiles rendered with distinct colors

  QA Scenarios:

  Scenario: Grid renders with correct tile types
    Tool: Bash
    Preconditions: Tasks 1-4 completed
    Steps:
      1. Run `cargo build`
      2. Verify no compilation errors in grid module
    Expected Result: Build succeeds
    Evidence: .sisyphus/evidence/task-5-grid-build.txt
  
  Scenario: Coordinate conversion tests pass
    Tool: Bash
    Preconditions: Grid module implemented
    Steps:
      1. Run `cargo test grid::conversions`
      2. Verify roundtrip tests pass for all quadrants
    Expected Result: All conversion tests pass
    Failure Indicators: Roundtrip failures, off-by-one errors
    Evidence: .sisyphus/evidence/task-5-conversion-tests.txt
  

  Commit: YES

  • Message: feat(grid): isometric diamond grid rendering with 2-floor layers
  • Files: src/grid/
  • Pre-commit: cargo test

• 6. Navigation Graph + A* Pathfinding

  What to do:

  • Implement navigation system in src/pathfinding/:
    • NavGraph struct: builds a graph from facility footprints on the grid
    • Nodes = walkable grid positions (x, y, floor) derived from placed facilities
    • Edges = 4-neighbor connections within same floor
    • Portal edges = elevator/escalator positions connecting B1 ↔ 1F
    • rebuild_graph(facilities, grid) method — called when facilities change
  • Implement A* pathfinding:
    • find_path(graph, start, end) → Option<Vec<NavNode>>
    • Heuristic: Manhattan distance on grid (4-neighbor)
    • Support portal nodes (inter-floor transitions)
  • Define passenger needs pool:
    • PassengerNeed enum: BuyTicket, BuySnack, UseRestroom (3 needs for MVP)
    • Each need maps to a facility type: BuyTicket → TicketMachine, BuySnack → VendingMachine/Shop
  • Implement need→facility resolution: given a passenger's current position and needs, find the nearest facility that satisfies each need
  • Write comprehensive unit tests:
    • Single-floor pathfinding (straight line, L-shape, blocked path)
    • Multi-floor pathfinding via elevator/escalator
    • Need→facility resolution with multiple candidate facilities
    • Graph rebuild after facility placement/removal
    • Edge case: no path exists, no matching facility for need

  Must NOT do:

  • Don't implement passenger spawning/movement (Wave 3)
  • Don't optimize for performance yet (30 passengers is small)
  • Don't use external pathfinding crate — implement A* directly (keeps it pure Rust, testable)

  Recommended Agent Profile:

  • Category: deep
    • Reason: Core algorithm work requiring careful correctness — A* + graph building + multi-floor portals
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES
  • Parallel Group: Wave 2 (with Tasks 5, 7, 8, 9)
  • Blocks: Task 10
  • Blocked By: Task 2

  References: External References:

  • A* algorithm reference: standard grid-based A* with Manhattan distance heuristic
  • Bevy ECS querying pattern for facility positions

  WHY Each Reference Matters:

  • A* correctness is critical — wrong pathfinding breaks the entire game
  • Must handle portal nodes correctly for inter-floor transitions

  Acceptance Criteria:

  • NavGraph builds correctly from facility placements
  • A* finds shortest path on single floor
  • A* finds path across floors via elevator/escalator portals
  • Returns None when no path exists
  • Need→facility resolution finds nearest matching facility
  • cargo test pathfinding passes all tests (10+ test cases)

  QA Scenarios:

  Scenario: Single-floor pathfinding tests
    Tool: Bash
    Steps:
      1. Run `cargo test pathfinding::single_floor`
    Expected Result: Tests for straight, L-shape, blocked paths all pass
    Evidence: .sisyphus/evidence/task-6-path-single.txt
  
  Scenario: Multi-floor pathfinding via portal
    Tool: Bash
    Steps:
      1. Run `cargo test pathfinding::multi_floor`
    Expected Result: A* correctly routes through elevator/escalator portals between B1 and 1F
    Evidence: .sisyphus/evidence/task-6-path-multi.txt
  
  Scenario: Need resolution tests
    Tool: Bash
    Steps:
      1. Run `cargo test pathfinding::needs`
    Expected Result: Each need type resolves to correct facility type, nearest facility chosen
    Evidence: .sisyphus/evidence/task-6-needs.txt
  

  Commit: YES

  • Message: feat(pathfinding): A* navigation graph with multi-floor portals and need resolution
  • Files: src/pathfinding/
  • Pre-commit: cargo test

• 7. Building Placement System

  What to do:

  • Implement building placement in src/building/:
    • Track BuildState resource: selected_facility: Option<FacilityType>, current_floor: Floor
    • Placement preview: show ghost/preview of facility at mouse position, green=valid/red=invalid
    • Validation: check grid bounds, no overlap with existing facilities, not on restricted tiles, not on railway (unless platform)
    • Place facility: update grid, spawn ECS entity with Facility component + Transform
    • Demolish: click existing facility to remove it, refund partial cost, update grid
    • Floor toggle: button/key to switch between B1 and 1F placement
  • Facility cost definitions:
    • Platform: $5000, Hall: $3000, Entrance/Exit: $2000, Shop: $1500
    • Elevator: $1000, Escalator: $800
    • TicketMachine: $200, VendingMachine: $150
  • Write unit tests:
    • Placement validation (valid position, overlap, restricted, out-of-bounds)
    • Cost calculation
    • Demolish + grid state restoration
    • Multi-tile footprint overlap detection

  Must NOT do:

  • Don't implement undo history stack (just demolish is enough)
  • Don't implement rotation for MVP (all prefabs have fixed orientation)

  Recommended Agent Profile:

  • Category: deep
    • Reason: Core interaction system with multi-tile validation, state management, preview rendering
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES
  • Parallel Group: Wave 2 (with Tasks 5, 6, 8, 9)
  • Blocks: Tasks 12, 13, 14
  • Blocked By: Tasks 2, 3

  References: Pattern References:

  • Kilowatt Tycoon src/systems/build_input.rs — Placement cursor system with green/red preview, multi-tile footprint validation

  WHY Each Reference Matters:

  • Kilowatt Tycoon shows the exact pattern for placement cursor, validation, and multi-tile structure handling in Bevy

  Acceptance Criteria:

  • Can select facility from toolbar and see preview at mouse position
  • Green preview for valid placement, red for invalid
  • Click places facility, updates grid state
  • Right-click or demolish tool removes facility
  • Floor toggle switches between B1 and 1F
  • Placement cost tracked in build state
  • cargo test building passes validation tests

  QA Scenarios:

  Scenario: Placement validation tests pass
    Tool: Bash
    Steps:
      1. Run `cargo test building`
    Expected Result: Tests for valid/invalid/overlap/bounds all pass
    Evidence: .sisyphus/evidence/task-7-building-tests.txt
  
  Scenario: Build system compiles with camera integration
    Tool: Bash
    Steps:
      1. Run `cargo build`
    Expected Result: No errors in building module
    Evidence: .sisyphus/evidence/task-7-build.txt
  

  Commit: YES

  • Message: feat(building): placement system with validation, preview, demolish, and floor toggle
  • Files: src/building/
  • Pre-commit: cargo test

• 8. Passenger Data Types + Needs System

  What to do:

  • Define passenger types in src/passenger/:
    • Passenger component: id, needs (Vec), current_need_index, state, happiness, position, floor
    • PassengerState enum: Spawning, MovingTo(target), AtFacility(facility_type, timer), Satisfied, Complaining(reason), Despawning
    • PassengerNeed enum: BuyTicket, BuySnack, UseRestroom, BoardTrain
    • Happiness struct: value (0.0-100.0), complaint_threshold (30.0), complaint_fired (bool)
  • Implement needs generation:
    • generate_needs(rng) → Vec<PassengerNeed>: random 0-3 needs from pool
    • Always append BoardTrain as the final need (every passenger needs to reach platform)
    • BoardTrain maps to Platform facility type
  • Implement happiness model:
    • Starts at 100.0
    • Decreases per tick while waiting (not moving): -0.5/tick
    • Decreases when need cannot be resolved (no matching facility): -1.0/tick
    • When happiness < complaint_threshold: fires complaint event once
    • Complaint deducts money from score (flat amount, e.g., -$50)
  • Write unit tests:
    • Needs generation produces 0-3 needs + BoardTrain
    • Happiness decreases correctly
    • Complaint fires exactly once at threshold
    • Complaint applies correct money penalty

  Must NOT do:

  • Don't implement pathfinding/movement logic (Wave 3)
  • Don't implement visual representation

  Recommended Agent Profile:

  • Category: unspecified-high
    • Reason: Game logic design with state machine, needs careful thought on edge cases
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES
  • Parallel Group: Wave 2 (with Tasks 5, 6, 7, 9)
  • Blocks: Tasks 10, 11
  • Blocked By: Task 2

  References: Pattern References:

  • Kilowatt Tycoon src/components/driver.rs — Driver component with patience/state model, similar pattern to passenger happiness

  WHY Each Reference Matters:

  • Shows production pattern for entity state machines in Bevy ECS with happiness/patience mechanics

  Acceptance Criteria:

  • Passenger component with all fields defined
  • PassengerState enum covers all states
  • Needs generation always includes BoardTrain as final need
  • Happiness model is deterministic with seeded RNG
  • Complaint fires exactly once per passenger at threshold
  • cargo test passenger passes all tests

  QA Scenarios:

  Scenario: Passenger needs generation tests
    Tool: Bash
    Steps:
      1. Run `cargo test passenger::needs`
    Expected Result: All needs generation tests pass, BoardTrain always last
    Evidence: .sisyphus/evidence/task-8-needs-tests.txt
  
  Scenario: Happiness and complaint tests
    Tool: Bash
    Steps:
      1. Run `cargo test passenger::happiness`
    Expected Result: Happiness decreases correctly, complaint fires exactly once
    Evidence: .sisyphus/evidence/task-8-happiness-tests.txt
  

  Commit: YES

  • Message: feat(passenger): passenger types, needs system, and happiness model
  • Files: src/passenger/
  • Pre-commit: cargo test

• 9. UI Framework — Toolbar + HUD + Mode Indicator

  What to do:

  • Implement game UI in src/ui/:
    • Bottom Toolbar: Grid of buttons for each facility type (8 buttons: 4 large + 2 medium + 2 small)
    • Each button shows facility name, cost, size (e.g., "Platform $5000 3x2")
    • Selected facility highlighted in toolbar
    • Top HUD: Display current mode (Build/Simulate), current floor (B1/1F), total cost so far
    • Mode indicator: Clear visual distinction between Build mode and Simulate mode
    • Floor toggle button: Switch between B1 and 1F in Build mode
    • Simulate controls: Play/Pause/Speed buttons (visible in Simulate mode)
    • Demolish button: Toggle demolish mode
  • Use Bevy's native UI system (Node, Text, Button components)
  • Style with placeholder colors (no fancy art)

  Must NOT do:

  • Don't implement scoring UI (Wave 4)
  • Don't add animations or polish
  • Don't use egui or external UI crate — Bevy native UI only

  Recommended Agent Profile:

  • Category: visual-engineering
    • Reason: UI layout and styling work
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES
  • Parallel Group: Wave 2 (with Tasks 5, 6, 7, 8)
  • Blocks: Tasks 13, 15
  • Blocked By: Task 3

  References: External References:

  • Bevy UI system: https://docs.rs/bevy/latest/bevy/ui/ — Node, Text, Button components with flexbox layout

  WHY Each Reference Matters:

  • Bevy UI uses flexbox layout — need to understand Node properties for toolbar layout

  Acceptance Criteria:

  • Toolbar displays 8 facility buttons with name + cost
  • Clicking a button selects that facility type
  • HUD shows current mode and floor
  • Floor toggle button works
  • Demolish button toggles demolish mode
  • Simulate controls visible only in Simulate mode
  • cargo build succeeds with UI module

  QA Scenarios:

  Scenario: UI module builds correctly
    Tool: Bash
    Steps:
      1. Run `cargo build`
    Expected Result: No errors in UI module
    Evidence: .sisyphus/evidence/task-9-ui-build.txt
  

  Commit: YES

  • Message: feat(ui): toolbar, HUD, mode indicator, and simulate controls
  • Files: src/ui/
  • Pre-commit: cargo build

• 10. Passenger AI — Spawn, Pathfind, Fulfill Needs

  What to do:

  • Implement passenger AI systems in src/passenger/:
    • Spawn system: At fixed intervals (per PassengerConfig.spawn_rate), spawn passenger at Entrance entity position with random 0-3 needs + BoardTrain
    • Pathfind system: Each tick, passengers in Spawning state calculate path to next need's target facility via NavGraph::find_path()
    • Movement system: Move passengers along their calculated path, one tile per tick (discrete movement)
    • Facility interaction: When passenger reaches target facility, enter AtFacility state with a timer (e.g., 3 ticks for BuyTicket, 5 ticks for BuySnack)
    • Need progression: After facility timer completes, advance to next need, re-pathfind
    • Completion: After all needs fulfilled (including BoardTrain), passenger despawns at Platform
    • Happiness update: Decrease happiness while waiting (not moving). If happiness < threshold, fire complaint event
  • Use seeded RNG resource for deterministic passenger generation (testability)
  • System ordering: Spawn → Pathfind → Move → Interact → Happiness → Despawn (chain)

  Must NOT do:

  • Don't add visual sprites (Wave 3, Task 13)
  • Don't optimize pathfinding (recalculate only when needed)
  • Don't implement crowd avoidance

  Recommended Agent Profile:

  • Category: deep
    • Reason: Core gameplay system with state machine, pathfinding integration, multiple interacting systems
  • Skills: []

  Parallelization:

  • Can Run In Parallel: NO (depends on pathfinding being done)
  • Parallel Group: Wave 3 (with Tasks 11, 12, 13 — but this is the critical path)
  • Blocks: Tasks 14, 17
  • Blocked By: Tasks 6, 8

  References: Pattern References:

  • Task 6 NavGraph API — find_path(), need resolution methods
  • Task 8 Passenger component — state machine, needs, happiness
  • Kilowatt Tycoon src/systems/driver_spawn.rs — Entity spawn + state initialization pattern

  WHY Each Reference Matters:

  • Must use exact NavGraph API from Task 6 for pathfinding calls
  • Must use exact Passenger component from Task 8 for state transitions

  Acceptance Criteria:

  • Passengers spawn at entrance positions at configured rate
  • Passengers pathfind to first need target, then next, then platform
  • Passengers interact with facilities (timer-based)
  • Happiness decreases while waiting
  • Complaint events fire when happiness drops below threshold
  • Passengers despawn after reaching platform
  • cargo test passenger::ai passes (deterministic test with seeded RNG)

  QA Scenarios:

  Scenario: Passenger full lifecycle test
    Tool: Bash
    Steps:
      1. Run `cargo test passenger::ai::lifecycle`
    Expected Result: Test spawns passenger, verifies pathfind→move→interact→despawn cycle
    Evidence: .sisyphus/evidence/task-10-lifecycle-test.txt
  
  Scenario: Deterministic simulation test
    Tool: Bash
    Steps:
      1. Run `cargo test passenger::ai::deterministic`
    Expected Result: Same seed produces identical passenger behavior across runs
    Evidence: .sisyphus/evidence/task-10-deterministic-test.txt
  

  Commit: YES

  • Message: feat(ai): passenger AI with spawn, pathfind, needs fulfillment, and happiness
  • Files: src/passenger/
  • Pre-commit: cargo test

• 11. Simulation Controller — Play/Pause/Speed

  What to do:

  • Implement simulation controller in src/simulation/:
    • SimulationState resource: speed: SimulationSpeed, elapsed_ticks: u32, max_ticks: u32, active: bool
    • SimulationSpeed enum: Paused, Normal(1x), Fast(2x), UltraFast(4x)
    • Systems gated by run_if(in_state(GameMode::Simulating)) — only run passenger AI in Simulate mode
    • tick_simulation system: advance simulation clock, drive passenger AI systems
    • At faster speeds, run multiple simulation ticks per frame
    • End condition: elapsed_ticks >= max_ticks OR all passengers despawned → transition to scoring
  • Implement mode transition:
    • Build → Simulate: Freeze editing, start spawning passengers, rebuild nav graph
    • Simulate → Build: Despawn all passengers, reset simulation state, allow editing
  • Write headless Bevy test: create minimal world, toggle mode, verify sim systems only advance in Simulate mode

  Must NOT do:

  • Don't implement save states
  • Don't add simulation rewind

  Recommended Agent Profile:

  • Category: unspecified-high
    • Reason: System integration with Bevy state management
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES (with Tasks 10, 12, 13)
  • Parallel Group: Wave 3
  • Blocks: Tasks 14, 16
  • Blocked By: Task 8

  References: External References:

  • Bevy States: https://docs.rs/bevy/latest/bevy/prelude/trait.States.html — run_if(in_state(...)) pattern

  Acceptance Criteria:

  • Simulation only advances in Simulate mode
  • Speed controls work (Paused, Normal, Fast, UltraFast)
  • Simulation ends at max_ticks or when all passengers despawned
  • Mode transition works: Build→Simulate and Simulate→Build
  • Passengers despawned when returning to Build mode
  • Headless mode-switch test passes

  QA Scenarios:

  Scenario: Headless mode-switch test
    Tool: Bash
    Steps:
      1. Run `cargo test simulation::mode_switch`
    Expected Result: Simulation systems only advance in Simulate mode, not in Build mode
    Evidence: .sisyphus/evidence/task-11-mode-switch.txt
  

  Commit: YES

  • Message: feat(sim): simulation controller with speed controls and mode transitions
  • Files: src/simulation/
  • Pre-commit: cargo test

• 12. Demolish + Floor Toggle System

  What to do:

  • Enhance building system from Task 7 with demolish UX:
    • Demolish mode: toggle via toolbar button or keyboard shortcut (D key)
    • In demolish mode, hover over placed facility → highlight in red
    • Click to remove facility, update grid state, recalculate total cost
    • Refund 50% of facility cost on demolish
  • Floor toggle:
    • Button or keyboard shortcut (PageUp/PageDown or F1/F2) to switch active floor
    • Visual feedback: current floor displayed in HUD, non-active floor tiles dimmed
    • Placement only works on active floor
  • Rebuild nav graph after demolish (trigger nav graph rebuild event)

  Must NOT do:

  • Don't implement undo history (just demolish + rebuild)
  • Don't implement copy/paste

  Recommended Agent Profile:

  • Category: quick
    • Reason: Extending existing building system with toggle functionality
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES
  • Parallel Group: Wave 3 (with Tasks 10, 11, 13)
  • Blocks: Task 17
  • Blocked By: Task 7

  Acceptance Criteria:

  • Demolish mode toggle works
  • Clicking placed facility in demolish mode removes it
  • 50% cost refund applied
  • Floor toggle switches active floor
  • Nav graph rebuilds after demolish

  QA Scenarios:

  Scenario: Demolish and refund tests
    Tool: Bash
    Steps:
      1. Run `cargo test building::demolish`
    Expected Result: Demolish removes facility, refunds 50%, grid state correct
    Evidence: .sisyphus/evidence/task-12-demolish-test.txt
  

  Commit: YES

  • Message: feat(building): demolish mode with refund and floor toggle
  • Files: src/building/
  • Pre-commit: cargo test

• 13. Prefab Visual Rendering — Placeholder Geometry

  What to do:

  • Implement placeholder rendering in src/rendering/:
    • Each facility type gets a distinct colored rectangle/shape on the isometric grid
    • Large prefabs: Larger colored shapes (Platform=blue rectangle, Hall=grey, Entrance=green, Shop=orange)
    • Medium prefabs: Tall narrow shapes (Elevator=purple, Escalator=yellow)
    • Small prefabs: Small squares (TicketMachine=cyan, VendingMachine=red)
    • Railway: Brown/dark line through the level
    • Restricted areas: Dark grey with X pattern
    • Buildable empty: Light grey diamond tiles
  • Z-ordering: Use Y-sort for isometric depth — entities further from camera render behind
  • Floor visualization: B1 floor tiles slightly transparent, 1F tiles fully opaque
  • Facility preview (from Task 7): Render ghost shape with transparency
  • Passenger visualization: Small colored dots moving on the grid (different color per state)

  Must NOT do:

  • Don't create actual sprite assets
  • Don't add shadows, lighting, or post-processing
  • Don't implement animation

  Recommended Agent Profile:

  • Category: visual-engineering
    • Reason: Visual rendering and z-ordering work
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES
  • Parallel Group: Wave 3 (with Tasks 10, 11, 12)
  • Blocks: Task 17
  • Blocked By: Tasks 5, 7, 9

  Acceptance Criteria:

  • Each facility type has distinct colored shape
  • Isometric Z-ordering correct (entities behind rendered first)
  • B1 floor visible but distinct from 1F
  • Railway visible as a line through the level
  • Passengers visible as small dots moving on grid
  • cargo build succeeds

  QA Scenarios:

  Scenario: Rendering module builds
    Tool: Bash
    Steps:
      1. Run `cargo build`
    Expected Result: No errors in rendering module
    Evidence: .sisyphus/evidence/task-13-render-build.txt
  

  Commit: YES

  • Message: feat(visuals): placeholder geometry rendering with z-sorting
  • Files: src/rendering/
  • Pre-commit: cargo build

• 14. Scoring System — Cost/Time/Space Calculation

  What to do:

  • Implement scoring engine in src/scoring/:
    • Score struct: cost: f32, avg_transit_time: f32, footprint: u32
    • ScoreCalculator:
      • Cost: Sum of all placed facility costs (minus demolish refunds)
      • Time: Average ticks from passenger spawn to despawn across all passengers
      • Space: Total grid tiles occupied by facility footprints
    • HistogramData struct: For each metric, store bins of score distribution (use placeholder data for MVP — e.g., 100 simulated "other player" scores)
    • calculate_percentile(score, histogram) → f32: Where player's score falls in distribution
  • Generate histogram: Create plausible distribution of scores (normal distribution around a mean for each metric)
  • Write unit tests:
    • Score calculation with known facility layout → exact expected scores
    • Percentile calculation with known distribution
    • Edge cases: 0 passengers, all passengers complained, minimum possible score

  Must NOT do:

  • Don't implement online leaderboard
  • Don't use real player data — generate placeholder histogram data

  Recommended Agent Profile:

  • Category: deep
    • Reason: Mathematical scoring logic requiring precise calculation and testing
  • Skills: []

  Parallelization:

  • Can Run In Parallel: NO (needs passenger results)
  • Parallel Group: Wave 4
  • Blocks: Tasks 15, 16
  • Blocked By: Tasks 7, 10, 11

  Acceptance Criteria:

  • Score calculation produces correct Cost/Time/Space values
  • Histogram data generated with plausible distribution
  • Percentile calculation correct
  • Golden test: fixed layout → exact expected scores
  • cargo test scoring passes all tests

  QA Scenarios:

  Scenario: Scoring golden tests
    Tool: Bash
    Steps:
      1. Run `cargo test scoring::golden`
    Expected Result: Known layout produces exact expected (Cost, Time, Space) scores
    Evidence: .sisyphus/evidence/task-14-scoring-tests.txt
  

  Commit: YES

  • Message: feat(scoring): Cost/Time/Space calculation with histogram and percentile
  • Files: src/scoring/
  • Pre-commit: cargo test

• 15. Scoring UI — Histogram Display + Results Screen

  What to do:

  • Implement scoring screen in src/ui/:
    • Full-screen overlay that appears when simulation ends
    • Display 3 histograms (one per metric: Cost, Time, Space)
    • Each histogram shows: player's score position, percentile, and bar distribution
    • "PASS" or "FAIL" indicator (pass = path exists from entrance to platform)
    • Total complaints and money deducted
    • "Back to Build" button to return and optimize
    • Simple bar chart rendering using Bevy UI nodes (colored rectangles for bins)

  Must NOT do:

  • Don't implement fancy chart animations
  • Don't add comparison with friends (use static histogram data)

  Recommended Agent Profile:

  • Category: visual-engineering
    • Reason: UI layout and data visualization
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES (with Tasks 14, 16)
  • Parallel Group: Wave 4
  • Blocks: None
  • Blocked By: Tasks 9, 14

  Acceptance Criteria:

  • Scoring screen displays after simulation ends
  • 3 histograms visible with player's position marked
  • Pass/Fail indicator shown
  • "Back to Build" button returns to build mode
  • cargo build succeeds

  QA Scenarios:

  Scenario: Scoring UI builds
    Tool: Bash
    Steps:
      1. Run `cargo build`
    Expected Result: No errors in scoring UI
    Evidence: .sisyphus/evidence/task-15-score-ui-build.txt
  

  Commit: YES

  • Message: feat(scoring-ui): histogram display and results screen
  • Files: src/ui/
  • Pre-commit: cargo build

• 16. Game State Machine — Build ↔ Simulate Transitions

  What to do:

  • Implement game state machine in src/state/:
    • Use Bevy States: GameState enum: Menu, Building, Simulating, Scoring
    • Building state: building placement systems active, simulation frozen, toolbar visible
    • Simulating state: passenger AI systems active, building frozen, sim controls visible
    • Scoring state: scoring screen displayed, everything else paused
    • Transitions: Building → Simulating (play button), Simulating → Scoring (auto on completion), Scoring → Building (back button)
    • On entering Simulating: rebuild nav graph from current facilities, reset simulation state, spawn passengers
    • On entering Building: despawn all passengers, restore build state
  • System scheduling: Use run_if(in_state(GameState::X)) for all game systems
  • Write headless integration test: verify state transitions work, correct systems active in each state

  Must NOT do:

  • Don't implement menu state content (just stub it)
  • Don't add save/load transitions

  Recommended Agent Profile:

  • Category: unspecified-high
    • Reason: System integration wiring with Bevy state management
  • Skills: []

  Parallelization:

  • Can Run In Parallel: YES (with Tasks 14, 15)
  • Parallel Group: Wave 4
  • Blocks: Task 17
  • Blocked By: Tasks 11, 14

  Acceptance Criteria:

  • State transitions work: Building → Simulating → Scoring → Building
  • Correct systems active in each state
  • Passengers cleaned up on Build re-entry
  • Nav graph rebuilt on Simulate entry
  • Headless state machine test passes

  QA Scenarios:

  Scenario: State machine integration test
    Tool: Bash
    Steps:
      1. Run `cargo test state::transitions`
    Expected Result: All state transitions work, correct systems active per state
    Evidence: .sisyphus/evidence/task-16-state-tests.txt
  

  Commit: YES

  • Message: feat(state): game state machine with Build/Simulate/Score transitions
  • Files: src/state/, src/main.rs (updated system registration)
  • Pre-commit: cargo test

• 17. Tutorial Level Assembly + Gameplay Integration Test

  What to do:

  • Assemble the complete tutorial level in src/level/:
    • Wire all systems together in main App
    • Load tutorial level data on startup
    • Verify full gameplay loop: Build → Simulate → Score → Back to Build
    • Ensure passenger AI, pathfinding, scoring all work together
    • Verify tutorial level is solvable (player can build a working station)
    • Add initial camera position for good overview of tutorial level
  • Integration testing:
    • Run a complete simulation with a pre-built station layout
    • Verify passengers complete their journeys
    • Verify scoring produces reasonable numbers
    • Verify no panics or errors in full gameplay loop
  • Polish placeholder visuals for readability:
    • Ensure facility colors are distinct and recognizable
    • Ensure grid lines are visible
    • Ensure passenger dots are visible against background

  Must NOT do:

  • Don't balance the level (that's post-MVP design work)
  • Don't add tutorial text or guidance
  • Don't add sound

  Recommended Agent Profile:

  • Category: deep
    • Reason: Full system integration, debugging cross-system issues
  • Skills: []

  Parallelization:

  • Can Run In Parallel: NO (depends on all other tasks)
  • Parallel Group: Wave 4 (last task)
  • Blocks: FINAL
  • Blocked By: Tasks 10, 12, 13, 16

  References: Pattern References:

  • All previous tasks — this task wires everything together

  Acceptance Criteria:

  • cargo run launches game with tutorial level
  • Player can place facilities and see them on the grid
  • Player can switch to Simulate and see passengers moving
  • Simulation ends and shows scoring screen
  • Player can return to Build mode and modify station
  • No panics in full gameplay loop
  • cargo test passes all tests
  • cargo build succeeds with no warnings

  QA Scenarios:

  Scenario: Full gameplay loop integration test
    Tool: Bash
    Steps:
      1. Run `cargo test integration::full_loop`
    Expected Result: Pre-built station → simulate → passengers arrive → score calculated
    Evidence: .sisyphus/evidence/task-17-integration.txt
  
  Scenario: Game builds and runs
    Tool: interactive_bash (tmux)
    Steps:
      1. Launch `cargo run` in tmux
      2. Wait 5 seconds for window to open
      3. Check for panic/error messages in output
    Expected Result: Game runs without panics, shows isometric grid
    Failure Indicators: Panic messages, compilation errors
    Evidence: .sisyphus/evidence/task-17-game-run.txt
  

  Commit: YES

  • Message: feat(tutorial): tutorial level assembly and full gameplay integration
  • Files: src/level/, src/main.rs
  • Pre-commit: cargo test && cargo build

---

Final Verification Wave (MANDATORY — after ALL implementation tasks)

4 review agents run in PARALLEL. ALL must APPROVE. Present consolidated results to user and get explicit "okay" before completing.

• F1. Plan Compliance Audit — oracle Read the plan end-to-end. For each "Must Have": verify implementation exists (read file, run command). For each "Must NOT Have": search codebase for forbidden patterns — reject with file:line if found. Check evidence files exist in .sisyphus/evidence/. Compare deliverables against plan. Output: Must Have [N/N] | Must NOT Have [N/N] | Tasks [N/N] | VERDICT: APPROVE/REJECT

• F2. Code Quality Review — unspecified-high Run cargo build + cargo clippy + cargo test. Review all changed files for: unwrap() in non-test code, empty error handling, println! in production, commented-out code, unused imports. Check AI slop: excessive comments, over-abstraction, generic names (data/result/item/temp). Verify Bevy plugin organization is clean. Output: Build [PASS/FAIL] | Clippy [PASS/FAIL] | Tests [N pass/N fail] | Files [N clean/N issues] | VERDICT

• F3. Real Manual QA — unspecified-high Launch game via tmux. Execute full gameplay loop: place floor tiles → place entrance → place hall → place ticket machines → place gates → place platform → connect to railway → switch to simulate → observe passengers → check scoring screen. Verify all interactions work. Save screenshots. Output: Scenarios [N/N pass] | Integration [N/N] | VERDICT

• F4. Scope Fidelity Check — deep For each task: read "What to do", read actual diff. Verify 1:1 — everything in spec was built, nothing beyond spec was built. Check "Must NOT do" compliance. Detect cross-task contamination. Flag unaccounted changes. Output: Tasks [N/N compliant] | Contamination [CLEAN/N issues] | Unaccounted [CLEAN/N files] | VERDICT

---

Commit Strategy

• Wave 1: feat(scaffold): initialize Bevy project with dependencies — Cargo.toml, src/main.rs
• Wave 1: feat(types): core grid, facility, and game state types — src/types/
• Wave 1: feat(camera): isometric diamond camera setup — src/camera/
• Wave 1: feat(level): level definition format and tutorial data — src/level/
• Wave 2: feat(grid): isometric grid rendering with tile types — src/grid/
• Wave 2: feat(pathfinding): A* pathfinding on floor tiles — src/pathfinding/
• Wave 2: feat(building): placement system for prefabs and floor tiles — src/building/
• Wave 2: feat(passenger): passenger types and needs system — src/passenger/
• Wave 2: feat(ui): toolbar, HUD, and mode indicator — src/ui/
• Wave 3: feat(ai): passenger AI with spawn, pathfind, fulfill needs — src/passenger/
• Wave 3: feat(sim): simulation controller with speed controls — src/simulation/
• Wave 3: feat(demolish): undo and demolish system — src/building/
• Wave 3: feat(visuals): placeholder geometry rendering — src/rendering/
• Wave 4: feat(scoring): cost/time/space calculation engine — src/scoring/
• Wave 4: feat(scoring-ui): histogram display and results screen — src/ui/
• Wave 4: feat(state): build/simulate state machine — src/state/
• Wave 4: feat(tutorial): tutorial level assembly and integration — src/level/

---

Success Criteria

Verification Commands

cargo build                    # Expected: Compiles without errors
cargo test                     # Expected: All unit tests pass
cargo clippy                   # Expected: No warnings
cargo run                      # Expected: Game window opens with tutorial level

Final Checklist

• All "Must Have" features implemented
• All "Must NOT Have" items absent from codebase
• All unit tests pass
• Game launches and tutorial level is playable
• Build → Simulate → Score loop works end-to-end
• Passenger AI pathfinds correctly through station
• 3-axis scoring displays with values