---
name: workflow-manager
description: "Create, test, and diagnose persistent workflows that automate recurring multi-step processes spanning different plugin tools. Use when the user describes a recurring multi-step process to automate."
---

# Workflow Manager

Create, test, and diagnose persistent workflows that automate recurring multi-step processes.

## When to Suggest a Workflow

The user describes a recurring process with two or more steps that involve different plugin tools. Examples: "every time a new contact signs up, send them a welcome message and schedule a follow-up", "when I get a new lead, create a contact, log it, and send a Telegram notification".

Do not suggest workflows for single-tool operations or one-off tasks.

## Gathering Requirements

Ask the user conversationally:

1. **What triggers this workflow?** Manual execution, scheduled (cron via scheduling plugin), or conversational ("run the follow-up workflow").
2. **What are the steps?** Each step is a single MCP tool call on a specific plugin. Identify the plugin name and tool name for each step.
3. **How do steps connect?** Which steps depend on output from earlier steps? Identify the `outputKey` for steps that produce data and the `{{outputKey.field}}` template variables for steps that consume it.
4. **What happens on failure?** For each step: abort the workflow, skip and continue, or retry (up to 3 times)?
5. **Any slow steps?** Steps calling tools that may take longer than 30 seconds (knowledge ingestion, external API calls) need an explicit `timeout` value (max 120 seconds).

## Presenting for Review

Before creating, show the user the planned workflow structure:

- Workflow name and description
- Each step numbered, showing: label, plugin/tool, parameters (with template variables highlighted), failure policy, and timeout if non-default
- Dependency chain (which steps must complete before which)
- Template variable flow (where data passes between steps)

Wait for the user's confirmation before calling `workflow-create`.

## Creating a Workflow

Use `workflow-create` with these parameters:
- `name` — short descriptive name (e.g. "New lead follow-up")
- `description` — what the workflow does, used for semantic discovery
- `steps` — array of step objects, each with:
  - `type`: `"tool"` (the only supported type)
  - `plugin`: plugin name (e.g. `"contacts"`, `"telegram"`, `"scheduling"`)
  - `tool`: tool name within the plugin (e.g. `"contact-create"`, `"message"`)
  - `params`: parameter object — use `{{outputKey.field}}` for values from prior steps
  - `label`: human-readable description
  - `dependsOn`: array of position indexes (as strings) for steps that must complete first — e.g. `["0"]` means "after step 0"
  - `onFailure`: `"abort"` (default), `"skip"`, or `"retry"`
  - `retryLimit`: 1-3, only when onFailure is `"retry"`
  - `outputKey`: name to store this step's output under
  - `timeout`: execution timeout in seconds (1-120, default 30)

If creation returns `status: "draft"`, tell the user which plugin capabilities are missing and that the workflow will activate automatically once those plugins are installed and built.

## Testing a Workflow

After creation, verify the workflow works:

1. Use `workflow-execute` with a test `context` object containing sample values for any runtime variables the workflow expects.
2. Check the result: `status`, `stepsCompleted`, `stepsSkipped`, `stepsFailed`.
3. If any steps failed, use `workflow-runs` to get the detailed run history, then examine per-step results to identify which step failed and why.

## Diagnosing Failures

When the user reports a workflow isn't working:

1. Use `workflow-get` with the `workflowId` to check the workflow's current status and step configuration.
2. If status is `"draft"` — missing plugins. Use `workflow-validate` to see which capabilities are unavailable.
3. If status is `"paused"` — the user or the system paused it. Use `workflow-update` with `status: "active"` to resume (this re-validates capabilities first).
4. If status is `"active"` but execution fails — use `workflow-runs` to find recent runs, then examine per-step errors:
   - Template variable errors: a step references `{{outputKey.field}}` but the prior step didn't produce that output key or field
   - Tool errors: the underlying MCP tool returned an error (check the step result's error message)
   - Timeout errors: the step exceeded its timeout — consider increasing the `timeout` field via `workflow-update`

## Managing Existing Workflows

- **List**: `workflow-list` — optionally filter by `status` (`"active"`, `"paused"`, `"draft"`)
- **View details**: `workflow-get` with `workflowId`
- **Edit**: `workflow-update` — can change `name`, `description`, `steps` (full replacement), or `status`
- **Pause/resume**: `workflow-update` with `status: "paused"` or `status: "active"`
- **Re-validate**: `workflow-validate` — checks if draft workflows can now activate after plugin changes
- **Delete**: `workflow-delete` — cascades to all steps, runs, and step results. Confirm with the user first.
- **Run history**: `workflow-runs` — optionally filter by `workflowId` or `status`

## Schedule Integration

To run a workflow on a schedule, create a scheduling event with action dispatch:
- Plugin: `scheduling`
- Tool: `schedule-event`
- Action: `{ plugin: "workflows", tool: "workflow-execute", args: { workflowId: "..." } }`

The `check-due-events` dispatcher (currently unwired — see `maxy-code-prd.md` §Scheduled tasks) is the surface that will fire the workflow at the scheduled time. The WorkflowRun captures `trigger: "schedule"` when the dispatcher fires.
