Org As Code

org-as-code

The missing governance layer for AI agent teams.

[](CHANGELOG.md) [](https://python.org) [](LICENSE) [](#running-tests) [](#quick-start) [](#mcp-server) [](#cli-reference)

Turn organizational decisions into Git-native, auditable, version-controlled artifacts. Replace Slack threads and meeting notes with YAML files and immutable audit trails.

[Quick Start](#quick-start) · [Documentation](#the-pv-protocol) · [MCP Server](#mcp-server) · [Theory](THEORY.md) · [Examples](examples/)

---

pip3 install -r requirements.txt        # pyyaml + mcp — that's it
python3 org_cli.py dashboard            # see it live in 30 seconds
python3 org_cli.py create FEAT-003 feature "My first process" "Testing org-as-code" --agent coder
python3 org_cli.py verify               # check hash-chain integrity

---

The Problem

Organizations exist in people's heads — in Slack threads, meeting notes, and shared assumptions that dissolve the moment someone leaves the room. AI agents can't operate on that. They need something explicit, versioned, and machine-readable.

org-as-code encodes roles, responsibilities, and decision-making as Git-native artifacts — not as documentation, but as a system agents can actually run on.

---

Why This Exists

AI agents can code, review, deploy, and monitor. But they can't govern themselves — and neither can humans govern them through Slack threads and meeting notes.

org-as-code gives AI agents and humans a shared protocol for working together. One agent proposes, another validates. A human steps in when stakes are high. Every handoff is logged, every decision is traceable, every rejection drives a better next iteration. The P↔V protocol doesn't care whether a step is performed by Claude, GPT, a junior developer, or a CTO — it enforces the same rhythm of propose, validate, converge.

This means you can build teams where AI agents do the heavy lifting (proposals, implementations, reviews) while humans retain authority over critical decisions — without bottlenecking every step. The feature_v2 template demonstrates this: AI handles routine work autonomously, but processes with H(s) ≥ 0.8 automatically require human sign-off.

What you get

| | Feature | What it does | |---|---------|-------------| | P↔V | Protocol | Proposals oscillate with Validations — expand options, then contract to decisions | | H(s) | Priority Score | Calculated, not felt: w₁·urgency + w₂·commitment + w₃·demand + w₄·blocking | | E(x) | Convergence Score | Quadratic energy — one critical gap outweighs three minor ones | | AHP | Decision Engine | Multi-participant pairwise comparison with weighted aggregation and consistency check | | FDM | Process Dependencies | Cycle detection, parallel groups, impact scoring, living dependency register | | JSONL | Audit Trail | SHA-256 hash-chained, append-only, tamper-evident | | MCP | AI Agent Interface | 21 native tools over stdio transport | | CLI | Human Interface | 23 commands for operators | | YAML | Per-Process State | One state file per process — no merge conflicts |

---

Pairwise Decision Engine

When a decision involves multiple stakeholders with different weights, a single H(s) score isn't enough. org_decision.py adds AHP-based (Analytic Hierarchy Process) pairwise comparison as a native decision process type — no new dependencies beyond what org-as-code already requires.

Each participant compares options head-to-head. The engine computes individual priority vectors, checks consistency (CR = 0.20 by default) python3 org_decision.py aggregate --id DEC-001 --agent facilitator

4. Show result

python3 org_decision.py show --id DEC-001

Produces in `processes/DEC-001/`:
- `P.0_decision_session.yaml` — options, context, session metadata
- `V.N_vote_.yaml` — individual comparisons, priority vector, CR per voter
- `V.final_consensus.yaml` — aggregated ranking, verdict, mean CR, participant list

Role weights are configurable: `nedxis` participants carry 1.5× weight by default. All artifacts are hash-chained — the decision is as auditable as any other process in the system.

---

## Quick Start

### 1. Clone and configure

```bash
git clone https://github.com/syntriad/org-as-code.git
cd org-as-code
pip3 install -r requirements.txt

2. Register your agents

Edit registry/agents.yaml:

agents:
  - id: alice
    name: "Alice (Team Lead)"
    type: human
    interface: terminal
    skills: [strategic-review, final-validation, decision-making]
    status: active
    capacity: 5

  - id: coder
    name: "Coder (AI Agent)"
    type: ai
    interface: claude-code
    skills: [implementation, code-generation, testing]
    status: active
    capacity: 10

  - id: reviewer
    name: "Reviewer (AI Agent)"
    type: ai
    interface: ide
    skills: [technical-review, refactoring, testing]
    status: active
    capacity: 5

3. Start your first process

python3 org_cli.py create FEAT-001 feature \
  "Add user authentication" \
  "Implement JWT-based auth with refresh tokens" \
  --agent coder --priority 0.8

4. Let an AI agent validate

The assigned agent creates V.0_review.yaml in processes/FEAT-001/:

verdict: approved
confidence: 0.9
conditions:
  - "Add rate limiting before merge"
reviewed_by: reviewer

5. Commit and verify

python3 org_cli.py update FEAT-001 COMMITTED \
  --notes "Auth module complete. All tests pass."

python3 org_cli.py verify
# Chain integrity: VALID — no tampering detected.

Every step is logged in registry/artifacts.jsonl with hash-chain integrity.

---

The P↔V Protocol

Like a heartbeat (systole ↔ diastole), organizations need rhythm:

┌─────────────────────────────────────────┐
│              P ↔ V Protocol             │
├─────────────────────────────────────────┤
│                                         │
│   ┌─────────┐         ┌─────────┐      │
│   │    P    │────────▶│    V    │      │
│   │ Propose │         │Validate │      │
│   └─────────┘         └────┬────┘      │
│        ▲                   │           │
│        │     iterate       │           │
│        └───────────────────┘           │
│                                         │
│   P_READY → P_COMPLETE → V_COMPLETE    │
│                    → COMMITTED          │
│                    → ABANDONED          │
│                                         │
└─────────────────────────────────────────┘

P-steps (Production): Expand options, generate proposals V-steps (Validation): Contract, validate, select

This prevents two failure modes:

• Unbounded divergence — chaos, no decisions
• Frozen convergence — premature fixation, groupthink

---

Repository Structure

org-as-code/
├── registry/                ← Organization state (YAML)
│   ├── agents.yaml            Registered agents
│   ├── state.yaml             Process states (auto-generated index in per_process mode)
│   ├── tensions.yaml          Open problems/opportunities
│   ├── attractors.yaml        Strategic goals
│   ├── artifacts.jsonl        Immutable action log (hash-chained)
│   └── fdm.json               Dependency register (auto-generated)
│
├── processes/               ← All work (P,V artifacts + per-process state)
│   └── {ID}/
│       ├── state.yaml           Per-process state (in per_process mode)
│       ├── P.0_proposal.md      Proposals (expand)
│       └── V.0_review.yaml      Reviews (contract)
│
├── examples/                ← Real cases from independent evaluations
│   ├── SEC-001/               Security hardening (V.0 rejected, 6 artifacts)
│   └── PERF-001/              Performance optimization (V.0 rejected, 4 artifacts)
│
├── protocol/                ← Rules of the game
│   ├── config.yaml            Priority weights, thresholds, security
│   └── process_templates/     Reusable flows
│       ├── feature.yaml
│       ├── feature_v2.yaml    (with conditional human gate)
│       ├── bugfix.yaml
│       └── decision.yaml      (pairwise AHP — multi-participant)
│
├── tools/                   ← Maintenance utilities
│   ├── fix_hash_chain.py      Rebuild hash chain if corrupted
│   └── per_process_state.py   Migrate to per-process state files
│
├── org_mcp_server.py        ← MCP Server (21 tools, stdio transport)
├── org_cli.py               ← CLI interface (23 commands)
├── org_decision.py          ← Pairwise AHP decision engine
├── fdm.py                   ← Dependency graph engine (Tarjan, Kahn, stdlib only)
├── pyproject.toml           ← Package metadata (pip install org-as-code)
└── requirements.txt

---

CLI Reference

# Read commands
python3 org_cli.py status              # All processes + state
python3 org_cli.py tensions            # Open tensions
python3 org_cli.py attractors          # Strategic goals
python3 org_cli.py agents              # Registered agents
python3 org_cli.py health              # Health metrics
python3 org_cli.py log [--limit N]     # Recent artifact log
python3 org_cli.py show FEAT-001       # Process detail + artifacts
python3 org_cli.py verify              # Verify hash-chain integrity
python3 org_cli.py dashboard           # Combined overview

# Write commands
python3 org_cli.py create FEAT-002 feature "Title" "Description" --agent coder --priority 0.8
python3 org_cli.py update FEAT-002 COMMITTED --notes "Done"
python3 org_cli.py artifact coder V.0_review "Approved" --process FEAT-002
python3 org_cli.py tension-add "Title" "Description" --priority 0.7
python3 org_cli.py tension-resolve T-2026-001 "Resolved via process assignment"
python3 org_cli.py priority --urgency 0.9 --demand 0.8 --blocking 0.7
python3 org_cli.py energy --gaps 0.8 --inconsistencies 0.2 --evidence 0.6
python3 org_cli.py convergence FEAT-001  # Show E(x) trajectory over V-steps

# Dependency commands
python3 org_cli.py deps-add FEAT-002 FEAT-001      # FEAT-002 depends on FEAT-001
python3 org_cli.py deps-remove FEAT-002 FEAT-001    # Remove dependency
python3 org_cli.py deps FEAT-002                     # Show upstream + downstream deps
python3 org_cli.py deps-analyze                      # Full FDM analysis (parallel groups, cycles)

# Git sync
python3 org_cli.py sync                          # Pull only
python3 org_cli.py sync "commit message" --agent coder  # Commit + push

# Decision engine (pairwise AHP)
python3 org_decision.py session --id DEC-001 --options "A" "B" "C" --agent facilitator
python3 org_decision.py vote --id DEC-001 --participant alice
python3 org_decision.py aggregate --id DEC-001 --agent facilitator
python3 org_decision.py show --id DEC-001

---

MCP Server

org_mcp_server.py gives AI agents native tools to interact with the organization:

Read tools

| Tool | Description | |------|-------------| | org_read_state | Read all process states | | org_read_tensions | Read open problems/opportunities | | org_read_attractors | Read strategic goals | | org_read_agents | Read registered agents | | org_read_health | Read system health metrics | | org_read_process | Read a specific process and its artifacts | | org_read_artifacts | Read recent entries from audit log | | org_read_convergence | Read convergence history (E(x) over V-steps) |

Write tools

| Tool | Description | |------|-------------| | org_update_state | Update process state | | org_create_process | Create a new process (P.0), optional depends_on | | org_log_artifact | Append to immutable audit log | | org_create_tension | Register a new tension | | org_resolve_tension | Mark a tension as resolved | | org_add_dependency | Add a dependency between two processes | | org_remove_dependency | Remove a dependency between two processes |

Governance tools

| Tool | Description | |------|-------------| | org_calculate_priority | Calculate priority score H(s) | | org_calculate_energy | Calculate convergence score E(x) | | org_verify_chain | Verify hash-chain integrity of audit log | | org_analyze_dependencies | Full dependency graph analysis (cycles, parallel groups, bottleneck) | | org_read_dependencies | Read the current FDM dependency register | | org_git_sync | Pull, commit, push changes |

Setup

Add to your Claude Code MCP configuration (~/.claude.json):

{
  "mcpServers": {
    "org-as-code": {
      "command": "python3",
      "args": ["org_mcp_server.py"],
      "env": {
        "ORG_REPO_PATH": "/path/to/org-as-code"
      }
    }
  }
}

---

Priority Score

Priority is not a feeling. It is a calculation:

H(s) = w₁·urgency + w₂·commitment + w₃·demand + w₄·blocking

Default weights (configurable in protocol/config.yaml):

| Weight | Value | Component | |--------|-------|-----------| | w₁ | 0.30 | Urgency — how time-sensitive | | w₂ | 0.20 | Commitment — how invested we are | | w₃ | 0.30 | Demand — external need | | w₄ | 0.20 | Blocking — how much this blocks other work |

Thresholds:

• H(s) ≥ 0.8 → Escalate to human
• H(s) ≥ 0.5 → Action required
• **H(s)

org-as-code is part of the SYNTRIAD ecosystem.

[](https://github.com/SYNTRIAD/org-as-code) [](https://zenodo.org/records/17618208)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SYNTRIAD
• Source: SYNTRIAD/org-as-code
• License: MIT

Install and usage instructions live in the source repository linked above.