gazefix-dev

name	gazefix-dev
description	Guidance for developing gazefix.ai (macOS virtual camera + Vision/CoreML/Metal pipeline). Use for architecture changes, new pipeline stages, or debugging CMIO issues.

gazefix-dev

When to use

• Adding or modifying the CoreMediaIO Camera Extension
• Changing frame pipeline timing, formats, or dropping behavior
• Integrating Vision tracking or Core ML models
• Implementing Metal compositing or masks
• Investigating black frames, freezes, high latency, or high CPU/GPU
• For OBS Studio filter plugin work, use gazefix-obs-filter-dev instead.

Instructions

0. Architecture support:
   • Gazefix is currently Apple Silicon (arm64) only. Avoid adding x86_64/universal guidance unless Intel support is explicitly reintroduced.
1. Identify which module(s) change:
   • extension/ (CMIO virtual camera)
   • packages/GazefixCore/ (Vision/Gaze/Metal/ML)
   • app/ (UI + settings)
2. Preserve real-time constraints:
   • no blocking on CMIO callbacks
   • bounded queues; drop under load
3. Prefer Apple silicon acceleration paths (and keep them verifiable):
   • Move image processing + overlays to Metal:
     • CVMetalTextureCache for texture ingestion
     • composite on GPU (no per-frame Core Graphics drawing)
   • If/when Core ML is added:
     • set MLModelConfiguration.computeUnits explicitly (default: .all)
     • instrument inference time and fallback/budget-miss rate
   • Minimize CPU copies:
     • avoid full-frame memcpy where possible
     • prefer GPU pathways + pooled buffers/textures
4. Add/adjust instrumentation:
   • fps, latency estimate, drops, Vision refresh cadence, inference time
5. Provide a manual test recipe:
   • how to reproduce
   • what to observe (overlay/metrics)
6. ALWAYS update documentation when behavior changes.
   • Update the most relevant docs/*.md pages (often docs/pipeline.md, plus feature-specific docs like docs/vision-eye-roi.md).
   • If the change affects agent workflows/guardrails, update the relevant agent rule/skill too.

Output format (when you respond as an agent)

• “Files to change” (paths)
• “Key design notes” (constraints + pitfalls)
• “Implementation steps”
• “Documentation updates” (what changed and where)
• “Test plan” (manual + automated if applicable)
• “Troubleshooting checklist” (if relevant)