From 81ab53272a062015e672f7ae8576fd54b40a382d Mon Sep 17 00:00:00 2001 From: shreyas-lyzr Date: Sun, 24 May 2026 12:45:31 -0400 Subject: [PATCH] =?UTF-8?q?chore:=20rebrand=20gapman=20=E2=86=92=20opengap?= =?UTF-8?q?=20(package,=20CLI,=20docs)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Renames the package and CLI to OpenGAP and updates all documentation. - package.json: name @open-gitagent/gapman → @open-gitagent/opengap, bin gapman → opengap (gitagent alias kept), version 0.3.2 → 0.4.0, description + keywords updated - package-lock.json: name/version/bin updated - src/index.ts: CLI self-name gapman → opengap, version 0.4.0 - src/commands/registry.ts: npx @open-gitagent/opengap - .github/workflows/publish.yml: publishes @open-gitagent/opengap (scoped) + opengap (unscoped alias) - 274 doc edits across README, docs.md, CONTRIBUTING, spec, examples, paper: all 'gapman ' CLI examples → 'opengap ', npm install lines, inline code names - Historical migration notes in README/docs preserved (gitagent → gapman → opengap chain) so existing gapman users can find the new package - gitagent command remains installed as a backward-compat alias --- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .github/workflows/publish.yml | 6 +- CONTRIBUTING.md | 20 +- README.md | 54 +++--- docs.md | 180 +++++++++--------- docs/adapters/gemini.md | 16 +- docs/comparison.md | 24 +-- examples/gitagent-helper/README.md | 6 +- examples/gitagent-helper/RULES.md | 2 +- .../knowledge/command-reference.md | 32 ++-- .../skills/create-agent/SKILL.md | 2 +- .../skills/export-agent/SKILL.md | 22 +-- .../skills/get-started/SKILL.md | 16 +- .../skills/manage-skills/SKILL.md | 22 +-- .../gitagent-helper/skills/run-agent/SKILL.md | 24 +-- .../README.md | 4 +- examples/lyzr-agent/README.md | 18 +- examples/nvidia-deep-researcher/README.md | 12 +- .../standard/memory/daily-log/2026-02-18.md | 2 +- package-lock.json | 12 +- package.json | 11 +- paper/README.md | 2 +- paper/open-gap.md | 28 +-- spec/SPECIFICATION.md | 38 ++-- src/commands/registry.ts | 2 +- src/index.ts | 6 +- 26 files changed, 282 insertions(+), 281 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index cb7d37a..3376f3e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -12,7 +12,7 @@ A clear and concise description of the bug. ## Environment - **OS**: (e.g., macOS 14, Ubuntu 22.04, Windows 11) - **Node.js version**: (e.g., 18.19.0) -- **gapman version**: (run `gapman --version`) +- **opengap version**: (run `opengap --version`) - **Adapter** (if applicable): (e.g., claude-code, openai, crewai) ## Steps to Reproduce diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index b5ee7f7..91f68d6 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -23,14 +23,14 @@ jobs: - run: npm run build - run: npm test - - name: Publish @open-gitagent/gapman (scoped) + - name: Publish @open-gitagent/opengap (scoped) run: npm publish --provenance --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - - name: Publish gapman (unscoped alias) + - name: Publish opengap (unscoped alias) run: | - node -e "const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));p.name='gapman';fs.writeFileSync('package.json',JSON.stringify(p,null,2));" + node -e "const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));p.name='opengap';fs.writeFileSync('package.json',JSON.stringify(p,null,2));" npm publish --provenance --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c2dca5c..c3a4fdb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,16 +55,16 @@ Recompiles on file changes. You still need to re-run the command manually. src/ ├── index.ts # CLI entry point (Commander.js) ├── commands/ # One file per CLI command -│ ├── run.ts # gapman run -│ ├── init.ts # gapman init -│ ├── validate.ts # gapman validate -│ ├── export.ts # gapman export -│ ├── import.ts # gapman import -│ ├── audit.ts # gapman audit -│ ├── skills.ts # gapman skills -│ ├── install.ts # gapman install -│ ├── info.ts # gapman info -│ └── lyzr.ts # gapman lyzr +│ ├── run.ts # opengap run +│ ├── init.ts # opengap init +│ ├── validate.ts # opengap validate +│ ├── export.ts # opengap export +│ ├── import.ts # opengap import +│ ├── audit.ts # opengap audit +│ ├── skills.ts # opengap skills +│ ├── install.ts # opengap install +│ ├── info.ts # opengap info +│ └── lyzr.ts # opengap lyzr ├── runners/ # Runtime adapters (execute agents) │ ├── claude.ts # Claude Code runner │ ├── openai.ts # OpenAI Agents SDK runner diff --git a/README.md b/README.md index a4c8b90..5de0154 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,17 @@ gitagent banner

-# GitAgentProtocol (Open GAP) | your repository becomes your agent +# OpenGAP | your repository becomes your agent -> **`gapman`** — the GitAgentProtocol (GAP) Manager CLI, published as [`@open-gitagent/gapman`](https://www.npmjs.com/package/@open-gitagent/gapman). Previously published as `@open-gitagent/gitagent`. +> **`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. -[![npm version](https://img.shields.io/npm/v/@open-gitagent/gapman)](https://www.npmjs.com/package/@open-gitagent/gapman) +[![npm version](https://img.shields.io/npm/v/@open-gitagent/opengap)](https://www.npmjs.com/package/@open-gitagent/opengap) [![CI](https://github.com/open-gitagent/gitagent/actions/workflows/ci.yml/badge.svg)](https://github.com/open-gitagent/gitagent/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![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) [![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org) -GitAgentProtocol (Open GAP) is a framework-agnostic, git-native standard for defining AI agents. Clone a repo, get an agent. `gapman` is its reference CLI. +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 @@ -136,7 +136,7 @@ Fork any public agent repo, customize its `SOUL.md`, add your own skills, and PR Agent Forking & Remixing ### CI/CD for Agents -Run `gapman validate` on every push via GitHub Actions. Test agent behavior in CI, block bad merges, and auto-deploy — treat agent quality like code quality. +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. CI/CD for Agents @@ -216,7 +216,7 @@ This pattern is demonstrated with [NVIDIA's AIQ Deep Researcher](https://github. - **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** — `gapman validate --compliance` ensures the orchestrator can't also be the researcher +- **Validate SOD** — `opengap 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 ``` @@ -238,22 +238,22 @@ See [`examples/nvidia-deep-researcher/`](examples/nvidia-deep-researcher/) for t ```bash # Install -npm i -g @open-gitagent/gapman +npm i -g @open-gitagent/opengap # Create a new agent -gapman init --template standard +opengap init --template standard # Validate -gapman validate +opengap validate # View agent info -gapman info +opengap info # Export to system prompt -gapman export --format system-prompt +opengap export --format system-prompt ``` -> `gitagent` is installed as an alias — all `gapman ` calls work as `gitagent ` too. +> `gitagent` is installed as an alias — all `opengap ` calls work as `gitagent ` too. ## agent.yaml @@ -304,20 +304,20 @@ compliance: ## CLI Commands -Both `gapman` and `gitagent` refer to the same binary — use whichever you prefer. +Both `opengap` and `gitagent` refer to the same binary — use whichever you prefer. | Command | Description | |---------|-------------| -| `gapman init [--template]` | Scaffold new agent (`minimal`, `standard`, `full`, `llm-wiki`) | -| `gapman validate [--compliance]` | Validate against spec and regulatory requirements | -| `gapman info` | Display agent summary | -| `gapman export --format ` | Export to other formats (see adapters below) | -| `gapman import --from ` | Import (`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 compliance audit report | -| `gapman skills ` | Manage skills (`search`, `install`, `list`, `info`) | -| `gapman lyzr ` | Manage Lyzr agents (`create`, `update`, `info`, `run`) | +| `opengap init [--template]` | Scaffold new agent (`minimal`, `standard`, `full`, `llm-wiki`) | +| `opengap validate [--compliance]` | Validate against spec and regulatory requirements | +| `opengap info` | Display agent summary | +| `opengap export --format ` | Export to other formats (see adapters below) | +| `opengap import --from ` | Import (`claude`, `cursor`, `crewai`, `opencode`) | +| `opengap run --adapter ` | Run an agent from a git repo or local directory | +| `opengap install` | Resolve and install git-based dependencies | +| `opengap audit` | Generate compliance audit report | +| `opengap skills ` | Manage skills (`search`, `install`, `list`, `info`) | +| `opengap lyzr ` | Manage Lyzr agents (`create`, `update`, `info`, `run`) | ## Compliance @@ -347,7 +347,7 @@ gitagent has first-class support for financial regulatory compliance: 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). -Run `gapman audit` for a full compliance checklist against your agent configuration. +Run `opengap audit` for a full compliance checklist against your agent configuration. ## Adapters @@ -374,13 +374,13 @@ Adapters are used by both `export` and `run`. Available adapters: ```bash # Export to system prompt -gapman export --format system-prompt +opengap export --format system-prompt # Run an agent directly -gapman run ./my-agent --adapter lyzr +opengap run ./my-agent --adapter lyzr # Run an agent definition against a separate target workspace -gapman run --dir ./agents/reviewer --workspace ~/code/my-app --adapter claude -p "Review this repository" +opengap run --dir ./agents/reviewer --workspace ~/code/my-app --adapter claude -p "Review this repository" ``` ## Inheritance & Composition diff --git a/docs.md b/docs.md index 051f737..2cb14a6 100644 --- a/docs.md +++ b/docs.md @@ -1,10 +1,10 @@ -# GitAgentProtocol (Open GAP) Documentation +# OpenGAP Documentation -A framework-agnostic, git-native standard for defining AI agents. `gapman` is the reference CLI (the GitAgentProtocol Manager). +A framework-agnostic, git-native standard for defining AI agents. `opengap` is the reference CLI for the Git Agent Protocol. **Clone a repo, get an agent.** -> The package was previously published as `@open-gitagent/gitagent`. Starting with v0.3.1 it is published as [`@open-gitagent/gapman`](https://www.npmjs.com/package/@open-gitagent/gapman). Both `gapman` and `gitagent` commands are installed as binaries — they point to the same CLI. +> The package was originally published as `@open-gitagent/gitagent`, then `@open-gitagent/gapman`. Starting with v0.4.0 it is published as [`@open-gitagent/opengap`](https://www.npmjs.com/package/@open-gitagent/opengap). Both `opengap` and `gitagent` commands are installed as binaries — they point to the same CLI. --- @@ -50,17 +50,17 @@ A framework-agnostic, git-native standard for defining AI agents. `gapman` is th ## Installation ```bash -npm install -g @open-gitagent/gapman +npm install -g @open-gitagent/opengap ``` Verify: ```bash -gapman --version # 0.3.1 -gapman --help +opengap --version # 0.3.1 +opengap --help # gitagent alias also works -gapman --version +opengap --version ``` --- @@ -69,28 +69,28 @@ gapman --version ```bash # Create a new agent -gapman init --template standard --dir ./my-agent +opengap init --template standard --dir ./my-agent # Validate it -gapman validate -d ./my-agent +opengap validate -d ./my-agent # Run it locally with Claude Code -gapman run -d ./my-agent +opengap run -d ./my-agent # Run from a git repo -gapman run -r https://github.com/user/my-agent -p "Hello" +opengap run -r https://github.com/user/my-agent -p "Hello" # Run with a different adapter -gapman run -d ./my-agent -a github -p "Summarize this project" +opengap run -d ./my-agent -a github -p "Summarize this project" # Clone + auto-detect best adapter + run -gapman run -r https://github.com/user/my-agent -a git -p "Hello" +opengap run -r https://github.com/user/my-agent -a git -p "Hello" # Deploy to Lyzr Studio and chat -gapman lyzr run -r https://github.com/user/my-agent -p "Hello" +opengap lyzr run -r https://github.com/user/my-agent -p "Hello" # Export to another framework -gapman export -f openai -d ./my-agent -o agent.py +opengap export -f openai -d ./my-agent -o agent.py ``` --- @@ -336,7 +336,7 @@ metadata: Scaffold a new agent repository. ```bash -gapman init [options] +opengap init [options] ``` | Option | Default | Description | @@ -353,8 +353,8 @@ gapman init [options] | `full` | Everything in standard + `memory/`, `hooks/`, `examples/`, `agents/`, `compliance/`, `config/`, `.gitignore` | ```bash -gapman init --template minimal -gapman init --template full --dir ./my-agent +opengap init --template minimal +opengap init --template full --dir ./my-agent ``` --- @@ -364,7 +364,7 @@ gapman init --template full --dir ./my-agent Validate an agent against the specification and optionally check regulatory compliance. ```bash -gapman validate [options] +opengap validate [options] ``` | Option | Default | Description | @@ -392,9 +392,9 @@ gapman validate [options] - Vendor management metadata for dependencies ```bash -gapman validate -gapman validate --compliance -gapman validate -d ./examples/full --compliance +opengap validate +opengap validate --compliance +opengap validate -d ./examples/full --compliance ``` --- @@ -404,7 +404,7 @@ gapman validate -d ./examples/full --compliance Display a formatted summary of the agent configuration. ```bash -gapman info [options] +opengap info [options] ``` | Option | Default | Description | @@ -414,8 +414,8 @@ gapman info [options] Shows: name, version, description, author, license, model preferences, skills, tools, sub-agents, runtime config, compliance settings, tags, and a SOUL.md preview. ```bash -gapman info -gapman info -d ./examples/standard +opengap info +opengap info -d ./examples/standard ``` --- @@ -425,7 +425,7 @@ gapman info -d ./examples/standard Export an agent to another framework's format. ```bash -gapman export [options] +opengap export [options] ``` | Option | Default | Description | @@ -449,22 +449,22 @@ gapman export [options] ```bash # Print system prompt to terminal -gapman export --format system-prompt +opengap export --format system-prompt # Save Claude Code format to file -gapman export --format claude-code --output CLAUDE.md +opengap export --format claude-code --output CLAUDE.md # Generate OpenAI Python code -gapman export --format openai --output agent.py +opengap export --format openai --output agent.py # Preview Lyzr API payload -gapman export --format lyzr -d ./examples/lyzr-agent +opengap export --format lyzr -d ./examples/lyzr-agent # Preview GitHub Models payload -gapman export --format github -d ./examples/standard +opengap export --format github -d ./examples/standard # Export CrewAI config -gapman export --format crewai -d ./examples/standard +opengap export --format crewai -d ./examples/standard ``` --- @@ -474,7 +474,7 @@ gapman export --format crewai -d ./examples/standard Import from another agent framework into gitagent format. ```bash -gapman import --from [options] +opengap import --from [options] ``` | Option | Default | Description | @@ -492,9 +492,9 @@ gapman import --from [options] | `crewai` | CrewAI YAML config | `agent.yaml`, `SOUL.md`, sub-agents in `agents/` | ```bash -gapman import --from claude ./my-claude-project -gapman import --from cursor ./.cursorrules -gapman import --from crewai ./crew.yaml --dir ./imported-agent +opengap import --from claude ./my-claude-project +opengap import --from cursor ./.cursorrules +opengap import --from crewai ./crew.yaml --dir ./imported-agent ``` --- @@ -504,7 +504,7 @@ gapman import --from crewai ./crew.yaml --dir ./imported-agent Resolve and install git-based agent dependencies declared in `agent.yaml`. ```bash -gapman install [options] +opengap install [options] ``` | Option | Default | Description | @@ -518,8 +518,8 @@ For each entry in `dependencies`: - Validates that installed dependencies contain `agent.yaml` ```bash -gapman install -gapman install -d ./my-agent +opengap install +opengap install -d ./my-agent ``` --- @@ -529,7 +529,7 @@ gapman install -d ./my-agent Generate a comprehensive compliance audit report. ```bash -gapman audit [options] +opengap audit [options] ``` | Option | Default | Description | @@ -549,8 +549,8 @@ gapman audit [options] 9. **Audit Hooks** — hooks.yaml and compliance-flagged hooks ```bash -gapman audit -gapman audit -d ./examples/full +opengap audit +opengap audit -d ./examples/full ``` --- @@ -562,7 +562,7 @@ Manage agent skills — search registries, install, list, and inspect. #### skills search ```bash -gapman skills search [options] +opengap skills search [options] ``` | Option | Default | Description | @@ -574,7 +574,7 @@ gapman skills search [options] #### skills install ```bash -gapman skills install [options] +opengap skills install [options] ``` | Option | Default | Description | @@ -588,7 +588,7 @@ gapman skills install [options] #### skills list ```bash -gapman skills list [options] +opengap skills list [options] ``` | Option | Default | Description | @@ -599,7 +599,7 @@ gapman skills list [options] #### skills info ```bash -gapman skills info [options] +opengap skills info [options] ``` | Option | Default | Description | @@ -607,10 +607,10 @@ gapman skills info [options] | `-d, --dir ` | `.` | Agent directory | ```bash -gapman skills search "code review" -gapman skills install code-review --global -gapman skills list -gapman skills info code-review +opengap skills search "code review" +opengap skills install code-review --global +opengap skills list +opengap skills info code-review ``` --- @@ -620,7 +620,7 @@ gapman skills info code-review Run an agent interactively with a specific adapter/framework. ```bash -gapman run [options] +opengap run [options] ``` | Option | Default | Description | @@ -654,31 +654,31 @@ Either `--repo` or `--dir` is required. ```bash # Run a local agent with Claude Code (interactive) -gapman run -d ./my-agent +opengap run -d ./my-agent # Run from a git repo -gapman run -r https://github.com/user/agent +opengap run -r https://github.com/user/agent # Run with GitHub Models -gapman run -d ./my-agent -a github -p "Review my code" +opengap run -d ./my-agent -a github -p "Review my code" # Run with Lyzr -gapman run -r https://github.com/user/agent -a lyzr -p "Hello" +opengap run -r https://github.com/user/agent -a lyzr -p "Hello" # Auto-detect adapter from repo contents -gapman run -r https://github.com/user/agent -a git -p "Hello" +opengap run -r https://github.com/user/agent -a git -p "Hello" # One-shot prompt mode -gapman run -d ./my-agent -p "Review my authentication code" +opengap run -d ./my-agent -p "Review my authentication code" # Run an agent definition against a separate target workspace -gapman run -d ./agents/reviewer --workspace ~/code/my-app -a claude -p "Review this repository" +opengap run -d ./agents/reviewer --workspace ~/code/my-app -a claude -p "Review this repository" # Run a specific branch, force refresh -gapman run -r https://github.com/user/agent -b develop --refresh +opengap run -r https://github.com/user/agent -b develop --refresh # Just output the system prompt (no runner) -gapman run -d ./my-agent -a prompt +opengap run -d ./my-agent -a prompt ``` --- @@ -688,7 +688,7 @@ gapman run -d ./my-agent -a prompt Manage Lyzr Studio agents — create, update, inspect, and run. ```bash -gapman lyzr [options] +opengap lyzr [options] ``` #### lyzr create @@ -696,7 +696,7 @@ gapman lyzr [options] Create a new agent on Lyzr Studio from the local gitagent definition. ```bash -gapman lyzr create [options] +opengap lyzr create [options] ``` | Option | Default | Description | @@ -707,7 +707,7 @@ gapman lyzr create [options] Saves the returned agent ID to `.lyzr_agent_id` for reuse. ```bash -gapman lyzr create -d ./examples/lyzr-agent +opengap lyzr create -d ./examples/lyzr-agent ``` #### lyzr update @@ -715,7 +715,7 @@ gapman lyzr create -d ./examples/lyzr-agent Push the current gitagent definition to an existing Lyzr agent. ```bash -gapman lyzr update [options] +opengap lyzr update [options] ``` | Option | Default | Description | @@ -725,8 +725,8 @@ gapman lyzr update [options] | `--api-key ` | — | Lyzr API key (or set `LYZR_API_KEY`) | ```bash -gapman lyzr update -d ./examples/lyzr-agent -gapman lyzr update --agent-id abc123 +opengap lyzr update -d ./examples/lyzr-agent +opengap lyzr update --agent-id abc123 ``` #### lyzr info @@ -734,7 +734,7 @@ gapman lyzr update --agent-id abc123 Show the Lyzr agent ID linked to this gitagent directory. ```bash -gapman lyzr info [options] +opengap lyzr info [options] ``` | Option | Default | Description | @@ -742,7 +742,7 @@ gapman lyzr info [options] | `-d, --dir ` | `.` | Agent directory | ```bash -gapman lyzr info -d ./examples/lyzr-agent +opengap lyzr info -d ./examples/lyzr-agent ``` #### lyzr run @@ -750,7 +750,7 @@ gapman lyzr info -d ./examples/lyzr-agent Clone a git agent repo, create it on Lyzr, and chat — all in one command. ```bash -gapman lyzr run [options] +opengap lyzr run [options] ``` | Option | Default | Description | @@ -767,13 +767,13 @@ If no `.lyzr_agent_id` exists, the agent is created on Lyzr Studio first. If no ```bash # Full one-liner: clone + create + chat -gapman lyzr run -r https://github.com/user/my-agent -p "Hello" +opengap lyzr run -r https://github.com/user/my-agent -p "Hello" # From local directory -gapman lyzr run -d ./examples/lyzr-agent -p "Summarize AI trends" +opengap lyzr run -d ./examples/lyzr-agent -p "Summarize AI trends" # Just create (no prompt) -gapman lyzr run -r https://github.com/user/my-agent +opengap lyzr run -r https://github.com/user/my-agent ``` **Lyzr API Endpoints:** @@ -878,7 +878,7 @@ GitHub Models API payload (OpenAI-compatible chat completions). Returns JSON wit ## Adapters & Runners -When you run `gapman run -a `, the corresponding runner prepares the environment and launches the framework. +When you run `opengap run -a `, the corresponding runner prepares the environment and launches the framework. ### Claude Runner @@ -1005,7 +1005,7 @@ Adapter: `github` ```bash export GITHUB_TOKEN="ghp_..." -gapman run -d ./my-agent -a github -p "Review this code" +opengap run -d ./my-agent -a github -p "Review this code" ``` --- @@ -1032,10 +1032,10 @@ The git runner clones a repository and auto-detects the best adapter from the ag ```bash # Auto-detect and run -gapman run -a git -r https://github.com/user/my-agent -p "Hello" +opengap run -a git -r https://github.com/user/my-agent -p "Hello" # Force a specific branch -gapman run -a git -r https://github.com/user/my-agent -b develop --refresh -p "Hello" +opengap run -a git -r https://github.com/user/my-agent -b develop --refresh -p "Hello" ``` --- @@ -1157,7 +1157,7 @@ compliance/ ### Audit Report -Run `gapman audit` to generate a section-by-section compliance checklist with pass/fail/warning indicators for every regulatory requirement. +Run `opengap audit` to generate a section-by-section compliance checklist with pass/fail/warning indicators for every regulatory requirement. --- @@ -1186,7 +1186,7 @@ dependencies: risk_assessment: low ``` -Run `gapman install` to resolve and clone all dependencies. +Run `opengap install` to resolve and clone all dependencies. ### Sub-Agents @@ -1347,8 +1347,8 @@ examples/lyzr-agent/ ``` ```bash -gapman lyzr create -d ./examples/lyzr-agent -gapman lyzr run -d ./examples/lyzr-agent -p "What are AI agents?" +opengap lyzr create -d ./examples/lyzr-agent +opengap lyzr run -d ./examples/lyzr-agent -p "What are AI agents?" ``` --- @@ -1378,16 +1378,16 @@ gitagent/ ├── src/ │ ├── index.ts # CLI entry point (Commander) │ ├── commands/ -│ │ ├── init.ts # gapman init -│ │ ├── validate.ts # gapman validate -│ │ ├── info.ts # gapman info -│ │ ├── export.ts # gapman export -│ │ ├── import.ts # gapman import -│ │ ├── install.ts # gapman install -│ │ ├── audit.ts # gapman audit -│ │ ├── skills.ts # gapman skills -│ │ ├── run.ts # gapman run -│ │ └── lyzr.ts # gapman lyzr +│ │ ├── init.ts # opengap init +│ │ ├── validate.ts # opengap validate +│ │ ├── info.ts # opengap info +│ │ ├── export.ts # opengap export +│ │ ├── import.ts # opengap import +│ │ ├── install.ts # opengap install +│ │ ├── audit.ts # opengap audit +│ │ ├── skills.ts # opengap skills +│ │ ├── run.ts # opengap run +│ │ └── lyzr.ts # opengap lyzr │ ├── adapters/ │ │ ├── index.ts # Re-exports all adapters │ │ ├── system-prompt.ts # Markdown system prompt diff --git a/docs/adapters/gemini.md b/docs/adapters/gemini.md index 34a1f45..97deb88 100644 --- a/docs/adapters/gemini.md +++ b/docs/adapters/gemini.md @@ -83,10 +83,10 @@ gemini --version ```bash # Export to stdout -gapman export --format gemini -d ./my-agent +opengap export --format gemini -d ./my-agent # Save to file -gapman export --format gemini -d ./my-agent -o gemini-export.txt +opengap export --format gemini -d ./my-agent -o gemini-export.txt # The export includes both GEMINI.md and .gemini/settings.json content ``` @@ -125,13 +125,13 @@ Agent description ```bash # Interactive mode -gapman run ./my-agent --adapter gemini +opengap run ./my-agent --adapter gemini # Single-shot mode with prompt -gapman run ./my-agent --adapter gemini -p "Explain quantum computing" +opengap run ./my-agent --adapter gemini -p "Explain quantum computing" # From git repository -gapman run --repo https://github.com/user/agent.git --adapter gemini +opengap run --repo https://github.com/user/agent.git --adapter gemini ``` **What Happens:** @@ -145,11 +145,11 @@ gapman run --repo https://github.com/user/agent.git --adapter gemini ```bash # Import from existing Gemini CLI project -gapman import --from gemini /path/to/gemini-project -d ./imported-agent +opengap import --from gemini /path/to/gemini-project -d ./imported-agent # Verify the imported agent cd ./imported-agent -gapman validate +opengap validate ``` **What Gets Created:** @@ -326,7 +326,7 @@ hooks: 3. **Create proper tool schemas** - imported tools have minimal schemas -4. **Test the agent** with `gapman validate` +4. **Test the agent** with `opengap validate` ### When Running diff --git a/docs/comparison.md b/docs/comparison.md index aed84bb..eaec4ae 100644 --- a/docs/comparison.md +++ b/docs/comparison.md @@ -12,7 +12,7 @@ This document compares gitagent against three common alternatives developers rea |-----------|----------|----------------------|---------------|-------------------------------| | **Where does the agent live?** | Git repository = the agent | Separate spec file, usually checked into a repo | Config file(s) checked into a repo | Python/TypeScript class, checked into a repo | | **Portable across frameworks?** | ✅ Yes — `export` to 9+ targets | ⚠️ Depends on adoption | ❌ No — framework-specific parsers | ❌ No — tied to one framework | -| **Runnable from repo URL?** | ✅ `gapman run -r github.com/org/agent` | ❌ No | ❌ No | ❌ No | +| **Runnable from repo URL?** | ✅ `opengap run -r github.com/org/agent` | ❌ No | ❌ No | ❌ No | | **Version-controlled identity** | ✅ Git tags = agent versions | ⚠️ Optional | ⚠️ Manual | ⚠️ Git blame only | | **Compliance / audit built-in** | ✅ Yes — FINRA, SEC, CFPB, SR 11-7 fields | ❌ No | ❌ No | ❌ No | | **Multi-agent topology** | ✅ Native `agents:` block + SOD | ❌ No standard | ❌ No | ⚠️ Framework-specific | @@ -51,8 +51,8 @@ Many teams define agents with hand-rolled YAML files that are parsed by custom c **Raw YAML/JSON** gives you full flexibility but zero standardization. Every team invents their own schema, every framework reads it differently, and there is no tooling layer. **gitagent** gives you a *community standard* schema with: -- A validated `agent.yaml` spec (run `gapman validate` to check conformance) -- A CLI layer (`gapman export`, `gapman run`, `gapman audit`) that acts on the standard +- A validated `agent.yaml` spec (run `opengap validate` to check conformance) +- A CLI layer (`opengap export`, `opengap run`, `opengap audit`) that acts on the standard - Installable skills from a shared ecosystem (`npx skills add`) - A compliance block that maps to real regulatory frameworks (FINRA 3110/4511, SEC 17a-4, SR 11-7, CFPB) — not invented fields @@ -65,11 +65,11 @@ Many teams define agents with hand-rolled YAML files that are parsed by custom c Raw YAML → gitagent is straightforward: ```bash -gapman init -t minimal # scaffold the standard layout +opengap init -t minimal # scaffold the standard layout # copy your system prompt → SOUL.md # copy your rules → RULES.md # move your config fields into agent.yaml -gapman validate # check conformance +opengap validate # check conformance ``` --- @@ -88,11 +88,11 @@ LangChain agents, CrewAI agents, AutoGen agents, etc. are all defined as Python **gitagent** sits *above* frameworks. You define the agent once in the standard format, then export to the framework of your choice: ```bash -gapman export -f crewai # → YAML config for CrewAI -gapman export -f openai # → Python script for OpenAI Agents SDK -gapman export -f langchain # → Python script for LangChain -gapman export -f langgraph # → Python StateGraph for LangGraph -gapman export -f claude-code # → CLAUDE.md for Claude Code +opengap export -f crewai # → YAML config for CrewAI +opengap export -f openai # → Python script for OpenAI Agents SDK +opengap export -f langchain # → Python script for LangChain +opengap export -f langgraph # → Python StateGraph for LangGraph +opengap export -f claude-code # → CLAUDE.md for Claude Code ``` The framework-native implementation becomes a *derived artifact* of the canonical gitagent definition, not the source of truth. @@ -104,7 +104,7 @@ The framework-native implementation becomes a *derived artifact* of the canonica ### The hybrid pattern -Many teams combine both: gitagent defines the agent’s identity, compliance, and skills; framework-native code handles tool implementations, memory backends, and custom orchestration. The `gapman export` output is a starting point, not a locked output. +Many teams combine both: gitagent defines the agent’s identity, compliance, and skills; framework-native code handles tool implementations, memory backends, and custom orchestration. The `opengap export` output is a starting point, not a locked output. --- @@ -135,7 +135,7 @@ compliance: - [maker, checker] # No agent may both make and check its own work ``` -Running `gapman audit` against this produces a structured compliance report. No other agent definition format offers this. +Running `opengap audit` against this produces a structured compliance report. No other agent definition format offers this. For teams building agents in regulated industries — financial services, healthcare (HIPAA), or any environment governed by SEC/FINRA/CFPB/MiCA rules — gitagent’s compliance model is the primary differentiator. diff --git a/examples/gitagent-helper/README.md b/examples/gitagent-helper/README.md index 5902b00..268a9d9 100644 --- a/examples/gitagent-helper/README.md +++ b/examples/gitagent-helper/README.md @@ -6,10 +6,10 @@ The official gitagent assistant — an AI agent that helps you build, run, and m ```bash # Run directly from GitHub -gapman run -r https://github.com/anthropics/gitagent-helper +opengap run -r https://github.com/anthropics/gitagent-helper # Or with a prompt -gapman run -r https://github.com/anthropics/gitagent-helper -p "How do I create my first agent?" +opengap run -r https://github.com/anthropics/gitagent-helper -p "How do I create my first agent?" ``` ## What It Can Do @@ -34,7 +34,7 @@ gapman run -r https://github.com/anthropics/gitagent-helper -p "How do I create ```bash git clone https://github.com/anthropics/gitagent-helper -gapman run -d ./gitagent-helper +opengap run -d ./gitagent-helper ``` ## Structure diff --git a/examples/gitagent-helper/RULES.md b/examples/gitagent-helper/RULES.md index efa4c9b..865bf2f 100644 --- a/examples/gitagent-helper/RULES.md +++ b/examples/gitagent-helper/RULES.md @@ -5,7 +5,7 @@ - Show the expected output or result of a command - Use real, working examples — not pseudocode - Mention required environment variables before showing adapter commands -- Suggest `gapman validate` after any agent.yaml changes +- Suggest `opengap validate` after any agent.yaml changes ## Must Never - Make up CLI flags that don't exist diff --git a/examples/gitagent-helper/knowledge/command-reference.md b/examples/gitagent-helper/knowledge/command-reference.md index e09481d..1f447f7 100644 --- a/examples/gitagent-helper/knowledge/command-reference.md +++ b/examples/gitagent-helper/knowledge/command-reference.md @@ -4,22 +4,22 @@ | Command | Description | |---------|-------------| -| `gapman init` | Scaffold a new agent repo (`-t minimal\|standard\|full`) | -| `gapman validate` | Validate agent.yaml and structure (`-c` for compliance) | -| `gapman info` | Show agent summary | -| `gapman export` | Export to other formats (`-f system-prompt\|claude-code\|openai\|crewai\|openclaw\|nanobot\|lyzr\|github`) | -| `gapman import` | Import from other frameworks (`--from claude\|cursor\|crewai`) | -| `gapman install` | Resolve git dependencies | -| `gapman audit` | Generate compliance audit report | -| `gapman skills search` | Search skill registries | -| `gapman skills install` | Install a skill | -| `gapman skills list` | List discovered skills | -| `gapman skills info` | Inspect a skill | -| `gapman run` | Run agent with an adapter (`-a claude\|openai\|crewai\|openclaw\|nanobot\|lyzr\|github\|git\|prompt`) | -| `gapman lyzr create` | Create agent on Lyzr Studio | -| `gapman lyzr update` | Push changes to Lyzr | -| `gapman lyzr info` | Show linked Lyzr agent ID | -| `gapman lyzr run` | Clone + create + chat on Lyzr in one command | +| `opengap init` | Scaffold a new agent repo (`-t minimal\|standard\|full`) | +| `opengap validate` | Validate agent.yaml and structure (`-c` for compliance) | +| `opengap info` | Show agent summary | +| `opengap export` | Export to other formats (`-f system-prompt\|claude-code\|openai\|crewai\|openclaw\|nanobot\|lyzr\|github`) | +| `opengap import` | Import from other frameworks (`--from claude\|cursor\|crewai`) | +| `opengap install` | Resolve git dependencies | +| `opengap audit` | Generate compliance audit report | +| `opengap skills search` | Search skill registries | +| `opengap skills install` | Install a skill | +| `opengap skills list` | List discovered skills | +| `opengap skills info` | Inspect a skill | +| `opengap run` | Run agent with an adapter (`-a claude\|openai\|crewai\|openclaw\|nanobot\|lyzr\|github\|git\|prompt`) | +| `opengap lyzr create` | Create agent on Lyzr Studio | +| `opengap lyzr update` | Push changes to Lyzr | +| `opengap lyzr info` | Show linked Lyzr agent ID | +| `opengap lyzr run` | Clone + create + chat on Lyzr in one command | ## Common Flags diff --git a/examples/gitagent-helper/skills/create-agent/SKILL.md b/examples/gitagent-helper/skills/create-agent/SKILL.md index e16e9a6..b98386b 100644 --- a/examples/gitagent-helper/skills/create-agent/SKILL.md +++ b/examples/gitagent-helper/skills/create-agent/SKILL.md @@ -16,7 +16,7 @@ metadata: 2. Write `agent.yaml` with required fields (see below) 3. Create `SOUL.md` with agent identity 4. Add skills, tools, and knowledge as needed -5. Validate: `gapman validate -d ./my-agent` +5. Validate: `opengap validate -d ./my-agent` ## agent.yaml Reference diff --git a/examples/gitagent-helper/skills/export-agent/SKILL.md b/examples/gitagent-helper/skills/export-agent/SKILL.md index 325123a..31a1358 100644 --- a/examples/gitagent-helper/skills/export-agent/SKILL.md +++ b/examples/gitagent-helper/skills/export-agent/SKILL.md @@ -16,7 +16,7 @@ After exporting, check the output matches expectations: ```bash # Verify export file was created and contains agent name -gapman export -f system-prompt -d ./my-agent | head -5 +opengap export -f system-prompt -d ./my-agent | head -5 ``` ## Export @@ -24,7 +24,7 @@ gapman export -f system-prompt -d ./my-agent | head -5 Convert a gitagent definition to another framework: ```bash -gapman export -f -d ./my-agent [-o output-file] +opengap export -f -d ./my-agent [-o output-file] ``` ### Formats @@ -44,19 +44,19 @@ gapman export -f -d ./my-agent [-o output-file] ```bash # Get a system prompt for any LLM -gapman export -f system-prompt -d ./my-agent +opengap export -f system-prompt -d ./my-agent # Generate a CLAUDE.md -gapman export -f claude-code -d ./my-agent -o CLAUDE.md +opengap export -f claude-code -d ./my-agent -o CLAUDE.md # Generate Python code for OpenAI -gapman export -f openai -d ./my-agent -o agent.py +opengap export -f openai -d ./my-agent -o agent.py # Preview what Lyzr API will receive -gapman export -f lyzr -d ./my-agent +opengap export -f lyzr -d ./my-agent # Preview GitHub Models payload -gapman export -f github -d ./my-agent +opengap export -f github -d ./my-agent ``` ## Import @@ -64,7 +64,7 @@ gapman export -f github -d ./my-agent Convert existing agent frameworks into gitagent: ```bash -gapman import --from [-d target-dir] +opengap import --from [-d target-dir] ``` ### Sources @@ -79,11 +79,11 @@ gapman import --from [-d target-dir] ```bash # Import a Claude Code project -gapman import --from claude ./my-project +opengap import --from claude ./my-project # Import from Cursor -gapman import --from cursor ./.cursorrules +opengap import --from cursor ./.cursorrules # Import CrewAI config -gapman import --from crewai ./crew.yaml -d ./imported +opengap import --from crewai ./crew.yaml -d ./imported ``` diff --git a/examples/gitagent-helper/skills/get-started/SKILL.md b/examples/gitagent-helper/skills/get-started/SKILL.md index 6a2d3b7..f88cf1d 100644 --- a/examples/gitagent-helper/skills/get-started/SKILL.md +++ b/examples/gitagent-helper/skills/get-started/SKILL.md @@ -17,8 +17,8 @@ When a user is new to gitagent, wants to set up their first agent, or asks "how ### Installation ```bash -npm install -g @open-gitagent/gapman -gapman --version +npm install -g @open-gitagent/opengap +opengap --version ``` ### Create Your First Agent @@ -27,32 +27,32 @@ Walk the user through these steps: 1. **Scaffold** — Pick a template: ```bash # Minimal (2 files) - gapman init --template minimal --dir ./my-agent + opengap init --template minimal --dir ./my-agent # Standard (with skills, tools, knowledge) - gapman init --template standard --dir ./my-agent + opengap init --template standard --dir ./my-agent # Full (compliance, hooks, memory, workflows) - gapman init --template full --dir ./my-agent + opengap init --template full --dir ./my-agent ``` 2. **Edit** — Customize `agent.yaml` (name, description, model) and `SOUL.md` (identity, personality) 3. **Validate** — Check your work: ```bash - gapman validate -d ./my-agent + opengap validate -d ./my-agent ``` 4. **Run** — Launch with Claude: ```bash - gapman run -d ./my-agent + opengap run -d ./my-agent ``` 5. **Share** — Push to git and anyone can run it: ```bash cd my-agent && git init && git add . && git commit -m "Initial agent" # Push to GitHub, then: - gapman run -r https://github.com/you/my-agent + opengap run -r https://github.com/you/my-agent ``` ### Minimum Required Files diff --git a/examples/gitagent-helper/skills/manage-skills/SKILL.md b/examples/gitagent-helper/skills/manage-skills/SKILL.md index bc4fa08..0fd92d3 100644 --- a/examples/gitagent-helper/skills/manage-skills/SKILL.md +++ b/examples/gitagent-helper/skills/manage-skills/SKILL.md @@ -18,49 +18,49 @@ When a user wants to find skills, install them, create new ones, or understand t After installing a skill, confirm it's available: ```bash -gapman skills list -d ./my-agent | grep "code-review" +opengap skills list -d ./my-agent | grep "code-review" ``` ## Search Skills ```bash # Search SkillsMP registry -gapman skills search "code review" +opengap skills search "code review" # Search GitHub -gapman skills search "pdf reader" --provider github +opengap skills search "pdf reader" --provider github # Limit results -gapman skills search "testing" --limit 5 +opengap skills search "testing" --limit 5 ``` ## Install Skills ```bash # Install from SkillsMP to agent-local skills/ -gapman skills install code-review -d ./my-agent +opengap skills install code-review -d ./my-agent # Install globally to ~/.agents/skills/ -gapman skills install code-review --global +opengap skills install code-review --global # Install from GitHub -gapman skills install owner/repo#skills/my-skill --provider github +opengap skills install owner/repo#skills/my-skill --provider github ``` ## List Skills ```bash # Show all discovered skills (local + global) -gapman skills list -d ./my-agent +opengap skills list -d ./my-agent # Only agent-local skills -gapman skills list -d ./my-agent --local +opengap skills list -d ./my-agent --local ``` ## Inspect a Skill ```bash -gapman skills info code-review -d ./my-agent +opengap skills info code-review -d ./my-agent ``` Shows: name, description, license, allowed tools, metadata, optional directories. @@ -96,7 +96,7 @@ skills: 4. Validate: ```bash -gapman validate -d ./my-agent +opengap validate -d ./my-agent ``` ## Skill Discovery Paths diff --git a/examples/gitagent-helper/skills/run-agent/SKILL.md b/examples/gitagent-helper/skills/run-agent/SKILL.md index e4d7c30..53a3ae9 100644 --- a/examples/gitagent-helper/skills/run-agent/SKILL.md +++ b/examples/gitagent-helper/skills/run-agent/SKILL.md @@ -25,13 +25,13 @@ If you see authentication errors: ```bash # Run local agent with Claude (default) -gapman run -d ./my-agent +opengap run -d ./my-agent # Run from git repo -gapman run -r https://github.com/user/agent +opengap run -r https://github.com/user/agent # Run with a prompt (one-shot mode) -gapman run -d ./my-agent -p "Review my code" +opengap run -d ./my-agent -p "Review my code" ``` ## Adapters @@ -52,24 +52,24 @@ gapman run -d ./my-agent -p "Review my code" ```bash # Claude (interactive) -gapman run -d ./my-agent +opengap run -d ./my-agent # GitHub Models (one-shot, streaming) export GITHUB_TOKEN="ghp_..." -gapman run -d ./my-agent -a github -p "Explain this codebase" +opengap run -d ./my-agent -a github -p "Explain this codebase" # Lyzr (creates agent on Lyzr Studio + chats) export LYZR_API_KEY="..." -gapman run -r https://github.com/user/agent -a lyzr -p "Hello" +opengap run -r https://github.com/user/agent -a lyzr -p "Hello" # Lyzr one-liner (clone + create + chat) -gapman lyzr run -r https://github.com/user/agent -p "Hello" +opengap lyzr run -r https://github.com/user/agent -p "Hello" # Auto-detect adapter from repo -gapman run -r https://github.com/user/agent -a git -p "Hello" +opengap run -r https://github.com/user/agent -a git -p "Hello" # Just print the system prompt -gapman run -d ./my-agent -a prompt +opengap run -d ./my-agent -a prompt ``` ## Git Caching @@ -77,13 +77,13 @@ gapman run -d ./my-agent -a prompt Repos cloned via `-r` are cached at `~/.gitagent/cache/`: ```bash # Use cache (default) -gapman run -r https://github.com/user/agent +opengap run -r https://github.com/user/agent # Force refresh -gapman run -r https://github.com/user/agent --refresh +opengap run -r https://github.com/user/agent --refresh # No cache (temp dir, deleted after) -gapman run -r https://github.com/user/agent --no-cache +opengap run -r https://github.com/user/agent --no-cache ``` ## Auto-Detection (`-a git`) diff --git a/examples/jason-my-claw-is-the-law-deebee-4567b4/README.md b/examples/jason-my-claw-is-the-law-deebee-4567b4/README.md index 769c4ac..5d5f54a 100644 --- a/examples/jason-my-claw-is-the-law-deebee-4567b4/README.md +++ b/examples/jason-my-claw-is-the-law-deebee-4567b4/README.md @@ -55,10 +55,10 @@ jason-my-claw-is-the-law-deebee-4567b4/ ```bash # Install gitagent -npm install -g @open-gitagent/gapman +npm install -g @open-gitagent/opengap # Clone this agent -gapman clone open-gitagent/gitagent examples/jason-my-claw-is-the-law-deebee-4567b4 my-jason +opengap clone open-gitagent/gitagent examples/jason-my-claw-is-the-law-deebee-4567b4 my-jason # Review the rules before running cat my-jason/RULES.md diff --git a/examples/lyzr-agent/README.md b/examples/lyzr-agent/README.md index 5ebfe12..aed6d42 100644 --- a/examples/lyzr-agent/README.md +++ b/examples/lyzr-agent/README.md @@ -6,13 +6,13 @@ A gitagent example designed to run on [Lyzr Studio](https://studio.lyzr.ai). ```bash # Create the agent on Lyzr -gapman lyzr create -d ./examples/lyzr-agent +opengap lyzr create -d ./examples/lyzr-agent # Chat with it -gapman lyzr run -d ./examples/lyzr-agent -p "Summarize the latest trends in AI agents" +opengap lyzr run -d ./examples/lyzr-agent -p "Summarize the latest trends in AI agents" # Or do it all in one command from a git repo -gapman lyzr run -r https://github.com/youruser/lyzr-research-agent -p "What is RAG?" +opengap lyzr run -r https://github.com/youruser/lyzr-research-agent -p "What is RAG?" ``` ## Prerequisites @@ -29,11 +29,11 @@ Get your API key from [Lyzr Studio](https://studio.lyzr.ai). | Command | Description | |---------|-------------| -| `gapman lyzr create -d .` | Create the agent on Lyzr Studio | -| `gapman lyzr update -d .` | Push local changes to Lyzr | -| `gapman lyzr info -d .` | Show the linked Lyzr agent ID | -| `gapman lyzr run -d . -p "..."` | Chat with the agent | -| `gapman export -d . -f lyzr` | Preview the Lyzr API payload | +| `opengap lyzr create -d .` | Create the agent on Lyzr Studio | +| `opengap lyzr update -d .` | Push local changes to Lyzr | +| `opengap lyzr info -d .` | Show the linked Lyzr agent ID | +| `opengap lyzr run -d . -p "..."` | Chat with the agent | +| `opengap export -d . -f lyzr` | Preview the Lyzr API payload | ## How It Works @@ -44,4 +44,4 @@ Get your API key from [Lyzr Studio](https://studio.lyzr.ai). 5. `skills/research/SKILL.md` provides structured research instructions 6. `.gitagent_adapter` tells the git runner to use Lyzr automatically -When you run `gapman lyzr create`, all of these files are combined into a single Lyzr API payload and sent to Lyzr Studio. The returned agent ID is saved to `.lyzr_agent_id` for subsequent runs. +When you run `opengap lyzr create`, all of these files are combined into a single Lyzr API payload and sent to Lyzr Studio. The returned agent ID is saved to `.lyzr_agent_id` for subsequent runs. diff --git a/examples/nvidia-deep-researcher/README.md b/examples/nvidia-deep-researcher/README.md index 387acb8..ae6ce04 100644 --- a/examples/nvidia-deep-researcher/README.md +++ b/examples/nvidia-deep-researcher/README.md @@ -21,7 +21,7 @@ This gitagent definition faithfully translates the NVIDIA Jinja2 prompts (`orche | **SOD enforcement** | Implicit in code | Explicit roles, conflicts, and handoffs validated in CI | | **Fork & customize** | Modify Python code | Fork for legal/medical/finance variants without touching code | | **Memory** | No persistence across sessions | Version-controlled research session history | -| **CI/CD** | Manual testing | `gapman validate --compliance` on every push | +| **CI/CD** | Manual testing | `opengap validate --compliance` on every push | | **Audit trail** | None | Every prompt, skill, and rule change traced via git | ## Quick Start @@ -30,23 +30,23 @@ This gitagent definition faithfully translates the NVIDIA Jinja2 prompts (`orche ```bash cd examples/nvidia-deep-researcher -gapman validate --compliance +opengap validate --compliance ``` ### Export ```bash # System prompt (for any LLM) -gapman export --format system-prompt +opengap export --format system-prompt # Claude Code (generates CLAUDE.md) -gapman export --format claude-code +opengap export --format claude-code ``` ### Info ```bash -gapman info +opengap info ``` ## Structure @@ -88,7 +88,7 @@ cd my-legal-researcher # Add legal knowledge docs to knowledge/ # Update agent.yaml with domain-specific metadata -gapman validate --compliance +opengap validate --compliance ``` No Python code changes needed — just edit the markdown and YAML files. diff --git a/examples/standard/memory/daily-log/2026-02-18.md b/examples/standard/memory/daily-log/2026-02-18.md index 67e7366..7bd5626 100644 --- a/examples/standard/memory/daily-log/2026-02-18.md +++ b/examples/standard/memory/daily-log/2026-02-18.md @@ -1,7 +1,7 @@ # 2026-02-18 ## Session Summary -Implemented `gapman run` command with git caching and multi-adapter support. +Implemented `opengap run` command with git caching and multi-adapter support. ## What Happened - Created `src/utils/git-cache.ts` — shallow clone with SHA-based cache at `~/.gitagent/cache/` diff --git a/package-lock.json b/package-lock.json index e77a74c..7a7c847 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { - "name": "@open-gitagent/gapman", - "version": "0.3.2", + "name": "@open-gitagent/opengap", + "version": "0.4.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "@open-gitagent/gapman", - "version": "0.3.2", + "name": "@open-gitagent/opengap", + "version": "0.4.0", "license": "MIT", "dependencies": { "ajv": "^8.17.1", @@ -17,8 +17,8 @@ "js-yaml": "^4.1.0" }, "bin": { - "gapman": "dist/index.js", - "gitagent": "dist/index.js" + "gitagent": "dist/index.js", + "opengap": "dist/index.js" }, "devDependencies": { "@types/inquirer": "^9.0.7", diff --git a/package.json b/package.json index e865087..8effa54 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,10 @@ { - "name": "@open-gitagent/gapman", - "version": "0.3.2", - "description": "GitAgentProtocol (GAP) Manager — framework-agnostic, git-native standard for defining AI agents", + "name": "@open-gitagent/opengap", + "version": "0.4.0", + "description": "OpenGAP — the Git Agent Protocol: a framework-agnostic, git-native standard for defining AI agents", "type": "module", "bin": { - "gapman": "./dist/index.js", + "opengap": "./dist/index.js", "gitagent": "./dist/index.js" }, "scripts": { @@ -15,8 +15,9 @@ "prepublishOnly": "npm run build" }, "keywords": [ + "opengap", "gap", - "gapman", + "git-agent-protocol", "gitagentprotocol", "gitagent", "ai", diff --git a/paper/README.md b/paper/README.md index 8966d18..eb69878 100644 --- a/paper/README.md +++ b/paper/README.md @@ -43,7 +43,7 @@ Preferred BibTeX entry (update year and arXiv id once posted): The fidelity matrix in Appendix B should be regenerated against the current adapters before each submission. The procedure: -1. Run `gapman export --format -o /tmp/export-` for each of the 15 adapters, against both `examples/standard/` and `examples/full/`. +1. Run `opengap export --format -o /tmp/export-` for each of the 15 adapters, against both `examples/standard/` and `examples/full/`. 2. For each adapter output, check whether each of the nine GAP elements (SOUL, RULES, DUTIES, skills, tools, hooks, memory, sub-agents, compliance) is (F) fully preserved, (P) partially preserved, or (-) absent. 3. Commit the result to `tables/fidelity-matrix.csv`. 4. Update the tabular block in `open-gap.tex`, Appendix B, from the CSV. diff --git a/paper/open-gap.md b/paper/open-gap.md index f59b33b..3ca3076 100644 --- a/paper/open-gap.md +++ b/paper/open-gap.md @@ -15,7 +15,7 @@ AI agents are being deployed into regulated, high-stakes environments faster tha Under OpenGAP, an agent is fully described by files in a directory: identity (`SOUL.md`), hard constraints (`RULES.md`), segregation-of-duties (`DUTIES.md`), skills, tools, knowledge, memory, hooks, sub-agents, and regulatory-compliance artifacts. A single canonical definition deterministically exports to **15 execution environments** (Claude Code, OpenAI Agents SDK, CrewAI, Cursor, Gemini CLI, Codex, OpenCode, Kiro, Lyzr, OpenClaw, Nanobot, GitHub Copilot, GitHub Models, GitClaw, system-prompt) with a documented **fidelity profile** per target. **Fourteen lifecycle patterns** — which we show decompose into four meta-patterns: *structural guarantees*, *lifecycle operations*, *collaboration primitives*, and *runtime hooks* — emerge naturally from the git substrate. Compliance is a first-class spec element, mapped onto FINRA 3110/4511/2210, SEC Reg BI/Reg S-P/17a-4, Federal Reserve SR 11-7, and CFPB Circular 2022-03, and enforced through `pre_tool_use` hooks with `fail_open: false` semantics. We prove a simple **structural SOD theorem**: any segregation-of-duties conflict declared in `DUTIES.md` is unbypassable by the agent itself, provided branch-protection rules are active and the agent has no force-push rights. -OpenGAP is MIT-licensed. The reference implementation has **2,700+ GitHub stars**, 21 adapters, 11 runtime runners, and ships as `@open-gitagent/gapman` on npm. This paper consolidates the specification, the adapter model, the patterns, and the compliance framing into a single citable artifact, and sets an agenda for conformance testing, formal SOD verification, and an event schema for regulated agent-to-agent interaction. +OpenGAP is MIT-licensed. The reference implementation has **2,700+ GitHub stars**, 21 adapters, 11 runtime runners, and ships as `@open-gitagent/opengap` on npm. This paper consolidates the specification, the adapter model, the patterns, and the compliance framing into a single citable artifact, and sets an agenda for conformance testing, formal SOD verification, and an event schema for regulated agent-to-agent interaction. **Keywords:** AI agents · protocols · version control · governance · segregation of duties · FINRA · SEC · SR 11-7 · model risk management · interoperability · open standards. @@ -136,7 +136,7 @@ LangChain, LangGraph, CrewAI, AutoGen, and similar frameworks define the agent a - **Not auditable as a unit.** The agent's rules, identity, and policy are entangled with control flow. A compliance reviewer must read code rather than read a manifest. - **Not semantically versioned.** `git diff` between two commits of a LangGraph agent shows line-level changes, not "v2.1.0 changed the supervisory policy from `review_above_cents: 10000` to `review_above_cents: 5000`." -GAP sits **above** frameworks: the canonical definition is the repository, and the framework-native implementation is a *derived artifact* produced by `gapman export`. Teams that already have framework-native agents can adopt GAP incrementally by using `gapman import --from ` to extract a canonical definition, then treating the framework-native version as a generated output. +GAP sits **above** frameworks: the canonical definition is the repository, and the framework-native implementation is a *derived artifact* produced by `opengap export`. Teams that already have framework-native agents can adopt GAP incrementally by using `opengap import --from ` to extract a canonical definition, then treating the framework-native version as a generated output. ### 3.4 Raw YAML/JSON configuration @@ -231,7 +231,7 @@ Three files carry the agent's normative content. They are read in this order by ### 4.5 Capabilities -**Skills** ($S$) are reusable capability modules. Each skill is a directory with `SKILL.md` (Markdown + YAML frontmatter), optional `scripts/`, `references/`, `assets/`, and `examples/`. Skills are installable from a shared registry via `gapman skills install`; one skill can be shared across many agents. +**Skills** ($S$) are reusable capability modules. Each skill is a directory with `SKILL.md` (Markdown + YAML frontmatter), optional `scripts/`, `references/`, `assets/`, and `examples/`. Skills are installable from a shared registry via `opengap skills install`; one skill can be shared across many agents. **Tools** ($T$) are MCP-compatible schemas annotated with cost class (`none|low|medium|high`) and side-effect class. Implementations may be local (`tools/name.py`) or remote (URL). @@ -261,7 +261,7 @@ Each hook has a `fail_open` flag. `fail_open: true` means a hook failure is non- ### 4.7 The manifest -Appendix A excerpts `agent-yaml.schema.json`. The specification currently ships ten JSON schemas covering agent manifest, hooks, hook I/O, tools, skills, knowledge, memory, skillflows, configuration, and marketplace descriptors. Every `agent.yaml` in a GAP repository is validated against the manifest schema by `gapman validate`. +Appendix A excerpts `agent-yaml.schema.json`. The specification currently ships ten JSON schemas covering agent manifest, hooks, hook I/O, tools, skills, knowledge, memory, skillflows, configuration, and marketplace descriptors. Every `agent.yaml` in a GAP repository is validated against the manifest schema by `opengap validate`. > **Key insight.** In GAP, every file has a purpose, every purpose has a file, and the tuple $(I, R, D, S, T, K, Me, H, A, C)$ enumerates the complete surface of what an agent is. Compliance review becomes a finite, structural exercise rather than an open-ended code audit. @@ -273,8 +273,8 @@ Appendix A excerpts `agent-yaml.schema.json`. The specification currently ships A GAP agent can be consumed in two ways. -- **Export mode.** `gapman export --format ` renders the canonical definition into the target framework's native format as a directory or file. The output is deterministic — the same GAP directory yields the same output bytes — and is a reviewable artifact that the team may check into source control, attach to a PR, or hand to auditors. -- **Runtime mode.** `gapman run --adapter -p "prompt"` performs the equivalent export into a temporary workspace and launches the target runtime over it, either one-shot or interactively. +- **Export mode.** `opengap export --format ` renders the canonical definition into the target framework's native format as a directory or file. The output is deterministic — the same GAP directory yields the same output bytes — and is a reviewable artifact that the team may check into source control, attach to a PR, or hand to auditors. +- **Runtime mode.** `opengap run --adapter -p "prompt"` performs the equivalent export into a temporary workspace and launches the target runtime over it, either one-shot or interactively. Export produces an artifact; runtime produces a process. A team that wants reviewable outputs chooses export; a team that wants convenience chooses runtime. Either is GAP-compliant. @@ -364,7 +364,7 @@ The claim is that **structural guarantees are load-bearing for regulated deploym **P2 — Agent Versioning via Git Tags.** A runtime consumes `github.com/org/agent@v2.1.0`. The version is the deployment unit. Undo history is the commit graph. Rollback is not a database operation but a git operation. -**P4 — CI/CD for Agents.** `gapman validate --compliance` runs on every push via GitHub Actions. A failing manifest blocks merge. Agent quality is treated as code quality. Quarterly validation schedules can be enforced as CI gates. +**P4 — CI/CD for Agents.** `opengap validate --compliance` runs on every push via GitHub Actions. A failing manifest blocks merge. Agent quality is treated as code quality. Quarterly validation schedules can be enforced as CI gates. **P5 — Branch-Based Deployment.** `dev`, `staging`, `main` correspond to environments. Promotion is merge. Environment-specific configuration lives in `config/.yaml` and is selected at runtime. @@ -545,7 +545,7 @@ Let $w \in W$ be a trace that contains tool calls attributable to both $r_i$ and ## 9. Reference Implementation -The reference implementation is **`gapman`** (GAP manager), a TypeScript CLI published to npm as both `@open-gitagent/gapman` (scoped, provenance-signed) and `gapman` (unscoped alias). The repository is [github.com/open-gitagent/gitagent](https://github.com/open-gitagent/gitagent); the license is MIT. +The reference implementation is **`opengap`** (GAP manager), a TypeScript CLI published to npm as both `@open-gitagent/opengap` (scoped, provenance-signed) and `opengap` (unscoped alias). The repository is [github.com/open-gitagent/gitagent](https://github.com/open-gitagent/gitagent); the license is MIT. ### 9.1 Verb surface @@ -633,14 +633,14 @@ As of April 2026, the reference repository has: - **2,700+ GitHub stars** - **21 adapters**, five of which (Cursor, Kiro, Codex, Gemini, OpenCode) were contributed by pull request from *external authors* unaffiliated with the maintainer - **15+ closed issues** and active RFC discussions (financial governance, conformance testing, registry trust model) -- **Provenance-signed** releases on npm under both `@open-gitagent/gapman` and `gapman` +- **Provenance-signed** releases on npm under both `@open-gitagent/opengap` and `opengap` - **Cross-community pollination**: GAP agents appear in registries that predate it (the Lyzr registry) and in new registries that postdate it (GitClaw, the OpenClaw ecosystem) External adapter contributions are the strongest signal that the protocol is perceived as a **neutral substrate**, not a vendor product. No single contributor has standing to force a breaking change in favor of their framework. ### 11.2 Export fidelity (empirical) -The fidelity matrix (§5.4, Appendix B) is generated mechanically by running `gapman export --format ` over `examples/standard/` and `examples/full/` and diffing the output for the presence of each GAP element. Two headline findings: +The fidelity matrix (§5.4, Appendix B) is generated mechanically by running `opengap export --format ` over `examples/standard/` and `examples/full/` and diffing the output for the presence of each GAP element. Two headline findings: - **`claude-code` is the only adapter with full fidelity.** GAP and Claude Code were co-designed; the directory layout is nearly isomorphic. Other adapters vary. - **Hooks and sub-agents are the most frequently dropped elements.** `cursor`, `gemini`, `codex`, `openai`, and `system-prompt` all drop hooks entirely. Hook-based enforcement is a GAP-native guarantee that degrades gracefully per-target; teams requiring enforcement should choose a target that preserves hooks or should rely on GAP-native runtime modes. @@ -685,7 +685,7 @@ An open protocol with a dominant reference implementation is one bug report away ### 12.3 Why a protocol, not a framework -A framework solves problems for the framework's users. A protocol creates a substrate that multiple competing products can build on. OpenGAP chooses the protocol path. The reference implementation `gapman` is one of potentially many, and the specification has deliberate latitude so that vendors add value within their adapters without needing to modify the canonical definition. +A framework solves problems for the framework's users. A protocol creates a substrate that multiple competing products can build on. OpenGAP chooses the protocol path. The reference implementation `opengap` is one of potentially many, and the specification has deliberate latitude so that vendors add value within their adapters without needing to modify the canonical definition. ### 12.4 Why git, not a new system @@ -741,7 +741,7 @@ The OpenGAP working group thanks contributors to the reference implementation an 15. **P. Priyam.** *GitClose: A git-native reference implementation of the monthly financial close using OpenGAP.* 2026. 16. **OpenGAP Working Group.** *RFC #38 — `compliance.financial_governance` block.* 2026. 17. **OpenGAP Working Group.** *OpenGAP Specification v0.1.0.* 2026. -18. **OpenGAP Working Group.** *gapman on npm.* 2026. +18. **OpenGAP Working Group.** *opengap on npm.* 2026. 19. **L. Lamport.** *Specifying Systems: The TLA+ Language and Tools for Hardware and Software Engineers.* Addison-Wesley, 2002. 20. **D. Jackson.** *Software Abstractions: Logic, Language, and Analysis (Alloy).* MIT Press, 2012. 21. **Commission of the European Union.** *Regulation (EU) 2024/1689 (Artificial Intelligence Act).* 2024. @@ -816,7 +816,7 @@ The OpenGAP working group thanks contributors to the reference implementation an **Legend:** **F** = fully preserved · **P** = partially preserved (text present, semantics dropped) · **⊥** = not representable in the target format. Columns correspond to $I$=identity, $R$=rules, $D$=duties, $S$=skills, $T$=tools, $H$=hooks, $Me$=memory, $A$=sub-agents, $C$=compliance. -The CSV source is [`tables/fidelity-matrix.csv`](tables/fidelity-matrix.csv), regenerated by running `gapman export` against `examples/standard/` and `examples/full/` for each adapter. +The CSV source is [`tables/fidelity-matrix.csv`](tables/fidelity-matrix.csv), regenerated by running `opengap export` against `examples/standard/` and `examples/full/` for each adapter. --- @@ -857,7 +857,7 @@ A CLI or library is **GAP-conformant at level $k$** iff: - **Level 2 (export):** for at least one target $t$, it produces an output artifact whose fidelity profile matches the specification's published profile for $t$. - **Level 3 (run):** for at least one target $t$, it launches the target runtime in a way that honors $(R, D, H)$ when those elements are present. -The reference implementation `gapman` is Level 3-conformant on Claude Code, OpenCode, Gemini, CrewAI, OpenAI, Lyzr, OpenClaw, Nanobot, GitHub, and GitClaw. +The reference implementation `opengap` is Level 3-conformant on Claude Code, OpenCode, Gemini, CrewAI, OpenAI, Lyzr, OpenClaw, Nanobot, GitHub, and GitClaw. --- diff --git a/spec/SPECIFICATION.md b/spec/SPECIFICATION.md index 021e0c4..d3f8021 100644 --- a/spec/SPECIFICATION.md +++ b/spec/SPECIFICATION.md @@ -459,7 +459,7 @@ Provides fallback instructions compatible with Cursor, Copilot, and other tools ## 7. Skills — Agent Skills Open Standard -gitagent fully adopts the **Agent Skills** open standard ([agentskills.io](https://agentskills.io)) for its `skills/` directory. Any valid Agent Skills skill works in gitagent with zero modification, and gapman skills work in Claude Code, Codex, VS Code, Cursor, Gemini CLI, and all other tools that support the standard. +gitagent fully adopts the **Agent Skills** open standard ([agentskills.io](https://agentskills.io)) for its `skills/` directory. Any valid Agent Skills skill works in gitagent with zero modification, and opengap skills work in Claude Code, Codex, VS Code, Cursor, Gemini CLI, and all other tools that support the standard. ### SKILL.md Format (Agent Skills Standard) @@ -560,10 +560,10 @@ Built-in providers: | Command | Description | |---------|-------------| -| `gapman skills search ` | Search for skills in a registry | -| `gapman skills install ` | Install a skill from a registry | -| `gapman skills list` | List discovered skills | -| `gapman skills info ` | Show detailed skill information | +| `opengap skills search ` | Search for skills in a registry | +| `opengap skills install ` | Install a skill from a registry | +| `opengap skills list` | List discovered skills | +| `opengap skills info ` | Show detailed skill information | Options: `--provider `, `--global` (install to `~/.agents/skills/`), `--dir ` @@ -971,28 +971,28 @@ A valid gitagent repository must: | Command | Description | |---------|-------------| -| `gapman init [--template]` | Scaffold new agent (`minimal`, `standard`, `full`) | -| `gapman validate [--compliance]` | Validate against spec, optionally with regulatory checks | -| `gapman info` | Display agent summary | -| `gapman export --format ` | Export (`system-prompt`, `claude-code`, `openai`, `crewai`) | -| `gapman import --from ` | Import (`claude`, `cursor`, `crewai`) | -| `gapman install` | Resolve and install git-based dependencies | -| `gapman audit` | Generate compliance audit report | -| `gapman skills search ` | Search for skills in a registry | -| `gapman skills install ` | Install a skill from a registry | -| `gapman skills list` | List discovered skills | -| `gapman skills info ` | Show detailed skill information | +| `opengap init [--template]` | Scaffold new agent (`minimal`, `standard`, `full`) | +| `opengap validate [--compliance]` | Validate against spec, optionally with regulatory checks | +| `opengap info` | Display agent summary | +| `opengap export --format ` | Export (`system-prompt`, `claude-code`, `openai`, `crewai`) | +| `opengap import --from ` | Import (`claude`, `cursor`, `crewai`) | +| `opengap install` | Resolve and install git-based dependencies | +| `opengap audit` | Generate compliance audit report | +| `opengap skills search ` | Search for skills in a registry | +| `opengap skills install ` | Install a skill from a registry | +| `opengap skills list` | List discovered skills | +| `opengap skills info ` | Show detailed skill information | ### Planned (future versions) | Command | Description | |---------|-------------| -| `gapman run [--env] [--model]` | Start agent interactively | +| `opengap run [--env] [--model]` | Start agent interactively | | `gitagent serve --protocol ` | Run as A2A/MCP server | -| `gapman test` | Run against example scenarios | +| `opengap test` | Run against example scenarios | | `gitagent publish` | Publish to registry | | `gitagent card` | Generate A2A Agent Card | -| `gapman diff ` | Semantic diff between versions | +| `opengap diff ` | Semantic diff between versions | ## 19a. JSON Schemas diff --git a/src/commands/registry.ts b/src/commands/registry.ts index 6dc6006..7d6da48 100644 --- a/src/commands/registry.ts +++ b/src/commands/registry.ts @@ -235,7 +235,7 @@ ${manifest.description} ## Run \`\`\`bash -npx @open-gitagent/gapman run -r ${repoUrl} +npx @open-gitagent/opengap run -r ${repoUrl} \`\`\` ## Skills diff --git a/src/index.ts b/src/index.ts index 8783c4f..1fe7952 100644 --- a/src/index.ts +++ b/src/index.ts @@ -16,9 +16,9 @@ import { registryCommand } from './commands/registry.js'; const program = new Command(); program - .name('gapman') - .description('GitAgentProtocol (GAP) Manager — framework-agnostic, git-native standard for defining AI agents') - .version('0.3.2'); + .name('opengap') + .description('OpenGAP — the Git Agent Protocol: a framework-agnostic, git-native standard for defining AI agents') + .version('0.4.0'); program.addCommand(initCommand); program.addCommand(validateCommand);