OpenGAP: A Git-Native Standard for Portable AI Agent Definitions

The Problem OpenGAP Addresses: Agent Definitions Tied to a Single Framework

Every major AI framework (Claude Code, OpenAI, LangChain, CrewAI, AutoGen) stores agent configuration in its own format. Moving an agent from one to another means rewriting prompts, rules, and tool schemas from scratch, and version-controlling those definitions is left to whoever set up the project. There is no standard for what a portable agent definition looks like, so organizations that run more than one framework end up with fragmented, duplicated configuration.

OpenGAP addresses this by defining the agent as a set of versioned files in a plain git repository. The standard names the specific files and their purpose; the CLI validates that definition and exports it to any supported framework. The idea, as the README states, is that cloning a repository gives you an agent without further ceremony.

Repository Layout: Two Required Files and a Set of Optional Modules

An OpenGAP repository needs only two files to be valid. The first is `agent.yaml`, the manifest that declares the agent's name, version, model preference, skills, tools, and optional compliance rules. The second is `SOUL.md`, which defines the agent's identity, personality, communication style, and values.

The README documents the full optional set:

my-agent/
│
│   # ── Core Identity (required) ──────────────────────────
├── agent.yaml              # Manifest — name, version, model, skills, tools, compliance
├── SOUL.md                 # Identity, personality, communication style, values
│
│   # ── Behavior & Rules ──────────────────────────────────
├── RULES.md                # Hard constraints, must-always/must-never, safety boundaries
├── DUTIES.md               # Segregation of duties policy and role boundaries
├── AGENTS.md               # Framework-agnostic fallback instructions

Beyond these, the standard defines `memory/runtime/` for live agent state, a `hooks/` folder with `bootstrap.md` and `teardown.md` for lifecycle events, a `knowledge/` folder for entity relationships, and a `workflows/` folder for deterministic multi-step execution. None of these are required for a minimal agent, but each has a defined role that any compliant tool must respect. The modular design means that an agent can start with only `agent.yaml` and `SOUL.md` and acquire capabilities incrementally.

Segregation of Duties and Financial Compliance in agent.yaml

One of the more concrete design choices in OpenGAP is first-class support for regulatory compliance. The `agent.yaml` manifest accepts a `compliance.segregation_of_duties` block that declares roles, which role combinations are forbidden, which agents hold which roles, and how handoffs between roles must be structured. The README gives an example targeting financial workflows:

compliance:
  segregation_of_duties:
    roles:
      - id: maker
        description: Creates proposals
        permissions: [create, submit]
      - id: checker
        description: Reviews and approves
        permissions: [review, approve, reject]
    conflicts:
      - [maker, checker]         # maker cannot approve own work
    assignments:
      loan-originator: [maker]
      credit-reviewer: [checker]
    handoffs:
      - action: credit_decision
        required_roles: [maker, checker]
        approval_required: true
    enforcement: strict

With `enforcement: strict`, the validator catches violations before deployment. This means a team can define who can create, who can approve, and which combinations are illegal, and let `opengap validate` enforce it in CI rather than relying on manual process checks. The README mentions FINRA, Federal Reserve, and SEC as use cases, though it does not document which specific rules map to which regulations.

Installing the opengap CLI and Running the Validator

The `opengap` CLI is published to npm as `@open-gitagent/opengap`. It was previously published under the names `@open-gitagent/gapman` and `@open-gitagent/gitagent`; the README notes that the `gitagent` command is installed as an alias for backward compatibility. The package requires Node 18 or later, which is declared in `package.json` under `engines`.

The README recommends running the validator in CI via GitHub Actions:

opengap validate

This command checks the repository against the OpenGAP specification, reports role conflicts in the segregation of duties block, and can block a merge if the agent definition is malformed. Version 0.5.0, released on 2026-07-02, added three flags for Claude Code session management: `--continue`, `--resume`, and `--session-id`. The README does not document what these flags accept as values beyond the release title, so consulting the current CLI help output before relying on them is advisable.

SkillsFlow: Deterministic Workflows Without LLM Discretion

OpenGAP includes a workflow definition format called SkillsFlow, stored as YAML files in the `workflows/` folder. Each workflow declares triggers, steps, dependencies between steps, and data flowing between them using `${{ }}` template syntax. The README gives a code review pipeline as an example:

name: code-review-flow
description: Full code review pipeline
triggers:
  - pull_request

steps:
  lint:
    skill: static-analysis
    inputs:
      path: ${{ trigger.changed_files }}

  review:
    agent: code-reviewer
    depends_on: [lint]
    prompt: |
      Focus on security and performance.
      Flag any use of eval() or raw SQL.
    inputs:
      findings: ${{ steps.lint.outputs.issues }}

The purpose is explicit: the README states that SkillsFlow provides deterministic, multi-step execution where every run follows the same path with no LLM discretion on execution order. Steps can invoke skills, delegate to other agents, or run shell tools. The `depends_on` field orders steps; the `prompt` field overrides the agent's default instruction for that step. This makes SkillsFlow different from an agentic loop where the model decides the next action at runtime.

Limitations: Runtime Orchestration Stays in the Framework

OpenGAP is explicit about its scope boundary. The README states what ports cleanly to the standard (system prompts, persona definitions, constraints, tool schemas, role policies, model preferences) and what stays in the originating framework (runtime orchestration, state machines, graph wiring, live tool execution, memory I/O, iterative loops). An OpenGAP repository does not run the agent; it only describes it.

This is a real constraint for teams evaluating whether to migrate from LangGraph or CrewAI. Moving the identity layer into OpenGAP files is the proposed value, but the execution infrastructure stays where it is. If a team's primary pain is runtime behavior rather than agent definition portability, OpenGAP does not address it.

A second limitation is that the RELATED SEARCHES signal shows no meaningful organic search volume for this project by name, suggesting the adapter ecosystem and community documentation are still in early formation. The standard is at v0.5.0, the `gitagent` alias exists for backward compatibility from earlier names, and the spec lives in `spec/SPECIFICATION.md` within the repository. The project does not document how to handle secret rotation or how to update a deployed agent without downtime, so teams with those requirements should plan the operational process themselves before committing to the standard.

Editorial conclusion

Teams that run coding agents across several frameworks and need to version agent prompts, rules, and compliance policies alongside code will find OpenGAP's file-based structure a practical foundation. It is a poor fit for teams that want a runtime orchestration engine: the README is explicit that execution, state machines, and live tool calls stay in the framework, while OpenGAP only carries the identity layer. Before adopting it, verify that your chosen frameworks have existing OpenGAP adapters, since the adapter ecosystem is still forming around a standard that reached v0.5.0 in July 2026.

Frequently asked questions

Official sources

1. License: MIT
2. open-gitagent/opengap on GitHub
3. Project website
4. README
5. Releases