VibeTags — AI Guardrails for Java Development

VibeTags is a compile-time Java annotation processor that generates AI platform-specific guardrail files from source annotations — zero runtime overhead, all from a single mvn compile.

At a glance: 44 annotations → guardrails for 29 AI platforms, written as 46 config files and 16 scoped-rule directories. These numbers are the single source of truth for the project's scope; other docs link back here rather than restating them. A platform is a tool, not a file — Cursor is one platform with both .cursorrules and .cursorignore. (All four counts verified by ProjectFactsConsistencyTest.)

Why VibeTags?

.cursorrules, CLAUDE.md, and similar files are hand-edited by each developer, grow inconsistent across the team, and go stale the moment the code changes. VibeTags makes your AI configuration source-controlled and compile-enforced:

• Annotate once, all platforms updated — add @AILocked to PaymentProcessor and every AI tool's guardrail file is regenerated on the next compile. No more per-developer copy-pasting across every generated config file.
• Derived from the code, not separate from it — guardrails live next to the code they protect. When the code moves, the rules move with it.
• Granular rules keep the always-loaded context slim — opt a platform's scoped-rules directory in (.claude/rules/, .cursor/rules/, .windsurf/rules/, .github/instructions/, .gemini/rules/) and its aggregate file collapses to an index: only the safety buckets (@AILocked, @AICore, @AIPrivacy, @AIIgnore, @AIAudit, @AISecure) stay inline, and the per-element detail loads on demand when the matching source file is opened (Gemini CLI does not read .gemini/rules/ itself, so GEMINI.md's index tells the agent to open the file). This repository dogfoods it — the generated block in its own CLAUDE.md is 71 lines, with 370 lines of per-element detail sitting in .claude/rules/ until they are relevant. Without it, that file grows linearly with every annotated element. See USAGE.md.
• Zero runtime cost — RetentionPolicy.SOURCE annotations are erased at compile time; nothing reaches the JVM.
• CI-enforceable — opt-in check mode (-Avibetags.check=true) fails the build when guardrail files have drifted from the annotations, and the locked-files GitHub Action fails any PR whose diff touches @AILocked code. See USAGE.md.

⚡ Add VibeTags to Your Project in 60 Seconds

Maven

1. Add to pom.xml:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>se.deversity.vibetags</groupId>
            vibetags-bom</artifactId>
            <version>1.4.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>se.deversity.vibetags</groupId>
        vibetags-annotations</artifactId>
    </dependency>
</dependencies>