@hailer/mcp 0.0.1

package/.claude/skills/local-first-skill/SKILL.md

@@ -0,0 +1,570 @@
+---
+name: local-first-skill
+description: Complete guide to local-first data access - check workspace configs before API calls to save tokens and reduce latency
+---
+
+# Local-First Data Access Skill
+
+Complete guide to using local workspace configurations before making API calls. This optimization saves 2-3 API calls per operation and hundreds of tokens by reading cached TypeScript files.
+
+## Table of Contents
+- [Quick Reference](#quick-reference)
+- [Overview](#overview)
+- [Helper Functions](#helper-functions)
+- [Decision Tree](#decision-tree)
+- [Common Patterns](#common-patterns)
+- [Benefits](#benefits)
+- [Limitations](#limitations)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Quick Reference
+
+### Get workflows from local cache
+```typescript
+const workflows = await getLocalWorkflows() || await list_workflows();
+```
+
+### Get field definitions from local cache
+```typescript
+const fields = await getLocalFields("Players") || await get_workflow_schema({...});
+```
+
+### Get phases from local cache
+```typescript
+const phases = await getLocalPhases("Players") || await list_workflow_phases({...});
+```
+
+### Get type-safe enums
+```typescript
+const enums = await getEnums();
+console.log(enums.Players_FieldIds.player_name_694);
+```
+
+## Overview
+
+The local-first strategy caches workspace metadata (workflows, fields, phases) as TypeScript files that can be imported directly. This eliminates unnecessary API calls for data that rarely changes.
+
+**What gets cached:**
+- ✅ Workflow names, IDs, structure
+- ✅ Field definitions (types, labels, keys, options)
+- ✅ Phase definitions (names, IDs, transitions)
+- ✅ Type-safe enums for field/phase IDs
+
+**What doesn't get cached:**
+- ❌ Activity data (always from API)
+- ❌ Activity counts (always from API)
+- ❌ Live status information
+
+**Performance impact:**
+- **Before**: 4 API calls to list activities (workflows → phases → schema → activities)
+- **After**: 1 API call (activities only)
+- **Savings**: 75% reduction in API calls + hundreds of tokens saved
+
+## Helper Functions
+
+Copy these functions to use local-first access:
+
+```typescript
+const WORKSPACE_PATH = process.env.WORKSPACE_CONFIG_PATH || '/home/brodolf/Desktop/footballmanager';
+
+/**
+ * Get all workflows from local cache
+ * Returns: Array of workflow objects with _id, name, folder properties
+ * Fallback: list_workflows() API call
+ */
+async function getLocalWorkflows() {
+  try {
+    const { workflows } = await import(`${WORKSPACE_PATH}/workspace/workflows.ts`);
+    return workflows;
+  } catch (error) {
+    console.log('Local workflows not found, falling back to API');
+    return null;
+  }
+}
+
+/**
+ * Get field definitions for a workflow from local cache
+ * @param workflowName - Human-readable workflow name (e.g., "Players")
+ * Returns: Array of field objects with _id, key, label, type, data properties
+ * Fallback: get_workflow_schema() API call
+ */
+async function getLocalFields(workflowName: string) {
+  try {
+    const workflows = await getLocalWorkflows();
+    const workflow = workflows?.find(w => w.name === workflowName);
+    if (!workflow) {
+      console.log(`Workflow "${workflowName}" not found in local cache`);
+      return null;
+    }
+
+    const { fields } = await import(`${WORKSPACE_PATH}/workspace/${workflow.folder}/fields.ts`);
+    return fields;
+  } catch (error) {
+    console.log(`Fields for "${workflowName}" not found, falling back to API`);
+    return null;
+  }
+}
+
+/**
+ * Get phase definitions for a workflow from local cache
+ * @param workflowName - Human-readable workflow name (e.g., "Players")
+ * Returns: Array of phase objects with _id, name, isInitial, possibleNextPhase properties
+ * Fallback: list_workflow_phases() API call
+ */
+async function getLocalPhases(workflowName: string) {
+  try {
+    const workflows = await getLocalWorkflows();
+    const workflow = workflows?.find(w => w.name === workflowName);
+    if (!workflow) {
+      console.log(`Workflow "${workflowName}" not found in local cache`);
+      return null;
+    }
+
+    const { phases } = await import(`${WORKSPACE_PATH}/workspace/${workflow.folder}/phases.ts`);
+    return phases;
+  } catch (error) {
+    console.log(`Phases for "${workflowName}" not found, falling back to API`);
+    return null;
+  }
+}
+
+/**
+ * Get type-safe enums for all workflows
+ * Returns: Object with workflow-specific enum exports (e.g., Players_FieldIds, Players_PhaseIds)
+ * Use for type-safe field/phase ID access
+ */
+async function getEnums() {
+  try {
+    return await import(`${WORKSPACE_PATH}/workspace/enums.ts`);
+  } catch (error) {
+    console.log('Enums not found in local cache');
+    return null;
+  }
+}
+
+/**
+ * Get workflow main config (permissions, order, etc.)
+ * @param workflowName - Human-readable workflow name
+ * Returns: Workflow configuration object
+ */
+async function getLocalWorkflowConfig(workflowName: string) {
+  try {
+    const workflows = await getLocalWorkflows();
+    const workflow = workflows?.find(w => w.name === workflowName);
+    if (!workflow) return null;
+
+    const { workflowConfig } = await import(`${WORKSPACE_PATH}/workspace/${workflow.folder}/main.ts`);
+    return workflowConfig;
+  } catch (error) {
+    console.log(`Config for "${workflowName}" not found`);
+    return null;
+  }
+}
+```
+
+## Decision Tree
+
+Use this flowchart to decide local vs API:
+
+```
+┌─────────────────────────────┐
+│ What data do you need?      │
+└──────────┬──────────────────┘
+           │
+           ├─> Workflow list (names, IDs, folders)
+           │   → getLocalWorkflows() || list_workflows()
+           │
+           ├─> Field definitions (types, labels, keys)
+           │   → getLocalFields("WorkflowName") || get_workflow_schema()
+           │
+           ├─> Phase definitions (names, transitions)
+           │   → getLocalPhases("WorkflowName") || list_workflow_phases()
+           │
+           ├─> Type-safe field/phase IDs
+           │   → getEnums()
+           │
+           └─> Activity data (records, counts, live values)
+               → ALWAYS use API (list_activities, show_activity_by_id)
+```
+
+## Common Patterns
+
+### Pattern 1: List Activities in a Workflow
+
+```typescript
+// ❌ BAD - Makes 4 API calls
+const workflows = await list_workflows();
+const playersWorkflow = workflows.find(w => w.name === "Players");
+const phases = await list_workflow_phases({ workflowId: playersWorkflow._id });
+const schema = await get_workflow_schema({ workflowId: playersWorkflow._id, phaseId: phases[0]._id });
+const activities = await list_activities({ workflowId: playersWorkflow._id, phaseId: phases[0]._id, fields: [...] });
+
+// ✅ GOOD - Makes 1 API call
+const workflows = await getLocalWorkflows();
+const playersWorkflow = workflows.find(w => w.name === "Players");
+const phases = await getLocalPhases("Players");
+const fields = await getLocalFields("Players");
+const activities = await list_activities({
+  workflowId: playersWorkflow._id,
+  phaseId: phases[0]._id,
+  fields: fields.slice(0, 5).map(f => f.key)
+});
+```
+
+**Savings**: 3 fewer API calls, ~500-1000 tokens saved
+
+### Pattern 2: Create Activity with Proper Field IDs
+
+```typescript
+// ❌ BAD - Hardcoded field IDs (breaks if schema changes)
+await create_activity({
+  workflowId: "691ffdf84217e9e8434e5693",
+  fields: {
+    "691ffdf84217e9e8434e5694": "Bruno Fernandes",
+    "691ffdf84217e9e8434e5695": 8
+  }
+});
+
+// ✅ GOOD - Use local cache to get field keys
+const fields = await getLocalFields("Players");
+const playerNameField = fields.find(f => f.label === "Player Name");
+const jerseyField = fields.find(f => f.label === "Jersey Number");
+
+await create_activity({
+  workflowId: "691ffdf84217e9e8434e5693",
+  fields: {
+    [playerNameField.key]: "Bruno Fernandes",
+    [jerseyField.key]: 8
+  }
+});
+
+// ✅ BEST - Use key property directly (if fields have keys)
+await create_activity({
+  workflowId: "691ffdf84217e9e8434e5693",
+  fields: {
+    playerName: "Bruno Fernandes",
+    jerseyNumber: 8
+  }
+});
+```
+
+### Pattern 3: Type-Safe Field Access with Enums
+
+```typescript
+// ✅ EXCELLENT - Type-safe with enums
+const enums = await getEnums();
+const fields = await getLocalFields("Players");
+
+// Access field by enum (autocomplete + compile-time safety)
+const playerNameFieldId = enums.Players_FieldIds.player_name_694;
+const activeSquadPhaseId = enums.Players_PhaseIds.active_squad_69f;
+
+await list_activities({
+  workflowId: "691ffdf84217e9e8434e5693",
+  phaseId: activeSquadPhaseId,
+  fields: [
+    enums.Players_FieldIds.player_name_694,
+    enums.Players_FieldIds.jersey_number_695,
+    enums.Players_FieldIds.position_696
+  ]
+});
+```
+
+### Pattern 4: Bulk Operations with Field Validation
+
+```typescript
+// ✅ GOOD - Validate field types before bulk create
+const fields = await getLocalFields("Players");
+const positionField = fields.find(f => f.key === "position");
+const validPositions = positionField.data; // ["Goalkeeper", "Defender", "Midfielder", "Forward"]
+
+// Validate before creating
+const players = [
+  { name: "Player 1", position: "Midfielder" },  // ✅ Valid
+  { name: "Player 2", position: "Striker" }      // ❌ Invalid - will fail!
+];
+
+// Pre-validate
+players.forEach(p => {
+  if (!validPositions.includes(p.position)) {
+    console.error(`Invalid position: ${p.position}. Valid: ${validPositions.join(", ")}`);
+  }
+});
+
+// Then bulk create
+await create_activity({
+  workflowId: "xxx",
+  activities: players.map(p => ({
+    name: p.name,
+    fields: { position: p.position }
+  }))
+});
+```
+
+## Benefits
+
+### 1. Performance Improvement
+
+| Operation | API Calls (Before) | API Calls (After) | Improvement |
+|-----------|-------------------|-------------------|-------------|
+| List activities | 4 | 1 | 75% faster |
+| Create activity with validation | 3 | 0 + 1 | 66% faster |
+| Update activity field | 2 | 0 + 1 | 50% faster |
+| Bulk operations | N × 3 | 0 + 1 | 90%+ faster |
+
+### 2. Token Savings
+
+- Workflow list: ~200-500 tokens saved
+- Field schema: ~300-800 tokens saved
+- Phase definitions: ~100-300 tokens saved
+- **Total per operation**: 600-1600 tokens saved
+
+### 3. Offline Capability
+
+Work with workflow structure without network:
+- Browse field definitions
+- Understand phase transitions
+- Validate data against schemas
+- Generate code with type-safe IDs
+
+### 4. Type Safety
+
+Enums provide compile-time safety:
+```typescript
+// TypeScript knows these exist and autocompletes!
+Players_FieldIds.player_name_694
+Players_PhaseIds.active_squad_69f
+```
+
+## Limitations
+
+### 1. Stale Data Risk
+
+**Problem**: Local cache doesn't update automatically when workspace changes.
+
+**Solution**: Re-run `/ws-pull` after schema changes:
+```bash
+/ws-pull  # or: npm run ws-pull
+```
+
+**When to refresh:**
+- After adding/removing workflows
+- After adding/removing fields
+- After modifying field types/options
+- After adding/removing phases
+
+### 2. No Activity Data
+
+**Problem**: Local cache has no activity records or counts.
+
+**Solution**: Always use API for activity operations:
+- `list_activities()` - Get activities
+- `show_activity_by_id()` - Get single activity
+- `create_activity()` - Create activities
+- `update_activity()` - Update activities
+
+### 3. No Live Counts
+
+**Problem**: Workflow activity counts in local cache are outdated.
+
+**Solution**: Call `list_workflows()` API if you need current counts.
+
+## Best Practices
+
+### ✅ Do This
+
+1. **Always try local first**
+   ```typescript
+   const data = await getLocalData() || await apiCall();
+   ```
+
+2. **Use meaningful workflow names**
+   ```typescript
+   // ✅ Good - readable
+   await getLocalFields("Players")
+
+   // ❌ Bad - requires ID lookup
+   await get_workflow_schema({ workflowId: "691..." })
+   ```
+
+3. **Cache helper results if used multiple times**
+   ```typescript
+   const workflows = await getLocalWorkflows();
+   // Use workflows multiple times without re-importing
+   ```
+
+4. **Run `/ws-pull` regularly**
+   - Daily for active development
+   - After schema changes
+   - When starting new features
+
+5. **Use enums for type safety**
+   ```typescript
+   const enums = await getEnums();
+   // Use enums.Players_FieldIds.* everywhere
+   ```
+
+### ❌ Avoid This
+
+1. **Don't skip local check**
+   ```typescript
+   // ❌ BAD
+   const workflows = await list_workflows();
+
+   // ✅ GOOD
+   const workflows = await getLocalWorkflows() || await list_workflows();
+   ```
+
+2. **Don't use local cache for activity data**
+   ```typescript
+   // ❌ WRONG - activities not in local cache!
+   const activities = await getLocalActivities("Players");
+
+   // ✅ CORRECT
+   const activities = await list_activities({...});
+   ```
+
+3. **Don't forget to fallback to API**
+   ```typescript
+   // ❌ BAD - fails if cache missing
+   const workflows = await getLocalWorkflows();
+
+   // ✅ GOOD - graceful fallback
+   const workflows = await getLocalWorkflows() || await list_workflows();
+   ```
+
+4. **Don't use outdated cache without warning**
+   ```typescript
+   // ✅ GOOD - Check timestamp
+   const cacheAge = Date.now() - fs.statSync(`${WORKSPACE_PATH}/workspace/workflows.ts`).mtimeMs;
+   if (cacheAge > 24 * 60 * 60 * 1000) {
+     console.warn('Local cache is >24h old. Consider running /ws-pull');
+   }
+   ```
+
+## Troubleshooting
+
+### Issue: "Cannot find module" error
+
+**Symptom:**
+```
+Error: Cannot find module '/path/to/workspace/workflows.ts'
+```
+
+**Cause**: Local cache doesn't exist or path is wrong.
+
+**Solutions:**
+1. Run `/ws-pull` to download configs
+2. Check `WORKSPACE_CONFIG_PATH` in `.env.local`
+3. Verify path exists: `ls $WORKSPACE_CONFIG_PATH/workspace/`
+
+### Issue: Workflow not found by name
+
+**Symptom:**
+```typescript
+const fields = await getLocalFields("Players");  // Returns null
+```
+
+**Cause**: Workflow name doesn't match exactly.
+
+**Solutions:**
+1. Check exact spelling/capitalization
+2. List available workflows:
+   ```typescript
+   const workflows = await getLocalWorkflows();
+   console.log(workflows.map(w => w.name));
+   ```
+3. Use workflow ID directly if name is ambiguous
+
+### Issue: Field/phase data seems outdated
+
+**Symptom**: Local data doesn't match what's in Hailer.
+
+**Cause**: Cache is stale (workspace was modified).
+
+**Solutions:**
+1. Re-run `/ws-pull` to refresh
+2. Compare timestamps:
+   ```bash
+   ls -la $WORKSPACE_CONFIG_PATH/workspace/
+   ```
+3. For critical operations, use API directly
+
+### Issue: Import fails in production
+
+**Symptom**: Works locally but fails in deployed environment.
+
+**Cause**: Workspace configs not deployed or path incorrect.
+
+**Solutions:**
+1. Ensure `WORKSPACE_CONFIG_PATH` is set correctly in production
+2. Copy workspace configs to production environment
+3. Use API fallback for production reliability
+
+### Issue: Type errors with enums
+
+**Symptom:**
+```typescript
+const enums = await getEnums();
+enums.Players_FieldIds.player_name_694;  // Type error
+```
+
+**Cause**: TypeScript doesn't recognize dynamic imports.
+
+**Solutions:**
+1. Use type assertion:
+   ```typescript
+   const enums = await getEnums() as any;
+   ```
+2. Or use direct imports (static):
+   ```typescript
+   import { Players_FieldIds } from './workspace/enums';
+   ```
+
+## Integration with MCP Tools
+
+### When to use local-first with each tool:
+
+| Tool | Local First? | Notes |
+|------|-------------|-------|
+| `list_workflows` | ✅ Yes | Use `getLocalWorkflows()` |
+| `list_workflow_phases` | ✅ Yes | Use `getLocalPhases()` |
+| `get_workflow_schema` | ✅ Yes | Use `getLocalFields()` |
+| `list_activities` | ❌ No | Always API |
+| `show_activity_by_id` | ❌ No | Always API |
+| `create_activity` | Validate with local | Get field types for validation |
+| `update_activity` | Validate with local | Check field types before update |
+| `update_workflow_field` | Check local first | Know current state before update |
+
+## Summary
+
+**Key Takeaway**: Always check local cache before API calls for workflow metadata.
+
+**Pattern to remember:**
+```typescript
+const data = await getLocalData() || await apiCall();
+```
+
+**Benefits:**
+- 75% fewer API calls
+- 600-1600 tokens saved per operation
+- Faster response times
+- Offline-capable development
+- Type-safe field/phase access
+
+**Next steps:**
+1. Run `/ws-pull` to set up local cache
+2. Copy helper functions into your code
+3. Replace direct API calls with local-first pattern
+4. Use enums for type-safe IDs
+5. Refresh cache regularly
+
+---
+
+**Related Skills:**
+- `list-workflows-minimal-skill` - Minimal API calls for workflow listing
+- `install-workflow-skill` - Creating workflows (uses local patterns)
+- `update-workflow-field-skill` - Modifying fields (validate with local data)
+
+**Last Updated**: 2025-11-24