Workflows and reusable runbooks

Workflows and reusable runbooks

Workflows let you turn a repeatable job into a typed, durable runbook without editing Holaryn source
code. A workflow can call a model, run tools or connected apps, branch, pause for approval, wait,
fan out within a fixed bound, call another workflow, create an artifact, and return a typed result.

Open Workflows in the desktop or web navigation. The main editor is an accessible ordered
list/form. Show visual graph adds a read-only DAG; it is never required for authoring.

Your first workflow

1. Enter a workflow ID, semantic version, title, input/output JSON Schemas, and any variables.
2. Add steps in dependency order. Each Needs value names a committed predecessor.
3. Select Validate / dry-run.
4. Review dependencies, permissions, secret handles, triggers, network access, risk, and
   consequential steps. Dry-run performs no action.
5. Select Save immutable draft, then Publish selected version.
6. Enter manual run inputs and select Start pinned version.

Published definitions are immutable. Create a new version to change one. Deprecating a version
stops new starts but does not change an active run; that run remains pinned to its original version
and digest.

Use YAML or JSON

The YAML / JSON round-trip section exports the exact typed definition. An import is untrusted
and disabled by default. Review its permission, dependency, secret, trigger, network, risk, and
consequence diff, then select Approve import capabilities before publishing.

Never paste a secret value into a definition. Declare a slot name and configure it through the
scoped secret broker. Workflows persist only opaque secret handles.

CLI equivalents:

holaryn workflow list
holaryn workflow validate ./my-workflow.yaml
holaryn workflow import ./my-workflow.yaml
holaryn workflow approve-import my-workflow 1.0.0
holaryn workflow publish my-workflow 1.0.0
holaryn workflow run my-workflow --version 1.0.0 --inputs '{"topic":"release notes"}'
holaryn workflow instances --workflow-id my-workflow

The CLI queues runs in the selected state directory. Keep the desktop app, holaryn serve, or the OS
service running so scheduled, event-driven, and queued workflows execute.

Start automatically

A published definition can expose:

• a manual start in the Workflows page or CLI;
• a public API run;
• a slash command such as /research-brief accessibility testing;
• a five-field cron schedule;
• a named event, messaging-channel, or connected-app event.

Duplicate external events reuse the original workflow run when the source sends the same
idempotency key. Trigger mappings may read only the event payload, workflow variables, or literals.

Supervise and recover

The run list shows committed steps, attempt counts, output, and errors. You can cancel an active
run. Approval and wait steps persist without keeping a worker busy.

After an unexpected shutdown, Holaryn resumes an idempotent step once from its committed boundary
with the same idempotency key. It does not guess after a possibly completed non-idempotent external
action; that run enters manual recovery so you can inspect the external result and explicitly
record retry, succeeded, or failed.

Every tool and connector call still follows the normal autonomy and approval
policy. Publishing a workflow never grants blanket authority.

Included recipes

Holaryn installs five editable-by-version recipes:

• Research brief — typed research plus a Markdown artifact and /research-brief.
• Issue triage — classification, risk branch, approval, and issue routing.
• Code validation — repository checks with typed pass/fail evidence.
• Document generation — a typed draft rendered as DOCX.
• Scheduled summary — a weekday summary from a schedule trigger.

Select a recipe to inspect its exact requirements. Dry-run identifies a model, connector, secret,
or permission that still needs configuration.

Troubleshooting

• Missing dependency: connect or install the named capability, then validate again.
• Unavailable secret slot: configure that slot in the secret broker; do not edit a credential
  into the workflow.
• Waiting: provide the requested approval/signal or wait for the displayed wake time.
• Manual recovery: verify whether the external action happened before choosing retry.
• Schedule not firing: keep the persistent host running and verify the cron expression.
• Imported draft will not publish: approve the import review and resolve every dry-run error.

For the complete contract, trigger payload, runtime, security, and operator details, see
Declarative workflows.