Cortivex Node Type Reference

Every node in a Cortivex pipeline is an instance of a node type. Each node type defines a specialized agent role with default behaviors, model assignments, and configuration options.

Node Type Summary Table

Detailed Node Type Reference

1. SecurityScanner

Category: analysis Purpose: Scans source code and dependencies for security vulnerabilities, insecure coding patterns, exposed secrets, and known CVEs in dependencies.

When to use:

• Before merging any PR that touches authentication, authorization, cryptography, or data handling
• As part of nightly or pre-release security audits
• When onboarding a new dependency
• After any code change to security-sensitive modules

Default configuration:

- id: security_scan
  type: SecurityScanner
  config:
    model: claude-sonnet-4-20250514
    scan_depth: standard          # shallow | standard | deep
    check_dependencies: true      # scan package.json / requirements.txt / Cargo.toml etc.
    check_secrets: true           # scan for hardcoded secrets, API keys, tokens
    check_patterns: true          # scan for insecure coding patterns (SQL injection, XSS, etc.)
    severity_threshold: medium    # low | medium | high | critical (only report at or above)
    ignore_paths:                 # paths to exclude from scanning
      - node_modules/
      - vendor/
      - "*.test.*"
    cve_database: latest          # use latest CVE database
    max_files: 500                # limit to avoid excessive cost on huge repos
    output_format: structured     # structured | markdown | sarif

Output:

{
  "vulnerabilities": [
    {
      "severity": "high",
      "type": "sql_injection",
      "file": "src/db/queries.ts",
      "line": 47,
      "description": "User input directly interpolated into SQL query",
      "recommendation": "Use parameterized queries",
      "cwe": "CWE-89"
    }
  ],
  "dependency_issues": [
    {
      "package": "lodash",
      "version": "4.17.15",
      "cve": "CVE-2021-23337",
      "severity": "high",
      "fix_version": "4.17.21"
    }
  ],
  "secrets_found": 0,
  "summary": {
    "total_issues": 3,
    "critical": 0,
    "high": 2,
    "medium": 1,
    "low": 0
  }
}

2. CodeReviewer

Category: analysis Purpose: Performs comprehensive code review, checking for code quality, design patterns, potential bugs, naming conventions, complexity, and adherence to best practices.

When to use:

• On every PR before merging
• When reviewing unfamiliar code
• After large refactors to validate quality
• As part of periodic codebase quality audits

Default configuration:

- id: code_review
  type: CodeReviewer
  config:
    model: claude-sonnet-4-20250514
    review_scope: changed_files   # changed_files | full | directory
    target_path: null             # specific directory to review (when scope is directory)
    check_patterns:               # what to check for
      - error-handling
      - naming-conventions
      - complexity
      - dry-violations
      - dead-code
      - type-safety
      - edge-cases
      - documentation
    max_issues: 50                # cap issues to avoid overwhelming output
    severity_levels: true         # categorize issues by severity
    suggest_fixes: true           # include fix suggestions for each issue
    ignore_patterns:              # file patterns to skip
      - "*.generated.*"
      - "*.min.*"
    complexity_threshold: 15      # cyclomatic complexity warning threshold
    line_length_limit: 120        # flag lines exceeding this length

Output:

{
  "issues": [
    {
      "severity": "warning",
      "category": "complexity",
      "file": "src/utils/parser.ts",
      "line": 23,
      "description": "Function parseInput has cyclomatic complexity of 18 (threshold: 15)",
      "suggestion": "Extract nested conditionals into helper functions"
    }
  ],
  "summary": {
    "files_reviewed": 12,
    "total_issues": 7,
    "errors": 1,
    "warnings": 4,
    "info": 2
  },
  "overall_quality": "good"
}

3. BugHunter

Category: analysis Purpose: Actively searches for bugs, logic errors, race conditions, off-by-one errors, null pointer issues, and other defects that could cause runtime failures.

When to use:

• When investigating reported bugs to find root cause and related issues
• As part of pre-release quality gates
• On complex business logic code
• After major refactors to catch regressions

Default configuration:

- id: bug_hunt
  type: BugHunter
  config:
    model: claude-sonnet-4-20250514
    hunt_scope: changed_files     # changed_files | full | directory
    target_path: null
    bug_categories:               # what types of bugs to hunt
      - null-safety
      - off-by-one
      - race-conditions
      - resource-leaks
      - type-coercion
      - boundary-conditions
      - error-propagation
      - state-mutations
    include_edge_cases: true      # look for edge case inputs that could trigger bugs
    trace_data_flow: true         # follow data through call chains
    max_depth: 5                  # call chain depth for data flow analysis
    report_confidence: true       # include confidence level per finding

Output:

{
  "bugs": [
    {
      "confidence": "high",
      "category": "null-safety",
      "file": "src/services/user.ts",
      "line": 89,
      "description": "user.profile accessed without null check; getUser() returns null when user is deleted",
      "reproduction": "Call getUserProfile() with a deleted user ID",
      "suggested_fix": "Add null check: if (!user?.profile) return null;"
    }
  ],
  "edge_cases": [
    {
      "file": "src/utils/math.ts",
      "line": 12,
      "description": "divide() does not handle divisor of 0",
      "input": "divide(10, 0)",
      "expected": "Error or Infinity",
      "actual": "NaN propagates silently"
    }
  ],
  "summary": {
    "bugs_found": 4,
    "high_confidence": 2,
    "medium_confidence": 1,
    "low_confidence": 1,
    "edge_cases": 3
  }
}

4. PerformanceProfiler

Category: analysis Purpose: Identifies performance bottlenecks, inefficient algorithms, excessive memory allocation, N+1 queries, unnecessary re-renders, and optimization opportunities.

When to use:

• When users report slow performance
• Before and after performance optimization work
• As part of pre-release performance validation
• On database query code and API endpoints

Default configuration:

- id: perf_profile
  type: PerformanceProfiler
  config:
    model: claude-sonnet-4-20250514
    profile_scope: changed_files  # changed_files | full | directory | hot_paths
    target_path: null
    check_categories:
      - algorithm-complexity       # O(n^2) loops, inefficient sorting, etc.
      - memory-allocation         # excessive object creation, memory leaks
      - database-queries          # N+1, missing indexes, full table scans
      - network-calls             # sequential requests that could be parallel
      - caching-opportunities     # repeated expensive computations
      - bundle-size               # large imports, tree-shaking issues
      - render-performance        # unnecessary re-renders (React/Vue)
    include_benchmarks: false     # if true, suggest benchmark code
    complexity_analysis: true     # analyze Big-O complexity of functions

Output:

{
  "bottlenecks": [
    {
      "severity": "high",
      "category": "algorithm-complexity",
      "file": "src/search/filter.ts",
      "line": 34,
      "description": "Nested loop creates O(n*m) complexity; items and filters are both unbounded",
      "current_complexity": "O(n*m)",
      "suggested_complexity": "O(n+m)",
      "suggestion": "Build a Set from filters for O(1) lookup, reducing overall to O(n+m)"
    },
    {
      "severity": "medium",
      "category": "database-queries",
      "file": "src/api/orders.ts",
      "line": 67,
      "description": "N+1 query: fetching user details inside a loop over orders",
      "suggestion": "Use a JOIN or batch fetch users with an IN clause"
    }
  ],
  "summary": {
    "bottlenecks_found": 5,
    "high_severity": 1,
    "medium_severity": 3,
    "low_severity": 1,
    "estimated_impact": "2-5x improvement possible in hot paths"
  }
}

5. ArchitectAnalyzer

Category: analysis Purpose: Analyzes the overall architecture of a codebase, mapping module structure, dependency graphs, design patterns in use, and providing structural understanding for downstream nodes.

When to use:

• As the first node in pipelines that need codebase context
• Before major refactors to understand current structure
• For onboarding documentation generation
• To detect architectural anti-patterns (circular dependencies, god modules)

Default configuration:

- id: architect
  type: ArchitectAnalyzer
  config:
    model: claude-sonnet-4-20250514
    target_path: ./                # root of analysis
    analyze_dependencies: true     # map module dependency graph
    detect_patterns: true          # identify design patterns in use
    detect_antipatterns: true      # flag architectural smells
    map_entry_points: true         # identify application entry points
    language_detection: auto       # auto-detect languages
    max_depth: 10                  # directory depth for analysis
    include_metrics: true          # LOC, file count, complexity per module
    output_format: structured      # structured | markdown
    ignore_paths:
      - node_modules/
      - vendor/
      - dist/
      - build/
      - .git/

Output:

{
  "architecture": {
    "type": "monolith",
    "languages": ["TypeScript", "JavaScript"],
    "framework": "Express.js",
    "entry_points": ["src/index.ts", "src/worker.ts"],
    "modules": [
      {
        "path": "src/api/",
        "purpose": "REST API route handlers",
        "files": 15,
        "loc": 2340,
        "dependencies": ["src/services/", "src/models/"]
      },
      {
        "path": "src/services/",
        "purpose": "Business logic layer",
        "files": 8,
        "loc": 1560,
        "dependencies": ["src/models/", "src/utils/"]
      }
    ],
    "patterns_detected": ["repository-pattern", "middleware-chain", "dependency-injection"],
    "antipatterns": [
      {
        "type": "circular-dependency",
        "between": ["src/services/auth.ts", "src/services/user.ts"],
        "suggestion": "Extract shared logic into src/services/identity.ts"
      }
    ]
  },
  "metrics": {
    "total_files": 87,
    "total_loc": 12450,
    "avg_complexity": 8.3,
    "test_coverage_estimate": "65%"
  }
}

6. AutoFixer

Category: modification Purpose: Automatically applies fixes for issues identified by analysis nodes (SecurityScanner, CodeReviewer, BugHunter). Creates clean, minimal diffs.

When to use:

• After CodeReviewer or BugHunter identifies fixable issues
• To auto-remediate security vulnerabilities
• For bulk style and pattern fixes
• After linting to fix remaining issues

Default configuration:

- id: auto_fix
  type: AutoFixer
  config:
    model: claude-sonnet-4-20250514
    fix_categories:               # which issue categories to fix
      - style
      - bugs
      - performance
      - security
    require_confirmation: false   # if true, show fixes before applying
    create_backup: true           # backup original files before modifying
    max_files: 50                 # limit files modified per run
    fix_mode: minimal             # minimal | comprehensive
    preserve_formatting: true     # maintain existing code style
    validate_fixes: true          # verify fix doesn't break syntax
    commit_message_prefix: "fix:" # prefix for commit messages

7. LintFixer

Category: modification Purpose: Runs project linters (ESLint, Prettier, Ruff, Clippy, etc.) and auto-fixes all fixable issues. Lightweight and fast.

When to use:

• Before TestRunner to ensure clean code
• After code generation or migration steps
• As a quick cleanup pass

Default configuration:

- id: lint_fix
  type: LintFixer
  config:
    model: claude-haiku-4-20250414
    fix_mode: auto                # auto | report-only
    config_file: auto             # auto-detect .eslintrc, .prettierrc, etc.
    typescript_rules: true        # enable TypeScript-specific rules
    format_on_save: true          # run formatter after fixing
    ignore_paths:
      - node_modules/
      - dist/
      - "*.min.*"

8. RefactorAgent

Category: modification Purpose: Performs structural refactoring operations -- extracting functions/classes, renaming across codebase, reorganizing modules -- while preserving all existing behavior.

When to use:

• When code complexity exceeds thresholds
• To break apart god classes/modules
• To improve naming consistency
• When preparing codebase for new features

Default configuration:

- id: refactor
  type: RefactorAgent
  config:
    model: claude-sonnet-4-20250514
    refactor_scope: targeted      # targeted | module | full
    target_path: null             # specific file or directory
    operations:                   # which refactoring operations to consider
      - extract-function
      - extract-class
      - rename-symbol
      - move-module
      - inline-function
      - simplify-conditional
    preserve_public_api: true     # do not change exported interfaces
    max_changes_per_file: 10      # limit changes to keep diffs reviewable
    include_tests: true           # update test imports/references
    dry_run: false

9. TypeMigrator

Category: modification Purpose: Converts JavaScript files to TypeScript, adding type annotations, interfaces, and type guards. Handles JSDoc to TypeScript type conversion.

When to use:

• When migrating a JavaScript project to TypeScript
• When adding types to specific modules
• After scaffolding new code that needs type definitions

Default configuration:

- id: type_migrate
  type: TypeMigrator
  config:
    model: claude-sonnet-4-20250514
    source_dir: src/              # directory to migrate
    strict_mode: false            # if true, no implicit any
    add_types: inferred           # inferred | explicit | minimal
    preserve_jsdoc: true          # keep JSDoc comments alongside types
    generate_interfaces: true     # extract interfaces for object shapes
    handle_imports: true          # update import paths (.js -> .ts)
    tsconfig_update: true         # update tsconfig.json include/exclude
    file_extension: .ts           # .ts | .tsx (for React components)
    batch_size: 20                # files per batch to manage cost
    skip_patterns:
      - "*.test.js"
      - "*.spec.js"
      - "*.config.js"

10. DependencyUpdater

Category: modification Purpose: Updates project dependencies to latest compatible versions, resolves conflicts, applies required migration steps, and validates the update.

When to use:

• Scheduled weekly or monthly dependency maintenance
• When security vulnerabilities are found in dependencies
• Before major version upgrades
• As part of CI/CD dependency health checks

Default configuration:

- id: dep_update
  type: DependencyUpdater
  config:
    model: claude-sonnet-4-20250514
    update_scope: all             # all | security-only | major | minor | patch
    package_manager: auto         # auto | npm | yarn | pnpm | pip | cargo
    include_dev: true             # update devDependencies too
    respect_ranges: true          # stay within semver ranges in package.json
    check_breaking: true          # review changelogs for breaking changes
    auto_migrate: true            # apply migration scripts when available
    lockfile_update: true         # regenerate lockfile after updates
    max_updates: 20               # limit updates per run

11. TestGenerator

Category: testing Purpose: Generates unit tests for functions, classes, and modules that lack test coverage. Analyzes code to understand expected behavior and edge cases.

When to use:

• To increase test coverage on under-tested code
• After writing new features that need test coverage
• Before refactoring to establish a safety net
• As part of coverage boost campaigns

Default configuration:

- id: test_gen
  type: TestGenerator
  config:
    model: claude-sonnet-4-20250514
    test_scope: uncovered         # uncovered | changed_files | directory | all
    target_path: null
    test_framework: auto          # auto | jest | mocha | pytest | vitest | go-test
    test_style: arrange-act-assert
    coverage_target: 80           # target coverage percentage
    include_edge_cases: true      # generate tests for boundary conditions
    include_error_cases: true     # generate tests for error paths
    mock_strategy: minimal        # minimal | comprehensive | none
    output_directory: auto        # auto = alongside source or in tests/ dir
    naming_convention: auto       # auto-detect from existing tests
    max_tests_per_file: 15

12. E2ETestWriter

Category: testing Purpose: Generates end-to-end tests that simulate real user workflows through the application interface using Playwright, Cypress, or similar frameworks.

When to use:

• For critical user flows (login, checkout, onboarding)
• When unit tests alone are insufficient
• Before major releases to validate user journeys
• When adding new user-facing features

Default configuration:

- id: e2e_test
  type: E2ETestWriter
  config:
    model: claude-sonnet-4-20250514
    framework: auto               # auto | playwright | cypress | selenium
    target_flows:                 # user flows to test
      - login
      - registration
      - checkout
      - navigation
    base_url: http://localhost:3000
    include_visual: false         # screenshot comparisons
    include_accessibility: true   # a11y checks within E2E tests
    browser: chromium             # chromium | firefox | webkit
    timeout_per_test: 30000       # ms per test
    retry_flaky: 2                # retry count for flaky tests
    output_directory: tests/e2e/

13. TestRunner

Category: testing Purpose: Executes test suites, captures output, reports pass/fail status, coverage metrics, and performance of the test run itself.

When to use:

• After any code modification to validate correctness
• After AutoFixer or RefactorAgent to confirm no regressions
• As the final gate before PRCreator
• In CI/CD validation pipelines

Default configuration:

- id: test_run
  type: TestRunner
  config:
    model: claude-haiku-4-20250414      # lightweight model sufficient
    test_command: auto              # auto-detect: npm test, pytest, cargo test, etc.
    coverage_enabled: true
    coverage_threshold: 80          # fail if coverage below this
    coverage_report: lcov           # lcov | text | html | json
    timeout_seconds: 300            # overall test timeout
    fail_fast: false                # stop on first failure
    parallel: true                  # run tests in parallel if framework supports
    retry_flaky: 1                  # retry failed tests once
    env_vars: {}                    # additional environment variables
    output_verbose: false           # full test output vs summary only

14. DocWriter

Category: documentation Purpose: Generates or updates project documentation including README files, API docs, architecture guides, and usage examples.

When to use:

• After major code changes to keep docs current
• When creating a new project or module
• As part of documentation refresh campaigns
• Before public releases

Default configuration:

- id: doc_write
  type: DocWriter
  config:
    model: claude-sonnet-4-20250514
    doc_types:                     # which docs to generate/update
      - readme
      - api
      - architecture
      - setup-guide
    target_path: ./
    output_format: markdown
    include_examples: true         # include code examples
    include_diagrams: false        # include mermaid diagrams
    update_mode: merge             # merge (update existing) | overwrite | create-only
    toc_generation: true           # add table of contents
    link_validation: true          # verify internal links

15. ChangelogWriter

Category: documentation Purpose: Generates changelog entries from git history, PR descriptions, and code analysis. Follows Keep a Changelog format.

When to use:

• Before releases to document changes
• As part of PR pipelines to update CHANGELOG.md
• For automated release notes

Default configuration:

- id: changelog
  type: ChangelogWriter
  config:
    model: claude-haiku-4-20250414
    format: keep-a-changelog       # keep-a-changelog | conventional | custom
    source: git-log                # git-log | pr-descriptions | both
    since: last-tag                # last-tag | last-release | <date> | <commit>
    categories:                    # changelog sections
      - Added
      - Changed
      - Deprecated
      - Removed
      - Fixed
      - Security
    include_authors: true
    include_pr_links: true
    output_file: CHANGELOG.md
    prepend: true                  # add to top of existing file

16. CodeExplainer

Category: documentation Purpose: Produces human-readable explanations of code, architecture decisions, and data flows. Designed for onboarding new developers.

When to use:

• When creating onboarding documentation
• To explain complex algorithms or business logic
• For knowledge transfer before team changes
• To document legacy code

Default configuration:

- id: explainer
  type: CodeExplainer
  config:
    model: claude-sonnet-4-20250514
    explain_scope: full            # full | module | file | function
    target_path: ./
    audience: junior               # junior | mid | senior | non-technical
    include_diagrams: true         # mermaid flow diagrams
    include_examples: true         # usage examples
    explain_why: true              # explain design decisions, not just what
    link_to_source: true           # reference file:line in explanations
    output_format: markdown
    max_depth: 3                   # how deep into call chains to explain

17. APIDesigner

Category: design Purpose: Designs REST or GraphQL API schemas from requirements, including endpoint definitions, request/response schemas, authentication flows, and error handling patterns.

When to use:

• When designing new API endpoints
• When converting internal functions to API surfaces
• For API review and consistency checking
• When migrating between API styles (REST to GraphQL)

Default configuration:

- id: api_design
  type: APIDesigner
  config:
    model: claude-sonnet-4-20250514
    api_style: rest                # rest | graphql | grpc
    spec_format: openapi-3.1      # openapi-3.1 | openapi-3.0 | graphql-schema
    include_auth: true             # design authentication endpoints
    include_pagination: true       # add pagination to list endpoints
    include_errors: true           # define error response schemas
    include_examples: true         # request/response examples
    naming_convention: kebab-case  # kebab-case | camelCase | snake_case
    versioning: url-prefix         # url-prefix | header | query-param
    output_file: api-spec.yaml

18. PRCreator

Category: integration Purpose: Creates or updates pull requests with structured summaries, labels, reviewer assignments, and links to related issues.

When to use:

• As the final node in PR-focused pipelines
• After AutoFixer or RefactorAgent to submit changes
• For automated dependency update PRs

Default configuration:

- id: pr_create
  type: PRCreator
  config:
    model: claude-haiku-4-20250414
    action: create                 # create | update | draft
    title_format: conventional     # conventional | descriptive | custom
    include_summary: true          # generate PR description from changes
    include_checklist: true        # add review checklist
    include_test_results: true     # embed test results in PR body
    labels:                        # labels to apply
      - cortivex-generated
    reviewers: []                  # GitHub usernames to request review
    draft: false                   # create as draft PR
    base_branch: main              # target branch
    link_issues: true              # auto-link related issues from commit messages

19. Orchestrator

Category: control Purpose: Meta-node that coordinates sub-pipelines, conditional branching, and dynamic node generation. Used for complex workflows that need runtime decisions.

When to use:

• When pipeline behavior depends on runtime conditions
• To fan-out work across multiple sub-pipelines
• For A/B testing different pipeline strategies
• When dynamic node generation is needed

Default configuration:

- id: orchestrate
  type: Orchestrator
  config:
    model: claude-sonnet-4-20250514
    strategy: conditional          # conditional | fan-out | priority-queue
    conditions:                    # runtime conditions for branching
      - if: "security_scan.critical_count > 0"
        then: "halt_pipeline"
        else: "continue"
    max_sub_pipelines: 5           # limit concurrent sub-pipelines
    timeout_minutes: 15            # overall orchestration timeout
    collect_results: true          # aggregate results from sub-pipelines

20. CustomAgent

Category: custom Purpose: Fully customizable agent node with user-defined system prompt, tools, and behavior. Use when no built-in node type fits your needs.

When to use:

• For domain-specific tasks not covered by built-in nodes
• For experimental workflows
• To integrate external tools or APIs
• For one-off specialized agents

Default configuration:

- id: custom_agent
  type: CustomAgent
  config:
    model: claude-sonnet-4-20250514
    system_prompt: |
      You are a specialized agent that...
      [Your custom instructions here]
    tools:                         # MCP tools to make available
      - file_read
      - file_write
      - bash
    temperature: 0.5
    max_tokens: 4096
    timeout_seconds: 300
    input_schema:                  # expected input format
      type: object
      properties:
        task: { type: string }
    output_schema:                 # expected output format
      type: object
      properties:
        result: { type: string }
        status: { type: string, enum: [success, failure] }

Creating Custom Node Types

To create a reusable custom node type, define it in a YAML file:

# custom-nodes/MarkdownLinter.yaml
node_type:
  name: MarkdownLinter
  category: documentation
  description: Lints markdown files for style, broken links, and formatting issues
  default_model: claude-haiku-4-20250414

  system_prompt: |
    You are a markdown documentation linter. Analyze markdown files for:
    - Broken internal links
    - Inconsistent heading levels
    - Missing alt text on images
    - Spelling and grammar issues
    - Formatting inconsistencies

    Report issues in structured JSON format.

  default_config:
    check_links: true
    check_spelling: true
    check_formatting: true
    style_guide: google           # google | microsoft | custom
    ignore_patterns:
      - CHANGELOG.md
      - node_modules/

  input_schema:
    type: object
    properties:
      target_path:
        type: string
        description: Directory containing markdown files

  output_schema:
    type: object
    properties:
      issues:
        type: array
        items:
          type: object
          properties:
            file: { type: string }
            line: { type: number }
            severity: { type: string }
            message: { type: string }
      summary:
        type: object
        properties:
          files_checked: { type: number }
          total_issues: { type: number }

Register custom node types with:

cortivex_nodes({
  action: "register",
  definition_file: "custom-nodes/MarkdownLinter.yaml"
})

Then use it in pipelines like any built-in node:

nodes:
  - id: lint_docs
    type: MarkdownLinter
    config:
      target_path: docs/
      check_links: true

Node Selection Guide

Use this decision tree to select the right node type:

Need to analyze code without changing it?

• Security concerns -> SecurityScanner
• Code quality/patterns -> CodeReviewer
• Finding bugs -> BugHunter
• Performance issues -> PerformanceProfiler
• Understanding structure -> ArchitectAnalyzer

Need to modify code?

• Fix identified issues -> AutoFixer
• Fix lint/style issues -> LintFixer
• Structural changes -> RefactorAgent
• Add TypeScript types -> TypeMigrator
• Update dependencies -> DependencyUpdater

Need to test code?

• Generate unit tests -> TestGenerator
• Generate E2E tests -> E2ETestWriter
• Run existing tests -> TestRunner

Need documentation?

• READMEs, API docs, guides -> DocWriter
• Release notes/changelogs -> ChangelogWriter
• Code explanations for humans -> CodeExplainer

Need to design?

• API schemas and endpoints -> APIDesigner

Need integration?

• Create/update PRs -> PRCreator

Need control flow?

• Conditional branching, sub-pipelines -> Orchestrator

None of the above?

• Build your own -> CustomAgent

Reasoning Protocol

Before selecting a node type, reason through explicitly:

1. What is the primary action? Categorize as: analyze, modify, test, document, design, integrate, or control. This narrows the candidates immediately.
2. Does the task require code changes? If no, use an analysis node. If yes, use a modification node followed by a validation node.
3. What model tier is appropriate? Tasks requiring deep reasoning (CodeReviewer, BugHunter, RefactorAgent) need Sonnet. Mechanical tasks (LintFixer, TestRunner, PRCreator) work well with Haiku at a fraction of the cost.
4. Is there a built-in node that fits? Check the 20 node types above before resorting to CustomAgent. CustomAgent should be the exception, not the default.
5. What output does the downstream node need? Select nodes that produce the output format expected by the next node in the pipeline.

Think step-by-step through the decision tree above. State your reasoning before selecting a node type.

Anti-Patterns

output_format: structured

WRONG:

# Wrong node for the job
- id: find_bugs
  type: CodeReviewer      # CodeReviewer checks patterns, not bugs
  config:
    model: claude-sonnet-4-20250514
    check_patterns: [bugs]  # This is a style check, not bug hunting

RIGHT:

# Correct node for bug finding
- id: find_bugs
  type: BugHunter
  config:
    model: claude-sonnet-4-20250514
    bug_categories: [null-safety, race-conditions, boundary-conditions]
    trace_data_flow: true

Grounding Rules

• Cannot decide between two node types: Ask yourself what the primary output should be. If it is a list of issues to review, use an analysis node. If it is modified source code, use a modification node.
• Node produces poor quality output: Before switching to a more expensive model, check if the configuration is correct. A misconfigured Sonnet node will underperform a well-configured Haiku node.
• Need a capability not covered by built-in nodes: Create a CustomAgent with a clear, specific system prompt. Do not write vague instructions like "analyze the code" -- specify exactly what to look for and what format to produce.
• Unsure about cost estimates: The cost column in the summary table reflects median runs on medium-sized repositories (50-200 files). Scale estimates linearly with file count for larger repos.

Advanced Capabilities

Custom Node Creation

Register new node types at runtime via the

cortivex_node_register

{
  "method": "cortivex_node_register",
  "params": {
    "name": "ComplianceAuditor",
    "category": "analysis",
    "description": "Audits code for regulatory compliance (SOC2, HIPAA, GDPR)",
    "default_model": "claude-sonnet-4-20250514",
    "system_prompt": "Analyze source code for regulatory framework violations.",
    "default_config": { "framework": "SOC2", "severity_threshold": "medium" },
    "input_schema": {
      "type": "object",
      "properties": {
        "target_path": { "type": "string" },
        "framework": { "type": "string", "enum": ["SOC2", "HIPAA", "GDPR"] }
      }
    }
  }
}

Registration response:

{ "result": { "node_type": "ComplianceAuditor", "registered": true, "id": "custom_node_a7f3" } }

Node Performance Profiling

Every node execution emits telemetry conforming to this schema for capacity planning and cost attribution.

{
  "title": "NodePerformanceMetrics",
  "type": "object",
  "properties": {
    "node_id": { "type": "string" },
    "node_type": { "type": "string" },
    "pipeline_run_id": { "type": "string" },
    "timing": {
      "type": "object",
      "properties": { "queue_wait_ms": { "type": "number" }, "execution_ms": { "type": "number" }, "total_ms": { "type": "number" } }
    },
    "tokens": { "input_tokens": { "type": "integer" }, "output_tokens": { "type": "integer" } },
    "cost_usd": { "type": "number" },
    "outcome": { "type": "string", "enum": ["success", "partial", "failure", "timeout"] }
  }
}

Auto-Scaling Node Configurations

Configure auto-scaling rules that adjust concurrency, model tier, and batch sizes based on queue depth and latency.

auto_scaling:
  enabled: true
  rules:
    - node_type: CodeReviewer
      min_instances: 1
      max_instances: 8
      scale_up: { metric: queue_depth, threshold: 10, cooldown_seconds: 60 }
      scale_down: { metric: idle_time_seconds, threshold: 120 }
      model_fallback:
        primary: claude-sonnet-4-20250514
        fallback: claude-haiku-4-20250414
        fallback_trigger: queue_depth > 25
    - node_type: TestRunner
      min_instances: 2
      max_instances: 12
      scale_up: { metric: pending_jobs, threshold: 5 }
      batch_config: { max_batch_size: 10, batch_timeout_seconds: 15 }
  global_limits:
    max_total_instances: 30
    max_cost_per_hour_usd: 50.00
    circuit_breaker: { error_rate_threshold: 0.25, evaluation_window_seconds: 300 }

Node Chaining Patterns

The

cortivex_node_chain

depends_on

input_map

{
  "method": "cortivex_node_chain",
  "params": {
    "chain_id": "security-fix-verify",
    "nodes": [
      { "id": "scan", "type": "SecurityScanner", "config": { "scan_depth": "deep" } },
      {
        "id": "fix", "type": "AutoFixer", "depends_on": "scan",
        "input_map": { "issues": "$.scan.vulnerabilities" },
        "config": { "fix_categories": ["security"] }
      },
      { "id": "verify", "type": "TestRunner", "depends_on": "fix", "config": { "fail_fast": true } }
    ],
    "on_failure": "halt"
  }
}

Response with execution handle:

{ "result": { "chain_id": "security-fix-verify", "execution_id": "exec_8b2c4d1f", "status": "running", "current_node": "scan", "progress": { "completed": 0, "total": 3 }, "estimated_completion_seconds": 105 } }

Cost-Optimized Model Selection

Evaluate model options per node against latency and quality constraints. The cost analysis API recommends assignments that minimize spend while meeting SLA targets.

{
  "title": "CostAnalysisRequest",
  "type": "object",
  "properties": {
    "pipeline_id": { "type": "string" },
    "optimization_target": { "type": "string", "enum": ["minimize_cost", "minimize_latency", "balance"] },
    "constraints": {
      "max_cost_per_run_usd": { "type": "number" },
      "max_latency_seconds": { "type": "number" },
      "min_quality_score": { "type": "number", "minimum": 0, "maximum": 1 }
    },
    "node_overrides": [{ "node_id": { "type": "string" }, "locked_model": { "type": "string" } }]
  },
  "required": ["pipeline_id", "optimization_target"]
}

The response provides per-node recommendations with projected savings:

interface CostAnalysisResult {
  pipeline_id: string;
  recommendations: Array<{
    node_id: string;
    current_model: string;
    recommended_model: string;
    quality_delta: number;       // -1.0 to 1.0
    cost_reduction_pct: number;
    latency_delta_ms: number;
  }>;
  summary: { current_cost_per_run: number; optimized_cost_per_run: number; total_savings_pct: number; quality_impact: "none" | "minimal" | "moderate"; nodes_changed: number };
}

Security Hardening (OWASP AST10 Aligned)

AST03: Per-Node Permission Manifests

Every node declares a permission manifest (AST03 -- Excessive Permissions) enumerating allowed file paths, tools, and network access. The runtime denies anything not listed.

node_permissions:
  SecurityScanner:
    filesystem: { read: ["src/**", "lib/**", "package.json", "Cargo.toml"], write: [] }
    tools: { allowed: [file_read, grep, glob], denied: [file_write, bash, file_delete] }
    network: { allowed_hosts: ["cve.circl.lu", "osv.dev"], denied: ["*"] }
  AutoFixer:
    filesystem: { read: ["src/**", "lib/**", "tests/**"], write: ["src/**", "lib/**"] }
    tools: { allowed: [file_read, file_write, grep, glob], denied: [bash, file_delete] }
    network: { denied: ["*"] }
  TestRunner:
    filesystem: { read: ["**/*"], write: ["/tmp/**", "coverage/**"] }
    tools: { allowed: [file_read, bash], denied: [file_write, file_delete] }
    network: { allowed_hosts: ["localhost"], denied: ["*"] }

{ "method": "cortivex_permission_validate", "params": { "node_type": "AutoFixer", "requested_access": { "filesystem_write": ["src/utils/parser.ts"], "tools": ["file_write"] } } }

AST06: Shell Command Allowlists for TestRunner and CustomAgent

Only TestRunner and CustomAgent may invoke shell commands (AST06 -- Excessive Agency), both under strict allowlists.

shell_policy:
  enforcement: strict
  default_action: deny
  TestRunner:
    allowed_commands:
      - { pattern: "npm test*", timeout_seconds: 300 }
      - { pattern: "npx jest*", timeout_seconds: 300 }
      - { pattern: "pytest*", timeout_seconds: 300 }
      - { pattern: "cargo test*", timeout_seconds: 300 }
    blocked_patterns: ["rm *", "curl *", "wget *", "*| bash*", "sudo *"]
  CustomAgent:
    allowed_commands: []              # must be explicitly configured per-instance
    require_explicit_allowlist: true
    blocked_patterns: ["rm -rf *", "eval *", "exec *", "sudo *", "> /dev/*"]
  argument_sanitization: { strip_shell_metacharacters: true, block_path_traversal: true }

{ "method": "cortivex_shell_validate", "params": { "node_type": "TestRunner", "command": "npm test -- --coverage" } }

Secret Handling During SecurityScanner Execution

SecurityScanner detects secrets but must never persist them to disk or logs (in-memory only, zeroized on completion).

secret_handling:
  SecurityScanner:
    detection: { patterns: ["API[_-]?KEY", "SECRET[_-]?KEY", "PRIVATE[_-]?KEY", "ghp_[a-zA-Z0-9]{36}"] }
    output_policy: { redact_values: true, report_location_only: true, max_context_chars: 40 }
    storage: { persist_to_disk: false, persist_to_logs: false, memory_policy: zeroize_on_complete }

{ "method": "cortivex_secret_policy_check", "params": { "node_type": "SecurityScanner", "checks": ["no_disk_persistence", "output_redaction", "memory_zeroization"] } }

Custom Node Registration Validation

Custom node registration (AST03, AST06) validates definitions to reject unsafe system prompts and excessive tool requests.

const registrationPolicy = {
  system_prompt_checks: {
    block_patterns: ["ignore previous instructions", "act as root", "bypass security", "disable safety"],
    max_length: 10000,
    require_role_declaration: true,
  },
  tool_access_checks: {
    max_tools: 5,
    prohibited_tools: ["file_delete", "process_kill", "env_set", "network_raw"],
  },
  resource_checks: { max_timeout_seconds: 600, max_tokens: 16384, max_output_size_bytes: 1048576 },
};

{ "method": "cortivex_node_register", "params": { "name": "ComplianceAuditor", "system_prompt": "You are a compliance auditing agent.", "tools": ["file_read", "grep"], "validate_security": true } }

{ "registered": false, "validation_errors": [{ "check": "system_prompt_checks", "reason": "Blocked pattern detected", "ast_risk": "AST03" }, { "check": "tool_access_checks", "reason": "Tool 'file_delete' is prohibited", "ast_risk": "AST06" }] }

Model Tier Enforcement

Security-critical nodes require minimum model capability (AST06) to prevent false negatives from underpowered models.

model_tier_enforcement:
  tiers:
    tier_1_high:
      minimum_model: claude-sonnet-4-20250514
      applies_to: [SecurityScanner, BugHunter, RefactorAgent]
    tier_2_standard:
      minimum_model: claude-sonnet-4-20250514
      applies_to: [CodeReviewer, ArchitectAnalyzer, AutoFixer, TestGenerator]
    tier_3_lightweight:
      minimum_model: claude-haiku-4-20250414
      applies_to: [LintFixer, TestRunner, PRCreator, ChangelogWriter]
  overrides: { allow_downgrade: false, allow_upgrade: true, audit_downgrades: true }

{ "method": "cortivex_model_tier_check", "params": { "pipeline": "security-audit", "node_assignments": [{ "node_id": "security_scan", "type": "SecurityScanner", "model": "claude-haiku-4-20250414" }] } }

{ "valid": false, "violations": [{ "node_id": "security_scan", "assigned_model": "claude-haiku-4-20250414", "minimum_required": "claude-sonnet-4-20250514", "tier": "tier_1_high", "ast_risk": "AST06" }] }