Workflows

See also: Pipelines -- deterministic script-driven steps that run before workflows. Use pipelines for context gathering and preparation, workflows for AI-driven reasoning.

Concept

User Input --> [Pipeline (scripts)] --> [Workflow (AI)] --> Enhanced Input --> AI Session
                                             |
                                             ├── Step 1: Refine query
                                             ├── Step 2: Research context
                                             └── Step 3: Validate plan

The workflow acts as a planner: it enriches and clarifies the user's request. The session AI acts as the executor: it carries out the refined task.

Configuration

Define workflows in [[workflows]] and reference layers from [[layers]]:

[[workflows]]
name = "developer_workflow"
description = "Two-stage workflow: refine task, then research context"

[[workflows.steps]]
name = "refine"
type = "once"
layer = "task_refiner"

[[workflows.steps]]
name = "research"
type = "once"
layer = "task_researcher"

Activate a workflow for a role:

[[roles]]
name = "developer"
workflow = "developer_workflow"

Step Types

Once

Execute a layer once.

[[workflows.steps]]
name = "refine"
type = "once"
layer = "task_refiner"

Loop

Repeat until an exit pattern is matched in the output.

[[workflows.steps]]
name = "validation_loop"
type = "loop"
max_iterations = 3
exit_pattern = "APPROVED"

  [[workflows.steps.substeps]]
  name = "propose"
  type = "once"
  layer = "task_refiner"

  [[workflows.steps.substeps]]
  name = "validate"
  type = "once"
  layer = "task_researcher"

Foreach

Parse output into items and process each.

[[workflows.steps]]
name = "process_items"
type = "foreach"
parse_pattern = "\\d+\\. (.+)"
layer = "item_processor"

Conditional

Branch based on pattern matching. If condition_pattern matches the output, execute on_match commands; otherwise execute on_no_match commands.

[[workflows.steps]]
name = "route"
type = "conditional"
condition_pattern = "COMPLEX"
on_match = ["echo 'Complex task detected'"]
on_no_match = ["echo 'Simple task'"]

Parallel

Execute multiple layers concurrently.

[[workflows.steps]]
name = "gather"
type = "parallel"
parallel_layers = ["researcher_a", "researcher_b"]

Pattern-Based Control

Workflows use regex patterns for flow control:

• exit_pattern (loop): Stop iterating when output matches
• parse_pattern (foreach): Extract items from output using capture groups
• condition_pattern (conditional): Branch when output matches

Brain-Inspired MAP Architecture

The MAP (Modular Agentic Planner) system models cognitive processes:

MAP templates are available in config-templates/map-planner.toml and config-templates/map-executor.toml.

Usage

In Sessions

/workflow                        # List available workflows
/workflow developer_workflow     # Execute specific workflow

Via Role Binding

When a role has workflow = "developer_workflow", the workflow runs automatically on each user message before the AI processes it.

Layer Requirements

Each workflow step references a layer. Layers must:

• Have a description field (required)
• Be defined in [[layers]] config

[[layers]]
name = "task_refiner"
description = "Refines and clarifies user requests"
command = "octomind acp task_refiner"
input_mode = "last"
output_mode = "none"
output_role = "assistant"

See Commands and Layers for layer configuration details.

Step Timing

Each workflow step captures its execution duration. The orchestrator tracks both per-step and total workflow time:

── developer_workflow | refine | Step 1/2 | 1250ms ──
── developer_workflow | research | Step 2/2 | 3400ms ──

Step outputs include:

• step_name — which step ran
• step_index / total_steps — progress indicator
• duration_ms — per-step milliseconds
• Total duration_secs — aggregate workflow time

This is useful for profiling workflow efficiency and identifying slow steps.

Best Practices

1. Use appropriate output modes: "none" for intermediate steps, "append" for final output
2. Keep patterns robust: Use anchored regex where possible
3. Set max_iterations on loops to prevent infinite cycles
4. Use cheap models for refinement layers (e.g., gpt-4.1-mini)
5. Monitor costs: Workflows add overhead -- ensure the improved output justifies it

Debugging

Enable debug logging to see workflow execution:

/loglevel debug

Check workflow status:

/workflow

Common issues:

• Layer not found: Ensure the layer name in step config matches a [[layers]] entry
• Pattern never matches: Test regex patterns against expected output
• Loop runs forever: Always set max_iterations