cortivex-pipeline

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_on chain
• 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

1. Definition -- Pipeline is defined in YAML (or generated from natural language)
2. Validation -- Cortivex validates the DAG structure, checks for cycles, verifies node types exist
3. Planning -- Cortivex estimates cost and duration, resolves model assignments
4. Execution -- Nodes execute in dependency order; parallel where possible
5. Collection -- Results from all nodes are aggregated into a pipeline result
6. 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