L1 — Mental Models
This section introduces the key vocabulary you'll encounter throughout #B4arena. These four concepts form the mental toolkit for understanding how the system works day-to-day.
SOUL: How Agents Are Defined
Every #B4arena agent is defined by two independent layers:
| Layer | What It Defines | Changes When |
|---|---|---|
| Role | What needs to be done — responsibilities, authority, escalation rules | The organization changes |
| Soul | Who does it — persona, values, tone, communication style | The agent configuration changes |
A Role exists whether or not any agent fills it. A Soul instantiates a Role into a concrete agent. Replacing an agent means writing a new Soul, not redefining the Role.
The Agent File Structure
Each agent lives in a directory with these files:
agents/b4-dev/
├── SOUL.md ← Personality, directives, domain context
├── ROLE.yaml ← Machine-readable: wing, skills, tools, routing
└── AGENTS.md ← Peer routing guide: who to involve and when
SOUL.md is injected into the agent's context at session start. It follows a specific structure optimized for LLM attention patterns:
- Identity — Name and one-sentence purpose (top — establishes framing)
- Core Directives — 3–5 non-negotiable behavioral rules (top — highest priority)
- Domain Context — Product-specific knowledge (middle — reference material)
- Communication Style — Voice, tone, formats (middle — shapes output)
- What I Track — Metrics and signals (end — operational checklist)
- What I Do NOT Do — Explicit prohibitions (end — high-attention position)
ROLE.yaml is consumed by infrastructure tooling — routing, dispatch, capability discovery — without requiring an LLM to parse prose.
Wings
Agents are grouped into Wings — functional clusters that define reporting lines and communication patterns. #B4arena has five wings: Leadership, Product, Engineering, Quality, and Domain.
Wings are an organizational convenience, not hard boundaries. Cross-wing collaboration happens through work items.
Source: Agent Design — the full meta-framework for roles, souls, and wings.
Bead: How Work Is Tracked
A Bead is the unit of work coordination between agents. Beads are managed by the bd CLI, backed by a Dolt database (version-controlled SQL) with JSONL portability via git.
What a Bead Contains
| Field | Purpose |
|---|---|
id | Hash-based identifier (e.g., ws-3o9) — not sequential |
title | Short summary |
description | Full details |
status | open → in_progress → closed |
priority | P0 (critical) through P4 (backlog) |
labels | Routing tags (e.g., dev, eng-mgr) |
assignee | Who claimed the work |
dependencies | What blocks this bead |
How Beads Flow
- A bead is created with a title, type, and priority
bd readyshows beads with no open blockers — the agent's work queue- The agent claims a bead atomically (
bd update --claim) - After completing the work, the agent closes the bead
- Closing a bead may unblock downstream beads
Beads vs. GitHub Issues
#B4arena uses two tracking systems that serve different purposes:
| System | Purpose | Lifecycle | Analogy |
|---|---|---|---|
| Beads | Internal agent coordination | Ephemeral — cleaned up after completion | Slack conversations |
| GitHub Issues | Official project tracking | Permanent — part of the project record | Jira tickets |
There is no automatic sync between the two. Agents reference GitHub Issues in beads manually where needed.
Source: Beads Protocol · bd CLI Reference
Git and Repo Strategy
#B4arena's code is distributed across multiple repositories, managed as git subtrees under a workspace root (meta/).
Repository Layout
meta/ ← workspace root (private)
├── arena/ ← org design docs (private)
├── ludus/ ← agent config & deployment (private)
├── infra/ ← Ansible deployment (public)
├── intercom/ ← Beads coordination channel (private)
├── observe/ ← observability hub (private)
├── exploration-openclaw/ ← OpenClaw research (public)
├── tabula/ ← this knowledge base (public)
└── resources/ ← external reference checkouts
Key Principles
- Each sub-repo is a standalone git repository with its own
CLAUDE.mdfor project-specific context just setupclones all repos into the workspace- Never push directly to main — always use feature branches and pull requests
- All content in English, using conventional commits
Infrastructure Deployment
Infrastructure is managed via Ansible in infra/. All deploy commands run from infra/:
just deploy # deploy to all hosts
just deploy mimas # deploy to a single host
just check # dry-run
Source: meta README
Constructor ↔ Editor Boundary
This is the most important design principle for understanding who decides what in #B4arena.
The Boundary
| Role | Responsibility | Authority |
|---|---|---|
| Constructor (Human) | Defines the shape of the system — architecture, boundaries, purpose | Final say on anything that changes the shape |
| Editor (Agent) | Fills the volume within those boundaries — implements, builds, tests | Autonomous within defined boundaries |
The human decides what the system looks like. Agents decide how to build it. No agent may alter the shape of the system without human approval.
How the Boundary Is Enforced
Every decision is assessed against four dimensions. If any dimension is "high," the decision must be escalated:
| Dimension | Low (Agent proceeds) | High (Escalate) |
|---|---|---|
| Reversibility | Undo in minutes, no data loss | Hours/days to roll back |
| Blast radius | One component, one agent | Multiple services or agents |
| Commitment | No external bindings | Money, accounts, contracts |
| Visibility | Internal only | Visible to users or third parties |
Escalation Levels
| Level | Name | What Happens |
|---|---|---|
| L0 | Agent-autonomous | No notification to human |
| L1 | CoS-informed | Included in daily briefing FYI |
| L2 | CoS-decided | CoS makes the call, informs human after |
| L3 | Human-decided | CoS presents options, human chooses |
| L4 | Human-action | Only a human can perform this action |
The key insight: this is not a hierarchy of importance — it is a dimension-based assessment. A small security change (high visibility) escalates the same way as a large refactor (high blast radius). The four dimensions, not subjective judgment, determine what gets escalated.
Source: Operating Model §2 — full escalation framework with peer validation rules.
Next Steps
With these four mental models in hand, you're ready to explore the architecture:
- L2 — Architecture — how the subsystems (Ludus, Beads, Arena Core) fit together
- L3 — Runbooks — hands-on guides for getting things done