Introducing OrgSpec: a portable language for organizations

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 and operating-model format with a standalone CLI from Orgonaut. It turns HR exports and spreadsheets into structured data that can connect organization structure to work, capabilities, and solutions, then be validated, rendered, diffed, exported, and prepared for use in Orgonaut.

It starts with a simple idea: organizations deserve a real, portable language.

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 model layer: a way to describe the shape of an organization, the work it performs, the capabilities it depends on, and the solutions it deploys 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 and operating models.
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 organization 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, actor-kind compatibility, and links between work, capabilities, and solutions.
• Render org structure to Mermaid, SVG, or graph JSON.
• Diff two org files to see structural changes alongside additions, removals, and updates to work, capabilities, and solutions.
• 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 0.2 extends the structural foundation into a portable operating model.

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.
• Work: a durable catalogue of categories and activities, with assignments to units, positions, actors, or role families.
• Capabilities: what the organization must be able to do, with contextual assessments, work contributions, and measurable outcomes.
• Solutions: governed copilots, agents, automations, workflows, platforms, and service assets with versioned claims, obligations, and deployments.
• Metadata: enough context for tools to preserve useful information without turning the format into a vendor-specific database.

That distinction matters.

An OrgSpec model can show that a platform team belongs under engineering, that a staff engineer is allocated across two units, that a vacant role exists, and that an AI support agent performs incident triage work in support of a service-reliability capability.

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 operating models easier to compare. Diffs can show what moved, which work changed hands, which capabilities were affected, and which solutions were introduced or retired.

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, work, capabilities, governed solutions, transformation cases, scenarios, costs, capacity, 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?
• Which work develops or consumes a critical capability?
• Which governed copilots, agents, automations, workflows, platforms, or service assets support that work?
• What would a proposed reorg change before it becomes real?

OrgSpec can export an Orgonaut bridge payload, preserving actor kinds, units, placements, work, capabilities, solutions, and their portable references for Orgonaut import tooling. Orgonaut then becomes the place to collaborate on that model, explore scenarios, analyze rollups, build transformation cases, and govern changes.

In other words: OrgSpec makes the organization model portable. Orgonaut makes it 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.

With OrgSpec 0.2, the same document can carry the next layer of meaning:

orgspec: "0.2"
work_categories:
  - id: work_category_operations
    name: Operations

work_activities:
  - id: work_incident_triage
    name: Incident triage
    category: work_category_operations

capabilities:
  - id: capability_service_reliability
    name: Service reliability
    outcome: Customer services remain dependable and recoverable.

solutions:
  - id: solution_triage_agent
    name: Incident Triage Agent
    solution_type: agent
    lifecycle_status: active

Additional assessment, assignment, capability-work, version, claim, obligation, and deployment records connect these catalogues using stable IDs. The CLI validates those references, includes the entities in deterministic diffs, and preserves them through canonical and Orgonaut bridge exports.

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 and operating-model semantics clearly enough that tools can understand them, while leaving collaboration, governance, analytics, and scenario modeling to platforms like Orgonaut.

What is available now

OrgSpec 0.2 includes the structural foundation and the operating-model entities needed to connect it to how value is delivered:

• 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
• work activities and responsibilities
• business capabilities and their work links
• governed copilots, agents, automations, workflows, platforms, and service assets
• deterministic operating-model validation, diffs, and bridge export

That is enough to use OrgSpec as a practical utility and to test the bigger idea: organization models 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.