marathon/docs/agent-simulation-breakdown.md

Agent Simulation Framework - Task Breakdown

Epic: Agent Simulation Framework (#5) Overall Size: XXXL (165 points across 12 phases) Priority: P0 (Critical - core differentiator for Marathon)

This document breaks down the 12 layers of the agent simulation framework into specific, sized tasks for prioritization and scheduling.

Philosophy: Generic composition over special cases. Emergence over authorship. Consequences without failure. Existence is cheap; cognition is expensive.

Approach: Incremental implementation. Each layer should be validated in isolation before adding the next. Start with foundation, add one layer at a time, continuously test performance and emergent behavior.

---

Phase 1: Foundation (Entity Composition)

Phase Goal: Implement entity composition system with core component categories Phase Size: 16 points Dependencies: Bevy ECS Risk: Low (building on solid ECS foundation)

Tasks

#	Task	Size	Points	Rationale	Priority
1.1	Define entity component categories and marker traits	S	2	Create type hierarchy for components (Lifecycle, PhysicalPresence, Needs, etc.)	P0
1.2	Implement Lifecycle state machine for all entity types	M	4	States: Unborn → Infant → Child → Adolescent → Adult → Elder → Deceased	P0
1.3	Implement PhysicalPresence component with position and movement	M	4	Position, velocity, pathfinding integration, spatial indexing	P0
1.4	Implement Needs system (biological and psychological drives)	M	4	Hunger, thirst, sleep, social, safety needs with decay and satisfaction	P0
1.5	Implement Instincts system (species-typical behaviors)	S	2	Basic instincts (flee danger, seek food, seek shelter)	P0

Phase 1 Total: 16 points

Lean Analysis

• Eliminate Waste: Can we use existing ECS patterns? YES - leverage Bevy's component model
• Amplify Learning: What will we learn? How to compose complex entities from simple components
• Deliver Fast: Can we implement incrementally? YES - add components one at a time
• Build Quality In: Risk of component coupling? YES - enforce clean boundaries between categories

Phase 1 Recommendations

1. Start with marker traits - define component categories clearly
2. Validate Lifecycle separately - ensure state machine is solid before adding other components
3. Test composition patterns - verify entities can have any combination of components

---

Phase 2: Life Arc System

Phase Goal: Implement life arc state machines and autonomy gradient Phase Size: 12 points Dependencies: Phase 1 complete Risk: Medium (complex state transitions, schedule authority handoff)

Tasks

#	Task	Size	Points	Rationale	Priority
2.1	Implement life arc state machines (Child → Adult → Elder)	L	8	Major state transitions with capability changes and schedule authority shifts	P0
2.2	Implement autonomy gradient (None → Partial → Full)	S	2	Track who controls entity schedule (parent, self, institution)	P0
2.3	Implement life arc transition triggers	S	2	Age-based, event-based, and condition-based transitions	P1

Phase 2 Total: 12 points

Lean Analysis

• Eliminate Waste: Can we hardcode ages? NO - emergent transitions are key to feeling alive
• Amplify Learning: What will we learn? How autonomy affects entity behavior
• Deliver Fast: Can we implement incrementally? YES - start with simple age transitions
• Build Quality In: Risk of broken transitions? YES - comprehensive state transition testing

Phase 2 Recommendations

1. Start with simple age-based transitions - Child(0-12) → Adolescent(13-17) → Adult(18+)
2. Test authority handoff carefully - ensure schedule control transfers correctly
3. Validate edge cases - what happens when parent dies while child is dependent?

---

Phase 3: Schedule System

Phase Goal: Implement daily schedule generation from roles and personality Phase Size: 14 points Dependencies: Phase 2 complete Risk: Medium (schedule conflicts, authority model complexity)

Tasks

#	Task	Size	Points	Rationale	Priority
3.1	Implement daily schedule generation from roles	M	4	Generate time blocks (work, sleep, leisure) based on role and personality	P0
3.2	Implement schedule authority model (autonomous, external, partial)	M	4	Track who can modify entity schedule (self, parent, employer)	P0
3.3	Implement shared commitments between related entities	M	4	Couples, families, work teams share schedule blocks	P1
3.4	Implement schedule regeneration on condition changes	S	2	Rebuild schedule when sick, pregnant, grieving, etc.	P1

Phase 3 Total: 14 points

Lean Analysis

• Eliminate Waste: Can we use fixed schedules? NO - dynamic schedules enable emergent behavior
• Amplify Learning: What will we learn? How schedule conflicts get resolved
• Deliver Fast: Can we implement incrementally? YES - basic schedules first, then shared commitments
• Build Quality In: Risk of schedule conflicts? YES - need clear resolution rules

Phase 3 Recommendations

1. Start with single-entity schedules - validate basic time blocking works
2. Add authority later - ensure autonomous schedules work before external control
3. Test regeneration - verify schedules adapt to condition changes

---

Phase 4: Behavior Tree System

Phase Goal: Implement behavior tree framework and need-driven prioritization Phase Size: 16 points Dependencies: Phase 3 complete Risk: High (performance critical, complex evaluation logic)

Tasks

#	Task	Size	Points	Rationale	Priority
4.1	Implement behavior tree framework and evaluation engine	L	8	Tree structure, node types (sequence, selector, action), tick evaluation	P0
4.2	Implement activity-specific behavior trees	M	4	Work, Leisure, Social, Maintenance activities with contextual behaviors	P0
4.3	Implement need-driven behavior prioritization	M	4	Urgent needs interrupt schedule, utility-based selection	P0

Phase 4 Total: 16 points

Lean Analysis

• Eliminate Waste: Can we use FSM instead? NO - behavior trees compose better
• Amplify Learning: What will we learn? How needs affect behavior selection
• Deliver Fast: Can we implement incrementally? YES - simple trees first, add complexity
• Build Quality In: Risk of infinite loops? YES - add evaluation limits and cycle detection

Phase 4 Recommendations

1. Start with simple trees - single activity type, no interruption
2. Profile evaluation performance - this is frame-rate critical for nearby entities
3. Test need interruption - verify urgent hunger can interrupt work

---

Phase 5: World Substrate

Phase Goal: Implement substrate layer types and environmental effects Phase Size: 14 points Dependencies: Phase 1 complete (can parallelize with Phases 2-4) Risk: Medium (spatial queries performance, substance simulation)

Tasks

#	Task	Size	Points	Rationale	Priority
5.1	Implement substrate layer types (substances, temperature, light, sound, air quality, contagion)	L	8	Spatial grids or continuous fields for environmental state	P1
5.2	Implement trigger volume system for spatial events	S	2	Zones that affect entities (fire, poison gas, music)	P1
5.3	Implement generic substance transfer and consumption	M	4	Entities consume/produce substances, transfer between locations	P2

Phase 5 Total: 14 points

Lean Analysis

• Eliminate Waste: Can we skip substrate entirely? NO - enables fire, disease, pollution
• Amplify Learning: What will we learn? How spatial state affects entity behavior
• Deliver Fast: Can we implement incrementally? YES - start with simple trigger volumes
• Build Quality In: Risk of performance issues? YES - spatial queries must be efficient

Phase 5 Recommendations

1. Start with trigger volumes - simpler than continuous fields
2. Use spatial indexing - KD-tree or grid for efficient queries
3. Test with 500 entities - verify performance scales

---

Phase 6: Institutions

Phase Goal: Implement institution entity type with coordination blackboard Phase Size: 16 points Dependencies: Phase 3 complete Risk: High (cross-entity coordination, emergent organizational behavior)

Tasks

#	Task	Size	Points	Rationale	Priority
6.1	Implement Institution entity type with Governance, Resources, Reputation	M	4	Special entity type that manages members and shared state	P0
6.2	Implement shared blackboard state for coordination	L	8	Shared memory for work assignments, inventory, schedules	P0
6.3	Implement worker schedule template generation	M	4	Institutions create schedule templates for roles (baker, guard, teacher)	P1

Phase 6 Total: 16 points

Lean Analysis

• Eliminate Waste: Can we hardcode workplace behavior? NO - emergent coordination is key
• Amplify Learning: What will we learn? How entities coordinate without communication
• Deliver Fast: Can we implement incrementally? YES - simple bakery first, then generalize
• Build Quality In: Risk of coordination deadlocks? YES - need clear state machine

Phase 6 Recommendations

1. Start with single institution - bakery with 1 baker, 1 apprentice
2. Validate blackboard pattern - ensure shared state enables coordination
3. Test with multiple institutions - verify they don't interfere

---

Phase 7: Relationships

Phase Goal: Implement relationship state and coordination levels Phase Size: 14 points Dependencies: Phase 3 complete Risk: Medium (relationship evolution, coordination complexity)

Tasks

#	Task	Size	Points	Rationale	Priority
7.1	Implement Relationship state and evolution	M	4	Bond strength, interaction history, sentiment tracking	P1
7.2	Implement bond types (Romantic, Familial, Friendship, Professional, Caretaking)	M	4	Different bond types enable different interactions	P1
7.3	Implement coordination levels (None → AdHoc → Recurring → Cohabiting → Dependent)	M	4	Stronger bonds enable tighter schedule coordination	P1
7.4	Implement relationship effects on all simulation layers	S	2	Relationships affect needs, schedules, behaviors, conditions	P2

Phase 7 Total: 14 points

Lean Analysis

• Eliminate Waste: Can we skip relationships? NO - core to "living village" feel
• Amplify Learning: What will we learn? How bonds enable coordination
• Deliver Fast: Can we implement incrementally? YES - family bonds first, then friends
• Build Quality In: Risk of relationship graph bugs? YES - need clear formation/dissolution rules

Phase 7 Recommendations

1. Start with familial bonds - parent-child relationships are simplest
2. Test coordination levels - verify cohabiting couples share schedules
3. Validate evolution - bonds should strengthen/weaken from interactions

---

Phase 8: Conditions

Phase Goal: Implement condition system with effects on all layers Phase Size: 12 points Dependencies: Phases 1-4 complete Risk: Medium (condition interactions, contagion simulation)

Tasks

#	Task	Size	Points	Rationale	Priority
8.1	Implement Condition system with severity and duration	M	4	Temporary states (sick, pregnant, grieving, drunk)	P1
8.2	Implement condition effects (need modifiers, capability modifiers, schedule overrides, behavior modifiers)	M	4	Conditions affect all simulation layers	P1
8.3	Implement contagion system for spreading conditions	M	4	Diseases spread through proximity and substrate	P2

Phase 8 Total: 12 points

Lean Analysis

• Eliminate Waste: Can we hardcode illness? NO - generic conditions enable emergent drama
• Amplify Learning: What will we learn? How conditions cascade through simulation
• Deliver Fast: Can we implement incrementally? YES - simple illness first, then contagion
• Build Quality In: Risk of runaway epidemics? YES - need disease progression model

Phase 8 Recommendations

1. Start with non-contagious conditions - pregnancy, grief, intoxication
2. Add simple illness - validate need modifiers and schedule overrides work
3. Test contagion carefully - ensure diseases don't wipe out entire village

---

Phase 9: Tools & Capabilities

Phase Goal: Implement capability types and tool operator modes Phase Size: 12 points Dependencies: Phase 1 complete Risk: Medium (capability composition, tool quality effects)

Tasks

#	Task	Size	Points	Rationale	Priority
9.1	Implement capability types (Movement, Communication, Transformation, Force, Storage)	M	4	Abstract capabilities that entities and tools provide	P1
9.2	Implement tool operator modes (Inhabit, Wield, Station, Wear)	M	4	Different ways entities use tools (house, hammer, oven, clothes)	P1
9.3	Implement tools as institutional resources	S	2	Bakery owns ovens, blacksmith owns anvils	P2
9.4	Implement tool quality affecting output	S	2	Better tools produce better results	P2

Phase 9 Total: 12 points

Lean Analysis

• Eliminate Waste: Can we skip tools? NO - needed for production workflows
• Amplify Learning: What will we learn? How capabilities compose
• Deliver Fast: Can we implement incrementally? YES - simple wielded tools first
• Build Quality In: Risk of capability conflicts? YES - need clear capability stacking rules

Phase 9 Recommendations

1. Start with wielded tools - hammer, axe, hoe
2. Add stations - ovens, forges, looms require entity presence
3. Test quality modifiers - verify master blacksmith + good anvil = quality sword

---

Phase 10: Production Workflows

Phase Goal: Implement batch entity system for multi-step processes Phase Size: 14 points Dependencies: Phase 9 complete Risk: High (workflow state persistence, interruption handling)

Tasks

#	Task	Size	Points	Rationale	Priority
10.1	Implement batch entity system for multi-step processes	L	8	Bread batch progresses: mix → knead → proof → bake → cool	P1
10.2	Implement recipe and phase system	M	4	Recipes define inputs, phases, outputs, time/skill requirements	P1
10.3	Implement interruptible work with state persistence	S	2	Baker can pause kneading to serve customer, resume later	P2

Phase 10 Total: 14 points

Lean Analysis

• Eliminate Waste: Can we use instant crafting? NO - multi-step processes enable depth
• Amplify Learning: What will we learn? How to persist complex workflow state
• Deliver Fast: Can we implement incrementally? YES - simple 1-phase recipes first
• Build Quality In: Risk of lost state on interruption? YES - need save/restore

Phase 10 Recommendations

1. Start with simple recipes - bread (mix → bake), no interruption
2. Add multi-phase - validate state transitions work
3. Test interruption - ensure baker can resume kneading after break

---

Phase 11: Performance Architecture

Phase Goal: Implement simulation tier system and discrete event simulation Phase Size: 15 points Dependencies: Phase 4 complete Risk: Critical (performance determines feasibility of 500 entities)

Tasks

#	Task	Size	Points	Rationale	Priority
11.1	Implement simulation tier system (Attached, Nearby, Background, Wildlife)	L	8	Different update strategies for different proximity levels	P0
11.2	Implement tier promotion/demotion based on player proximity	M	4	Seamless transitions as players move through world	P0
11.3	Implement discrete event simulation and wake queue	S	3	Background entities only update when something changes	P1

Phase 11 Total: 15 points

Lean Analysis

• Eliminate Waste: Can we update all entities every frame? NO - exceeds iPad budget
• Amplify Learning: What will we learn? How to scale simulation efficiently
• Deliver Fast: Can we implement incrementally? YES - simple tier system first
• Build Quality In: Risk of visible tier transitions? YES - need smooth fade

Phase 11 Recommendations

1. Profile early and often - this determines if 500 entities is feasible
2. Start with 2 tiers - nearby (full), background (interpolated)
3. Add wake queue - discrete events are key to efficient background simulation
4. Test on iPad - don't optimize for desktop and hope it works

---

Phase 12: Networking & Sync

Phase Goal: Implement CRDT-based synchronization and entity ownership Phase Size: 16 points Dependencies: All previous phases complete Risk: Critical (desyncs break multiplayer experience)

Tasks

#	Task	Size	Points	Rationale	Priority
12.1	Implement CRDT-based state synchronization for slow-changing layers	L	8	Life arcs, schedules, relationships use CRDTs for eventual consistency	P0
12.2	Implement behavior tree outcome synchronization	M	4	Fast-changing behavior trees sync outcomes, not state	P0
12.3	Implement entity ownership model	S	2	Entities owned by nearest player, ownership transfers on proximity	P0
12.4	Implement spatial ownership for substrate	S	2	World divided into chunks, each owned by one peer	P1

Phase 12 Total: 16 points

Lean Analysis

• Eliminate Waste: Can we use lockstep sync? NO - too slow for 500 entities
• Amplify Learning: What will we learn? How to sync without desyncs
• Deliver Fast: Can we implement incrementally? YES - basic ownership first
• Build Quality In: Risk of desyncs? YES - extensive multiplayer testing required

Phase 12 Recommendations

1. Start with entity ownership - simplest sync model
2. Add CRDT sync for schedules - slow-changing state is easier
3. Test with 2 peers first - validate before scaling to 4
4. Add reconciliation - handle ownership conflicts gracefully
5. Stress test with 500 entities - verify no desyncs in 1-hour sessions

---

Overall WSJF Analysis

Using Cost of Delay / Duration to prioritize phases:

Phase	Size	Business Value	Time Criticality	Risk Reduction	CoD	WSJF
Phase 1	16	8/10	9/10	9/10	26	1.63
Phase 2	12	7/10	8/10	8/10	23	1.92
Phase 3	14	8/10	8/10	7/10	23	1.64
Phase 4	16	9/10	9/10	9/10	27	1.69
Phase 11	15	10/10	10/10	10/10	30	2.00
Phase 12	16	10/10	10/10	10/10	30	1.88

Recommendation: Implement in order 1 → 2 → 3 → 4 → 11 (critical path for viability), then parallelize remaining layers.

Success Metrics

Performance Targets

• 500 entities simulated simultaneously
• 60 FPS on iPad Pro with full simulation load
• Background entities consume <5% of frame budget
• Tier transitions are visually seamless

Multiplayer Targets

• 2-4 peers supported
• <100ms sync latency for state propagation
• Zero desyncs in 1-hour multiplayer sessions
• Ownership transitions are seamless

Emergence Targets

• Entities follow believable daily routines without hand-authoring
• Relationships form and evolve through interaction
• Institutions coordinate workers without explicit communication
• Unexpected behaviors emerge from generic rule interactions

Implementation Notes

1. Incremental Development: Each phase should be fully validated before moving to the next
2. Performance First: Profile on iPad hardware from Phase 1 onwards
3. Test Emergent Behavior: Create test scenarios that exercise rule interactions
4. Document Invariants: Clear rules for how systems interact prevents bugs
5. Content Light: Focus on generic rules that recombine, not hand-authored content
6. Multiplayer Always: Test sync from Phase 1, don't bolt on later

Total Breakdown

• Total Points: 165
• Total Phases: 12
• Critical Path: Phases 1, 2, 3, 4, 11, 12 (89 points)
• Parallel Work: Phases 5-10 can be done alongside or after critical path (76 points)