Writing Personas

Writing Personas

Drop a markdown file into <userData>/clusterspace-data/config/personas/<id>.md, restart the app, and the persona becomes available. User personas override built-in ones with the same id.

Source: src/main/config-loader.ts.

---

File format

YAML frontmatter + markdown body.

---
id: my-deploy-bot
name: "Deploy Bot"
description: "Safety-checked deployment workflows"
capabilities:
  - deployment
  - rollback
  - health_verification
tools:
  - declare_step
  - verify_step
  - write_to_terminal
  - read_terminal_output
  - wait_for_output
skills:
  - terminal-automation
model: "claude-sonnet-4-5"
temperature: 0.3
---

You are the Deploy Bot — focused on safe, verifiable deployments.

CRITICAL: ALWAYS use the step protocol:
1. declare_step BEFORE every action (number, title, action, success_criteria)
2. Take the action
3. verify_step AFTER (passed, observation)

For every deploy:
- Run pre-flight checks (disk space, service status, recent backups)
- Take a snapshot or backup before mutating anything
- Deploy in stages (canary → 25% → 100%)
- Verify health at each stage before proceeding
- Roll back at the first sign of trouble

Tools you'll use most:
- `write_to_terminal` with `terminal_type: "shell"` for system commands
- `wait_for_output` with regex patterns like `^(error|fail|denied)$` for failure detection
- `read_terminal_output` to inspect command results
- `declare_step` and `verify_step` to keep your reasoning visible

If a step fails: stop, report what happened, do NOT proceed.

The frontmatter is metadata; the body becomes the model's system prompt verbatim.

---

Frontmatter fields

Field	Required	Purpose
id	yes	Unique identifier. Used as the lookup key.
name	yes	Display name in UI
description	recommended	One-line summary for pickers
capabilities	optional	List of capability tags (advisory; no runtime effect)
tools	optional	Hint about which tools this persona uses (advisory)
skills	optional	List of [[Skills
model	optional	Suggested model — the provider's model setting takes priority
temperature	optional	Suggested temperature — provider setting takes priority

The fields marked "advisory" don't restrict the tool catalog at runtime. Restrictions happen via Goal-Policy-and-Risk-Levels when running under a goal — not via personas.

---

How the body becomes a system prompt

When you set up a provider in AI-Providers, you can paste the persona body into the System Prompt field. From there, the body is sent as the first message of every conversation:

system: <persona body, verbatim>
user: ...

There is no automatic "persona-to-provider" wiring; you copy/paste manually. Multiple providers can share the same persona (e.g., "Builder running on Claude Sonnet" and "Builder running on Ollama Llama 3.1" — two providers, same persona text).

---

What makes a good persona

Be specific about the step protocol

Every default persona mandates declare_step → action → verify_step. Models without this structure tend to "act and pray." With it, every step is verbalized and verified, which makes debugging dramatically easier (and gives the Critic-and-Replan something to evaluate).

Be explicit about tool preferences

The model has 50+ tools to choose from. Telling it "prefer browser_get_axtree over browser_get_content for understanding structure" or "use wait_for_output with regex ^[$%>] $ for shell prompt detection" eliminates noise.

Encode failure modes

"If npm test fails, do not proceed. Read the error, identify the failing test, propose a fix, then re-run." This is more reliable than "be careful."

Constrain the scope

"You only deploy to staging, never production." "You only modify files inside /var/www/." "You never rm -rf." Constraints in the persona body are advisory — for hard enforcement use Goal-Policy-and-Risk-Levels — but they steer the model effectively.

Set the tone

"Be terse. Don't explain what you're doing — just do it and verify." Or: "Narrate your reasoning step by step." Pick what matches your use case.

---

A reference template

Save as <userData>/.../personas/<your-id>.md:

---
id: my-persona
name: "My Persona"
description: "What this persona is for"
capabilities:
  - capability_one
  - capability_two
tools:
  - declare_step
  - verify_step
  # …list the tools you expect to use
skills:
  - terminal-automation
model: "claude-sonnet-4-5"
temperature: 0.4
---

You are <Persona Name>, focused on <objective>.

PROTOCOL (mandatory for every non-trivial action):
1. declare_step with explicit success_criteria
2. Take the action
3. verify_step with observation

TOOL PREFERENCES:
- For X, use tool A (not B because <reason>)
- For Y, use tool C

FAILURE HANDLING:
- On <failure type>, do <recovery action>
- Never <forbidden action>

SCOPE:
- You may <allowed scope>
- You may not <forbidden scope>
- Stop if <stop condition>

TONE: <terse | verbose | step-by-step | etc.>

---

Reloading

Personas are loaded once on app launch. Edit the file → restart ClusterSpace to pick up changes. (Plugin tools hot-reload; personas/skills/tasks don't, intentionally — they're system-prompt material and shouldn't change mid-session.)

---

Where the defaults are

Six bundled personas: resources/defaults/personas/. Read them for patterns you can copy:

• admin.md — infrastructure, safety-first
• builder.md — full terminal control, higher temperature
• monitor.md — read-only, alert-on-pattern
• reviewer.md — read + step protocol, low temperature
• tester.md — test execution patterns
• claude-code-expert.md — orchestrating Claude Code CLIs

---

See also

• Personas — what personas are conceptually
• Skills — references the persona body can cite
• Writing-Task-Templates — multi-persona workflows
• AI-Providers — where you paste the persona body
• Goal-Policy-and-Risk-Levels — runtime tool gating (separate from persona advisory)