Plans Dir Exists + AI Use Collector

✓ Guardrail ↓ Collector Experimental Devex Build And Ci

Enforce Plans Dir Exists using data collected by AI Use Collector. Automatically check devex build and ci standards on every PR.

Guardrail: Verifies that a dedicated plans directory exists for AI agent task planning. A dedicated directory keeps AI-generated plans organized and reviewable.

Data Source: Track AI coding assistant usage across your organization. Collect agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md), plans directories, CI tool invocations, and AI authorship annotations from commits.

Get Started View on GitHub

How AI Use Collector Powers This Guardrail

The AI Use Collector gathers metadata from your code analysis, ci cd systems. This data flows into Lunar's Component JSON, where the Plans Dir Exists guardrail evaluates it against your standards.

When enabled, this check runs automatically on every PR and in AI coding workflows, providing real-time enforcement with actionable feedback.

↓ AI Use Collector Gathers Data Collector

Extracts metadata from code, configs, and tool outputs

{ } Component JSON

Data centralized in structured format for evaluation

✓ Plans Dir Exists Checks Guardrail

Pass/fail result with actionable feedback in PRs

Quick Start Configuration

Add both the collector and policy to your lunar-config.yml to enable this guardrail.

📄 lunar-config.yml

# Step 1: Enable the AI Use Collector
collectors:
  - uses: github://earthly/lunar-lib/collectors/ai-use@v1.0.0
    # with: ...

# Step 2: Enable the AI Use Guardrails
policies:
  - uses: github://earthly/lunar-lib/policies/ai-use@v1.0.0
    include: [plans-dir-exists]
    # with: ...

What AI Use Collector Collects

This collector gathers the following data that the Plans Dir Exists guardrail evaluates.

Collector code

`instruction-files`

Discovers all agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, CODEX.md) across the repository using a configurable find command. Records each file's path, line count, byte size, markdown section headings, and symlink status. Groups files by directory for per-directory policy checks.

Collector code

`plans-dir`

Checks whether a dedicated plans directory exists for AI agent task planning. Tries candidate paths in order (first match wins). Records the directory path and file count.

Collector ci-after-command

`ai-cli-ci-claude`

Detects Claude Code CLI invocations in CI pipelines. Records the command string and version for policy-level flag analysis.

Collector ci-after-command

`ai-cli-ci-codex`

Detects OpenAI Codex CLI invocations in CI pipelines. Records the command string and version for policy-level flag analysis.

View all 6 collectors in AI Use Collector →

Example Data Flow

Here's an example of the data that AI Use Collector writes to the Component JSON, which Plans Dir Exists then evaluates.

{ } component.json From AI Use Collector

{
  "ai_use": {
    "instructions": {
      "root": {
        "exists": true,
        "filename": "AGENTS.md",
        "lines": 85,
        "bytes": 3200,
        "sections": ["Project Overview", "Architecture", "Build Commands", "Testing"]
      },
      "all": [
        {
          "path": "AGENTS.md",
          "dir": ".",
          "filename": "AGENTS.md",
          "lines": 85,
          "bytes": 3200,
          "sections": ["Project Overview", "Architecture", "Build Commands", "Testing"],
          "is_symlink": false,
          "symlink_target": null
        },
        {
          "path": "CLAUDE.md",
          "dir": ".",
          "filename": "CLAUDE.md",
          "lines": 85,
          "bytes": 3200,
          "sections": ["Project Overview", "Architecture", "Build Commands", "Testing"],
          "is_symlink": true,
          "symlink_target": "AGENTS.md"
        }
      ],
      "count": 2,
      "total_bytes": 3200,
      "directories": [
        {
          "dir": ".",
          "files": [
            { "filename": "AGENTS.md", "is_symlink": false },
            { "filename": "CLAUDE.md", "is_symlink": true, "symlink_target": "AGENTS.md" }
          ]
        }
      ],
      "source": { "tool": "find", "integration": "code" }
    },
    "plans_dir": {
      "exists": true,
      "path": ".agents/plans",
      "file_count": 3
    },
    "cicd": {
      "cmds": [
        {
          "cmd": "claude -p --output-format json --allowedTools Bash(git*) Read 'review this PR'",
          "tool": "claude",
          "version": "1.0.20",
          "allowed_tools": "Bash(git*) Read"
        }
      ]
    },
    "authorship": {
      "provider": "git-ai",
      "total_commits": 12,
      "annotated_commits": 8,
      "git_ai": {
        "notes_ref_exists": true,
        "commits_with_notes": 8
      }
    }
  }
}

Configuration Options

AI Use Collector Inputs

Input	Required	Default	Description
`md_find_command`	Optional	`find . \( -type f -o -type l \) \( -name AGENTS.md -o -name CLAUDE.md -o -name GEMINI.md -o -name CODEX.md \) -not -path '/node_modules/' -not -path '/.git/'`	Command to find agent instruction files (must output one file path per line)
`plans_dir_paths`	Optional	`.agents/plans,.ai/plans`	Comma-separated list of candidate paths for the plans directory (first match wins)
`annotation_prefix`	Optional	`AI-`	Prefix for git trailer-based AI annotations
`default_branch_window`	Optional	`50`	Number of recent commits to scan on the default branch

AI Use Guardrails Inputs

Input	Required	Default	Description
`canonical_filename`	Optional	`AGENTS.md`	The canonical (vendor-neutral) instruction filename
`required_symlinks`	Optional	`CLAUDE.md`	Comma-separated list of symlinks required alongside the canonical file
`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)
`dangerous_flags_claude`	Optional	`--dangerously-skip-permissions,--allow-dangerously-skip-permissions`	Comma-separated dangerous flags for Claude CLI
`dangerous_flags_codex`	Optional	`--dangerously-bypass-approvals-and-sandbox,--yolo,--full-auto`	Comma-separated dangerous flags for Codex CLI
`dangerous_flags_gemini`	Optional	`--yolo,-y`	Comma-separated dangerous flags for Gemini CLI
`min_annotation_percentage`	Optional	`0`	Minimum percentage of commits that should have AI annotations (0 = awareness mode)

Learn More

Guardrail · AI Use Guardrails Plans Dir Exists View all compatible integrations

→

Collector AI Use Collector View full documentation

→

Ready to Automate Your Standards?

See how Lunar can turn your engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 100+ built-in guardrails.

Works with any process

Infrastructure conventions

Post-mortem action items

Security & compliance policies

Testing & quality requirements

Automate Now

Turn any process doc into guardrails

Book a Demo