Skip to content
NatamuxNatamux

Build a workflow

A workflow is the stages list of .natamux.json. Commit the file, and everyone on the team runs the same process: the same steps, the same checks, the same agents. Each task goes through the list, and agents and people work on it as the stages say.

This page shows how the parts fit together with two full examples. For every field, see the configuration reference.

Project settings of storefront, Stages tab, with the branch Bug or feature selected. The chart shows an If node and two lanes: Bug fix, with its condition, holds Reproduce the bug, and Feature, marked Otherwise, holds Plan.Project settings of storefront, Stages tab, with the branch Bug or feature selected. The chart shows an If node and two lanes: Bug fix, with its condition, holds Reproduce the bug, and Feature, marked Otherwise, holds Plan.
A workflow in Project settings: the If node splits the task into two paths.
Select a branch, open its condition, and see both paths. Recorded on the real dashboard; the agents are stand-in scripts.

Building blocks

Section titled “Building blocks”
Block What it does Reference
Stage One step of the work. Stages
Gate auto goes on by itself. manual waits for a person. Gates
Check Output file, sections, commit, clean worktree or a command. Checks
Group 2 to 4 stages that run side by side. Stages that run side by side
Branch Paths with a condition. The task takes the first path that holds. Paths with a condition
Send back An agent, CI or a person starts an earlier stage again. Send a stage back
Own shell A report stage runs in its own shell with a new session. Stages in their own shell
End shell A done stage closes its shell to free memory. End a stage’s shell
Check on CI A stage waits for the CI runs of its work. Check a stage on CI
Run as a workflow Claude Code uses sub-agents on one stage. Run a stage as a workflow

Edit a workflow on a screen

Section titled “Edit a workflow on a screen”
  1. Open Project settings → Stages. See Project settings.
  2. Add, move or change stages, groups and branches. The chart on top shows the result.
  3. Click Save. Natamux writes .natamux.json.
  4. Commit the file. Everyone on the team now runs the same workflow.

The JSON tab shows the same file as text.

Patterns

Section titled “Patterns”

Review loop. An agent in its own shell reviews the work and sends the task back with the findings. See The review loop.

CI watcher. A stage after the pull request watches the CI jobs and sends the task back to the stage that changes code when a job fails. The solo example does this with gh in the prompt. Or tick Check on CI on a stage: Natamux pushes a snapshot, waits for the runs and sends the failed logs back itself.

A person’s gate before a risky step. Put a manual stage, or "gate": "manual", before the step: Spec before the code, Final check before the end. The task waits in state review until a person approves.

Condition from a file or from a command.

Use When
output An agent decides, and a person can read and fix the answer. Triage in the team example.
command The repository decides, for example test -f .no-review or a git check. No agent has to write a file.

Limit a loop. An agent can send a task back 2 times. The third time the stage waits for the person. To stop earlier, say it in the prompt: “After 3 rounds, stop and tell me what is left.”

Two example workflows

Section titled “Two example workflows”

The two examples are full files. Pick the one that looks like your team.

One person, one repository. The person approves the context and the spec. After that, agents write the tests and the code, review it and watch CI.

Context → Spec → [ Test spec ‖ Implement ] → Review → Watch CI and merge
 manual   manual   Copilot       Claude Code   Cursor    Copilot
                                  (workflow)    own shell
                                      ▲            │ findings
                                      └────────────┤
                                      ▲            │ conflict or failed CI
                                      └────────────┘ (from Watch CI and merge)

The task’s agent is Claude Code, so Context, Spec and Implement run in Shell 1. The other three stages name their own agent.

The send back loop of the solo workflow.

The solo file

Section titled “The solo file”
Full file: .natamux.json
.natamux.json
{
  "stages": [
    { "id": "context", "kind": "context", "gate": "manual", "output": "context.md" },
    {
      "id": "spec",
      "kind": "agent",
      "gate": "manual",
      "output": "spec.md",
      "sections": ["Goal", "Scope", "Out of scope", "Acceptance criteria"]
    },
    {
      "id": "build",
      "name": "Test spec and Implement",
      "parallel": [
        {
          "id": "test-spec",
          "kind": "agent",
          "gate": "auto",
          "output": "test-spec.md",
          "sections": ["Cases"],
          "agent": "copilot",
          "endShell": true
        },
        {
          "id": "implement",
          "kind": "agent",
          "gate": "auto",
          "workflow": true,
          "prompt": "Task: {title}\nRead {dir}/spec.md and {dir}/plan.md when they are there.\nWrite the tests first (TDD), then the code that makes them pass.\nDo not commit."
        }
      ]
    },
    {
      "id": "agent-review",
      "name": "Review",
      "kind": "agent",
      "gate": "auto",
      "output": "review.md",
      "sections": ["Findings"],
      "ownShell": true,
      "agent": "cursor",
      "endShell": true,
      "prompt": "Task: {title}\nReview the changes of this task against {dir}/spec.md. Do not change code.\nWrite {dir}/review.md with a Findings section: each problem with its file and why, or \"None\". Keep the old rounds as revisions.\nWhen a problem must be fixed, run `natamux stage back $NATAMUX_TASK_ID --to implement --reason \"<the problems, one per line>\"` and stop. Do not run natamux done.\nWhen there are no findings, commit, push and open the pull request, then run `natamux done`."
    },
    {
      "id": "ci-cd-watch",
      "name": "Watch CI and merge",
      "kind": "agent",
      "gate": "auto",
      "agent": "copilot",
      "prompt": "Task: {title}\nWatch the pull request of this task.\nWhen it has a conflict, run `natamux stage back $NATAMUX_TASK_ID --to implement --reason \"Fix the conflict\"` and stop. Do not run natamux done.\nWhen a CI job fails, run `natamux stage back $NATAMUX_TASK_ID --to implement --reason \"<the failed jobs>\"` and stop. Do not run natamux done.\nWhen all jobs are green, merge the pull request, then run `natamux done`.\nIf the task is a release, stop after the merge and tell me to run the release script. Never create or push a tag."
    }
  ]
}

The owner’s file also has review, testing, merge-prs and release stages with "enabled": false. A stage that is off stays in the file with its prompt and gate, but new tasks do not get it. Use it to keep a step you may need later, or to try a change without losing the old setup. The example leaves them out.

Solo: who runs where

Section titled “Solo: who runs where”
Stage Agent Shell
Context, Spec, Implement Claude Code (the task’s agent) Shell 1
Test spec Copilot Its own shell, closed when done
Review Cursor Its own shell, closed when done
Watch CI and merge Copilot Its own shell

See Mix agents in one task for why.

Solo: send back points

Section titled “Solo: send back points”
From To When What happens
Review Implement The review has findings Implement starts again with “What to change: …”. Review runs again after it, in a new session because Review ends its shell.
Watch CI and merge Implement A conflict in the pull request Implement fixes it. Review and Watch CI and merge run again.
Watch CI and merge Implement A CI job fails Same, with the failed jobs as the reason.

An agent may send the task back from its stage 2 times. The third time the stage waits for you. See Review by an agent.

Solo: two rules in the prompts

Section titled “Solo: two rules in the prompts”
  • After natamux stage back, the agent stops. It does not run natamux done. Natamux adds “When you are done, run natamux done, unless the steps above say not to.” to every prompt, so the prompt must say when not to.
  • A person makes the release tag. The CI stage merges the pull request, but its prompt tells the agent to stop at a release and never create a tag.
Section titled “Related”