Roles

A role is a persona the AI assumes during a workflow phase. It defines how the AI should think, what it should prioritize, and what it should avoid. When a workflow moves from one phase to the next, the AI's role changes with it.

Why roles matter

Without roles, the AI treats every phase the same way. Ask it to investigate a bug and it jumps straight to writing a fix. Ask it to review code and it starts refactoring instead of analyzing.

Roles force a different mindset per phase. The investigator traces causes — it doesn't write code. The builder implements solutions — it doesn't re-investigate. The reviewer analyzes — it doesn't rewrite. Each role has a clear boundary.

Structure

name: investigator
group: vast
department: engineering
description: Traces bugs to their root cause

instructions: |
  You are the investigator. You methodically trace problems
  to their root cause. You build timelines, gather evidence,
  and use structured techniques (five whys, hypothesis testing).
  You do not fix things. You find the cause.

phases:
  - understand
  - validate

A role has:

• name — Identifier used in workflow phase definitions (e.g., role: vast:investigator).
• group — Namespace. vast for built-in roles. Use your own group name for custom roles.
• description — A one-line summary of what this role does.
• instructions — The prompt given to the AI when it assumes this role. This is where you define the behavior: what to focus on, what to avoid, how to approach problems.
• phases — Which workflow phases this role is designed for. This is informational — it helps you understand which phases typically use this role, but any phase can reference any role.

Built-in roles

8Vast ships with roles for common engineering tasks:

• vast:investigator — Traces problems to their root cause. Gathers evidence. Builds timelines. Does not fix things.
• vast:builder — Implements solutions. Writes code. Writes tests. Follows conventions. Does not re-investigate.
• vast:reviewer — Analyzes code changes. Checks for correctness, style, and edge cases. Does not rewrite.
• vast:planner — Designs solutions. Evaluates tradeoffs. Produces specifications. Does not implement.

Each role has detailed instructions that shape the AI's behavior during its active phases.

Custom roles

Define your own roles for your team's needs. A security auditor, a documentation writer, a performance analyst — any perspective you want the AI to adopt during a workflow phase.

name: security-auditor
group: myteam
description: Reviews code for security issues

instructions: |
  You review code for security vulnerabilities. Check for:
  injection attacks, authentication bypasses, data exposure,
  insecure defaults, missing input validation.

  Flag issues by severity. Do not fix them — document them
  with reproduction steps and suggested mitigations.

Reference it in a workflow phase:

phases:
  - name: security-review
    role: myteam:security-auditor
    steps:
      - name: Audit changes
        instruction: Review all modified files for security issues
        deliverable:
          kind: document
          description: Security audit report

Where roles live

Roles are YAML files stored in .8v/roles/:

• Project roles (.8v/roles/security-auditor.yaml in your project) — Available only in that project.
• User roles (~/.8v/roles/security-auditor.yaml) — Available in all your projects.

Project roles take priority over user roles with the same name.

Roles vs. skills

Roles and skills are different things. A role defines who the AI is — its perspective and approach. A skill provides what the AI knows — domain-specific knowledge and rules. A role says "you are an investigator." A skill says "here are this project's error handling conventions." They work together: a phase has one role and can reference multiple skills.