Workflow Overview

Workflows are CodeCourier's mechanism for orchestrating multi-step AI agent pipelines. Instead of sending a single prompt to a single agent, workflows let you define a sequence of agent steps -- each with its own role, CLI tool, model, and instructions -- that work together to produce higher-quality results. A workflow is a reusable blueprint; each time you execute it, CodeCourier creates a run that tracks the execution through each step.

What is a Workflow?

A workflow in CodeCourier is a template that defines how AI agents collaborate on a task. It specifies:

• What agents participate -- Each step in the pipeline corresponds to a persona (a named agent configuration with its own CLI tool, model, and instructions).
• In what order they execute -- Steps run sequentially. The output of one step becomes context for the next.
• Whether any step group iterates -- A designer+checker pair can be placed inside an Iteration Blockso the group repeats until the checker approves, up to the block's iteration cap. Steps outside an Iteration Block run once.
• What sandbox configuration to use -- The workflow carries a default sandbox config (CLI tool, model, resources) that applies to all steps unless overridden.

Core Concepts

Blueprints vs. Runs

There is a critical distinction between a workflow and a run. A workflow is a blueprint -- it defines the pipeline structure but does not execute anything. A run is an execution instance of a workflow. When you start a workflow, CodeCourier creates a run record that tracks the execution state, prompt, configuration, and results. You can execute the same workflow many times, producing multiple runs with different prompts and configurations.

Persona Pipelines

CodeCourier's workflow system uses a persona pipelinearchitecture. Each step in the pipeline is bound to a persona - a preconfigured agent identity with a specific role (designer, checker, optimizer, prompter, investigator, evaluator, judge, or answerer), CLI tool, model, and custom instructions. This means you control not just what the agent does, but how it does it.

For example, a code review workflow might define:

1. A designer persona using Claude Opus for implementation.
2. A checker persona using Claude Sonnet for E2E testing.
3. An optimizer persona for code cleanup after approval.

Iteration Blocks

Iteration is explicit and opt-in: it lives inside an Iteration Block node. Consecutive steps sharing the same loopId form one block, and the block repeats as a unit. The canonical pattern is the designer-checker block:

1. The designer implements the requested changes.
2. The checker reviews the implementation and produces a verdict.
3. If the checker passes, the block exits and the pipeline continues. If the checker fails, the designer receives the checker's feedback and the block re-runs.

Each block has its own loopMaxIterations cap (default 3) to prevent infinite loops. When the cap is hit without a passing verdict, the block terminates and the run is marked failed.

Steps outside an Iteration Block run exactly once. A checker that is not inside a block still emits a verdict (persisted on its run step) but does not trigger an automatic retry.

Execution Blocks

Under the hood the orchestrator parses the pipeline into execution blocks. Each block is either a single block (one or more steps that run once) or a loop block (the Iteration Block - a loopId group that repeats).

Execution Modes

Workflows can be triggered in several ways, each suited to a different use case:

• Direct runs - A single execution triggered manually from the workflow detail page or the Runs page. The most common entry point for one-off tasks.
• Sprint Chains - A batch execution that runs the same workflow multiple times in sequence, once per sprint. Each sprint produces its own pull request. Sprint chains are ideal for phased development work where each phase builds on the previous one. The chain tracks per-sprint PR URLs and supports resuming from any sprint index if a sprint fails.
• Recurring Tasks - Scheduled executions that fire automatically at a configured frequency (daily, every other day, weekly, biweekly, or monthly). Each firing creates a standard run with source scheduled. Recurring tasks are ideal for continuous quality checks, automated dependency updates, and other maintenance workflows that need to run on a regular cadence.
• Work Chains (issue-driven) - Sequential runs created by issue session work chains. Each item in the chain is a different issue processed through the same workflow pipeline.

Quality Scoring

Every workflow run participates in CodeCourier's quality scoring system. When the pipeline includes an Evaluator step, that step produces structured quality scores across five dimensions:

• Correctness - Does the implementation meet the requirements?
• Type Safety - Are TypeScript types correct and complete?
• Code Style - Does the code follow project conventions?
• Test Coverage - Are the changes covered by tests?
• Completeness - Is the implementation fully finished?

These five dimension scores are combined into a composite score (0–100). Each run also tracks an overall qualityScore derived from all Evaluator steps in the pipeline. Scores are visible in the run detail view and in the Monitoring dashboard, enabling trend analysis over time.

Workflow Configuration

Every workflow carries configuration that controls how its steps execute:

• Name and description -- A human-readable name and optional description for the workflow blueprint.
• Default sandbox config -- The base configuration for all sandboxes created during runs: template ID, timeout, memory, CPU count, designer model, and checker model.
• Persona pipeline steps -- An ordered array of persona references. Steps that belong to an Iteration Block carry aloopId (and the block's loopMaxIterations); steps outside any block carry neither and execute once.

How Workflows Execute

When a workflow is triggered, the following sequence occurs:

1. Run creation -- A run record is created in the database with the prompt, configuration, and a reference to the workflow blueprint.
2. Trigger.dev dispatch -- A background task is dispatched to the Trigger.dev task queue. This is the workflow orchestrator that manages the entire execution.
3. Step execution -- The orchestrator processes each execution block sequentially. For each step, it creates an E2B sandbox, sets up the environment, runs the AI agent, and records the results.
4. Verdict handling -- For checker steps, the verdict (pass/fail with feedback) determines whether the loop continues.
5. Run completion -- When all steps finish, the run status is updated to completed. If any step fails fatally, the run is marked as failed.
6. PR creation -- If the run worked on a Git branch, a pull request is created automatically.

Relationship to Other Features

• Sandboxes - Each workflow step creates and uses its own sandbox. The sandbox lifecycle is managed by the step executor.
• Personas - Workflow steps reference personas for their agent configuration. Changing a persona updates all workflows that use it.
• Issues - Issue sessions can discover problems that are executed as sequential workflow runs via work chains.
• Sprint Chains - Batch execution that runs the same workflow multiple times, each sprint producing its own PR.
• Recurring Tasks - Scheduled automation that fires the workflow at a configured frequency without manual intervention.
• Learnings - Learnings are extracted from workflow run sandboxes and fed back into future runs through compiled learning versions.
• Usage tracking - Every workflow run generates usage records for E2B compute time, AI token consumption, and overall cost.

Use Cases

• Design-Review cycles - A designer implements changes and a checker verifies them with E2E testing, looping until quality passes.
• Prompt refinement - A prompter agent refines a vague task description into a detailed prompt before passing it to a designer.
• Investigation-then-fix - An investigator analyzes the codebase to understand the issue, then a designer implements the fix based on the investigation.
• Multi-agent code generation - Different agents handle different aspects (frontend, backend, testing) of a feature in sequence.
• Quality-gated delivery - An evaluator step scores the implementation against quality thresholds before the PR is opened, ensuring only production-ready changes are submitted for review.
• Phased batch development - Sprint chains run the same workflow across multiple phases of a project, each sprint delivering a discrete, reviewable set of changes.
• Continuous automation - Recurring tasks fire quality, security, or dependency workflows on a schedule, keeping the codebase healthy without manual intervention.