Agent Instructions: GOPAL

August 30, 2026 · View on GitHub

This file is the canonical operational guide for AI coding agents working in this repository (Claude Code, Cursor, Codex, Windsurf, Gemini CLI, Copilot, etc.). Tool-specific files (CLAUDE.md, GEMINI.md) inherit from this and add only platform-specific notes.

What this project is

GOPAL (Governance Open Policy Agent Library) is a curated set of OPA Rego policies encoding real-world AI-governance requirements: the EU AI Act, NIST AI RMF, aviation safety standards, FERPA/COPPA in education, fair-lending rules, and more.

It is consumable two ways:

  1. Standalone via the OPA CLI / Go SDK / any OPA-compatible runtime
  2. As the policy engine for AICertify, which provides a Python framework, report generators, and an end-to-end compliance flow

Repository layout

gopal/
├── global/v1/                Cross-cutting categories (fairness, transparency, …)
├── international/            Per-jurisdiction frameworks
│   ├── eu_ai_act/v1/         29 policies — EU AI Act 2024/1689
│   ├── nist/v1/              NIST AI RMF + AI 600-1
│   ├── india/v1/             India Digital Policy
│   ├── brazil/v1/            Brazil AI Governance Bill
│   ├── icao/, faa/, easa/    Aviation regulators
│   └── standards/v1/         RTCA DO-365, ISO 21384
├── industry_specific/
│   ├── education/v1/         12 policies — FERPA, COPPA, proctoring, grading
│   ├── aviation/v1/          12 policies — airworthiness, autonomy, data, ops
│   ├── healthcare/v1/        Patient & diagnostic safety
│   ├── bfs/v1/               Model risk, fair lending
│   └── automotive/v1/        Vehicle safety integration
├── operational/              AIOps, cost, corporate
├── helper_functions/         Shared utilities (reporting.rego, validation.rego)
├── custom/                   Local-only org policies, git-ignored and CI-skipped
├── pyproject.toml            Distribution as a Python package (Rego files included)
├── .regal/config.yaml        Regal linter configuration
└── .github/workflows/        OPA + Regal CI

92 production policies. 198 Rego files including tests.

Useful commands

# Run the same checks CI runs
opa check --ignore custom/ --ignore dist .
regal lint --ignore-files custom/ .

# Pre-commit (auto-runs on commit if installed)
pre-commit install
pre-commit run --all-files

# Evaluate a policy against an input
opa eval -d international/eu_ai_act/v1 \
  --input your_input.json \
  "data.international.eu_ai_act.v1.transparency.allow"

# Run tests for a single policy
opa test -v international/eu_ai_act/v1/transparency.rego \
        international/eu_ai_act/v1/transparency_test.rego

Authoring a new policy

This is the most common task. Strict conventions:

1. Directory structure

{domain}/{framework}/v{N}/{policy_name}.rego
{domain}/{framework}/v{N}/{policy_name}_test.rego

Where {domain} is one of global, international, industry_specific, operational.

2. Mandatory file contents

package international.eu_ai_act.v1.transparency  # MUST match directory path

import data.helper_functions.reporting

# METADATA
# title: Transparency obligations for GPAI providers
# description: Article 53: technical documentation must be published.
# version: 1
# source: https://eur-lex.europa.eu/eli/reg/2024/1689/oj

default allow := false

allow if {
    input.system.technical_documentation_published == true
}

report := reporting.compose_report(
    "eu_ai_act.transparency",
    allow,
    [{"name": "documentation_present", "value": allow, "control_passed": allow}],
)

3. Tests are required

Every policy.rego ships with policy_test.rego covering both the allow and deny paths.

4. Framework-level README

At each international/<framework>/v1/ and industry_specific/<industry>/v1/, include a README.md with:

  • Source: link to the official regulation/standard
  • Disclaimer: "These policies are not legal advice; they encode the authors' reading of the source text in Rego."

5. Helpers

Use helper_functions/reporting.rego for output composition and helper_functions/validation.rego for input checks. Don't roll your own.

CI quality gate

Both must pass:

opa check --ignore custom/ --ignore dist .
regal lint --ignore-files custom/ .

If Regal flags an issue, look it up in the Regal rule catalog: don't disable rules without a documented reason.

Conventions

  • One concept per file: don't bundle unrelated checks. A policy file should answer one regulatory question.
  • Boolean output: every policy exposes allow (or equivalent) and a report composed via helper_functions.reporting.
  • No external HTTP/file I/O: policies must be pure functions of input and data. They evaluate offline.
  • Stable package paths: the package path is the public API. Don't rename without bumping a major version.

Versioning

Each framework lives under v1/. When the upstream regulation changes materially, add v2/ alongside rather than mutate v1/ in place. See COMPATIBILITY.md.

Diagrams and visual assets

All README diagrams live in diagrams/ as paired light and dark SVGs, embedded via <picture> for GitHub theme switching. The full design system (palette, type, shape language, naming, contribution flow) is documented in diagrams/STYLE.md. Read it before adding or modifying any diagram.

  • Edit existing diagrams in place: they are hand-authored SVGs, not generated. Open the file, change it, validate with python3 -c "import xml.etree.ElementTree as ET; ET.parse('<path>')".
  • Do not reintroduce a matplotlib generator: the previous generate_diagrams.py was deliberately removed. Hand-authored SVGs are the source of truth.
  • New diagrams must ship both _light.svg and _dark.svg variants. Use <picture> markup; verify GitHub theme switching by viewing the rendered README on both light and dark settings.
  • Rego syntax-coloured text in diagram3_policy_anatomy uses <tspan> with xml:space="preserve" on the parent. Without that attribute Inkscape and some browsers normalise whitespace, and keywords run into the next token.

What NOT to do

  • Don't edit policies under custom/: that's a local-only space for downstream consumers.
  • Don't add a policy without tests. CI will pass but Regal lint reviews will catch you.
  • Don't introduce dependencies on Styra-only Regal features that aren't in mainline OPA.
  • Don't claim a regulation is "fully covered" unless every named article/section has a corresponding policy. Partial coverage is fine, just be explicit.

Sister project

AICertify consumes GOPAL. When you add a framework here, AICertify users get it for free on next vendor sync.

Conservatism

The author prefers surgical changes: do only what was asked, present the plan first when there's any ambiguity, and ask before introducing new abstractions. Critique your own design once for elegance, DRY, KISS, and explainability before presenting it.