Workflows

A workflow is a YAML file that defines how a specific type of work gets done. It breaks work into phases, each phase into steps, and controls what the AI can do at each stage.

Why workflows exist

When you tell an AI to "fix this bug," it tends to jump straight to writing code. Sometimes that works. Often it doesn't — the AI misunderstands the problem, writes a fix for the wrong thing, or makes changes without understanding the codebase's conventions.

A workflow prevents this. It forces structure: understand the problem first, then plan, then implement, then verify. Each phase has its own rules, its own role, and its own deliverables. The AI can't skip ahead.

Structure

Here's what a workflow looks like:

name: fix
group: vast
description: Fix bugs and patches

phases:
  - name: understand
    role: vast:investigator
    steps:
      - name: Reproduce the issue
        instruction: Find a way to reproduce consistently
        deliverable:
          kind: evidence
          description: Reproduction steps documented
      - name: Find root cause
        instruction: Trace to the root cause
        skills: [rust-conventions]
        deliverable:
          kind: evidence
          description: Root cause identified

  - name: implement
    role: vast:builder
    allowed_actions:
      - fs.*
      - code.*
      - cargo.*
    steps:
      - name: Write the fix
        instruction: Minimal change that addresses root cause
        deliverable:
          kind: code_change
          description: Fix implemented
      - name: Write tests
        instruction: Test that covers the bug
        deliverable:
          kind: code_change
          description: Tests pass

This workflow has two phases — "understand" and "implement" — each with steps. Let's break down the pieces.

Phases

Phases are sequential stages of work. The workflow moves through them in order. Each phase defines:

• name — What this stage is called. Used in logs, status, and chain conditions.
• role — The role the AI assumes during this phase. The investigator role makes the AI focus on understanding. The builder role makes it focus on implementation.
• steps — The atomic tasks within this phase.
• allowed_actions (optional) — Restricts what the AI can do during this phase.

When a phase starts, the AI adopts its role and works through its steps in order. When all steps are complete, the workflow advances to the next phase.

Steps

Steps are the atomic units of work. Each step has:

• name — A human-readable label.
• instruction — What the AI should do. Be specific. "Find a way to reproduce consistently" is better than "investigate."
• deliverable — What the step must produce. The kind field says what type of output is expected (evidence, code_change, document, decision). The description says what constitutes completion.
• skills (optional) — A list of skills to inject for this step. If a step references skills: [rust-conventions], the AI gets that skill's domain knowledge during execution.

Steps within a phase are sequential. The AI works through them one at a time.

Enforcement

Workflows can control what the AI is allowed to do during specific phases. This is enforcement — not suggestions, but hard constraints.

Action restrictions

phases:
  - name: understand
    allowed_actions:
      - fs.read
      - code.search
      - git.log

This phase only allows reading files, searching code, and checking git history. The AI cannot write files, run commands, or make changes. It can only observe and analyze.

The inverse also works:

phases:
  - name: implement
    blocked_actions:
      - fs.delete

This phase allows everything except deleting files.

Write patterns

phases:
  - name: implement
    write_patterns:
      - "src/**"
      - "tests/**"

The AI can only write to files matching these glob patterns. It cannot modify configuration files, CI scripts, or anything outside src/ and tests/.

Combining constraints

You can combine allowed_actions, blocked_actions, and write_patterns on the same phase. The most restrictive constraint wins. If an action is allowed but writes to a path outside write_patterns, it's blocked.

Where workflows live

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

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

Project workflows take priority. If both locations have a workflow named "fix," the project version wins.

Built-in workflows

8Vast ships with a set of workflows for common tasks:

• fix — Bug fixing with investigation, implementation, and testing phases.
• feature-planning — Feature design with research, specification, and review phases.
• review — Code review with analysis, feedback, and verification phases.

These are starting points. You can override them by creating a workflow with the same name in your project's .8v/workflows/ directory, or define entirely new ones for your team's processes — deployment checklists, security audits, onboarding procedures, content review, or anything else that follows a repeatable structure.

Workflow lifecycle

When a workflow runs, it produces a work session — a record of what happened. The session tracks:

• Which phase the workflow is in.
• Which steps have been completed.
• What deliverables were produced.
• How long each phase took.

If a workflow is interrupted (you close your laptop, the daemon restarts), it resumes from where it left off. The session is persistent.

Connecting workflows

A single workflow handles one type of work. When you need multiple workflows in sequence — investigate, then plan, then fix, then review — you use a chain.