Building Workflows

Building a workflow in CodeCourier means defining a reusable blueprint that orchestrates AI agents in a multi-step pipeline. This guide walks through the workflow creation process, from choosing personas to configuring loops and sandbox settings.

Creating a New Workflow

Navigate to the Workflows page in your project dashboard and click the "New Workflow" button. The workflow creation dialog guides you through the configuration.

Pipeline Architecture

Step Ordering

Steps execute in the order they appear in the personaPipelineSteps array. The workflow orchestrator processes them sequentially -- step 2 does not start until step 1 completes. This ensures that each step can build on the work of previous steps.

Iteration Blocks (loop groups)

An Iteration Block is how you opt a group of steps into repeated execution. Consecutive steps sharing the same loopIdform one block, and the block repeats until the block's checker returns a passing verdict or the block's loopMaxIterations is reached. Steps without a loopId run once, in order. The typical iteration pattern is:

// Example: persona pipeline steps with a loop
personaPipelineSteps: [
  {
    personaId: prompterPersonaId,
    // No loopId -- runs once
  },
  {
    personaId: designerPersonaId,
    loopId: "design-review",
    loopMaxIterations: 3,
  },
  {
    personaId: checkerPersonaId,
    loopId: "design-review",
    loopMaxIterations: 3,
  },
  {
    personaId: optimizerPersonaId,
    // No loopId -- runs once after the loop
  },
]

In this example, the prompter runs first (once), then the designer and checker loop up to 3 times, and finally the optimizer runs once after the loop exits.

Execution Blocks

The orchestrator parses the flat step array into execution blocks:

• Single blocks -- Steps without a loopId. They execute once in order.
• Loop blocks -- Groups of steps with the same loopId. They repeat as a group until the checker passes or the max iteration count is reached.

If no steps carry a loopId, the pipeline executes linearly - each step runs exactly once. A checker without an Iteration Block still produces a verdict on its run step, but does not trigger an automatic retry. To enable retry-on-fail, wrap the relevant steps in an Iteration Block.

Editing Workflows

Existing workflows can be edited from the workflow detail page. You can change:

• Name and description.
• Persona step order and composition.
• Loop IDs and max iterations.
• Default sandbox configuration.

Edits apply to future runs only. Runs that are already in progress continue with the configuration they were started with. The updatedAt timestamp on the workflow record tracks when the last edit was made.

Duplicating Workflows

You can duplicate an existing workflow to create a variant. The duplicate inherits all configuration from the original (name, steps, sandbox config) with "(copy)" appended to the name. This is useful for creating A/B test variants -- for example, the same pipeline with different models or iteration counts.

Workflow Types

The workflow's type field defines its execution pattern. New workflows use persona_pipeline, but CodeCourier supports several types for backward compatibility:

• persona_pipeline -- The current default. Steps are defined by persona references with optional loop groups. This is the most flexible type.
• custom_pipeline -- Steps are defined inline with type, CLI, model, and instructions. Each step is a raw configuration object rather than a persona reference.
• designer_checker-- A simplified two-step pattern: designer runs, then checker produces a verdict. Uses the workflow's defaultCheckerInstructions. The pair runs once - to enable retry-on-fail, use a persona pipeline and wrap the two steps in an Iteration Block.
• single_designer -- A single step that runs the designer once with no checker loop.

Best Practices

• Start simple -- Begin with a two-step designer-checker workflow before adding more steps. Complex pipelines are harder to debug.
• Use appropriate models -- Use Opus for design work that requires deep reasoning and Sonnet or Haiku for checker steps that perform verification. Evaluator steps generally perform well on Sonnet given their structured output requirements.
• Set reasonable iteration limits -- Inside an Iteration Block, 3 iterations is a good default. More than 5 rarely improves results and increases cost significantly.
• Write clear persona instructions -- The quality of workflow output depends heavily on the instructions in each persona. Be specific about what each step should do and what constitutes success.
• Gate PRs with evaluators -- Add an evaluator as the final step before PR creation to enforce a quality threshold. Start with a threshold of 70 and tune upward as your pipeline matures.
• Test with small tasks first -- Run your workflow on a small, well-defined task before using it for large features. This helps you tune the pipeline without wasting resources.