Personas

Personas

A persona is a named bundle of system prompt + temperature + allowed tools + skill references that shapes how the AI behaves. Six personas ship as defaults; you can author your own by dropping markdown files into your config directory.

Source: src/main/config-loader.ts. Defaults: resources/defaults/personas/. User overrides: <userData>/clusterspace-data/config/personas/.

---

How a persona gets applied

Personas are configured per-AI-provider — not switched mid-conversation. When you create a provider, you can paste a persona's body into its systemPrompt field, or just let the default 700-line system prompt run.

If you want to switch personas at runtime, set up multiple providers (one per persona) and switch between them via AI-Providers.

There is no set_persona tool — that's an intentional design decision to keep persona application predictable.

---

The 6 defaults

admin — Infrastructure & deployments

• Temperature: 0.4 (more deterministic)
• Capabilities: system_administration, deployment_management, infrastructure_control, monitoring_setup
• Tools: declare_step, verify_step, create_workspace, restart_terminal, write_to_terminal (with safety patterns), read_terminal_output, browser (limited)
• Use for: deploys, system health, infrastructure changes

builder — Code & builds

• Temperature: 0.7 (more creative)
• Capabilities: code_generation, terminal_control, file_modification, build_management
• Tools: Full terminal control, browser tools, step protocol
• Use for: writing code, running builds, fixing bugs, refactoring

monitor — Watching & alerting

• Temperature: 0.2 (very deterministic)
• Capabilities: log_analysis, health_monitoring, alert_detection, performance_tracking
• Tools: Mostly read-only — read_terminal_output, wait_for_output, browser_get_content
• Use for: tailing logs, health checks, regression watching

reviewer — Code review & quality

• Temperature: 0.3
• Capabilities: code_review, quality_analysis, security_review, standards_enforcement
• Tools: Read + step protocol; minimal write
• Use for: PR review, security audit, style enforcement

tester — Test execution

• Temperature: 0.3
• Capabilities: test_execution, test_analysis, coverage_tracking, regression_testing
• Tools: Test commands, read output, file uploads (browser_set_files)
• Use for: running test suites, e2e tests, validation

claude-code-expert — Orchestrating Claude Code CLIs

• Temperature: 0.5
• Capabilities: claude_code_interaction, long_running_commands, ai_orchestration, code_review
• Tools: Long-timeout reads, write_to_terminal with terminal_type="claude_code"
• Use for: when one or more panes are running the Claude Code CLI and you want a meta-orchestrator coordinating them

All six mandate the step protocol (declare → verify) in their bodies.

---

Persona file format

YAML frontmatter + markdown body. Example (builder.md):

---
id: builder
name: "Builder"
description: "Writes code, runs builds, and manages development tasks"
capabilities:
  - code_generation
  - terminal_control
  - file_modification
  - build_management
tools:
  - declare_step
  - verify_step
  - write_to_terminal
  - read_terminal_output
  - poll_terminal_status
  - wait_for_output
  - list_panes
  - capture_screenshot
skills:
  - terminal-automation
model: "claude-sonnet-4-5"
temperature: 0.7
---

You are the Builder agent — focused on writing code and managing builds.

ALWAYS use the step protocol:
1. declare_step before any non-trivial action
2. Take the action
3. verify_step after, with observation

When running build commands…

The frontmatter fields are advisory metadata; only the body becomes the system prompt the model actually sees. The tools field hints at intent but doesn't restrict the tool catalog (the model can call any registered tool — restrictions happen via Goal-Policy-and-Risk-Levels at runtime).

For the full authoring guide, see Writing-Personas.

---

Where do skills fit?

The skills field lists references to Skills. Skills aren't programmatically injected into the prompt — they're docs personas refer to. If you want a skill to actually be read by the model, either:

1. Inline the skill content directly into the persona's body, or
2. Author a tool that returns the skill markdown when the model asks for it (see Plugin-Authoring)

---

Loading order

1. Built-in defaults loaded from resources/defaults/personas/ (bundled with the app)
2. User overrides loaded from <userData>/clusterspace-data/config/personas/
3. User overrides win on name collision — drop <userData>/.../personas/builder.md and yours replaces the default

Reload requires app restart. (Tools hot-reload; personas/skills/tasks don't.)

---

See also

• Writing-Personas — full authoring guide
• Skills — what skills are and how personas reference them
• Task-Templates — multi-persona workflows
• AI-Providers — where you paste the persona body into a provider