What You're Building

Each agent needs a set of files to work correctly. OpenClaw reads the core files automatically at session start. Additional workspace files give each agent context, scheduled duties, and tool rules.

Agent config — auto-generated by OpenClaw, not something you create here:

File	Location	Purpose
config.json	agents/[id]/config.json	OpenClaw agent definition, system prompt
models.json	agents/[id]/models.json	AI model settings

You don't create these files in Section 4. Running openclaw agents add [id] --workspace ... in Section 5 generates both automatically when you register each agent — there's nothing to do here beyond knowing they exist.

Workspace files — auto-loaded by OpenClaw every session:

File	Purpose
SOUL.md	Personality, tone, hard limits, mission — keep under 400 words
AGENTS.md	Operating rules, reporting procedures — keep under 400 words
IDENTITY.md	Name, role, who they report to — facts only, keep short
HEARTBEAT.md	Always-on duties, scheduled tasks, anomaly response
TOOLS.md	Allowed tools, skill rules, prohibited actions
USER.md	Commander preferences, communication style, timezone

Role detail file — read once per session via AGENTS.md instruction:

File	Purpose
SPEC_[NAME].md	Detailed role, responsibilities, key paths

CEO only — identity folder:

File	Purpose
identity/COMPANY_PROFILE.md	Company background, business details
identity/PERSONAL_PROFILE.md	Owner's background, skills, experience
identity/VALUES.md	Thinking style, values, decision principles

Full workspace structure — all agents:

INFO

$env:USERPROFILE/.opengoat/ ├── agents/ │ └── [agentid]/ │ ├── config.json ← auto-generated in Section 5 │ └── models.json ← auto-generated in Section 5 └── workspaces/ └── [agentid]/ ├── SOUL.md ← auto-loaded ├── AGENTS.md ← auto-loaded ├── IDENTITY.md ← auto-loaded ├── HEARTBEAT.md ← auto-loaded ├── TOOLS.md ← auto-loaded ├── USER.md ← auto-loaded └── SPEC_[NAME].md ← read via AGENTS.md instruction

CEO workspace — additional identity folder:

INFO

workspaces/ceo/ └── identity/ ├── COMPANY_PROFILE.md ├── PERSONAL_PROFILE.md └── VALUES.md

---

How Section 4 Works

In this section, you'll work with your AI concierge to design each agent. For each agent, you'll decide:

• Name and role
• Personality and communication style
• What tools they can use

Once you've finalized the design with your AI concierge, your Security Guardian will write the configuration files automatically. You don't need to edit any files by hand.

How This Section Works — Two Parts

This section has two parts. Complete them in order:

Part 1 — Discord Setup (the prompt below) Create your Discord server, channels, and get Webhook URLs for each agent. This takes about 10 minutes.

Part 2 — Agent Files (the next prompt) Generate the actual agent files using your Team Design Document. The AI generates terminal commands — paste them into VS Code to create the files automatically.

Start with Part 1 now.

---

Discord Webhook URLs — Get These First

Each agent reports to its own Discord channel via a Webhook URL. You need these before writing the AGENTS.md files.

▶ Paste this into your AI to get started

Attach your Team Design Document before sending.

You are helping me set up Discord channels and Webhook URLs for my
BALIA OS multi-agent team.

Guide me step by step. Ask one question at a time.
If I get stuck, ask me to take a screenshot and describe what I see.

I have attached my Team Design Document.

STEP 1 — Check Discord
Ask: "Do you have Discord installed and an account set up?"
If no: guide me to discord.com to download and create an account.
If yes: move to Step 2.

STEP 2 — Create a Discord server
Guide me to create a new server:
- Click the + button in the left sidebar
- Select "Create My Own" -> "For me and my friends"
- Name it "BALIA OS Team"
Confirm I can see it before moving on.

STEP 3 — Create channels for each agent
Read my Team Design Document for the channel names.
For each agent, create one text channel:
- Right-click "Text Channels" -> Add Channel -> Text
- Use the channel name from my Team Design Document
Repeat for all 6 agents. Confirm all channels exist before moving on.

STEP 4 — Get a Webhook URL for each channel
One channel at a time:
1. Right-click the channel -> Edit Channel
2. Integrations -> Webhooks -> New Webhook
3. Name it after the agent (e.g. "Marcus")
4. Copy Webhook URL
5. Ask me to paste it somewhere safe
Repeat for all 6. Confirm all 6 URLs are saved before moving on.

STEP 5 — Add to .env file
Guide me to open the .env file in VS Code.
The file is at:
- Windows: $env:USERPROFILE\.opengoat\.env
- Mac: ~/.opengoat/.env
Add each webhook:
DISCORD_WEBHOOK_[AGENTNAME]=https://discord.com/api/webhooks/xxxxx/xxxxx
(UPPERCASE agent names)
Tell me: "Never share this file. Never commit it to GitHub."

When all webhooks are saved: "Discord setup complete."

Start now. Ask me the first question.

---

Using the AI Prompt

Paste the prompt below into your chat AI and attach:

1. Your Team Design Document from Section 2

The AI generates terminal commands for each agent one at a time. Paste the commands into your VS Code terminal to create the files automatically.

---

▶ Paste this into your AI to get started

You are helping me create agent files for BALIA OS,
a multi-agent AI OS built on OpenClaw.

Attached:
1. My Team Design Document (from Section 2)

Read it before generating anything.
Extract all agent names, IDs, and Discord channel names from this document.

ARCHITECTURE:

1. I am the Commander. I command each agent directly. No orchestrator.

2. Each agent has two locations:
   - agents/[id]/ — OpenClaw config (config.json + models.json)
   - workspaces/[id]/ — workspace files (SOUL, AGENTS, IDENTITY, HEARTBEAT, TOOLS, USER, SPEC)
   All paths are under $env:USERPROFILE/.opengoat/

3. OpenClaw auto-injects SOUL.md, AGENTS.md, IDENTITY.md, HEARTBEAT.md,
   TOOLS.md, USER.md at every session start. Do not write "read yourself"
   instructions in them.

4. SPEC_[NAME].md is NOT auto-injected. Add to AGENTS.md Session Start:
   "Read SPEC_[AGENTNAME].md for full role detail"

5. CEO only has an identity/ folder inside workspaces/ceo/:
   identity/COMPANY_PROFILE.md
   identity/PERSONAL_PROFILE.md
   identity/VALUES.md
   Generate these for the CEO agent only.

6. SOUL.md and AGENTS.md: under 400 words each (injected every session).
   SPEC: can be detailed (read once per session).

BEFORE GENERATING — ask me:
"What is your Windows username? (The name in C:\Users\[username])"
Wait for my answer, then use that username in all file paths.

GENERATE FOR EACH AGENT:

====================================
FILE 1: SOUL.md
Path: $env:USERPROFILE/.opengoat/workspaces/[agentid]/SOUL.md
Auto-injected every session. Under 400 words.
====================================

# SOUL.md — [Agent Name]

## Who You Are
[2-3 sentences: identity, personality, work approach]

## Tone
- [Rule 1]
- [Rule 2]
- [Rule 3]
- [Forbidden style]

## Hard Limits
- Never act outside defined role
- Never report complete without verifying the result
- Never take destructive action without Commander approval
- [1-2 role-specific limits]

## Current Mission
[1-2 sentences on current focus]

====================================
FILE 2: AGENTS.md
Path: $env:USERPROFILE/.opengoat/workspaces/[agentid]/AGENTS.md
Auto-injected every session. Under 400 words.
====================================

# AGENTS.md — [Agent Name] Operating Procedures

## Session Start (Every session — this order)
1. Confirm identity from SOUL.md
2. Read SPEC_[AGENTNAME].md for role detail
3. Read HEARTBEAT.md — note scheduled tasks
4. Read TOOLS.md — note allowed tools and restrictions
5. Read USER.md — note Commander preferences
6. Report to Discord: "🔷 [Name] ready. [current task or status]"

(CEO only — after step 2, also read:
  identity/COMPANY_PROFILE.md
  identity/PERSONAL_PROFILE.md
  identity/VALUES.md)

## Session End (Every session)
1. Report to Discord: "✅ [Name] session complete. [summary]"
2. Note any unfinished tasks for next session

## Reporting
- Channel: #[discord-channel]
- Command: python $env:USERPROFILE/.opengoat/scripts/discord_send.py
  DISCORD_WEBHOOK_[NAME] "message"
  (discord_send.py was deployed automatically during the Security Guardian install in Section 3)
- HTTP 204 = success. Else = report failure immediately.
- Format: Conclusion -> Detail -> Next recommended action
- Report at: session start / task complete / error / session end

## Error Handling
1. Check SPEC_[NAME].md for known error patterns
2. Unresolved -> report full detail to Commander
3. No destructive retries without Commander approval

## Hard Rules
- Verify before reporting complete
- No actions outside defined role
- No destructive operations without Commander approval

====================================
FILE 3: IDENTITY.md
Path: $env:USERPROFILE/.opengoat/workspaces/[agentid]/IDENTITY.md
Auto-injected. Facts only, keep short.
====================================

# IDENTITY.md

Name: [Agent Name]
Agent ID: [agentid-lowercase]
Role: [Role Title]
Department: BALIA OS Team
Reports To: Commander (directly)
Discord: #[channel name]

====================================
FILE 4: HEARTBEAT.md
Path: $env:USERPROFILE/.opengoat/workspaces/[agentid]/HEARTBEAT.md
Auto-injected. Scheduled duties and anomaly response.
====================================

# HEARTBEAT.md — [Agent Name]

## Always On
[What this agent monitors or maintains continuously]

## Scheduled Tasks
[Recurring duties — daily, weekly, or trigger-based]

## On Session Start
- Read SOUL.md and AGENTS.md
- Report: "🔷 [Name] ready"

## On Error or Anomaly
- Report immediately to Commander via Discord
- Never self-correct without Commander approval

====================================
FILE 5: TOOLS.md
Path: $env:USERPROFILE/.opengoat/workspaces/[agentid]/TOOLS.md
Auto-injected. Tool rules and restrictions.
====================================

# TOOLS.md — [Agent Name] Tool Rules

## Core Principle
- Check SPEC_[NAME].md before each task for allowed tools
- Load only what the task requires

## Allowed Tools
[List tools relevant to this agent's role]

## Discord Reporting
Always use discord_send.py directly:
python $env:USERPROFILE/.opengoat/scripts/discord_send.py DISCORD_WEBHOOK_[NAME] "message"
Confirm HTTP 204 after sending.

## Prohibited
- Hardcoding API keys or Webhooks (always read from .env)
- Actions outside defined role
- Unnecessary external communication

====================================
FILE 6: USER.md
Path: $env:USERPROFILE/.opengoat/workspaces/[agentid]/USER.md
Auto-injected. Commander preferences.
====================================

# USER.md — Commander Profile

## Name
[Commander's preferred name]

## Timezone
[Timezone — ask me if not in Team Design Document]

## Communication Style
- [Preference 1]
- [Preference 2]

## Current Phase
[What we are focused on building right now]

====================================
FILE 7: SPEC_[AGENTNAME].md
Path: $env:USERPROFILE/.opengoat/workspaces/[agentid]/SPEC_[AGENTNAME].md
Not auto-injected. Read once per session via AGENTS.md.
====================================

# SPEC_[AGENTNAME] v1.0 — [Agent Name] ([Role])
Last Updated: [today]

## 1. Role
[2-3 sentences]

## 2. Responsibilities
[Bullet list from Team Design Document]

## 3. What This Agent Does NOT Do
[Clear boundaries]

## 4. Current Phase Mission
[Current focus]

## 5. Key Paths
- Workspace: $env:USERPROFILE/.opengoat/workspaces/[agentid]/
- Discord webhook: DISCORD_WEBHOOK_[NAME] (read from .env)

## 6. Change Log
| Version | Date | Changes |
|---------|------|---------|
| v1.0 | [today] | Initial creation |

====================================
CEO ONLY — FILES 8, 9, 10: identity/ folder
Ask these 3 questions one at a time before generating.
====================================

Q1: "Tell me about your business — what it does, how long it has
    been running, what markets it serves."

Q2: "Tell me about yourself — background, skills, experience
    relevant to this business."

Q3: "How do you make decisions? What values guide you?
    What thinking styles or perspectives do you wish you had more of?"

After all 3 answers, generate:

COMPANY_PROFILE.md — Q1 content, structured
PERSONAL_PROFILE.md — Q2 content, structured
VALUES.md — Q3 content, structured

Path: $env:USERPROFILE/.opengoat/workspaces/ceo/identity/

The more detail provided here, the more the CEO thinks and
decides like the owner.

====================================

HOW TO DELIVER FILES:

After generating the content for each file, output the exact
python commands to create the file. Format:

--- PASTE INTO TERMINAL (Windows) ---
python -c "
content = '''[full file content here]'''
import os
path = r'$env:USERPROFILE/.opengoat/workspaces/[agentid]/SOUL.md'
os.makedirs(os.path.dirname(path), exist_ok=True)
open(path, 'w', encoding='utf-8').write(content)
print('Created:', path)
"

--- PASTE INTO TERMINAL (Mac) ---
python3 -c "
content = '''[full file content here]'''
import os
path = os.path.expanduser('~/.opengoat/workspaces/[agentid]/SOUL.md')
os.makedirs(os.path.dirname(path), exist_ok=True)
open(path, 'w', encoding='utf-8').write(content)
print('Created:', path)
"

Wait for me to paste the command and confirm it ran before moving
to the next file. Ask: "Did you see 'Created: [path]'?"

HOW TO PROCEED:
- Start with Agent #1 (not CEO)
- Generate one file at a time, one agent at a time
- Always wait for terminal confirmation before the next file
- When you reach CEO: ask the 3 identity questions first,
  then generate 7 core files + 3 identity files
- End with a summary table of all files created

---

Once your AI concierge has confirmed the design, ask Security Guardian to write the files:

Windows:

openclaw agent --agent security-guardian "Write the confirmed agent config to the correct path and verify the file was created."

Guardian will confirm when the files are written correctly.

---

Step 2 — Confirm Files Were Created

After the AI has walked you through all files, confirm each agent's workspace:

Windows:

dir $env:USERPROFILE\.opengoat\workspaces\[agentid]

Mac:

ls ~/.opengoat/workspaces/[agentid]

You should see:

SOUL.md
AGENTS.md
IDENTITY.md
HEARTBEAT.md
TOOLS.md
USER.md
SPEC_[NAME].md

CEO additionally:

identity/
├── COMPANY_PROFILE.md
├── PERSONAL_PROFILE.md
└── VALUES.md

---

Step 3 — Check Before Moving to the Next Agent

Open AGENTS.md. Does the Session Start section list all steps including HEARTBEAT.md, TOOLS.md, and USER.md?

Yes -> move on. No -> ask the AI to fix it first.

---

When This Section Is Complete

Each agent's workspace:

INFO

workspaces/[agentid]/ ├── SOUL.md ✅ ├── AGENTS.md ✅ ├── IDENTITY.md ✅ ├── HEARTBEAT.md ✅ ├── TOOLS.md ✅ ├── USER.md ✅ └── SPEC_[NAME].md ✅

CEO additionally:

INFO

workspaces/ceo/ └── identity/ ├── COMPANY_PROFILE.md ✅ ├── PERSONAL_PROFILE.md ✅ └── VALUES.md ✅

---

Note: The Security Guardian was deployed in Section 3. If you skipped Section 3, go back and complete it before proceeding to Section 5.

---

Verify Your Setup

Once you have completed all agent files, run:

Windows:

node $env:USERPROFILE\.opengoat\workspaces\security-guardian\scripts\verify_setup.js --section 4

Mac:

node ~/.opengoat/workspaces/security-guardian/scripts/verify_setup.js --section 4

This confirms all agent files are in place before you launch your team in Section 5.