agent-policy

Schema-first generator for coding-agent repo policies and compatibility files.

Generates AGENTS.md, CLAUDE.md, .cursor/rules/, and .windsurf/rules/ (among others) from a single agent-policy.yaml.

What it does

Maintaining AGENTS.md, CLAUDE.md, and Cursor rules separately means the same policy information gets duplicated across files that diverge over time. agent-policy solves this by letting you define your repo's coding-agent policy once in a canonical agent-policy.yaml, then generating all the tool-specific compatibility files from that single source of truth.

Keep one policy file. Generate all agent instruction files from it. Detect drift in CI.

Install

From crates.io

cargo install agent-policy

Binary releases

Download pre-built binaries from GitHub Releases.

Quick start

# Create a starter policy
agent-policy init

# Edit agent-policy.yaml, then generate
agent-policy generate

# Add to CI to prevent drift
agent-policy check

Commands

Command	Description
`agent-policy init`	Write a starter `agent-policy.yaml` in the current directory
`agent-policy list-targets`	View a table of all available export formats and their stability
`agent-policy generate`	Generate all enabled output files from `agent-policy.yaml`
`agent-policy check`	Verify committed files match the current policy (CI use)

Both generate and check accept --config / -c to specify a non-default config path, and --targets to natively override outputs:

agent-policy generate --config infra/agent-policy.yaml
agent-policy check --targets agents-md,clinerules

agent-policy.yaml

Minimal example:

project:
  name: my-project
  summary: A short description.
outputs:
  - agents-md

Note: You do not need to manually add .md outputs or target paths to your paths.generated config list. Any active outputs are injected into your generated list automatically!

Full example — see examples/website/agent-policy.yaml.

The file is validated against agent-policy.schema.json (JSON Schema Draft 2020-12). The schema is bundled with the binary and is versioned alongside it. It is considered unstable until v1.0.0.

Generated outputs

Target ID	File	Enabled by default	Tool(s)
`agents-md`	`AGENTS.md`	Yes	Codex, Windsurf, Copilot
`claude-md`	`CLAUDE.md`	No	Claude Code, Copilot
`cursor-rules`	`.cursor/rules/*.mdc`	No	Cursor
`gemini-md`	`GEMINI.md`	No	Google Gemini CLI
`windsurf-rules`	`.windsurf/rules/*.md`	No	Codeium Windsurf
`clinerules`	`.clinerules/*.md`	No	Cline
`copilot-instructions`	`.github/copilot-instructions.md`	No	Copilot (Global)
`copilot-instructions-scoped`	`.github/instructions/*.md`	No	Copilot (Scoped Context)
`junie-guidelines`	`.junie/guidelines.md`	No	JetBrains Junie

When outputting directory rules like cursor-rules or clinerules, agent-policy generates one default layout and optionally one file per customized role, intelligently assigning frontmatter globs and path references directly into the generated configurations to cleanly silo AI behaviors scope-to-scope!

CI integration

Add to your CI workflow to enforce that generated files are never edited by hand:

- name: Check agent policy
  run: agent-policy check

This step exits non-zero if any generated file is stale or missing, and prints a unified diff to stderr.

Non-goals

Not a replacement for AGENTS.md — it generates AGENTS.md
Not a full enforcement engine or policy-as-code runtime
Not a SaaS platform or hosted service
Not a daemon or background process

License

Apache-2.0

agent-policy 0.3.0