MC Automations (the automation engine behind Mission Control boards)

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
• pm-workflow-nodes-contract.md

Related

See also

• mission-control.md (parent page)
• INDEX.md