Write custom workflows

Custom workflows are the main way to make nax fit a team’s recurring work. A workflow lives in a directory with one flow.* file and a prompts/ folder. The file describes orchestration; the Markdown prompts describe the work each agent should do.

The most useful workflows usually preserve independent first passes before the agents see each other’s output. Later steps can feed those results forward for cross-review, consensus synthesis, or human approval.

mkdir -p .github/nax-flows/conversion-audit/prompts

id: conversion-audit
title: Conversion Audit
description: Audit key conversion paths and synthesize one prioritized plan.
 
defaults:
  transport: auto
  agents: [claude, gemini, codex]
 
steps:
  - id: audit
    title: Audit Conversion Paths
    prompt: prompts/1_audit.md
    action: issue
    submit: new-run
    agents: [claude, gemini, codex]
    waitFor: agent-results
 
  - id: synthesize
    title: Synthesize Plan
    prompt: prompts/2_synthesize.md
    action: issue
    submit: new-run
    agents: [codex]
    input:
      - step: audit
        results: all
    waitFor: agent-results

# Audit conversion paths
 
Study checkout, pricing, signup, and activation. Report concrete friction with file references, user impact, and a suggested fix.

# Synthesize conversion plan
 
Read the prior audit results. Deduplicate findings, reject weak claims, and produce one ranked plan with implementation locations and verification steps.

nax list --verbose
nax run conversion-audit --dry --force

Custom flow roots

{
  "flowsDirs": [
    ".github/nax-flows",
    "tools/nax/flows"
  ]
}

Design guidance

• Give each step one job.
• Run independent first-pass steps with submit: new-run before cross-review steps read prior outputs.
• Use waitFor: agent-results when later steps depend on all prior outputs.
• Use submit: follow-up when the same agent should continue an earlier runner context.
• Use submit: new-run when a step should start with a clean context plus selected inputs.
• Use a single synthesis step when you want a concise artifact for human review.

See also

• Workflow file reference for every supported key.
• Run workflows for execution flags.
• Council pattern for designing multi-model review loops.
• Architecture for how prompts become agent runs.