> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Blueprint Branching & Early Completion

> Create flexible workflows with conditional paths and early exits

## 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.

<Info>
  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.
</Info>

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

```yaml theme={null}

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"
```

<Tip>
  The description field helps the AI agent understand when to choose each path. Be specific about what differentiates the options.
</Tip>

### 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**

```python theme={null}
exit_result = EXIT_PHASE(
    blueprint_name="data_migration",
    phase="0",
    next_phase="advanced_0",
    completion_proof={
        "summary": "Analysis complete",
        "deliverables": ["analysis.md"],
    },
)

ENTER_PHASE(
    blueprint_name="data_migration",
    phase="advanced_0",
    exit_ticket_from_previous=exit_result["exit_ticket"],
)
```

<Note>
  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.
</Note>

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:

```yaml theme={null}

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:

```yaml theme={null}

phases:

  "advanced_1":

    name: "Complete Advanced Processing"

    next_options:

      - id: "2"

        description: "Rejoin main workflow at Phase 2"
```

Visual Example:

```mermaid theme={null}

graph TD

    A[Phase 0: Analysis] -->|Simple| B[Phase 1: Simple Processing]

    A -->|Complex| C[Advanced Processing]

    B --> D[Phase 2: Final Review]

    C --> D

    D --> E[Phase 3: Completion]
```

<img src="https://mintlify.s3.us-west-1.amazonaws.com/genesiscomputing/BlueprintBranching" alt="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:

```yaml theme={null}

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"
```

<Warning>
  Once a blueprint completes early, it cannot be resumed. Ensure all critical deliverables are ready before choosing the END option.
</Warning>

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

```yaml theme={null}

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:

```yaml theme={null}

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"
```

<Note>
  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
</Note>

## 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`:

```yaml theme={null}
- criterion: "Runner handoff decision resolved"
  type: "handoff_decision"
  decision_field: "user_approved_handoff"
  triggered_field: "runner_handoff_triggered"
  target_blueprint: "databricks_migration_runner"
  allow_standing_decline_when_input_missing: "target_connection"
```

| Field | Purpose |
| - | - |
| `decision_field` | Boolean key in `completion_proof` for approval (`true`) or decline (`false`). Default: `user_approved_handoff`. |
| `triggered_field` | Boolean key in `completion_proof` recording whether the handoff was triggered. |
| `target_blueprint` | Expected child blueprint name (used in error messages). Falls back to the phase's first `handoff_actions` target when omitted. |
| `allow_standing_decline_when_input_missing` | Optional blueprint input name. When set, an explicit decline is accepted without a separate user reply if that input is absent (standing plan-only decline). |

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:

| Type | Behavior | Required fields |
| - | - | - |
| `required_check` | Runs a server-pinned Python check from the mission repository and requires matching platform-owned evidence before `EXIT_PHASE` succeeds. | `name`, `script`, `script_sha256`; optional `expected_exit_code` |
| `required_document` | Checks that a matching file exists in the mission repository before `EXIT_PHASE` succeeds. | `path` |
| `handoff_decision` | Requires a recorded user decision and matching durable handoff state before the phase can exit. | See [Handoff decision exit criteria](#handoff-decision-exit-criteria). |
| `prover_grade` | Reads the Prover run named by `completion_proof.<run_id_field>`: the agent's `prove` run, or its grade. The proof must be run from this mission's conversation after the phase was entered and have completed; a bare grade id counts only when the newest proof from this conversation names it. The grade must be a complete spec grade (not the spec-less platform grade) with a recorded verdict. A file the agent writes cannot satisfy it. | Optional `run_id_field` (default `prover_grade_run_id`) and `accepted_verdicts` (any of `verified`, `verified_with_indeterminate`, `not_verified`; default: any recorded verdict) |

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](/docs/Blueprint/Blueprint-Library-And-Missions#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:

```yaml theme={null}
exit_criteria:
  - criterion: "Repository validation passes"
    type: "required_check"
    name: "validate_repository"
    script: "checks/validate_repository.py"
    script_sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    expected_exit_code: 0
```

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

```yaml theme={null}
libraries:
  - name: view_to_dbt                    # the name a check script imports
    path: resources/lib/view_to_dbt.py   # repository-relative .py file
    sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
```

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

```yaml theme={null}
libraries:
  - name: view_to_dbt
    source:
      managed_source: shared-check-libraries   # the registered source's id
      commit: 0123456789abcdef0123456789abcdef01234567
      path: lib/view_to_dbt.py                 # path in that repository
    sha256: "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
```

* 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](/docs/Genesis-API/API-Reference#programmatic-blueprintrun-endpoints).

```yaml theme={null}
exit_criteria:
  - criterion: "Validation results reviewed before continuing"
    details: "Review the action-level validation report before exiting."
  - criterion: "Validation report is saved"
    type: "required_document"
    path: "validation_report.md"
```

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

```yaml theme={null}
phases:
  "2":
    name: "Validate results"
    require_human_approval: true
```

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:

```text theme={null}
<<QUESTION:START|phase=2|expected_response_type=choice|recommended=2>>
Which validation path should we use?
<<QUESTION:OPTIONS>>
Full refresh
Incremental refresh
<<QUESTION:END>>
```

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](#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`.

```yaml theme={null}
exit_criteria:
  - criterion: "Report deliverable exists"
    type: "required_document"
    path: "reports/REPORT_*.md"
```

If the agent writes `reports/REPORT_final.md`, `EXIT_PHASE` succeeds.

<Note>
  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](/docs/Blueprint/Blueprint-Library-And-Missions#injected-documents-and-mission-file-preview)
  for the full matching rules.
</Note>

## 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`:

```yaml theme={null}

phases:

  "0":

    name: "Setup"

    required_actions:

      - action: "Choose a dashboard name and create the setup file"

        instruction: |

          Pick a dashboard name and save it via phase_checkpoint
          when completing this phase.

    exit_criteria:

      - criterion: "Setup complete"

        type: "required_document"

        path: "setup_done.md"

  "1":

    name: "Create Dashboard Config"

    exit_criteria:

      - criterion: "Config file exists"

        type: "required_document"

        path: "CONFIG_<dashboard_name>.md"

    next_options:

      - id: "2"

        description: "Proceed to validation"

        requires_documents:

          - "VALIDATION_<dashboard_name>.md"
```

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`

<Note>
  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](#glob-patterns-in-exit-criteria-paths) above. Explicit checkpoint values are preferred for precise validation.
</Note>

### 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`

<Tip>
  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.
</Tip>

## Complete Example

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

```yaml theme={null}

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:

```mermaid theme={null}

graph TD

    A[Phase 0: Analyze] -->|Simple| B[Phase 1: Simple Migration]

    A -->|Complex| C[Transform 0: Design]

    B --> D[Phase 2: Validate]

    C --> E[Transform 1: Execute]

    E --> D

    D -->|Continue| F[Phase 3: Document]

    D -->|Complete| G[END]

    F --> G
```

## Automatic Progression

### When Branching Isn't Needed

If a phase doesn't have next\_options, the blueprint automatically continues to the next sequential phase:

<CardGroup cols={2}>
  <Card title="Numbered Phases" icon="list-ol">
    "0" → "1" → "2" → "3"
  </Card>

  <Card title="Named Sequences" icon="arrows-right">
    "setup\_0" → "setup\_1" → "setup\_2"
  </Card>
</CardGroup>

```yaml theme={null}

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
```

### 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](/docs/Genbot-Toolkit/Additional-Tool-Groups#thread-goal-tools)
for declaration behavior and [goal mode limits](/docs/Setup/Advanced-Settings#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](/docs/Blueprint/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

<AccordionGroup>
  <Accordion title="How does the AI agent choose which path to take?">
    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.
  </Accordion>

  <Accordion title="Can I influence which path is chosen?">
    Yes, by providing clear requirements and context in your initial conversation. The agent will ask clarifying questions if the right path isn't obvious.
  </Accordion>

  <Accordion title="What happens if required documents are missing?">
    The agent will automatically create the missing documents before proceeding. You'll see what files are being created and why.
  </Accordion>

  <Accordion title="Can I switch paths mid-mission?">
    No, once a path is chosen, the mission follows that branch. However, branches can merge back together at later phases.
  </Accordion>

  <Accordion title="How do I know when early completion is available?">
    The agent will inform you when objectives are met and offer to complete early. You can also see END options in the blueprint definition.
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Clear Path Descriptions" icon="comment">
    Write descriptive text explaining when each path should be chosen. Help the AI agent make the right decision.
  </Card>

  <Card title="Validate Early Exits" icon="check-circle">
    Always require key deliverables when allowing early completion to ensure work quality.
  </Card>

  <Card title="Keep Branches Meaningful" icon="sitemap">
    Create branches for genuinely different approaches, not minor variations.
  </Card>

  <Card title="Plan Merge Points" icon="code-merge">
    Design where branches rejoin to avoid duplicating later phases unnecessarily.
  </Card>
</CardGroup>

## 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

<Tip>
  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.
</Tip>