GitAgentProtocol (Open GAP) — gapman, the GAP Manager CLI

GitAgentProtocol (Open GAP) and gapman: Your Repository, Your Agent

Overview GitAgentProtocol, also known as Open GAP, introduces a bold idea: treat a git repository as a living, portable agent. At the heart of the project sits gapman, the reference CLI that makes agents feel like native software projects. The vision is simple but powerful: a framework-agnostic, git-native standard for defining AI agents that can work across Claude Code, OpenAI, LangChain, CrewAI, and AutoGen. Instead of looping through disparate formats and runtimes, a single repository becomes an agent that can be exported to adapters and executed in diverse environments.

The core value proposition is deeper than a single toolchain. It’s about a community-driven, auditable, and compliant approach to agent design that fits modern software practices. The project emphasizes a Git-native model—versioning, branching, diffing, and collaboration are built in. It’s not just about the agent’s prompts; it’s about the whole lifecycle: identity, behavior rules, memory, tools, compliance, and orchestration, all living alongside the code that defines the agent.

Why This Approach Matters

• A universal, portable agent definition: No more bespoke, framework-bound formats. Your repository defines the agent, and adapters translate that identity into the right runtime.
• Built-in collaboration: Branching and PRs enable human-in-the-loop reviews for skill acquisition, memory updates, and policy changes.
• Compliance by design: The framework includes first-class support for financial and regulatory requirements, with explicit patterns for segregation of duties and auditable records.
• Composability and scalability: Agents can extend, depend on, and delegate to other agents, creating a modular, scalable agent ecosystem.
• Transparency and traceability: Every change to an agent is captured in git history, with diffs and blame information ensuring a complete audit trail.

The Standard: Architecture of a Git-native Agent

The idea is that your repository becomes your agent. Drop a curated set of files into any git repo, and the project becomes a portable, framework-agnostic agent definition. Everything else, like the CLI, adapters, and patterns, builds on top of this foundation.

Two essential files (the minimum you need)

• agent.yaml: Manifest—name, version, model, skills, tools, compliance, and more.
• SOUL.md: Identity, personality, communication style, values.

Everything else is optional, chosen by you to fit your needs. This minimalist approach keeps the core identity clean while allowing rich extensions.

A representative layout (illustrative) 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 │ └── code-review/ │ ├── SKILL.md │ └── review.sh ├── tools/ # MCP-compatible tool definitions ├── workflows/ # Multi-step procedures / playbooks │ # Knowledge & Memory ├── knowledge/ # Reference documents for consultation ├── memory/ # Persistent cross-session memory │ └── runtime/ │ ├── dailylog.md │ ├── context.md │ # Lifecycle & Ops ├── hooks/ # Lifecycle event handlers ├── config/ # Environment-specific overrides ├── compliance/ # Regulatory compliance artifacts │ # Composition ├── agents/ # Sub-agent definitions │ └── fact-checker/ │ ├── agent.yaml │ ├── SOUL.md │ └── DUTIES.md │ # Examples ├── examples/ # Calibration interactions (few-shot) │ # Runtime └── .gitagent/ # Runtime state (gitignored)

In practice, only two files are strictly required: agent.yaml and SOUL.md. The rest is optional, tailored to your needs. This is a deliberate design to keep the identity portable and versionable—everything else can be layered on top as required.

Patterns: Architectural Patterns Emerge

Human-in-the-Loop for RL Agents When an agent learns a new skill or writes to memory, it opens a branch and a pull request for human review before merging. This keeps learning tightly coupled to human oversight and quality control. Image reference:

Segregation of Duties (SOD) A critical pattern to prevent single-agent dominance over a process. By defining roles (maker, checker, executor, auditor) and a conflict matrix, the system ensures proper safeguards. The validator catches violations before deployment. A sample YAML excerpt demonstrates roles and conflicts:

• maker: create, submit
• checker: review, approve, reject Conflicts: maker vs checker Handoff workflows ensure that certain actions require multi-party approval. Image reference:

Live Agent Memory The memory folder is a living archive. A runtime subfolder holds dailylog.md, key-decisions.md, and context.md to persist state across sessions. This enables a true memory layer that agents can reference over time. Image reference:

Agent Versioning Every git commit is a version of your agent. You can roll back prompts, revert skills, and explore past states—full undo history for the agent. Image reference:

Shared Context & Skills via Monorepo Context, skills, and tools are shared at the repository root so every agent in the monorepo benefits from a single source of truth. Image reference:

Branch-based Deployment Adopt standard software workflows by promoting changes through environments using branches (dev → staging → main). This provides a familiar, reliable deployment model for agents as they mature. Image reference:

Knowledge Tree Store entity relationships as a hierarchical tree with embeddings. This structure supports runtime reasoning over structured data. Image reference:

Agent Forking & Remixing Fork a public agent repo, tailor its SOUL.md, add your skills, and submit upstream improvements. It’s collaborative by design, aligning AI agent development with open-source practices. Image reference:

CI/CD for Agents Run validations on every push via CI. Test agent behavior, block bad merges, and automate deployment—treat agent quality like code quality. Image reference:

Agent Diff & Audit Trail Git diff shows exactly what changed between agent versions. Git blame traces every line to its author and timestamp—full traceability baked in. Image reference:

Tagged Releases Tag stable agent versions (e.g., v1.1.0). Use tags to pin production, canary new versions on staging, and rollback instantly if needed. Image reference:

Secret Management via .gitignore Keep sensitive keys out of version control. API keys and secret configurations can live in a local .env file, ignored by Git. This keeps secrets local while enabling shareable configurations. Image reference:

Agent Lifecycle with Hooks Define bootstrap and teardown in the hooks directory to control startup and shutdown behavior. This ensures predictable lifecycle management. Image reference:

SkillsFlow: Deterministic Workflows Define multi-step workflows in workflows/, chaining skill, agent, and tool steps with explicit ordering and data flow. Each run follows a deterministic path, ensuring consistent behavior. Code example (simplified):

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]
  test:
    tool: bash
    depends_on: [lint]
  report:
    skill: review-summary
    depends_on: [review, test]

Tip: prompt overrides and data flow are per-step, ensuring a tight, auditable script of execution.

Porting Framework Agents to GitAgent GitAgent focuses on porting the identity layer—prompts, rules, roles, and tool schemas—into a portable format. What ports cleanly includes system prompts, persona definitions, hard constraints, tool schemas, and SOD policies. What stays in the framework includes runtime orchestration, live tool execution, memory I/O, and iterative loops. A well-known example demonstrates multiple agents (orchestrator → planner → researcher) with a centralized identity layer that travels across runtimes.

The quick-start journey demonstrates how to begin with gapman and grow into a production-ready agent system.

Quick Start: Getting Up and Running

• Install gapman globally
• Create a new agent with a template
• Validate the agent
• Inspect agent information
• Export to a system prompt
• Use gitagent as a convenient alias for gapman

Image reference:

A Minimal Agent: agent.yaml and SOUL.md

Minimal example

• agent.yaml (spec_version: "0.1.0", name, version, description)
• SOUL.md: Identity and personality

Minimal example code:

spec_version: "0.1.0"
name: my-agent
version: 0.1.0
description: A helpful assistant agent

Full example with compliance The full example includes compliance, supervision policies, and SOD configuration:

spec_version: "0.1.0"
name: compliance-analyst
version: 1.0.0
description: Financial compliance analysis agent
model: preferred: claude-opus-4-6
compliance:
  risk_tier: high
frameworks: [finra, federal_reserve, sec]
supervision: human_in_the_loop: always
kill_switch: true
recordkeeping: audit_logging: true
retention_period: 7y
immutable: true
model_risk: validation
cadence: quarterly
ongoing_monitoring: true
segregation_of_duties:
  roles:
    - id: analyst
      permissions: [create, submit]
    - id: reviewer
      permissions: [review, approve, reject]
  conflicts:
    - [analyst, reviewer]
assignments:
  compliance-analyst: [analyst]
  fact-checker: [reviewer]
enforcement: strict

CLI Commands: Working with gapman/gitagent

Two names, one binary

• gapman and gitagent refer to the same executable. Use either name you prefer.

Key commands

• gapman init [--template] — Scaffold a new agent (minimal, standard, full, llm-wiki)
• gapman validate [--compliance] — Validate against the spec and regulatory requirements
• gapman info — Display a summary of the agent
• gapman export --format — Export to adapters (system-prompt, etc.)
• gapman import --from — Import from Claude, Cursor, CrewAI, OpenCode
• gapman run --adapter — Run an agent from a git repo or local directory
• gapman install — Resolve and install git-based dependencies
• gapman audit — Generate a compliance audit report
• gapman skills — Manage skills (search, install, list, info)
• gapman lyzr — Manage Lyzr agents (create, update, info, run)

Image reference:

Compliance: A Grounded Foundation

FINRA

• Rule 3110: Supervision, escalation triggers, kill switch
• Rule 4511: Recordkeeping, immutable audit logs, retention
• Rule 2210: Communications: fair, balanced
• Reg Notice 24-09: GenAI/LLMs rule alignment

Federal Reserve

• SR 11-7: Model Risk Management, validation cadence, ongoing monitoring
• SR 23-4: Third-Party Risk, vendor due diligence, SOC reports

SEC / CFPB

• Reg S-P: Customer privacy, PII handling
• CFPB Circular 2022-03: Explainable adverse action, Less Discriminatory Alternative

DUTIES & Enforcement

• Roles & permissions and a conflict matrix
• Handoff workflows that require multi-agent participation for critical actions
• Isolation: separate state and credentials between roles
• Enforcement: strict or advisory

These principles are designed to be validated by the built-in tooling and ensured through the repository structure, so adherence to regulatory requirements can be audited alongside code quality.

Adapters: Translating Identity into Runtime

Adapters are the translation layer that makes the same agent definition usable in multiple runtimes. They bridge the gap between the portable identity and the runtime-specific system prompts, tool schemas, and orchestration logic.

Common adapters include

• system-prompt: Concatenated system prompts usable by any LLM
• claude-code: Claude Code format
• openai: OpenAI Agents SDK Python code
• crewai: CrewAI YAML configuration
• lyzr: Lyzr Studio integration
• github: GitHub Actions agent
• git: Git-native execution
• opencode: OpenCode configuration
• gemini: Google Gemini CLI
• openclaw: OpenClaw format
• nanobot: Nanobot format
• cursor: Cursor-based format

Exporting and running with adapters is a core workflow, enabling teams to validate and deploy agents across ecosystems without rewriting the agent’s identity.

Inheritance & Composition: Extending Agents

Agents can extend a parent agent or compose with dependencies. This makes it possible to build complex hierarchies while preserving a clean identity layer.

Example snippet

# Extend a parent agent
extends: https://github.com/org/base-agent.git
# Compose with dependencies
dependencies:
  - name: fact-checker
    source: https://github.com/org/fact-checker.git
    version: ^1.0.0
    mount: agents/fact-checker

Examples Directory: Real-world Realizations

The repository includes several examples that illustrate different levels of completeness and complexity:

• examples/minimal: two-file hello world (agent.yaml + SOUL.md)
• examples/standard: code review agent with skills, tools, and rules
• examples/full: production compliance agent with all directories, hooks, workflows, SOD, and regulatory artifacts
• examples/gitagent-helper: helper agent that assists with creating gitagent definitions
• examples/lyzr-agent: Lyzr Studio integration

Specification and Validation

Full specification is available in spec/SPECIFICATION.md, with JSON Schemas for validation in spec/schemas/. This ensures a formal, machine-readable standard that can be used by validators and adapters alike.

Star History and Community

GitAgentProtocol has a recognizable presence in the open-source community. A star history visualization reflects the project’s adoption trajectory, and the community is encouraged to share their own agent creations and experiences.

License

MIT

Immersive Visuals and Patterns

The design language of GitAgentProtocol uses a series of visuals to illustrate patterns and workflows. The imagery emphasizes the cognitive and operational layers of an agent—memory, decision-making, versioning, and governance. The banner sets the tone, while the supporting diagrams reinforce the habits of living repositories and their agents.

A gallery of pattern images to explore

• Human-in-the-Loop for RL Agents Image:
• Live Agent Memory Image:
• Agent Versioning Image:
• Shared Context Image:
• Branch-based Deployment Image:
• Knowledge Tree Image:
• Agent Forking & Remixing Image:
• CI/CD for Agents Image:
• Agent Diff & Audit Trail Image:
• Tagged Releases Image:
• Secret Management Image:
• Agent Lifecycle Hooks Image:

A Final Note: The GitAgent Promise

GitAgentProtocol and gapman invite you to reimagine AI agents as first-class software artifacts. The repository is not just a codebase; it’s a living contract between people and machines. It codifies who the agent is, what it should do, how it should behave in compliance with regulations, and how it evolves through collaborations, reviews, and governance.

If you’ve ever wanted a portable, auditable, and scalable way to define AI agents that can travel across runtimes, this is your invitation to explore the GitAgent world. Set up a repository that becomes a robust, versioned agent—and watch how the same identity can propel multiple runtimes, adapters, and teams toward shared goals. The journey begins with two files, but it ends in a universe of modular, trustworthy agents that you can fork, remix, and improve—together.