Step types

Each step in a pipeline has a step_type that determines what it does when executed. There are seven step types.

Agent

Runs an LLM agent to perform a task. This is the most common step type.

Resolution order

The executor resolves which agent and role to use in this order:

1. role_id on the step (or config.role_id) -- looks up the role's assigned_agent_id and uses the role as an override.
2. agent_id on the step -- uses the agent directly (the agent's default role applies).
3. Fallback -- uses the first available agent if neither is set.

Required fields

Either agent_id or role_id must be set. Validation rejects agent steps that have neither.

Config fields

Behavior

• The agent receives the pipeline context (ticket details, git branch, previous outputs, gate feedback).
• When the pipeline trigger is cron, the agent uses the role's cron_task template instead of ticket_task.
• The result is a StepResult with passed: true/false and the agent's output text.

Council

Runs a multi-agent council session. Multiple roles collaborate on the task through structured conversation.

Required fields

council_id must be set. The agent_id field should be null for council steps.

Config fields

Same as agent steps. The council configuration (roles, orchestration mode) is defined on the council itself.

Behavior

The council executor manages the multi-agent session and returns a single StepResult. See Councils for details on council configuration.

Gate

A quality gate that evaluates the output of the previous step against specified criteria. Gate steps use an LLM agent to perform the evaluation.

Resolution

Gate steps resolve their agent the same way as agent steps (via role_id, agent_id, or fallback). The agent receives the previous step's result and the gate criteria.

Config fields

Behavior

• Receives the most recent StepResult from the pipeline context.
• The agent evaluates the output against the criteria and returns passed: true or passed: false.
• On failure, the gate's output is stored as gate_feedback in the pipeline context. If the failing step connects to another agent via an on_fail edge, that agent receives the feedback so it knows what to fix.
• The ticket_source is updated to the gate's role name, so downstream agents know the feedback came from the gate.

Cron

A polling step that repeatedly executes a function (agent or lambda) at a fixed interval until it signals completion or times out. See Cron and scheduling for the full reference.

Required fields

At least one of role_id, lambda_id, or council_id must be set. If both lambda_id and role_id are present, lambda takes precedence.

Config fields

Duration format

Durations use a simple format: a number followed by a unit suffix.

Signaling

The function signals its status using a JSON object in its output:

{"cron_status": "pass", "reason": "PR was merged"}

A legacy format is also supported: CRON_DONE:PASS and CRON_DONE:FAIL markers in the output text.

Modes

Lambda

Runs a deterministic script without an LLM. Use lambda steps for tasks like running tests, checking git status, or calling external APIs.

Required fields

lambda_id must be set (either on the step or in config.lambda_id).

Config fields

Behavior

• The script is resolved from ~/.nenjo/lambdas/{lambda.path}.
• Pipeline context is injected via NENJO_* environment variables and a NENJO_CONTEXT_FILE JSON file.
• The script's exit code determines passed: exit 0 means pass, non-zero means fail.
• stdout is captured as the step's output.

See Lambdas for the full reference.

Terminal

Marks a successful end of the pipeline. Every pipeline must have at least one terminal step.

Required fields

None. Terminal steps do not require agent_id, role_id, or any other reference.

Behavior

• Returns the most recent step result from the pipeline context.
• If no previous steps have run (single-step pipeline), returns passed: true with the initial input as output.
• Terminal steps must not have outgoing edges.

TerminalFail

Marks a failure end of the pipeline. Use this to explicitly terminate a pipeline with a failure status when a particular path is reached.

Config fields

Behavior

• Always returns passed: false with the configured failure reason as output.
• Useful for explicit failure paths in branching pipelines (e.g., after exhausting retry options).

Summary table