Skip to content

WARP.md

Latest commit

 

History

History
187 lines (147 loc) · 5.98 KB

WARP.md

File metadata and controls

187 lines (147 loc) · 5.98 KB

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

WorkflowOS-Core is a PowerShell-based Windows optimization framework designed for professional workflows. It provides modular, profile-based system optimization with full auditability and rollback capabilities.

Key Architecture Principles

  • Additive Enhancement: Enhances systems without removing functionality
  • Security Preservation: Maintains Windows Defender, Firewall, BitLocker
  • Full Reversibility: Git-style snapshot and rollback system
  • Profile-Based: Context-aware optimization (Developer, Designer, Analyst)
  • Enterprise Compliance: Comprehensive audit logging

Core Commands

Main Operations

# Activate a profile (basic)
.\WorkflowOS.ps1 -Profile Developer

# Activate profile with module loading and monitoring
.\WorkflowOS.ps1 -Profile Designer -LoadModules

# Create manual snapshot before making changes
.\WorkflowOS.ps1 -Profile Analyst -CreateSnapshot

# View available snapshots
.\WorkflowOS.ps1 -Rollback

# Restore from specific snapshot
.\WorkflowOS.ps1 -Rollback -RollbackId "snapshot-guid-here"

# Run with verbose logging for debugging
.\WorkflowOS.ps1 -Profile Developer -Verbose

Log Analysis

# View recent audit entries
Get-Content "Logs\workflowos-*.log" | Select-Object -Last 50

# View today's log
Get-Content "Logs\workflowos-$(Get-Date -Format 'yyyyMMdd').log"

Architecture Overview

Core System

  • WorkflowOS.ps1: Main entry point and orchestration engine
  • Core/: Fundamental engine components
    • ModuleLoader.ps1: Module loading and validation system
    • AuditLogger.ps1: Comprehensive audit logging with JSON and human-readable formats
    • RollbackSystem.ps1: Git-style snapshot and rollback functionality

Module System

All modules follow consistent structure:

  • manifest.yaml: Module metadata, requirements, capabilities
  • ModuleName.ps1: Core implementation with standardized functions
  • Profile-aware configuration support
  • Automatic rollback support

Active Modules

  1. ProcessOptimizer: CPU priority, affinity, and memory optimization for professional applications
  2. ServiceOrchestrator: Context-aware Windows service management with dependency validation
  3. ProfileEngine: Dynamic profile switching via WMI process monitoring

Configuration System

  • Config/global.yaml: Engine-wide settings and feature flags
  • Config/Profiles/: Profile-specific YAML configurations
    • Developer.yaml: IDE optimization, WSL enablement, gaming service deactivation
    • Designer.yaml: Adobe Creative Suite optimization, graphics performance enhancement
    • Analyst.yaml: BI tool optimization, database service management

Development Guidelines

Adding New Modules

  1. Create Modules/YourModule/ directory
  2. Define manifest.yaml with requirements and capabilities
  3. Implement YourModule.ps1 with standard functions:
    • YourModule-Apply-Configuration
    • YourModule-Cleanup (optional)
  4. Update relevant profile YAML files

Required PowerShell Functions for Modules

function ModuleName-Apply-Configuration {
    param([PSCustomObject]$Configuration)
    # Apply module configuration
}

function ModuleName-Cleanup {
    # Optional: cleanup on module unload
}

Profile Configuration Structure

profile:
  name: "ProfileName"
  description: "Profile purpose"

triggers:
  - process_name: "app.exe"
    priority: "High"
    minimum_runtime_seconds: 10

modules:
  - name: "ModuleName"
    enabled: true
    # module-specific configuration

Important Constraints

Security Requirements

  • NEVER disable: Windows Defender, Firewall, BitLocker, TPM
  • Always preserve: Critical system services and dependencies
  • Required privileges: Administrator rights for all operations
  • Audit everything: All changes must be logged and reversible

System Requirements

  • PowerShell 7.3+ (strictly enforced)
  • Windows 10/11 with administrator privileges
  • Auto-installs powershell-yaml module if missing

Profile Switching Logic

  • Automatic switching via WMI process monitoring
  • Minimum switch intervals to prevent rapid changes
  • Application-specific triggers with runtime thresholds
  • Profile priorities determine precedence

Debugging and Troubleshooting

Common Issues

  1. Module Loading Failures: Check PowerShell version, admin privileges, manifest syntax
  2. Service Management Issues: Validate service names, check dependencies, review audit logs
  3. Profile Switching Problems: Verify process names, check WMI monitoring status

Debug Mode

# Enable verbose logging
.\WorkflowOS.ps1 -Profile Developer -Verbose

# Check loaded modules
$Global:LoadedModules

# View current profile configuration
$Global:CurrentProfile

Log Locations

  • Audit Logs: Logs/workflowos-YYYYMMDD.log (human-readable)
  • Structured Logs: Logs/workflowos-YYYYMMDD.json.log (machine-readable)
  • Snapshots: Snapshots/ directory with JSON snapshot files
  • Index: Snapshots/snapshots.index.json

Module Development Patterns

Manifest Requirements

name: ModuleName
version: 1.0.0
description: "Module purpose"
requirements:
  powershell_version: "7.3"
  windows_version: "10.0"
  admin_required: true
configuration:
  rollback_supported: true
  profile_aware: true

Error Handling

  • All module operations must include comprehensive error handling
  • Use Write-AuditLog for all significant operations and errors
  • Implement graceful degradation when possible
  • Always validate dependencies before making changes

Testing Considerations

  • No formal test framework currently exists
  • Manual verification required for all changes
  • Use snapshot/rollback system for safe testing
  • Verify operations in isolated environments first

This framework prioritizes enterprise compatibility, security preservation, and professional workflow optimization over gaming or consumer-focused optimizations.