A framework-agnostic, git-native standard for defining AI agents. Clone a repo, get an agent.

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

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.

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

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

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

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

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.

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

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

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

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

Run gitagent validate on every push via GitHub Actions. Test agent behavior in CI, block bad merges, and auto-deploy — treat agent quality like code quality.

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.

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.

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.

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

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"

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 reports. The gitagent version captures the agent's identity, rules, and SOD policy so you can:

• Fork for a new domain — edit SOUL.md for legal/medical/finance research without touching Python
• Version prompts independently — git diff when the orchestrator's style regresses
• Validate SOD — gitagent validate --compliance ensures the orchestrator can't also be the researcher
• Export to other runtimes — same identity on Claude Code, OpenAI, or as a raw system prompt

examples/nvidia-deep-researcher/
├── agent.yaml                  # Manifest + SOD policy
├── SOUL.md                     # Orchestrator identity (from orchestrator.j2)
├── RULES.md                    # Citation rules, report constraints
├── DUTIES.md                   # Role separation: orchestrator ↔ planner ↔ researcher
├── agents/planner/             # Planner sub-agent (from planner.j2)
├── agents/researcher/          # Researcher sub-agent (from researcher.j2)
├── skills/{web,paper,knowledge}-search/
├── tools/*.yaml                # MCP-compatible tool schemas
└── config/                     # Model assignments per environment

See examples/nvidia-deep-researcher/ for the full working example.

# Install
npm i @open-gitagent/gitagent

# Create a new agent
gitagent init --template standard

# Validate
gitagent validate

# View agent info
gitagent info

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

The only file with a strict schema. Minimal example:

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

Full example with compliance:

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

Command	Description
gitagent init [--template]	Scaffold new agent (minimal, standard, full)
gitagent validate [--compliance]	Validate against spec and regulatory requirements
gitagent info	Display agent summary
gitagent export --format <fmt>	Export to other formats (see adapters below)
gitagent import --from <fmt> <path>	Import (claude, cursor, crewai, opencode)
gitagent run <source> --adapter <a>	Run an agent from a git repo or local directory
gitagent install	Resolve and install git-based dependencies
gitagent audit	Generate compliance audit report
gitagent skills <cmd>	Manage skills (search, install, list, info)
gitagent lyzr <cmd>	Manage Lyzr agents (create, update, info, run)

gitagent has first-class support for financial regulatory compliance:

• Rule 3110 — Supervision: human-in-the-loop, escalation triggers, kill switch
• Rule 4511 — Recordkeeping: immutable audit logs, retention periods, SEC 17a-4 compliance
• Rule 2210 — Communications: fair/balanced enforcement, no misleading statements
• Reg Notice 24-09 — Existing rules apply to GenAI/LLMs

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

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

• Roles & Permissions — Define maker, checker, executor, auditor roles with controlled permissions
• Conflict Matrix — Declare which role pairs cannot be held by the same agent
• Handoff Workflows — Require multi-agent participation for critical actions (credit decisions, regulatory filings)
• Isolation — Full state and credential segregation between roles
• DUTIES.md — Root-level policy + per-agent role declarations
• Enforcement — Strict (blocks deployment) or advisory (warnings only)

Inspired by Salient AI's purpose-built agent architecture and the FINOS AI Governance Framework.

Run gitagent audit for a full compliance checklist against your agent configuration.

Adapters are used by both export and run. Available adapters:

Adapter	Description
system-prompt	Concatenated system prompt (works with any LLM)
claude-code	Claude Code compatible CLAUDE.md
openai	OpenAI Agents SDK Python code
crewai	CrewAI YAML configuration
lyzr	Lyzr Studio agent
github	GitHub Actions agent
git	Git-native execution (run only)
opencode	OpenCode instructions + config
gemini	Google Gemini CLI (GEMINI.md + settings.json)
openclaw	OpenClaw format
nanobot	Nanobot format
cursor	Cursor .cursor/rules/*.mdc files

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

# Run an agent directly
gitagent run ./my-agent --adapter lyzr

# 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

See the examples/ directory:

• examples/minimal/ — 2-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, sub-agents, SOD with DUTIES.md, and regulatory artifacts
• examples/gitagent-helper/ — Helper agent that assists with creating gitagent definitions
• examples/lyzr-agent/ — Example Lyzr Studio integration

Full specification at spec/SPECIFICATION.md.

JSON Schemas for validation at spec/schemas/.

If you've built an agent using gitagent, we'd love to hear about it! Open a discussion or add a gitagent topic to your repo.

MIT