Introducing OrgSpec: a portable format for modern org charts

Most organizations can answer “who reports to whom” only by pointing at a spreadsheet, a slide, a screenshot, or a view inside an HR system.

That works until the org chart needs to move.

Move it into a planning tool. Move it into a diagram. Move it into a review document. Move it into a model of next quarter’s hiring plan. Move it from the HRIS into a system that engineering, finance, product, and operations can all reason about.

At that point, the org chart usually stops being data and becomes fragile copy-paste work.

OrgSpec is our attempt to fix that.

OrgSpec is a portable organization-structure format and standalone CLI from Orgonaut. It turns HR exports and spreadsheets into structured org data that can be validated, rendered, diffed, exported, and prepared for use in Orgonaut.

It starts with a simple idea: org charts deserve a real file format.

Why we built it

Orgonaut is built around a broader model of organizations than the classic “employee, title, department, manager” spreadsheet.

That older model is useful, but it is no longer enough.

Modern organizations are made of people, teams, departments, roles, positions, contractors, vacant seats, reporting relationships, dotted-line relationships, fractional allocations, and increasingly non-human contributors. AI agents and robots are already becoming part of operational reality. They need to be represented in the same planning language as the people they work with.

Inside Orgonaut, we call these contributors actors. A person is an actor, but not every actor has to be a person. OrgSpec carries that same idea forward with actor kinds for people, agents, and robots.

We built OrgSpec because the market lacks a shared, practical org-chart language for this kind of structure.

Without that language, every tool invents its own version:

• HRIS exports flatten the org into rows and manager fields.
• Diagramming tools capture layout, but not much structure.
• Spreadsheets are flexible, but hard to validate.
• Internal tools create one-off schemas that do not travel.
• Planning documents explain intent, but drift away from the underlying data.

The result is unnecessary friction around one of the most important operating models in a company: how work is organized.

OrgSpec is not trying to replace an HRIS. It is not trying to become a system of record for payroll, benefits, or employment history. It is a portable structure layer: a way to describe the shape of an organization in a file that tools can read, validate, compare, and transform.

What OrgSpec does

OrgSpec has two parts:

1. A portable file format for organization structure.
2. A local CLI for working with those files.

The CLI can run without an Orgonaut account. It is designed for practical workflows that start with the files teams already have.

Install it with:

curl -fsSL https://app.orgonaut.co/orgspec/install.sh | sh

Then use it to initialize, import, validate, render, diff, and export org structure data:

orgspec init --out org.orgspec.yaml
orgspec import people.csv --mapping manager_email --out org.orgspec.json
orgspec validate org.orgspec.json
orgspec render org.orgspec.json --format mermaid --out org.mmd
orgspec diff january.orgspec.json february.orgspec.json --format markdown --out org-diff.md
orgspec export org.orgspec.json --format orgonaut --out orgonaut-import.json

The initial CLI supports common workflows:

• Import CSV exports using mapping presets such as manager email, manager ID, or department path.
• Validate references, duplicates, reporting loops, placement issues, and actor-kind compatibility.
• Render org structure to Mermaid, SVG, or graph JSON.
• Diff two org files to see actor changes, unit moves, reporting changes, placement changes, and position or vacancy changes.
• Export canonical JSON.
• Prepare an Orgonaut bridge payload for Orgonaut import tooling.

That makes OrgSpec useful even before it touches a SaaS product. You can use it in a repo, in an internal tools pipeline, during a planning cycle, or as a local sanity check before sharing org data with another system.

What it models

OrgSpec is intentionally focused on structure.

It models the parts of an organization that describe where work happens, who or what contributes to it, and how those contributors relate to units and positions.

The core concepts are:

• Actors: people, AI agents, and robots.
• Units: teams, departments, nodes, or other structural groupings.
• Positions: seats, titles, levels, disciplines, and vacancies.
• Placements: where actors sit, including allocation and fractional involvement.
• Relationships: reporting lines and structural parent-child relationships.
• Metadata: enough context for tools to preserve useful information without turning the format into a vendor-specific database.

That distinction matters.

An org chart should be able to show that a platform team belongs under engineering, that a staff engineer is allocated across two units, that a vacant role exists, that an AI support agent is part of an operations workflow, or that a robot is owned by a facilities team.

Those details are not decorative. They affect cost, capacity, planning, accountability, and change management.

Why a CLI first

We chose to ship OrgSpec as a CLI first because org data often starts in the hands of technical operators.

Someone has a CSV export. Someone is building an internal dashboard. Someone is trying to compare this month’s structure with last month’s. Someone wants to generate a diagram in a pull request. Someone wants to clean up data before it reaches a planning system.

A local CLI fits those jobs.

It also keeps the early workflow honest. OrgSpec should be useful as a file format, not only as a feature inside Orgonaut. If the format cannot stand on its own for validation, rendering, and diffing, it is not portable enough.

The local-first design has another benefit: it can fit into existing developer workflows. Org structure can be checked into a private repo, reviewed in a pull request, rendered into documentation, or validated in CI.

That opens up a different way of thinking about org design. Instead of treating the org chart as a static image, teams can treat it as structured operational data.

How it helps teams

OrgSpec is useful when the current org chart workflow is too manual, too opaque, or too trapped in one tool.

For engineering leaders, it can turn spreadsheets into a reviewable org model. Instead of emailing screenshots, you can produce structured files, diagrams, and diffs.

For internal tools teams, it provides a stable interchange format. You do not need to invent a new schema every time you move org data between an HR export, a dashboard, and a planning workflow.

For people analytics and operations teams, it creates a validation step before org data becomes a slide deck or a planning artifact. Broken manager references, duplicate actors, orphaned units, and unclear placements can be caught earlier.

For consultants and transformation teams, it makes before-and-after org design easier to compare. Diffs can show what moved, what changed, and what needs attention.

For teams adopting AI into real operating workflows, it gives non-human contributors a first-class place in the org model. Agents and robots do not have to be bolted on as notes or fake employees.

OrgSpec is not a complete organization operating system. That is where Orgonaut comes in.

How OrgSpec connects to Orgonaut

Orgonaut is the product we are building for mapping, analyzing, and evolving organizations.

It takes the same underlying belief as OrgSpec and extends it into a collaborative SaaS platform: actors, teams, departments, roles, placements, scenarios, costs, capacity, velocity, governance, integrations, and change planning.

OrgSpec handles the portable file layer. Orgonaut handles the operating layer.

That split is deliberate.

The file format should be simple enough to move between tools. The platform should be powerful enough to answer deeper questions:

• What is the current shape of the organization?
• Where are people, agents, and robots allocated?
• What does this structure cost?
• Where is capacity concentrated?
• What changes between two plans?
• Which teams are overloaded?
• What would a proposed reorg change before it becomes real?

OrgSpec can export an Orgonaut bridge payload, preserving actor kinds, units, placements, and key structure so the data can be prepared for Orgonaut import tooling. Orgonaut then becomes the place to collaborate on that structure, model scenarios, analyze rollups, and govern changes.

In other words: OrgSpec makes org structure portable. Orgonaut makes org structure actionable.

A small example

A simple OrgSpec workflow might start with an HR export:

employee_id,name,email,title,department,manager_email
e001,Ada Hart,ada@example.com,VP Engineering,Engineering,
e002,Grace Lin,grace@example.com,Engineering Manager,Platform,ada@example.com
e003,Samir Vale,samir@example.com,Staff Engineer,Platform,grace@example.com

You can convert that file into structured org data:

orgspec import people.csv \
  --mapping manager_email \
  --format json \
  --out org.orgspec.json \
  --org-id example \
  --org-name "Example Co"

Then validate it:

orgspec validate org.orgspec.json

Render it:

orgspec render org.orgspec.json --format mermaid --out org.mmd

And compare it later:

orgspec diff january.orgspec.json march.orgspec.json --format markdown --out org-changes.md

That is a modest workflow, but it changes the shape of the problem. The org chart is no longer just a picture. It is data you can inspect, version, transform, and discuss.

What OrgSpec is not

It is worth being precise about the boundary.

OrgSpec is not a payroll system, HRIS, authorization model, or source of truth for every employee lifecycle event.

It is not a formal standards-body specification.

It is not the whole of Orgonaut compressed into a file. Orgonaut concepts such as scenarios and snapshots belong in the platform, not in the initial OrgSpec file format.

That restraint is important. A portable format becomes less useful when it tries to carry every workflow, permission, and product-specific concept with it.

OrgSpec should describe organization structure clearly enough that tools can understand it, while leaving collaboration, governance, analytics, and scenario modeling to platforms like Orgonaut.

Where we are starting

The first version of OrgSpec focuses on the basics that make the format immediately useful:

• CSV import
• schema validation
• Mermaid and SVG rendering
• JSON graph output
• org diffs
• canonical JSON export
• Orgonaut bridge export
• actor kinds for people, agents, and robots

That is enough to begin using it as a practical utility and enough to test the bigger idea: organization structure should be portable, inspectable, and easier to move between systems.

Try it

Install the CLI:

curl -fsSL https://app.orgonaut.co/orgspec/install.sh | sh

Read the CLI guide.

If you already have an HR export or an org spreadsheet, OrgSpec gives you a way to start turning that file into something more durable: a structured representation of how the organization works.

And if you want to go further, Orgonaut is where that structure becomes a living model for planning, analysis, and organizational change.