feat(#24): implement mosaic-plugin-calendar skill

2026-01-29 21:11:50 -06:00
parent 9de0b2f92f
commit 93f6c87113
3 changed files with 479 additions and 0 deletions
--- a/packages/skills/calendar/SKILL.md
+++ b/packages/skills/calendar/SKILL.md
@@ -0,0 +1,150 @@
+---
+name: mosaic-plugin-calendar
+description: Integration with Mosaic Stack's Events API for calendar management. Use when the user wants to schedule, view, update, or cancel events/meetings/appointments in their Mosaic calendar, including queries like "schedule a meeting", "what's on my calendar", "upcoming events", "cancel meeting", or "reschedule appointment".
+---
+
+# Mosaic Calendar
+
+Integration with Mosaic Stack's Events API for comprehensive calendar management.
+
+## Quick Start
+
+Use `scripts/calendar.js` for all calendar operations. The script handles authentication and API communication automatically.
+
+### Creating Events
+
+```bash
+node scripts/calendar.js create \
+  --title "Team Meeting" \
+  --start "2024-01-30T15:00:00Z" \
+  --end "2024-01-30T16:00:00Z" \
+  --description "Weekly sync" \
+  --location "Conference Room A"
+```
+
+Natural language examples:
+- "Schedule a meeting tomorrow at 3pm"
+- "Create an event called 'dentist appointment' on Friday at 2pm"
+- "Add a recurring standup every weekday at 9am"
+
+### Querying Events
+
+```bash
+# List all upcoming events
+node scripts/calendar.js list
+
+# Events in a date range
+node scripts/calendar.js list \
+  --from "2024-01-30" \
+  --to "2024-02-05"
+
+# Events for a specific project
+node scripts/calendar.js list --project-id "uuid-here"
+```
+
+Natural language examples:
+- "What's on my calendar this week?"
+- "Show me upcoming events"
+- "What do I have scheduled for tomorrow?"
+- "Any meetings today?"
+
+### Updating Events
+
+```bash
+node scripts/calendar.js update EVENT_ID \
+  --title "Updated Title" \
+  --start "2024-01-30T16:00:00Z"
+```
+
+Natural language examples:
+- "Move my 3pm meeting to 4pm"
+- "Reschedule tomorrow's dentist appointment to Friday"
+- "Change the location of my team meeting to Zoom"
+
+### Deleting Events
+
+```bash
+node scripts/calendar.js delete EVENT_ID
+```
+
+Natural language examples:
+- "Cancel my meeting with Sarah"
+- "Delete tomorrow's standup"
+- "Remove the 3pm appointment"
+
+## Event Fields
+
+- **title** (required): Event name (1-255 characters)
+- **startTime** (required): ISO 8601 date string (e.g., "2024-01-30T15:00:00Z")
+- **endTime** (optional): ISO 8601 date string
+- **description** (optional): Event details (max 10,000 characters)
+- **location** (optional): Physical or virtual location (max 500 characters)
+- **allDay** (optional): Boolean flag for all-day events
+- **recurrence** (optional): Recurrence rules (object)
+- **projectId** (optional): Link event to a Mosaic project (UUID)
+- **metadata** (optional): Custom key-value data (object)
+
+## Date Handling
+
+When processing natural language date/time requests:
+
+1. Convert to ISO 8601 format (e.g., "2024-01-30T15:00:00Z")
+2. Handle relative dates ("tomorrow", "next week", "Friday")
+3. Infer end time if not specified (default: 1 hour after start)
+4. Use user's timezone (America/Chicago) unless specified otherwise
+
+## Response Format
+
+All operations return JSON:
+
+```json
+{
+  "id": "uuid",
+  "title": "Team Meeting",
+  "startTime": "2024-01-30T15:00:00Z",
+  "endTime": "2024-01-30T16:00:00Z",
+  "description": "Weekly sync",
+  "location": "Conference Room A",
+  "allDay": false,
+  "workspaceId": "uuid",
+  "createdBy": "uuid",
+  "projectId": null,
+  "recurrence": null,
+  "metadata": {},
+  "createdAt": "2024-01-29T10:00:00Z",
+  "updatedAt": "2024-01-29T10:00:00Z"
+}
+```
+
+List queries return paginated results with metadata:
+
+```json
+{
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "limit": 50,
+    "total": 100,
+    "totalPages": 2
+  }
+}
+```
+
+## Environment
+
+The script reads configuration from:
+- `MOSAIC_API_URL` (default: http://localhost:3001)
+- `MOSAIC_WORKSPACE_ID` (required)
+- `MOSAIC_API_TOKEN` (required for authentication)
+
+Ensure these are set in the environment or `.env` file.
+
+## Error Handling
+
+Common errors:
+- **401 Unauthorized**: Missing or invalid API token
+- **403 Forbidden**: Insufficient workspace permissions
+- **404 Not Found**: Event ID doesn't exist
+- **400 Bad Request**: Invalid date format or missing required fields
+
+When operations fail, the script outputs clear error messages with guidance on resolution.