Workflow distillation

When a procedure works, you should be able to repeat it without rediscovering every operation. Workflow distillation records an explicit Semwright task, compiles its successful steps into a Recipe candidate, and lets you review and test that candidate before publishing it to your local capability catalogue.

The useful distinction is between learning a procedure and authorizing its execution. Recording, compilation and static verification prepare a workflow. Live replay performs the work. Promotion makes the reviewed workflow discoverable; it does not grant any new application permissions.

From one task to a reusable capability

1. RecordCapture an explicit task.
2. CompileBuild a Recipe candidate.
3. VerifyCheck structure and descriptors.
4. ReplayRun it under current policy.
5. PromoteAdd a searchable capability.

Promotion requires static verification and at least one successful live replay. Each execution still enters the broker.

For example, an export task might find an object, export it, and hand its output to another application. A reusable workflow needs to find the object again and use the new export result on every run. A reference from yesterday’s session is not a durable target.

1. Record a deliberate task

Owner policy must grant workflow.record. Observe-only access does not cover recording, compilation, verification or replay. The underlying operations also need their own permissions.

semwright workflow record start export-demo --capture-values
# Perform the intended task through ordinary Semwright operations.
semwright workflow record stop

These are administration commands, not a complete application example. Use the trace ID returned by your own recording. Recording is session-scoped and limited to 64 operational steps; workflow administration and other management commands are not recursively recorded.

Value capture is explicit. By default, recorded values are redacted: those traces can help with diagnostics but cannot be compiled. Even with --capture-values, credential-shaped fields and secret-access payloads remain redacted. An expired or revoked session discards an unfinished recording.

2. Compile and inspect the candidate

semwright workflow compile export-demo --trace TRACE_ID
semwright workflow candidates
semwright workflow candidate CANDIDATE_ID

Replace the uppercase placeholders with IDs returned by your own commands. Compilation accepts one to eight successful traces with the same command sequence. They must contain captured values, known outcomes and no failed or redacted steps, and still match the current capability descriptors.

With one trace, constants remain constants unless you explicitly parameterize them. With several compatible traces, varying scalar arguments can become typed inputs. Compatible values produced by an earlier step become bindings, so replay reacquires references and uses fresh results.

Observed in the task	Preserved in the workflow
A value that stays the same	A constant, unless explicitly parameterized
A scalar argument that varies across compatible traces	A typed input
A reference or artifact path uniquely produced by an earlier step	A binding to that step’s fresh result
An opaque reference with no identifiable source	Compilation stops until it is explicitly parameterized

A matching string alone is not enough to infer dataflow. The compiler recognizes compatible structural classes such as references, identities, paths, digests and revisions. It does not guess application-specific postconditions.

3. Verify, then replay deliberately

semwright workflow verify CANDIDATE_ID

Verification validates the Recipe and checks its stored descriptor digests against the current catalogue. It checks whether the procedure is still structurally valid; it does not perform the task or prove the application outcome.

Inspect the candidate’s inputs before live replay. For a candidate with no required inputs, the command takes this form:

semwright workflow replay CANDIDATE_ID --args-json '{}'

Supply the candidate’s actual inputs instead of an empty object when required. A live replay is rejected until static verification succeeds. Dry-run replay can help with planning, but it does not count as successful live evidence. Every live step checks current policy and references and invokes its provider through the normal broker path.

A learned mutation does not acquire an automatic retry. If an outcome is uncertain, inspect the application’s state before deciding what to do next. See Effects and readback for the distinction between a command response and evidence of a change.

4. Promote the reviewed procedure

After successful verification and at least one successful live replay, an owner with workflow.manage can promote the candidate:

semwright workflow promote CANDIDATE_ID export-mobile-assets

The resulting capability is recipe.export-mobile-assets.run. It appears in normal capability search with Recipe provenance. Its permissions are the union of its steps, its risk is their maximum, and consent and idempotency are aggregated conservatively.

Promoted recipeA reviewed sequence with inputs.

Broker checksPolicy, references and provider selection.

Each operationRuns with its existing permissions.

A reusable capability preserves the execution boundary. Promotion changes discoverability, not authority.

What changes after an application update?

Candidates record their source descriptors. A changed descriptor causes a verification conflict: review and recompile rather than assuming that the same name still means the same operation. Drift is checked again before a promoted workflow executes.

Completed traces and candidates remain in the private owner library across daemon restarts. Configured providers load first; stale promotions are reported and are not registered. The library is bounded to 8 MiB and rejects corrupt or inconsistent stored state.

To remove a workflow from the live catalogue while retaining its candidate:

semwright workflow demote export-mobile-assets

Deletion is a separate destructive operation. A promoted candidate must be demoted before deletion, and a referenced trace cannot be deleted while a candidate depends on it.

How repeated tasks become suggestions

V2 and V3 analyze the same explicitly recorded traces. They do not watch background application activity.

Stage	What Semwright prepares	What you still decide
V1: deliberate compilation	A candidate from selected successful traces	Verify, replay and promote
V2: repeated-pattern mining	Advisory patterns and suggestions; the default suggestion threshold is three successful compatible traces	Choose a suggestion to compile, then verify, replay and promote
V3: automatic proposals	An in-memory candidate and static validation from at least three compatible value-capturing traces	Accept the exact proposal, then replay and promote

A V2 suggestion needs at least two compatible, successful, unredacted value-capturing traces to compile. Metadata-only traces can establish repetition but cannot supply a compilable procedure.

V3 proposals expose sanitized metadata: command names, inferred input types, aggregate permissions and risk, and evidence counts. They do not expose captured constants or the compiled Recipe. Planning a proposal is always a dry run. Accepting one persists the exact candidate and its static verification; it does not execute it.

semwright workflow proposals
semwright workflow proposal PROPOSAL_ID
semwright workflow accept-proposal PROPOSAL_ID

New evidence produces a different proposal ID, so stale acceptance fails. Evidence tiers are deterministic heuristics, not probabilities of success or a basis for granting permissions.

Choose the right kind of reuse

Use an Agent Skill to guide how an agent approaches a task. Use a Recipe for a declarative sequence of typed operations. Use workflow distillation to derive a Recipe candidate from successful explicit executions. All three retain the broker’s authorization boundary.

For a task that moves files between applications, read Artifact handoff. For a runnable fixture recipe, start with the documented fake-export example; it tests the fixture, not a live application.

Source: workflow distillation v1, v2 and v3 and CLI command definitions, source references checked 7 October 2026.