OpenGAP | your repository becomes your agent

opengap — the OpenGAP CLI, published as @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.

= 18">

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.

Why

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.

• Git-native — Version control, branching, diffing, and collaboration built in
• Framework-agnostic — Export to any framework with adapters
• Compliance-ready — First-class support for FINRA, Federal Reserve, SEC, and segregation of duties
• Composable — Agents can extend, depend on, and delegate to other agents

The Standard

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.

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
│
│   # ── Capabilities ──────────────────────────────────────
├── skills/                 # Reusable capability modules (SKILL.md + scripts)
│   └── code-review/
│       ├── SKILL.md
│       └── review.sh
├── tools/                  # MCP-compatible tool definitions (YAML schemas)
├── workflows/              # Multi-step procedures/playbooks
│
│   # ── Knowledge & Memory ────────────────────────────────
├── knowledge/              # Reference documents the agent can consult
├── memory/                 # Persistent cross-session memory
│   └── runtime/            # Live agent state (dailylog.md, context.md)
│
│   # ── Lifecycle & Ops ───────────────────────────────────
├── hooks/                  # Lifecycle event handlers (bootstrap.md, teardown.md)
├── config/                 # Environment-specific overrides
├── compliance/             # Regulatory compliance artifacts
│
│   # ── Composition ───────────────────────────────────────
├── agents/                 # Sub-agent definitions (recursive structure)
│   └── fact-checker/
│       ├── agent.yaml
│       ├── SOUL.md
│       └── DUTIES.md       # This agent's role, permissions, boundaries
├── examples/               # Calibration interactions (few-shot)
│
│   # ── Runtime ───────────────────────────────────────────
└── .gitagent/              # Runtime state (gitignored)

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.

Patterns

These are the architectural patterns that emerge when you define agents as git-native file systems.

Human-in-the-Loop for RL Agents

When an agent learns a new skill or writes to memory, it opens a branch + PR for human review before merging.

Segregation of Duties (SOD)

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.

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

Live Agent Memory

The memory/ folder holds a runtime/ subfolder where agents write live knowledge — dailylog.md, key-decisions.md, and context.md — persisting state across sessions.

Agent Versioning

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.

Shared Context & Skills via Monorepo

Root-level context.md, skills/, tools/ are automatically shared across every agent in the monorepo. No duplication, one source of truth.

Branch-based Deployment

Use git branches (dev → staging → main) to promote agent changes through environments, just like shipping software.

Knowledge Tree

The knowledge/ folder stores entity relationships as a hierarchical tree with embeddings, letting agents reason over structured data at runtime.

Agent Forking & Remixing

Fork any public agent repo, customize its SOUL.md, add your own skills, and PR improvements back upstream — open-source collaboration for AI agents.

CI/CD for Agents

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.

Agent Diff & Audit Trail

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.

Tagged Releases

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.

Secret Management via .gitignore

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.

Agent Lifecycle with Hooks

Define bootstrap.md and teardown.md in the hooks/ folder to control what an agent does on startup and before it stops.

SkillsFlow

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.

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 }}

  test:
    tool: bash
    depends_on: [lint]
    inputs:
      command: "npm test -- --coverage"

  report:
    skill: review-summary
    depends_on: [review, test]
    conditions:
      - ${{ steps.review.outputs.severity != 'none' }}
    inputs:
      review: ${{ steps.review.outputs.comments }}
      coverage: ${{ steps.test.outputs.report }}

error_handling:
  on_failure: notify
  channel: "#eng-reviews"

Porting Framework Agents to GitAgent

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.

What ports cleanly: system prompts, persona definitions, hard constraints, tool schemas, role/SOD policies, model preferences.

What stays in the framework: runtime orchestration (state machines, graph wiring), live tool execution, memory I/O, iterative loops.

This pattern is demonstrated with NVIDIA's AIQ Deep Researcher — a 3-agent hierarchy (orchestrator → planner → researcher) that produces cited research