AutomationsCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: automations
description: >-
  Event-triggered and schedule-triggered automations with natural-language
  conditions. Use when creating automations, wiring events, or understanding
  how triggers fire.
metadata:
  internal: true
---

# Automations

## Rule

Automations are the user-facing umbrella for agent-executed tasks that fire in
response to events or on a cron schedule. **Scheduled** and **Event** are the
two trigger types. Each automation is a markdown resource under `jobs/` with
YAML frontmatter describing when and how it fires, and a body containing
natural-language instructions the agent follows.

Recurring Jobs is the legacy name and API for scheduled automations.
`manage-jobs`, `jobs/`, and `/agent#jobs` remain stable compatibility surfaces.
Use `manage-automations` for new personal or organization automations, including
per-automation model overrides and MCP allowlists. Keep `manage-jobs` for
existing schedule-only integrations and delivery metadata.

## The Two Trigger Types

| Type       | Fires when                                      | Key field           |
| ---------- | ----------------------------------------------- | ------------------- |
| `schedule` | Cron expression matches (same as recurring jobs) | `schedule` (cron)   |
| `event`    | A matching event is emitted on the event bus     | `event` (event name) |

Event triggers can optionally include a `condition` -- a natural-language string evaluated by a model against the event payload before dispatch. If the condition does not match, the automation is skipped.

## How It Works

1. User asks the agent to create an automation (or uses the app's Automations page in Settings, `/settings/automations`; open it with `open-settings-page` page `automations`).
2. Agent calls `manage-automations` with `action=list-events` to discover available events.
3. Agent calls `manage-automations` with `action=define` to write a `jobs/<name>.md` resource.
4. The trigger dispatcher subscribes to the event on the bus.
5. When the event fires, the dispatcher loads all matching triggers, enforces
   owner and organization scope, and evaluates conditions via the resolved model.
6. Event and cron acquisition converge on the shared background-automation
   runner, which validates identity, resolves the configured model and MCP
   allowlist, runs the agent loop, handles continuation and delivery, and
   records usage.
7. Status (`lastRun`, `lastStatus`, `lastError`) is written back to the resource frontmatter.

Trigger acquisition stays separate by design: the scheduler decides when a cron
expression is due, while the event dispatcher matches event names, owners, and
conditions. Everything after a trigger is accepted uses the same execution
lifecycle.

## Markdown Format

```yaml
---
schedule: ""
enabled: true
triggerType: event
event: calendar.booking.created
condition: "attendee email ends with @example.com"
mode: agentic
domain: calendar
createdBy: [email protected]
runAs: creator
---

Send a Slack message to #sales with the booking details.
Use the web-request tool with ${keys.SLACK_WEBHOOK}.
```

### Frontmatter Fields

| Field         | Type                           | Purpose                                                |
| ------------- | ------------------------------ | ------------------------------------------------------ |
| `schedule`    | `string`                       | Cron expression; new scheduled automations default to once per hour (`0 * * * *`) when omitted |
| `enabled`     | `boolean`                      | Whether the automation is active                       |
| `triggerType` | `"schedule" \| "event"`        | How the automation fires                               |
| `event`       | `string?`                      | Event name to subscribe to (event triggers)            |
| `condition`   | `string?`                      | Natural-language condition evaluated before dispatch   |
| `mode`        | `"agentic"`                    | Full agent loop (only supported mode; `"deterministic"` was removed — never implemented, rejected at define time) |
| `model`       | `string?`                      | Override the model for this trigger's agent loop       |
| `reasoningEffort` | `string?`                   | Override reasoning effort for this trigger's model; omitted uses the model's default |
| `domain`      | `string?`                      | Grouping tag (mail, calendar, clips, etc.)             |
| `createdBy`   | `string?`                      | Creator email; required for organization event automations |
| `orgId`       | `string?`                      | Organization scope                                     |
| `runAs`       | `"creator" \| "shared"`        | Execution identity; trigger-aware automations use `creator` |
| `mcpTools`    | `string[]?`                    | Exact MCP tool allowlist for this automation           |
| `lastRun`     | `string?`                      | ISO timestamp of last execution                        |
| `lastStatus`  | `string?`                      | `success`, `error`, `running`, `skipped`, or `paused`  |
| `lastError`   | `string?`                      | The last failure cause or declared skip reason          |
| `lastErrorCode` | `string?`                    | Typed code of the last failure (see Failure handling)  |
| `consecutiveFailures` | `number?`              | Run of identical `lastErrorCode` failures              |
| `pausedReason` | `string?`                     | Set with `enabled: false` when the framework paused it |
| `pausedAt`    | `string?`                      | ISO timestamp of that pause                            |

## Agent Tools

All automation operations are accessed through a single `manage-automations` tool with an `action` parameter:

| Action        | Purpose                                                              |
| ------------- | -------------------------------------------------------------------- |
| `list-events` | Discover all registered 

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Automations](https://modelsatlas.com/skills/builderio/automations/badge.svg)](https://modelsatlas.com/skills/builderio/automations/)

Not your listing, or something out of date? Claim or update your listing.