Pipelines

Pipelines allow you to define multi-stage workflows that execute sequentially, with optional approval checkpoints between stages. Each stage can use a different model selected by topic.

How Pipelines Work

1. Define stages: Each pipeline consists of ordered stages with specific topics and prompts
2. Execute sequentially: Stages run one after another, with each stage’s output available to the next
3. Topic routing: Each stage specifies a topic; the best model for that topic is selected automatically
4. Approval gates: Optional checkpoints pause execution and wait for user approval

Pipeline Templates

Templates are reusable pipeline definitions that can be created, edited, and shared through the web UI.

Creating Templates

Use the Pipelines page in the web UI to create templates with:

• Name: A descriptive name for the pipeline
• Description: What the pipeline does
• Stages: Ordered list of stages, each with:
  • Stage name
  • Topic (for model routing)
  • Prompt template
  • Whether an approval gate follows this stage

Template API

Method	Endpoint	Description
GET	/api/pipelines/templates	List all templates
POST	/api/pipelines/templates	Create a new template
PUT	/api/pipelines/templates/:id	Update a template
DELETE	/api/pipelines/templates/:id	Delete a template

Approval Gates

Approval gates are optional checkpoints that pause pipeline execution and wait for user input.

When a pipeline reaches an approval gate:

1. Execution pauses
2. A notification is sent to the user
3. The user reviews the output so far
4. The user can:
   • Approve — continue to the next stage
   • Skip — skip the next stage and continue
   • Stop — terminate the pipeline

QA Retry Loop

Pipeline stages can be typed as qa_validation, which enables automatic retry with feedback injection. When a QA stage determines that the output from a previous stage does not meet quality standards, the pipeline automatically retries the failed stage with the QA feedback included in the prompt.

How It Works

1. A stage is marked with type: "qa_validation" in the template
2. The QA stage evaluates the previous stage’s output against defined criteria
3. If validation fails, the pipeline retries the preceding stage with feedback injected
4. This loop repeats up to 3 times before the pipeline fails or requires manual intervention

Configuration

In a pipeline template, set the stage type, max retries, and which stage to retry:

{
  "name": "Code Quality Check",
  "stageType": "qa_validation",
  "topic": "review",
  "maxRetries": 3,
  "retryTargetStage": 2,
  "prompt": "Review the code from the previous stage. Check for correctness, edge cases, and test coverage."
}

Field	Description	Default
stageType	"standard" or "qa_validation"	"standard"
maxRetries	Max retry attempts before escalation	3
retryTargetStage	Index of the stage to re-run on failure	Previous stage

These fields are configurable per-stage in the pipeline template editor UI (checkbox + dropdowns).

Note

After maxRetries failed attempts, the pipeline pauses at an approval gate so the user can intervene or abort.

Handoff Context Documents

When a pipeline transitions between stages, a structured handoff document is generated and passed to the next stage. This ensures continuity and prevents context loss between agents.

Handoff Document Structure

Each handoff document contains:

Section	Description
Decisions	Key decisions made during the stage and their rationale
Artifacts	Files created, modified, or referenced (paths, descriptions)
Open Questions	Unresolved issues or ambiguities for the next stage to address
Summary	A concise summary of what was accomplished

Handoff documents are stored with the pipeline run and visible in the web UI’s pipeline detail view. They provide an audit trail of how each stage contributed to the final result.

Pipeline Runs

Method	Endpoint	Description
GET	/api/pipelines	List your pipeline runs
GET	/api/pipelines/:id	Get pipeline detail with stages
POST	/api/pipelines/:id/stop	Stop a running pipeline

Real-Time Events

Pipeline progress is streamed via WebSocket, allowing the web UI to show live updates as stages execute and complete.

Example Use Cases

• Code Review Pipeline: Analyze code, run tests, generate review summary, await approval, then create PR
• Research Pipeline: Search for information, summarize findings, verify sources, compile report
• Deployment Pipeline: Run tests, build artifacts, await approval, deploy to staging