Workflow, run, and runtime

• A workflow describes how a class of work should happen: inputs, context rules, instructions, steps, outputs, validation, approvals, and triggers.

• A logical work item groups recurring executions without conflating scheduler ticks.

• An attempt run records one concrete execution of one workflow version, including its trigger, attempt number, context, state, artifacts, approvals, validation, events, and outcome.

• An agent profile is the stable Celorga worker identity or responsibility attached to the work.

• An AI destination is the configured execution endpoint, such as local Codex, Claude Code, OpenClaw, or a direct model provider. It is not the agent identity.

• A runtime adapter sends work to that destination and normalizes its result into the same history. The workflow and run formats do not depend on one provider.

Repeating a prompt is useful, but it does not by itself create a workflow. A workflow earns its durable form by making the process inspectable, editable, versionable, reviewable, and reliable across executions.

File ownership

The default corpus layout separates authored process from execution state:

workflows/                 authored workflow files
.org2/runs/                generated durable run records
.org2/                     runtime bindings, correlation state, and derived control data

Older early-alpha installations may contain .org2/workflows/. Celorga continues to read that location, prefers a visible workflows/ file when both contain the same workflow ID, and provides celorga workflow migrate to move non-conflicting legacy files. New and newly saved workflows use workflows/.

One workflow per file is the default. A note or project heading may link to or invoke a workflow, while independent files keep workflow identity, version history, review, and distribution straightforward.

Creating an automation

Open Agent Work → Automations in the Mac app and choose New Automation. Give it a name and prompt, select any enabled AI destination, optionally pin an exact model and reasoning effort, optionally attach an agent profile, and either leave it manual or add an interval or cron schedule. Celorga writes the result as a normal file under workflows/. Edit Source opens that canonical file in the ordinary Celorga editor.

The minimal CLI form is:

celorga workflow create weekly-product-update \
  --title "Weekly product update" \
  --prompt "Prepare a cited update from this week's product notes." \
  --destination-ref builtin.claude \
  --model opus \
  --schedule "0 9 * * 1" \
  --timezone America/Los_Angeles \
  --dir ~/notes

The readable :AI_DESTINATION_REF: property is a symbolic reference to configured app state. Optional :MODEL: and :REASONING_EFFORT: properties pin the exact runtime choices for every manual or scheduled attempt. Leave either field absent to use that destination's configured/default value. Credentials and machine-local connection details never enter the workflow file. If the destination is missing, disabled, or cannot honor a requested reasoning level, the attempt fails visibly instead of being rerouted or silently dropping the request.

Creating and maintaining a fuller workflow

A completed one-off run can become a draft workflow:

celorga workflow save RUN_ID --id weekly-review --dir ~/notes

The saved file is a proposal, not an automatic publication or rerun. Review the concrete context copied from the original run, replace one-off values with inputs where appropriate, and inspect outputs, validation, and approval boundaries before activation.

The Mac Agent Work → Automations surface also lists fuller reusable workflows and opens the selected file in the normal Org document editor. Structured controls such as Run Now, Validate, Schedule, Activate, Pause, and View History are conveniences over the file and shared CLI.

Useful lifecycle commands include:

celorga workflow list --dir ~/notes --json
celorga workflow validate weekly-review --dir ~/notes
celorga workflow run weekly-review --dir ~/notes --json
celorga workflow due --dir ~/notes --json
celorga workflow activate weekly-review --dir ~/notes
celorga workflow pause weekly-review --dir ~/notes
celorga workflow schedule weekly-review --cron "0 9 * * 1" \
  --timezone America/Los_Angeles --model gpt-5.6-sol \
  --reasoning-effort high --dir ~/notes
celorga workflow delete weekly-review --dir ~/notes
celorga workflow delete weekly-review --dir ~/notes --apply
celorga workflow migrate --dir ~/notes

Draft, active, and paused describe operational intent. Editing the file remains possible in every state. A workflow should be validated and reviewed before an edited version becomes responsible for consequential or scheduled work.

The first workflow delete command previews the exact workflow files that would be removed; --apply performs the deletion. The Mac app exposes the same action behind a confirmation dialog. Deleting an automation removes its definition and prevents future Celorga schedule checks, but preserves every existing run and its review history. It does not cancel an attempt that has already been dispatched.

Celorga scheduling and destination dispatch

Celorga owns the portable scheduling loop. While the Mac app is running, it checks active automations once a minute and again after launch or app activation. If the Mac was asleep or Celorga was closed, it catches up only the latest missed occurrence instead of replaying every tick.

For each due occurrence Celorga:

1. Creates a durable numbered run from the exact workflow revision before contacting an AI destination.

2. Records the schedule, planned time, destination reference, agent profile, and stable logical-work ID, then carries the file-owned model and reasoning effort into dispatch.

3. Refuses to overlap a queued, running, blocked, or approval-waiting attempt for the same automation.

4. Opens a destination thread and sends the resolved prompt through the same destination-neutral path used by AI Chat.

5. Retains the reply, result, errors, artifacts, approvals, duration, and destination thread in the shared run history.

Codex, Claude Code, OpenClaw, and enabled custom or direct-provider destinations all use this path. Manual Run Now uses the same durable preparation and dispatch without waiting for the clock. Pausing the automation stops new attempts; it does not erase its source or history.

Automation threads use the workflow's exact model and reasoningEffort when present. Otherwise they use the configured destination model and runtime reasoning default. They do not inherit overrides from interactive chats. Ordinary new chats continue to remember those choices. A runtime that rejects a pinned value fails that attempt visibly; Celorga does not retry a file-configured automation with different defaults.

This first version requires Celorga to be running. A small background helper or provider-native scheduler can be added later without changing the workflow file or splitting its run history.

OpenClaw lifecycle integration

The optional org2-lifecycle plugin adds deeper OpenClaw lifecycle integration:

1. For a manual execution, the plugin instantiates the workflow into a durable Celorga run before the agent begins.

2. The plugin sends OpenClaw a workflow marker and a request to read the canonical workflow and run records.

3. OpenClaw lifecycle events update that same run instead of creating a duplicate generic run. Available provider, model, token, and elapsed-time metadata is preserved on the run, and successful terminal turns record a concise outcome summary.

4. When execution requests approval or clarification, the turn may end while the durable run remains open. Approving in the Mac app continues the existing workflow in its correlated OpenClaw chat session; a pending approval or blocked run is never treated as successful completion.

5. Outputs, validation, steps, and approvals remain visible in Agent Work as the agent records them through the shared CLI.

Run celorga doctor --dir CORPUS --json before reconciliation or execution when a long-running workspace may contain stale or hand-edited state. The read-only report identifies contradictory run/approval state, duplicate provider identities, missing workflow definitions, conflicting attempt numbers, overlapping active attempts, unmanaged OpenClaw cron series, and broken or duplicate headline projections. It exits nonzero for hard contradictions but never rewrites the canonical records automatically.

Lifecycle mutations use atomic revision-checked writes. A client that holds a run across requests should read run show ID --with-revision --json and return that token through --if-revision; even without the explicit flag, one CLI invocation protects the revision it loaded. A concurrent mutation or ambiguous direct edit therefore produces a conflict for the caller to refresh and reconcile, not a last-writer-wins overwrite.

High-volume account-oriented workflows should keep global selection state in celorga ledger accounts rather than in the workflow prompt or one append-only task heading. Resolve every available name, email, domain, and provider identity before creating an account. A workflow can query ledger list LEDGER --eligible --json, link the exact run approval through an idempotent account event, and record the provider receipt after the approved action completes. The workflow remains the recipe, each run remains one attempt, and the ledger remains durable cross-attempt subject history.

Opening a PDF output from Agent Work uses the system's default PDF application (Preview by default on macOS). Text outputs continue to open in the Celorga workspace, with raw source editing available when needed.

OpenClaw cron reconciliation remains available as an optional runtime-native clock:

1. Explicitly syncing workflows reconciles enabled generic schedule triggers into OpenClaw cron.

2. The cron payload identifies the workflow, version, and trigger; it does not maintain a separate copy of the process.

3. Each eligible execution creates a distinct numbered attempt under the workflow's stable logical-work ID. run list --json includes a logicalWork roll-up without erasing per-attempt evidence.

4. A schedule may declare --gate-event and/or --gate-path. workflow signal records event/fresh-work evidence, and the lifecycle adapter safely skips a tick when no matching signal is newer than the prior attempt.

5. Pausing the workflow disables its managed OpenClaw job at the next reconciliation.

OpenClaw job IDs and correlation mappings are adapter state. They are not part of the portable workflow definition. This boundary prevents scheduler details from leaking into authored corpus files and allows another runtime adapter to execute the same process later.

The plugin has one explicit corpusDir write target. Requests from the Mac app carry the selected portable corpus ID, and the adapter refuses to act when that identity does not match its configured corpus. Read-only mounted agenda and search views do not silently become agent write access.

Do not enable both Celorga scheduling and a provider-native clock for the same automation. Provider-native scheduling is an execution adapter, not a second canonical definition; Celorga remains authoritative for the prompt, desired schedule, review boundaries, and durable work record.

Safety and review

A workflow declares capabilities and a risk class. Expected outputs should land in reviewable locations such as views/ or compiled/, and consequential or external actions should carry an explicit approval requirement. An external-action or high-impact approval must expose the exact recipient, content, command, and attachments through an inspectable artifact, approval note, or live runtime detail; a fingerprint is integrity evidence, not review material. Once requested, Celorga fingerprints that exact material and preserves the same native approval ID/fingerprint through CLI, Mac, mobile decision transport, and OpenClaw. A mismatched --fingerprint is rejected. The Mac Agent Work surface retrieves linked OpenClaw exec details when they remain available and disables Approve when no reviewable material can be shown. Activating a schedule never weakens those boundaries.

Keep runtime credentials outside workflow files. A workflow may name a capability or symbolic runtime policy, but provider tokens, Gateway credentials, machine-local job IDs, and private scheduler state belong in runtime configuration.

Current limits

This is an early automation surface. The canonical file carries readable Org authoring fields plus a versioned machine-state block for the complete portable definition. The visible title, description, instructions, destination reference, model, reasoning effort, version, risk, and lifecycle state are authoritative when edited in source; a later structured save normalizes those values back into the complete definition. Source mode remains the complete editing escape hatch while structured assistance for inputs, steps, outputs, validation, and approvals becomes deeper. Scheduled work requires the selected desktop app or headless server process to be running. Celorga does not yet delegate clock ownership to Codex or Claude Code native schedulers.

Running without the desktop app

The headless server reuses these workflow and run records. Assign automationHostRef with preview-first celorga server assign --dir CORPUS --host-ref HOST. Updated desktop schedulers skip a corpus owned by another host. Scheduled attempt creation locks each workflow separately and refuses an already dispatched occurrence. Independently synchronized copies require one explicitly chosen owner; they do not support automatic distributed failover.