mac-life-admin

name	mac-life-admin
description	Create and maintain local personal-admin workspaces that sync structured files to macOS Calendar and Reminders. Use when Codex needs to manage daily affairs, travel, conferences, appointments, errands, recurring preparations, personal preferences, memory files, or completion-state round trips between Reminders and source files.

Mac Life Admin

Turn a folder into a durable personal-operations workspace: files are the source of truth, macOS Calendar and Reminders are synchronized views. All workspace state lives under a single hidden .mac-life-admin/ folder.

Workflow

1. Inspect the workspace. Look for .mac-life-admin/schedule.toml, .mac-life-admin/reminders.tsv, .mac-life-admin/memory.md, .mac-life-admin/plan.md, and .mac-life-admin/scripts/sync_mac_life_admin.py.
2. If the workspace is new, follow references/new-workspace-onboarding.md (Chinese) or references/new-workspace-onboarding-en.md (English). Copy assets/workspace-template/ into the workspace root, create .mac-life-admin/scripts/, copy scripts/sync_mac_life_admin.py and scripts/reminders_native_sync.m there, then personalize .mac-life-admin/schedule.toml.
3. For each user update, write to files before touching apps:
   • Calendar events → .mac-life-admin/schedule.toml [[events]]
   • Reminders → the TSV configured in meta.reminders_source, default .mac-life-admin/reminders.tsv (assign a stable id for every row)
   • Stable preferences and schedule context → .mac-life-admin/memory.md (run user-supplied strings through redact_for_privacy)
   • Human-readable summaries → .mac-life-admin/plan.md
   • Tool failures, AppleScript errors, sync gotchas: NOT here — delegate to the self-improvement skill.
4. Do not generate or overwrite workspace-root AGENTS.md. Keep generic rules in this skill, local state under .mac-life-admin/.
5. Validate first: python3 .mac-life-admin/scripts/sync_mac_life_admin.py --check
6. Diff before mutating: python3 .mac-life-admin/scripts/sync_mac_life_admin.py --dry-run
7. Apply: python3 .mac-life-admin/scripts/sync_mac_life_admin.py --apply. The script snapshots files before any destructive op. Use --skip-calendar or --skip-reminders for partial syncs.
8. Verify the important Calendar entries and Reminders sections in the macOS apps when the change matters.

Important Rules

• Files are durable state; do not make app-only changes unless the user asks. If a user-side app change happens, backfill files before the next sync.
• Preserve user-created data. Delete events, reminders, lists only when requested.
• Keep generated state under .mac-life-admin/ unless the user explicitly wants visible project files.
• Prefer one managed Reminders list with native sections; switch to multi-list only on explicit request.
• Before rebuilding Reminders, let the script read current completion state and write it back to the TSV. A checked-off Reminders item means completed=true.
• Completion writeback matches Reminders by exact title. Keep reminder titles unique and stable, and still assign source-file ids for maintenance.
• Use exact list-name comparison when deleting/rebuilding a managed list; never rely on compound whose predicates.
• For travel or remote events, store local event time with an explicit UTC offset (e.g. 2026-06-05T13:00:00+02:00).
• When facts can change (ticket policy, opening hours, travel rules, product requirements), verify online and cite sources.
• Run user-supplied strings through redact_for_privacy before writing them to memory.md.

Resources

• scripts/sync_mac_life_admin.py — generic Calendar/Reminders sync script. Subcommands: --check, --dry-run, --apply, --from-template, --list-templates.
• scripts/reminders_native_sync.m — native Reminders sections/tags helper, compiled by the Python script.
• assets/workspace-template/ — starter .mac-life-admin/ folder for a new workspace.
• references/new-workspace-onboarding.md / new-workspace-onboarding-en.md — first-run checklist (Chinese / English).
• references/rules.md — durable operating do/don'ts. Read once per session.
• references/schema-reference.md — full field reference for schedule.toml, reminders.tsv, and the CLI. Read when editing schema-level config or adding new fields.
• references/troubleshooting.md — permissions, ReminderKit compile, AppleScript, timezone, writeback, backup issues. Read when a sync fails.
• references/mac-sync-notes.md — macOS Calendar/Reminders implementation notes and common failure modes (lower-level than troubleshooting).

When to read what

• Routine reminder/event add → no references needed.
• First-run setup → onboarding (per language).
• Adding a new TOML section, alarm, recurrence, template, or per-event override → schema-reference.md.
• A command failed → troubleshooting.md first, then mac-sync-notes.md if it's lower-level.
• Unclear about what's allowed → rules.md.