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.1
    permissions:
      allowed_tools: ["Read", "Glob", "Grep"]
      deny: ["Write(*)", "Edit(*)"]

Built-in Personas

Wave includes 14 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, read-only analysis with detailed reporting	✓Allow	✗Deny	✗Deny	✗Deny
craftsman	Full implementation and testing with scoped write and execute access	✓Allow	●Conditional	●Conditional	✗Deny
implementer	Code generation and modification with scoped write access	✓Allow	●Conditional	●Conditional	✗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.1
    permissions:
      allowed_tools: ["Read", "Glob", "Grep"]
      deny: ["Write(*)", "Edit(*)", "Bash(*)"]

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.2
    permissions:
      allowed_tools: ["Read", "Glob", "Grep"]
      deny: ["Write(*)", "Edit(*)", "Bash(*)"]

Use cases:

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

Implementer

The Implementer handles code generation and modification with scoped write access.

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

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"
        - "Glob"
        - "Grep"
        - "Write(src/*)"
        - "Write(*_test.go)"
        - "Edit(src/*)"
        - "Bash(go test*)"
        - "Bash(go build*)"
      deny:
        - "Write(*.env)"
        - "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: ephemeral          # Always isolated
  clone_depth: 1           # Shallow clone for speed
  preserve_on_failure: true # Keep workspace for debugging

Using Personas in Pipelines

Reference personas by name in pipeline steps:

pipelines:
  gh-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

• 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