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:
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:
The description field helps the AI agent understand when to choose each path. Be specific about what differentiates the options.

​
Transition Rules During Execution

When a phase defines next_options, the handoff to the next phase is explicit:
  1. Call EXIT_PHASE with next_phase set to one of the allowed options.
  2. Call ENTER_PHASE for that same phase using the returned exit_ticket.
Genesis enforces both manifest adjacency and the specific branch choice made at exit time:
  • For branching phases, the exit ticket only unlocks the chosen next_phase.
  • For phases without next_options, the exit ticket only unlocks the default next phase in manifest order.
  • You cannot reuse one ticket to enter a sibling branch or skip ahead to a non-adjacent phase. To move farther ahead, exit the intermediate phase or phases in order so Genesis can mint fresh tickets for each transition.
  • If ENTER_PHASE targets the wrong next phase, Genesis rejects the transition and keeps the pending ticket available so you can retry with the correct target.
Example
After EXIT_PHASE succeeds, Genesis treats the run as being between phases until ENTER_PHASE consumes the pending ticket. While a phase is active, Genesis also keeps the agent anchored to that phase’s scope and should ask before producing artifacts that belong to another phase or its phase-owned folders.
When an agent retries a failed EXIT_PHASE by calling ENTER_PHASE again for the same blueprint and phase, Genesis preserves the original entry turn count from the first time that phase was entered. Entering a different phase or blueprint still records a fresh baseline. This matters for phases that use a handoff_decision exit criterion (see below): the gate requires at least one separate user reply after phase entry, and preserving the original baseline lets retries succeed after the user has already replied.

​
Using Descriptive Phase Names

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

​
Merging Paths Back Together

Different branches can converge back to a common phase:
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:
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:

​
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:
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:
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

​
Handoff decision exit criteria

Phases that require an explicit user approval before delegating to another blueprint can declare a handoff_decision criterion in exit_criteria:
Genesis blocks EXIT_PHASE until completion_proof includes both boolean fields, the user has replied in a turn after the phase was entered (unless the standing-decline exception applies), and — when approved — a durable child handoff thread exists for target_blueprint. If EXIT_PHASE fails for other reasons, the agent may call ENTER_PHASE again for the same phase; Genesis preserves the original entry turn count so replies that already occurred still count toward the separate-reply requirement.

​
Exit criterion types

The phase runtime enforces exactly four typed exit criteria: When accepted_verdicts excludes a partial-seal grade, the refusal uses its human-readable seal label rather than the amber verified_with_indeterminate status. When a phase declares its own context_defaults.active_tool_groups (or the tools_in_context alias) and uses a required_document exit criterion, include git_and_file_tools in that phase’s list. The file tool in this group writes documents to the mission repository for the gate to check. Blueprint validation warns when a phase’s declared tool-group list omits this group. See Tool groups during blueprint missions for how phase and blueprint tool-group lists interact. Each phase’s exit_criteria must include at least one criterion with one of these enforced types. Any of the four types satisfies this requirement; a required_document is not specifically required. Prose-only criteria do not count because the phase runtime does not verify them. Goal mode binds one run-completion item rather than converting a phase’s exit criteria into the goal. It does not add a criterion-type requirement: each phase must still satisfy the typed exit-criterion requirements above so its exit gate can decide whether the phase is done. Use an exit criterion without type for prose guidance that the phase runtime does not verify. Unknown or unenforced typed criteria are rejected during blueprint authoring; do not use custom values such as validation_passed, tests_passed, or repo_exists. Put those checks in phase actions and record their results in a deliverable document instead. For an existing manifest that still contains an unenforced typed criterion, phase results identify it in unenforced_criteria so the caller can correct the manifest rather than treating the criterion as a completed gate.

​
Required check exit criteria

Use required_check when a phase must pass a specific Python check whose source and result are verified by Genesis rather than inferred from a file written by an agent:
script must be a repository-relative .py path that does not contain ... script_sha256 must be 64 lowercase hexadecimal characters and must match the script bytes in the mission repository. expected_exit_code defaults to 0 and must be an integer when provided. At mission start, Genesis snapshots every phase’s required checks, including a fresh phase-entry identity. The snapshot is retained for the mission so later changes to the manifest do not change the check being evaluated. In the active phase, the agent runs each named check with run_repo_script(check_name="validate_repository"); the tool executes the hash-verified script and records platform-owned provenance evidence. A result file or other hand-written artifact does not satisfy this criterion. The phase cannot exit until every required check has matching evidence with the expected exit code.

​
Shared libraries for required checks

A check script may import packages installed with Genesis. To share your own helper code between checks, declare it as a library at the top level of the manifest, pinned the same way as a check script:
A check script then uses import view_to_dbt. Libraries can import each other by their declared names.
  • name must be a valid Python identifier, unique in the list, and must not match a standard-library module, an installed package, genesis, genesis_sdk or genesis_bots.
  • path follows the same rules as script, and must also be under resources/. That is the blueprint folder Genesis copies into each new mission repository. Each library is one .py file; packages (folders) are not supported.
  • sha256 must be 64 lowercase hexadecimal characters and match the file’s bytes in the mission repository.
Genesis checks each library’s bytes when the mission starts and refuses to start the mission if a library is missing or does not match. The mission keeps the script and library pins it started with: entering any phase again, the entry phase included, keeps them even after the blueprint is edited. Starting or restarting the mission takes the pins from the current blueprint, and every check then runs again. Each time run_repo_script runs a check, Genesis reads and checks every library again and reviews it with the same safety checks as the script. If a library changed after mission start, the check is refused, and the refusal names the library. A pass recorded before the change still counts. The run’s evidence records each library’s name, path and SHA-256. The phase gate accepts only evidence whose library list matches the mission’s pins exactly. The check imports the verified library source; Genesis does not load it from the file a second time. Any other module in the mission repository that a check tries to import is still refused. Each library is reviewed in full on every run, so each one adds review time to every check. A check script and its libraries together are limited to 1 MB.
Libraries from another repository
A library can also come from another Git repository, as long as that repository is registered with Genesis as a managed source and the source is enabled. Being registered is what makes a repository eligible; Genesis does not check how or by whom it was registered. Use source in place of path:
  • Give exactly one of path or source.
  • commit must be the full 40-character commit SHA in lowercase. Branch and tag names are not accepted, because they can move.
  • The source path must be a .py file in that repository. It does not need to be under resources/.
When the mission starts, Genesis reads the file from the managed source’s local copy at that commit. If the commit is not there yet, Genesis fetches it from the repository with the source’s own credentials and keeps it available for the rest of the mission. The file must be an ordinary file of at most 256 KB: symbolic links and submodules are refused. Its bytes must match sha256. The mission does not start if the source is not registered, is disabled or has never been synced, or if the commit or file cannot be read. Each check run reads the file again from the local copy, so a check does not need the network once the mission has started. Genesis also verifies that the registered remote and the local copy’s origin still match the remote recorded at mission start; if the source is re-pointed, the check is refused and the mission must be restarted. The run’s evidence records the library’s managed source, commit and path in place of a repository path. If a check is unavailable, Genesis exposes a blocked required-check gate on a programmatic BlueprintRun. Re-enable the code_executor_tools group under the phase’s context_defaults, run the check, or have an authenticated human with the approve_agent_action permission record a waiver through the BlueprintRun waiver endpoint.

​
Human approval gates in continuous missions

A phase can require approval of its completion proof by setting require_human_approval: true in the phase manifest:
This gate applies even when the mission runs in continuous mode. When the mission has an external approval transport, Genesis sends the requester an interactive approval card in the originating Google Chat direct message. The request identifies the phase and the exact completion proof being approved. An approval continues the transition; a rejection stops the phase so the agent can revise the work and submit a new proof. In manual mode, or when no external approval transport is available, the agent must use EXIT_PHASE to present the work and wait for the user before entering the next phase. Goal mode, the default mode of most shipped blueprints, stops at this gate the same way: the agent presents the work and waits for the person in the thread, and the external approval card is sent only for continuous missions. A trusted blueprint-chain handoff or a bound presenter launch that pre-approved the gates proceeds without stopping in either mode.

​
Structured question options

For a phase question that should offer explicit choices, set expected_response_type=choice or expected_response_type=multiple and place the options after a whole-line <<QUESTION:OPTIONS>> marker:
Add recommended=N to the START parameters to name the recommended option by its position in the options list, counting from 1. In the example, recommended=2 marks Incremental refresh. The chat card badges the named option; omit the parameter when the options are a genuine toss-up. A non-numeric or out-of-range value makes the options block fall back to a text question. Choice questions require at least two unique options; multiple-response questions require at least one. Both types accept at most 25 options, and each option is limited to 100 characters. Genesis treats malformed option blocks as a text question instead of exposing unsupported choices. During a mission, the agent is instructed to resolve measurable questions itself when it can reach the reference or query that answers them, rather than asking the person to choose a source. When it does ask a question with options, it states its recommendation in the form Recommended: <option> — <why>. If there is no preference, it explains why the options are a genuine toss-up instead of inventing a recommendation, and omits the recommended parameter.

​
Glob patterns in exit criteria paths

When an exit_criteria entry uses type: "required_document", Genesis checks the mission repository for files matching each declared path before EXIT_PHASE succeeds.

​
Wildcard paths

Declare a deliverable with shell-style glob metacharacters — *, ?, and [...] — when the exact filename is not fixed but must match a pattern. For example, a phase that produces any report matching reports/REPORT_*.md passes validation when at least one file in the mission repo matches that pattern. Genesis treats these metacharacters as wildcards, not literal filename characters:
  • If the path has no <variable> placeholders, Genesis runs glob.glob against the mission repo instead of os.path.exists.
  • If the path mixes placeholders and wildcards (for example CONFIG_<env>_*.sql) and every placeholder is resolved from a phase checkpoint, Genesis substitutes each checkpoint value (escaping glob-special characters in user data so they match literally), then glob-matches the result.
  • If a placeholder is still unresolved, Genesis falls back to the template-variable glob behavior described in Template variables in file paths below (unresolved <name> becomes *).
At least one matching file must exist. An empty match set causes EXIT_PHASE to return success=False with the manifest path listed in missing_files.
If the agent writes reports/REPORT_final.md, EXIT_PHASE succeeds.
In a running mission’s work-log phase-details view, Open and Preview for exit_criteria and branch requires_documents paths also resolve bare filenames (no /, no *) against mission artifacts by matching the final path segment. See Injected documents and mission file preview for the full matching rules.

​
Report consistency guard

When EXIT_PHASE or PROCEED_TO_NEXT_PHASE includes a completion_proof that references report files, Genesis runs a report consistency guard before the phase transition succeeds. The guard checks naming conventions for ad-hoc report paths and reconciles numeric metrics when the proof includes aliased count keys (for example rows vs total_rows).

​
Declared report paths

Genesis collects document paths declared in the manifest:
  • The current phase’s exit_criteria entries with type: "required_document" and a path
  • Manifest-level blueprint.outputs entries with type: "document" and a path
When a report path in completion_proof matches a declared path — by full normalized path or by filename — Genesis skips naming heuristics for that report. This lets blueprints pin fixed filenames such as 10_validation/FINAL_REPORT.md without conflicting with the generic naming rules below. Metric consistency checks still apply to declared reports. Path matching is case-insensitive, strips leading ./, and accepts a basename match when the proof lists only the filename (for example FINAL_REPORT.md matches a declared path of 10_validation/FINAL_REPORT.md).

​
Naming rules for non-declared reports

For report paths in completion_proof that do not match a declared path:
  • The file must use a .md extension
  • The basename should include the word report
  • When advancing to another phase, the basename should include the current phase identifier (for example phase 7 requires 7 in the filename)
  • When completing the blueprint (next_phase is omitted or END), at least one report basename should contain final
Genesis reads report paths from these completion_proof keys: report, report_path, phase_report, final_report, report_paths, and reports. When the guard blocks a transition, the error response includes report_consistency_guard with naming_issues, metric_issues, and declared_matched. Fix the reported issues and retry EXIT_PHASE or PROCEED_TO_NEXT_PHASE.

​
Template Variables in File Paths

​
Dynamic File Names

Sometimes the exact file name isn’t known at blueprint design time — it depends on decisions made during execution. Template variables let you use placeholders in exit_criteria paths and requires_documents:
In this example, <dashboard_name> is a placeholder. If the agent saved {"dashboard_name": "Sales"} as a phase checkpoint in Phase 0, then Phase 1 will require CONFIG_Sales.md and VALIDATION_Sales.md.

​
How Variables Are Resolved

Template variables are resolved from phase checkpoints — key-value data that agents save when completing phases:
  1. The agent calls EXIT_PHASE with phase_checkpoint={"dashboard_name": "Sales"}
  2. This value is stored and carried forward to all subsequent phases
  3. When validating CONFIG_<dashboard_name>.md, the system resolves it to CONFIG_Sales.md
If a template variable has no checkpoint value, the system falls back to glob matching — unresolved <dashboard_name> becomes *, so CONFIG_<dashboard_name>.md behaves like CONFIG_*.md and matches any file with that prefix and suffix. Paths that already contain literal *, ?, or [...] wildcards (without relying on unresolved placeholders) use glob matching directly; see Glob patterns in exit criteria paths above. Explicit checkpoint values are preferred for precise validation.

​
Variable Syntax

  • Use angle brackets: <variable_name>
  • Variable names can contain letters, numbers, and underscores
  • Multiple variables can appear in one path: REPORT_<project>_<version>.md
  • Variables work in both exit_criteria.path and requires_documents
Design your blueprint so agents save checkpoint values early. A good pattern: Phase 0 gathers requirements and saves key names via phase_checkpoint, then later phases reference those names in exit_criteria paths.

​
Complete Example

Here’s a practical blueprint with branching and early completion:
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”

​
Goal mode transitions

In goal mode, a phase that passes its exit checks proceeds directly into the next phase when its navigation is sequential: it has no next_options, or it has exactly one option. A phase with multiple options still pauses for the person to choose a branch. The transition also pauses when the phase sets require_human_approval: true, unless a trusted blueprint-chain handoff has pre-approved the gate. Goal mode carries one goal across the blueprint run: its statement describes the person’s overall requested outcome, and its single item is blueprint_run_complete (the blueprint run is complete). Entering another phase keeps the goal, its budget, recorded progress, and any pending declaration; each new blueprint run gets its own goal. The phase’s own exit criteria remain separate and its exit gate still decides whether that phase can exit. When the terminal phase exits, Genesis marks the run-completion item met, including when the run ends at a branch to @END or an approval stop. The agent does not attest completion a second time. Only the progressing stance is nudged; see the thread goal tools for declaration behavior and goal mode limits for the two configurable nudge ceilings. If Genesis cannot bind a goal to an entered phase, it applies manual mode instead and tells the agent in the phase-entry response why goal mode was not applied. The agent should follow the manual-mode instructions and must not call declare_goal_turn_status for that phase, because there is no goal to declare against. For a sequential transition, the phase guidance tells the agent to continue with PROCEED_TO_NEXT_PHASE without asking the person to confirm. EXIT_PHASE is also accepted and routed to that transition unless a branch choice or approval gate requires the person to take over. At the final phase, the guidance marks the run ended and tells the agent to report what the blueprint produced and stop, rather than ask for confirmation or review.

​
Phase instructions

Phases may include an optional string instructions field in blueprint_manifest.yaml for reusable guidance. Keep the phase purpose in description and explicit, verifiable steps in required_actions; instructions do not replace actions or exit criteria. Genesis returns the field in phase-entry responses. When a Mission or BlueprintRun enters the phase before the first agent turn, it is included once in the structured kickoff entry contract; see Programmatic BlueprintRun for its size limit and readback behavior. If omitted, instructions are empty; empty and whitespace-only strings are accepted and preserved, while null and other types are invalid.

​
Phase checklists

For phases with required_actions, the phase-entry guidance names checklist item ids in the form phase_<phase_id>_<n> and tells the agent to update them with <<CHECK:UPDATE|id=...|status=in_progress>> and finish them with <<CHECK:DONE|id=...>>. When a phase exits, Genesis marks any remaining checklist items completed and saves that completed checklist as phase evidence. The validation field in a required_actions entry is completion guidance for the agent; the phase runtime does not evaluate it. To enforce a document existence check, add a required_document exit criterion for that path instead. Blueprint validation warns when validation contains a bare document-existence claim such as reports/summary.md exists and no matching required_document criterion enforces it. This warning is advisory and does not fail the blueprint.

​
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, track phase completion across branches, and inspect child blueprint handoff threads when a phase delegates work to another blueprint.