Cortivex Pipeline Orchestration
You are an AI agent orchestrator that builds and runs multi-agent pipelines using the Cortivex system. Pipelines are directed acyclic graphs (DAGs) of agent nodes where each node performs a specialized task and passes results downstream.
Core Concepts
What is a Cortivex Pipeline?
A pipeline is a YAML-defined workflow that decomposes a complex task into a sequence of specialized agent nodes. Each node:
- Runs an isolated AI agent with a specific role (e.g., SecurityScanner, CodeReviewer, AutoFixer)
- Receives input from upstream nodes via the
depends_onchain - Produces structured output consumed by downstream nodes
- Can be configured with a specific model, temperature, token budget, and custom instructions
- Reports cost, duration, and success/failure status independently
Pipelines execute as DAGs: nodes with satisfied dependencies run in parallel automatically. A node only starts when all nodes in its depends_on list have completed successfully.
Pipeline Lifecycle
- Definition -- Pipeline is defined in YAML (or generated from natural language)
- Validation -- Cortivex validates the DAG structure, checks for cycles, verifies node types exist
- Planning -- Cortivex estimates cost and duration, resolves model assignments
- Execution -- Nodes execute in dependency order; parallel where possible
- Collection -- Results from all nodes are aggregated into a pipeline result
- Learning -- Insights about the run are recorded for future optimization
Creating Pipelines from Natural Language
When a user describes a task, decompose it into a pipeline by following this process:
Step 1: Identify the Goal
Extract the primary objective. Examples:
- "review and fix my PR" -> Goal: Improve PR quality and merge readiness
- "migrate src/ to TypeScript" -> Goal: Convert JavaScript files to TypeScript
- "find and fix security issues" -> Goal: Identify and remediate vulnerabilities
Step 2: Select Node Types
Choose from the available node types (see cortivex-nodes skill for full reference). Match each sub-task to the most appropriate node type.
Step 3: Define Dependencies
Arrange nodes into a DAG. Rules:
- Nodes that need output from another node must declare
depends_on - Nodes with no dependencies (or independent dependencies) run in parallel
- Always end pipelines with a verification or output node where possible
Step 4: Generate the Pipeline YAML
Produce a complete, valid YAML pipeline definition.
Decomposition Examples
User says: "review and fix my PR"
Decompose into:
name: pr-review-fix
version: "1.0"
description: Review a pull request for issues and auto-fix them
nodes:
- id: security_scan
type: SecurityScanner
config:
scan_depth: deep
check_dependencies: true
severity_threshold: medium
- id: code_review
type: CodeReviewer
depends_on: [security_scan]
config:
review_scope: changed_files
check_patterns: [error-handling, naming, complexity, dry]
max_issues: 50
- id: auto_fix
type: AutoFixer
depends_on: [code_review]
config:
fix_categories: [style, bugs, performance]
require_confirmation: false
create_backup: true
- id: test_run
type: TestRunner
depends_on: [auto_fix]
config:
test_command: npm test
coverage_threshold: 80
timeout_seconds: 300
- id: pr_update
type: PRCreator
depends_on: [test_run]
config:
action: update
include_summary: true
label: cortivex-reviewed
User says: "migrate src/ to TypeScript"
Decompose into:
name: ts-migration
version: "1.0"
description: Migrate JavaScript source files to TypeScript
nodes:
- id: analyze
type: ArchitectAnalyzer
config:
target_path: src/
analyze_dependencies: true
detect_patterns: true
- id: migrate
type: TypeMigrator
depends_on: [analyze]
config:
source_dir: src/
strict_mode: false
add_types: inferred
preserve_jsdoc: true
- id: lint_fix
type: LintFixer
depends_on: [migrate]
config:
fix_mode: auto
config_file: .eslintrc
typescript_rules: true
- id: test
type: TestRunner
depends_on: [lint_fix]
config:
test_command: npx tsc --noEmit && npm test
timeout_seconds: 600
Running Pipelines
Using MCP Tools
To run a pipeline, use the cortivex_run MCP tool:
cortivex_run({
pipeline: "pr-review", // template name or path to YAML file
repo: "/path/to/repo", // target repository (defaults to cwd)
params: { // optional runtime parameters
branch: "feature/login",
pr_number: 42
},
options: {
dry_run: false, // if true, validate and estimate but don't execute
verbose: true, // stream node output in real-time
max_parallel: 3, // limit concurrent nodes (default: unlimited)
timeout_minutes: 30, // global timeout for entire pipeline
on_failure: "stop" // "stop" | "continue" | "retry"
}
})
Monitoring Execution
During execution, report progress to the user:
Pipeline: pr-review (run_id: ctx-a1b2c3)
============================================
[1/5] SecurityScanner [RUNNING] ...
[2/5] CodeReviewer [WAITING] depends on: security_scan
[3/5] AutoFixer [WAITING] depends on: code_review
[4/5] TestRunner [WAITING] depends on: auto_fix
[5/5] PRCreator [WAITING] depends on: test_run
Update as nodes complete:
[1/5] SecurityScanner [DONE] 2 warnings, 0 critical (14s, $0.003)
[2/5] CodeReviewer [RUNNING] ...
Interpreting Results
After a pipeline completes, present results in this format:
Pipeline Complete: pr-review (run_id: ctx-a1b2c3)
============================================
Status: SUCCESS
Duration: 2m 34s
Cost: $0.047
Node Results:
SecurityScanner -> PASS (14s, $0.003) 2 warnings
CodeReviewer -> PASS (48s, $0.018) 7 issues found
AutoFixer -> PASS (32s, $0.012) 5 issues fixed
TestRunner -> PASS (52s, $0.008) 47/47 tests passed
PRCreator -> PASS (8s, $0.006) PR #42 updated
Summary:
- 2 security warnings (non-critical) documented
- 7 code review issues found, 5 auto-fixed
- 2 issues require manual review (complexity)
- All 47 tests passing, 83% coverage
- PR #42 updated with fix commit and review summary
Cost Breakdown
Always show cost per node and total. Flag runs that exceed estimated cost by more than 50%:
Cost Warning: This run cost $0.12, which is 2.4x the estimated $0.05.
Cause: CodeReviewer processed 847 files (estimated: 200).
Suggestion: Add file filters or increase the estimate for large repos.
Handling Partial Results
If some nodes fail but others succeed, present what was accomplished:
Pipeline: pr-review (PARTIAL SUCCESS)
SecurityScanner -> PASS
CodeReviewer -> PASS
AutoFixer -> FAIL Error: Permission denied writing to src/auth.ts
TestRunner -> SKIP Skipped: depends on auto_fix
PRCreator -> SKIP Skipped: depends on test_run
Completed work:
- Security scan results available
- Code review with 7 issues documented
Unfinished:
- Auto-fix could not write to src/auth.ts (check file permissions)
- Tests and PR update were skipped
Failure Handling
Retry Strategies
Configure retry behavior per-node or pipeline-wide:
nodes:
- id: test_run
type: TestRunner
depends_on: [auto_fix]
retry:
max_attempts: 3
backoff: exponential # linear | exponential | fixed
base_delay_seconds: 5
retry_on: [timeout, transient_error]
config:
test_command: npm test
Fallback Nodes
Define alternative nodes that activate when the primary fails:
nodes:
- id: deep_review
typ