Building an org directory for AI agents on OpenCLAW

Here's something nobody warns you about when you build a multi-agent system: your agents don't know who each other are.

I run a Business Operating System (BOS) on OpenCLAW with over 20 AI agents, each owning a specific department or function. There's a Chief of Staff coordinating everything, department leads handling governance, finance, marketing, sales, technology, and so on, plus a development team running a full DevOps pipeline. It sounds impressive on paper, but for weeks there was a fundamental problem: none of them knew who the others were.

When my Chief of Staff agent received a request to publish a blog post, it had no way to know that Marketing owns content publishing, not Technology or Knowledge Base Governance. When a department lead needed to escalate a cross-functional issue, it didn't know the Telegram topic ID for the relevant peer. When my orchestrator agent needed to route a client delivery question, it was guessing.

The fix was surprisingly simple: build an org directory. The same thing every company of more than five people has. Except this one is designed for AI agents, not humans.

Why AI Agents Need an Org Directory#

In a human organisation, people learn who does what through onboarding, hallway conversations, Slack channels, and institutional memory built over months. AI agents have none of that. Every session starts fresh. Context windows get compacted. Memory files only capture what was explicitly written down.

Atlassian calls org charts "visual roadmaps that outline how a company operates." Workleap describes them as helping new employees "quickly learn who is who, who does what, who works where, and who they need to get to know." Those exact problems apply to AI agents. Every time an agent starts a new session after compaction, it's effectively a new employee on day one.

Without an org directory, three things go wrong consistently:

Misrouting. Work lands on the wrong agent. A blog post request goes to the knowledge base governance agent instead of marketing because both deal with "content" in some abstract sense. The agent that receives it either attempts work outside its expertise or bounces it back, wasting tokens and time.

Duplication. Two agents independently start working on the same problem because neither knows the other exists or owns the relevant domain. Your finance agent starts building a pricing model while your products agent is already designing one from a different angle.

Broken handoffs. Work that requires cross-department collaboration stalls because agents don't know how to reach each other. Your delivery agent needs legal review on a contract but doesn't know the legal agent's ID, topic, or even that a legal department exists.

What Good Org Directories Include#

Research into organisational design shows that effective employee directories go well beyond names and titles. The best ones include context that enables autonomous routing. For an AI agent system, that means four things per department:

How to Build One for OpenCLAW#

The implementation has four layers. Each serves a different access pattern.

Layer 1: Canonical Source (Git)#

Create an ORG-DIRECTORY.md file in your shared documents repository. This is the single source of truth. Every change starts here and propagates outward. Keep it in version control so you have a history of organisational changes.

The structure I landed on after research and iteration looks like this:

# Organisational Directory

## Reporting Structure
(ASCII tree showing the hierarchy)

## Executive Agents
(Your orchestrator and chief-of-staff with mission, owns, does-not-own)

## Department Directory
### Dept 01 — [Name]

**Mission:** [One sentence]
**Send work here when:** [Explicit routing triggers]
**Does NOT own:** [Explicit boundaries with cross-references]

The "Send work here when" and "Does NOT own" sections are the most important. Without them, you have a pretty chart that doesn't actually help agents route work.

Layer 2: Orchestrator Context (Workspace Files)#

Your routing agents need the org directory in their bootstrap context, loaded every session. In OpenCLAW, that means placing ORG-DIRECTORY.md directly in the workspace of your orchestrator and chief-of-staff agents, and referencing it in their AGENTS.md session startup sequence.

## Session Startup — Required Reading

Before any coordination work, read these files:
1. `SOUL.md` - identity and authority
2. `ORG-DIRECTORY.md` - who runs what, how to reach them
3. `SESSION-STATE.md` - active working memory

This is non-negotiable. If the org directory isn't in the bootstrap sequence, the agent will only see it if they actively go looking, which means they won't.

Layer 3: RAG (Semantic Search)#

Ingest the org directory into your ChromaDB collection, or whatever vector store you use for Retrieval Augmented Generation (RAG). This covers the case where any agent in the system queries "who handles marketing" or "what's the topic ID for finance." The orchestrators have the file directly; everyone else can query it through RAG.

Split the document into logical chunks when ingesting, one chunk per department. This gives the vector search clean, self-contained results rather than fragments that span department boundaries.

Layer 4: Quick Routing Reference#

At the bottom of the org directory, add a flat lookup table:

## Quick Routing Reference

This table is the cheat sheet. When your Chief of Staff is deciding where to route a request, this table gives an instant answer without reading every department's full entry.

Lessons Learned#

Boundaries matter more than missions. The mission tells you what a department does. The boundaries tell you what it doesn't do. In practice, misrouting happens at the edges, where two departments could plausibly own the work. "Marketing does NOT own sales pipeline management" prevents the most common confusion between Marketing and Sales.

Keep it updated or it becomes harmful. An outdated org directory is worse than no org directory because agents will confidently route work to the wrong place. I built a simple sync script that copies changes from the canonical source to workspaces and re-ingests to ChromaDB.

Your orchestrator agents are the primary consumers. Department agents occasionally need to know who their peers are, but the Chief of Staff and main orchestrator use the directory every single session. Design it for their workflow first.

Agents will overwrite each other's workspace files. During this build, I discovered that one department agent had completely overwritten my Chief of Staff's AGENTS.md with its own content. If you're running many agents with write access to workspaces, add governance checks. The canonical version in git is your recovery path.

The Payoff#

After deploying the org directory, my Chief of Staff agent can now instantly answer "who handles this?" for any incoming request. Work routes correctly on the first try. Cross-department escalations include the right topic IDs. New agents joining the system can query RAG to understand the full organisational structure without anyone manually briefing them.

It's the most mundane piece of infrastructure I've built, and it solved one of the most persistent operational problems in the entire system. Every company has an org chart. Your multi-agent system needs one too.

Mark Smith is Principal AI Strategist at Cloverbase. To discuss this article or work with me, contact me at Cloverbase.