Build a workflow

Start with a small process you already understand. Name the input, the deliverable and the evidence needed to accept it. Then decide which steps require model judgment.

Begin with the working file

The coding starter lives at laufwerk/workflows/coding/workflow.ts. It is a complete example with imports and explicit cleanup. Read it before assembling a larger system.

Input → model work → deterministic check → optional decision → result

Keep a simple command deterministic. Use an agent when the step needs interpretation, investigation or generation. More agents are not automatically better.

Define what success means

For code, exercise behavior with tests. For a report, require structured observations and inspect the supporting evidence. For a document, check the claims that are mechanically verifiable and review those that are not.

A model saying “all checks pass” is not the test result. The workflow needs to run the actual check and fail on a nonzero exit code. Decide the permitted change boundary before the run.

Return structured data

Within a workflow, pass an Effect Schema to Session.run or session.ask:

const Report = Schema.Struct({
  summary: Schema.String,
  findings: Schema.Array(Schema.String),
});
const report = yield* Session.run({
  key: "review",
  agent: reviewer,
  workspace,
  access: "read-only",
  prompt: "Inspect the files. Summarize the evidence and identify problems.",
  output: Report,
});

This fragment assumes your workflow has a reviewer and workspace. See the complete incident example for a full file.

Laufwerk adds JSON schema guidance before inference and validates the response afterward. This is not constrained generation and does not guarantee a correct answer. An invalid response fails without automatically repeating a potentially side-effecting turn.

Set access deliberately

Use a read-only workspace for review and read-write access for implementation. Prompt instructions are not a substitute for enforced permissions. Keep host credentials out of task files.

A continuous session must close at the intended durable boundary. Do not replace explicit close with a generic Effect finalizer: ordinary finalizers can run when a workflow suspends, too. The generated starter handles the success/failure path explicitly.

Add repair only when it helps

A negative review means the candidate needs a change. A provider error means the review did not finish. Treat them differently. If you add a loop, set a small attempt limit and keep the original evidence; do not implement “retry until green.”

External actions such as creating a PR need stable business identity and external receipts. The factory reference explains the boundary. A local workflow record cannot guarantee exactly-once execution of an arbitrary external API.

Use your coding assistant

Initialization installs laufwerk-authoring. You can ask your assistant:

Read this project's Laufwerk authoring skill and the generated coding workflow.
Explain its input, agent step, verification and write-back boundary.
Help me adapt it to one small task. Preserve project identity, use a new
execution key, and run deterministic verification. Do not publish anything.

Review what it creates. The skill is help with authoring, not proof that the resulting workflow is correct.

Add a human decision →