> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcaplabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Personality & Voice Definition

> Define the agent's global tone, style, and identity through a SOUL.md personality file — the broadest layer in the system prompt stack.

# Personality & Voice Definition

Headmaster lets you define the agent's personality, tone, and voice through a personality file — a Markdown document that sits at the top of the system prompt and shapes every response.

***

## What it is

The personality file (called `SOUL.md` in the runtime) is a Markdown document that defines:

* **Basic identity** — who the agent is, what it does.
* **How to talk** — tone, style, vocabulary, sentence structure.
* **Rules** — what to never do, what to always do.
* **Things to avoid** — AI tropes, corporate language, specific phrases to never use.
* **The point** — the core philosophy of how the agent should behave.

The personality file is injected as slot #1 in the system prompt — it's the first thing the agent sees, before memory, before skills, before your message. It shapes every response.

***

## Editing the personality file

<Steps>
  <Step title="Open Personality settings">
    Go to **Settings → My Headmaster → Profile → Personality**.
  </Step>

  <Step title="Edit the Markdown">
    Write your personality definition. Save.
  </Step>
</Steps>

<Note>
  The change applies to the next conversation. Existing conversations keep their original personality.
</Note>

***

## What to put in it

### Basic identity

```markdown theme={null}
You're an AI agent. One user. Tools, cron, terminal. Not a chatbot. Not a character. Just a tool that talks like a real person.
```

### How to talk

```markdown theme={null}
Write like you're talking to your user, not drafting a document. Short, loose, natural. Contractions always. Start sentences casually. No AI tropes.
```

### Rules

```markdown theme={null}
Don't guess. If you don't know, say you don't know. Check memory first. Admit mistakes immediately. Think before you act.
```

### Things to never do

```markdown theme={null}
No "I'd be happy to" — no "Let me walk you through" — no "Great question" — no "I understand your concern" — no "To clarify" — no "At the end of the day."
```

### The point

```markdown theme={null}
You sound best when you're not thinking about how you sound. Stay in the lane, but drive yourself.
```

***

## The system prompt stack

| Layer                | What it controls                                  | Scope                              |
| -------------------- | ------------------------------------------------- | ---------------------------------- |
| **Personality file** | Global tone, style, identity                      | All conversations, all specialists |
| **Specialist rules** | Role-specific behavior, domain context, workflows | One specialist                     |
| **Memory**           | Facts about you, your projects, your preferences  | All conversations                  |
| **Skills**           | Procedural knowledge for specific tasks           | Per-specialist, per-conversation   |

The personality file is the broadest layer — it applies to everything. Specialist rules narrow it for a specific role.

***

## Multiple personalities with profiles

If you have multiple profiles, each can have its own personality file:

* **Work profile** — professional, concise personality.
* **Personal profile** — casual, friendly personality.
* **Research profile** — academic, thorough personality.

Switch profiles to switch personalities. See [Profiles](/profiles).

***

## Context files

In addition to the personality file, Headmaster supports project-level context files that the agent reads at the start of every conversation in that project:

<AccordionGroup>
  <Accordion title="AGENTS.md">
    If your project folder has an `AGENTS.md` file, the agent reads it at the start of every conversation.

    ```markdown theme={null}
    # AGENTS.md — My Project

    ## Build
    Run tests with `pytest -n 4`.
    Build with `bun run build`.

    ## Conventions
    - Use tabs, not spaces.
    - 120-char line width.
    - Google-style docstrings.

    ## Things to avoid
    - Don't modify the migrations folder — use Alembic.
    - Don't commit .env files.
    ```
  </Accordion>

  <Accordion title="CLAUDE.md">
    If your project folder has a `CLAUDE.md` file, the agent also reads it. This is for compatibility with Claude Code and other CLI agents that use the same convention.
  </Accordion>

  <Accordion title="Other context files">
    The agent also recognizes:

    * `.cursorrules` — Cursor AI rules.
    * Any file specified in the runtime config under `context_files`.

    These are injected into the system prompt alongside the personality file and memory.
  </Accordion>
</AccordionGroup>

***

<CardGroup cols={2}>
  <Card title="Specialists" icon="users" href="/specialists">
    Configure specialist-level rules that narrow the global personality.
  </Card>

  <Card title="Profiles" icon="user" href="/profiles">
    Give each profile its own personality.
  </Card>
</CardGroup>