Skip to content
Back to search

opengap

A framework-agnostic, git-native standard for defining AI agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/open-gitagent--opengap/badge.svg)](/listings/open-gitagent--opengap)

HTML

<a href="/listings/open-gitagent--opengap"><img src="/api/listings/open-gitagent--opengap/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Install
npm i -g @open-gitagent/opengap

# Create a new agent
opengap init --template standard

# Validate
opengap validate

# View agent info
opengap info

# Export to system prompt
opengap export --format system-prompt

> `gitagent` is installed as an alias — all `opengap <cmd>` calls work as `gitagent <cmd>` too.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 426 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="hero.png" alt="OpenGAP — GitAgentProtocol (Open GAP)" width="700" />
  3. </p>
  4. # OpenGAP | your repository becomes your agent
  5. > **`opengap`** — the OpenGAP CLI, published as [`@open-gitagent/opengap`](https://www.npmjs.com/package/@open-gitagent/opengap). Previously published as `@open-gitagent/gapman` and originally `@open-gitagent/gitagent`; the `gitagent` command is still installed as an alias for backward compatibility.
  6. [![npm version](https://img.shields.io/npm/v/@open-gitagent/opengap)](https://www.npmjs.com/package/@open-gitagent/opengap)
  7. [![CI](https://github.com/open-gitagent/gitagent/actions/workflows/ci.yml/badge.svg)](https://github.com/open-gitagent/gitagent/actions/workflows/ci.yml)
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  9. [![Spec: v0.1.0](https://img.shields.io/badge/spec-v0.1.0-blue)](https://github.com/open-gitagent/gitagent/blob/main/spec/SPECIFICATION.md)
  10. [![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
  11. OpenGAP (the Git Agent Protocol) is a framework-agnostic, git-native standard for defining AI agents. Clone a repo, get an agent. `opengap` is its reference CLI.
  12. ## Why
  13. Every AI framework has its own structure. There's no universal, portable way to define an agent that works across Claude Code, OpenAI, LangChain, CrewAI, and AutoGen. **gitagent** fixes that.
  14. - **Git-native** — Version control, branching, diffing, and collaboration built in
  15. - **Framework-agnostic** — Export to any framework with adapters
  16. - **Compliance-ready** — First-class support for FINRA, Federal Reserve, SEC, and segregation of duties
  17. - **Composable** — Agents can extend, depend on, and delegate to other agents
  18. ## The Standard
  19. Your repository becomes your agent. Drop these files into any git repo and it becomes a portable, framework-agnostic agent definition — everything else (CLI, adapters, patterns) builds on top of it.
  20. ```
  21. my-agent/
  22. │
  23. │ # ── Core Identity (required) ──────────────────────────
  24. ├── agent.yaml # Manifest — name, version, model, skills, tools, compliance
  25. ├── SOUL.md # Identity, personality, communication style, values
  26. │
  27. │ # ── Behavior & Rules ──────────────────────────────────
  28. ├── RULES.md # Hard constraints, must-always/must-never, safety boundaries
  29. ├── DUTIES.md # Segregation of duties policy and role boundaries
  30. ├── AGENTS.md # Framework-agnostic fallback instructions
  31. │
  32. │ # ── Capabilities ──────────────────────────────────────
  33. ├── skills/ # Reusable capability modules (SKILL.md + scripts)
  34. │ └── code-review/
  35. │ ├── SKILL.md
  36. │ └── review.sh
  37. ├── tools/ # MCP-compatible tool definitions (YAML schemas)
  38. ├── workflows/ # Multi-step procedures/playbooks
  39. │
  40. │ # ── Knowledge & Memory ────────────────────────────────
  41. ├── knowledge/ # Reference documents the agent can consult
  42. ├── memory/ # Persistent cross-session memory
  43. │ └── runtime/ # Live agent state (dailylog.md, context.md)
  44. │
  45. │ # ── Lifecycle & Ops ───────────────────────────────────
  46. ├── hooks/ # Lifecycle event handlers (bootstrap.md, teardown.md)
  47. ├── config/ # Environment-specific overrides
  48. ├── compliance/ # Regulatory compliance artifacts
  49. │
  50. │ # ── Composition ───────────────────────────────────────
  51. ├── agents/ # Sub-agent definitions (recursive structure)
  52. │ └── fact-checker/
  53. │ ├── agent.yaml
  54. │ ├── SOUL.md
  55. │ └── DUTIES.md # This agent's role, permissions, boundaries
  56. ├── examples/ # Calibration interactions (few-shot)
  57. │
  58. │ # ── Runtime ───────────────────────────────────────────
  59. └── .gitagent/ # Runtime state (gitignored)
  60. ```
  61. Only two files are required: **`agent.yaml`** (the manifest) and **`SOUL.md`** (the identity). Everything else is optional — add what you need, ignore the rest.
  62. ## Patterns
  63. These are the architectural patterns that emerge when you define agents as git-native file systems.
  64. ### Human-in-the-Loop for RL Agents
  65. When an agent learns a new skill or writes to memory, it opens a branch + PR for human review before merging.
  66. <img src="patterns/human-in-the-loop.png" alt="Human-in-the-Loop" width="600" />
  67. ### Segregation of Duties (SOD)
  68. No single agent should control a critical process end-to-end. Define roles (`maker`, `checker`, `executor`, `auditor`), a conflict matrix (which roles can't be the same agent), and handoff workflows — all in `agent.yaml` + `DUTIES.md`. The validator catches violations before deployment.
  69. ```yaml
  70. compliance:
  71. segregation_of_duties:
  72. roles:
  73. - id: maker
  74. description: Creates proposals
  75. permissions: [create, submit]
  76. - id: checker
  77. description: Reviews and approves
  78. permissions: [review, approve, reject]
  79. conflicts:
  80. - [maker, checker] # maker cannot approve own work
  81. assignments:
  82. loan-originator: [maker]
  83. credit-reviewer: [checker]
  84. handoffs:
  85. - action: credit_decision
  86. required_roles: [maker, checker]
  87. approval_required: true
  88. enforcement: strict
  89. ```
  90. ### Live Agent Memory
  91. The `memory/` folder holds a `runtime/` subfolder where agents write live knowledge — `dailylog.md`, `key-decisions.md`, and `context.md` — persisting state across sessions.
  92. <img src="patterns/live-agent-memory.png" alt="Live Agent Memory" width="600" />
  93. ### Agent Versioning
  94. Every change to your agent is a git commit. Roll back broken prompts, revert bad skills, and explore past versions — full undo history for your agent.
  95. <img src="patterns/agent-versioning.png" alt="Agent Versioning" width="600" />
  96. ### Shared Context & Skills via Monorepo
  97. Root-level `context.md`, `skills/`, `tools/` are automatically shared across every agent in the monorepo. No duplication, one source of truth.
  98. <img src="patterns/shared-context.png" alt="Shared Context" width="600" />
  99. ### Branch-based Deployment
  100. Use git branches (`dev` → `staging` → `main`) to promote agent changes through environments, just like shipping software.
  101. <img src="patterns/branch-deployment.png" alt="Branch-based Deployment" width="600" />
  102. ### Knowledge Tree
  103. The `knowledge/` folder stores entity relationships as a hierarchical tree with embeddings, letting agents reason over structured data at runtime.
  104. <img src="patterns/knowledge-tree.png" alt="Knowledge Tree" width="600" />
  105. ### Agent Forking & Remixing
  106. Fork any public agent repo, customize its `SOUL.md`, add your own skills, and PR improvements back upstream — open-source collaboration for AI agents.
  107. <img src="patterns/agent-forking.png" alt="Agent Forking & Remixing" width="600" />
  108. ### CI/CD for Agents
  109. Run `opengap validate` on every push via GitHub Actions. Test agent behavior in CI, block bad merges, and auto-deploy — treat agent quality like code quality.
  110. <img src="patterns/ci-cd-agents.png" alt="CI/CD for Agents" width="600" />
  111. ### Agent Diff & Audit Trail
  112. `git diff` shows exactly what changed between agent versions. `git blame` traces every line to who wrote it and when — full traceability out of the box.
  113. <img src="patterns/agent-diff-audit.png" alt="Agent Diff & Audit Trail" width="600" />
  114. ### Tagged Releases
  115. Tag stable agent versions like `v1.1.0`. Pin production to a tag, canary new versions on staging, and roll back instantly if something breaks.
  116. <img src="patterns/tagged-releases.png" alt="Tagged Releases" width="600" />
  117. ### Secret Management via .gitignore
  118. Agent tools that need API keys read from a local `.env` file — kept out of version control via `.gitignore`. Agent config is shareable, secrets stay local.
  119. <img src="patterns/secret-management.png" alt="Secret Management" width="600" />
  120. ### Agent Lifecycle with Hooks
  121. Define `bootstrap.md` and `teardown.md` in the `hooks/` folder to control what an agent does on startup and before it stops.
  122. <img src="patterns/agent-automation-hooks.png" alt="Agent Lifecycle Hooks" width="600" />
  123. ### SkillsFlow
  124. Deterministic, multi-step workflows defined in `workflows/` as YAML. Chain `skill:`, `agent:`, and `tool:` steps with `depends_on` ordering, `${{ }}` template data flow, and per-step `prompt:` overrides. Every run follows the same path — no LLM discretion on execution order.
  125. ```yaml
  126. name: code-review-flow
  127. description: Full code review pipeline
  128. triggers:
  129. - pull_request
  130. steps:
  131. lint:
  132. skill: static-analysis
  133. inputs:
  134. path: ${{ trigger.changed_files }}
  135. review:
  136. agent: code-reviewer
  137. depends_on: [lint]
  138. prompt: |
  139. Focus on security and performance.
  140. Flag any use of eval() or raw SQL.
  141. inputs:
  142. findings: ${{ steps.lint.outputs.issues }}
  143. test:
  144. tool: bash
  145. depends_on: [lint]
  146. inputs:
  147. command: "npm test -- --coverage"
  148. report:
  149. skill: review-summary
  150. depends_on: [review, test]
  151. conditions:
  152. - ${{ steps.review.outputs.severity != 'none' }}
  153. inputs:
  154. review: ${{ steps.review.outputs.comments }}
  155. coverage: ${{ steps.test.outputs.report }}
  156. error_handling:
  157. on_failure: notify
  158. channel: "#eng-reviews"
  159. ```
  160. ### Porting Framework Agents to GitAgent
  161. Agents built in frameworks like NVIDIA AIQ, LangGraph, or CrewAI have their identity split across config files, Jinja2 templates, and Python code. gitagent extracts the **identity layer** — prompts, rules, roles, tool schemas — into a portable, versionable format.
  162. > **What ports cleanly:** system prompts, persona definitions, hard constraints, tool schemas, role/SOD policies, model preferences.
  163. >
  164. > **What stays in the framework:** runtime orchestration (state machines, graph wiring), live tool execution, memory I/O, iterative loops.
  165. This pattern is demonstrated with [NVIDIA's AIQ Deep Researcher](https://github.com/NVIDIA-AI-Blueprints/aiq) — a 3-agent hierarchy (orchestrator → planner → researcher) that produces cited research reports. The gitagent version captures the agent's identity, rules, and SOD policy so you can:
  166. - **Fork for a new domain** — edit `SOUL.md` for legal/medical/finance research without touching Python
  167. - **Version prompts independently** — `git diff` when the orchestrator's style regresses
  168. - **Validate SOD** — `opengap validate --compliance` ensures the orchestrator can't also be the researcher
  169. - **Export to other runtimes** — same identity on Claude Code, OpenAI, or as a raw system prompt
  170. ```
  171. examples/nvidia-deep-researcher/
  172. ├── agent.yaml # Manifest + SOD policy
  173. ├── SOUL.md # Orchestrator identity (from orchestrator.j2)
  174. ├── RULES.md # Citation rules, report constraints
  175. ├── DUTIES.md # Role separation: orchestrator ↔ planner ↔ researcher
  176. ├── agents/planner/ # Planner sub-agent (from planner.j2)
  177. ├── agents/researcher/ # Researcher sub-agent (from researcher.j2)
  178. ├── skills/{web,paper,knowledge}-search/
  179. ├── tools/*.yaml # MCP-compatible tool schemas
  180. └── config/ # Model assignments per environment
  181. ```
  182. See [`examples/nvidia-deep-researcher/`](examples/nvidia-deep-researcher/) for the full working example.
  183. ## Quick Start
  184. ```bash
  185. # Install
  186. npm i -g @open-gitagent/opengap
  187. # Create a new agent
  188. opengap init --template standard
  189. # Validate
  190. opengap validate
  191. # View agent info
  192. opengap info
  193. # Export to system prompt
  194. opengap export --format system-prompt
  195. ```
  196. > `gitagent` is installed as an alias — all `opengap <cmd>` calls work as `gitagent <cmd>` too.
  197. ## agent.yaml
  198. The only file with a strict schema. Minimal example:
  199. ```yaml
  200. spec_version: "0.1.0"
  201. name: my-agent
  202. version: 0.1.0
  203. description: A helpful assistant agent
  204. ```
  205. Full example with compliance:
  206. ```yaml
  207. spec_version: "0.1.0"
  208. name: compliance-analyst
  209. version: 1.0.0
  210. description: Financial compliance analysis agent
  211. model:
  212. preferred: claude-opus-4-6
  213. compliance:
  214. risk_tier: high
  215. frameworks: [finra, federal_reserve, sec]
  216. supervision:
  217. human_in_the_loop: always
  218. kill_switch: true
  219. recordkeeping:
  220. audit_logging: true
  221. retention_period: 7y
  222. immutable: true
  223. model_risk:
  224. validation_cadence: quarterly
  225. ongoing_monitoring: true
  226. segregation_of_duties:
  227. roles:
  228. - id: analyst
  229. permissions: [create, submit]
  230. - id: reviewer
  231. permissions: [review, approve, reject]
  232. conflicts:
  233. - [analyst, reviewer]
  234. assignments:
  235. compliance-analyst: [analyst]
  236. fact-checker: [reviewer]
  237. enforcement: strict
  238. ```
  239. ## CLI Commands
  240. Both `opengap` and `gitagent` refer to the same binary — use whichever you prefer.
  241. | Command | Description |
  242. |---------|-------------|
  243. | `opengap init [--template]` | Scaffold new agent (`minimal`, `standard`, `full`, `llm-wiki`) |
  244. | `opengap validate [--compliance]` | Validate against spec and regulatory requirements |
  245. | `opengap info` | Display agent summary |
  246. | `opengap export --format <fmt>` | Export to other formats (see adapters below) |
  247. | `opengap import --from <fmt> <path>` | Import (`claude`, `cursor`, `crewai`, `opencode`) |
  248. | `opengap run <source> --adapter <a>` | Run an agent from a git repo or local directory |
  249. | `opengap install` | Resolve and install git-based dependencies |
  250. | `opengap audit` | Generate compliance audit report |
  251. | `opengap skills <cmd>` | Manage skills (`search`, `install`, `list`, `info`) |
  252. | `opengap lyzr <cmd>` | Manage Lyzr agents (`create`, `update`, `info`, `run`) |
  253. ## Compliance
  254. gitagent has first-class support for financial regulatory compliance:
  255. ### FINRA
  256. - **Rule 3110** — Supervision: human-in-the-loop, escalation triggers, kill switch
  257. - **Rule 4511** — Recordkeeping: immutable audit logs, retention periods, SEC 17a-4 compliance
  258. - **Rule 2210** — Communications: fair/balanced enforcement, no misleading statements
  259. - **Reg Notice 24-09** — Existing rules apply to GenAI/LLMs
  260. ### Federal Reserve
  261. - **SR 11-7** — Model Risk Management: validation cadence, ongoing monitoring, outcomes analysis
  262. - **SR 23-4** — Third-Party Risk: vendor due diligence, SOC reports, subcontractor assessment
  263. ### SEC / CFPB
  264. - **Reg S-P** — Customer privacy, PII handling
  265. - **CFPB Circular 2022-03** — Explainable adverse action, Less Discriminatory Alternative search
  266. ### Segregation of Duties
  267. - **Roles & Permissions** — Define maker, checker, executor, auditor roles with controlled permissions
  268. - **Conflict Matrix** — Declare which role pairs cannot be held by the same agent
  269. - **Handoff Workflows** — Require multi-agent participation for critical actions (credit decisions, regulatory filings)
  270. - **Isolation** — Full state and credential segregation between roles
  271. - **DUTIES.md** — Root-level policy + per-agent role declarations
  272. - **Enforcement** — Strict (blocks deployment) or advisory (warnings only)
  273. Inspired by [Salient AI](https://www.trysalient.com/)'s purpose-built agent architecture and the [FINOS AI Governance Framework](https://air-governance-framework.finos.org/mitigations/mi-22_multi-agent-isolation-and-segmentation.html).
  274. Run `opengap audit` for a full compliance checklist against your agent configuration.
  275. ## Adapters
  276. Adapters are used by both `export` and `run`. Available adapters:
  277. | Adapter | Description |
  278. |---------|-------------|
  279. | `system-prompt` | Concatenated system prompt (works with any LLM) |
  280. | `claude-code` | Claude Code compatible CLAUDE.md |
  281. | `openai` | OpenAI Agents SDK Python code |
  282. | `crewai` | CrewAI YAML configuration |
  283. | `lyzr` | Lyzr Studio agent |
  284. | `github` | GitHub Models inference |
  285. | `git` | Git-native execution (run only) |
  286. | `opencode` | OpenCode instructions + config |
  287. | `gemini` | Google Gemini CLI (GEMINI.md + settings.json) |
  288. | `openclaw` | OpenClaw format |
  289. | `nanobot` | Nanobot format |
  290. | `cursor` | Cursor `.cursor/rules/*.mdc` files |
  291. | `copilot` | GitHub Copilot instructions (export only) |
  292. | `codex` | OpenAI Codex CLI instructions (export only) |
  293. | `kiro` | Kiro agent format (export only) |
  294. | `gitclaw` | GitClaw agent format |
  295. ```bash
  296. # Export to system prompt
  297. opengap export --format system-prompt
  298. # Run an agent directly
  299. opengap run ./my-agent --adapter lyzr
  300. # Run an agent definition against a separate target workspace
  301. opengap run --dir ./agents/reviewer --workspace ~/code/my-app --adapter claude -p "Review this repository"
  302. ```
  303. ## Inheritance & Composition
  304. ```yaml
  305. # Extend a parent agent
  306. extends: https://github.com/org/base-agent.git
  307. # Compose with dependencies
  308. dependencies:
  309. - name: fact-checker
  310. source: https://github.com/org/fact-checker.git
  311. version: ^1.0.0
  312. mount: agents/fact-checker
  313. ```
  314. ## Examples
  315. See the `examples/` directory:
  316. - **`examples/minimal/`** — 2-file hello world (agent.yaml + SOUL.md)
  317. - **`examples/standard/`** — Code review agent with skills, tools, and rules
  318. - **`examples/full/`** — Production compliance agent with all directories, hooks, workflows, sub-agents, SOD with DUTIES.md, and regulatory artifacts
  319. - **`examples/gitagent-helper/`** — Helper agent that assists with creating gitagent definitions
  320. - **`examples/lyzr-agent/`** — Example Lyzr Studio integration
  321. ## Specification
  322. Full specification at [`spec/SPECIFICATION.md`](spec/SPECIFICATION.md).
  323. JSON Schemas for validation at `spec/schemas/`.
  324. ## Star History
  325. [![Star History Chart](https://api.star-history.com/svg?repos=open-gitagent/opengap&type=Date)](https://star-history.com/#open-gitagent/opengap&Date)
  326. ## Built with gitagent?
  327. If you've built an agent using gitagent, we'd love to hear about it! [Open a discussion](https://github.com/open-gitagent/gitagent/discussions) or add a `gitagent` topic to your repo.
  328. ## License
  329. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.