---
title: MC Automations (the automation engine behind Mission Control boards)
---

# MC Automations (Mission Control automation engine + workflow nodes)

## What it is

The automation layer for Mission Control boards: an event-driven engine (Phase 5C), a channel bridge for cross-system automations, and workflow engine integration (Phase 5H).

## Where to find it

Inside **Mission Control**, on a board: automations are configured against the board rather than on a screen of their own. The board's own page describes where the automation controls sit.

## How it behaves

### Board automation engine (Phase 5C)

An event-driven automation engine that fires action chains when board data changes. The sync service snapshots board state before each sync, diffs after, and emits typed `BoardEvent` objects.

**12 event types:** `item_created`, `item_archived`, `item_status_changed`, `item_assigned`, `item_due_date_passed`, `item_moved_to_group`, `item_column_changed`, `date_approaching`, `schedule`, `sprint_started`, `sprint_ended`, `comment_added`.

**Condition evaluation:** each rule carries a `conditionConfig` (either `{ method: 'always' }` or a recursive AND/OR tree of column conditions). Ten operators: equals, not_equals, contains, not_contains, greater_than, less_than, is_empty, is_not_empty, in_list, not_in_list. Cross-board conditions resolve linked items via `connect_boards` columns. Safety limits: max 3 nesting depth, max 10 conditions, max 3 cross-board refs, 5-second timeout.

**Safety controls:** master toggle (`pmAutomationsEnabled`, default **on**), event dedup (SQLite `pm_automation_processed_events` with 7-day retention), 5-second per-rule cooldown, stop-on-match, always-persist run records. Failure-rate alerting: 5+ failures in 10 minutes raises a deduped inbox alert (`pm-automation-rule-failure-rate`).

**Observability:** `pm_automation` FeatureId tracks `fired` (success) and `failure` actions with `ruleId`, `ruleName`, `durationMs` metadata.

**Due-date checker:** runs every 15 minutes, scans date columns for overdue items, feeds `item_due_date_passed` events.

**19 preset templates** in four categories: notify (5), organize (7), escalate (3), automate (4).

**Per-rule approval:** rules default to `approval_status = 'approved'`; pending rules gated via `pm-automation-approval` inbox source.

**Feature gating:** `'pm-automations'` in `UNRELEASED_FEATURES` with status `'in-development'`.

### Key files

- `src/main/services/pm/automation/pm-automation-service.ts` (engine)
- `src/main/services/pm/automation/pm-condition-evaluator.ts` (condition tree evaluator)
- `src/main/services/pm/pm-board-diff.ts` (diff)
- `src/main/services/pm/date-scanning/pm-due-date-checker.ts` (cron)
- `src/main/services/pm/automation/pm-automation-queries.ts` (CRUD)
- `src/main/services/pm/automation/pm-automation-presets.ts` (presets)
- `src/main/ipc/pm-automation-handlers.ts` (IPC)
- `src/main/services/cli/cli-server-pm-automation-routes.ts` (CLI)
- `src/plugins/mission-control/web/features/automations/` (UI: AutomationsPage, AutomationBuilder, PresetGallery, TriggerPicker, ActionPicker, RunHistoryPanel)

### PM event channel bridge

Bridges PM board events into the channel automation engine (`automations` table), adding a `on_pm_event` trigger type alongside `on_message`, `manual`, and `on_session_state`. The bridge is SEPARATE from the board automation engine: board automations use `pm_board_automations`, channel bridge uses the `automations` table with `pm_event_config` column.

**Three v2 actions:** `pm.update-linked-status`, `pm.add-comment`, `pm.create-item`.

**Four preset templates:** Overdue Task Nudge, Status Change Update, Comment on New Items, Assignment Notification.

### Key files

- `src/main/services/pm/pm-event-channel-bridge.ts`
- `src/main/services/automation/v2/dispatcher.ts`
- `src/main/services/automation/v2/actions/pm-update-linked-status.ts`, `pm-add-comment.ts`, `pm-create-item.ts`

### Workflow Engine Nodes (Phase 5H)

Integrates PM boards into the Workflow Engine with a poll-based trigger (60-second intervals) and five action nodes. Trigger dedup by `pm-trigger:boardId:itemId:event:value`. Kill switch: `AMC_DISABLE_PM_WORKFLOW_TRIGGER`.

**Trigger node** (`trigger.pm_item`): configurable event filter, optional board/column scoping.

**Action nodes:** `action.pm_create_item`, `action.pm_transition`, `action.pm_comment`, `action.pm_assign`, `action.pm_search`.

Nodes are auto-registered via `import.meta.glob`. Side effects route through `WorkflowEnginePorts`.

### Key files

- `src/main/services/workflow-engine/pm-item-trigger.ts` (watcher)
- `src/main/services/workflow-engine/nodes/pm-*-node.ts` (6 node files)
- `src/main/services/workflow-engine/ports.ts` (port implementations)

## For agents

### Contracts

- [pm-automation-contract.md](../../.claude/memory/contracts/pm-automation-contract.md)
- [pm-workflow-nodes-contract.md](../../.claude/memory/contracts/pm-workflow-nodes-contract.md)

## Related

### See also

- [mission-control.md](mission-control.md) (parent page)
- [INDEX.md](INDEX.md)