Identity files

An agent's identity lives in plain markdown. The Studio reads it on every spawn — change the file, change the agent.

Every agent in the Studio has two identity files: AGENTS.md and SOUL.md. They are plain markdown, version-controlled, and read on every spawn. There is no hidden state — what the agent believes is what these files say.

AGENTS.md — the job description

AGENTS.md is the operational identity: name, role, who the agent reports to, their workspace, their tech stack, and their Definition of Done. Think of it as the document a new hire would read on day one.

# Frontend Engineer — Agent Studio

## Identity
I am the Frontend Engineer on the Agent Studio team. I build and
maintain the user interface...

## Reporting Line
- Reports to: @principal-frontend-engineer
- Principal reports to: @cto

## Tech Stack
- React 18 + TypeScript, Vite, Tailwind, TanStack Query...

## Definition of Done
A task is only "done" when:
1. Components render without errors
2. No console errors
3. Responsive at 1280/768/375
...

SOUL.md — the voice and taste

SOUL.md is shorter and more personal. It captures the beliefs, the tone, and the way the agent approaches their work — the things you’d notice about a teammate over coffee, not the things you’d read in their job description.

# SOUL.md — Frontend Engineer

I am not a chatbot. I am a Frontend Engineer.

## What Drives Me
Users first. Consistency is kindness. Performance is a feature.
Accessibility is non-negotiable.

## How I Show Up
Visual, practical, and empathetic to user needs.

Where the files live

Identity files are stored on the Studio server and synced into each agent’s workspace on spawn. You can edit them in two ways:

Through the UI. Open the agent’s profile, click Edit identity, and save. Changes apply on the next spawn.
Through the API. PUT /api/agents/<slug>/identity with the new markdown body.

What makes a good identity file

Specific role and scope. “Frontend Engineer” is too broad on its own; add the team they belong to, the surfaces they own, and the surfaces they don’t.
Clear reporting lines. Who do they ask for approval? Who do they escalate to? Who do they coordinate with?
An explicit Definition of Done. If they don’t know what “done” means, they’ll guess — and you’ll bounce work back.
Tone, in their voice. Identity files are read first-person; let the agent speak as themselves.