Creating Personas

Step-by-step guide to creating AI personas in CodeCourier, including all ten persona types, fields, context binding, and initial configuration.

7 min read

personascreateconfiguration

Creating a persona in CodeCourier takes just a few clicks from the dashboard. Once created, the persona can be used in any workflow pipeline within the project. This guide walks through the creation process, explains each field, and provides recommendations for getting the best results from your persona configurations.

Creating a Persona from the UI

Navigate to the Personas page

From your project dashboard, find the Personas entry in the sidebar navigation. If you do not see it, you may need to scroll down or access it from the navigation menu. The personas page is located at /p/{projectId}/personas.

Open the Create dialog

Click the + Create button in the top-right corner of the page header. This opens a dialog where you enter the basic persona details. If you have no personas yet, the page shows an empty state with a prominent create button.

Enter a name

Give your persona a descriptive name that reflects its purpose. Good names communicate the role and specialization at a glance:

Frontend Designer - a designer focused on UI implementation
Strict Code Reviewer - a reviewer with detailed feedback
Security Checker - a checker that enforces security standards
Performance Optimizer - an optimizer focused on runtime efficiency
Architecture Planner - a planner for system design tasks

Names must be non-empty and are validated on submission. They can be changed later from the persona detail page.

Select a type

Choose the persona type from the dropdown. CodeCourier defines the following types, each corresponding to a specific role in the workflow pipeline:

Designer - Primary coding and implementation agent
Checker - Code review with pass/fail verdict and feedback
Optimizer - Code improvement and refactoring agent
Prompter - Prompt engineering and specification agent
Investigator - Codebase analysis and research agent
Planner - Architecture and issue analysis agent
Deep-Dive - Intensive multi-system analysis agent
Reviewer - Qualitative code review without a pass/fail verdict
Custom - Free-form type for specialized or non-standard roles

The type determines the persona’s icon and default behavior within workflow pipelines. The default selection is designer.

Add a description (optional)

The description field is optional but recommended. Use it to document the persona’s purpose, specialization, or any conventions it should follow. This helps team members understand what the persona is for when selecting it in workflow configurations.

Submit the form

Click Create to save the persona. On success, you are automatically redirected to the persona detail page where you can configure advanced settings like model selection, instructions, skills, commands, scripts, and context binding.

Quick Start

After creating a persona, the two most important next steps are writing its instructions and selecting its skills. The Instructions tab is where you define the agent’s behavior, coding standards, and domain-specific rules. The Skills tab is where you inject relevant domain knowledge packages, commands, and scripts.

Persona Fields Reference

The create dialog captures the essential fields. The full configuration is available on the persona detail page after creation. Here is a complete reference of all fields:

Core Fields (set during creation)

Field	Type	Required	Description
`name`	string	Yes	Display name for the persona. Must be non-empty.
`type`	enum	Yes	Role type: designer, checker, optimizer, prompter, investigator, planner, deep-dive, reviewer, or custom.
`description`	string	No	Human-readable description of the persona’s purpose.

Configuration Fields (set on the detail page)

Field	Type	Default	Description
`cliId`	string	Project default	Which CLI tool to use (e.g., claude, opencode, codex).
`model`	string	Tool default	Specific LLM model (e.g., claude-opus-4-6, claude-sonnet-4-6).
`thinkingEffort`	string	none	Reasoning depth: none, low, medium, high, xhigh, or max.
`instructions`	string	Empty	Custom system-level instructions for the agent.
`contextId`	ID	None	Binds a Context document to this persona. The context’s active version markdown is injected into the sandbox alongside the persona’s instructions.
`selectedSkills`	string[]	Empty	Array of skill IDs to make available during sessions.
`selectedCommands`	string[]	Empty	Array of command IDs to inject into the sandbox as shell aliases or commands.
`selectedScripts`	string[]	Empty	Array of script IDs to inject into the sandbox as executable scripts.
`learningsEnabled`	boolean	true	Whether compiled learnings are injected into sessions.
`isEnabled`	boolean	true	Whether the persona is active and selectable in pipelines.

Versioning Fields (managed automatically)

Field	Type	Description
`version`	number	Monotonically incrementing version number. Starts at 1 on creation.
`isLatest`	boolean	True on the current active version. Only one version per persona is latest at any time.
`parentPersonaId`	ID	Points to the preceding version record. Null on the first version.

Versioning and Editing

Editing a persona’s instructions or configuration from the detail page creates a new version automatically. The new version becomes isLatest and all future workflow runs use it. Previous versions are preserved and visible in the version history.

Context Binding

Context documents are reusable markdown resources - documentation, reference guides, architectural notes, or any other reference material - that you maintain separately from persona instructions. When you bind a context document to a persona via the contextIdfield, the context’s active version markdown is automatically prepended to the sandbox configuration alongside the persona’s own instructions.

This is particularly powerful for sharing context across multiple personas without duplicating content. For example, a “Codebase Architecture” context document could be bound to your designer, reviewer, and deep-dive personas simultaneously. When you update the architecture document, all three personas pick up the change on their next run.

To bind a context, navigate to the Context tab on the persona detail page and select a context document from the dropdown. Only active context documents are listed.

Creating Personas via the API

Personas can also be created programmatically through the Convex mutation. This is useful for automating persona setup or building custom tooling:

create-persona.ts

import { api } from "@/convex/_generated/api";
import { useMutation } from "convex/react";

// In a React component:
const createPersona = useMutation(api.personas.create);

const personaId = await createPersona({
  projectId: "your-project-id",
  name: "Frontend Designer",
  type: "designer",
  description: "Specialized in React and Tailwind CSS",
  model: "claude-opus-4-6",
  instructions: "Follow the project's component patterns...",
  contextId: "context-id-for-architecture-doc",
  selectedSkills: ["frontend-design", "vitest-testing"],
  selectedCommands: ["lint-check", "type-check"],
  selectedScripts: ["run-tests"],
  isEnabled: true,
});

Validation

The persona name is validated server-side. Empty names or names that exceed the maximum length will cause the mutation to throw a ConvexError. Always trim user input before submitting.

Duplicating Existing Personas

If you want to create a persona that is similar to an existing one, use the Duplicateaction from the persona list. This creates a copy with “(copy)” appended to the name and identical settings - including the same context binding, skills, commands, and scripts. You can then rename it and adjust whichever fields need to change. Duplication is often faster than creating from scratch when you need multiple personas with similar configurations.

Bulk Operations

The persona list page supports bulk selection with checkboxes. Select multiple personas and use the bulk action bar to delete them all at once. Bulk deletion uses soft delete, meaning the personas are moved to the trash and can be restored if needed.

Next Steps

Persona Configuration

Deep dive into model selection, instructions, skills, commands, scripts, context, and versioning.

Built-in Personas

Learn about all ten persona types available in every project.