calendar-event-manager

Calendar Event Manager

Create macOS Calendar events with tiered sound alarms and paired Reminders so events are never missed across Mac and iOS.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

CRITICAL RULES (Hard-Learned Truths 2026-02-12)

These rules are NON-NEGOTIABLE. Violating any of them defeats the purpose of this skill.

1. Calendar + Reminders ALWAYS Together

Every event MUST create BOTH:

• Calendar event with multiple sound alarm entries (custom sound per tier)
• Reminders (3 minimum) as a separate notification channel

Never create one without the other.

2. Use sound alarm, NOT display alarm

-- CORRECT: audible alert with custom sound
make new sound alarm at end of sound alarms with properties {trigger interval:-60, sound name:"Glass"}

-- WRONG: silent visual banner only
make new display alarm at end of display alarms with properties {trigger interval:-60}

Each alarm supports its own sound name property. Use DIFFERENT sounds for different tiers so the user knows which alert level it is by sound alone.

3. ONLY Long Sounds (>= 1.4 seconds)

Short sounds get missed and ignored. NEVER use sounds under 1.4 seconds.

APPROVED sounds only:

BANNED sounds: Hero, Basso, Bottle, Purr, Frog, Morse, Tink (all < 1.4s)

4. Multiple Early Reminders Are Mandatory

Calendar accepts at most 5 alarms per event (verified 2026-08-17 on a CalDAV calendar: adding a 6th silently evicts an earlier one, with no error). Budget the 5 slots deliberately and do NOT spend one duplicating a Reminder that already fires at the same moment.

Default alarm tiers:

Plus 3 Reminders: "TOMORROW:" (day before, 9 AM), "TODAY:" (morning-of), and the due-time one.

Use -1439, never -1440. An exact 1440-minute (24 h) offset is silently dropped by Calendar — the alarm simply does not appear on read-back. Verified twice on 2026-08-17. -1439 persists.

Early-morning events (before ~9:30 AM)

The default tiers misfire for early events. Adjust:

• The morning-of 9 AM Reminder fires after an 08:30 event. Move it to ~90 min before the event instead.
• A -180 min tier on an 08:30 event rings at 05:30, waking the user three hours early. Drop it; use the night-before -720 tier instead.

5. macOS Notification Settings Prerequisite

Calendar notifications must be enabled in System Settings:

• System Settings > Notifications > Calendar > Allow Notifications = ON
• Alert style = Banners or Alerts
• Play sound = ON

Open with: open "x-apple.systempreferences:com.apple.Notifications-Settings.extension"

TodoWrite Task Templates

Template A: Create Event from Invitation

1. Extract event details (title, date, time, location, notes, RSVP)
2. Create Calendar event with 5-tier sound alarms (Blow, Sosumi, Glass, Ping, Funk)
3. Create 3 Reminders (TOMORROW, TODAY morning, due-time)
4. Verify event and reminders created
5. Report full schedule to user

Template B: Create Event from User Description

1. Ask user for: event name, date/time, duration, location
2. Create Calendar event with 5-tier sound alarms (max Calendar allows)
3. Create 3 Reminders
4. Verify event and reminders created
5. Report full schedule to user

Template C: Test Notification Setup

1. Create test Calendar event 3 min in future with sound alarms (1 min, 2 min tiers)
2. Create test Reminder 2 min in future
3. Wait for user confirmation of notifications
4. Clean up test event and reminders

AppleScript Date Construction (CRITICAL)

NEVER use date "STRING" in AppleScript. String-based date parsing is locale-dependent and silently produces wrong results:

ALWAYS use programmatic date construction:

-- Build date safely: day-first-then-month prevents rollover
set d to current date
set day of d to 1           -- safe floor FIRST (prevents month rollover)
set month of d to April
set year of d to 2026
set day of d to 1           -- now set actual target day
set hours of d to 18        -- 24h format, no AM/PM ambiguity
set minutes of d to 0
set seconds of d to 0

Calendar Discovery (run first)

tell application "Calendar"
    set output to ""
    repeat with c in calendars
        set output to output & name of c & " (writable:" & writable of c & ")" & linefeed
    end repeat
    output
end tell

Use the first writable:true calendar. Never assume "Home" or "Calendar" exists.

Full Event Creation (Copy-Paste Ready)

tell application "Calendar"
    -- Build start date programmatically
    set startDate to current date
    set day of startDate to 1
    set month of startDate to MONTH_CONSTANT
    set year of startDate to YEAR_INT
    set day of startDate to DAY_INT
    set hours of startDate to HOUR_24
    set minutes of startDate to 0
    set seconds of startDate to 0

    -- Build end date (1 hour later)
    set endDate to startDate + 1 * hours

    tell calendar "WRITABLE_CALENDAR_NAME"
        set newEvent to make new event with properties {summary:"EVENT_NAME", start date:startDate, end date:endDate, location:"LOCATION", description:"NOTES"}
        tell newEvent
            -- EXACTLY 5 alarms: a 6th silently evicts one of these.
            -- -1439 not -1440: an exact 24h offset is silently dropped.
            make new sound alarm at end of sound alarms with properties {trigger interval:-1439, sound name:"Blow"}
            make new sound alarm at end of sound alarms with properties {trigger interval:-720, sound name:"Sosumi"}
            make new sound alarm at end of sound alarms with properties {trigger interval:-60, sound name:"Glass"}
            make new sound alarm at end of sound alarms with properties {trigger interval:-30, sound name:"Ping"}
            make new sound alarm at end of sound alarms with properties {trigger interval:0, sound name:"Funk"}
        end tell
    end tell
    reload calendars
end tell

Verification (always run after creation)

Verification is NOT optional. Every failure logged in this file was silent — the create step returned success in all of them.

tell application "Calendar"
    tell calendar "WRITABLE_CALENDAR_NAME"
        set e to first event whose summary contains "EVENT_NAME"
        set out to (summary of e) & " | " & (start date of e) & " -> " & (end date of e) & linefeed
        -- Read BOTH classes: Calendar reports sound alarms back as display alarms.
        set out to out & "alarms=" & ((count of display alarms of e) + (count of sound alarms of e)) & linefeed
        repeat with a in display alarms of e
            set out to out & "  " & (trigger interval of a) & linefeed
        end repeat
        repeat with a in sound alarms of e
            set out to out & "  " & (trigger interval of a) & linefeed
        end repeat
        return out
    end tell
end tell

Confirm the alarm COUNT and every trigger interval — do not just confirm the event exists. Dropped alarms are the most common silent failure.

Calendar AppleScript bridge limitations (verified 2026-08-17)

Paired Reminders Creation

NEVER use default list. On this machine it resolves to an empty placeholder list literally named DEFAULT_TASK_CALENDAR_NAME (an unsubstituted template string). make new reminder in (default list) returns success and writes nothing — a total silent failure. Discover the real list by name first and target it explicitly.

-- Discover lists FIRST; never assume.
tell application "Reminders"
    set out to ""
    repeat with l in lists
        set out to out & name of l & " count=" & (count of reminders in l) & linefeed
    end repeat
    return out
end tell

tell application "Reminders"
    -- Target the real list BY NAME (usually "Reminders"), not `default list`.
    set targetList to list "Reminders"

    -- Build date programmatically (same pattern as Calendar)
    set eventDate to current date
    set day of eventDate to 1
    set month of eventDate to MONTH_CONSTANT
    set year of eventDate to YEAR_INT
    set day of eventDate to DAY_INT
    set hours of eventDate to HOUR_24
    set minutes of eventDate to 0
    set seconds of eventDate to 0

    -- CRITICAL: `copy`, not `set`. `set x to eventDate` ALIASES the same date
    -- object, so mutating x silently rewrites eventDate too (this corrupted a
    -- due-time reminder to 07:00 on 2026-08-17). `copy` makes a real clone.
    copy eventDate to morningDate
    set hours of morningDate to 7
    set minutes of morningDate to 0
    set seconds of morningDate to 0

    copy eventDate to dayBefore
    set dayBefore to dayBefore - 1 * days
    set hours of dayBefore to 9
    set minutes of dayBefore to 0
    set seconds of dayBefore to 0

    make new reminder in targetList with properties {name:"NOW: EVENT_NAME", due date:eventDate, body:"LOCATION" & linefeed & "NOTES"}
    make new reminder in targetList with properties {name:"TOMORROW: EVENT_NAME", due date:dayBefore, body:"Event tomorrow! LOCATION"}
    make new reminder in targetList with properties {name:"TODAY: EVENT_NAME", due date:morningDate, body:"Today! LOCATION"}
end tell

Note body: must use & linefeed & — a literal \n inside an AppleScript string is the two characters backslash-n, not a newline.

Post-Change Checklist

After modifying this skill:

1. Sound reference table matches sound-reference.md
2. All 5 alarm tiers documented with correct sounds (Calendar caps at 5)
3. BANNED sounds list is complete
4. Hook file (hooks/calendar-reminder-sync.ts) aligned with skill rules
5. AppleScript examples use sound alarm not display alarm

References

• Sound Reference - Full sound duration data and approved/rejected lists
• Apple Calendar Scripting Guide

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure.
2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.