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

In the Munder Difflin multi-agent architecture, registry.json functions as the live roster tracking every agent’s identity, role, and status, while 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 and 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 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. 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 before delivering messages, ensuring only agents marked as active are considered valid targets src/main/hive.ts lines 7-10. 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. This guarantees that the on-disk state always reflects the actual runtime configuration.

board.md: The Shared Collaborative Blackboard

The Planning Surface

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

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

Reading and updating the agent roster:

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:

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 maintains the live roster of all agents, storing identity metadata and operational status for routing decisions.
• 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?

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.

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

The Electron main process uses atomic write operations when updating 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.

What information does 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.

Why is 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}