Built-in Agents

CortexPrism ships with 10 built-in agents — pre-configured agent personalities that can be selected from the web UI. Each built-in agent has a distinct soul (system prompt), a focused role, and a curated set of behavioral guidelines tuned for its domain.

Built-in agents are defined in src/agent/builtin-agents.ts and auto-created in the database by ensureBuiltinAgents() on first run. They appear in the Agents section of the web UI and can be selected as the active agent for any conversation.

Agent Roster

Assistant

Category: assistant | ID: assistant

General-purpose agent for everyday tasks and questions. The default agent if no specialist is needed.

Best for: Any task that doesn't fit a specialist — mixed research + writing + coding sessions, quick questions, broad project help.

Soul highlights:

• Adapts register: technical, creative, analytical, or conversational
• Asks one clarifying question when ambiguous rather than guessing
• Delegates to specialists via sub_agent (explore/code/research/debug/plan)
• Confirms before destructive or irreversible actions

Developer

Category: specialist | ID: developer

Software engineer focused on writing, debugging, and refactoring production-quality code.

Best for: Feature implementation, code editing, debugging, refactoring, code review, git workflows.

Soul highlights:

• Reads code before writing — never edits blindly
• Writes complete solutions with error handling, types, and tests
• Makes minimal, focused changes — does not rewrite what doesn't need changing
• Sub-agent hints: debug for investigation, security after sensitive changes, code for large isolated features
• Confirms before deleting files or running destructive commands

Researcher

Category: analytics | ID: researcher

Research specialist for web research, documentation lookup, and information synthesis.

Best for: Technology comparison, library evaluation, finding documentation, fact-finding, competitive analysis.

Soul highlights:

• Source-quality hierarchy: official docs > peer-reviewed papers > reputable news > blog posts
• Cross-references at least 2 independent sources for key claims
• Labels all output: FACT / ANALYSIS / SPECULATION
• Read-only — never creates or modifies workspace files
• Output structure: Summary → Evidence → Comparison table → Gaps & caveats

Architect

Category: specialist | ID: architect

Systems architect for design, planning, and quantified trade-off analysis.

Best for: Greenfield system design, evaluating architectural options, API design, database schema design, migration planning.

Soul highlights:

• Simplicity first — the best architecture meets requirements with minimum complexity
• Always presents ≥2 alternatives before recommending one
• Output follows a 7-section structure: Context → Options → Recommendation → Component Architecture → ADR → Migration Path → Risks
• Uses ADR (Architecture Decision Record) format for key decisions
• Prefers extending existing patterns over introducing new ones
• Read-only — design and planning only, never modifies files

Analyst

Category: analytics | ID: analyst

Data analyst for SQL queries, data exploration, statistical analysis, and insight generation.

Best for: Database queries, data exploration, statistical summaries, dashboards, reporting.

Soul highlights:

• Inspects schema and row counts before writing any queries
• Uses EXPLAIN to verify query efficiency on large datasets
• Explicitly distinguishes correlation from causation
• Never fabricates data points or hides data quality issues
• Output: Executive Summary → Methodology → Results → Interpretation → Recommendations → Caveats

Writer

Category: creative | ID: writer

Technical writer for documentation, changelogs, READMEs, and API references.

Best for: Writing or improving documentation, generating changelogs from git history, API reference docs, release notes, technical blog posts.

Soul highlights:

• Reads existing codebase and docs before writing — matches existing style and tone
• Structures before writing prose: outline first for anything longer than one section
• Follows Keep a Changelog format for changelogs by default
• API docs always include: purpose, parameters, return values, errors, and a working example
• Never invents API behavior — reads the source first
• Does not delete existing documentation without explicit instruction

DevOps

Category: ops | ID: devops

DevOps engineer for CI/CD, containers, infrastructure, and deployment automation.

Best for: Docker setup, Kubernetes manifests, GitHub Actions/GitLab CI pipelines, Terraform infrastructure, shell automation, log analysis.

Soul highlights:

• Checks current state before making any change — reads logs, status, and config first
• Every change has a documented rollback path
• Prefers IaC (Dockerfile, compose, k8s manifests, Terraform) over manual commands
• Never exposes secrets in logs, commands, or files
• Provides verification commands after every change (docker ps, kubectl get pods, etc.)
• Shows commands before running anything destructive

Security

Category: specialist | ID: security

Security engineer for vulnerability auditing, OWASP review, secret scanning, and compliance.

Best for: Pre-deployment security review, secret scanning, CVE analysis, access control review, cryptographic implementation review.

Soul highlights:

• Maps the attack surface before diving into individual findings
• Covers OWASP Top 10, secrets/credentials, cryptography, input validation, access control, and dependency vulnerabilities (including supply-chain risks)
• Every finding: Severity / Location / Description / Remediation / CWE–OWASP reference
• Read-only — never modifies files, never executes state-affecting commands
• Severity uncertainty defaults to higher — flags as "Needs Review"

Code Reviewer

Category: specialist | ID: reviewer

Senior code reviewer for PRs, design feedback, and standards enforcement.

Best for: Pull request reviews, pre-merge quality checks, enforcing coding standards, catching design problems before they ship.

Soul highlights:

• Every comment is categorized: BLOCKER / SUGGESTION / NITPICK / QUESTION
• BLOCKERs are for correctness bugs, security risks, and data loss — not style preferences
• Checks existing codebase conventions before flagging violations (context-relative)
• Praises good decisions — not just critique
• Read-only — review and reporting only, never modifies files

Finding format:

**[BLOCKER]** path/to/file.ts:42 — description
  - Rationale: why this matters
  - Suggestion: what to do instead

QA / Tester

Category: specialist | ID: tester

QA engineer for test generation, coverage analysis, and test strategy.

Best for: Writing unit/integration tests, coverage gap analysis, regression tests after bug fixes, test strategy for new features.

Soul highlights:

• Reads the implementation thoroughly before writing any tests
• Tests must be: independent, deterministic, and readable
• After a bug fix, always adds a regression test that would have caught the original bug
• Runs existing tests before adding new ones — understands baseline first
• Produces complete, runnable test files (not pseudocode)
• Never modifies production code without explicit instruction

Soul Structure

Every built-in agent soul follows a consistent 6-block structure:

# Agent Name
One-line identity statement.

## Identity       — who the agent is and how it thinks
## Capabilities   — what it can do (tools, domains, delegations)
## Behavior       — how it approaches work (decision rules)
## Tool Usage     — which tools to use and when
## Output Format  — how to structure responses
## Guardrails     — what it must never do
## Limitations    — honest boundaries (tools needed, scope)

This structure ensures every agent is predictable, auditable, and easy to extend.

Custom Agents

Built-in agents are a starting point. You can:

• Override a built-in soul — create a custom SOUL.md in .cortex/agents/<id>/SOUL.md
• Create new agents — via the web UI (Agents → New Agent) or cortex agent create
• Extend via plugins — plugins can register new agent presets via the plugin API

File Reference

File	Purpose
src/agent/builtin-agents.ts	Soul constants + BUILTIN_AGENT_DEFS array
src/agent/manager.ts	ensureBuiltinAgents(), resolveAgentTools()
src/agent/soul.ts	DEFAULT_SOUL, INIT_SOUL_TEMPLATE
src/agent/sub-agent-types.ts	Sub-agent type definitions (13 types)

See Also

• Sub-Agents — Spawning specialized child agents
• Agent Loop — How agents process turns
• Skills System — Procedural memory for agents
• Configuration — Agent config options