A governance framework for production-grade autonomous AI operations.
Platform-agnostic. Works with Claude, OpenAI, LangChain, CrewAI, AutoGen, or any agent system.
If you find SOSA useful, please ⭐ star this repo — it helps other developers discover the framework and motivates us to keep building.
git clone https://github.com/MSApps-Mobile/sosa.git && cd sosa
./scripts/sosa-lint.sh examples/compliant-agent # ✅ PASSED
./scripts/sosa-lint.sh examples/non-compliant-agent # ❌ FAILED — one pillar, one lineThose two agents differ by exactly one line: the compliant one references its
credentials from the environment, the other pastes them into the role spec. That
is the whole Secured pillar in a diff. Copy
examples/compliant-agent/role-spec.yaml
as the starting point for your own agent.
AI agents are shipping to production without governance standards. Bug bounties find vulnerabilities after deployment. Security researchers discover prompt injection paths in live systems. Token costs spiral because nobody measures waste.
Every agent framework gives you tools to build agents. None of them tell you how to govern them.
SOSA fills that gap. It prevents architectural vulnerabilities before an agent ever runs — not after.
Traditional AI safety treats human oversight as all-or-nothing. SOSA introduces a trust gradient:
| Mode | When Applied | Behavior |
|---|---|---|
| Autonomous | Proven low-risk actions | Execute without human approval |
| Notify | Medium-risk actions | Execute and alert the human |
| Approve | High-risk actions | Halt and require explicit confirmation |
| Blocked | Prohibited actions | Never permitted regardless of trust level |
The trust gradient is dynamic — agents that consistently succeed earn expanded autonomy. Agents that fail or exceed scope get reduced autonomy automatically.
In practice: An outreach agent can't send 500 emails without your sign-off. An agent that consistently produces clean PRs earns the right to auto-merge formatting changes.
Agents follow Plan → Act → Verify. Tasks are coordinated through DAG execution, not ad-hoc messaging. Orchestration demands efficiency:
- Skill descriptions must be lean and trigger-accurate
- Shared rules externalized to structured stores, not duplicated across agents
- Unused tool connectors eliminated
- Task frequency matches actual change cadence
- Token budgets are treated as shared, finite resources
Waste is an orchestration failure, not just a performance issue.
| Layer | Requirement |
|---|---|
| Credentials | Never hardcoded — use environment variables or secure stores |
| Tool Access | Declared capability sets with principle of least privilege |
| Input | Prompt injection scanning on all external data |
| Dependencies | Pinned versions for all packages and MCP servers |
| Output | Audit logging of all agent actions and decisions |
| Context | Session isolation — no cross-agent context contamination |
Every SOSA agent is a tuple A = (R, T, M, P):
| Component | Symbol | Definition |
|---|---|---|
| Role | R | What the agent does, what it doesn't do, and its operational boundaries |
| Tools | T | Explicit manifest of every tool with declared permissions and scope |
| Memory | M | Defined context store with scope: session, persistent, or shared |
| Planning | P | How the agent decides: reactive (trigger-based), proactive, or scheduled |
Informal agents — those without complete definitions — are not SOSA-compliant.
Every SOSA agent operation follows a structured three-phase loop:
- Assess resource costs (tokens, API calls, time)
- Define success criteria before acting
- Check permissions against the current trust gradient
- Identify escalation points — what triggers a human handoff
- Execute with full logging of every tool invocation and result
- Enforce escalation thresholds: cost, risk, or scope breaches stop execution
- Track all API calls, file operations, and external communications
- Maintain rollback capability wherever technically feasible
- Evaluate results against the pre-defined success criteria from Plan
- Measure efficiency: tokens consumed, time elapsed, API calls made
- Generate a structured audit trail entry
- Update the trust gradient based on outcome
Escalation protocol: When any agent encounters a condition exceeding its trust level — stop immediately, log with full context, escalate to human with clear options, wait for explicit decision, resume only after authorization.
SOSA defines three compliance levels, each a strict superset of the previous:
| Level | Name | Requirements |
|---|---|---|
| L1 | Basic | Role spec, pinned dependencies, no hardcoded secrets, basic docs |
| L2 | Standard | L1 + injection scanning, audit logging, capability declaration, token efficiency, error handling |
| L3 | Full | L2 + approval gates, Plan→Act→Verify loops, dynamic trust gradient, cross-agent isolation, system-wide auditing, efficiency benchmarks |
SOSA extends naturally to AI coding agents — systems that autonomously generate, review, refactor, and deploy code. The "SOSA for Code" paper introduces:
- Plan-Code-Verify — a code-specific instantiation of Plan→Act→Verify for the software development lifecycle
- Graduated code supervision — five levels (L0–L4) from auto-merge formatting fixes to human-only production deploys
- Multi-agent development coordination — orchestrated task DAGs preventing merge conflicts and architectural drift
- Codebase knowledge models — the extended tuple A_code = (R, T, M, P, K) where K captures architectural patterns, conventions, and technical debt
- Trust gradients for repositories — agents earn autonomy per-repo through demonstrated reliability
| Level | Scope | Example | Review |
|---|---|---|---|
| L0 — Auto | Formatting, comments, docs | Fix typo in README | None (auto-merge) |
| L1 — Async | Single-file, non-critical | Add unit test | Post-merge review |
| L2 — Pre-merge | Multi-file, business logic | New API endpoint | 1 human reviewer |
| L3 — Gated | Security, infra, shared libs | Auth flow change | Senior + security review |
| L4 — Prohibited | Production deploy, DB migration | Schema migration | Human-only execution |
📄 Read the full paper: SOSA™ for Code: A Methodology for Governing AI Coding Agents (Shatz, 2026)
SOSA is platform-agnostic. The formal agent definition maps to concrete artifacts in every major framework:
| Platform | Role Spec | Tool Manifest | Trust Gradient |
|---|---|---|---|
| Claude Code / Cowork | SKILL.md |
plugin.json + MCP declarations |
Hook lifecycle |
| OpenAI Agents SDK | instructions param |
tools[] array |
Guardrail validators |
| LangChain / LangGraph | System prompt | Tool bindings | Graph conditionals |
| CrewAI | role / goal / backstory |
tools list |
Task delegation |
| OpenAI AgentKit | Agent Builder node | Connector Registry | Visual DAG |
| AutoGen | Agent config | Message filter | Human-in-the-loop |
🔗 OpenAI-specific implementation: sosa-openai — Trust gradients, compliance auditing, and structured supervision for OpenAI Agents SDK and AgentKit.
Production-ready plugins that implement SOSA governance, available in the MSApps Claude Plugins marketplace:
| Plugin | What it does | Install |
|---|---|---|
| sosa-governor | Real-time governance layer — classifies, gates, and logs every MCP tool call | sosa-governor@msapps-plugins |
| sosa-orchestrator | Token-aware task prioritization and budget management | sosa-orchestrator@msapps-plugins |
| sosa-compliance-checker | Audit any plugin ecosystem against SOSA — catches hardcoded keys, missing gates, injection vulnerabilities | sosa-compliance-checker@msapps-plugins |
| token-efficiency-audit | Find and fix token waste — typical savings: 20–50% | token-efficiency-audit@msapps-plugins |
# Install the full SOSA suite
/plugin marketplace add MSApps-Mobile/claude-plugins
/plugin install sosa-governor@msapps-plugins
/plugin install sosa-orchestrator@msapps-plugins
/plugin install sosa-compliance-checker@msapps-plugins
/plugin install token-efficiency-audit@msapps-pluginsPro tip: Run
sosa-compliance-checkeron all your installed plugins — not just ours. It catches issues in any plugin.
SOSA compliance is enforced at three levels:
Every PR and push to main runs .github/workflows/sosa-lint.yml — four-pillar compliance check, secret scanning, role spec presence verification, and token efficiency warnings. PRs that fail cannot be merged.
The workflow lints a known-positive and a known-negative example and asserts both verdicts. A linter that has only ever been run against passing input has not been tested: if the negative control ever passes, the rule has failed open, and that is a security finding — see SECURITY.md.
./scripts/sosa-lint.sh /path/to/your/agentEvery PR includes the four-pillar checklist:
- Supervised: Are approval gates defined for high-risk actions?
- Orchestrated: Is the execution efficient? No bloated context or redundant tools?
- Secured: No hardcoded secrets? Injection scanning? Least privilege enforced?
- Agents: Role spec complete? Tool manifest declared? Memory scope defined?
| Document | Description |
|---|---|
| Specification v1.0 | Complete SOSA technical specification — principles, execution model, compliance levels, platform mappings |
| SOSA for Code | Extended white paper on governing AI coding agents across the SDLC |
| Enforcement Guide | CI/CD, local linting, and human review enforcement |
| SOSA for OpenAI | Governance layer for OpenAI Agents SDK and AgentKit |
| Claude Plugins | 31 production plugins built on SOSA, including 4 SOSA governance plugins |
| Examples | A compliant and a non-compliant reference agent — the linter's positive and negative controls |
| Contributing | The four contribution shapes, ground rules, and the local check to run before pushing |
| Security Policy | How to report a linter rule that fails open, or spec guidance that would make a system less safe |
OpsAgent by MSApps — 18+ production agent types running under SOSA governance since early 2025, across sales, recruiting, invoicing, security research, outreach, and development workflows.
Audit your existing agents:
./scripts/sosa-lint.sh /path/to/your/agentInstall SOSA governance for Claude:
/plugin marketplace add MSApps-Mobile/claude-plugins
/plugin install sosa-compliance-checker@msapps-pluginsApply to your own framework:
- Define each agent as a tuple (R, T, M, P)
- Classify actions by impact level and assign supervision thresholds
- Implement the Plan → Act → Verify loop
- Pin dependencies, scan inputs, log everything
- Start at L1 — graduate to L3 as governance matures
| Repository | Description |
|---|---|
| sosa-spec | Platform-agnostic SOSA specification (canonical spec source) |
| sosa-openai | SOSA governance layer for OpenAI Agents SDK and AgentKit |
| claude-plugins | 31 production Claude plugins built on the SOSA framework |
- 💬 Discussions — ran SOSA on a real agent fleet and something did not fit? These field reports are the most useful contributions we get.
- 🧩 Platform mappings — the easiest way in. You need to know one agent framework well, not SOSA.
- 🐛 Open an issue for bugs or spec ambiguities
- 🤝 CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md
- ⭐ Star the repo to help others find it
MIT — use it, fork it, build on it.
Created by Michal Shatz / MSApps
Part of the OpsAgent project.
Questions: michal@msapps.mobi | GitHub Issues
Built by MSApps · github.com/MSApps-Mobile/sosa