# Workflows (https://docs.neuralisapp.com/package-system/workflows)

Packages can ship **workflow templates** — blueprints for scheduled or
recurring agent runs. They are deliberately **not** a markdown category:
`workflows/*.json` becomes a parallel typed array (`PackageWorkflow[]`) like
`tools`, is validated strictly at load (an invalid template fails the package
load), and is never injected into the system prompt. The model reaches
templates only through the workflow routes, with the `manage-workflows` skill's
template scripts (list, install, upgrade); users reach them through the same
routes and the Calendar's template browser.

If your package ships templates, add `workflows` to the `package.json#files`
whitelist.

## The template shape [#the-template-shape]

A template declares its id (from the filename), a `title` and `description`, a
`defaultInstructionTemplate`, and optional `defaultTriggers`.

- **Triggers.** All four kinds are authorable — `manual`, `schedule` (a `cron`
  expression or a `once` timestamp, both bounded by `endAt`, cron additionally
  by `maxRuns`), `webhook`, and `message`. The engine-runtime fields inside a
  trigger (fire counters, next-fire time, webhook token material) are rejected
  at validation. Cron defaults always carry the UTC timezone (template inputs
  never reach triggers, so a shipped cron must not depend on install-time
  locale) — say so in the description and let users edit the schedule after
  install.
- **Inputs.** An optional `inputs` map describes its `{{PLACEHOLDER}}`
  parameters using the GitHub-Actions `workflow_dispatch.inputs` field names
  (`description`, `required`, `type` `string`/`choice`/`boolean`, `default`,
  `options`). Three placeholder names are engine-owned and rejected as input
  keys — `WORKFLOW_DIR`, `WORKFLOW_STATE_URI`, and `FIRE_TIME`, all substituted
  at fire time.
- **Visibility.** An optional `requires.features` gate carries the same
  semantics as `requiredFeatures` on markdown contributions
  ([Instructions → Visibility](https://docs.neuralisapp.com/package-system/instructions.md#visibility)).
- **Presentation and defaults.** `icon`, `color` and `group` for the calendar
  and the template catalog; `teamMemberSlug` names a packaged
  [team member](https://docs.neuralisapp.com/package-system/team.md)'s agent (validated, but no runtime reads
  it yet); `defaultStateMode` (`fresh` starts each run clean, `continue` keeps
  the run conversation); a `defaultSessionSetup` carrying the run's goal and
  loop bounds; and `requiredCredentials`, the credential-catalog ids the
  instruction's skills and tools will need.
- **Execution policy.** `defaultExecutionPolicy` carries `maxConcurrent`,
  `maxRuntimeMs`, and optionally a model id (`modelId`), `reasoningEffort`, an
  exact catalog-declared base or extended `contextWindowOverride`, and
  `fastMode`. Template and persisted values are null-free: omission means
  inherit from the target agent. Clearing is a runtime update operation, not an
  authored template value, and an explicit `false` means fast mode is off.
  Provider capability validation is performed by the consuming workflow runtime
  rather than duplicated in the package kernel.
- **Delivery.** A template may declare a `delivery` intent (`announce` /
  `webhook` / `none`) and the `channelKinds` it expects to deliver to: an
  `announce` template installs with announce delivery already enabled on the
  entry, and the install surfaces show the channel hint — actual routing still
  requires an explicit channel binding created by the user.

## Install and lifecycle [#install-and-lifecycle]

Installing a template validates the supplied inputs, substitutes them into the
instruction, and creates a **draft** workflow owned by the installing user —
every later fire runs with that user's current permissions. Disabling the
source package suspends installed workflows at their next fire instead of
running them; re-enabling does not auto-resume.

## Revisions [#revisions]

A template may carry an optional `revision` (a positive integer; omitting it
means revision 1). Because installing **copies** the instruction into the
workflow rather than live-linking it, bumping a shipped template's `revision`
is how you signal that already-installed copies are stale: the platform pauses
an out-of-date active copy (surfacing an "upgrade required" reason) rather than
silently rewriting a user's installed instruction. Someone allowed to edit that
workflow then upgrades it in place — it keeps its identity, run history and
state — and resumes it after reviewing the new text.
