Workflows
workflows[] — workflow templates a package ships as blueprints for scheduled or recurring agent runs.
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
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(acronexpression or aoncetimestamp, both bounded byendAt, cron additionally bymaxRuns),webhook, andmessage. 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
inputsmap describes its{{PLACEHOLDER}}parameters using the GitHub-Actionsworkflow_dispatch.inputsfield names (description,required,typestring/choice/boolean,default,options). Three placeholder names are engine-owned and rejected as input keys —WORKFLOW_DIR,WORKFLOW_STATE_URI, andFIRE_TIME, all substituted at fire time. - Visibility. An optional
requires.featuresgate carries the same semantics asrequiredFeatureson markdown contributions (Instructions → Visibility). - Presentation and defaults.
icon,colorandgroupfor the calendar and the template catalog;teamMemberSlugnames a packaged team member's agent (validated, but no runtime reads it yet);defaultStateMode(freshstarts each run clean,continuekeeps the run conversation); adefaultSessionSetupcarrying the run's goal and loop bounds; andrequiredCredentials, the credential-catalog ids the instruction's skills and tools will need. - Execution policy.
defaultExecutionPolicycarriesmaxConcurrent,maxRuntimeMs, and optionally a model id (modelId),reasoningEffort, an exact catalog-declared base or extendedcontextWindowOverride, andfastMode. 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 explicitfalsemeans 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
deliveryintent (announce/webhook/none) and thechannelKindsit expects to deliver to: anannouncetemplate 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
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
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.