@hailer/mcp 1.1.12 → 1.1.13

package/.claude/skills/SDK-activity-patterns/SKILL.md

@@ -1,428 +0,0 @@
----
-name: SDK-activity-patterns
-description: Activity CRUD patterns - field value formats, dates, users, links, dropdowns
-version: 1.4.0
-triggers: Create activity, update activity, field values, date format, activitylink value
----
-
-# Activity CRUD Patterns
-
-## MCP Tools
-
-| Tool | Purpose |
-|------|---------|
-| `mcp__hailer__create_activity` | Create new activity |
-| `mcp__hailer__update_activity` | Update existing activity |
-
----
-
-## Create Activity
-
-```javascript
-mcp__hailer__create_activity({
-  workflowId: "682ac815fba468d857d498f7",
-  phaseId: "682ac815fba468d857d49904",
-  name: "New Task",  // Optional - activity name
-  fields: {
-    "fieldId1": "value1",
-    "fieldId2": "value2"
-  }
-})
-```
-
-## Update Activity
-
-```javascript
-mcp__hailer__update_activity({
-  activityId: "692abc123def456",
-  fields: {
-    "fieldId1": "new value"
-  },
-  // Optional: move to different phase
-  phaseId: "682ac815fba468d857d49906"
-})
-```
-
----
-
-## Field Value Formats
-
-All valid field types from `hailer.d.ts`. **No multi-select types exist.**
-
-### Text Fields
-
-| Type | Format | Example |
-|------|--------|---------|
-| `text` | String | `"Hello world"` |
-| `textarea` | String | `"Multi\nline\ntext"` |
-| `textunit` | String | `"100"` (unit in display) |
-
-### Number Fields
-
-| Type | Format | Example |
-|------|--------|---------|
-| `numeric` | Number | `42` or `42.5` |
-| `numericunit` | Number | `99.99` (unit defined in field config) |
-
-### Date/Time Fields
-
-| Type | Format | Example |
-|------|--------|---------|
-| `date` | Unix timestamp (ms) | `1730937600000` |
-| `datetime` | Unix timestamp (ms) | `1730937600000` |
-| `daterange` | Object | `{ start: 1730937600000, end: 1731024000000 }` |
-| `datetimerange` | Object | `{ start: 1730937600000, end: 1731024000000 }` |
-| `time` | Unix timestamp (ms, includes date!) | `1765863000000` |
-| `timerange` | Object | `{ start: 1765863000000, end: 1765915200000 }` (ms timestamps, includes date!) |
-
-**Date Conversion:**
-```javascript
-// JavaScript Date to Hailer timestamp
-const timestamp = new Date('2024-11-07').getTime();  // 1730937600000
-
-// Hailer timestamp to Date
-const date = new Date(1730937600000);
-
-// Time field: also Unix timestamp (includes date)
-const today = new Date();
-today.setUTCHours(9, 30, 0, 0);
-const timeValue = today.getTime();  // e.g., 1765863000000
-```
-
-### Selection Fields
-
-| Type | Format | Example |
-|------|--------|---------|
-| `textpredefinedoptions` | **STRING** | `"High"` |
-
-**CRITICAL:** Value is STRING, not array! No multi-select type exists.
-```javascript
-// ✅ Correct
-fields: { priority: "High" }
-
-// ❌ Wrong
-fields: { priority: ["High"] }
-```
-
-### User & Team Fields
-
-| Type | Format | Example |
-|------|--------|---------|
-| `users` | **STRING** (user ID) | `"5f8a1b2c3d4e5f6a7b8c9d0e"` |
-| `teams` | **STRING** (team ID) | `"teamId123"` |
-
-**CRITICAL:** Value is STRING, not array! No multi-select types exist.
-```javascript
-// ✅ Correct
-fields: { assignee: "5f8a1b2c3d4e5f6a7b8c9d0e" }
-
-// ❌ Wrong
-fields: { assignee: ["5f8a1b2c3d4e5f6a7b8c9d0e"] }
-```
-
-### Link Fields
-
-| Type | Format | Example |
-|------|--------|---------|
-| `activitylink` | **STRING** (activity ID) | `"692abc123def456"` |
-
-**CRITICAL:** Activity link is plain STRING ID, not array or object!
-```javascript
-// ✅ Correct - plain string ID
-fields: { customer: "692abc123def456" }
-
-// ❌ Wrong - array
-fields: { customer: ["692abc123def456"] }
-
-// ❌ Wrong - object (this is READ format, not WRITE format!)
-fields: { customer: { _id: "692abc123def456", name: "Acme" } }
-```
-
-**READ vs WRITE formats differ:**
-- **READ** (from API): `{ _id: string, name: string }` object
-- **WRITE** (to API): plain string ID only
-
-### Modified Fields (Checkbox & File)
-
-These use base types with a `modifier` in the field config:
-
-| Config | Value Format | Example |
-|--------|--------------|---------|
-| `numeric` + `modifier.checkbox: true` | Number | `1` (true) or `0` (false) |
-| `text` + `modifier.file: true` | Object | File reference (UI handles) |
-
-### Other Fields
-
-| Type | Format | Example |
-|------|--------|---------|
-| `country` | ISO code | `"FI"`, `"SE"`, `"US"` |
-
----
-
-## Complete Create Example
-
-```javascript
-mcp__hailer__create_activity({
-  workflowId: "682ac815fba468d857d498f7",
-  phaseId: "682ac815fba468d857d49904",
-  name: "Fix login bug",
-  fields: {
-    // Text
-    "description_abc": "Users cannot log in after password reset",
-
-    // Dropdown select (STRING!)
-    "priority_def": "High",
-
-    // User (STRING!)
-    "assignee_jkl": "5f8a1b2c3d4e5f6a7b8c9d0e",
-
-    // Activity link (STRING!)
-    "project_mno": "692abc123def456",
-
-    // Date (timestamp ms)
-    "due_date_pqr": 1730937600000,
-
-    // Number
-    "estimated_hours_stu": 4
-  }
-})
-```
-
----
-
-## Bulk Creation
-
-Use the `activities[]` array for bulk creation. **Each activity must include its own teamId and phaseId.**
-
-```javascript
-mcp__hailer__create_activity({
-  workflowId: "682ac815fba468d857d498f7",
-  activities: [
-    {
-      name: "Task 1",
-      phaseId: "682ac815fba468d857d49904",
-      teamId: "690d2b2e2b3a4c5d6e7f8a9b",  // REQUIRED per activity!
-      fields: { "priority_abc": "High" }
-    },
-    {
-      name: "Task 2",
-      phaseId: "682ac815fba468d857d49904",
-      teamId: "690d2b2e2b3a4c5d6e7f8a9b",
-      fields: { "priority_abc": "Medium" }
-    }
-  ]
-})
-```
-
-**API:** Calls `v3.activity.createMany` via socket.
-
-### Single vs Bulk: Parameter Placement
-
-| Parameter | Single mode | Bulk mode |
-|-----------|-------------|-----------|
-| `name` | Top-level | Inside each `activities[]` item |
-| `phaseId` | Top-level | Inside each `activities[]` item |
-| `teamId` | Top-level | **Inside each `activities[]` item** |
-| `fields` | Top-level | Inside each `activities[]` item |
-| `workflowId` | Top-level | Top-level (shared) |
-
-**CRITICAL:** In bulk mode, `teamId` at the top level is **IGNORED**. Each activity in the array must have its own `teamId`. Omitting it causes "Missing team(s)" (code 127) unless the workflow has a default team.
-
-### Team ID Fallback Chain
-
-The MCP tool auto-fills `teamId` if omitted:
-1. Per-activity `teamId` (if provided) — **always provide this**
-2. Workflow's default team (`workflow.team`)
-3. First workspace team (last resort, may be wrong team)
-
-**Best practice:** Always pass `teamId` explicitly. Don't rely on fallbacks.
-
----
-
-## Phase Transitions
-
-Move activity to different phase:
-
-```javascript
-mcp__hailer__update_activity({
-  activityId: "692abc123def456",
-  phaseId: "682ac815fba468d857d49906"  // Target phase
-})
-```
-
-Update fields AND move phase:
-
-```javascript
-mcp__hailer__update_activity({
-  activityId: "692abc123def456",
-  phaseId: "682ac815fba468d857d49906",
-  fields: {
-    "completed_date_abc": Date.now()
-  }
-})
-```
-
----
-
-## Getting IDs
-
-Before creating/updating, you need:
-- **Workflow ID** - from `list_workflows` (real MongoDB ObjectId)
-- **Phase ID** - from `list_workflow_phases` (real MongoDB ObjectId)
-- **Field IDs** - from `get_workflow_schema` (real MongoDB ObjectId)
-- **User IDs** - from `search_workspace_users`
-- **Activity IDs** - from `list_activities` or previous create results
-
-**CRITICAL: MCP Tools Need Real ObjectIds**
-
-MCP tools require actual MongoDB ObjectIds (24-char hex strings), not enum key names.
-
-```javascript
-// ❌ WRONG - Passing enum KEY NAMES as strings
-mcp__hailer__create_activity({
-  workflowId: "Asiakkaat",           // ❌ This is the enum key, not the ID
-  fields: { "projekti_f84": "value" } // ❌ This is the enum key, not the ID
-})
-
-// ✅ CORRECT - Use real MongoDB ObjectIds
-mcp__hailer__create_activity({
-  workflowId: "682ac815fba468d857d498f7",        // ✅ Real ObjectId
-  fields: { "68cbfec59b3869137fe2af84": "value" } // ✅ Real ObjectId
-})
-```
-
-**TypeScript code vs MCP calls:**
-- **TypeScript:** Use enums for type safety → `WorkflowIds.Asiakkaat` (resolves to the ObjectId)
-- **MCP tools:** Pass the actual ObjectId string → `"682ac815fba468d857d498f7"`
-
-**Where to get real IDs:**
-- `enums.ts` → enum values ARE the real ObjectIds
-- `list_workflows` → workflow `_id` field
-- `get_workflow_schema` → field `_id` property
-- Kenji agent → extracts IDs from workspace files
-
-**Agent pattern:** Orchestrator gets real IDs from Kenji (or enums.ts), passes to Dmitri.
-
----
-
-## Date Helpers
-
-### Current Date
-```javascript
-const now = Date.now();  // Current timestamp ms
-```
-
-### Specific Date
-```javascript
-// From string
-const date = new Date('2024-11-07T09:00:00').getTime();
-
-// From components
-const date = new Date(2024, 10, 7, 9, 0, 0).getTime();  // Month is 0-indexed!
-```
-
-### Add Days
-```javascript
-const inOneWeek = Date.now() + (7 * 24 * 60 * 60 * 1000);
-```
-
-### Start of Day
-```javascript
-const today = new Date();
-today.setHours(0, 0, 0, 0);
-const startOfDay = today.getTime();
-```
-
----
-
-## Time Field Values
-
-Time fields (`time` and `timerange`) store **Unix timestamps in milliseconds** that include the date.
-
-```javascript
-// Time field stores a full timestamp
-const timeField = 1765863000000;  // e.g., 2025-12-16 09:30:00 UTC
-
-// To extract just the time portion:
-const date = new Date(timeField);
-const hours = date.getUTCHours();    // 9
-const minutes = date.getUTCMinutes(); // 30
-
-// To create a time value for a specific time today:
-const today = new Date();
-today.setUTCHours(9, 30, 0, 0);
-const timeValue = today.getTime();
-```
-
-**Note:** When copying values between time/timerange fields, no conversion needed.
-
----
-
-## Clearing Field Values
-
-To clear a field, set to empty string or null:
-
-```javascript
-mcp__hailer__update_activity({
-  activityId: "692abc123def456",
-  fields: {
-    "assignee_abc": "",     // Clear user
-    "due_date_def": null,   // Clear date
-    "notes_ghi": ""         // Clear text
-  }
-})
-```
-
----
-
-## Common Mistakes
-
-| Wrong | Right |
-|-------|-------|
-| `{ priority: ["High"] }` | `{ priority: "High" }` (string for single select) |
-| `{ assignee: ["userId"] }` | `{ assignee: "userId" }` (string for single user) |
-| `{ customer: ["actId"] }` | `{ customer: "actId" }` (string for activitylink) |
-| `{ date: "2024-11-07" }` | `{ date: 1730937600000 }` (timestamp ms) |
-| `{ time: "09:00" }` | `{ time: 1765863000000 }` (ms timestamp) |
-| `{ datetimerange: 1730937600000 }` | `{ datetimerange: { start: 1730937600000, end: 1731024000000 } }` (OBJECT!) |
-| `{ daterange: 1730937600000 }` | `{ daterange: { start: 1730937600000, end: 1731024000000 } }` (OBJECT!) |
-| `{ textField: 300 }` | `{ textField: "300" }` (text fields must be STRINGS, even for numbers) |
-| Guessing field IDs | Get from enums or `get_workflow_schema` |
-| Bulk create with top-level teamId | Put teamId INSIDE each activity object |
-| Creating without loading this skill | Always load SDK-activity-patterns before CRUD calls |
-
----
-
-## Team Handling
-
-### Option 1: Pass teamId explicitly (recommended)
-Always include `teamId` in your create calls. For bulk mode, include it in **each activity object**.
-
-### Option 2: Workflow default team
-If the workflow has a default team set, the MCP tool auto-fills `teamId` when omitted.
-
-**Set default team:** Hailer UI → Workflow Settings → Default Team → Select team.
-
-### Common Error: "Missing team(s)" (Code 127)
-
-**Cause:** No teamId provided AND workflow has no default team AND no workspace teams found.
-
-**Fix options:**
-1. Pass `teamId` explicitly in every create call (best)
-2. Set default team on the workflow in Hailer UI
-3. Ask orchestrator/Kenji for available team IDs before creating
-
----
-
-## Checklist
-
-Before creating/updating activities:
-
-- [ ] Have workflow ID (from enum or API)
-- [ ] Have phase ID (from enum or API)
-- [ ] Have field IDs (from enum or API)
-- [ ] Have **team ID** (from teams.ts or API) — don't rely on fallbacks
-- [ ] All values are **STRINGS** for select/user/link fields (no multi-select types exist)
-- [ ] Dates are **Unix timestamps in milliseconds**
-- [ ] Times are **Unix timestamps in milliseconds** (like dates)
-- [ ] **Bulk mode:** teamId, phaseId, fields are **inside each activity object**, not top-level