Storing Specs in Git

An .envelope.json file is infrastructure-as-code. It describes exactly what your AI agents do — version it, diff it, review it in PRs, and deploy from it the same way you would a Terraform config or a Kubernetes manifest.

Why it belongs in Git

Auditability — every change to the agent design is tracked, attributed, and reversible
Review process — agent spec changes go through the same PR workflow as everything else
CI validation — catch spec errors before they reach production
Reproducibility — any version of the agent spec can be reconstructed from history

Where to put it

Keep specs alongside the code that runs them. If the agents are part of a service, put it in that repo:

your-repo/
├── src/
├── infra/
│   └── envelope/
│       ├── support-triage.envelope.json
│       └── newsletter-digest.envelope.json
└── .github/
    └── workflows/
        └── validate-specs.yml

If teams are managed centrally, a dedicated repo works too:

ai-teams/
├── support/
│   └── triage.envelope.json
├── marketing/
│   └── newsletter.envelope.json
└── README.md

.gitignore

The spec file is safe to commit — it contains no secrets. requiredSecrets lists secret names, not values. Credentials live in your vault or secrets manager, never in the file.

No .gitignore entries needed for .envelope.json files.

Validating in CI

Add a validation step to your GitHub Actions workflow to catch broken specs before merge:

name: Validate Envelope specs

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Validate specs
        run: npx @openenvelope/schema validate ./infra/envelope/*.envelope.json

The validator exits non-zero on any schema violation, blocking the merge.

Diffing changes

Because the file is structured JSON, changes are readable in a standard diff:

  "agents": [
    {
      "key": "triage-agent",
-     "role": "Classifies inbound tickets by priority.",
+     "role": "Classifies inbound tickets by priority and estimated resolution time.",
      "capabilities": ["zendesk"]
    }
  ]

For large teams, tools like jq help isolate the relevant section:

# Show just the agent keys and roles
jq '.agents[] | {key, role}' support-triage.envelope.json

Deploying from a tag

Pin production installs to a specific git tag:

git tag v1.0.0
git push origin v1.0.0

When updating an agent spec, bump the tag and update the install — the same pattern as any other versioned artifact.