@hailer/mcp 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/.claude/commands/tool-builder.md +37 -0
  2. package/.claude/commands/ws-pull.md +44 -0
  3. package/.claude/settings.json +8 -0
  4. package/.claude/settings.local.json +49 -0
  5. package/.claude/skills/activity-api/SKILL.md +96 -0
  6. package/.claude/skills/activity-api/references/activity-endpoints.md +845 -0
  7. package/.claude/skills/add-app-member-skill/SKILL.md +977 -0
  8. package/.claude/skills/agent-building/SKILL.md +243 -0
  9. package/.claude/skills/agent-building/references/architecture-patterns.md +446 -0
  10. package/.claude/skills/agent-building/references/code-examples.md +587 -0
  11. package/.claude/skills/agent-building/references/implementation-guide.md +619 -0
  12. package/.claude/skills/app-api/SKILL.md +219 -0
  13. package/.claude/skills/app-api/references/app-endpoints.md +759 -0
  14. package/.claude/skills/building-hailer-apps-skill/SKILL.md +548 -0
  15. package/.claude/skills/create-app-skill/SKILL.md +1101 -0
  16. package/.claude/skills/create-insight-skill/SKILL.md +1317 -0
  17. package/.claude/skills/get-insight-data-skill/SKILL.md +1053 -0
  18. package/.claude/skills/hailer-api/SKILL.md +283 -0
  19. package/.claude/skills/hailer-api/references/activities.md +620 -0
  20. package/.claude/skills/hailer-api/references/authentication.md +216 -0
  21. package/.claude/skills/hailer-api/references/datasets.md +437 -0
  22. package/.claude/skills/hailer-api/references/files.md +301 -0
  23. package/.claude/skills/hailer-api/references/insights.md +469 -0
  24. package/.claude/skills/hailer-api/references/workflows.md +720 -0
  25. package/.claude/skills/hailer-api/references/workspaces-users.md +445 -0
  26. package/.claude/skills/insight-api/SKILL.md +185 -0
  27. package/.claude/skills/insight-api/references/insight-endpoints.md +514 -0
  28. package/.claude/skills/install-workflow-skill/SKILL.md +1056 -0
  29. package/.claude/skills/list-apps-skill/SKILL.md +1010 -0
  30. package/.claude/skills/list-workflows-minimal-skill/SKILL.md +992 -0
  31. package/.claude/skills/local-first-skill/SKILL.md +570 -0
  32. package/.claude/skills/mcp-tools/SKILL.md +419 -0
  33. package/.claude/skills/mcp-tools/references/api-endpoints.md +499 -0
  34. package/.claude/skills/mcp-tools/references/data-structures.md +554 -0
  35. package/.claude/skills/mcp-tools/references/implementation-patterns.md +717 -0
  36. package/.claude/skills/preview-insight-skill/SKILL.md +1290 -0
  37. package/.claude/skills/publish-hailer-app-skill/SKILL.md +453 -0
  38. package/.claude/skills/remove-app-member-skill/SKILL.md +671 -0
  39. package/.claude/skills/remove-app-skill/SKILL.md +985 -0
  40. package/.claude/skills/remove-insight-skill/SKILL.md +1011 -0
  41. package/.claude/skills/remove-workflow-skill/SKILL.md +920 -0
  42. package/.claude/skills/scaffold-hailer-app-skill/SKILL.md +1034 -0
  43. package/.claude/skills/skill-testing/README.md +137 -0
  44. package/.claude/skills/skill-testing/SKILL.md +348 -0
  45. package/.claude/skills/skill-testing/references/test-patterns.md +705 -0
  46. package/.claude/skills/skill-testing/references/testing-guide.md +603 -0
  47. package/.claude/skills/skill-testing/references/validation-checklist.md +537 -0
  48. package/.claude/skills/tool-builder/SKILL.md +328 -0
  49. package/.claude/skills/update-app-skill/SKILL.md +970 -0
  50. package/.claude/skills/update-workflow-field-skill/SKILL.md +1098 -0
  51. package/.env.example +81 -0
  52. package/.mcp.json +13 -0
  53. package/README.md +297 -0
  54. package/dist/app.d.ts +4 -0
  55. package/dist/app.js +74 -0
  56. package/dist/cli.d.ts +3 -0
  57. package/dist/cli.js +5 -0
  58. package/dist/client/adaptive-documentation-bot.d.ts +108 -0
  59. package/dist/client/adaptive-documentation-bot.js +475 -0
  60. package/dist/client/adaptive-documentation-types.d.ts +66 -0
  61. package/dist/client/adaptive-documentation-types.js +9 -0
  62. package/dist/client/agent-activity-bot.d.ts +51 -0
  63. package/dist/client/agent-activity-bot.js +166 -0
  64. package/dist/client/agent-tracker.d.ts +499 -0
  65. package/dist/client/agent-tracker.js +659 -0
  66. package/dist/client/description-updater.d.ts +56 -0
  67. package/dist/client/description-updater.js +259 -0
  68. package/dist/client/log-parser.d.ts +72 -0
  69. package/dist/client/log-parser.js +387 -0
  70. package/dist/client/mcp-client.d.ts +50 -0
  71. package/dist/client/mcp-client.js +532 -0
  72. package/dist/client/message-processor.d.ts +35 -0
  73. package/dist/client/message-processor.js +352 -0
  74. package/dist/client/multi-bot-manager.d.ts +24 -0
  75. package/dist/client/multi-bot-manager.js +74 -0
  76. package/dist/client/providers/anthropic-provider.d.ts +19 -0
  77. package/dist/client/providers/anthropic-provider.js +631 -0
  78. package/dist/client/providers/llm-provider.d.ts +47 -0
  79. package/dist/client/providers/llm-provider.js +367 -0
  80. package/dist/client/providers/openai-provider.d.ts +23 -0
  81. package/dist/client/providers/openai-provider.js +621 -0
  82. package/dist/client/simple-llm-caller.d.ts +19 -0
  83. package/dist/client/simple-llm-caller.js +100 -0
  84. package/dist/client/skill-generator.d.ts +81 -0
  85. package/dist/client/skill-generator.js +386 -0
  86. package/dist/client/test-adaptive-bot.d.ts +9 -0
  87. package/dist/client/test-adaptive-bot.js +82 -0
  88. package/dist/client/token-pricing.d.ts +38 -0
  89. package/dist/client/token-pricing.js +127 -0
  90. package/dist/client/token-tracker.d.ts +232 -0
  91. package/dist/client/token-tracker.js +457 -0
  92. package/dist/client/token-usage-bot.d.ts +53 -0
  93. package/dist/client/token-usage-bot.js +153 -0
  94. package/dist/client/tool-executor.d.ts +69 -0
  95. package/dist/client/tool-executor.js +159 -0
  96. package/dist/client/tool-schema-loader.d.ts +60 -0
  97. package/dist/client/tool-schema-loader.js +178 -0
  98. package/dist/client/types.d.ts +69 -0
  99. package/dist/client/types.js +7 -0
  100. package/dist/config.d.ts +162 -0
  101. package/dist/config.js +296 -0
  102. package/dist/core.d.ts +26 -0
  103. package/dist/core.js +147 -0
  104. package/dist/lib/context-manager.d.ts +111 -0
  105. package/dist/lib/context-manager.js +431 -0
  106. package/dist/lib/logger.d.ts +74 -0
  107. package/dist/lib/logger.js +277 -0
  108. package/dist/lib/materialize.d.ts +3 -0
  109. package/dist/lib/materialize.js +101 -0
  110. package/dist/lib/normalizedName.d.ts +7 -0
  111. package/dist/lib/normalizedName.js +48 -0
  112. package/dist/lib/prompt-length-manager.d.ts +81 -0
  113. package/dist/lib/prompt-length-manager.js +457 -0
  114. package/dist/lib/terminal-prompt.d.ts +9 -0
  115. package/dist/lib/terminal-prompt.js +108 -0
  116. package/dist/mcp/UserContextCache.d.ts +56 -0
  117. package/dist/mcp/UserContextCache.js +163 -0
  118. package/dist/mcp/auth.d.ts +2 -0
  119. package/dist/mcp/auth.js +29 -0
  120. package/dist/mcp/hailer-clients.d.ts +42 -0
  121. package/dist/mcp/hailer-clients.js +246 -0
  122. package/dist/mcp/signal-handler.d.ts +45 -0
  123. package/dist/mcp/signal-handler.js +317 -0
  124. package/dist/mcp/tool-registry.d.ts +100 -0
  125. package/dist/mcp/tool-registry.js +306 -0
  126. package/dist/mcp/tools/activity.d.ts +15 -0
  127. package/dist/mcp/tools/activity.js +955 -0
  128. package/dist/mcp/tools/app.d.ts +20 -0
  129. package/dist/mcp/tools/app.js +1488 -0
  130. package/dist/mcp/tools/discussion.d.ts +19 -0
  131. package/dist/mcp/tools/discussion.js +950 -0
  132. package/dist/mcp/tools/file.d.ts +15 -0
  133. package/dist/mcp/tools/file.js +119 -0
  134. package/dist/mcp/tools/insight.d.ts +17 -0
  135. package/dist/mcp/tools/insight.js +806 -0
  136. package/dist/mcp/tools/skill.d.ts +10 -0
  137. package/dist/mcp/tools/skill.js +279 -0
  138. package/dist/mcp/tools/user.d.ts +10 -0
  139. package/dist/mcp/tools/user.js +108 -0
  140. package/dist/mcp/tools/workflow-template.d.ts +19 -0
  141. package/dist/mcp/tools/workflow-template.js +822 -0
  142. package/dist/mcp/tools/workflow.d.ts +18 -0
  143. package/dist/mcp/tools/workflow.js +1362 -0
  144. package/dist/mcp/utils/api-errors.d.ts +45 -0
  145. package/dist/mcp/utils/api-errors.js +160 -0
  146. package/dist/mcp/utils/data-transformers.d.ts +102 -0
  147. package/dist/mcp/utils/data-transformers.js +194 -0
  148. package/dist/mcp/utils/file-upload.d.ts +33 -0
  149. package/dist/mcp/utils/file-upload.js +148 -0
  150. package/dist/mcp/utils/hailer-api-client.d.ts +120 -0
  151. package/dist/mcp/utils/hailer-api-client.js +323 -0
  152. package/dist/mcp/utils/index.d.ts +13 -0
  153. package/dist/mcp/utils/index.js +39 -0
  154. package/dist/mcp/utils/logger.d.ts +42 -0
  155. package/dist/mcp/utils/logger.js +103 -0
  156. package/dist/mcp/utils/types.d.ts +286 -0
  157. package/dist/mcp/utils/types.js +7 -0
  158. package/dist/mcp/workspace-cache.d.ts +42 -0
  159. package/dist/mcp/workspace-cache.js +97 -0
  160. package/dist/mcp-server.d.ts +42 -0
  161. package/dist/mcp-server.js +280 -0
  162. package/package.json +56 -0
  163. package/tsconfig.json +23 -0
@@ -0,0 +1,920 @@
1
+ ---
2
+ name: Removing Hailer Workflows
3
+ description: Complete guide for safely removing Hailer workflows - use when deleting workflows or cleaning up workspace
4
+ ---
5
+
6
+ # Removing Hailer Workflows - Complete Guide
7
+
8
+ Complete reference for safely removing Hailer workflows using the `remove_workflow` MCP tool.
9
+
10
+ ## Table of Contents
11
+ 1. [Quick Reference](#quick-reference)
12
+ 2. [Overview](#overview)
13
+ 3. [What Gets Deleted](#what-gets-deleted)
14
+ 4. [Prerequisites](#prerequisites)
15
+ 5. [Basic Usage](#basic-usage)
16
+ 6. [Safety Checklist](#safety-checklist)
17
+ 7. [Common Scenarios](#common-scenarios)
18
+ 8. [Before Removing](#before-removing)
19
+ 9. [After Removing](#after-removing)
20
+ 10. [Troubleshooting](#troubleshooting)
21
+ 11. [Best Practices](#best-practices)
22
+
23
+ ## Quick Reference
24
+
25
+ **⚠️ DANGER: This operation is PERMANENT and CANNOT be undone!**
26
+
27
+ **Basic Removal:**
28
+
29
+ ```javascript
30
+ remove_workflow({
31
+ workflowId: "68446dc05b30685f67c6fcd4"
32
+ })
33
+ ```
34
+
35
+ **With Workspace Specification:**
36
+
37
+ ```javascript
38
+ remove_workflow({
39
+ workflowId: "68446dc05b30685f67c6fcd4",
40
+ workspaceId: "6901c67b4e80fecb6fd7b38a" // Optional
41
+ })
42
+ ```
43
+
44
+ **Key Requirements:**
45
+ - User must be workspace administrator
46
+ - Workflow ID must be valid and exist
47
+ - Cannot be undone - all data permanently deleted
48
+ - Affects: workflow, activities, discussions, relationships
49
+
50
+ ## Overview
51
+
52
+ The `remove_workflow` tool permanently deletes a workflow (also called a "process") from your Hailer workspace. This is a **destructive operation** that removes not just the workflow structure, but all associated data.
53
+
54
+ **Think of it as:**
55
+ - Dropping a database table AND all its rows
56
+ - Deleting the schema AND all records
57
+ - Removing structure AND content permanently
58
+
59
+ **When to use:**
60
+ - Cleaning up test/development workflows
61
+ - Removing unused or obsolete workflows
62
+ - Workspace reorganization
63
+ - Decommissioning old processes
64
+
65
+ **When NOT to use:**
66
+ - If you might need the data later (export first)
67
+ - If other workflows reference it via ActivityLinks
68
+ - If you're unsure about dependencies
69
+ - For temporary workflow deactivation (use phases instead)
70
+
71
+ ## What Gets Deleted
72
+
73
+ ### 1. The Workflow Structure
74
+ - Workflow definition (name, description)
75
+ - All field definitions
76
+ - All phase definitions
77
+ - Workflow configuration settings
78
+ - View settings (timeline, kanban, etc.)
79
+
80
+ ### 2. All Activities (Records)
81
+ Every activity in the workflow is permanently deleted:
82
+ - Activity names and content
83
+ - All field values
84
+ - Activity metadata (created date, updated date, creator)
85
+ - Activity phase assignments
86
+ - Team/user assignments
87
+
88
+ ### 3. All Discussions
89
+ Every discussion thread linked to activities in the workflow:
90
+ - Discussion messages
91
+ - Message history
92
+ - Attachments in discussions
93
+ - Discussion participants
94
+ - Read receipts and notifications
95
+
96
+ ### 4. Relationship Data
97
+ - ActivityLink references FROM this workflow TO other workflows
98
+ - May break ActivityLink references FROM other workflows TO this workflow (see warnings)
99
+
100
+ ### What Does NOT Get Deleted
101
+ - Files attached to activities (files remain in file storage but lose association)
102
+ - Users who participated in discussions
103
+ - Insights that query this workflow (will break and show errors)
104
+ - Other workflows that reference this workflow (links will break)
105
+
106
+ ## Prerequisites
107
+
108
+ ### Required Permissions
109
+ **User must be workspace administrator**
110
+
111
+ Check your permissions:
112
+ ```javascript
113
+ get_current_workspace()
114
+ // Look for your user role - must be admin
115
+ ```
116
+
117
+ If you don't have admin permissions:
118
+ - You'll get "Permission Denied" error
119
+ - Contact workspace administrator
120
+ - Cannot be bypassed
121
+
122
+ ### Required Information
123
+
124
+ **1. Workflow ID**
125
+
126
+ Get workflow ID from `list_workflows`:
127
+ ```javascript
128
+ list_workflows()
129
+ // Returns list with _id field for each workflow
130
+ ```
131
+
132
+ **2. Workflow Dependencies**
133
+
134
+ Check if other workflows reference this workflow:
135
+ ```javascript
136
+ list_workflows()
137
+ // Look for ActivityLink fields with data: ["target-workflow-id"]
138
+ ```
139
+
140
+ ## Basic Usage
141
+
142
+ ### Example 1: Remove Simple Workflow
143
+
144
+ ```javascript
145
+ // 1. Find the workflow
146
+ list_workflows()
147
+ // Output shows: { _id: "68446dc05b30685f67c6fcd4", name: "Test Tasks" }
148
+
149
+ // 2. Remove it
150
+ remove_workflow({
151
+ workflowId: "68446dc05b30685f67c6fcd4"
152
+ })
153
+
154
+ // Output:
155
+ // ✅ Workflow Removed Successfully
156
+ // Workflow: Test Tasks
157
+ // Workflow ID: 68446dc05b30685f67c6fcd4
158
+ // ⚠️ All activities and discussions permanently deleted
159
+ ```
160
+
161
+ ### Example 2: Remove in Specific Workspace
162
+
163
+ ```javascript
164
+ // Useful when managing multiple workspaces
165
+ remove_workflow({
166
+ workflowId: "68446dc05b30685f67c6fcd4",
167
+ workspaceId: "6901c67b4e80fecb6fd7b38a"
168
+ })
169
+ ```
170
+
171
+ ### Example 3: Remove with Verification
172
+
173
+ ```javascript
174
+ // 1. List workflows to verify
175
+ const workflows = list_workflows();
176
+ console.log(workflows);
177
+
178
+ // 2. Get workflow details
179
+ const schema = get_workflow_schema({
180
+ workflowId: "68446dc05b30685f67c6fcd4"
181
+ });
182
+ console.log("Removing workflow:", schema.name);
183
+
184
+ // 3. Check for activities
185
+ const activities = list_activities({
186
+ workflowId: "68446dc05b30685f67c6fcd4",
187
+ limit: 1
188
+ });
189
+ console.log("Activity count:", activities.total);
190
+
191
+ // 4. Confirm and remove
192
+ remove_workflow({
193
+ workflowId: "68446dc05b30685f67c6fcd4"
194
+ })
195
+ ```
196
+
197
+ ## ⚠️ MANDATORY: Comprehensive Confirmation Protocol
198
+
199
+ **BEFORE calling `remove_workflow`, you MUST gather complete context and show it to the user:**
200
+
201
+ ### Required Context to Gather
202
+
203
+ 1. **Workspace Information:**
204
+ - Workspace ID: Get from `list_workflows` response
205
+ - Workspace name: Get from API init or workflow data
206
+
207
+ 2. **Workflow Information:**
208
+ - Workflow ID (provided by user)
209
+ - Workflow name: Get from `list_workflows`
210
+ - Activity count: Get from `list_workflows` (createdActivities field)
211
+
212
+ 3. **Impact Analysis:**
213
+ - Other workflows linking TO this workflow: Check `list_workflows` for ActivityLink fields with `data` containing this workflow ID
214
+ - List affected workflows by name
215
+
216
+ ### Required Confirmation Message Format
217
+
218
+ **You MUST display this information to the user BEFORE calling the tool:**
219
+
220
+ ```
221
+ ⚠️ WARNING: This action is irreversible!
222
+
223
+ You are about to permanently delete the following:
224
+
225
+ **Workspace**:
226
+ - Workspace ID: `<workspace-id>`
227
+ - Workspace name: <workspace-name>
228
+
229
+ **Workflow to Delete**:
230
+ - Name: <workflow-name>
231
+ - ID: `<workflow-id>`
232
+
233
+ **What Will Be Lost**:
234
+ - ❌ The workflow structure and all fields
235
+ - ❌ **<activity-count> activities** will be permanently deleted
236
+ - ❌ All associated discussions will be deleted
237
+ - ❌ All workflow configuration will be lost
238
+
239
+ **⚠️ Impact on Other Workflows**:
240
+ - The **<Workflow A>** workflow has activity links pointing to this workflow
241
+ - The **<Workflow B>** workflow has activity links pointing to this workflow
242
+ - These links will be broken after deletion
243
+
244
+ **This operation cannot be undone. All data will be permanently lost.**
245
+
246
+ Do you want to proceed with permanently deleting this workflow?
247
+ ```
248
+
249
+ ### Example: Complete Safe Removal Flow
250
+
251
+ ```javascript
252
+ // Step 1: Gather complete context
253
+ const workflows = list_workflows()
254
+ const targetWorkflow = workflows.find(w => w._id === "target-id")
255
+
256
+ // Step 2: Identify affected workflows
257
+ const affectedWorkflows = workflows.filter(w => {
258
+ const hasLink = Object.values(w.fields || {}).some(field =>
259
+ field.type === 'activitylink' &&
260
+ (field.data || []).includes(targetWorkflow._id)
261
+ )
262
+ return hasLink
263
+ })
264
+
265
+ // Step 3: Show comprehensive confirmation message to user
266
+ console.log(`
267
+ ⚠️ WARNING: This action is irreversible!
268
+
269
+ **Workspace**:
270
+ - Workspace ID: \`${targetWorkflow.workspaceId}\`
271
+ - Workspace name: ${workspaceName}
272
+
273
+ **Workflow to Delete**:
274
+ - Name: ${targetWorkflow.name}
275
+ - ID: \`${targetWorkflow._id}\`
276
+
277
+ **What Will Be Lost**:
278
+ - ❌ The workflow structure and all fields
279
+ - ❌ **${targetWorkflow.activityCount} activities** will be permanently deleted
280
+ - ❌ All associated discussions will be deleted
281
+
282
+ **⚠️ Impact on Other Workflows**:
283
+ ${affectedWorkflows.map(w => `- The **${w.name}** workflow has activity links pointing to this workflow`).join('\n')}
284
+
285
+ This operation cannot be undone.
286
+ `)
287
+
288
+ // Step 4: Wait for explicit user confirmation
289
+
290
+ // Step 5: Only after confirmation, call the tool
291
+ remove_workflow({ workflowId: targetWorkflow._id })
292
+ ```
293
+
294
+ ### **FAILURE TO GATHER AND SHOW THIS CONTEXT IS AN ERROR**
295
+
296
+ If you call `remove_workflow` without first gathering and displaying all this information to the user, you are violating safety protocols.
297
+
298
+ ## Safety Checklist
299
+
300
+ **Before removing ANY workflow, complete this checklist:**
301
+
302
+ ### Step 1: Identify the Workflow
303
+ - [ ] Confirmed workflow name with `list_workflows`
304
+ - [ ] Verified workflow ID is correct
305
+ - [ ] Checked workflow contains expected data
306
+
307
+ ### Step 2: Check Dependencies
308
+ - [ ] Searched for workflows with ActivityLinks to this workflow
309
+ - [ ] Identified any insights that query this workflow
310
+ - [ ] Reviewed apps that might reference this workflow
311
+ - [ ] Checked if data is referenced in documentation/reports
312
+
313
+ ### Step 3: Export Data (If Needed)
314
+ - [ ] Exported activities with `list_activities` if backup needed
315
+ - [ ] Saved workflow schema with `get_workflow_schema`
316
+ - [ ] Documented field definitions and relationships
317
+ - [ ] Archived any important discussions
318
+
319
+ ### Step 4: Notify Stakeholders
320
+ - [ ] Informed users who work with this workflow
321
+ - [ ] Updated documentation that references workflow
322
+ - [ ] Communicated removal timeline
323
+ - [ ] Provided alternative workflows if applicable
324
+
325
+ ### Step 5: Verify Permissions
326
+ - [ ] Confirmed you have workspace admin rights
327
+ - [ ] Checked with other admins if unsure
328
+ - [ ] Verified no organizational policies prevent removal
329
+
330
+ ### Step 6: Final Confirmation
331
+ - [ ] Double-checked workflow ID one more time
332
+ - [ ] Confirmed this is the intended workflow to remove
333
+ - [ ] Accepted that this cannot be undone
334
+ - [ ] Ready to proceed with deletion
335
+
336
+ ## Common Scenarios
337
+
338
+ ### Scenario 1: Clean Up Test Workflows
339
+
340
+ **Situation:** Created test workflows during development/training.
341
+
342
+ **Steps:**
343
+ ```javascript
344
+ // 1. List all workflows
345
+ list_workflows()
346
+
347
+ // 2. Identify test workflows (look for "test", "demo", "sandbox" in names)
348
+ // Example IDs: "test-workflow-id-1", "test-workflow-id-2"
349
+
350
+ // 3. Remove each test workflow
351
+ remove_workflow({ workflowId: "test-workflow-id-1" })
352
+ remove_workflow({ workflowId: "test-workflow-id-2" })
353
+
354
+ // 4. Verify removal
355
+ list_workflows()
356
+ ```
357
+
358
+ ### Scenario 2: Replace Workflow with Improved Version
359
+
360
+ **Situation:** Created new workflow to replace old one.
361
+
362
+ **Steps:**
363
+ ```javascript
364
+ // 1. Install new workflow
365
+ install_workflow({
366
+ workflowTemplates: [{ _id: '_0001', name: 'Tasks v2', ... }]
367
+ })
368
+ // Returns new workflow ID
369
+
370
+ // 2. Migrate data (manually or with script)
371
+ // - Export old activities with list_activities
372
+ // - Create new activities in new workflow
373
+
374
+ // 3. Update ActivityLinks in other workflows
375
+ update_workflow_field({
376
+ workflowId: "other-workflow-id",
377
+ fieldId: "link-field-id",
378
+ fieldData: {
379
+ data: ["new-workflow-id"] // Point to new workflow
380
+ }
381
+ })
382
+
383
+ // 4. Remove old workflow
384
+ remove_workflow({
385
+ workflowId: "old-workflow-id"
386
+ })
387
+ ```
388
+
389
+ ### Scenario 3: Remove Unused Workflow
390
+
391
+ **Situation:** Workflow exists but no longer used.
392
+
393
+ **Steps:**
394
+ ```javascript
395
+ // 1. Verify no recent activity
396
+ list_activities({
397
+ workflowId: "workflow-id",
398
+ limit: 10
399
+ })
400
+ // Check if any activities or all old
401
+
402
+ // 2. Check for dependencies
403
+ list_workflows()
404
+ // Search for ActivityLinks referencing this workflow
405
+
406
+ // 3. Export for archive (if needed)
407
+ const activities = list_activities({
408
+ workflowId: "workflow-id",
409
+ limit: 1000
410
+ })
411
+ // Save to file for records
412
+
413
+ // 4. Remove workflow
414
+ remove_workflow({
415
+ workflowId: "workflow-id"
416
+ })
417
+ ```
418
+
419
+ ### Scenario 4: Cascade Deletion (Related Workflows)
420
+
421
+ **Situation:** Need to remove related workflows (parent and children).
422
+
423
+ **Steps:**
424
+ ```javascript
425
+ // Example: Projects → Tasks hierarchy
426
+
427
+ // 1. Remove child workflows FIRST
428
+ remove_workflow({ workflowId: "tasks-workflow-id" })
429
+
430
+ // 2. Then remove parent workflow
431
+ remove_workflow({ workflowId: "projects-workflow-id" })
432
+
433
+ // Note: Removing parent first would break ActivityLinks in children
434
+ ```
435
+
436
+ ### Scenario 5: Partial Cleanup
437
+
438
+ **Situation:** Want to remove workflow but preserve some data.
439
+
440
+ **Steps:**
441
+ ```javascript
442
+ // 1. Export important activities
443
+ const activities = list_activities({
444
+ workflowId: "old-workflow-id",
445
+ filters: [{ field: "status", operator: "eq", value: "Important" }]
446
+ })
447
+ // Save to external storage
448
+
449
+ // 2. Create new workflow for preserved data
450
+ install_workflow({ ... })
451
+
452
+ // 3. Manually recreate important activities
453
+ activities.forEach(activity => {
454
+ create_activity({
455
+ workflowId: "new-workflow-id",
456
+ name: activity.name,
457
+ fields: { ... }
458
+ })
459
+ })
460
+
461
+ // 4. Remove old workflow
462
+ remove_workflow({ workflowId: "old-workflow-id" })
463
+ ```
464
+
465
+ ## Before Removing
466
+
467
+ ### Check for ActivityLink References
468
+
469
+ **Other workflows might link TO this workflow:**
470
+
471
+ ```javascript
472
+ // 1. List all workflows
473
+ const workflows = list_workflows()
474
+
475
+ // 2. Check each workflow's schema
476
+ workflows.forEach(workflow => {
477
+ const schema = get_workflow_schema({ workflowId: workflow._id })
478
+
479
+ // 3. Look for ActivityLink fields
480
+ const activityLinks = schema.fields.filter(field =>
481
+ field.type === 'activitylink' &&
482
+ field.data.includes("target-workflow-id")
483
+ )
484
+
485
+ if (activityLinks.length > 0) {
486
+ console.log(`⚠️ Workflow "${workflow.name}" has links to target workflow`)
487
+ }
488
+ })
489
+ ```
490
+
491
+ **What happens to broken links:**
492
+ - Activities with links to removed workflow will keep field values
493
+ - But linked activities won't be accessible (broken reference)
494
+ - UI will show "Activity not found" or similar error
495
+
496
+ ### Check for Insights
497
+
498
+ **Insights query workflows:**
499
+
500
+ ```javascript
501
+ // 1. List insights
502
+ list_insights()
503
+
504
+ // 2. Check each insight's sources
505
+ insights.forEach(insight => {
506
+ if (insight.sources.some(s => s.workflowId === "target-workflow-id")) {
507
+ console.log(`⚠️ Insight "${insight.name}" queries this workflow`)
508
+ }
509
+ })
510
+ ```
511
+
512
+ **What happens to broken insights:**
513
+ - Insights will show errors when executed
514
+ - Must update or remove affected insights manually
515
+
516
+ ### Export Data for Backup
517
+
518
+ **Export activities:**
519
+ ```javascript
520
+ // Get all activities (paginate if needed)
521
+ const activities = list_activities({
522
+ workflowId: "workflow-id",
523
+ limit: 1000,
524
+ returnFlat: true
525
+ })
526
+
527
+ // Save to JSON file or database
528
+ console.log(JSON.stringify(activities, null, 2))
529
+ ```
530
+
531
+ **Export schema:**
532
+ ```javascript
533
+ const schema = get_workflow_schema({
534
+ workflowId: "workflow-id"
535
+ })
536
+
537
+ // Save schema definition
538
+ console.log(JSON.stringify(schema, null, 2))
539
+ ```
540
+
541
+ ## After Removing
542
+
543
+ ### Verify Removal
544
+
545
+ ```javascript
546
+ // 1. Check workflow list
547
+ list_workflows()
548
+ // Removed workflow should not appear
549
+
550
+ // 2. Try to access workflow (should fail)
551
+ get_workflow_schema({
552
+ workflowId: "removed-workflow-id"
553
+ })
554
+ // Should return error: "Workflow not found"
555
+ ```
556
+
557
+ ### Update Documentation
558
+
559
+ - Update workspace documentation
560
+ - Remove workflow references from guides
561
+ - Update team training materials
562
+ - Archive workflow specifications
563
+
564
+ ### Fix Broken References
565
+
566
+ **Update ActivityLinks in other workflows:**
567
+ ```javascript
568
+ update_workflow_field({
569
+ workflowId: "other-workflow-id",
570
+ fieldId: "link-field-id",
571
+ fieldData: {
572
+ data: [] // Remove reference or update to new workflow
573
+ }
574
+ })
575
+ ```
576
+
577
+ **Update or remove affected insights:**
578
+ ```javascript
579
+ // Option 1: Remove insight
580
+ remove_insight({
581
+ insightId: "affected-insight-id"
582
+ })
583
+
584
+ // Option 2: Update insight sources
585
+ // (Must use update_insight tool - not in current tool set)
586
+ ```
587
+
588
+ ### Clean Up Related Data
589
+
590
+ **Remove associated apps if any:**
591
+ ```javascript
592
+ list_apps()
593
+ // Check for apps that were specific to removed workflow
594
+
595
+ remove_app({
596
+ appId: "app-id"
597
+ })
598
+ ```
599
+
600
+ ## Troubleshooting
601
+
602
+ ### Error: "Permission Denied"
603
+
604
+ **Cause:** User is not workspace administrator.
605
+
606
+ **Solution:**
607
+ - Contact workspace administrator
608
+ - Request admin permissions
609
+ - Have admin perform removal
610
+ - Cannot be bypassed - security requirement
611
+
612
+ **Verification:**
613
+ ```javascript
614
+ get_current_workspace()
615
+ // Check your role - must show admin privileges
616
+ ```
617
+
618
+ ### Error: "Workflow Not Found"
619
+
620
+ **Cause:** Workflow ID is invalid or workflow already deleted.
621
+
622
+ **Solutions:**
623
+
624
+ 1. **Verify workflow ID:**
625
+ ```javascript
626
+ list_workflows()
627
+ // Check if workflow exists in list
628
+ ```
629
+
630
+ 2. **Check workspace context:**
631
+ ```javascript
632
+ get_current_workspace()
633
+ // Ensure you're in correct workspace
634
+ ```
635
+
636
+ 3. **Try with explicit workspace ID:**
637
+ ```javascript
638
+ remove_workflow({
639
+ workflowId: "workflow-id",
640
+ workspaceId: "workspace-id"
641
+ })
642
+ ```
643
+
644
+ ### Error: "Workflow is referenced by other workflows"
645
+
646
+ **Note:** This error may not be shown by API, but is a logical concern.
647
+
648
+ **Solution:**
649
+
650
+ 1. **Find references:**
651
+ ```javascript
652
+ // Check all workflows for ActivityLinks
653
+ list_workflows().forEach(workflow => {
654
+ const schema = get_workflow_schema({ workflowId: workflow._id })
655
+ // Look for activitylink fields with data containing target workflow
656
+ })
657
+ ```
658
+
659
+ 2. **Update references first:**
660
+ ```javascript
661
+ // Remove or update ActivityLink fields pointing to this workflow
662
+ update_workflow_field({
663
+ workflowId: "referencing-workflow-id",
664
+ fieldId: "link-field-id",
665
+ fieldData: { data: [] } // Remove reference
666
+ })
667
+ ```
668
+
669
+ 3. **Then remove workflow:**
670
+ ```javascript
671
+ remove_workflow({ workflowId: "target-workflow-id" })
672
+ ```
673
+
674
+ ### Error: "Network Error" or Timeout
675
+
676
+ **Cause:** Workflow has large number of activities/discussions.
677
+
678
+ **Solution:**
679
+ - Wait for operation to complete (may take time)
680
+ - Retry if timeout occurs
681
+ - Check server logs if persistent
682
+ - Contact support for very large workflows
683
+
684
+ ### Workflow Removed But Still Appears
685
+
686
+ **Cause:** Cache not updated.
687
+
688
+ **Solution:**
689
+ ```javascript
690
+ // Refresh workspace cache
691
+ get_current_workspace()
692
+ list_workflows()
693
+ ```
694
+
695
+ ### Accidentally Removed Wrong Workflow
696
+
697
+ **Reality Check:** **Cannot be undone.**
698
+
699
+ **Mitigation steps:**
700
+
701
+ 1. **If you have backup:**
702
+ - Reinstall workflow with `install_workflow`
703
+ - Manually recreate activities from backup
704
+ - Will have different IDs - references broken
705
+
706
+ 2. **If no backup:**
707
+ - Data is permanently lost
708
+ - Contact Hailer support (may have database backups)
709
+ - Implement backup procedures for future
710
+
711
+ 3. **Prevention:**
712
+ - Always verify workflow ID before removing
713
+ - Use descriptive workflow names
714
+ - Export data before removal
715
+ - Test in development workspace first
716
+
717
+ ## Best Practices
718
+
719
+ ### 1. Always Verify Before Removing
720
+
721
+ **Bad:**
722
+ ```javascript
723
+ // Removed without checking
724
+ remove_workflow({ workflowId: "some-id" })
725
+ ```
726
+
727
+ **Good:**
728
+ ```javascript
729
+ // 1. Verify workflow
730
+ const workflows = list_workflows()
731
+ const target = workflows.find(w => w._id === "some-id")
732
+ console.log("About to remove:", target.name)
733
+
734
+ // 2. Check activity count
735
+ const activities = list_activities({ workflowId: "some-id", limit: 1 })
736
+ console.log("Contains activities:", activities.total)
737
+
738
+ // 3. Confirm and remove
739
+ remove_workflow({ workflowId: "some-id" })
740
+ ```
741
+
742
+ ### 2. Document Removal Reason
743
+
744
+ Keep a record of why workflows were removed:
745
+ ```javascript
746
+ // Log removal for audit trail
747
+ console.log({
748
+ action: "remove_workflow",
749
+ workflowId: "workflow-id",
750
+ workflowName: "Old Tasks",
751
+ reason: "Replaced by Tasks v2",
752
+ date: new Date().toISOString(),
753
+ removedBy: "admin-user-id"
754
+ })
755
+ ```
756
+
757
+ ### 3. Use Descriptive Workflow Names
758
+
759
+ Makes identification easier:
760
+ - ✅ "Tasks (Test - Can Delete)"
761
+ - ✅ "Legacy Customers - Archive 2023"
762
+ - ❌ "Workflow 1"
763
+ - ❌ "Test"
764
+
765
+ ### 4. Export Before Removing
766
+
767
+ Always export unless certain data not needed:
768
+ ```javascript
769
+ // Export activities
770
+ const backup = {
771
+ workflow: get_workflow_schema({ workflowId: "id" }),
772
+ activities: list_activities({ workflowId: "id", limit: 1000 }),
773
+ exportDate: new Date().toISOString()
774
+ }
775
+
776
+ // Save to file
777
+ console.log(JSON.stringify(backup, null, 2))
778
+
779
+ // Then remove
780
+ remove_workflow({ workflowId: "id" })
781
+ ```
782
+
783
+ ### 5. Remove Test Workflows Promptly
784
+
785
+ Don't let test workflows accumulate:
786
+ - Remove after testing complete
787
+ - Use clear naming (e.g., "TEST - Delete After Demo")
788
+ - Regular cleanup schedule (weekly/monthly)
789
+
790
+ ### 6. Communicate Before Removing
791
+
792
+ Notify team before removing shared workflows:
793
+ - Send message in workspace
794
+ - Post in relevant discussions
795
+ - Update documentation
796
+ - Provide migration path if replacing workflow
797
+
798
+ ### 7. Remove Children Before Parents
799
+
800
+ When removing related workflows:
801
+ ```javascript
802
+ // Correct order: Child → Parent
803
+ remove_workflow({ workflowId: "tasks-id" }) // Child
804
+ remove_workflow({ workflowId: "topics-id" }) // Parent of tasks
805
+ remove_workflow({ workflowId: "projects-id" }) // Top parent
806
+ ```
807
+
808
+ ### 8. Consider Alternatives to Removal
809
+
810
+ **Instead of removing, consider:**
811
+
812
+ **Option 1: Rename for clarity**
813
+ ```javascript
814
+ update_workflow({
815
+ workflowId: "id",
816
+ name: "Archived - Old Tasks (2023)"
817
+ })
818
+ ```
819
+
820
+ **Option 2: Remove from views**
821
+ - Users can hide workflows from their view
822
+ - Preserves data without deletion
823
+
824
+ **Option 3: Move to archive workspace**
825
+ - Create "Archive" workspace
826
+ - Move data there (manually)
827
+ - Keep original workspace clean
828
+
829
+ ## Integration with Other Tools
830
+
831
+ ### Used With list_workflows
832
+
833
+ ```javascript
834
+ // 1. List to find ID
835
+ const workflows = list_workflows()
836
+
837
+ // 2. Remove specific workflow
838
+ const testWorkflow = workflows.find(w => w.name.includes("Test"))
839
+ if (testWorkflow) {
840
+ remove_workflow({ workflowId: testWorkflow._id })
841
+ }
842
+ ```
843
+
844
+ ### Used With get_workflow_schema
845
+
846
+ ```javascript
847
+ // 1. Get details before removing
848
+ const schema = get_workflow_schema({ workflowId: "id" })
849
+ console.log("Removing workflow:", schema.name)
850
+ console.log("Fields:", schema.fields.length)
851
+
852
+ // 2. Remove
853
+ remove_workflow({ workflowId: "id" })
854
+ ```
855
+
856
+ ### Used With list_activities
857
+
858
+ ```javascript
859
+ // 1. Check activity count
860
+ const activities = list_activities({
861
+ workflowId: "id",
862
+ limit: 1
863
+ })
864
+
865
+ if (activities.total > 0) {
866
+ console.log(`⚠️ Warning: Removing workflow with ${activities.total} activities`)
867
+ }
868
+
869
+ // 2. Confirm and remove
870
+ remove_workflow({ workflowId: "id" })
871
+ ```
872
+
873
+ ### Used With install_workflow
874
+
875
+ **Replace workflow pattern:**
876
+ ```javascript
877
+ // 1. Install new version
878
+ const result = install_workflow({
879
+ workflowTemplates: [{ _id: '_0001', name: 'Tasks v2', ... }]
880
+ })
881
+
882
+ // 2. Migrate data (if needed)
883
+ // ... migration logic ...
884
+
885
+ // 3. Remove old version
886
+ remove_workflow({ workflowId: "old-workflow-id" })
887
+ ```
888
+
889
+ ## Summary
890
+
891
+ **Key Takeaways:**
892
+ 1. ⚠️ **Permanent deletion** - cannot be undone
893
+ 2. 🔒 **Admin only** - requires workspace administrator rights
894
+ 3. 🗑️ **Complete removal** - workflow, activities, discussions all deleted
895
+ 4. 🔗 **Breaks references** - ActivityLinks from other workflows will break
896
+ 5. 💾 **Export first** - always backup important data
897
+ 6. ✅ **Verify twice** - double-check workflow ID before removing
898
+ 7. 📢 **Communicate** - inform team before removing shared workflows
899
+
900
+ **Quick Decision Tree:**
901
+
902
+ ```
903
+ Need to remove workflow?
904
+
905
+ ├─ Contains important data? → Export first, then remove
906
+ ├─ Referenced by other workflows? → Update references first, then remove
907
+ ├─ Used by insights? → Update/remove insights first, then remove
908
+ ├─ Test/demo workflow? → Remove immediately
909
+ ├─ Might need later? → Consider archiving instead
910
+ └─ Sure about removal? → Verify ID and remove
911
+ ```
912
+
913
+ ## Additional Resources
914
+
915
+ - See `install-workflow-skill` for creating workflows
916
+ - See `update-workflow-field-skill` for modifying workflows (alternative to removal)
917
+ - Use `list_workflows` to view all workflows
918
+ - Use `get_workflow_schema` to inspect workflow structure before removal
919
+ - See `hailer-api` skill for comprehensive API documentation
920
+ - See `mcp-tools` skill for implementation patterns