Copilot Instructions for MonPere

Project Overview

MonPere is a cross-platform desktop application that provides an AI agent capable of controlling a user's computer in real-time while maintaining human oversight and safety controls.

Core Principles

1. Safety First

Always prioritize user safety and system security
Implement multiple layers of safety checks before any system operation
Never suggest code that could harm the user's system without explicit warnings
Always include emergency stop mechanisms and rollback capabilities
Validate all user inputs and sanitize system commands

2. Real-time Control & Transparency

Design for real-time monitoring and intervention capabilities
Log all AI actions with timestamps and context
Provide clear visual feedback for all AI operations
Enable users to pause, modify, or stop AI actions at any time
Make AI decision-making process transparent and explainable

3. Cross-platform Compatibility

Write code that works across Windows, macOS, and Linux
Use platform-agnostic APIs where possible
Handle platform-specific features gracefully with appropriate fallbacks
Test and validate on multiple operating systems

Technical Guidelines

Architecture Patterns

Use a modular, event-driven architecture
Implement clear separation between UI, business logic, and system control
Design for scalability and maintainability
Use dependency injection and interfaces for testability

Code Quality

Follow TypeScript best practices (if using Electron/web stack)
Use strict typing and comprehensive error handling
Write self-documenting code with clear variable and function names
Include comprehensive unit and integration tests
Follow consistent naming conventions and code formatting

Security Considerations

Never hardcode API keys or sensitive information
Implement secure storage for credentials and user data
Use encryption for sensitive data transmission and storage
Validate and sanitize all external inputs
Implement proper access controls and permission systems

Performance

Optimize for low latency in real-time operations
Minimize resource usage and memory footprint
Implement efficient screen capture and processing
Use async/await patterns for non-blocking operations
Profile and optimize critical paths

Component-Specific Guidelines

Frontend (UI Layer)

// Example pattern for React components
interface ComponentProps {
  onAction: (action: ActionType) => void;
  isAIActive: boolean;
  canStop: boolean;
}

const SafeComponent: React.FC<ComponentProps> = ({
  onAction,
  isAIActive,
  canStop,
}) => {
  // Always include emergency controls
  const handleEmergencyStop = useCallback(() => {
    onAction({ type: "EMERGENCY_STOP", timestamp: Date.now() });
  }, [onAction]);

  return (
    <div>
      {/* Main UI */}
      {isAIActive && (
        <EmergencyStopButton
          onClick={handleEmergencyStop}
          disabled={!canStop}
        />
      )}
    </div>
  );
};

AI Integration Layer

// Example pattern for AI service integration
interface AIService {
  processCommand(command: string, context: Context): Promise<ActionPlan>;
  validateAction(action: Action): Promise<ValidationResult>;
  explainDecision(action: Action): string;
}

class SafeAIService implements AIService {
  async processCommand(command: string, context: Context): Promise<ActionPlan> {
    // Validate input
    if (this.containsUnsafeOperations(command)) {
      throw new Error("Unsafe operation detected");
    }

    // Process with AI
    const plan = await this.llmService.generatePlan(command, context);

    // Validate output
    await this.validateActionPlan(plan);

    return plan;
  }
}

System Control Layer

// Example pattern for system operations
interface SystemController {
  executeAction(action: Action): Promise<ActionResult>;
  validatePermissions(action: Action): boolean;
  createRollbackPoint(): string;
  rollback(pointId: string): Promise<void>;
}

class SafeSystemController implements SystemController {
  async executeAction(action: Action): Promise<ActionResult> {
    // Check permissions
    if (!this.validatePermissions(action)) {
      throw new Error("Insufficient permissions");
    }

    // Create rollback point
    const rollbackId = this.createRollbackPoint();

    try {
      const result = await this.performSystemAction(action);
      this.logAction(action, result);
      return result;
    } catch (error) {
      await this.rollback(rollbackId);
      throw error;
    }
  }
}

Common Patterns and Best Practices

Error Handling

// Always use comprehensive error handling
try {
  const result = await riskyOperation();
  return { success: true, data: result };
} catch (error) {
  logger.error("Operation failed", { error, context });
  await this.handleFailure(error);
  return { success: false, error: error.message };
}

Logging and Monitoring

// Include structured logging for all operations
const logger = createLogger({
  service: "monpere",
  level: "info",
  format: "json",
});

logger.info("AI action executed", {
  action: action.type,
  duration: Date.now() - startTime,
  success: true,
  userId: user.id,
});

Configuration Management

// Use type-safe configuration
interface AppConfig {
  ai: {
    provider: "openai" | "anthropic";
    model: string;
    apiKey: string;
  };
  safety: {
    maxActions: number;
    requireConfirmation: boolean;
    allowedOperations: string[];
  };
  ui: {
    theme: "light" | "dark";
    language: string;
  };
}

const config = loadConfig<AppConfig>();

File Organization

src/
├── ui/                     # Frontend components
│   ├── components/         # Reusable UI components
│   ├── pages/             # Main application pages
│   ├── hooks/             # Custom React hooks
│   └── styles/            # Styling and themes
├── core/                  # Core business logic
│   ├── ai/                # AI service integration
│   ├── system/            # System control layer
│   ├── safety/            # Safety and validation
│   └── models/            # Data models and types
├── services/              # External service integrations
├── utils/                 # Utility functions
├── config/                # Configuration management
└── tests/                 # Test suites

Testing Strategy

Unit Tests

Test all business logic functions in isolation
Mock external dependencies (AI APIs, system calls)
Achieve >90% code coverage for critical paths
Use property-based testing for complex logic

Integration Tests

Test component interactions and data flow
Validate AI service integrations
Test system control operations in safe environments
Verify safety mechanisms and emergency stops

End-to-End Tests

Test complete user workflows
Validate cross-platform compatibility
Test performance under realistic conditions
Verify security and permission systems

Development Workflow

Before Starting Any Feature

Review safety implications of the feature
Design with user control and transparency in mind
Consider cross-platform compatibility requirements
Plan comprehensive testing strategy

Code Review Checklist

Safety mechanisms implemented and tested
Error handling covers all edge cases
Performance implications considered
Security vulnerabilities addressed
Cross-platform compatibility verified
Documentation updated
Tests written and passing

Deployment Considerations

Use staged rollouts for safety-critical features
Monitor system performance and user feedback
Have rollback plans for all releases
Validate on multiple platforms before release

Emergency Protocols

If AI Misbehaves

Implement immediate stop mechanisms
Log all actions for debugging
Notify user of the issue
Provide rollback options where possible
Report to AI service provider if needed

Security Incidents

Immediately isolate affected systems
Document the incident thoroughly
Implement fixes and preventive measures
Communicate transparently with users
Review and update security protocols

Remember

The user's safety and system integrity are paramount
Always err on the side of caution
Make AI behavior transparent and controllable
Design for reliability and fault tolerance
Keep security considerations at the forefront of all decisions

This software has the potential to significantly impact users' systems. Approach development with appropriate caution and responsibility.