AI Guardrails
Enforce cross-tool AI standards: code review bots, instruction files, naming conventions, plans directories, and authorship annotations.
ai to your lunar-config.yml:uses: github://earthly/lunar-lib/policies/ai@v1.0.5
Included Guardrails
This policy includes 7 guardrails that enforce standards for your devex build and ci.
code-reviewer
Verifies that at least one AI code reviewer is active on the component. Checks ai.code_reviewers[] for any entry with detected: true. Tool-agnostic — doesn't care which reviewer is active, just that something is reviewing code. Skips if no code reviewer data exists (no tool-specific collectors configured).
instruction-file-exists
Verifies that an agent instruction file exists at the repository root. Checks ai.instructions.all[] which is populated by the ai collector (AGENTS.md) and tool-specific collectors via array append (CLAUDE.md, CODEX.md, GEMINI.md). Passes if any entry exists.
canonical-naming
Verifies the root instruction file uses the canonical vendor-neutral name (AGENTS.md by default). Repos with only CLAUDE.md pass the existence check but fail this naming check.
instruction-file-length
Validates that the root instruction file is within reasonable length bounds. Too short means insufficient context; too long wastes context window budget and can reduce AI task success rates.
instruction-file-sections
Ensures the root instruction file contains required section headings. Validates that essential information like project overview and build commands is documented for AI agents.
plans-dir-exists
Verifies that a dedicated plans directory exists for AI agent task planning. A dedicated directory keeps AI-generated plans organized and reviewable.
ai-authorship-annotated
Verifies that commits include AI authorship annotations. Supports the Git AI standard (usegitai.com) for automated line-level tracking and git trailers as a lightweight manual alternative.
How Guardrails Fit into Lunar
Lunar guardrails define your engineering standards as code. They evaluate data collected by integrations and produce pass/fail checks with actionable feedback.
Policies support gradual enforcement—from silent scoring to blocking PRs or deployments—letting you roll out standards at your own pace without disrupting existing workflows.
Learn How Lunar Works →Example Evaluated Data
This policy evaluates structured metadata from the Component JSON. Here's an example of the data it checks:
{
"ai": {
"code_reviewers": [
{
"tool": "coderabbit",
"check_name": "coderabbitai",
"detected": true,
"last_seen": "2024-01-15T10:30:00Z"
}
],
"instructions": {
"root": {
"exists": true,
"filename": "AGENTS.md",
"lines": 85,
"bytes": 3200,
"sections": ["Project Overview", "Architecture", "Build Commands", "Testing"]
},
"all": [],
"count": 2,
"total_bytes": 3200
},
"plans_dir": {
"exists": true,
"path": ".agents/plans",
"file_count": 3
},
"authorship": {
"provider": "git-ai",
"total_commits": 12,
"annotated_commits": 8
}
}
}Required Integrations
This policy evaluates data gathered by one or more of the following integration(s).
Make sure to enable them in your lunar-config.yml.
Provides instruction files, plans dirs, and authorship data
Provides Claude code review detection data for code-reviewer policy check
Provides CodeRabbit code review detection data
Configuration
Configure this policy in your lunar-config.yml.
Inputs
| Input | Required | Default | Description |
|---|---|---|---|
canonical_filename
|
Optional |
AGENTS.md
|
The canonical (vendor-neutral) instruction filename |
min_lines
|
Optional |
10
|
Minimum number of lines for the root instruction file (0 to disable) |
max_lines
|
Optional |
300
|
Maximum number of lines for the root instruction file (0 to disable) |
max_total_bytes
|
Optional |
32768
|
Maximum combined bytes across all instruction files (0 to disable) |
required_sections
|
Optional |
Project Overview,Build Commands
|
Comma-separated required section heading substrings (case-insensitive) |
min_annotation_percentage
|
Optional |
0
|
Minimum percentage of commits that should have AI annotations (0 = awareness mode) |
Documentation
View on GitHubAI Guardrails
Enforce AI coding assistant standards across your organization.
Overview
This policy enforces cross-tool AI standards using data from the ai.* namespace. It covers code review bot presence, instruction file quality, plans directories, and AI authorship annotations.
Policies
| Policy | Severity | Description |
|---|---|---|
code-reviewer |
error | At least one AI code reviewer must be active (ai.code_reviewers[]) |
instruction-file-exists |
error | An agent instruction file must exist at the repo root |
canonical-naming |
warning | Root instruction file should use the vendor-neutral name (AGENTS.md) |
instruction-file-length |
warning | Root instruction file must be within configured length bounds |
instruction-file-sections |
warning | Root instruction file must contain required section headings |
plans-dir-exists |
warning | A dedicated AI plans directory should exist |
ai-authorship-annotated |
warning | Commits should include AI authorship annotations |
Required Data
| Path | Provided By | Description |
|---|---|---|
.ai.code_reviewers[] |
coderabbit, claude collectors |
Normalized array of detected code review tools |
.ai.instructions |
ai, claude, codex, gemini collectors |
Instruction file metadata — ai writes root/AGENTS.md, tool collectors append to all[] via array append |
.ai.plans_dir |
ai collector |
Plans directory existence and file count |
.ai.authorship |
ai collector |
AI authorship annotation coverage |
Installation
# Enable tool-specific collectors for code review detection:
collectors:
- uses: github://earthly/lunar-lib/collectors/ai@main
on: ["domain:your-domain"]
- uses: github://earthly/lunar-lib/collectors/coderabbit@main
on: ["domain:your-domain"]
secrets:
GH_TOKEN: "${{ secrets.GH_TOKEN }}"
- uses: github://earthly/lunar-lib/collectors/claude@main
on: ["domain:your-domain"]
secrets:
GH_TOKEN: "${{ secrets.GH_TOKEN }}"
# Enable the policy:
policies:
- uses: github://earthly/lunar-lib/policies/ai@main
enforcement: report-pr
Examples
Passing
Component has an active code reviewer and proper instruction files:
{
"ai": {
"code_reviewers": [
{ "tool": "coderabbit", "check_name": "coderabbitai", "detected": true }
],
"instructions": {
"root": { "exists": true, "filename": "AGENTS.md", "lines": 85 }
}
}
}
Failing
No code reviewer detected, no instruction file:
{
"ai": {
"code_reviewers": [],
"instructions": { "root": { "exists": false } }
}
}
Remediation
- code-reviewer: Enable a code review bot (CodeRabbit, Claude) and configure its collector
- instruction-file-exists: Create an AGENTS.md file at the repo root
- canonical-naming: Rename to AGENTS.md (vendor-neutral) or symlink it
- plans-dir-exists: Create a
.agents/plansdirectory for AI agent task planning - ai-authorship-annotated: Enable git-ai or add AI-model trailers to commits
Open Source
This policy is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.
Common Use Cases
Explore how individual guardrails work with specific integrations.
Ready to Automate Your Standards?
See how Lunar can turn your AGENTS.md, engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 100+ built-in guardrails.
AI agent rules & prompt files
Post-mortem action items
Security & compliance policies
Testing & quality requirements