The Org Chart from Ground Truth

Tier 3 · Real Builds 7 min read

Before this, read:

Nerve Center v5: the web cockpit — the cockpit where the org chart lives
harnessview: an OSS tool that visualizes a harness — harnessview is the standalone spinout of this same pattern

The org chart in the cockpit shows you the agent org: MCP servers, agent packages, domain brains, skills, hooks, commands, and plugins — how they’re connected, what’s active, how the hierarchy is structured. It’s the single-pane view of what the system actually is.

The first version of this chart lied. Not deliberately — it just had the wrong data source.

The original approach and why it drifted

The first org chart in the Nerve Center read from a hand-curated YAML file in the agent registry. The file had a list of agents, their domains, their connections. When someone added a new agent, they were supposed to update the YAML. When a CLAUDE.md rule changed the scope of a skill, someone was supposed to update the YAML.

Nobody kept it updated. By mid-May 2026, the /org page in the cockpit was showing:

Agents that had been archived or renamed
Missing agents that had been added to the codebase
Domain counts that didn’t match the actual domain directories
MCP servers that had been added without a registry update

The chart was a historical artifact, not a current description of the system.

The root-cause fix

The diagnosis from the 2026-05-31 audit was direct: the org chart reads from a hand-curated YAML registry, not from the filesystem. The fix: wire the chart to the filesystem directly.

The /api/org endpoint (PR #136 from the May 31 fix night) reads from three ground-truth sources:

~/agent-system/agents/ — every directory is an agent. ls agents/ | wc -l gives the authoritative count.
~/agent-system/.mcp.json — every MCP server configuration, exactly as Claude Code reads it. 16 MCPs as of mid-2026.
~/clawd/domains/ — every domain directory. 8 domains: school, family, growth, ai-foundry, siemens, consulting, health, life-ops.

The /org API response is a live composition of these three sources, assembled at request time. No registry. No YAML. The files are the truth; the API reads the files.

The graph structure

The org chart renders as a React Flow + elkjs graph. The layout algorithm (elkjs) handles the automatic positioning — you don’t place nodes manually.

Node types:

CEO — the top node (Opus tier)
Domain — one node per domain directory (8 domains)
Agent — one node per agents/ package (~31 as of mid-2026)
MCP — one node per MCP server in .mcp.json (16 as of mid-2026)
Skill — skills from .claude/skills/ (14 skills)
Hook — hooks registered in settings.json (12 hooks)
Command — commands in .claude/commands/ (8 commands)

Edges:

CEO → Domains (hierarchy)
Domain → relevant Agent packages (domain responsibility)
Agent → MCPs they use (tool connections)
Skills, hooks, commands connect to the Claude Code session node (they extend the harness, not individual agents)

The elkjs LAST_SEPARATE placement directive for MCP nodes was added to keep them at the bottom of the graph in a dedicated row (PR #56, 2026-05-23). Before that fix, MCPs were interleaved with agents and the graph looked like a hairball.

The regression check

The CLAUDE.md rule on the org chart states: “Add a regression check that fails if chart count diverges from .mcp.json | agents/ | domains/ ground truth.”

The regression test (running in CI via pytest) compares:

len(response["agents"]) against ls ~/agent-system/agents/ | wc -l
len(response["mcps"]) against the count of keys in .mcp.json
len(response["domains"]) against ls ~/clawd/domains/ | wc -l

If the counts don’t match, CI fails with an explanation. The test doesn’t prescribe exact values (those change as the system grows) — it checks that the chart isn’t lying about what’s on disk.

harnessview: the OSS spinout

On June 9, 2026, the org chart pattern was extracted into a standalone OSS tool: harnessview (~/code/harnessview). The generalization: instead of the specific paths JD’s system uses, harnessview uses a pluggable adapter architecture. A scanner reads any Claude Code harness’s .claude/ directory, agents/ directory, .mcp.json, and settings.json and produces a HarnessGraph — a typed output format with node kinds as free strings rather than hardcoded types.

The live local server uses SSE filesystem-watching (instead of Supabase + cron) to keep the graph current. Change a file; the graph updates in the browser within a second.

The npx CLI (npx harnessview) means anyone with a Claude Code harness can run it against their directory without installing anything. The end-to-end verification against ~/agent-system produced 52 nodes: 16 MCP, 14 skill, 8 command, 12 hook, 1 plugin.

The harnessview article (T3-A4) covers that spinout in full.

The “stale org chart” class of bug

The pattern from the original stale YAML — curated data that people are supposed to keep updated but don’t — appears everywhere in agent systems. Some examples from the JD system:

The project registry (project-registry.yaml) had ~30 ghost projects that were archived or idea but showed as active until the April 2026 audit pass
The agent registry (agents-registry.yaml) had 52 entries including several hollow/no-code stubs that were cleaned up in the June 2026 audits
The domain sync pipeline (domain-sync.sh) was crashing silently on a missing agent: block in report.md, so 4 domains weren’t syncing to Supabase

In every case, the fix is the same: read from the filesystem directly, not from a manually maintained list. The filesystem is the truth. Everything else is a cache that drifts.

What 52 nodes means

The mid-2026 harnessview scan of ~/agent-system found 52 nodes. That’s the ground-truth picture of JD’s Claude Code harness: 16 MCP servers giving the agent new senses (Telegram, Google Calendar, Supabase, GitHub, Brave search, Obsidian, Slack, etc.), 14 skills encoding reusable behaviors, 8 commands available in every session, 12 hooks wiring pre/post behaviors to tool calls and session events, and 1 plugin (the Telegram plugin providing the inbound message channel).

The org chart renders all 52. It doesn’t pad the count with aspirational nodes or archived entries. It reads the files, renders what it finds, and stays current as the system evolves.

That’s what “from ground truth” means: the chart and the system are always the same thing.

Previous in this group: Clean chat rendering

Continue exploring: AgentTree Merch: an AI operator that runs a store — the next major system piece, built on top of everything the cockpit group established.