consolidated master plan

Guide for consolidated master plan

Consolidated Master Plan (Agents 3, 4, 5, 6)

Status: Stabilization & Feature Completion Date: 2026-01-10

🏆 Principal Engineering Standards

All agents must adhere to these standards. Violations are considered critical failures.

1. Architectural Integrity

  • Strict File Ownership: Agents MUST NOT edit files outside their assigned domains. If a cross-domain change is needed, create a new interface/event or request a handover.
  • Zero Panic Policy: Usage of .unwrap() or .expect() in runtime systems (especially UI) is FORBIDDEN. Use if let, match, or propagated Results.
  • Modular Design: Avoid circular dependencies. If file size exceeds 300 lines, refactor into sub-modules.

2. Code Quality

  • Zero New Warnings: No new code shall introduce compiler warnings. Existing warnings must be reduced, not increased.
  • Documentation: All public structs, enums, and systems must have doc comments (///).
  • Type Safety: Use Newtypes (e.g., struct PlayerId(Uuid)) instead of primitives (String, u64) for IDs to prevent mixing arguments.

3. Reliability & Performance

  • Test Coverage: Every new logic branch requires a unit test; practice test-driven development.
  • Allocation Mindfulness: Avoid unnecessary .clone() or heap allocations in hot loops/UI update cycles.
  • Ownership: Even if it's not code you've written, if the file you're working on violates these rules, fix the file.

🔒 Domain Ownership Rules

AgentExclusive Directories/FilesShared (Read-Only)
Agent 3src/systems/ui/* (General), src/systems/worldsrc/systems/player
Agent 4src/systems/economy, src/systems/magic, src/systems/combatsrc/systems/data
Agent 5src/systems/editor, src/systems/ai, src/systems/tutorialsrc/systems/map
Agent 6src/systems/network, Global Migration TasksAll Projects (Read-Only)
> Conflict Protocol: If two agents need to edit mod.rs or the same UI file, Agent 3 (Architect) has authority. Others must implement their logic in a new file and ask Agent 3 to hook it up.

🤖 Agent 3: System Stability & UI Polish

Role: Architect & Polisher Domain: src/systems/ui (Excl. Trade/Editor overlays), Core Systems

1. Stability (High Priority)

  • Panic Prevention: Refactor xp_drops.rs, pathing_overlay.rs, milestone_notifications.rs, login.rs, hover_text.rs to remove all unwrap/expect calls.
  • Warning Eradication: Systematically resolve the 700+ warnings in assigned files.

2. UI Polish

  • Visuals: Finalize particle effects in milestone_notifications.rs.
  • Settings: Clean up settings_ui.rs (unused fields).

💰 Agent 4: Economy & Gameplay Systems

Role: Economist & Mechanic Domain: src/systems/economy, src/systems/magic, src/systems/combat

1. Economy System

  • Web Integration: Implement standard REST/Socket integration in src/systems/economy/api.rs.
  • Trade UI: Polish src/systems/economy/ui.rs (Exceptions to Agent 3's UI domain allowed here).

2. Gameplay Mechanics

  • Magic: Implement VFX in src/systems/magic/projectile.rs and collision logic.
  • Combat: Strict type checking for DamageDealtEvent in src/systems/combat.

🛠️ Agent 5: Tools, AI & Content

Role: World Builder Domain: src/systems/editor, src/systems/ai, src/systems/ui/{tile_markers.rs, npc_hover.rs}

1. Editor & Building

  • Snapping: Fix snap_rot in src/systems/editor/input.rs.
  • Undo/Redo: Finalize EditorHistory in src/systems/editor.

2. NPC & AI

  • AI Logic: Clean up NpcType definitions in src/systems/ui/npc_hover.rs.
  • Tutorial: Implement tasks from tutorial_area_todo.md in src/systems/tutorial.

🗳️ Agent 6: Rust & Bevy Migration

Role: Migration Specialist Domain: src/systems/network, Cargo.toml, Global Refactors

1. Bevy 0.17 Migration

  • Event Migration: Complete the Event system migration:
    • Replace add_message with add_event.
    • Replace usage of Message trait with #[derive(Event)].
    • Fix EventWriter::write -> EventWriter::send.
    • Scope: tutorial.rs, network/mod.rs, world/resources.rs, player/skills.rs.

2. Rust Modernization

  • Edition Check: Ensure Cargo.toml is using the latest stable Rust edition (2024 if available/supported, or 2021).
  • Deprecation Fixes: Resolve deprecated API usage across the codebase (collaborate with Agent 3 for UI-specific deprecations).

✅ Validation Checklist

Before marking a task complete:
  1. cargo check passes with 0 errors.
  2. No new warnings introduced.
  3. No overlap with other agents' active files.