Most organizations run on slide decks, static org charts, and unwritten rules. Roles live in someone's head. Decision rights are tribal knowledge. When something changes, nobody updates the slides.
That was always inefficient. Now it's becoming a structural risk — for two reasons.
Organizations drift. Like a river, they naturally diverge from their intended design. Committees stop meeting. Decision authority shifts informally. Roles accumulate responsibilities nobody wrote down. By the time you notice, the org chart is fiction.
AI agents are entering organizations. They handle support, write code, make decisions. And they operate on what they can read. An agent with access to your data but no understanding of your decision structures, escalation paths, or governance guardrails will optimize for the wrong thing. Confidently. At scale. Without a machine-readable org model, there is no permission system, no scope, no accountability — just an agent with a credit card and good intentions.
Software engineering solved versioning, review, and deployment decades ago. Org as Code applies those same principles to organizational structure, governance, and intent.
Define it. Version it. Detect when reality diverges. Make it legible — to people and to machines.
/Principles
Structure as Code
Roles, teams, and responsibilities defined in version-controlled files. The org chart is never out of date because it is the source of truth.
Governance as Logic
Decision rights, escalation paths, and trade-off logic as reviewable, testable rules. Not buried in a wiki — expressed as code that humans and AI agents can read, query, and act on.
Change as Pull Request
Every restructuring is a pull request. Reviewed, discussed, traceable. No surprise reorgs — every change carries context and rationale.
Reality as Test Suite
Validate that structure matches how work actually flows. Detect drift — attendance gaps, informal authority shifts, broken cadences — before they become conflicts. CI/CD for your organization.
Evolution as Deployment
Incremental rollouts, not big-bang reorgs. A 20-person startup and a 2,000-person enterprise use the same principles, different implementations.
Knowledge as Documentation
How we work is always readable, searchable, current — by people and by machines. Onboarding takes hours, not months. Ask "Who approves budgets over 10k?" and get an answer, not a meeting.
/OPI —
Organizational Programming Interfaces
APIs define how software components communicate. OPIs define how organizational units interact. Each unit declares:
- Mandate — What it owns and what it's accountable for
- Interfaces — What it receives, delivers, from whom, at what cadence
- Governance — Decision frameworks (DACI, RAPID, consent) with explicit authority and trade-off logic
- Roles — Reusable role definitions with responsibilities, authority levels, and qualifications. Not just names on an org chart — machine-readable job architectures
- Agents — AI and automation agents as first-class organizational citizens. Scoped to units, bound by governance, with explicit permissions and human-in-the-loop policies
- Decision Flows — Where decisions travel across units, under what conditions, with SLAs
- Drift Detection — Monitor divergence between intended structure and organizational reality. Attendance drift, decision drift, cadence drift — surfaced automatically, not discovered in a crisis
- Schedule — Calendar-ready timing with recurrence rules (iCal export)
Meetings and committees are first-class entities with members, governance, inputs, and outputs. Not just a calendar invite — a contractual interface.
The result: organizational intent becomes explicit. Who decides what, under which conditions, with what authority. No decision lives in someone's head. It's in the code. And when reality diverges from intent, the system tells you.
/top/OKF Interoperability —
Governance on an Open Substrate
In June 2026, Google shipped the Open Knowledge Format (OKF) — a deliberately minimal, untyped standard for versioned, agent-readable knowledge in plain Markdown. Same instinct as Org as Code, one layer down: OKF is the open substrate. OPI is the strict, typed, validatable governance layer on top.
As of OPI v0.6, the two snap together. OPI stays the single source of truth — strict YAML, JSON Schema, 103 validation rules. But it now exports losslessly to OKF, so your governance model travels on an open standard: any OKF reader — a static visualizer, an LLM agent, another OPI instance — can consume it without an OPI SDK.
Strict, typed, validatable. Roles, decision rights, agents, drift detection — with a controlled type vocabulary and 103 rules. Die Strenge ist der Punkt.
Minimal, untyped, permissive. One required field (type), untyped links, no central registry — the lingua franca governance travels in.
The export is a generated projection, not a second source of truth: the OPI YAML stays canonical, the bundle is regenerated on change. Round-trip import (orgspec import --okf) reads a bundle back — lossless out, best-effort in. And v0.6 adds a first-class knowledge graph (knowledge[]) that lives beside structure: where decisions record what was decided, knowledge records what is known.
Strict producer, permissive consumer. Governance you can validate — portability you can publish.
/top/What You Get
Onboarding in hours, not months
How you work is readable, searchable, current. New people — and new agents — ask the system, not the room.
No surprise reorgs
Drift is detected while it's cheap to fix — expected vs. actual, surfaced automatically, not discovered in a crisis.
Governance you can audit
Who decides what is written down, versioned, and reviewable — for people and AI agents alike.
/Example
team:
name: Customer Platform Team
type: cross-functional
mandate: "Own the customer-facing platform end-to-end"
roles:
- role: product-owner
accountabilities:
- backlog-prioritization
- stakeholder-alignment
- outcome-tracking
- role: tech-lead
accountabilities:
- architecture-decisions
- code-review-standards
- role: team-member
count: 4
skills: [frontend, backend, qa]
rituals:
- name: Sprint Planning
cadence: bi-weekly
duration: 90min
- name: Architecture Review
cadence: monthly
decision_framework: consent
decisions:
- type: product
authority: product-owner
escalation: head-of-product
- type: technical
authority: tech-lead
input_from: [team-member]
- type: process
authority: team
framework: consent
interfaces:
receives_from:
- source: product-strategy
artifact: quarterly-objectives
format: yaml
sends_to:
- target: stakeholders
artifact: sprint-review
cadence: bi-weekly
- target: platform-team
artifact: api-contracts
format: openapiAI agents as organizational citizens — scoped, governed, auditable:
agents:
- id: support-triage
type: ai
purpose: "Classify and route incoming support tickets"
scope:
units: [customer-platform]
permissions:
may_read: [tickets, knowledge-base]
may_write: [ticket-classification]
may_decide: [routing]
human_in_the_loop:
required_for: [escalation, refund]
owner: tech-lead
status:
drift:
- type: decision
expected: "product-owner approves backlog changes"
actual: "tech-lead has approved last 12 backlog changes"
severity: warning
detected: 2026-03-01And this is how decisions flow across units:
flow:
name: Budget Approval
type: decision
trigger: "Unit lead identifies budget need"
path:
- station: delivery-lead-sync
action: identify
output: budget-request
- station: steering-committee
action: approve
condition: "amount > 10k EUR"
governance:
framework: DACI
driver: head-of-delivery
approver: coo
sla: "Next meeting (max 14d)"
- station: board
action: ratify
condition: "amount > 50k EUR"
sla: "Next Board meeting (max 90d)"
fallback:
timeout: 14d
action: escalate
to: cooAnd orgspec export --target okf projects it losslessly onto the open OKF substrate — agent-readable, no OPI SDK required:
---
okf_version: "0.1"
---
# Organization: Product Organization
## Units
* [Product Organization](/units/product.md) - Define product strategy and user success
## Decisions
* [Adopt Jobs-to-Be-Done framework …](/decisions/dec-P001.md) - active, product-board
## Knowledge
* [Jobs-to-Be-Done Framework](/knowledge/jtbd-framework.md) - Discovery methodology framing demand as jobs/Compare
| Traditional Tools* | Org as Code | |
|---|---|---|
| Change history | Per file, isolated, no overarching context | Full git log across all structures |
| Review process | Comments in isolated documents | Pull request with structured approval |
| Consistency | Manual cross-referencing | Automated validation (CI/CD) |
| AI & agent readability | Agents can't read slide decks or tribal knowledge | Agents query structure, decisions, and intent directly |
| Agent governance | Separate RBAC systems, no org-native permissions | Agents scoped to units with governance guardrails built in |
| Drift detection | Discovered in crisis or annual review | Continuous monitoring: expected vs. actual, surfaced automatically |
| Visualization | Static, manually maintained charts | Auto-generated from code |
| Onboarding | Scattered across files and tribal knowledge | Navigable, self-explaining system |
* Slide decks, spreadsheets, intranet wikis, org chart editors, proprietary HR software, and shared drives.
/topOrganizations don't fail because people don't care. They fail because what matters was never written down — in a format that anyone, or anything, could act on. I'm building Org as Code to change that. If this resonates, I'd love to hear from you.
/Read
Why AI agents fail when no one writes down what the organization actually wants — and how Org as Code closes that gap.
Same instinct, different layer: how the open substrate (OKF) and the typed governance layer (OPI) snap together — and why strict producers and permissive consumers are the key.
/Get Started
Org as Code is open source and early stage. The spec, examples, and tooling are evolving — contributions and feedback are welcome.
Pre-built templates for common models — Spotify, Holacracy, traditional hierarchy, consulting firm — give you a starting point. Fork one, adapt it, iterate.
The current stable spec — OPI v0.8 (tagged v0.8.0: visibility tiers, decision lifecycle, ai: governance, Serving Profile, decision effect and approval) — includes 103 validation rules and a full JSON Schema, so your org definition can be validated automatically — in CI/CD, in your editor, or by an AI agent.
v0.8 is called Effect and Legitimacy: a decision now carries whether it was entitled to bind and whether it ever took effect, as two separate dated facts — so what did we decide and never carry? comes back with a number instead of a silence. Fully additive; every v0.4 through v0.7 document validates unchanged. Feedback and design partners welcome.
/top