workflow-authoring

Workflow authoring

Use this guide when a task benefits from deterministic fan-out across many focused agents, direct MCP data calls, or durable child sessions. Do not use a workflow for one small sequential task that the current session can do directly.

Start with current capabilities

Call mcp__opensession-workflows__workflow_capabilities when model choice or run size matters. It returns the live model ids, default model, concurrency, lifetime, timeout, and child-session limits. Do not guess model ids or copy an old model list into a script.

Script shape

Pass plain JavaScript, not TypeScript, to run_workflow. Do not use imports. Export meta, then write the async body with top-level await and return:

export const meta = {
  name: "route-audit",
  description: "Audit routes for missing auth checks",
  phases: [{ title: "List" }, { title: "Audit" }, { title: "Rank" }],
};

phase("List");
const files = await agent("List the route files. Return only a JSON array.", {
  schema: { type: "array", items: { type: "string" } },
});
if (!files) return "Listing failed";

phase("Audit");
const findings = await parallel(
  files.map(
    (file) => () =>
      agent(`Read ${file} and report missing auth or validation checks.`, {
        label: file,
      }),
  ),
);

phase("Rank");
return findings.filter(Boolean);

meta.name is required and should be a short slug. description and phases are optional. Predeclared phases make progress understandable before work reaches them.

Injected globals

agent(prompt, opts?)

Run one focused model turn. Agents begin with no conversation context, so every prompt must include the paths, constraints, and output contract it needs.

Options:

{
  label,   // short progress label
  phase,   // phase override for this call
  schema,  // JSON Schema; returns parsed validated data
  model,   // current model id from workflow_capabilities
  effort,  // low, medium, high, xhigh, or max when supported
  write,   // opt into a branch-producing write agent
}