omnifocus-manager

# OmniFocus Manager Skill

Manage OmniFocus tasks with proper project assignment, tagging, and organization based on user preferences.

## When to Activate

Use this skill when user wants to:
- Add/create tasks
- Follow up with someone
- Triage or review inbox
- Clean up or organize tasks
- Check what's due or available
- Query task status

## User Preferences

**Task Creation Philosophy:**
- Always assign to a project (never leave in Inbox)
- Always set expected completion date
- Tag with person + "Follow Up" for 1:1 discussions
- Use location tags for shopping tasks

## Working with OmniFocus Scripting

### JXA vs AppleScript: When to Use Each

**Use JXA (JavaScript for Automation) for:**
- ✅ Reading data (tasks, projects, tags, inbox)
- ✅ Creating/updating individual tasks
- ✅ Adding tags to tasks
- ✅ Moving tasks between projects
- ✅ Fast, single-purpose operations

**Use AppleScript for:**
- ✅ Creating projects inside folders
- ✅ Creating folders
- ✅ Bulk operations on multiple projects
- ✅ Complex nested structures (folder → project → tasks)

**CRITICAL DIFFERENCE:**
- **External JXA scripts** (via `osascript -l JavaScript`) have limitations
- **OmniJS** (built-in JavaScript in OmniFocus app) has more capabilities
- Documentation examples showing `new Project(name, folder)` work in OmniJS but **NOT in external JXA scripts**

### Common Pitfalls & Solutions

| Pitfall | Why It Happens | Solution |
|---------|---------------|----------|
| Projects created at root instead of in folder | JXA `parentFolder` property doesn't work externally | Use AppleScript with `tell folder` blocks |
| Duplicate empty folders | Script creates folder but projects fail to nest | Always verify `count of projects of folder` after creation |
| "Can't convert types" errors | JXA type mismatch between app objects and JavaScript | Use AppleScript for complex operations |
| Projects appear created but aren't | Script reports success but verification shows 0 projects | Always verify after c