Personas

A persona is a specialized AI agent with specific permissions and behavior. Personas control what an AI can see, do, and how it responds. They are fundamental to Wave's security model, enforcing separation of concerns and preventing unintended actions.

Overview

Personas serve three critical functions in Wave:

1. Permission Enforcement - Control which tools and files an AI can access
2. Behavior Customization - Define how the AI approaches tasks via system prompts
3. Security Isolation - Prevent cross-contamination between pipeline steps

personas:
  navigator:
    adapter: claude
    system_prompt_file: .wave/personas/navigator.md
    #temperature: 0.3
    permissions:
      allowed_tools: ["Read", "Glob", "Grep", "Bash(git log*)", "Bash(git status*)"]
      deny: ["Write(*)", "Edit(*)", "Bash(git commit*)", "Bash(git push*)"]

Built-in Personas

Wave includes 30 built-in personas designed for secure, specialized execution. The following table highlights four core personas commonly used in pipelines:

✓Allow - Full access granted

✗Deny - Access blocked

●Conditional - Scoped/limited access

Persona ▲	Description	Read	Write	Execute	Network
auditor	Security and code review with go vet and npm audit	✓Allow	✗Deny	●Conditional	✗Deny
craftsman	Full implementation and testing with broad tool access	✓Allow	✓Allow	✓Allow	✗Deny
implementer	Code generation and modification with full tool access	✓Allow	✓Allow	✓Allow	✗Deny
navigator	Read-only codebase explorer, produces navigation context and analysis	✓Allow	✗Deny	✗Deny	✗Deny

Navigator

The Navigator is a read-only codebase explorer. It produces navigation context without modifying any files.

personas:
  navigator:
    adapter: claude
    system_prompt_file: .wave/personas/navigator.md
    #temperature: 0.3
    permissions:
      allowed_tools: ["Read", "Glob", "Grep", "Bash(git log*)", "Bash(git status*)"]
      deny: ["Write(*)", "Edit(*)", "Bash(git commit*)", "Bash(git push*)"]

Use cases:

• Codebase analysis and understanding
• Architecture documentation generation
• Finding relevant code for implementation tasks
• Creating navigation context for downstream steps

Auditor

The Auditor performs security and code review analysis. It has read-only access to analyze code quality and security issues.

personas:
  auditor:
    adapter: claude
    system_prompt_file: .wave/personas/auditor.md
    #temperature: 0.1
    permissions:
      allowed_tools: ["Read", "Grep", "Bash(go vet*)", "Bash(npm audit*)"]
      deny: ["Write(*)", "Edit(*)"]

Use cases:

• Security vulnerability analysis
• Code quality assessment
• Compliance checking
• Review of proposed changes

Implementer

The Implementer handles code generation and modification with full tool access.

personas:
  implementer:
    adapter: claude
    system_prompt_file: .wave/personas/implementer.md
    #temperature: 0.3
    permissions:
      allowed_tools:
        - Read
        - Write
        - Edit
        - Bash
        - Glob
        - Grep
      deny:
        - "Bash(rm -rf /*)"
        - "Bash(sudo *)"

Use cases:

• Feature implementation
• Bug fixes
• Code refactoring
• Applying reviewer suggestions

Craftsman

The Craftsman handles implementation, testing, and code changes with full scoped access. It combines write and execute permissions for end-to-end feature delivery.

personas:
  craftsman:
    adapter: claude
    system_prompt_file: .wave/personas/craftsman.md
    #temperature: 0.3
    permissions:
      allowed_tools:
        - Read
        - Write
        - Edit
        - Bash
      deny:
        - "Bash(rm -rf /*)"

Use cases:

• Feature implementation with tests
• Bug fixes with regression tests
• Code refactoring
• End-to-end delivery tasks

Permission Model

Wave's permission system uses a deny-first evaluation model. This means all actions are denied by default unless explicitly allowed.

Evaluation Order

1. Check deny patterns - If any deny pattern matches, the action is blocked immediately
2. Check allowed_tools - If any allowed_tools pattern matches, the action is permitted
3. Implicit deny - If no pattern matches, the action is blocked (default deny)

Permission Patterns

Permissions use glob patterns to control tool access:

permissions:
  allowed_tools:
    - "Read"                    # All Read calls allowed
    - "Write(src/*.ts)"         # Write to TypeScript files in src/
    - "Write(docs/**/*.md)"     # Write to markdown files anywhere in docs/
    - "Bash(npm test*)"         # Only npm test commands
    - "Bash(go build ./...)"    # Specific go build command
  deny:
    - "Write(*.env)"            # Never write env files
    - "Write(**/.env*)"         # Block .env files anywhere
    - "Bash(rm -rf *)"          # Block destructive commands
    - "Bash(*secret*)"          # Block commands with 'secret'

Pattern Syntax

Pattern	Description	Example
Tool	Allow all calls to tool	Read - allows all reads
Tool(path)	Allow specific path	Write(src/main.go)
Tool(path/*)	Allow files in directory	Write(src/*)
Tool(path/**)	Allow recursive directory	Write(src/**)
Tool(*pattern*)	Wildcard matching	Bash(*test*)

Fresh Memory at Step Boundaries

A critical security feature of Wave is fresh memory at every step boundary. Each pipeline step starts with a clean context:

What This Means

• No chat history inheritance - Each step cannot see previous conversations
• Artifact-only communication - Steps communicate through explicit artifacts
• Clean context - Each persona starts fresh with only:
  • Its system prompt
  • Injected artifacts from dependencies
  • The current step's prompt

Why Fresh Memory Matters

1. Security - Prevents prompt injection from propagating across steps
2. Reliability - Each step behaves consistently regardless of previous execution
3. Audit trail - All inter-step communication is explicit and logged
4. Isolation - A compromised step cannot influence future steps via memory

Workspace Isolation

Each pipeline step executes in an ephemeral workspace - an isolated filesystem environment:

Workspace Features

• Fresh clone - Each step gets a fresh copy of the codebase
• Isolated filesystem - Changes in one workspace don't affect others
• Automatic cleanup - Workspaces are destroyed after step completion
• Artifact extraction - Only declared outputs are preserved
• No cross-contamination - File modifications cannot leak between steps

Workspace Configuration

workspace:
  type: worktree           # Git worktree for full isolation
  ref: my-shared-workspace # Optional: share workspace with another step
  mounts:                  # Optional: mount paths into workspace
    - path: ./config
      mode: readonly

Token Scopes

Personas can declare required forge token permissions via the token_scopes field. Scopes follow the format <resource>:<permission> (e.g., issues:read, pulls:write) with an optional @<ENV_VAR> suffix for custom token routing.

personas:
  implementer:
    adapter: claude
    system_prompt_file: .wave/personas/implementer.md
    token_scopes:
      - "repos:write"
      - "issues:write"
      - "pulls:write"
      - "actions:read"

Purpose

Token scopes enforce least-privilege API access per persona. During preflight, Wave validates that the active forge token satisfies each persona's declared scopes before pipeline execution begins. This catches misconfigured credentials early rather than failing mid-pipeline.

Permission Hierarchy

Permissions are hierarchical: admin satisfies write, which satisfies read. Canonical resources include issues, pulls, repos, actions, and packages.

For full scope format details, environment variable routing, and preflight validation behavior, see the Manifest Reference — Token Scopes.

Key sources: internal/scope/scope.go, internal/scope/validator.go, internal/scope/resolver.go

Using Personas in Pipelines

Reference personas by name in pipeline steps:

pipelines:
  ops-pr-review:
    description: "Review and improve code quality"
    steps:
      - id: analyze
        persona: navigator
        exec:
          type: prompt
          source: "Analyze the codebase structure and identify areas for improvement"
        outputs:
          - analysis.md

      - id: review
        persona: auditor
        dependencies: [analyze]
        inputs:
          - from: analyze
            artifact: analysis.md
        exec:
          type: prompt
          source: "Review the analysis and identify security concerns"

      - id: implement
        persona: implementer
        dependencies: [review]
        exec:
          type: prompt
          source: "Implement the suggested improvements"

Next Steps

Complete persona list: Run wave list personas to see all 30 built-in personas with their permissions, or browse the definitions in wave.yaml.

• Custom Personas Guide - Create specialized personas for your workflows
• Pipelines - Use personas in multi-step workflows
• Contracts - Validate persona outputs
• Workspaces - Understand workspace isolation
• Manifest Reference - Complete persona configuration options