Here's something nobody warns you about when you build a multi-agent system: your agents don't know who each other are. - AI agents need an org directory for the same reason humans do: they need to know who owns what, who to contact, and where the boundaries are - Mission statements are useful, but routing triggers and "does not own" boundaries prevent the most common handoff failures - The directory needs to live in more than one place: canonical git, orchestrator context, retrieval augmented generation, and a quick routing reference I run a Business Operating System (BOS) on [OpenCLAW](https://github.com/openclaw/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](https://www.atlassian.com) calls org charts "visual roadmaps that outline how a company operates." [Workleap](https://workleap.com) 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:

Field	What it gives the agent
Identity	The department number, lead agent name, agent ID, and communication channel. In OpenCLAW, this means the Telegram topic ID or whatever channel binding routes messages to that agent.
Mission	A single sentence explaining why this department exists. Not what it does day to day, but why it was created. This gives routing agents the semantic context they need to match incoming work to the right department.
Routing triggers	Explicit examples of what work should be sent here. "Send work here when you need a blog post published, content strategy, social media planning, brand messaging, or marketing analytics." This is the single most valuable section for a Chief of Staff agent that routes work all day.
Boundaries	What this department explicitly does not do. "Does not own sales pipeline management (that is Sales), marketing spend approval (that is the Business Owner), or technology builds (that is Technology)." Boundaries prevent the most common misrouting errors by eliminating ambiguity at the edges between departments.

## 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: ```markdown # 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] ```

Field	Value
Lead	[Name and emoji]
Agent ID	[agent-id]
Channel	[Topic ID or binding]

```markdown **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. ```markdown ## 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](https://www.trychroma.com) 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: ```markdown ## Quick Routing Reference ```

If the work involves...	Route to
Blog post, content, brand, social media	Marketing
New lead, pipeline, proposal, prospect	Sales
Client onboarding, delivery, renewal	Delivery
Contract, compliance, privacy, regulation	Legal
Infrastructure, website, dev, data	Technology

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](https://cloverbase.com/contact).

#agent-orchestration

Building an org directory for AI agents on OpenCLAW