AI Use Guardrails

Enforces AI coding assistant usage standards including instruction files, naming conventions, CI safety, and authorship tracking.

Overview

This policy plugin validates how AI coding assistants are used across your organization. It ensures repositories have properly structured instruction files, follow naming conventions, avoid dangerous CI flags, use structured output in automation, and track AI authorship in commits. These guardrails help teams adopt AI tools safely and consistently at scale.

Policies

This plugin provides the following policies (use include to select a subset):

Required Data

This policy reads from the following Component JSON paths:

Note: Ensure the corresponding collector is configured before enabling this policy.

Installation

Add to your lunar-config.yml:

policies:
  - uses: github://earthly/lunar-lib/policies/ai-use@v1.0.0
    on: ["domain:your-domain"]
    enforcement: report-pr
    # include: [instruction-file-exists, canonical-naming]  # Only run specific checks
    # with:
    #   canonical_filename: "AGENTS.md"
    #   required_symlinks: "CLAUDE.md"
    #   min_lines: "10"            # 0 to disable
    #   max_lines: "300"           # 0 to disable
    #   max_total_bytes: "32768"   # 0 to disable
    #   required_sections: "Project Overview,Build Commands"

Examples

Passing Example

A repository with a properly configured AGENTS.md, CLAUDE.md symlink, and plans directory:

{
  "ai_use": {
    "instructions": {
      "root": {
        "exists": true,
        "filename": "AGENTS.md",
        "lines": 85,
        "sections": ["Project Overview", "Architecture", "Build Commands"]
      },
      "count": 3,
      "total_bytes": 4200,
      "directories": [
        {
          "dir": ".",
          "files": [
            { "filename": "AGENTS.md", "is_symlink": false },
            { "filename": "CLAUDE.md", "is_symlink": true, "symlink_target": "AGENTS.md" }
          ]
        }
      ]
    },
    "plans_dir": { "exists": true, "path": ".agents/plans", "file_count": 2 },
    "cicd": {
      "cmds": [
        { "cmd": "claude -p --output-format json 'review this'", "tool": "claude", "version": "1.0.20" }
      ]
    },
    "authorship": { "total_commits": 10, "annotated_commits": 8 }
  }
}

Failing Examples

No instruction file at root (fails instruction-file-exists)

{
  "ai_use": {
    "instructions": {
      "root": { "exists": false },
      "count": 0,
      "total_bytes": 0
    }
  }
}

Failure message: "No agent instruction file found at repository root (e.g. AGENTS.md, CLAUDE.md, GEMINI.md)"

Only CLAUDE.md at root, no AGENTS.md (fails canonical-naming)

{
  "ai_use": {
    "instructions": {
      "root": { "exists": true, "filename": "CLAUDE.md", "lines": 50 }
    }
  }
}

Failure message: "Root instruction file is CLAUDE.md — rename to AGENTS.md and create CLAUDE.md as a symlink (Claude Code requires the symlink)"

Dangerous CI flags detected (fails ai-cli-safe-flags)

{
  "ai_use": {
    "cicd": {
      "cmds": [
        {
          "cmd": "claude --dangerously-skip-permissions -p 'deploy to prod'",
          "tool": "claude",
          "version": "1.0.20"
        }
      ]
    }
  }
}

Failure message: "claude CI invocation uses dangerous flag: --dangerously-skip-permissions"

Remediation

instruction-file-exists

Create an AGENTS.md file at the repository root with project context for AI coding assistants. Include sections covering project overview, build commands, and testing instructions.

canonical-naming

Rename your instruction file to AGENTS.md (the vendor-neutral canonical name) and create symlinks for tool-specific names:

mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

instruction-file-length

If too short: add meaningful content — project overview, architecture notes, build commands, testing patterns, and common gotchas. If too long: use progressive disclosure — keep the root file focused and create subdirectory AGENTS.md files for module-specific details. Codex hard-caps at 32KB combined. Set any threshold to "0" to disable that specific check.

instruction-file-sections

Add the missing required sections as markdown headings. Default required sections are ## Project Overview and ## Build Commands. Customize via the required_sections input.

symlinked-aliases

Create CLAUDE.md as a symlink to AGENTS.md in each directory that has an instruction file:

ln -s AGENTS.md CLAUDE.md

plans-dir-exists

Create a dedicated plans directory for AI agent task planning:

mkdir -p .agents/plans

ai-cli-safe-flags

Remove dangerous permission-bypassing flags from AI CLI invocations in CI. Use scoped permissions instead: Claude's allowedTools, Codex's execpolicy rules, or Gemini's sandbox profiles.

ai-cli-structured-output

Add structured output flags to headless AI CLI invocations in CI: --output-format json for Claude/Gemini, --json for Codex.

ai-authorship-annotated

Install Git AI for automated line-level AI authorship tracking, or add git trailers manually to commits: AI-model: claude-4, AI-tool: cursor.