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/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: coo/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.
/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 OPI spec includes 51 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.
/top