Personas

VibeFlow's persona system lets you assign specialized roles to AI agents, creating a virtual development team where each agent has a specific area of responsibility.

Available Personas

Persona	Role	What They Do
Developer	Senior Software Engineer	Implements features, fixes bugs, writes tests, commits code
Architect	Senior Architect	Reviews architecture, designs systems, validates approaches
Principal Engineer	Principal Engineer	God-level hands-on coder. Replaces developer + architect with surgical precision, minimal diffs, and canonical implementations
Security Lead	Senior Security Lead	Reviews code for vulnerabilities, creates compliance findings, verifies fixes
QA Lead	Senior QA Lead	Tests implementations, verifies functionality, rejects or approves work
Product Manager	Senior Product Manager	Creates PRDs, reviews requirements, plans features, manages priorities
Project Manager	Senior Project Manager	Tracks progress, manages timelines, coordinates across personas
UX Designer	Senior UX Designer	Creates designs, reviews UI implementations, provides design feedback
Customer	Customer Representative	Provides user perspective and feedback

How Personas Work

Work Item Routing

Each persona picks up work items at different stages:

Persona	Picks Up Items In Status	Transitions To
Product Manager	`in_review`	`planning` → `ready_to_implement`
Architect	`planning` or `ready_to_implement`	`architecture_review_complete`
Principal Engineer	`architecture_review_complete` or `ready_to_implement`	`implementing` → `done`
Developer	`ready_to_implement` or `architecture_review_complete`	`implementing` → `done`
Security Lead	`done` (security_reviewed = false)	Passes or rejects security review
QA Lead	`done` (security_reviewed = true, qa_verified = false)	Passes or rejects QA

Persona-Specific Behavior

Product Manager: Read-only for code. Creates documents, analysis, and work items. Does not implement.
Architect: Reviews design decisions, creates architecture docs, validates approaches before implementation.
Principal Engineer: Full code access. Replaces developer + architect as a single god-level session. Operates with 10 non-negotiable principles: full system comprehension, elegant solutions, minimal diffs, proven correctness, first-class error paths, performance awareness, security by default, canonical implementations, teaching-quality logs, and knowing when to say no.
Developer: Full code access. Implements, tests, commits, and pushes code changes.
Security Lead: Reviews completed code for vulnerabilities. Can create compliance findings and remediation issues.
QA Lead: Tests completed work against requirements. Can reject items back to in_review for rework.

Principal Engineer: Deployment Model

Principal Engineer replaces Developer + Architect — it is NOT additive.

Run PE as the only code persona on a branch. Do not run Developer or Architect sessions concurrently.
PE absorbs both implementation (Developer) and design (Architect) capabilities into one god-level session.
Branch conflict detection via GitModifyingPersonas prevents PE from sharing a branch with Developer or Architect.
Use PE when you want the highest-quality output for critical work. Use Developer + Architect for higher-throughput parallel work.

Setting Up a Multi-Persona Team

To create a complete development team:

Start a Developer session — This is your primary coding agent
Start an Architect session (optional) — Reviews architecture before implementation
Start a Security Lead session — Reviews completed work for vulnerabilities
Start a QA Lead session — Tests and verifies completed work
Start a Product Manager session (optional) — Manages requirements and priorities

Each persona runs as a separate agent session. They coordinate through VibeFlow's work item system — no direct communication between agents is needed.

Concurrent Personas

Multiple personas can run simultaneously on the same project:

Each persona uses its own session file (.vibeflow-session-{persona})
Work items are filtered by status, so personas don't conflict
Poll locks prevent race conditions when multiple agents try to claim work

The Review Pipeline

After a developer marks an item as done, it flows through the review pipeline:

done → Security Lead reviews → Security Lead passes
     → QA Lead tests → QA Lead passes → Fully Complete

If either reviewer rejects:

Security rejection → Item goes back to in_review for re-implementation
QA rejection → Item goes back to in_review for fixes

This creates a quality gate that ensures every piece of code is reviewed for security and tested for correctness.

Custom Persona Prompts

You can customize the agent prompt for each persona from the project's Setup tab:

Open the project → Setup tab
Find the Persona Prompts section
Edit the prompt template for any persona
Save — the updated prompt is used for all new sessions with that persona

Custom prompts let you add project-specific coding conventions, testing requirements, or architectural guidelines that agents follow automatically.