Chains

A chain connects multiple workflows into a sequence. Where a workflow defines how one type of work gets done, a chain defines the order in which different types of work happen — and which stages can be skipped based on context.

Why chains exist

Sometimes one workflow isn't enough. Fixing a critical bug might need: investigation, planning, implementation, code review, and QA. Each of those is a different workflow with different roles and rules. Doing them one at a time, manually, means you have to decide what comes next and when to transition.

A chain automates that. Define the sequence once, and the chain advances through stages as each workflow completes.

Structure

name: patch
group: vast
department: engineering
description: Fix bugs with conditional depth

stages:
  - name: Understand
    workflow: vast:investigate
    when: "cause_known != 'true'"

  - name: Plan
    workflow: vast:plan
    when: "risk != 'trivial'"

  - name: Fix
    workflow: vast:fix

  - name: Code Review
    workflow: vast:review-code
    when: "risk != 'trivial'"

This chain has four stages. Each stage runs a workflow. Three of the four stages have conditions.

Stages

A stage is one step in the chain. It has:

• name — A label for this stage.
• workflow — Which workflow to run. Uses the format group:name (e.g., vast:fix).
• when (optional) — A condition that determines whether this stage runs. If the condition evaluates to false, the stage is skipped.

Stages run in order. When one workflow completes, the chain evaluates the next stage's when condition. If it passes (or has no condition), that workflow starts. If it fails, the chain skips to the stage after that.

Conditional routing

The when field evaluates against parameters — key-value pairs that describe the context of the work. Parameters can be set when the chain starts, or by earlier stages as they produce output.

when: "cause_known != 'true'"

This means: run this stage only if we don't already know the cause. If someone files a bug report that includes the root cause, the investigation stage is skipped and the chain moves straight to planning or fixing.

when: "risk != 'trivial'"

This means: skip this stage for trivial changes. A one-line typo fix doesn't need a formal planning phase or code review.

Conditions keep chains efficient. The same chain handles both a critical production bug (all stages) and a minor text fix (just the fix stage), without you defining separate chains for each.

How stages advance

Stages advance automatically. When a workflow completes — all its phases finished, all deliverables produced — the chain moves to the next stage. There's no manual "next" button.

If a stage's when condition is false, it's skipped entirely. The chain evaluates the next stage immediately.

If all remaining stages are skipped (their conditions are all false), the chain completes.

Checkpoints

If a chain is paused or interrupted — you close your laptop, restart the daemon, or switch to a different task — it saves a checkpoint. The checkpoint records which stage the chain is on and what parameters have been set.

When you resume, the chain picks up from the last checkpoint. It doesn't re-run completed stages.

Where chains live

Chains are YAML files stored in .8v/chains/ — either in your project directory or your home directory.

• Project chains (.8v/chains/patch.yaml in your project) — Available only in that project.
• User chains (~/.8v/chains/patch.yaml) — Available in all your projects.

Like workflows, project chains take priority over user chains with the same name.

When to use a chain vs. a workflow

Use a workflow when the work has one focus: fix a bug, review code, write a spec. Use a chain when the work spans multiple focuses: investigate then plan then fix then review. Chains are the glue between workflows.

Most day-to-day work uses chains. The chain selects the right workflows, in the right order, with the right conditions. You define the process once and reuse it.