OpenGAP: turning a git repository into a portable agent definition
A framework-agnostic, git-native standard for defining AI agents
At a glance
- What is it?
- OpenGAP is a spec plus a reference CLI that stores an AI agent as files in a git repo. The interesting part is the directory contract and the segregation-of-duties validator, not the export story, which the README leaves mostly unshown.
- Who is it for?
- Adopt OpenGAP if your agents are already reviewed through pull requests and you want that review trail to cover prompts, skills and role boundaries in one place, and if you can live with a spec still marked v0.1.0. Do not adopt it if you need a runtime: the README describes a definition format and a validator, not an execution engine, and the adapter claim is not backed by any command in the material.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 75 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is that agent definitions do not travel
Every framework stores an agent differently. A LangChain agent lives in Python objects. A CrewAI crew lives in its own role and task classes. Claude Code reads a file. Moving an agent between those worlds means rewriting it, and rewriting it means the review history of the original is lost. OpenGAP's answer is to make the repository itself the agent: clone the repo, and you have the definition, with the commit log attached. The README states the goal plainly, that there is no universal, portable way to define an agent that works across Claude Code, OpenAI, LangChain, CrewAI, and AutoGen. Whether that portability is delivered is a separate question, and the material answers it weakly. What is clearly delivered is a file layout and a validator. The audience is teams who already treat prompts and tool configs as code under review, and who need a second party (an auditor, a compliance officer, a downstream team) to read the agent without installing the framework that runs it.
The directory contract: two required files, everything else optional
Only agent.yaml and SOUL.md are required. agent.yaml is the manifest: name, version, model, skills, tools, compliance. SOUL.md holds identity, personality, communication style and values. That split matters more than it looks. Machine-readable configuration goes in YAML so tooling can parse it; the parts that shape behaviour in prose go in Markdown so a human reviewer can diff them. Around those two files sit optional directories: RULES.md for hard constraints, DUTIES.md for role boundaries, AGENTS.md as a framework-agnostic fallback, skills/ for capability modules each with a SKILL.md and scripts, tools/ for MCP-compatible YAML schemas, workflows/, knowledge/, memory/ with a runtime/ subfolder for dailylog.md and context.md, hooks/ for bootstrap.md and teardown.md, config/, compliance/, and agents/ for sub-agents that repeat the same structure recursively. There is also a .gitagent/ directory marked as runtime state and gitignored. That last detail is the design decision worth noting: the definition is versioned, the live state is not. A team that wants to audit what an agent actually did will not find it in git under this layout.
Segregation of duties is the part with teeth
Most of the README describes conventions. The compliance block describes enforcement. Under compliance.segregation_of_duties you declare roles with ids and permission lists (maker with create and submit, checker with review, approve, reject), a conflicts list of role pairs that cannot be the same agent, an assignments map from business function to role, handoffs with required_roles and an approval_required flag, and an enforcement field set to strict. The README says the validator catches violations before deployment. That is a concrete, checkable claim, and it is the strongest reason to look at this project. It also has a visible shape limit: conflicts are expressed as pairs of roles. If your real control is "the same person may draft and review, but not approve above a threshold," a pairwise conflict matrix is the wrong instrument, and strict enforcement will either block legitimate work or be relaxed until it enforces nothing. The README does not show a conditional or threshold form.
Getting it running
The CLI is published on npm as @open-gitagent/opengap. The README notes the package was previously published as @open-gitagent/gapman and originally as @open-gitagent/gitagent, and that the gitagent command is still installed as an alias for backward compatibility, so older scripts keep working. Node 18 or later is required. The one command the README names explicitly is opengap validate, and it recommends running it on every push through GitHub Actions so bad merges are blocked. The material does not show the full command list, so treat validate as the confirmed entry point and check the published package for the rest. To start a new agent, the README's instruction is structural rather than a scaffold command: create agent.yaml with your name, version, model, skills and tools, create SOUL.md, and add the optional directories you need. If you use the compliance block, the roles, conflicts, assignments, handoffs and enforcement keys above are the ones to write.
What the material does not support
The README claims export to any framework with adapters. No adapter command, package name or configuration key appears in the supplied text. That is the central promise of a framework-agnostic standard, and it is the least documented part. Treat adapter support as unverified until you find it in the package. The same applies to the knowledge tree pattern: the README says knowledge/ stores entity relationships as a hierarchical tree with embeddings, but gives no schema, no embedding configuration and no runtime command that consumes it. The homepage at gitagent.sh is listed, and the spec lives at spec/SPECIFICATION.md in the repository, marked v0.1.0 in the badge. A v0.1.0 spec that has already been renamed twice (gitagent, then gapman, then OpenGAP) is a moving target. Pinning a version is not optional if you build on it.
The git-native patterns are conventions, not features
The README lists patterns that emerge from the file layout: human-in-the-loop review where an agent opens a branch and PR before merging a new skill or memory write, agent versioning where every change is a commit, branch-based deployment through dev, staging and main, and shared root-level context.md, skills/ and tools/ across a monorepo. None of these require code from OpenGAP. They require a team that already works this way. An agent that writes to memory/ and opens a PR is a workflow you have to build around the agent, and the README describes the pattern rather than a mechanism that enforces it. The one place the CLI does intervene is validate. That is the honest boundary of this project: it defines a shape and checks the compliance rules inside it.
Compared with a prompt-and-config repo
The obvious alternative is what many teams do now: keep prompts in a prompts/ directory, keep tool schemas next to the code that calls them, and rely on code review. That works, and it costs nothing to adopt. The difference is that a prompts directory has no schema. Nothing stops one agent's prompt from being a single string and another's from being a template with variables, and nothing validates that a reviewer role is distinct from an author role. OpenGAP imposes a fixed set of filenames and a YAML manifest, which is what makes validate possible. The trade is real: you accept a directory contract you did not design, and in exchange you get a checker that can fail a build. If your agents never leave one framework, that trade is probably not worth it. If a compliance function has to sign off on what an agent is allowed to do, the DUTIES.md plus segregation_of_duties pair is the part that a prompts directory cannot replace.
Licence, maintenance and upgrade cost
The project is MIT licensed, which permits commercial use and modification with attribution and no warranty. That is permissive and low-friction, and it also means there is no support obligation behind it. The release history shows v0.3.2 publishing gapman under both scoped and unscoped names, v0.4.0 as the rebrand to OpenGAP, and v0.5.0 adding Claude session continuation with --continue, --resume and --session-id. Three renames in the published package name across those releases is the concrete upgrade cost: any script, CI job or lockfile referencing @open-gitagent/gapman or @open-gitagent/gitagent needs auditing, even though the gitagent command alias is retained. Because the definition is plain files, the migration itself is cheap: agent.yaml and SOUL.md do not change shape when the CLI does. The expensive part is the compliance block, where a spec at v0.1.0 can change semantics between minor versions, and a validator that starts failing a previously passing conflict matrix will block merges.
Editorial conclusion
Adopt OpenGAP if your agents are already reviewed through pull requests and you want that review trail to cover prompts, skills and role boundaries in one place, and if you can live with a spec still marked v0.1.0. Do not adopt it if you need a runtime: the README describes a definition format and a validator, not an execution engine, and the adapter claim is not backed by any command in the material. Before committing, run npx @open-gitagent/opengap validate against an existing agent and check whether the segregation_of_duties block in agent.yaml can express your actual approval chain; if your conflict rules are not role-to-role pairs, the strict enforcement mode will not help you.
Community notes