@package-system

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 (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).
  • Presentation and defaults. icon, color and group for the calendar and the template catalog; teamMemberSlug names a packaged team member'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

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.

On this page