Skip to main content

​
Overview

Blueprints can have branching paths that let your AI agent choose different workflows based on the situation. You can also allow early completion when objectives are met before all phases are finished.
When to use branching: Your workflow has decision points where different approaches make sense. For example, a simple data migration might follow one path, while a complex migration with transformations follows another.

​
Understanding Branching

​
How It Works

Instead of following a single linear path (Phase 0 → Phase 1 → Phase 2), your blueprint can offer choices: 

Phase 0: Analysis

    ├─→ Phase 1: Simple Processing

    └─→ Advanced Path: Complex Processing
The AI agent analyzes your requirements and chooses the appropriate path automatically.

​
Setting Up Branches

In your blueprint YAML, use next_options to define multiple paths: 

phases:

  "0":

    name: "Phase 0: Analyze Requirements"

    description: "Review project scope and complexity"

    exit_criteria:

      - criterion: "Analysis complete"

        type: "required_document"

        path: "analysis.md"

    next_options:

      - id: "1"

        description: "Simple approach for straightforward projects"

      - id: "advanced_0"

        description: "Advanced approach for complex requirements"
The description field helps the AI agent understand when to choose each path. Be specific about what differentiates the options.

​
Using Descriptive Phase Names

You’re not limited to numbers. Use descriptive names like advanced_0, cleanup, or validation: 

phases:

  "advanced_0":

    name: "Deep Analysis Phase"

    description: "Detailed analysis for complex scenarios"

    # ... phase definition

​
Merging Paths Back Together

Different branches can converge back to a common phase: 

phases:

  "advanced_1":

    name: "Complete Advanced Processing"

    next_options:

      - id: "2"

        description: "Rejoin main workflow at Phase 2"
Visual Example: Blueprint Branching

​
Early Completion

​
When to Use

Sometimes your objectives are met before reaching the final phase. Early completion lets the blueprint finish successfully at any decision point. Common scenarios:
  • Analysis reveals the project is already complete
  • Quick path achieves all required outcomes
  • User decides remaining phases aren’t needed

​
Setting Up Early Completion

Add an END option to next_options: 

phases:

  "2":

    name: "Phase 2: Review Results"

    description: "Check if objectives are met"

    exit_criteria:

      - criterion: "Review complete"

        type: "required_document"

        path: "review.md"

    next_options:

      - id: "3"

        description: "Continue to optional refinement"

      - id: "END"

        description: "All objectives met - complete now"
Once a blueprint completes early, it cannot be resumed. Ensure all critical deliverables are ready before choosing the END option.

​
Ensuring Required Files Exist

​
Why This Matters

Before taking a specific path, you may need certain files to exist. For example, the advanced path might require a configuration file that the simple path doesn’t need.

​
Path-Specific Requirements

Use requires_documents to validate files before allowing a path: 

phases:

  "0":

    name: "Phase 0: Choose Approach"

    exit_criteria:

      - criterion: "Analysis complete"

        type: "required_document"

        path: "analysis.md"

    next_options:

      - id: "simple_path"

        description: "Simple approach"

        requires_documents:

          - "analysis.md"

      - id: "advanced_path"

        description: "Advanced approach"

        requires_documents:

          - "analysis.md"

          - "advanced_config.yaml"

          - "permissions.json"

​
What Happens If Files Are Missing

If the AI agent tries to choose a path but required files don’t exist, you’ll see a clear error message: 

❌ Cannot proceed with 'advanced_path': required files are missing

Missing files:

  • advanced_config.yaml

  • permissions.json

The AI agent will create these files before proceeding.
The agent will automatically create the missing files and retry.

​
Ensuring Complete Deliverables for Early Exit

When allowing early completion, ensure all deliverables are ready: 

phases:

  "2":

    name: "Phase 2: Deliverables Ready"

    exit_criteria:

      - criterion: "Core work complete"

        type: "required_document"

        path: "result.json"

    next_options:

      - id: "END"

        description: "All deliverables complete"

        requires_documents:

          - "result.json"

          - "summary.md"

          - "validation_report.md"
Understanding the difference:
  • exit_criteria: Files needed to complete the current phase (always required)
  • requires_documents on a path: Additional files needed to take that specific path

​
Complete Example

Here’s a practical blueprint with branching and early completion: 

blueprint:

  name: "data_migration"

  version: "1.0"

  description: "Data migration with simple and complex paths"

phases:

  "0":

    name: "Analyze Source Data"

    description: "Understand data structure and complexity"

    exit_criteria:

      - criterion: "Analysis complete"

        type: "required_document"

        path: "analysis.md"

    next_options:

      - id: "1"

        description: "Simple migration (direct copy)"

      - id: "transform_0"

        description: "Complex migration (with transformations)"

        requires_documents:

          - "analysis.md"

          - "transformation_rules.yaml"

  "1":

    name: "Simple Migration"

    description: "Direct data copy"

    exit_criteria:

      - criterion: "Migration complete"

        type: "required_document"

        path: "migration_result.md"

    # Automatically continues to Phase 2

  "2":

    name: "Validate Results"

    description: "Check migration success"

    exit_criteria:

      - criterion: "Validation complete"

        type: "required_document"

        path: "validation.md"

    next_options:

      - id: "3"

        description: "Continue to documentation"

      - id: "END"

        description: "Migration validated - complete"

        requires_documents:

          - "validation.md"

          - "sign_off.md"

  "3":

    name: "Create Documentation"

    description: "Document migration process"

    # Automatically completes (final phase)

  "transform_0":

    name: "Design Transformations"

    description: "Plan data transformations"

    exit_criteria:

      - criterion: "Transformation plan ready"

        type: "required_document"

        path: "transformation_plan.md"

    next_options:

      - id: "transform_1"

        description: "Execute transformations"

  "transform_1":

    name: "Execute Complex Migration"

    description: "Apply transformations and migrate"

    exit_criteria:

      - criterion: "Complex migration complete"

        type: "required_document"

        path: "transform_result.md"

    next_options:

      - id: "2"

        description: "Rejoin main path for validation"
Workflow Visualization:

​
Automatic Progression

​
When Branching Isn’t Needed

If a phase doesn’t have next_options, the blueprint automatically continues to the next sequential phase:

Numbered Phases

“0” → “1” → “2” → “3”

Named Sequences

“setup_0” → “setup_1” → “setup_2”

phases:

  "1":

    name: "Phase 1: Processing"

    exit_criteria:

      - criterion: "Processing complete"

        type: "required_document"

        path: "result.md"

    # No next_options - automatically continues to Phase 2

​
Frequently Asked Questions

The agent analyzes your project requirements, context, and the description field for each option. It evaluates which path best matches your needs and automatically selects it.
Yes, by providing clear requirements and context in your initial conversation. The agent will ask clarifying questions if the right path isn’t obvious.
The agent will automatically create the missing documents before proceeding. You’ll see what files are being created and why.
No, once a path is chosen, the mission follows that branch. However, branches can merge back together at later phases.
The agent will inform you when objectives are met and offer to complete early. You can also see END options in the blueprint definition.

​
Best Practices

Clear Path Descriptions

Write descriptive text explaining when each path should be chosen. Help the AI agent make the right decision.

Validate Early Exits

Always require key deliverables when allowing early completion to ensure work quality.

Keep Branches Meaningful

Create branches for genuinely different approaches, not minor variations.

Plan Merge Points

Design where branches rejoin to avoid duplicating later phases unnecessarily.

​
What You’ll See During Execution

When running a blueprint with branching:
  1. At Decision Points: The agent explains which path it’s choosing and why
  2. During Path Execution: Clear indication of which branch you’re on
  3. At Merge Points: Confirmation when branches rejoin the main workflow
  4. Early Completion Options: The agent will propose early completion when appropriate and explain why all objectives are met
Monitor the mission progress view in Genesis to see which path was taken and track phase completion across branches.