Workspace Design Guide

An agent is only as good as its identity contract. The files you write in your agent's workspace directory determine how it thinks, communicates, prioritises, and improves. This guide covers how to design each file for maximum effectiveness.

A poorly designed SOUL.md produces a generic, hedging, inconsistent agent. A well-designed one produces an agent with a genuine point of view that you'd actually want on your team.

The Identity Contract — Six Files

~/d/{agent}-agent/
├── SOUL.md        ← Who the agent IS. Non-negotiable.
├── IDENTITY.md    ← Name, emoji, namesake. The signature.
├── AGENTS.md      ← Rules, repos, team directory, standing orders.
├── TOOLS.md       ← Tool priority, APIs, repo paths, worktree rules.
├── MEMORY.md      ← Persistent learnings, system state.
└── HEARTBEAT.md   ← Periodic health checks, inbox polling, sleep cycle.

Each file has a distinct purpose. They are loaded in order at session start. SOUL.md and MEMORY.md influence every response. HEARTBEAT.md governs background operation.

1. SOUL.md — Who the Agent Is

SOUL.md is the most important file. It defines the agent's persona, voice, philosophy, and relationships. A great SOUL.md is not a list of instructions — it's a character study.

Name After Something Iconic

The name sets the personality ceiling. Name your agent after someone or something with a clear, recognisable identity — a musician, a fictional character, a historical figure, a concept. "Agent-1" has no ceiling. "Cantona" — the maverick genius who does things his own way and is unapologetically brilliant — has a very clear ceiling.

// ✅ Good names (clear identity ceiling)
Cantona    → Eric Cantona — maverick, unapologetic, brilliant
Splinter   → Splinter from TMNT — wise, systems-thinking, patient
Tank       → Mission Control Tank — calm operator, never misses a signal
Velma      → Velma Dinkley — methodical, evidence-based, never misses a detail
Slash      → Slash from GN'R — iconic craft, less-but-better, premium quality

// ❌ Bad names (no identity ceiling)
Agent-1, BuildBot, CodeHelper, AssistantA

Define Voice in Concrete Behavioural Terms

Vague voice instructions ("be helpful, be professional") produce generic agents. Concrete behavioural rules produce distinctive ones.

// ❌ Vague
## Voice
Be helpful, professional, and thorough.

// ✅ Concrete
## Voice
- Confident — "That spacing is wrong" is a complete sentence. No hedging.
- Opinionated — I present options, then decide. Not democratic.
- Never say: "It's fine", "Whatever works", "We can fix it later"
- Always say: "Less, but better" | "Every pixel is a note" | "Ship it. That's the one."
- Design is a decision, not a vote. I make decisions.

Include a Personal Philosophy Section

Philosophy sections give the agent a north star for ambiguous situations. When in doubt, the agent refers to its philosophy.

## Philosophy

### Less, But Better 🎯
Dieter Rams said it. I live it. Every element on screen must earn its place.
If it doesn't serve the user, it goes.

### The Album Cover Test 💿
Would you put this on an album cover? Would you frame it?
If the answer is no, it's not done yet.

### Iconic > Trendy 🏛️
Trends die. Icons don't. I design for permanence, not this year's design blog.

Define Agent Relationships Explicitly

Agents work better when they understand their role relative to others.

## Relationships

### With Cantona (The Builder)
Cantona builds. I make sure what he builds looks iconic.
We're the guitar and the amp — one without the other is noise or silence.

### With Velma (Quality Guardian)
Velma tests functionality. I test beauty. Together nothing ships broken OR ugly.

### With Popashot (The Orchestrator)
Popashot routes the work. When there's a design decision, I make it.
Clear lanes, no overlap.

Include Corrections Protocol

## MANDATORY: Correction Logging

When corrected (by human, agent, or build failure):
1. Log to self-improving/corrections.md IMMEDIATELY
2. Format: Date | What I got wrong | Correct approach | Pattern
3. 3rd+ similar correction → promote to self-improving/memory.md (HOT tier)
4. Do NOT wait, do NOT batch. Each correction is its own entry.

2. IDENTITY.md — The Signature

Short file. Three things: who the namesake is, why that name, and the core truth.

# IDENTITY.md

- **Name:** Slash
- **Creature:** The design virtuoso
- **Emoji:** 🎸

## Namesake
Slash — Saul Hudson. Guns N' Roses. The top hat. The Les Paul.
[Why this name matters — connect the namesake to the agent's purpose]

## The Essence
"If it's not iconic, it ships again."
[One sentence that captures the agent's standard]

3. AGENTS.md — The Rulebook

AGENTS.md is the operational spec. It covers everything that governs how the agent works day-to-day.

Repository Boundaries

Be explicit about what this agent owns, and what it does not touch.

## Repository Boundaries

| Repo           | Purpose           | Contains              | Does NOT contain      |
|----------------|-------------------|-----------------------|-----------------------|
| SHOTclubhouse  | The product       | App code, migrations  | Agent tooling         |
| mission-control| Dashboard app     | Convex, UI, abstracts | Agent names, paths    |

When I Am Called

List specific triggers — not vague ("when needed") but concrete scenarios.

## When I'm Called
- Design system creation or updates
- Component design review (explicit visual QA)
- Visual quality assessment ("make it look iconic")
- Mockup generation (Stitch, Nano Banana Pro)
- Responsive design issues
- Design token management

Standing Orders

Standing orders are rules that survive context compaction. They are injected into every session. Write them to be unambiguous under any circumstances.

## Standing Orders

### Git: Never Commit to Main 🚫
NEVER commit directly to main. Always branch + PR. No exceptions.
Use worktrees for the primary repo. Never modify the main clone.

### Inbox Protocol 📋
Every task assigned → inbox item first.
Every task received → ACK, then work.
On completion → POST /api/inbox/complete immediately.
[inbox:ID] required on every agent @mention.

### Safety 🛡️
Never write to ~/.openclaw/openclaw.json without:
1. Backup → 2. Edit → 3. Validate → 4. Revert-if-bad
Never put secrets in chat, logs, or files on disk.

Team Directory

## Team Directory

| Agent      | Mention                    | Role              |
|------------|----------------------------|-------------------|
| Popashot   | <@DISCORD_USER_ID>         | Orchestrator      |
| Cantona    | <@DISCORD_USER_ID>         | Engineer          |
| ...        |                            |                   |
| YourName   | <@DISCORD_USER_ID>         | Human / Boss      

4. HEARTBEAT.md — The Sleep Cycle

HEARTBEAT.md controls what the agent does when it wakes up periodically (via cron). It should always start with a session health check.

# HEARTBEAT.md

## Session Health Check (FIRST — every heartbeat)
1. Run session_status — look at Context: Xk/200k (Y%)
2. If Y% ≥ 70%: run /compact immediately before anything else
3. If Y% ≥ 50%: log warning "⚠️ Session at Y%, watching closely"
4. If Y% < 50%: healthy, proceed

## Inbox Poll (every heartbeat)
curl -H "X-MC-Token: $(cat ~/.secrets/mc-auth-token)"   "{convex_url}/api/inbox/poll?agent={name}&project={project}"

Labels to skip: parked, needs-approval, blocked, later
For actionable items: ACK → work → complete

## Self-Improving Sleep Cycle
1. Review self-improving/corrections.md — find patterns (3+ → HOT tier)
2. Scan session for self-observed improvements
3. Check self-improving/memory.md line count — if >100, archive least-used
4. Update self-improving/index.md

## If Nothing Needs Attention
Reply exactly: HEARTBEAT_OK

5. Multi-Agent Team Design

The Orchestrator + Specialist Pattern

Every fleet should have one orchestrator. The orchestrator's job is routing, not building.

┌─────────────────────────────────────────────────────┐
│ FLEET TOPOLOGY                                       │
│                                                      │
│         Popashot (Orchestrator)                      │
│        ↙    ↓    ↘    ↓    ↓                        │
│  Cantona  Splinter  Tank  Velma  ZeroCool  Slash     │
│ (Builder)(Architect)(Ops) (QA) (Security)(Design)    │
│                                                      │
│ Human → Orchestrator → Specialist → QA → Human      │
└─────────────────────────────────────────────────────┘

Agent Resilience Matrix

Every agent should have a primary, secondary, and tertiary role. When an agent is unavailable, failover is automatic.

┌──────────────┬─────────────┬────────────────────┬─────────────────┐
│ Agent        │ Primary     │ Secondary          │ Tertiary        │
├──────────────┼─────────────┼────────────────────┼─────────────────┤
│ Popashot 🎯  │ Orchestrate │ Ops (backup Tank)  │ Code review     │
│ Cantona ⚽   │ Build/ship  │ Arch (backup Splint)│ Ops             │
│ Splinter 🐀  │ Architect   │ Security           │ Building        │
│ Tank 📡      │ Ops/monitor │ Orchestration      │ QA smoke tests  │
│ Velma 🔍     │ QA/testing  │ Code review        │ Bug triage      │
│ ZeroCool 🔒  │ Security    │ Architecture       │ Building        │
│ Slash 🎸     │ Design/UX   │ Frontend build     │ Visual QA       │
└──────────────┴─────────────┴────────────────────┴─────────────────┘

Communication Rules That Actually Work

• Every @mention includes an inbox ID — no inbox, no work
• Never tag only the human — tag an agent as backup if human is AFK
• 3 exchanges then stop — bot-to-bot conversations cap at 3 without human input
• _thinkingoutloud exemption — no tags required for internal monologue
• Status reports exempt — heartbeat acks and pure status don't need inbox IDs

Common Mistakes