> For AI agents: the complete documentation index is available at https://docs.tessl.io/llms.txt, the full documentation bundle is available at https://docs.tessl.io/llms-full.txt.

# Actions, triggers, and schedules

This page specifies the `actions`, `triggers`, and `schedules` blocks of `tessl.json` and the top-level `environment` key. Each key below is given with its type, whether it is required, its default, its allowed values, and its bounds. For how loops, actions, triggers, and runs fit together, see [Automations](https://docs.tessl.io/automations/overview.md). For schedules in practice, see [Schedules](https://docs.tessl.io/schedules/overview.md).

`tessl doctor --automations` checks these blocks locally. `tessl schedule validate` checks the `schedules` and `actions` blocks, not `triggers`. Every example on this page is a complete `tessl.json` that passes `tessl doctor --automations`.

## Top-level keys

- `actions` (object, optional): declared actions, keyed by name. See [Actions](#actions).
- `triggers` (object, optional): event triggers, keyed by name. See [Triggers](#triggers).
- `schedules` (object, optional): schedules, keyed by name. See [Schedules](#schedules).
- `environment` (string, optional): the project's default [environment](https://docs.tessl.io/schedules/environments.md), by name. Every action that names no `environment` of its own runs in it. A non-empty string with no `{{`. It must be an organization environment the project is [bound to](https://docs.tessl.io/schedules/environments.md#bind-projects-to-an-environment).

Tessl reads these keys from the default branch when you push. The `name` key, as `workspace/project`, tells Tessl which project they belong to; see [How the sync works](https://docs.tessl.io/schedules/overview.md#how-the-sync-works).

### Names

The name of an action, trigger, or schedule is its identity: a lowercase kebab-case slug of 1 to 64 characters, made of `a-z` and `0-9` in groups joined by single dashes. An action or trigger name outside the pattern is refused with `Name must be a lowercase kebab-case slug (a-z, 0-9, single dashes).`, and one longer than 64 characters with a length error. A schedule name that breaks either rule is refused with `Schedule name must be a lowercase kebab-case slug (a-z, 0-9, single dashes), 1-64 chars.` Renaming an action, trigger, or schedule deletes it and creates a new one.

### Durations

`timeout` and `debounce` take a duration: a whole number followed by one unit, `s`, `m`, or `h`, with nothing else, for example `90s`, `15m`, or `2h`. Each field has its own range, given where it is described.

## Actions

An action is what a run does: the skill it runs and the settings it runs with. You write one in three places:

- **Declared**: a definition in the `actions` block, which triggers and schedules name. Every trigger and schedule that names the same declared action belongs to one loop.
- **Inline**: written whole as the `action` of one trigger or schedule. It belongs to that trigger or schedule alone.
- **Flat**: a schedule with no `action`, whose action fields sit beside its timing. See [Flat schedules](#flat-schedules).

### Action fields

A declared action and an inline action take these fields. Only `skill` is required.

- `skill` (string, required): the skill to run. One of:

  - a registry ref, `workspace/plugin`, optionally followed by `@version`;
  - a repo-local path, `file:path` or `./path`, relative to the directory of the `tessl.json`.

  Either form may end with `#skill` to pick one skill of the plugin.

  It resolves when a run starts.
- `environment` (string, optional): the [environment](https://docs.tessl.io/schedules/environments.md) the run executes in, by name, never by ID. Default: the top-level `environment`. Without either, a run gets a read-only GitHub token.
- `agent` (string, optional): the agent that runs the skill. Tessl accepts `claude` (also written `claude-code`), `codex`, and `tessl` (also written `tessl-agent`). Default: the platform default, `claude`. Tessl checks the value when the manifest syncs and when a run starts, not in local validation.
- `model` (string, optional): the model the agent runs on. Default: resolved for your organization when the run starts. Tessl checks that your organization can use the model with the agent when the manifest syncs and when a run starts.
- `effort` (string, optional): how hard the agent thinks. One of `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Default: the agent's own. A run whose agent and model do not offer the level does not start.
- `inputs` (object, optional): values for the skill's inputs, by input name. Each name is a non-empty string with no `{` or `}`. Each value is a string and may carry [substitutions](#substitutions).
- `instructions` (string, optional): free text added to the skill's prompt for this action. Non-empty. May carry [substitutions](#substitutions); it renders to at most 64,000 characters, and a run whose `instructions` render longer is refused.
- `baseBranch` (string, optional): the branch a run checks out before it runs. Default: the project's default loop branch, else the repository's default branch.
- `workdir` (string, optional): the directory inside the repository the agent runs in. Default: the repository root.
- `timeout` (string, optional): how long a run has, as a [duration](#durations), counted from when its sandbox starts, setup included. From `1s` to `6h`. Default: `2h`. The run reads its deadline, an ISO 8601 UTC time, from the `TESSL_LAUNCH_DEADLINE` environment variable; after it, the run can be stopped at any moment. A number is refused with `` `timeout` is a duration string such as `15m`. ``, and the launch API's `timeoutMs` with `` `timeoutMs` is not an action field; use `timeout`, a duration such as `2h`. ``
- `tags` (array of strings, optional): labels the action's loop is grouped by, such as `codebase-health`. Each a non-empty string with no `{{`. They change nothing a run does.
- `concurrency` (object, optional): what every run of the action holds and how its events are gathered, whatever started it. See [Concurrency](#concurrency).
- `description` (string, optional): what the action is for. At most 4,096 characters. It changes nothing a run does.

Every string field except `inputs` values, `instructions`, and `description` is taken as written: a value holding `{{` is refused. A `description` may hold `{{`, which is never rendered. `quiet` is refused on an action with `` `quiet` is set on the trigger, as `"quiet": true` beside its `on`, not on an action. ``

A declared action also takes `params`, `overlays`, and `selectOverlays`; see [Choosing settings from inputs](#choosing-settings-from-inputs).

```json
{
  "name": "engteam/my-repo",
  "environment": "production",
  "actions": {
    "triage": {
      "skill": "engteam/issue-triage@1.2.0#triage",
      "agent": "codex",
      "effort": "high",
      "inputs": { "LABEL": "needs-triage" },
      "instructions": "Triage issues labeled {{ inputs.LABEL }}.",
      "baseBranch": "main",
      "workdir": "services/api",
      "timeout": "30m",
      "tags": ["issue-flow"],
      "description": "Triage one issue and label it."
    }
  }
}
```

### Naming the action from a trigger or schedule

The `action` of a trigger or schedule takes one of three forms:

- **A name**: `"action": "triage"` runs the declared action `triage` as declared.
- **`use` with overrides**: `"action": { "use": "triage", ... }` runs the declared action with the fields you give replacing its own.
- **Inline**: `"action": { "skill": "...", ... }` is an action written whole, with the [action fields](#action-fields). An object with a `use` key is read as the second form; any other object as this one.

A name, or a `use`, that the `actions` block does not declare is refused with `Trigger "<trigger>" uses action "<name>", which this file does not declare. Declare it under actions, or write the action inline on the trigger.` (`Schedule "<schedule>" ...` for a schedule).

A `use` object takes `use` (the declared action's name, required) and any of these overrides: `skill`, `environment`, `agent`, `model`, `effort`, `inputs`, `instructions`, `baseBranch`, `workdir`, and `timeout`. The merge rule:

- A field you give replaces the declared one.
- `null` removes the declared field. `skill` can be replaced but not removed.
- `inputs` merges by input name: a name you give replaces that input, a name set to `null` removes it, and a name you leave out keeps its declared value. `"inputs": null` removes every input.
- A field you leave out keeps its declared value.

`tags`, `concurrency`, `description`, `params`, `overlays`, and `selectOverlays` always come from the declaration. A `use` object that sets `tags`, `concurrency`, or `description` is refused as an unrecognized key; one that sets `params`, `overlays`, or `selectOverlays` is refused with the message for an inline action, below. To describe one trigger or schedule, set `description` on the trigger or schedule itself.

```json
{
  "name": "engteam/my-repo",
  "actions": {
    "pr-report": {
      "skill": "file:tiles/pr-report",
      "environment": "reports",
      "model": "claude-sonnet-5-5",
      "inputs": { "WINDOW": "1d", "FORMAT": "markdown" }
    }
  },
  "schedules": {
    "pr-report-nightly": { "action": "pr-report", "cron": "0 2 * * *" },
    "pr-report-weekly": {
      "action": {
        "use": "pr-report",
        "model": null,
        "inputs": { "WINDOW": "7d", "FORMAT": null },
        "instructions": "Cover the last 7 days."
      },
      "cron": "0 4 * * 1"
    }
  }
}
```

The weekly schedule runs `pr-report` with the agent's default model, `WINDOW` set to `7d`, no `FORMAT`, and the extra instructions.

### Choosing settings from inputs

A declared action can choose its run settings from the inputs a run is given. Three fields do this, and only a declared action takes them. On an inline action each is refused with `` `<field>` is set only on an action declared in `actions`, not on one written inline in a trigger or schedule. Declare the action and name it with `use`. ``

- `params` (object, optional): what the action says about its inputs, by input name. Each value is either `"string"` or an object with `type` (required, `"string"`), `optional` (boolean, default `false`), and `actionOnly` (boolean, default `false`).
- `overlays` (object, optional): named sets of settings. Each name is 1 to 1,024 characters and holds no `{{`. Each overlay takes the same fields as a `use` override (`skill`, `environment`, `agent`, `model`, `effort`, `inputs`, `instructions`, `baseBranch`, `workdir`, `timeout`) by the same merge rule. At most 1,000 overlays. An overlay that sets `tags` or `concurrency` is refused by name.
- `selectOverlays` (array of strings, optional): selectors, each a non-empty string. At most 100. A selector with no `{{` must be the name of a declared overlay.

How they apply:

- **Selection**: each selector renders against the inputs the run is given: the action's own `inputs` with its starter's `inputs` merged over them. When the result is exactly the name of an overlay, that overlay applies. Any other result applies nothing. There are no patterns or wildcards, and an overlay's own `inputs` never feed selection.
- **Order**: a run's settings are the action's own, then each selected overlay in selector order, then the `use` overrides of the trigger or schedule that started it, then the fields of the request, such as `tessl action trigger --model`. A later layer wins, by the merge rule above.
- **Required inputs**: an input in `params` without `optional: true`, such as `"string"`, is required. A run that has no value for it is refused, naming the input, whether it was never given or its value names an event value that is null or absent.
- **Optional inputs**: an `optional` input with no value renders as empty text wherever a template reads it and is left out of the skill's inputs.
- **Action-only inputs**: an `actionOnly` input never reaches the skill. The action reads it in a selector or a template.
- **Inputs that `params` does not declare** reach the skill. One that is never given refuses a run only when a template reads it.
- An overlay's `inputs` reach the skill, but never the concurrency keys, which render from the inputs the run is given before overlays apply.

```json
{
  "name": "engteam/my-repo",
  "actions": {
    "implement": {
      "skill": "file:tiles/factory#implement",
      "params": {
        "LINEAR_ISSUE_IDENTIFIER": "string",
        "ESTIMATE": { "type": "string", "optional": true, "actionOnly": true }
      },
      "selectOverlays": ["estimate-{{ inputs.ESTIMATE }}"],
      "overlays": {
        "estimate-1": { "agent": "codex", "effort": "high" },
        "estimate-5": { "timeout": "3h" }
      }
    }
  },
  "triggers": {
    "issue-ready": {
      "on": ["linear:Issue.update"],
      "when": { "labelAdded": "factory" },
      "action": {
        "use": "implement",
        "inputs": {
          "LINEAR_ISSUE_IDENTIFIER": "{{ event.data.identifier }}",
          "ESTIMATE": "{{ event.data.estimate }}"
        }
      }
    }
  }
}
```

An issue with estimate 1 runs on `codex` at `high` effort, and `tessl action trigger implement --input LINEAR_ISSUE_IDENTIFIER=ENG-123 --input ESTIMATE=1` runs the same settings by hand. An issue with no estimate selects `estimate-`, which names no overlay, so the action runs as declared.

Runs whose settings are the same after overlays apply are the same action, so their events can fold into one run.

## Triggers

A trigger starts an action when a provider event matches it. The `triggers` block maps each trigger's name to its definition.

### Trigger fields

- `on` (array of strings, required, at least one): the events that fire the trigger, each written `<provider>:<event>`. The provider is lowercase letters, digits, and underscores, starting with a letter; the event starts with a letter and holds letters, digits, underscores, and dots. Every event in the list must have the same [event shape](#event-shapes); a list that mixes shapes is refused with `A trigger listens for activity of one event shape; this lists <shape> and <shape>.`
- `when` (object, optional): conditions that must all hold. Without it, every event in `on` fires the trigger. See [Conditions](#conditions).
- `action` (string or object, required): the action to run, in one of the [three forms](#naming-the-action-from-a-trigger-or-schedule).
- `concurrency` (object, optional): what the trigger's runs hold and how its events are gathered. See [Concurrency](#concurrency).
- `quiet` (boolean, optional, default `false`): when `true`, the trigger does not mark the item its event came from. It adds no reaction to the Slack message or GitHub item it matched, and a run reports nothing there (no status, no Stop button, no failure reply or comment) when only quiet triggers brought that event into the run. Another trigger without `quiet` that matches the same event still marks it.
- `description` (string, optional): what the trigger is for. At most 4,096 characters.

A `debounce` written on the trigger itself is refused with `` `debounce` is declared inside `concurrency`, as `"concurrency": { "debounce": "90s" }`. ``

```json
{
  "name": "engteam/my-repo",
  "actions": {
    "triage": { "skill": "engteam/issue-triage", "environment": "production" }
  },
  "triggers": {
    "issue-labeled": {
      "on": ["github:issues.labeled"],
      "when": { "label": "tessl" },
      "action": {
        "use": "triage",
        "inputs": { "GITHUB_ISSUE_NUMBER": "{{ event.issue.number }}" }
      },
      "description": "Triage an issue when someone labels it tessl."
    }
  }
}
```

### Providers

- `github`: GitHub webhook events, delivered through the Tessl GitHub App. The event is GitHub's event name, then a dot and the payload's `action` when it has one: `github:issues.labeled`, `github:pull_request_review.submitted`, `github:push`.
- `linear`: Linear webhook events. The event is Linear's entity type, a dot, and its action: `create`, `update`, or `remove` for an entity (`linear:Issue.update`, `linear:Comment.create`), and `created` or `prompted` for an agent session (`linear:AgentSessionEvent.prompted`).
- `slack`: Slack Events API callbacks delivered to the Tessl Factory app: `slack:app_mention` and `slack:message`.
- `tessl`: events about Tessl's own records: `tessl:finding.created`.
- `source`: events that code holding a Tessl API key posts to a named source on the project, written `source:<source>.<event>`. The source name starts with a letter and holds letters, digits, and underscores; the event starts with a letter, holds letters, digits, underscores, and dots, and is at most 256 characters. See [Event sources](https://docs.tessl.io/automations/event-sources.md).

Any other provider is refused with `Provider "<provider>" is not supported.` A `source:` reference that names no event a source can receive is refused with `"<reference>" names no event a source can receive.` followed by the form to write: no event (`source:ledger`, `source:ledger.`), an event outside the pattern (`source:ledger.1received`, `source:ledger..received`), or an event longer than 256 characters.

### Event shapes

An event's shape is its provider and the part of its event before the first dot: `github:issues.opened` and `github:issues.labeled` are both the `github:issues` shape. The shape decides which helpers a trigger may name, the default concurrency key its runs hold, and whether it is marked: whether Tessl can mark the item the event came from, with a reaction, to show that it started a run.

GitHub:

- `issues`: helper `label`. Default key `github:repo/{{ event.repository.id }}:#{{ event.issue.number }}`. Marked.
- `issue_comment`: helpers `mention` and `isPullRequest`. Default key `github:repo/{{ event.repository.id }}:#{{ event.issue.number }}`. Marked.
- `pull_request`, `pull_request_review`, `pull_request_review_comment`, `pull_request_review_thread`: no helpers. Default key `github:repo/{{ event.repository.id }}:#{{ event.pull_request.number }}`. Marked.
- `check_suite`, `check_run`: no helpers. No default key. Not marked.
- `release`: no helpers. Default key `{{ event.release.node_id }}`. Marked.
- `push`: helper `isDefaultBranch`. Default key `{{ event.after }}`. Not marked.

Linear:

- `Issue`: helper `labelAdded`. Default key `{{ event.data.id }}`. Not marked.
- `Comment`: no helpers. Default key `{{ event.data.issue.id }}`. Not marked.
- `AgentSessionEvent`: no helpers. Default key `{{ event.agentSession.issue.id }}`. Not marked.

Slack:

- `app_mention`, `message`: no helpers. No default key. Marked.

Tessl:

- `finding`: no helpers. Default key `{{ event.finding.id }}`. Not marked.

Source:

- Each source is one shape, `source:<source>`, so a trigger cannot listen to two sources at once. No helpers, no default key, not marked.

An event of a supported provider whose shape is not listed here still fires its trigger. It offers no helpers and no default key, and `tessl doctor` warns that it is not in the local event-shape table. A trigger whose shape has no default key, and that neither it nor its action gives `concurrency.keys`, gets a warning: its runs are held only by the project's limit, so two events on one item can run at once.

### Conditions

`when` maps each key to a condition, and every condition must hold. A key is one of:

- **A payload path**, `event.` followed by dot-separated fields into the event's raw payload, such as `event.issue.title`. A number addresses an array member (`event.issue.labels.0.name`), and `*` stands for every member of an array, so `event.issue.labels.*.name` is the list of label names. A path with an empty segment, such as `event.issue..title`, is refused.
- **A helper**: a name the event shape defines. See [Helpers](#helpers).

A path's condition is a literal or an operator object.

- **A literal** (string, number, boolean, or `null`) holds when the value at the path is exactly that literal. Values are compared as written, with no coercion: `12` and `"12"` are different conditions.
- **An operator object** holds when every operator in it holds. It must give at least one operator, and an unknown operator is refused.

Operators:

- `equals` (literal or `null`): the value is exactly this.
- `in` (array of literals or `null`, at least one): the value is exactly one of these.
- `contains` (string, number, or boolean): the value is a string that contains this string, or an array with a member exactly equal to this.
- `matches` (non-empty string): the value is a string that the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression matches anywhere. A pattern RE2 cannot compile is refused, and so is one holding `{{`.
- `mentions` (non-empty string): the value is Markdown text that says this keyword, in any case. The keyword counts when it neither follows an ASCII letter, digit, `_`, `@`, or `-` nor runs on into an ASCII letter, digit, `_`, or `-`, and when it is not inside a code span, a fenced code block, or a block quote. A keyword holding `{{` is refused.
- `exists` (boolean): `true` holds when the path has a non-null value; `false` when it has none or is `null`. No other operator may sit beside `exists: false`. To test for a `null` that is present, use `equals: null`.
- `not` (operator object): holds when the nested operators do not all hold.
- `any` (operator object): the value is an array and the nested operators hold for at least one member.
- `none` (operator object): the nested operators hold for no member of the value, which holds for an empty array or a value that is not an array.

`not`, `any`, and `none` nest at most 3 levels deep.

Writing an operator as a `when` key, such as `"contains": ...`, is refused: an operator tests a path, written `"event.<path>": { "contains": ... }`.

```json
{
  "name": "engteam/my-repo",
  "actions": {
    "review-fix": { "skill": "engteam/review-fix", "environment": "production" }
  },
  "triggers": {
    "changes-requested": {
      "on": ["github:pull_request_review.submitted"],
      "when": {
        "event.review.state": "changes_requested",
        "event.pull_request.draft": { "equals": false },
        "event.pull_request.labels.*.name": { "contains": "factory" },
        "event.review.body": {
          "exists": true,
          "not": { "matches": "^\\s*LGTM" }
        },
        "event.pull_request.user.login": {
          "in": ["tessl-app[bot]", "tessl-helper[bot]"]
        },
        "event.pull_request.requested_teams.*.slug": {
          "none": { "equals": "security" }
        }
      },
      "action": {
        "use": "review-fix",
        "inputs": { "PR_NUMBER": "{{ event.pull_request.number }}" }
      }
    }
  }
}
```

### Helpers

A helper is a condition the provider computes from the payload for one event shape. Its value is always a string, taken as written: an operator object, a number, or a `{{` in a helper's value is refused. A helper the trigger's shape does not offer is refused, with the available helpers or a near match named.

- `label` (GitHub `issues`): the label the activity added or removed is named this. It reads `event.label.name`, not the issue's whole label set.
- `mention` (GitHub `issue_comment`): the comment body mentions this keyword, by the same rule as the `mentions` operator. It is the same test as `"event.comment.body": { "mentions": "<keyword>" }`.
- `isPullRequest` (GitHub `issue_comment`): `"true"` holds for a comment on a pull request, `"false"` for a comment on an issue. Any other value never holds.
- `isDefaultBranch` (GitHub `push`): `"true"` holds for a push to the repository's default branch, `"false"` for any other push, a tag push included. Any other value never holds.
- `labelAdded` (Linear `Issue`): this label is on the issue now and was not before the update. It holds only on an update that changed the issue's labels.

```json
{
  "name": "engteam/my-repo",
  "actions": {
    "answer": { "skill": "engteam/answer-question", "environment": "production" },
    "release-notes": { "skill": "engteam/release-notes", "environment": "production" }
  },
  "triggers": {
    "issue-question": {
      "on": ["github:issue_comment.created"],
      "when": {
        "isPullRequest": "false",
        "event.comment.body": { "mentions": "@tessl-app" }
      },
      "action": "answer"
    },
    "main-pushed": {
      "on": ["github:push"],
      "when": { "isDefaultBranch": "true" },
      "action": "release-notes"
    }
  }
}
```

### When a condition cannot be evaluated

Tessl evaluates `when` against each event the trigger lists in `on`. A condition whose path the payload does not carry tests an absent value: `exists: false` holds, and `equals`, `in`, `contains`, `matches`, `mentions`, and `any` fail. `not` around one of those holds, and so does `none`, so a `not` condition fires when the field is missing unless `exists: true` sits beside it. A condition comparing with a connection value the workspace does not give fails, and so does `not` around it.

## Schedules

A schedule starts an action on a cron. The `schedules` block maps each schedule's name to its definition. A schedule is written in one of two forms: with `action`, or flat.

### Schedules with an action

- `action` (string or object, required): the action to run, in one of the [three forms](#naming-the-action-from-a-trigger-or-schedule).
- `cron` (string or object): when the schedule fires. See [Schedule values](#schedule-values).
- `schedule` (string or object): an alias for `cron`. Give exactly one of `cron` and `schedule`. Neither is refused with `Either cron or schedule is required.`, and both with `Use either cron or schedule, not both.`
- `timezone` (string, optional, default `UTC`): the IANA timezone the cron is read in, such as `America/New_York`. An unknown timezone is refused.
- `description` (string, optional): what the schedule is for. At most 4,096 characters.

An action field written beside `action` is refused with `A schedule with action takes the action's fields inside action, so it cannot set <field> beside it. Move <field> into action, or write the schedule flat without action.`

```json
{
  "name": "engteam/my-repo",
  "schedules": {
    "weekly-changelog": {
      "action": {
        "skill": "engteam/changelog-writer",
        "environment": "production",
        "instructions": "Cover the last 7 days."
      },
      "schedule": "weekly on friday at 09:00",
      "timezone": "America/New_York",
      "description": "Draft the weekly changelog."
    }
  }
}
```

### Flat schedules

A schedule with no `action` key is flat: its action's fields sit beside its timing, and it runs as the inline action they describe. A flat schedule takes:

- `skill` (string, required) and `environment` (string, required), as in [Action fields](#action-fields).
- `agent`, `model`, `baseBranch`, `workdir`, `inputs` (optional), as in [Action fields](#action-fields).
- `instructions` (string, optional). An empty string is accepted and ignored.
- `cron` or `schedule`, `timezone`, and `description`, as for a schedule with an action.

`effort`, `timeout`, and `tags` are refused with `` `<field>` is set inside `action`; a flat schedule does not take it, so write this schedule with `action` to set it. `` Any other key, `concurrency` included, is refused as unrecognized. `tessl doctor` shows each flat schedule in its `action` form. Moving the fields into `action` keeps the same schedule and its run history.

```json
{
  "name": "engteam/my-repo",
  "schedules": {
    "docs-audit": {
      "skill": "engteam/docs-audit",
      "environment": "production",
      "instructions": "Focus on the API reference.",
      "cron": "0 8 * * 1"
    }
  }
}
```

### Schedule values

`cron` and `schedule` take one of three forms. Tessl compiles each to a five-field cron expression and checks it in the schedule's `timezone`. Every form must fire at least once, and never more often than every 5 minutes; a tighter schedule is refused with `Cron fires too frequently: the minimum interval between runs is 5 minutes.`

**A cron expression**, at most 256 characters:

- Five fields separated by spaces: minute (0 to 59), hour (0 to 23), day of month (1 to 31), month (1 to 12), day of week (0 to 7, where 0 and 7 are Sunday).
- Each field holds numbers, `*`, `?`, `,`, `-`, and `/`. Month and day of week also take three-letter names (`jan` to `dec`, `sun` to `sat`) in any case. A longer name is refused with the three-letter form to use instead.
- Six or more fields, fewer than five, the `L` last-day extension, and any other character are refused.
- A descriptor in place of the five fields: `@yearly`, `@annually`, `@monthly`, `@weekly`, `@daily`, `@midnight`, or `@hourly`.
- `@every <duration>`, where the duration is one or more numbers, each with a unit of `h`, `m`, `s`, `ms`, `us`, `µs`, or `ns`, such as `@every 1h30m` or `@every 1.5h`. A number may have a decimal part, with at most 19 whole digits and 9 decimal places. The total must be positive and at most 9,223,372,036,854,775,807 nanoseconds (about 292 years).

`0 9 * * 5` fires at 9:00 every Friday.

**A shorthand string**, in any case and spacing:

- `hourly`
- `daily at HH:MM`
- `weekdays at HH:MM`, Monday to Friday
- `weekly on DAY at HH:MM`, where `DAY` is a weekday name or its three-letter form, such as `friday` or `fri`
- `monthly on Nth at HH:MM`, where `N` is 1 to 31 with its English suffix (`1st`, `2nd`, `3rd`, `4th`, `11th`, `21st`)
- `every N minutes`, where `N` divides 60
- `every N hours`, where `N` divides 24
- `every N minutes on weekdays`, where `N` divides 60
- `every N minutes between HH:MM-HH:MM`: from the start, inclusive, to the end, exclusive, which must be later, with `N` from 1 to 60. When the start and end fall in different hours, both must be whole hours (such as `09:00-17:00`) and `N` must divide 60.

`HH` and `MM` are two digits each. Any other string that does not look like a cron expression is refused with the list of supported shorthands.

**An object** with any of `minute` (0 to 59), `hour` (0 to 23), `day` (1 to 31), `month` (1 to 12), and `weekday` (0 to 7, where 0 and 7 are Sunday). No other key is accepted. An omitted field means every value.

- `minute`, `hour`, and `day` each take a number, a list of numbers (at least one, at most as many as the field has values), `{ "every": N }` with `N` from 1 to the number of values the field has, or `{ "between": [start, end] }` with `start` no greater than `end`.
- `month` takes a number, a name (`january` to `december`, or `jan` to `dec`), or a list of numbers or of names, at most 12.
- `weekday` takes a number, a name (`sunday` to `saturday`, or `sun` to `sat`), or a list of numbers or of names, at most 7.

Names are lowercase. A list holds names or numbers, not both.

```json
{
  "name": "engteam/my-repo",
  "actions": {
    "health-check": { "skill": "engteam/health-check", "environment": "production" }
  },
  "schedules": {
    "business-hours": {
      "action": "health-check",
      "cron": {
        "minute": { "every": 15 },
        "hour": { "between": [9, 17] },
        "weekday": ["mon", "tue", "wed", "thu", "fri"]
      },
      "timezone": "Europe/London"
    },
    "nightly": { "action": "health-check", "schedule": "daily at 02:30" },
    "monthly": { "action": "health-check", "cron": "@monthly" }
  }
}
```

A schedule's action answers a tick, not an event, so nothing in it may read `{{ event.… }}`; see [Substitutions](#substitutions).

## Concurrency

`concurrency` is an object on a trigger, a declared action, or an inline action. It says which keys a run holds while it runs, how many runs may hold each, how events are gathered first, and what a new event does when a run on the same keys is already waiting. Every field is optional. A `concurrency` that is not an object, such as a list of keys, is refused with `` `concurrency` is an object with optional `keys`, `debounce`, `mode` and `jump`, ... ``.

- `keys` (array, optional, 1 to 10 keys): the keys a run holds. Each is either a string, which holds with a limit of 1, or an object with `key` (non-empty string, required) and `limit` (integer of at least 1, required). A key may carry [substitutions](#substitutions). Runs whose keys render to the same string are held against each other. A key that renders to more than 512 characters refuses the claim.
- `debounce` (string, optional): a [duration](#durations) from `1s` to `15m`. Events whose keys render the same and whose action renders the same, inputs and `instructions` included, are gathered for this long from the first one, then run together. An event whose action renders differently, for example through an input read from a value each event carries, gets its own window. A later event does not extend the window.
- `mode` (string, optional, default `join`): what a new claim does while another run on the same keys is waiting to start. One of:
  - `join`: the claim joins the waiting run when every claim that run holds is a `join` claim for the same rendered action and the same rendered keys, and the run has room, so the item gets one run carrying the events that arrived while it waited.
  - `queue`: the claim gets its own run, in arrival order.
  - `skip`: the claim is refused while another run on the same keys has asked to start and has not been released.
- `jump` (boolean, optional, default `false`): when `true`, the run goes ahead of the runs waiting on its keys that do not jump, and on a key counts only the jumping runs holding it. It does not stop a run that is already running.

Two of a trigger's and its action's blocks combine:

- **Keys**: a run holds its trigger's keys and its action's keys. When a trigger's key and its action's key render to the same string, the run holds it once, at the lower of the two limits. When neither declares `keys`, a trigger's run holds its event shape's [default key](#event-shapes).
- **Mode**: the stronger of the two, `skip` over `queue` over `join`. A side that names none counts as `join`. `tessl doctor` warns when a trigger names a weaker mode than its action, because the trigger's own mode then has no effect.
- **Debounce**: the longer of the two windows. `tessl doctor` warns when a trigger's window is shorter than its action's, because the trigger's own window then has no effect.
- **Jump**: the run jumps when either side says `jump: true`.

One key has one limit across the whole file: two definitions that give the same key different limits are refused with `Concurrency key "<key>" is given limit <n> here and limit <m> elsewhere in this file. One key has one limit.` Spacing inside `{{ }}` does not make keys different.

```json
{
  "name": "engteam/my-repo",
  "actions": {
    "respond": {
      "skill": "engteam/respond",
      "environment": "production",
      "concurrency": {
        "keys": [{ "key": "respond-repo", "limit": 3 }],
        "mode": "queue"
      }
    }
  },
  "triggers": {
    "thread-reply": {
      "on": ["slack:message"],
      "action": {
        "use": "respond",
        "inputs": { "CHANNEL": "{{ event.event.channel }}" }
      },
      "concurrency": {
        "keys": ["slack:{{ event.event.channel }}"],
        "debounce": "90s"
      }
    }
  }
}
```

Each Slack channel gets one run at a time, its messages gathered for 90 seconds, and no more than three runs of `respond` run at once. The messages gather because the action reads only the channel; an input such as `{{ event.event.ts }}`, which differs per message, would give each message its own run. A key that reads a path some events lack, such as `event.event.thread_ts` on a message that starts a thread, refuses those events; see [When a substitution does not resolve](#when-a-substitution-does-not-resolve).

## Substitutions

A `{{ … }}` substitution is replaced by a value when a run is claimed. Spacing inside the braces does not matter. A substitution does nothing else: there are no defaults, conditionals, or filters.

### Roots

- `{{ event.<path> }}`: the value at that path in the event's payload, by the same path rule as [conditions](#conditions), without `*`. A string, number, or boolean renders as text. A path the payload does not carry, or one that lands on an object, an array, or `null`, does not resolve.
- `{{ inputs.<name> }}`: the value of one of the action's inputs, after overrides and overlays, itself rendered. An input name may hold dots.
- Connection values, filled from the workspace's connections:

  - `{{ linear.tesslApp.userId }}`: the Linear user the Tessl app acts as in your Linear organization. A string.
  - `{{ github.tesslApp.userId }}`: the GitHub user the Tessl App acts as. A number.
  - `{{ github.tesslApp.appId }}`: the Tessl App's GitHub App ID. A number.
  - `{{ github.tesslReviewerApp.userId }}`: the GitHub user the Tessl Reviewer app acts as. A number.
  - `{{ github.tesslReviewerApp.appId }}`: the Tessl Reviewer app's GitHub App ID, as a payload carries it in `check_run.app.id`. A number.

  In a template, a number renders as its decimal digits.

### Where each root is read

Substitutions render in four places: `instructions`, `inputs` values, concurrency `keys`, and `selectOverlays`. Each reads these roots:

- **A trigger's own `concurrency.keys`**: `event.`, `inputs.`, and connection values.
- **A trigger's inline action**, and the overrides in a trigger's `use`: `event.` and connection values in `inputs` values; `event.`, `inputs.`, and connection values in `instructions` and `concurrency.keys`.
- **A declared action**, its overlays and its selectors: connection values in `inputs` values; `inputs.` and connection values in `instructions`, `concurrency.keys`, and `selectOverlays`. It never reads `event.`, so every trigger, schedule, and manual start runs it the same way. The trigger that starts it maps event values onto its inputs.
- **A schedule's action**, in any form: as a declared action, never `event.`.
- **A trigger's `when`**: a connection value only, as the whole of a comparison value (a literal, `equals`, `in`, or `contains`). It compares with the value's own type, so a GitHub ID matches a number in the payload.

An `inputs` value never reads another input. Every other field (`skill`, `environment`, `agent`, `model`, `timeout`, `baseBranch`, `workdir`, a tag, an overlay name, and the top-level `environment`) is taken as written, and a value holding `{{` there is refused with ``A `{{ … }}` substitution is not rendered here, because this field decides what runs, with which credentials and at what cost. ...``

A declared action that reads the event is refused with `A declared action reads only its inputs and connection values, so every starter runs it the same way, but <field> reads <template>. Give it an input, map the event onto that input on the trigger that starts it, and read it as {{ inputs.<name> }}.` A schedule's action that reads the event is refused with `A Schedule's action answers a tick, not an event, so it reads only its inputs and connection values, but <field> reads <template>. Read the value from {{ inputs.<name> }} or a connection value instead.`

```json
{
  "name": "engteam/my-repo",
  "actions": {
    "triage": {
      "skill": "engteam/issue-triage",
      "environment": "production",
      "inputs": { "BOT_USER": "{{ github.tesslApp.userId }}" },
      "instructions": "Triage issue #{{ inputs.ISSUE }}.",
      "concurrency": { "keys": ["triage:{{ inputs.ISSUE }}"] }
    }
  },
  "triggers": {
    "issue-opened": {
      "on": ["github:issues.opened"],
      "when": {
        "event.sender.id": { "not": { "equals": "{{ github.tesslApp.userId }}" } }
      },
      "action": {
        "use": "triage",
        "inputs": { "ISSUE": "{{ event.issue.number }}" }
      }
    }
  }
}
```

### When a substitution does not resolve

A substitution that does not resolve never renders as empty text, except in an `optional` input. A claim whose `instructions`, `inputs`, keys, or selectors hold a substitution that does not resolve is refused, and starts no run; Tessl records which field and expression failed. Reading an `inputs.<name>` the action does not give refuses the claim the same way, unless `params` mark the input optional. An `optional` input whose event value is absent renders as empty text and is left out of the skill's inputs; a connection value the workspace does not give still refuses it.

In `when`, a substitution that does not resolve makes its condition fail, `not` included, so the trigger does not fire.

## Validation

`tessl doctor --automations` runs the checks on this page against the `tessl.json` in the current directory and reports each problem at its block, definition, and field:

```
$ tessl doctor --automations
Automation Configuration

  ✘ Found 1 automation configuration problem.

  Triggers
    ✘ /path/to/tessl.json: triggers.issue-labeled.debounce: `debounce` is declared inside `concurrency`, as `"concurrency": { "debounce": "90s" }`.
```

On push, Tessl applies each block that passes and keeps the stored state of each block that does not; see [The safety model](https://docs.tessl.io/schedules/overview.md#the-safety-model). Whether a plugin resolves, an environment exists, and your organization can use an agent, model, and effort is checked when the manifest syncs and when a run starts, not by the local check. To run the check in CI, see [Validate schedules in CI](https://docs.tessl.io/schedules/validate-in-ci.md).
