VibeTags AI Guardrails for Java Development

1. Add to pom.xml:

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

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

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>se.deversity.vibetags</groupId>
                        <artifactId>vibetags-processor</artifactId>
                        <version>1.4.1</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

Already using Lombok, MapStruct or another annotation processor? Put vibetags-processor in the same <annotationProcessorPaths> list as them. Once that list exists, javac ignores processors on the class path, so a list holding VibeTags alone switches the others off. VibeTags names any processor it sees dropped; Other Annotation Processors has the snippet and the Spring Boot layout.

2. Opt in to the AI platforms you use (file presence = opt-in; VibeTags never creates files on its own):

touch CLAUDE.md .cursorrules AGENTS.md   # Claude, Cursor, Codex CLI — add whichever you use

Or let the companion CLI do it (and vibetags doctor checks your setup afterwards):

jbang se.deversity.vibetags:vibetags-cli:1.4.1 init --platforms claude,cursor

3. Annotate your first class:

@AILocked(reason = "Legacy payment integration — changes will break production.")
public interface PaymentProcessor {
    String processPayment(double amount, String currency, String merchantId);
}

4. Compile:

mvn compile

CLAUDE.md and .cursorrules now contain generated guardrail rules. Open either file and look for the VIBETAGS-START / VIBETAGS-END marker block — that section is managed by VibeTags and regenerated on every compile.

1. Add to build.gradle:

dependencies {
    implementation platform('se.deversity.vibetags:vibetags-bom:1.4.1')
    annotationProcessor platform('se.deversity.vibetags:vibetags-bom:1.4.1')

    compileOnly 'se.deversity.vibetags:vibetags-annotations'
    annotationProcessor 'se.deversity.vibetags:vibetags-processor'
}

2. Opt in to the AI platforms you use:

touch CLAUDE.md .cursorrules AGENTS.md

3. Annotate your first class:

@AILocked(reason = "Legacy payment integration — changes will break production.")
public interface PaymentProcessor {
    String processPayment(double amount, String currency, String merchantId);
}

4. Compile:

gradle compileJava

Every @AI* annotation is a plain Java annotation with SOURCE retention, so it works on Kotlin classes and functions unchanged. VibeTags runs under kapt, or under KSP through vibetags-ksp (the next section).

1. Add to build.gradle.kts:

plugins {
    kotlin("jvm") version "2.4.21"
    kotlin("kapt") version "2.4.21"
}

dependencies {
    implementation(platform("se.deversity.vibetags:vibetags-bom:1.4.1"))
    kapt(platform("se.deversity.vibetags:vibetags-bom:1.4.1"))

    compileOnly("se.deversity.vibetags:vibetags-annotations")
    kapt("se.deversity.vibetags:vibetags-processor")
}

kapt {
    arguments {
        // kapt's working directory is not the project directory — pass the root explicitly.
        arg("vibetags.root", projectDir.absolutePath)
    }
}

2. Opt in to the AI platforms you use:

touch CLAUDE.md .cursorrules AGENTS.md

3. Annotate your first class:

@AILocked(reason = "Legacy payment integration — changes will break production.")
class PaymentProcessor {
    fun processPayment(amount: Double, currency: String, merchantId: String): String = TODO()
}

4. Compile:

gradle build

One caveat: kapt processes generated Java stubs, which carry no method bodies — so annotations on declarations inside a function body are invisible, and .vibetags-locks line ranges would describe the stub rather than the .kt file. Class-level and function-level annotations — the normal usage — work fully. A complete working consumer is in examples/kotlin/.

Other JVM languages: Groovy is fully supported via joint-compilation stubs (javaAnnotationProcessing = true — see examples/groovy/); Scala and Clojure toolchains never run JSR 269 processors, so guardrails there live on annotated Java neighbours (examples/scala/). The full support matrix is in USAGE.md.

KSP cannot load a JSR 269 processor, so a Kotlin build that has moved off kapt depends on vibetags-ksp in place of vibetags-processor. It runs the same processor behind a KSP front end and produces the same element paths and the same files as kapt: examples/kotlin-ksp/ compiles examples/kotlin's sources through KSP, and CI fails unless its output matches the kapt build byte for byte.

plugins {
    kotlin("jvm") version "2.4.21"
    id("com.google.devtools.ksp") version "2.3.12"
}

dependencies {
    implementation(platform("se.deversity.vibetags:vibetags-bom:1.4.1"))
    ksp(platform("se.deversity.vibetags:vibetags-bom:1.4.1"))

    compileOnly("se.deversity.vibetags:vibetags-annotations")
    ksp("se.deversity.vibetags:vibetags-ksp")
}

ksp {
    // KSP runs inside the Gradle daemon, whose working directory is not the project.
    arg("vibetags.root", projectDir.absolutePath)
}

Every processor option is a ksp { arg(...) }. Two differences from kapt: .vibetags-locks line ranges point at the .kt source (under kapt they pointed into the generated stubs), and a guardrail on a function kapt has no stub for (a value class in its signature) is reported as a build warning instead of being dropped without a word. Details: USAGE.md.