Built-in Personas

CodeCourier defines ten built-in persona types. These types are not pre-created personas themselves but rather role definitions that every persona must use. When you create a new persona, you assign it one of these types, which determines its icon, color, default tool and model, and its role within workflow pipelines.

The built-in types are defined in the workflow step configuration (convex/config/workflows.config.ts) and are shared across the entire platform. Understanding each type helps you create personas that are well-suited to their role in the development process.

Designer

The Designer is the primary implementation agent. It receives a task prompt and writes code to fulfill it. Designers work directly in the sandbox filesystem: creating files, installing packages, configuring build tools, and running the development server.

When to use: Any task that requires writing or modifying code. Feature implementation, bug fixes, configuration changes, documentation writing, and migration scripts. If the output is code in a repository, a Designer persona is the right choice.

Use cases: React component implementation, REST API development, database schema migrations, configuration file generation, build pipeline setup.

Recommended configuration:Use the most capable model available (Opus) for complex tasks. Set thinking effort to “high” for architectural changes. Include skills relevant to the technology stack (e.g., frontend-design for UI work,convex-implementation for database work). Bind a context document that covers your codebase architecture or coding standards.

Checker

The Checker is a verdict-based review agent that evaluates the work done by a preceding step (typically a Designer). It reads the code changes, optionally runs tests, and produces a structured verdict: pass or fail with detailed feedback. This binary verdict is what distinguishes the Checker from the Reviewer type.

When a Checker returns a fail verdict, the workflow can loop back to the Designer step for another iteration, creating an automated design-review cycle that improves quality without human intervention.

When to use: After any Designer step where quality assurance matters. Code reviews, type checking, test verification, security audits, and compliance checks.

Use cases: TypeScript type-safety enforcement, test coverage gates, security policy compliance, style guide adherence, performance budget checks.

Recommended configuration:A faster model (Sonnet) is often sufficient since the Checker’s task is more focused than the Designer’s. Instructions must define explicit pass/fail criteria - the checker should never be ambiguous about its verdict. Include the app-security skill if security review is part of the check.

Optimizer

The Optimizer is a refactoring specialist. It takes code that already works and makes it better: reducing duplication, improving performance, enhancing readability, and applying best practices. The Optimizer does not add new features; it improves existing ones.

When to use: As a post-processing step after a Designer has completed implementation. Particularly valuable for large code changes where the Designer focused on getting things working and the Optimizer polishes the result.

Use cases: Eliminating N+1 query patterns, reducing React re-renders, extracting reusable hooks, normalizing error handling, improving bundle size.

Recommended configuration: Use Opus for its ability to understand complex codebases. Instructions should explicitly state what NOT to change (public APIs, exports) to avoid breaking changes during optimization. Include the performance-optimization-addyosmani skill for performance-focused work.

Prompter

The Prompter is a prompt engineering agent. It takes a user’s informal, potentially vague request and rewrites it into a clear, structured specification with explicit acceptance criteria. The refined prompt is then passed to the next step in the pipeline.

When to use: As the first step in a pipeline when user requests are likely to be underspecified. Especially valuable for teams where non-technical stakeholders submit feature requests that need translation into technical specifications.

Use cases: Translating product requirements into technical specs, expanding short task descriptions into detailed implementation guides, generating acceptance criteria from user stories.

Recommended configuration:Sonnet is usually sufficient for prompt refinement. Instructions should specify the output format (e.g., “always include acceptance criteria as a numbered list and identify the affected files explicitly”).

Investigator

The Investigator is a research agent that analyzes the codebase before implementation begins. It reads files, traces dependencies, maps the architecture, and produces a structured summary of findings. This context helps subsequent agents make better decisions.

When to use: Before a Designer step on unfamiliar codebases, focused bug investigations, or when the task requires understanding how a specific subsystem works. The Investigator targets a particular area of the codebase and reports on it concisely.

Use cases: Understanding an authentication subsystem before adding a new OAuth provider, tracing a specific data flow before refactoring it, identifying which files will be affected by a proposed change.

Recommended configuration:Use Opus for its superior codebase comprehension. Set thinking effort to “high”. Instructions should specify what to investigate (e.g., “focus on database queries and API routes related to authentication”). For comprehensive cross-cutting analysis, prefer the Deep-Dive type instead.

Planner

The Planner is an architecture agent that analyzes codebases and creates structured assessments. It reviews the repository, understands the requirements, and breaks work into actionable items. Each item has a name, description, and detailed prompt. This type powers CodeCourier’s issue sessions feature.

When to use:For complex, multi-step projects that benefit from upfront analysis. The Planner’s output can be directly executed by CodeCourier’s work chain system.

Use cases: Breaking a large feature request into discrete issues, identifying technical debt across the codebase, producing a prioritized list of improvements, generating issue backlogs for sprint planning.

Recommended configuration: Always use Opus with high thinking effort. The Planner needs maximum reasoning capability to decompose complex projects effectively. Bind an architecture context document for best results.

Deep-Dive

The Deep-Dive is an intensive analysis agent designed for complex, multi-faceted problems that require comprehensive codebase understanding. It is similar to the Investigator but operates at a broader scope - rather than focusing on one subsystem, it explores cross-cutting concerns, traces interactions between multiple systems, and produces an exhaustive analysis report.

Deep-Dive sessions typically run longer and at higher thinking effort than Investigator sessions. The output is more thorough: not just “here is how this subsystem works” but “here is how all the relevant systems interact, where the boundaries are ambiguous, what the risk surface looks like, and what architectural decisions drove the current state.”

When to use: Architectural analysis before a major refactor, root-cause investigation for a complex production incident, understanding a legacy codebase before onboarding a new team, or any analysis task where depth matters more than speed.

Use cases: Pre-migration architectural assessment, security threat modeling across an entire application, dependency analysis before upgrading a major library, tracing a data flow that spans multiple services and databases.

Recommended configuration: Always use Opus with max or xhigh thinking effort. Budget for longer sandbox runtime (increase timeout). Include broad skills: app-security, performance-optimization-addyosmani, superpower-debugging. Bind a context document that provides project-level architectural context so the agent can focus on depth rather than orientation.

Reviewer

The Reviewer is a specialized code review agent focused on security, maintainability, design patterns, and code quality. It is fundamentally different from the Checker in one critical way: the Reviewer does not produce pass/fail verdicts. Instead, it produces detailed, nuanced review feedback - observations, suggestions, concerns, and commendations - that a human developer or subsequent agent can act on.

This makes the Reviewer ideal for situations where a binary gate is too blunt. A Checker might reject code because a nit-level issue fails a strict criterion; a Reviewer would note the same issue as a “minor concern” while still acknowledging that the implementation is fundamentally sound.

When to use: Pre-merge code reviews that should inform a human decision, architectural review of a proposed design, security review that produces a risk assessment rather than a block, or any review scenario where qualitative feedback is more valuable than a binary verdict.

Use cases: Pull request review commentary, security risk assessment for a new API surface, design pattern compliance audit, accessibility review for a UI component library.

Recommended configuration:Use Opus for nuanced reasoning. Set thinking effort to “high”. Instructions should define the output format explicitly (e.g., sections for Strengths, Major Concerns, Minor Concerns, Suggestions). Include app-security and superpower-codereview skills. The Reviewer should not be placed in a loop - its purpose is to produce one comprehensive review, not to gate-loop.

Custom

The Custom type is a free-form persona type for agents that don’t fit any of the nine standard categories. It imposes no structural expectations on the agent’s behavior - it behaves exactly as its instructions, skills, context, commands, and scripts dictate. The Custom type provides maximum flexibility for specialized, non-standard roles.

When to use:When none of the nine built-in types accurately describe what the persona does. Custom personas often fill unique roles that are specific to a project’s workflow rather than general development stages.

Use cases:

• Documentation Writer - Generates or updates JSDoc, README files, API documentation, and inline code comments.
• Changelog Generator - Reads git diff output and produces human-readable changelog entries in a specified format.
• Migration Assistant - Applies a specific database or API migration pattern across multiple files systematically.
• Dependency Auditor - Scans package.json for outdated or vulnerable dependencies and produces an upgrade plan.
• Localization Agent - Extracts hardcoded strings and populates i18n resource files.
• PR Summarizer - Reads a git diff and writes a structured pull request description.

Recommended configuration: Because the Custom type has no predefined role, the quality of the persona depends almost entirely on the quality of its instructions. Write highly specific, structured instructions that leave nothing ambiguous. Choose the model based on task complexity - simple text transformation tasks can use Sonnet, while complex multi-file reasoning tasks should use Opus.

Type Selection Summary

Next Steps