Mai/.planning/phases/03-resource-management/03-02-PLAN.md

---
phase: 03-resource-management
plan: 02
type: execute
wave: 1
depends_on: []
files_modified: [src/resource/__init__.py, src/resource/tiers.py, src/config/resource_tiers.yaml]
autonomous: true
user_setup: []

must_haves:
  truths:
    - "Hardware tier system detects and classifies system capabilities"
    - "Tier definitions are configurable and maintainable"
    - "Model mapping uses tiers for intelligent selection"
  artifacts:
    - path: "src/resource/tiers.py"
      provides: "Hardware tier detection and management system"
      min_lines: 80
    - path: "src/config/resource_tiers.yaml"
      provides: "Configurable hardware tier definitions"
      min_lines: 30
    - path: "src/resource/__init__.py"
      provides: "Resource management module initialization"
  key_links:
    - from: "src/resource/tiers.py"
      to: "src/config/resource_tiers.yaml"
      via: "YAML configuration loading"
      pattern: "yaml.safe_load|yaml.load"
    - from: "src/resource/tiers.py"
      to: "src/models/resource_monitor.py"
      via: "Resource monitoring integration"
      pattern: "ResourceMonitor"
---

<objective>
Create a hardware tier detection and management system that classifies systems into performance tiers (low_end, mid_range, high_end) with configurable thresholds and intelligent model mapping.

Purpose: Enable Mai to adapt gracefully from low-end hardware to high-end systems by understanding hardware capabilities and selecting appropriate models.
Output: Tier detection system with configurable definitions and model mapping capabilities.
</objective>

<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md

# Research-based architecture
@.planning/phases/03-resource-management/03-RESEARCH.md
</context>

<tasks>

<task type="auto">
  <name>Create resource module structure</name>
  <files>src/resource/__init__.py</files>
  <action>Create the resource module directory and __init__.py file. The __init__.py should expose the main resource management classes that will be created in this phase:
- HardwareTierDetector (from tiers.py)
- ProactiveScaler (from scaling.py) 
- ResourcePersonality (from personality.py)

Include proper module docstring explaining the resource management system's purpose.</action>
  <verify>ls -la src/resource/ shows the directory exists with __init__.py file</verify>
  <done>Resource module structure is established for Phase 3 components</done>
</task>

<task type="auto">
  <name>Create configurable hardware tier definitions</name>
  <files>src/config/resource_tiers.yaml</files>
  <action>Create a YAML configuration file defining hardware tiers based on the research patterns. Include:

1. Three tiers: low_end, mid_range, high_end
2. Resource thresholds for each tier:
   - RAM amounts (min/max in GB)
   - CPU core counts (min/max)
   - GPU requirements (required/optional)
   - GPU VRAM thresholds
3. Preferred model categories for each tier
4. Performance characteristics and expectations
5. Scaling thresholds specific to each tier

Example structure:
```yaml
tiers:
  low_end:
    ram_gb: {min: 2, max: 4}
    cpu_cores: {min: 2, max: 4}
    gpu_required: false
    preferred_models: ["small"]
    scaling_thresholds:
      memory_percent: 75
      cpu_percent: 80
  
  mid_range:
    ram_gb: {min: 4, max: 8}
    cpu_cores: {min: 4, max: 8}
    gpu_required: false
    preferred_models: ["small", "medium"]
    scaling_thresholds:
      memory_percent: 80
      cpu_percent: 85
  
  high_end:
    ram_gb: {min: 8, max: null}
    cpu_cores: {min: 6, max: null}
    gpu_required: true
    gpu_vram_gb: {min: 6}
    preferred_models: ["medium", "large"]
    scaling_thresholds:
      memory_percent: 85
      cpu_percent: 90
```

Include comments explaining each threshold's purpose.</action>
  <verify>python -c "import yaml; print('YAML valid:', yaml.safe_load(open('src/config/resource_tiers.yaml')))" loads the file without errors</verify>
  <done>Hardware tier definitions are configurable and well-documented</done>
</task>

<task type="auto">
  <name>Implement HardwareTierDetector class</name>
  <files>src/resource/tiers.py</files>
  <action>Create the HardwareTierDetector class that:
1. Loads tier definitions from resource_tiers.yaml
2. Detects current system resources using ResourceMonitor
3. Determines hardware tier based on resource thresholds
4. Provides model recommendations for detected tier
5. Supports tier-specific scaling thresholds

Key methods:
- load_tier_config(): Load YAML configuration
- detect_current_tier(): Determine system tier from resources
- get_preferred_models(): Return model preferences for tier
- get_scaling_thresholds(): Return tier-specific thresholds
- is_gpu_required(): Check if tier requires GPU
- can_upgrade_model(): Check if system can handle larger models

Include proper error handling for configuration loading and resource detection. The detector should integrate with the enhanced ResourceMonitor from Plan 01.</action>
  <verify>python -c "from src.resource.tiers import HardwareTierDetector; htd = HardwareTierDetector(); tier = htd.detect_current_tier(); print('Detected tier:', tier)" returns a valid tier name</verify>
  <done>HardwareTierDetector accurately classifies system capabilities and provides tier-based recommendations</done>
</task>

</tasks>

<verification>
Test hardware tier detection across simulated system configurations:
- Low-end systems (2-4GB RAM, 2-4 CPU cores, no GPU)
- Mid-range systems (4-8GB RAM, 4-8 CPU cores, optional GPU)
- High-end systems (8GB+ RAM, 6+ CPU cores, GPU required)

Verify tier recommendations align with research patterns and model mapping is logical.
</verification>

<success_criteria>
HardwareTierDetector successfully classifies systems into appropriate tiers, loads configuration correctly, integrates with ResourceMonitor, and provides accurate model recommendations based on detected capabilities.
</success_criteria>

<output>
After completion, create `.planning/phases/03-resource-management/03-02-SUMMARY.md`
</output>