# The Role of `registry.json` and `board.md` in Munder Difflin: Hive Roster and Shared Blackboard

> Discover how registry.json and board.md manage agent identity and collaborative plans in Munder Difflin. Understand their crucial roles in atomic coordination within the multi-agent architecture.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: internals
- Published: 2026-08-27

---

**In the Munder Difflin multi-agent architecture, [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) functions as the live roster tracking every agent’s identity, role, and status, while [`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md) serves as the shared blackboard containing the team’s collaborative plan, with both files managed exclusively by the Electron main process to ensure atomic, conflict-free coordination.**

The Munder Difflin repository implements a unique "hive" architecture that enables multiple Claude agents to coordinate autonomously. At the heart of this coordination mechanism lie two critical files: [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) and [`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md). Understanding the distinct roles of these files is essential for grasping how the system maintains situational awareness and shared context without race conditions.

## registry.json: The Canonical Agent Roster

### Tracking Live Agent State

[`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) acts as the **single source of truth** for which agents are currently active in the hive. According to the architecture documentation, this file maintains a canonical listing of every live agent together with its identity, including **role**, **working directory**, **session ID**, and current **status** [HIVE.md lines 72-74](https://github.com/chaitanyagiri/munder-difflin/blob/main/HIVE.md#L72-L74). When an agent spawns or changes its operational state, the main process records these details immediately.

### Routing and Orchestration Decisions

The **god/orchestrator** reads this file to determine which agent should receive a specific request. The router checks [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) before delivering messages, ensuring only agents marked as *active* are considered valid targets [src/main/hive.ts lines 7-10](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts#L7-L10). This prevents the system from attempting to communicate with terminated or unresponsive processes.

### Atomic Updates and Durability

To maintain consistency, the main process performs **atomic writes** when updating the roster. The implementation uses `atomicWriteJson` to prevent data corruption during concurrent access, writing the updated record back to disk only after validation [src/main/hive.ts lines 68-71](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts#L68-L71). This guarantees that the on-disk state always reflects the actual runtime configuration.

## board.md: The Shared Collaborative Blackboard

### The Planning Surface

[`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md) serves as the **shared blackboard**—a free-form markdown document that contains the team’s co-authored plan, strategic decisions, and narrative context [HIVE.md lines 89-91](https://github.com/chaitanyagiri/munder-difflin/blob/main/HIVE.md#L89-L91). Unlike the structured JSON registry, this file provides a human-readable space where the collective workflow is documented and refined.

### Controlled Edit Flow

Agents **do not** write directly to [`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md). Instead, they propose changes via structured messages, and the **god agent** validates and commits these edits after checking for conflicts [HIVE.md lines 49-60](https://github.com/chaitanyagiri/munder-difflin/blob/main/HIVE.md#L49-L60). This centralized gatekeeping prevents race conditions and ensures the blackboard never contains invalid or contradictory plans. The orchestrator treats this file as the definitive record of the current operational plan [src/main/hive.ts lines 2658-2664](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts#L2658-L2664).

### Reading the Blackboard

When rendering the UI or preparing context for agents, the system loads the blackboard content using standard file system operations [src/main/hive.ts lines 1686-1687](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts#L1686-L1687). This read-only access pattern for worker agents ensures that only the main process can mutate the shared state.

## Code Examples: Working with Hive Files

Below are practical Node.js implementations demonstrating how the core system interacts with these files. These patterns mirror the actual implementations found in [[`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts)](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts).

Reading and updating the agent roster:

```javascript
import { readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';

const hiveRoot = '/path/to/hive'; // Typically <harnessHome>/hive
const registryPath = join(hiveRoot, 'registry.json');

// Load the current roster
function loadRegistry() {
  const raw = readFileSync(registryPath, 'utf8');
  return JSON.parse(raw);
}

// Atomically update an agent's status
function updateAgentStatus(agentId, status) {
  const reg = loadRegistry();
  reg.agents[agentId] = { 
    ...reg.agents[agentId], 
    status, 
    lastSeen: Date.now() 
  };
  // In production, use atomicWriteJson to prevent corruption
  writeFileSync(registryPath, JSON.stringify(reg, null, 2));
}

```

Interacting with the shared blackboard:

```javascript
const boardPath = join(hiveRoot, 'board.md');

// Read the current plan
function loadBoard() {
  return readFileSync(boardPath, 'utf8');
}

// Propose an update (actual write performed by god agent)
function proposeBoardAddition(newSection) {
  const current = loadBoard();
  const proposed = current + '\n\n' + newSection;
  // Return proposal to main process for validation and commit
  return proposed;
}

```

## Summary

- **[`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json)** maintains the **live roster** of all agents, storing identity metadata and operational status for routing decisions.
- **[`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md)** provides the **shared blackboard** for collaborative planning, edited exclusively by the god agent to prevent conflicts.
- Both files reside in the hive's Git repository and are accessed through **atomic operations** managed by the Electron main process.
- This architecture ensures **situational awareness** (via the registry) and **shared context** (via the blackboard) without race conditions or data corruption.

## Frequently Asked Questions

### Can individual agents write directly to [`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md)?

No. Individual agents **cannot** write directly to the blackboard. They must send structured messages to the god agent, which validates the proposed changes and performs the actual file write. This prevents race conditions and maintains the integrity of the shared plan [HIVE.md lines 49-60](https://github.com/chaitanyagiri/munder-difflin/blob/main/HIVE.md#L49-L60).

### How does the system prevent corruption when multiple agents update simultaneously?

The Electron main process uses **atomic write operations** when updating [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json). By writing to a temporary file and renaming it to the target filename, the system ensures that readers always see a complete, valid JSON structure, even during concurrent updates [src/main/hive.ts lines 68-71](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts#L68-L71).

### What information does [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json) store about each agent?

The registry tracks each agent's unique identifier, assigned **role**, current **working directory (cwd)**, **session** ID, and current operational **status** (idle, working, or blocked) [src/main/hive.ts lines 7-10](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts#L7-L10).

### Why is [`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md) formatted as markdown rather than JSON?

Markdown provides a **human-readable** format that supports rich text, headers, and narrative structure. This allows both humans and agents to read the operational plan naturally, while still being machine-parseable. The format supports the system's goal of maintaining transparent, auditable decision logs.