design-persona

Design Persona

Guide the user through designing and creating a simulation persona using the coval CLI. Follow the phases below in order, asking questions at each step.

If $ARGUMENTS contains a use case (e.g. "insurance_claims", "customer_support") or agent name, use it to skip or pre-fill relevant questions.

Phase 0: Preflight + Inventory

Step 1: Check authentication

coval whoami

If not authenticated, guide the user:

coval login

This prompts for an API key. Get one at https://app.coval.dev/settings (Organization > Manage > API Keys).

If the user doesn't have a Coval account, direct them to https://coval.dev to sign up.

Step 2: Inventory existing resources

Run these in parallel:

coval personas list --format json
coval agents list --format json

Decision matrix:

• Has personas → present them as a numbered list: "You already have these personas. Want to reuse one, duplicate and modify, or create new?"
• No personas → proceed to Phase 1
• If $ARGUMENTS matches an existing agent name, pre-select that agent for Phase 1

Phase 1: Agent Context

Ask: "Which agent will this persona test?"

• If agents exist, present them as a numbered list to pick from
• If no agents exist, say: "No agents found. You can still create a persona — just tell me what type of agent it will test (voice, outbound-voice, chat, sms, websocket)."

If the user selects an agent, fetch its details:

coval agents get <agent_id> --format json

Extract from the response:

• Agent type (model_type) — determines whether voice settings are relevant and conversation initiator direction
• Agent name — for context in prompts
• Agent prompt (if available) — helps craft a better persona

Key type mappings:

• MODEL_TYPE_VOICE / MODEL_TYPE_OUTBOUND_VOICE → voice settings matter, conversation initiator depends on direction
• MODEL_TYPE_CHAT / MODEL_TYPE_WEBSOCKET / MODEL_TYPE_API / MODEL_TYPE_ENDPOINT → voice settings are defaults only (won't affect simulation)

Phase 2: Use Case Detection

Ask: "What does your agent do?"

Present the options:

• customer_support — Customer Support
• scheduling_booking — Scheduling & Booking
• sales — Sales
• insurance_claims — Insurance Claims
• healthcare_intake — Healthcare Intake
• restaurant_orders — Restaurant Orders
• debt_collection — Debt Collection
• it_helpdesk — IT Helpdesk
• other — Other (describe it)

Load references/persona-templates.md and select the template matching the chosen use case.

Present the template as a starting point:

Here's a starting persona for <use case>:

  Name:       <template name>
  Voice:      <voice>
  Language:   en-US
  Background: <background>
  Wait:       <wait seconds>s
  Prompt:     "<template description>"

Ask: "Use this as a starting point? (yes / customize name / start from scratch)"

Phase 3: Voice + Language

Load references/voice-options.md for available options.

Ask these questions:

1. "What language should the persona speak?"

   • en-US — English (US)
   • es-ES — Spanish (Spain)
   • fr-FR — French (France)
   • de-DE — German
   • pt-BR — Portuguese (Brazil)
   • ja-JP — Japanese

2. "Voice preference?"

   • Female: aria (clear, professional)
   • Male: callum (clear, professional)

For non-voice agents (chat, websocket, API), explain: "Since your agent is text-based, voice and language are stored as defaults but won't affect the simulation."

Phase 4: Environment + Behavior

Background Sound

Present options with recommendations based on the use case:

Value	Description	Recommended For
quiet	No background noise	Medical, legal, financial calls
office	Office ambient noise	Corporate, business, IT support
cafe	Restaurant/cafe noise	Casual, restaurant scenarios
airport	Airport/travel noise	Travel-related agents

Say: "Based on your use case, I'd recommend . Use that or pick another?"

Wait Seconds

How long the persona waits before speaking after connection:

Value	Style	Best For
0.3	Fast responder	Restaurant orders, fast-paced interactions
0.5	Standard	Most inbound call scenarios
1.0	Slow / deliberate	Outbound calls, debt collection, elderly callers

Say: "The template uses