MC Automations (the automation engine behind Mission Control boards)
The automation layer for Mission Control boards: an event-driven engine that fires action chains when board data changes, a channel bridge that lets a cross-system automation react to a board event, and the workflow-engine nodes that poll a board on a timer. Part of Mission Control Phases 5C and 5H.
On this page
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. Open the board's Automations page, or use the Add automation button in the board header. The page opens with the library.
The automation library (what to pick)
You do not build an automation from scratch. The page lists ready-made ones grouped by goal — keep me in the loop, never miss a date, hand-offs, assign and intake, keep the board tidy, AI sessions, and the AIPM. A search box covers the rest, and the most-used ones sit at the top.
Each template asks at most two things. Everything else is filled in from the board itself: the status column and its labels, the date column, the people column, the groups, and your own time zone. Picking a template shows it as one sentence with the filled-in values — "When Status becomes Done, notify Alex" — and each value can be changed. If the board is missing something a template needs, it says so in plain words rather than saving a blank.
Add it for me
When the missing piece is a column or a Done group, the card also offers a button that adds it — "Add a Status column", "Add a Finish date column", "Add a Done group" and so on. One click adds exactly that one piece with a plain name (Status, Due date, Owner, Start date, Finish date, or Done), the same way adding it by hand on the board would, and the card refreshes so you can turn the automation on. It never renames, removes or changes anything already on the board. If the board already has a group named "Done" that just isn't marked as the done group, it says so instead of adding a second one. The button is only ever a person's click: agents and the AIPM cannot change a board this way.
Turn on creates the automation. Nothing runs before that. A template that starts AI sessions or asks the AIPM to check something says so on its card, and turning it on is also your approval for it.
Describe it in one sentence
The box at the top of the page takes plain words: "remind me two days before things are due on the Marketing board." It picks the right template, fills in what it can, and shows you the same one-sentence summary. If it cannot tell what you meant, it asks one short question instead of guessing, and it can never set up a rule that deletes or archives anything.
The AIPM answers the same kind of request in its question box. When you type it there yourself and the rule is ready, it switches the rule on and says so ("On it. …"). An agent or a script does the same through POST /pm/automations/propose and then POST /pm/automations/proposals/:id/submit — the rule it submits is created switched off and waits for a person to turn it on, so an agent can never start something that acts on a board by itself.
Just ask Omni
Tell Omni in your own words — "if anything on Hiring goes overdue, move it to Blocked" — and it sets the automation up and switches it on, with no button to tap. Omni does this through POST /pm/automations/from-person-message, handing over only the id of the message you typed; the app reads your words itself and switches the rule on only when that message is your own newest one in that chat. A message from another agent, a script or an older turn never switches anything on, and each message sets up at most one automation. A rule that would cost money to run, or that deletes or archives anything, is never switched on this way: it waits in the Inbox for your OK, the same as an agent's proposal.
Turning on an agent's automation from the inbox
When an agent or the AIPM sets up an automation, your inbox gets a card naming it and the board. The card has a Turn on button beside Open Automations: one click turns that exact automation on and clears the card. If the automation starts AI work, the card says so, and Turn on is your approval for it. If it was already turned on or turned down somewhere else, the card simply clears and says so; nothing else changes.
Templates that check a whole board
An automation that runs on a schedule and carries conditions — "archive items that have been Done for 30 days", "nudge me about anything still In Progress after a week" — checks the board's items when it fires, acts on the matches, and stops at fifty items per run. It never treats an item with no history as old: it falls back to the item's own last-updated time.
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.
28 event types including item_created, item_status_changed, item_assigned, item_moved_to_group, item_column_changed, item_archived, item_deleted, comment_added, sprint_started, sprint_ended, approval_changed, session_completed, dependencies_resolved, and others. See BOARD_EVENT_TYPES in src/shared/types/pm-automations.ts for the full list.
Where comment_added comes from. A comment added on this computer, in the app or through the API (POST /pm/items/:id/comments), raises comment_added straight away through one shared step both doors call (src/main/services/pm/pm-comment-events.ts). A comment written somewhere else raises it when comment sync first brings it in. Each comment raises it once: sync never raises it again for a comment this computer already holds.
Column values are resolved against their column before the write — and when they are read. A preset or caller authors the human-readable label (pm.set-column-value with { label: 'High' }), but the backend validates a cell against its column's type handler and takes a status/priority label only as its index — so the action resolves the label against the target column's own settings.labels first, case-insensitively. An { index } value passes straight through; a label the column does not carry fails that step naming the labels it does. The CLI's cell route (PUT /pm/items/:id/columns/:colId) and email-to-item enrichment resolve through the same seam (src/main/services/pm/pm-column-label-resolve.ts), which also owns the dropdown { ids: ["Label"] } → { ids: [numericId] } resolution. The same seam serves the READ direction: a stored status/priority cell holds only { index }, so a condition comparing it to a label resolves the index through the column's own labels first, and a cell the column cannot resolve keeps its raw value.
A schedule that can never fire is refused when the rule is saved. Creating or updating a rule whose schedule carries a cron expression the scheduler cannot parse comes back as a plain refusal naming the field, instead of saving an "active" rule whose next fire instant is never computed. The check is the shared cron validator the scheduler parses with, applied in the automation schemas, so the app, the CLI create route and the CLI batch route all refuse alike.
Item actions act on the item that fired the rule. Move item, set column value, create subitem and duplicate item all find their item through one shared rule (resolveItemId in src/main/services/automation/v2/actions/resolve-trigger-item-id.ts): the triggering item first, then an item id written into the rule, and never a leftover {{itemId}} placeholder. A preset that authors itemId: '{{itemId}}' therefore works on the triggering item; with no item to act on (a schedule trigger, say) the step is skipped with "No linked PM item in trigger context" and nothing is written.
A step the engine cannot run is refused when the API saves the rule. An API caller (an agent, a script) creating or updating a rule has its action steps checked against the engine before anything is written: an unknown step type, or a step whose settings that step type does not accept, comes back as a refusal naming the step instead of saving a rule that would fail on every run. Each step's settings belong flat beside its type, not nested in a config object. Rules saved before this check, and rules the in-app builder or a template deployer saves, are untouched: they keep listing and running exactly as they did.
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. A condition on a status or priority column compares the label the user picked — the stored cell's { index } is resolved through that column's labels first, on the rule's own board and on a linked board, so Priority equals Critical matches the item whose Priority reads Critical. 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.
A condition is checked against the item as it exists when the event fires, so the cells an item was created with are readable by the time item_created is dispatched. An item is written together with the cells it was created with in one transaction, and the event is emitted only after that transaction commits — so Priority equals Critical on an item_created rule sees the item's Priority. A caller that creates an item and then adds its cells separately would hand the rule an item with no cells, and every condition on it would read false.
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.
37 preset templates in four categories: notify, organize, escalate, automate. Includes deps-resolved-auto-move (move an item when all its dependencies finish) and deps-resolved-notify (notify watchers when all dependencies finish).
Applying a preset. Clicking a preset whose steps are all complete installs it in one click. A
preset that ships a blank required setting — a target group, a column, a project, a board — cannot
run as-is, so it opens the automation builder pre-filled with the preset's name, trigger, conditions
and steps, the blank settings are marked, and Create stays disabled until they are chosen; Cancel
installs nothing. The page decides which path a preset takes from the same check the builder uses
for Save (action-required-fields.ts), so a preset can never open with Save already enabled, and a
test holds that check equal to the engine's own action schemas for every built-in preset. A step
type the builder cannot edit (such as the retired cli_session) takes this path too, so the user
picks a real step instead of installing one that can never run.
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'.
Suggested for you — automation suggestions
When someone keeps making the same follow-up by hand on a project, the project's Automations page offers to automate it as a Suggested for you card. Example: Status is set to Done and the item is then moved to the Done group, three times — the card reads "When Status becomes Done, move it to Done".
- When a card appears: after the same follow-up has been made by hand 3 times in total, however long that took. Each suggestion pairs the repeated change (the "then": a status or priority value, a group move, or archiving) with the move that comes right before it on the same item, within 10 minutes, by the same person or agent (the "when": an item created, a status change, or a group move). Assignee columns are never used — the history keeps who was assigned hidden.
- Whose moves count — by the project's Setup Style: a Tasks project, a First agent project, or a project with no setup yet counts only people's moves; every other Setup Style also counts AI agents' moves. Automations and imports never count, and neither do undo replays.
- Rare by design: at most 1 new suggestion per project per day and 10 new across all projects per week. When more qualify, the one that saves the most time shows first (how often the move happens × how many steps it would replace). A card already shown stays until it is used or hidden.
- Create this automation opens the automation builder already filled in (status values by their name). Nothing is saved until Save; after that the card never returns. A move an active automation already handles is never suggested.
- Hiding a card (✕) asks "Why are you hiding this?" with the same five reasons as the Omniscio inbox. I'm already doing this, Not useful, Wrong / inaccurate and Other (with an optional note) hide it on that project for good; Doesn't fit my workflow brings it back only once the move happens about twice as often. Undo brings a hidden card straight back.
- Free and quiet: the wording comes from simple rules (no AI, no cost) and says "project"; with nothing to suggest the section does not appear.
- Turning it off: Settings → Lab → Automation Suggestions (on by default). Desktop only, like the automation builder.
- For agents:
GET /pm/automations/suggestions?boardId=<id>lists a project's open suggestions;POST /pm/automations/suggestions/feedbackwith{ boardId, patternKey, action: "dismiss" | "undismiss" | "created", reason?, note? }records feedback (a reason is required to dismiss). Feedback needs the full-trust CLI token, and a project viewer can read suggestions but not give feedback on them.
What the builder saves for a step's settings
An item-scoped step (move item, set a column value, create a subitem, duplicate an item) always
names an item: the one the rule already carries, or the {{itemId}} placeholder the presets use,
which stands for the item that triggered the rule and is never an empty item. A notification step
needs both a title and a message, and Save stays disabled without them. The engine checks every
step against its action's own settings before it runs, so a step saved empty fails every run with
"This step's settings are invalid". Those four steps take their item from the rule, so the builder
offers no item picker for them.
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.
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.
Related
See also
- mission-control.md (parent page)
- INDEX.md
Last verified 2026-10-27