agent-workflow-author

name	agent-workflow-author
description	Create, adapt, run, and verify Open Agent Workflow harnesses. Use when Codex or another coding agent is asked to build an agentic workflow, dynamic workflow, harness, fan-out review, adversarial verification workflow, reusable workflow recipe, or `.workflow.js` file for the Open Agent Workflow runtime.

Agent Workflow Author

Use this skill to turn a substantial task into a workflow harness that can run through Open Agent Workflow.

Decision

Use a workflow when the task is large, repetitive, parallel, adversarial, or needs independent verification.

Prefer an ordinary coding session when the task is small, linear, or would be harder to understand if split across workers.

Process

1. Read AGENTS.md, README.md, and the relevant package docs before larger workflow/runtime changes.
2. Decide the workflow shape:
   • fan-out-and-synthesize for audits, broad reviews, research, and many-file checks.
   • proposal-then-verification when false positives matter.
   • generate-filter-rank for options, naming, design exploration, and planning.
   • loop-until-done for flaky bugs or iterative investigation.
   • nested workflow only when a subproblem is independently reusable.
3. Write a trusted project harness as plain JavaScript in workflows/<name>.workflow.js or examples/<name>.workflow.ts if the repo build compiles examples.
4. Run first with the mock adapter when possible, then with the requested real adapter.
5. Inspect the console or run artifacts and fix the harness until the run is understandable and evidence-backed.

Harness Rules

The runtime executes workflow code in a deterministic VM. It is not a secure sandbox for hostile code.

Required shape:

export const meta = {
  name: "short-stable-name",
  description: "What this workflow proves or produces.",
  phases: ["Plan", "Review", "Verify", "Report"],
};

export default async function run(ctx) {
  await ctx.phase("Plan");
  const result = await ctx.agent("Do focused work", { label: "worker", sandbox: "read-only" });
  await ctx.phase("Report");
  const artifact = await ctx.artifact("result", { result });
  return { result, artifact: artifact.path };
}

Do:

• Put literal export const meta = ... first.
• Use await ctx.phase(name) for visible runtime phases.
• Use ctx.parallel([...]) with thunks: () => ctx.agent(...).
• Give every worker a short stable label.
• Use sandbox: "read-only" unless edits are required.
• Use separate verifier agents for high-stakes claims.
• Persist important evidence with ctx.artifact(name, value).
• Return a compact structured final result.
• Await every ctx.agent, ctx.parallel, ctx.pipeline, and ctx.workflow call before returning.

Do not:

• Use imports, require(), shell commands, direct file IO, Date.now(), new Date(), or Math.random() in the harness.
• Let meta.phases replace runtime ctx.phase(...); metadata phases are documentation only.
• Pass already-started promises to ctx.parallel.
• Dump every intermediate result into the final answer.
• Claim the harness is securely isolated.

Commands

From this repo:

node --run build
node packages/cli/dist/bin.js guide
node packages/cli/dist/bin.js run dist/examples/security-audit.workflow.js --adapter mock --ui

From an installed package:

npx agent-workflow guide
npx agent-workflow run workflows/auth-audit.workflow.js --adapter codex --ui
npx agent-workflow serve --port 8783

Verification

After authoring a workflow, verify at least one of these paths:

• node --run validate for repo-level runtime coverage.
• A mock run with --adapter mock --ui-exit-on-complete.
• A real adapter run when the user explicitly asked for live agent work.
• Browser inspection of the run console when the request is UI/product-facing.

Check that the run has readable phases, stable agent labels, sensible artifacts, and a final result that summarizes evidence rather than raw transcript.

References

Read references/patterns.md when choosing a workflow topology or needing prompt/harness examples.