OrgSpec

Portable organization specification and CLI

Portable org-structure protocol macOS + Linux CLI

OrgSpec is the organization model for an AI-native ecosystem.

OrgSpec is a machine-readable specification and standalone CLI for describing teams, people, roles, reporting lines, allocations, costs, planning cycles, and operating-model change.

It gives Orgonaut and future ecosystem tools a shared data layer for generating, validating, visualising, benchmarking, and exchanging organization models across the systems where structure already lives.

One-command install

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

Install OrgSpec Read the CLI docs

actors:
  - id: actor_build_agent
    kind: agent
    name: Build Reliability Agent
    capabilities:
      - build-analysis
      - release-risk

units:
  - id: unit_platform
    kind: team
    name: Platform

placements:
  - actor: actor_build_agent
    unit: unit_platform
    allocation: 1.0

OrgSpec is the standard

A machine-readable specification for organization structure that can move across tools.

Orgonaut plans scenarios

Use Orgonaut when portable OrgSpec files need collaboration, governance, rollups, and scenario planning.

Ecosystem ready

Designed for generators, validators, visualizers, benchmarks, and future integration tooling.

Install

Install it like a normal CLI.

OrgSpec ships as a standalone binary for macOS and Linux. No Node.js runtime or Orgonaut account is required for local file workflows.

Install

Fetch the latest standalone binary from the app host.

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

Verify

Confirm the CLI is on your path.

orgspec --help

Pinned version

curl -fsSL https://app.orgonaut.co/orgspec/install.sh \
  | ORGSPEC_VERSION=v0.1.0 sh

Custom directory

curl -fsSL https://app.orgonaut.co/orgspec/install.sh \
  | ORGSPEC_INSTALL_DIR=$HOME/.local/bin sh

Manual downloads

Need a pinned version or manual download? Use the app-hosted release URLs.

macOS Apple Silicon orgspec-darwin-arm64 Download macOS Intel orgspec-darwin-x64 Download Linux x86-64 orgspec-linux-x64 Download Linux ARM64 orgspec-linux-arm64 Download

Why

Spreadsheets are not an org model.

Most org chart tools flatten structure into a person, a title, a department, and a manager.

That works until you need to model vacancies, matrixed teams, fractional allocation, AI agents, robots, dotted-line relationships, or a future structure you have not approved yet.

OrgSpec gives those facts a portable definition so the chart can move between spreadsheets, repositories, diagrams, analysis scripts, and Orgonaut without losing the meaning of the organization.

Org charts as versionable files

Humans, agents, and robots as first-class actors

Teams and departments as structure, not only labels

Positions and vacancies separate from people

Placements for allocation and membership

Relationships for reporting and non-reporting edges

Deterministic diffs for org changes

Ecosystem

OrgSpec is built for the tools where organisational reality already lives.

Jira shows how work flows. HRIS platforms hold people and role data. GitHub and Azure DevOps show engineering ownership. Spreadsheets hold the unofficial truth. OrgSpec gives these systems a shared, portable language for describing the organisation.

OrgSpec is designed to sit above the tools where organisational structure already hides: Jira boards, HRIS records, GitHub teams, Azure DevOps projects, spreadsheets, planning documents, Confluence pages, and transformation decks.

Ecosystem tools can generate, validate, visualise, benchmark, and exchange OrgSpec so teams can move from scattered operational data to a clear, machine-readable model.

Designed for ecosystems including

These are ecosystem targets and data surfaces, not a claim that every connector is shipped today.

Roadmap

Jira First initiative

BambooHR Orgonaut supported

HiBob Roadmap target

Workday Roadmap target

GitHub Roadmap target

Azure DevOps Roadmap target

Google Sheets Roadmap target

Excel Roadmap target

Confluence Roadmap target

Slack Roadmap target

Microsoft Teams Roadmap target

First ecosystem initiative: OrgSpec for Jira, a Jira-to-OrgSpec generator for creating a current-state organisational baseline. Ecosystem tools are being developed progressively.

Generate OrgSpec

Turn Jira structures, HRIS records, spreadsheets, planning documents, and future ecosystem tools into a current-state or future-state OrgSpec.

Validate OrgSpec

Check missing relationships, hierarchy cycles, duplicate identities, allocation issues, provenance, and scenario readiness before the model moves downstream.

Use OrgSpec

Import into Orgonaut, visualise changes, compare scenarios, benchmark structures, and exchange organization models with tools that understand the specification.

Explore OrgSpec See what OrgSpec can describe

Model

What OrgSpec models

A file can stay simple, or become precise enough for allocation, vacancies, provenance, and non-human contributors.

Actors

People, AI agents, robots, and future actor kinds. OrgSpec starts with actors because modern work is no longer only human headcount.

kindnameemailtitlecapabilitiesasset_idrobot_class

Units

Departments, teams, functions, groups, nodes, and cost centers with hierarchy and leads.

kindnameparentlead_actorpurpose

Positions

Seats that can be occupied, vacant, planned, frozen, or closed.

titleunitstatusrole_familylevelfte

Placements

The link between actors, units, and positions. Placements carry allocation, primary membership, and effective dates.

actorunitpositionprimaryallocationfte

Relationships

Reporting lines, dotted lines, ownership, support, supervision, and membership.

kindfromto

Sources

Provenance for imported facts, so generated org files can explain where each piece of structure came from.

kinduriobserved_atconfidence

Workflow

From CSV to chart, diff, and bridge export.

Import once, validate the structure, render a diagram, review changes, and export a portable payload.

Import

Convert a spreadsheet or HR export into an OrgSpec document.

Validate

Catch missing fields, duplicate ids, broken references, hierarchy cycles, and reporting cycles.

Render

Generate Mermaid, SVG, or graph JSON for review, documentation, and internal tools.

Diff

Compare two org states and get a readable summary of actor, reporting, placement, unit, and position changes.

Export

Write canonical JSON or an Orgonaut bridge payload.

CLI workflow

A complete local path from spreadsheet to Orgonaut bridge payload.

orgspec import people.csv \
  --mapping manager_email \
  --format json \
  --out org.orgspec.json \
  --org-id acme \
  --org-name "Acme Ltd"

orgspec validate org.orgspec.json
orgspec render org.orgspec.json --format svg --out org.svg
orgspec diff january.orgspec.json february.orgspec.json --format markdown
orgspec export org.orgspec.json --format orgonaut --out orgonaut-import.json

Example

A compact OrgSpec document

JSON and YAML files describe the organization as actors, units, positions, placements, and relationships.

Readable source file

This example models a human leader, an AI agent, a robot, a team, an occupied position, and a reporting edge.

orgspec: "0.1"
organization:
  id: acme
  name: Acme Ltd

actors:
  - id: actor_mara
    kind: person
    name: Mara Chen
    title: VP Engineering

  - id: actor_build_agent
    kind: agent
    name: Build Reliability Agent
    capabilities:
      - build-analysis
      - release-risk

  - id: actor_lab_robot
    kind: robot
    name: Lab Robot 12
    asset_id: ROBOT-12
    robot_class: prototype-lab

units:
  - id: unit_engineering
    kind: department
    name: Engineering
    lead_actor: actor_mara

  - id: unit_platform
    kind: team
    name: Platform
    parent: unit_engineering

positions:
  - id: position_ai_build_agent
    title: AI Build Agent
    unit: unit_platform
    status: occupied

placements:
  - id: placement_agent_platform
    actor: actor_build_agent
    unit: unit_platform
    position: position_ai_build_agent
    primary: true
    allocation: 1.0

relationships:
  - id: rel_agent_reports_to_mara
    kind: reports_to
    from:
      type: actor
      id: actor_build_agent
    to:
      type: actor
      id: actor_mara

Machine-friendly document

Use JSON when you want deterministic exchange with scripts, dashboards, and review tools.

{
  "orgspec": "0.1",
  "organization": {
    "id": "acme",
    "name": "Acme Ltd"
  },
  "actors": [
    {
      "id": "actor_mara",
      "kind": "person",
      "name": "Mara Chen",
      "title": "VP Engineering"
    },
    {
      "id": "actor_build_agent",
      "kind": "agent",
      "name": "Build Reliability Agent",
      "capabilities": ["build-analysis", "release-risk"]
    },
    {
      "id": "actor_lab_robot",
      "kind": "robot",
      "name": "Lab Robot 12",
      "asset_id": "ROBOT-12",
      "robot_class": "prototype-lab"
    }
  ],
  "units": [
    {
      "id": "unit_engineering",
      "kind": "department",
      "name": "Engineering",
      "lead_actor": "actor_mara"
    },
    {
      "id": "unit_platform",
      "kind": "team",
      "name": "Platform",
      "parent": "unit_engineering"
    }
  ],
  "placements": [
    {
      "id": "placement_agent_platform",
      "actor": "actor_build_agent",
      "unit": "unit_platform",
      "primary": true,
      "allocation": 1.0
    }
  ]
}

Validate, render, and diff

The same file can be checked locally, rendered into docs, and compared against another org state.

orgspec validate acme.orgspec.yaml
orgspec render acme.orgspec.yaml --format mermaid --out acme.mmd
orgspec diff january.orgspec.json february.orgspec.json --format markdown

Render the org into diagrams.

Use Mermaid for docs, SVG for quick sharing, and graph JSON when you want to build your own visualization.

orgspec render org.orgspec.yaml --format mermaid --out org.mmd
orgspec render org.orgspec.yaml --format svg --out org.svg
orgspec render org.orgspec.yaml --format json --out org.graph.json

Review structure changes like code changes.

Compare two states and get a readable Markdown summary of material org changes.

orgspec diff before.orgspec.json after.orgspec.json --format markdown

# OrgSpec Diff

- Added Actor: Build Reliability Agent
- Changed Actor Kind: Lab Robot 12
- Moved Unit: Platform
- Changed Reporting Edge: Build Reliability Agent reports to Mara Chen
- Changed Placement: Build Reliability Agent allocation 1.0 -> 1.25

Bridge

Bring portable org data into Orgonaut.

OrgSpec is the standard. Orgonaut is the scenario-planning platform. The bridge export prepares actors, units, positions, placements, and relationships for Orgonaut import tooling while keeping the specification portable.

Use OrgSpec when you need current-state or future-state organization models that can move between systems. Use Orgonaut when those models need scenario planning, permissions, audit history, AI assistance, rollups, governance, and stakeholder-ready visual workflows.

Explore Orgonaut

Bridge export

orgspec export org.orgspec.yaml --format orgonaut --out orgonaut-import.json

Mapping summary

OrgSpec person becomes Orgonaut human
agent and robot actor kinds are preserved
departments and teams map to Orgonaut org units and metadata rows
placements map to Orgonaut placement data
allocation ratios convert to percentages
target tenant and Live/scenario context are supplied by Orgonaut, not stored in the OrgSpec file

Principles

Protocol principles

OrgSpec stays portable and deterministic while leaving product workflows to Orgonaut.

Keep it portable

OrgSpec does not require an Orgonaut account and does not store Orgonaut tenant ids, scenario ids, or internal database ids.

Actors first

People are a kind of actor. Agents and robots are first-class because future org charts need to show both human and non-human contributors.

Positions are optional but real

Simple files can describe people, teams, and reporting lines. Higher-fidelity files can describe positions, vacancies, allocation, and planned starts.

Scenarios stay outside the core file

OrgSpec describes a structure state. Planning workflows, scenario sandboxes, snapshots, approvals, and promotion are application behavior. Orgonaut handles those when you need them.

Deterministic by default

Validation, rendering, diffing, and canonical export are designed to be stable enough for automation and code review.

FAQ

OrgSpec questions

The practical details for installing and using the CLI with local files.

Is the source public?

Not today. OrgSpec is distributed as an Orgonaut-hosted CLI binary. The format is portable, and the CLI works with local files, but the implementation remains private while the protocol matures.

Do I need an Orgonaut account?

No. Local OrgSpec commands such as import, validate, render, diff, and export do not require an Orgonaut account.

What platforms are supported?

macOS Apple Silicon, macOS Intel, Linux x86-64, and Linux ARM64.

Can it read my HRIS export?

The first CLI release supports CSV imports with manager-email, manager-id, and department-path mapping presets. More HRIS-specific presets can be added later.

Are the ecosystem integrations live today?

No. The ecosystem section describes the systems OrgSpec is designed to support through generators, validators, visualizers, benchmarks, and exchange tools. Ecosystem tooling is being developed progressively, starting with OrgSpec for Jira. Existing Orgonaut integrations remain described separately on the Orgonaut integrations page.

Does OrgSpec replace Orgonaut?

No. OrgSpec is the portable organization specification and data layer. Orgonaut is the scenario-planning platform for collaboration, governance, imports, AI assistance, metrics, and visual workflows.

Does OrgSpec include scenarios?

No. A file can represent a current or future structure, but scenarios and snapshots are not top-level OrgSpec schema entities.

Does OrgSpec handle AI agents and robots?

Yes. person, agent, and robot are core actor kinds in OrgSpec v0.1.

Can I use OrgSpec in Git?

Yes. OrgSpec files are JSON or YAML, and the CLI can export deterministic canonical JSON and Markdown diffs.

Start locally

Start with a spreadsheet. End with structured org data.

Install OrgSpec, convert a CSV, validate the structure, and render the chart locally in minutes.

Install OrgSpec Read the OrgSpec CLI docs