Section 4: Creating Your Agent Files

What You're Building

Each agent needs a set of files to work correctly. OpenClaw reads the core files automatically at session start. The cassette files give each agent a domain to work in and the memory to continue where they left off.

Core 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

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

File	Purpose
`SPEC_[NAME].md`	Detailed role, responsibilities, cassette system rules

Cassette files — read at session start after core files:

File	Purpose
`cassettes/ACTIVE_MODE.txt`	One word: the active mode name
`cassettes/[mode]/SKILL_[MODE].md`	What this agent can do in this mode
`cassettes/[mode]/WORKFLOW_[MODE].md`	Step-by-step procedures for this mode
`cassettes/[mode]/LIVE_LEDGER_[MODE].md`	Progress, incomplete tasks, next actions
`cassettes/[mode]/KNOWLEDGE_[MODE].md`	Accumulated successes, failures, learning

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

~/.openclaw/workspace-[agentid]/ ├── SOUL.md ├── AGENTS.md ├── IDENTITY.md ├── SPEC_[NAME].md └── cassettes/ ├── ACTIVE_MODE.txt ← created now, filled in Section 6 └── archive/ ← LIVE_LEDGER and KNOWLEDGE overflow

CEO workspace — additional identity folder:

INFO

~/.openclaw/workspace-ceo/ ├── SOUL.md ├── AGENTS.md ├── IDENTITY.md ├── SPEC_CEO.md ├── identity/ │ ├── COMPANY_PROFILE.md │ ├── PERSONAL_PROFILE.md │ └── VALUES.md └── cassettes/ ├── ACTIVE_MODE.txt └── archive/

The cassette mode folders (SKILL, WORKFLOW, LIVE_LEDGER, KNOWLEDGE) are created in Section 6 when you build your first cassette.

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. Paste the completed files into VS Code.

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 and 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.

How This Section Works

Paste the prompt below into Claude, ChatGPT, or Gemini and attach:

Your Team Design Document from Section 2

The AI generates all files for each agent one at a time, confirming before moving to the next.

▶ 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 CEO. I command each agent directly. No orchestrator.

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

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

4. Every agent has a cassette system:
   cassettes/ACTIVE_MODE.txt: one word, the active mode
   cassettes/[mode]/SKILL_[MODE].md
   cassettes/[mode]/WORKFLOW_[MODE].md
   cassettes/[mode]/LIVE_LEDGER_[MODE].md
   cassettes/[mode]/KNOWLEDGE_[MODE].md
   Mode folders are built in Section 6.
   For now: create cassettes/ folder and empty ACTIVE_MODE.txt only.

5. CEO only has an identity/ folder:
   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).

7. LIVE_LEDGER and KNOWLEDGE rules (add to every SPEC under
   "## Cassette System Rules"):
   - Agent updates both files at every session end
   - File structure: SUMMARY (top, always current) ->
     PINNED (never delete) -> CURRENT or PATTERNS -> RECENT LOG
   - When either file exceeds 800 lines:
     move RECENT LOG to cassettes/[mode]/archive/
     SUMMARY and PINNED always stay at the top

GENERATE FOR EACH AGENT:

====================================
FILE 1: SOUL.md
~/.openclaw/workspace-[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
~/.openclaw/workspace-[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 cassettes/ACTIVE_MODE.txt — note the active mode
4. Load cassettes/[mode]/SKILL_[MODE].md
5. Load cassettes/[mode]/WORKFLOW_[MODE].md
6. Read cassettes/[mode]/LIVE_LEDGER_[MODE].md — resume from last session
7. Read cassettes/[mode]/KNOWLEDGE_[MODE].md — apply accumulated learning
8. Report to Discord: "🔷 [Name] ready. Mode: [mode]. [current task]"

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

## Session End (Every session)
1. Update LIVE_LEDGER_[MODE].md:
   - Refresh SUMMARY (3-5 line overview)
   - Update CURRENT (today's progress, next task)
   - Append to RECENT LOG
   - If over 800 lines: move RECENT LOG to cassettes/[mode]/archive/
2. Update KNOWLEDGE_[MODE].md:
   - Refresh SUMMARY
   - Add new patterns to PATTERNS
   - Append to RECENT
   - If over 800 lines: move RECENT to cassettes/[mode]/archive/
3. Report to Discord: "✅ [Name] session complete. [summary]"

## Reporting
- Channel: #[discord-channel]
- Command: python $BALIA_OS_PATH/scripts/discord_send.py
  DISCORD_WEBHOOK_[NAME] "message"
  (BALIA_OS_PATH is set in the .env file from 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 KNOWLEDGE_[MODE].md for similar past cases
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
~/.openclaw/workspace-[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: SPEC_[AGENTNAME].md
~/.openclaw/workspace-[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: ~/.openclaw/workspace-[agentid]/
- Discord webhook: DISCORD_WEBHOOK_[NAME]
- Cassettes: ~/.openclaw/workspace-[agentid]/cassettes/

## 6. Cassette System Rules
- Read ACTIVE_MODE.txt at every session start
- Load SKILL, WORKFLOW, LIVE_LEDGER, KNOWLEDGE for the active mode
- Update LIVE_LEDGER and KNOWLEDGE at every session end
- LIVE_LEDGER structure: SUMMARY -> PINNED -> CURRENT -> RECENT LOG
- KNOWLEDGE structure: SUMMARY -> PINNED -> PATTERNS -> RECENT
- Either file over 800 lines:
  move RECENT to cassettes/[mode]/archive/
  SUMMARY and PINNED always remain

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

====================================
CEO ONLY — FILES 5, 6, 7: 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

Location: ~/.openclaw/workspace-ceo/identity/

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

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

HOW TO PROCEED:
- Start with Agent #1 (not CEO)
- Show all files completely, no truncation
- Show exact save paths after each agent
- Ask: "Ready for the next agent?" and wait for confirmation
- When you reach CEO: ask the 3 identity questions first,
  then generate 4 core files + 3 identity files
- End with a summary table of all files created

Step 2 — Save Each File in VS Code

For each agent:

Open the workspace: code ~/.openclaw/workspace-[agentid]
Right-click in the left panel -> New File -> paste content -> save
Create cassettes folder:

Windows:

mkdir C:\Users\%USERNAME%\.openclaw\workspace-[agentid]\cassettes
mkdir C:\Users\%USERNAME%\.openclaw\workspace-[agentid]\cassettes\archive

Mac:

mkdir -p ~/.openclaw/workspace-[agentid]/cassettes/archive

Create empty ACTIVE_MODE.txt inside cassettes (leave blank — filled in Section 6)

CEO only — create identity folder:

Windows: mkdir C:\Users\%USERNAME%\.openclaw\workspace-ceo\identity

Mac: mkdir ~/.openclaw/workspace-ceo/identity

Step 3 — Check Before Moving to the Next Agent

Open AGENTS.md. Does the Session Start section list all 8 steps including ACTIVE_MODE.txt, LIVE_LEDGER, and KNOWLEDGE?

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

When This Section Is Complete

Each agent's workspace:

INFO

workspace-[agentid]/ ├── SOUL.md ✅ ├── AGENTS.md ✅ ├── IDENTITY.md ✅ ├── SPEC_[NAME].md ✅ └── cassettes/ ├── ACTIVE_MODE.txt ✅ (empty — filled in Section 6) └── archive/ ✅ (empty — used at 800 lines)

CEO additionally:

INFO

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

Move to Section 5 to launch your team.

Deploy the Security Agent

Your agent files are complete.

There is one more agent in BALIA OS: the Security Agent (security).

This agent is pre-configured by BALIA. Do not change its name, personality, or paths. Doing so will break the integration with your other agents.

Download and Run the Installer

Step 1 — Download the installer

In your VS Code terminal:

Windows:

powershell

Invoke-WebRequest -Uri "https://balia-os-guide.vercel.app/scripts/install_core_pack.py" -OutFile install_core_pack.py

Mac / Linux:

bash

curl -o install_core_pack.py https://balia-os-guide.vercel.app/scripts/install_core_pack.py

Step 2 — Have your agent run it

openclaw agent --agent [your-agent-id] "Please run the following:
python install_core_pack.py --lang en
(The token will be read automatically from your .env file)
Report to Discord when done."

Your agent ID is the value of AGENT_ID in your .env file. The token is read automatically from BALIA_TOKEN in your .env file.

Your agent will autonomously:

Authenticate your token
Download the security agent files
Deploy to ~/.opengoat/agents/security/
Report "Security agent deployed" to Discord

⚠️ Important: Do not change the security agent's ID, name, or folder path. Other configuration files reference this agent directly. Changing it will break the skill quarantine system.

Once you receive the Discord confirmation, continue to Section 5.

What You're Building ​

How This Section Works — Two Parts ​

Discord Webhook URLs — Get These First ​

▶ Paste this into your AI to get started

How This Section Works ​

▶ Paste this into your AI to get started

Step 2 — Save Each File in VS Code ​

Step 3 — Check Before Moving to the Next Agent ​

When This Section Is Complete ​

Deploy the Security Agent ​

Download and Run the Installer ​

What You're Building

How This Section Works — Two Parts

Discord Webhook URLs — Get These First

How This Section Works

Step 2 — Save Each File in VS Code

Step 3 — Check Before Moving to the Next Agent

When This Section Is Complete

Deploy the Security Agent

Download and Run the Installer