v1.3.5 to v1.3.5

- description: This skill should be used when the user asks how to "use VibeTags", "add VibeTags annotations", "set up AI guardrails", "protect code from AI", "configure AI platforms", asks about @AILocked, @AIContext, @AIDraft, @AIAudit, @AIIgnore, @AIPrivacy, @AICore, @AIPerformance, @AIContract, @AITestDriven, @AIThreadSafe, @AIImmutable, @AIDeprecated, @AIObservability, @AIRegulation, @AIArchitecture, @AILegacyBridge, @AIStrictClasspath, @AIInternationalized, @AIPublicAPI, @AISchemaSafe, @AIStrictExceptions, @AIStrictTypes, @AIParallelTests, @AIIdempotent, @AIFeatureFlag, @AISecure, @AICallersOnly, @AISandboxOnly, @AIMemoryBudget, @AIPure, @AIDomainModel, @AIExtensible, @AIInputSanitized, @AISecureLogging, @AIExplain, @AIPrototype, @AISunset, @AITemporary, @AIGenerated, @AILoadBearing, @AIBannedApi, @AIThreadAffinity, @AIKeepInSync annotations, or wants to control how AI tools interact with Java code.

- ### `@AILocked` — Protect critical code from modification

-

- Use on: **class, method, field**

-

- ```java

- @AILocked(reason = "Tied to legacy database schema v2.3. Any change breaks production payment flow.")

- public interface PaymentProcessor {

- String processPayment(double amount, String currency, String merchantId);

- }

- ```

-

- When to use: legacy integrations, compliance-regulated code (PCI-DSS, HIPAA), algorithms that took months to stabilize.

-

- ---

-

- ### `@AIContext` — Guide AI behavior for a class or method

-

- Use on: **class, method**

-

- ```java

- @AIContext(

- focus = "Optimize for memory usage over CPU speed",

- avoids = "java.util.regex, String.split(), StringBuilder in loops"

- )

- public class StringParser { ... }

- ```

-

- Use `focus` to tell AI what to optimize for; use `avoids` to list libraries, patterns, or constructs it should not introduce.

-

- ---

-

- ### `@AIDraft` — Request an AI implementation

-

- Use on: **class, method**

-

- ```java

- @AIDraft(instructions = "Implement email sending via SMTP and push notifications via FCM. Include retry logic and rate limiting.")

- public class NotificationService {

- public void sendNotification(String userId, String message) {

- // AI implements this

- }

- }

- ```

-

- Tip: `@AIDraft` and `@AILocked` on the same element produce a compile-time warning — they are contradictory.

-

- ---

-

- ### `@AIAudit` — Require continuous security auditing

-

- Use on: **class, method**

-

- ```java

- @AIAudit(checkFor = {"SQL Injection", "Thread Safety issues", "Path Traversal"})

- public class DatabaseConnector { ... }

- ```

-

- Every time an AI tool modifies tagged code it must explicitly state it audited the changes for each listed vulnerability.

-

- Common values for `checkFor`: `"SQL Injection"`, `"XSS"`, `"CSRF"`, `"Command Injection"`, `"Thread Safety issues"`, `"Insecure Deserialization"`, `"Authentication Bypass"`.

-

- Empty `checkFor` array produces a compile-time warning and is ignored.

-

- ---

-

- ### `@AIIgnore` — Exclude from AI context entirely

-

- Use on: **class, method, field**

-

- ```java

- @AIIgnore(reason = "Auto-generated at build time. Manual edits are overwritten on every build.")

- public class GeneratedMetadata { ... }

- ```

-

- Unlike `@AILocked` (visible but immutable), `@AIIgnore` tells AI to treat the element as if it does not exist. Use for: generated code, deprecated scaffolding, internal plumbing.

-

- ---

-

- ### `@AIPrivacy` — Protect PII fields and methods

-

- Use on: **class, method, field**

-

- ```java

- public class UserRepository {

- @AIPrivacy(reason = "GDPR - never log or include in error messages, test fixtures, or mock data")

- private final String email;

-

- @AIPrivacy(reason = "PCI-DSS - must not appear in logs, console output, or external API calls")

- private final String creditCardToken;

- }

- ```

-

- AI remains aware the element exists (for code assistance) but must never reproduce its runtime values in logs, suggestions, test fixtures, mock data, or external API calls.

-

- Using `@AIPrivacy` together with `@AIIgnore` on the same element produces a compile-time warning (redundant — `@AIIgnore` already excludes the element).

-

- ---

-

- ### `@AICore` — Mark sensitive core logic

-

- Use on: **class, method, field**

-

- ```java

- @AICore(

- sensitivity = "Critical",

- note = "Core transaction engine. Well-tested. Changes require user approval."

- )

- public class TransactionEngine { ... }

- ```

-

- Use `sensitivity` (default `"High"`) to indicate impact level, and `note` to provide specific warnings. AI will treat changes with extreme caution and must not refactor without explicit approval.

-

- ---

-

- ### `@AIPerformance` — Enforce complexity constraints

-

- Use on: **class, method**

-

- ```java

- @AIPerformance(

- constraint = "Must maintain O(1) time complexity. No heap allocations."

- )

- public class FastBuffer { ... }

- ```

-

- Informs AI that logic is on a hot-path and suboptimal complexity is unacceptable. AI must reason about time and space complexity before proposing changes.

-

- ---

-

- ### `@AIContract` — Freeze a public API signature

-

- Use on: **class, method**

-

- ```java

- @AIContract(reason = "Signature locked by OpenAPI v2 contract. checkout-service and mobile-app bind to this exact signature. A type change is a breaking API change.")

- @AIPerformance(constraint = "Must complete in <5ms p99. Called on every cart update.")

- public double calculatePrice(String productId, int quantity, String customerId) {

- // Internal logic may be freely changed

- }

- ```

-

- Tells AI: the method name, parameter types, parameter order, return type, and checked exceptions are **frozen**. Internal logic may be refactored freely. Use when:

-

- - The method signature is pinned by an OpenAPI / AsyncAPI contract

- - Other services bind to it via generated clients or message schemas

- - Changing the signature requires a major-version bump and migration coordination

-

- Unlike `@AILocked` (which prohibits all changes), `@AIContract` explicitly invites AI to improve internal logic — it only protects the public surface.

-

- **Compile-time warnings:**

-

- - `@AIContract` + `@AIDraft` on the same element — contradictory (signature is frozen, but `@AIDraft` implies the element still needs implementing)

- - `@AIContract` + `@AILocked` on the same element — overlapping intent (`@AILocked` already prohibits all changes; consider using only `@AILocked` if no changes at all are intended)

-

- ---

-

- ### `@AITestDriven` — Enforce a test-driven workflow

-

- Use on: **class, method**

-

- ```java

- @AITestDriven(

- framework = {AITestDriven.Framework.JUNIT_5, AITestDriven.Framework.MOCKITO},

- coverageGoal = 90,

- mockPolicy = "Always mock external APIs and database calls",

- testLocation = "src/test/java/com/example/OrderServiceTest.java"

- )

- public class OrderService { ... }

- ```

-

- Enforces a strict Red-Green-Refactor workflow: AI **must** include the corresponding test code in the same response as any proposed change. A change without matching tests is treated as incomplete.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `framework` | `Framework[]` | `{JUNIT_5}` | Testing frameworks the AI must use. Combine freely (e.g., `{JUNIT_5, MOCKITO}`). Options: `JUNIT_5`, `JUNIT_4`, `TESTNG`, `MOCKITO`, `ASSERTJ`, `SPOCK`, `NONE` |

- | `coverageGoal` | `int` | `100` | Minimum statement-coverage % the AI must achieve in the generated or updated tests (0–100) |

- | `testLocation` | `String` | `""` | Explicit path to the corresponding test file. Leave empty to let the AI infer the test class by naming convention |

- | `mockPolicy` | `String` | `""` | Instruction describing how external dependencies should be handled in tests |

-

- **Compile-time warnings:**

-

- - `@AITestDriven` + `@AIIgnore` on the same element — contradictory (`@AIIgnore` excludes the element from AI context entirely; `@AITestDriven` cannot enforce test coverage on an ignored element)

- - `@AITestDriven` + `@AILocked` on the same element — contradictory (`@AILocked` prohibits all modifications; `@AITestDriven` permits changes only when tests are updated — consider using only `@AILocked` if no changes at all are intended)

- - `@AITestDriven` with `coverageGoal` outside 0–100 — invalid value

-

- ---

-

- ### `@AIThreadSafe` — Preserve a thread-safety strategy

-

- Use on: **class, method**

-

- ```java

- @AIThreadSafe(

- strategy = AIThreadSafe.Strategy.LOCK_FREE,

- note = "All mutations go through ConcurrentHashMap; never introduce a synchronized block on the cache map."

- )

- public class SessionCache { ... }

- ```

-

- Declares an *existing* thread-safety design that AI must not silently break. Different from `@AIAudit(checkFor = "Thread Safety")` (which asks the AI to look for new bugs).

-

- **Strategies:** `SYNCHRONIZED`, `LOCK_FREE`, `IMMUTABLE`, `THREAD_LOCAL`, `OTHER`. Default `SYNCHRONIZED`.

-

- When to use: caches and registries shared across threads, atomics-backed counters, singletons guarded by a named lock, per-thread context held in `ThreadLocal`.

-

- ---

-

- ### `@AIImmutable` — Declare a class immutable

-

- Use on: **class**

-

- ```java

- @AIImmutable(note = "Used by every test runner; safe to share across threads without copies.")

- public final class AsyncTestConfig {

- private final int timeoutMs;

- public AsyncTestConfig(int timeoutMs) { this.timeoutMs = timeoutMs; }

- }

- ```

-

- Declares the type immutable so AI assistants will not introduce setters, mutating methods, or non-final fields. The processor warns at compile time when an `@AIImmutable` class declares a non-final, non-static instance field.

-

- When to use: value objects, config holders, snapshots passed across thread boundaries, cache keys.

-

- **Compile-time warnings:**

-

- - `@AIImmutable` on a type with a non-final, non-static instance field — violates the immutability declaration

- - `@AIThreadSafe(IMMUTABLE)` + `@AIImmutable` on the same type — redundant (`@AIImmutable` already implies thread-safety)

-

- ---

-

- ### `@AIDeprecated` — Route callers toward a replacement

-

- Use on: **class, method, field**

-

- ```java

- @AIDeprecated(

- replacedBy = "com.example.payment.PaymentProcessor",

- migrationGuide = "Switch callers to PaymentProcessor.charge(). The new API uses Money instead of double.",

- deadline = "v2.0 (2026-Q4)"

- )

- public class OldPaymentApi { ... }

- ```

-

- Richer than Java's `@Deprecated`. Where `@AILocked` *preserves* an element, `@AIDeprecated` actively *routes AI toward killing it* — the AI is told to suggest migrating callers rather than extending the deprecated element.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `replacedBy` | `String` | `""` | Fully-qualified name of the replacement |

- | `migrationGuide` | `String` | `"Migrate any caller to the replacement."` | How callers should migrate |

- | `deadline` | `String` | `""` | Removal deadline (release version, ISO date, etc.) |

-

- When to use: legacy APIs being phased out, modules behind a sunset flag, methods kept only for backwards compatibility while callers migrate.

-

- **Compile-time warnings:**

-

- - `@AIDeprecated` + `@AILocked` on the same element — contradictory (locked preserves; deprecated routes callers away)

-

- ---

-

- ### `@AIObservability` — Protect instrumentation

-

- Use on: **class, method**

-

- ```java

- @AIObservability(

- metrics = {"orders.placed.total", "orders.placed.failed"},

- traces = {"order.place"},

- logs = {"OrderPlaced", "OrderPlacementFailed"},

- note = "Watched by the Orders SLO dashboard."

- )

- public void recordOrderPlaced(String orderId, boolean success) { ... }

- ```

-

- Marks code whose metrics, trace spans, or log statements downstream dashboards/alerts depend on. AI assistants must not silently remove or rename the listed instrumentation.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `metrics` | `String[]` | `{}` | Metric counter/gauge names this element publishes |

- | `traces` | `String[]` | `{}` | Trace span names this element opens |

- | `logs` | `String[]` | `{}` | Log statement identifiers this element emits |

- | `note` | `String` | `""` | Free-form note (e.g., "watched by SLO dashboard X") |

-

- When to use: SLO emitters, audit-log writers, request handlers whose latency histograms feed an SLA, background workers whose failure metrics page on-call.

-

- **Compile-time warnings:**

-

- - `@AIObservability` with no `metrics`, `traces`, or `logs` — no-op (nothing to preserve)

-

- ---

-

- ### `@AIRegulation` — Tie code to a compliance clause

-

- Use on: **class, method, field**

-

- ```java

- @AIRegulation(

- standard = "GDPR",

- clause = "Art. 17",

- description = "Right to erasure — when invoked, deletes ALL PII for the given user across every connected store."

- )

- public class GdprService { ... }

- ```

-

- Ties code to a specific regulatory clause (GDPR, PCI-DSS, HIPAA, SOX, …). Stronger than `@AIAudit` because it names the exact article — AI assistants must document compliance impact for every change and must not weaken the requirement.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `standard` | `String` | *(required)* | Compliance standard name (e.g., `"GDPR"`, `"PCI-DSS"`, `"HIPAA"`, `"SOX"`) |

- | `clause` | `String` | `""` | Specific clause/article/section |

- | `description` | `String` | non-blank | What this element does to satisfy the requirement |

-

- When to use: GDPR Art. 17 / Art. 20 implementations, PCI-DSS card-handling code, HIPAA-protected PHI read/write paths, SOX-relevant financial reporting and audit-log writers.

-

- **Compile-time warnings:**

-

- - `@AIRegulation` with a blank `standard` — required attribute missing

-

- ---

-

- ### `@AIArchitecture` — Enforce architectural layer boundaries

-

- Use on: **class**

-

- ```java

- @AIArchitecture(

- belongsTo = "domain",

- cannotReference = {"infrastructure", "web"}

- )

- public class OrderService { ... }

- ```

-

- Declares which architectural layer this class belongs to and which layers it must never import from. AI must not introduce references to forbidden layers — e.g., a domain class importing a JPA repository or an HTTP controller.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `belongsTo` | `String` | `""` | The layer or component this class belongs to (e.g., `"domain"`, `"application"`, `"web"`) |

- | `cannotReference` | `String[]` | `{}` | Layers or components this class must not import from |

-

- ---

-

- ### `@AILegacyBridge` — Protect compatibility bridges from modernization

-

- Use on: **class, method**

-

- ```java

- @AILegacyBridge(reason = "Mirrors a v1 payment-SDK quirk; 'cleaning it up' broke the gateway in 2023")

- public class LegacyPaymentAdapter {

- // Works around a quirk in the v1 payment provider SDK — must not be "cleaned up"

- public String formatAmount(double amount) { ... }

- }

- ```

-

- Marks code that exists solely to bridge to a legacy or upstream system with known quirks or bugs. AI must not modernize the structure, apply new patterns, or remove the "ugly" parts — they exist for a reason. Internal business logic may still be changed. The optional `reason` records *why* across AI sessions and is surfaced in the generated output.

-

- When to use: SDK adapter shims, workarounds for upstream library bugs, compatibility wrappers kept alive for old API clients.

-

- ---

-

- ### `@AIStrictClasspath` — Prevent dynamic loading and reflection hacks

-

- Use on: **class, method**

-

- ```java

- @AIStrictClasspath(reason = "Runs in the locked-down sandbox where the SecurityManager throws on reflection")

- public class DataParser {

- // Must only use JDK and existing compile-time classpath — no runtime class loading

- }

- ```

-

- Prohibits AI from introducing dynamic class loading, custom `ClassLoader`s, runtime reflection tricks, or execution of dynamically constructed code. All dependencies must be resolvable at compile time from the existing classpath.

-

- When to use: security-sensitive execution environments, GraalVM native-image targets, OSGi modules, any code that must be fully AOT-analyzable.

-

- ---

-

- ### `@AIInternationalized` — Prohibit hardcoded user-facing strings

-

- Use on: **class, method**

-

- ```java

- @AIInternationalized(reason = "Ships in 11 locales; a hardcoded English string failed the l10n audit last quarter")

- public class NotificationTemplateRenderer {

- // All user-visible text must come from message bundles — never hardcoded

- }

- ```

-

- Instructs AI that all user-visible text (labels, messages, error strings, button text) must be resolved through the project's i18n framework (e.g., `MessageSource`, `ResourceBundle`, `gettext`). AI must never introduce hardcoded string literals for anything a user would see.

-

- When to use: UI components, REST error responses, email templates, notification services — any code whose output reaches end users.

-

- ---

-

- ### `@AIPublicAPI` — Preserve backward compatibility

-

- Use on: **class, method**

-

- ```java

- @AIPublicAPI(reason = "Consumed by three external partner integrations pinned to v1")

- public class ProductSearchClient {

- public List<Product> search(String query, int maxResults) { ... }

- }

- ```

-

- Declares that this element is part of a public API surface. All AI changes must be **additive and backward-compatible** — renaming methods, changing parameter types, or altering serialization formats is forbidden. Internal implementation may be improved freely.

-

- Unlike `@AIContract` (which freezes one specific signature), `@AIPublicAPI` applies the backward-compatibility rule to the entire class.

-

- When to use: SDK entry points, REST controller response shapes, message schema classes, library interfaces consumed by third parties.

-

- ---

-

- ### `@AISchemaSafe` — Prevent destructive schema changes

-

- Use on: **class, field**

-

- ```java

- @AISchemaSafe(reason = "Replicated to the billing read-model; column changes need a backward-compatible migration")

- @Entity

- public class UserEntity {

- @Column(name = "email", nullable = false)

- private String email;

- }

- ```

-

- Instructs AI that this class or field maps to persistent storage (database, message schema, serialization format). Destructive changes — dropping columns, renaming fields, changing types — are forbidden without explicit backward-compatible migrations. AI must propose additive-only changes.

-

- When to use: JPA/Hibernate entities, Avro/Protobuf schema classes, JSON serialization DTOs, Flyway-managed tables.

-

- ---

-

- ### `@AIStrictExceptions` — Enforce precise error handling

-

- Use on: **class, method**

-

- ```java

- @AIStrictExceptions(reason = "A bare catch(Exception) once swallowed a rollback and double-charged customers")

- public class PaymentGatewayClient {

- public Receipt charge(Money amount) throws PaymentDeclinedException { ... }

- }

- ```

-

- Prohibits AI from catching or throwing `Exception`, `Throwable`, or other overly broad types. All exceptions must be specific, well-named, and carry descriptive messages with preserved stack traces. Silent catch blocks (`catch (Exception e) {}`) are also forbidden.

-

- When to use: external integrations, retry boundaries, error-handling layers, code that feeds into structured logging or alerting.

-

- ---

-

- ### `@AIStrictTypes` — Require precise domain types

-

- Use on: **class, method, field**

-

- ```java

- @AIStrictTypes(reason = "Currency math broke in INC-4412 when a double leaked into the amount")

- public class PricingCalculator {

- // Use BigDecimal for money, Instant/ZonedDateTime for time — never double or String

- public BigDecimal calculateDiscount(Money basePrice, Percentage rate) { ... }

- }

- ```

-

- Instructs AI to avoid loose types (`Object`, raw collections, `Map<String, Object>`, `double` for currency, `String` for dates) and instead use well-defined, type-safe domain models or strongly-typed transfer objects.

-

- When to use: financial calculations, time/date handling, any domain model where type safety prevents silent data corruption.

-

- ---

-

- ### `@AIParallelTests` — Enforce test isolation for concurrent execution

-

- Use on: **class, method**

-

- ```java

- @AIParallelTests(reason = "A shared static counter caused flaky CI in build #4471 — keep cases isolated")

- public class OrderServiceTest {

- // Tests must not share mutable state or bind to fixed ports

- }

- ```

-

- Instructs AI that any generated or modified tests for this element must be safe for parallel execution. Forbidden: shared mutable static state, fixed port bindings, database rows with hard-coded IDs, execution-order dependencies. Each test must be fully self-contained.

-

- When to use: test classes run under JUnit 5 parallel execution, `@Isolated` test suites, any test module with `forkCount > 1` in Maven Surefire.

-

- ---

-

- ### `@AIIdempotent` — Declare an operation must be idempotent

-

- Use on: **class, method**

-

- ```java

- @AIIdempotent(reason = "Called by the retry scheduler — multiple invocations must produce the same result.")

- public void processOrder(String orderId) {

- // Must tolerate repeated calls without double-processing

- }

- ```

-

- Declares that the annotated operation is expected to be idempotent. AI must not introduce side effects that cause repeated calls to produce different results (e.g., double-inserts, repeated external API calls without deduplication, counter increments on every call).

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `reason` | `String` | `""` | Free-form note explaining why idempotency is required |

-

- When to use: retry handlers, message consumers, webhook processors, payment captures, any operation exposed to at-least-once delivery.

-

- **Compile-time warnings:**

-

- - `@AIIdempotent` + `@AIDraft` on the same element — contradictory (idempotent declares a stable contract while draft marks the element as unfinished)

-

- ---

-

- ### `@AIFeatureFlag` — Mark code gated behind a feature flag

-

- Use on: **class, method, field**

-

- ```java

- @AIFeatureFlag(flag = "checkout.new-flow", defaultValue = false)

- public void processNewCheckout(Cart cart) {

- // Only active when the 'checkout.new-flow' flag is enabled

- }

- ```

-

- Tells AI that the annotated element is gated behind a runtime feature flag. AI must preserve the flag check and must never assume the flag is always active (or always inactive). Removing the conditional guard, inlining the `true` branch, or hardcoding the default is forbidden.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `flag` | `String` | `""` | The feature flag key (e.g., `"checkout.new-flow"`) |

- | `defaultValue` | `boolean` | `false` | The flag's default value when not explicitly set |

-

- When to use: A/B experiments, gradual rollouts, kill switches, beta features, dark launches.

-

- **Compile-time warnings:**

-

- - `@AIFeatureFlag` + `@AILocked` on the same element — contradictory (locked freezes code while feature flag implies conditional execution)

- - `@AIFeatureFlag` with blank `flag` — no-op; the flag key is unspecified

-

- ---

-

- ### `@AISecure` — Mark security-critical code

-

- Use on: **class, method**

-

- ```java

- @AISecure(aspect = "authentication")

- public class JwtTokenValidator {

- // Any change here must be reviewed for security implications

- public boolean validate(String token) { ... }

- }

- ```

-

- Declares that the annotated element implements a security-critical concern (e.g., authentication, encryption, authorization, session management, input sanitization). AI must not weaken security properties and must explicitly flag any proposed change for security review.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `aspect` | `String` | `""` | The security concern (e.g., `"authentication"`, `"encryption"`, `"authorization"`) |

-

- When to use: JWT/OAuth token handling, cryptographic operations, authorization checks, session management, input validation against injection attacks, any code whose weakening would create a security vulnerability.

-

- **Compile-time warnings:**

-

- - `@AISecure` with blank `aspect` — advisory; consider specifying the security concern (e.g. `"authentication"`, `"encryption"`)

- - `@AISecure` + `@AIIgnore` on the same element — contradictory; `@AIIgnore` hides the element but `@AISecure` requires AI visibility for security review

-

- ### `@AICallersOnly` — Restrict allowed invoking callers

-

- Use on: **class, method**

-

- ```java

- @AICallersOnly({"com.example.service.PricingService", "com.example.payment.PaymentProcessor"})

- public static void executeSecureDatabaseWipe() { ... }

- ```

-

- Restricts which packages or classes are permitted to invoke this method or class. Enforced by the compiler/processor to prevent AI from introducing illegal architectural bypasses.

-

- ---

-

- ### `@AISandboxOnly` — Restrict to mock or sandbox environments

-

- Use on: **class, method**

-

- ```java

- @AISandboxOnly(reason = "Seeds fake credentials; a prod hotfix once imported it and leaked test data to staging")

- public class SandboxTestHelper { ... }

- ```

-

- Restricts the target element strictly to sandbox, dev, or mock/test environments. Prevents the AI from importing or referencing sandbox utilities in production pathways.

-

- **Compile-time warnings:**

-

- - `@AISandboxOnly` + `@AIDomainModel` on the same element — contradictory (sandbox mocks should not be subjected to framework-free domain model constraints)

-

- ---

-

- ### `@AIMemoryBudget` — Enforce strict allocation policies

-

- Use on: **class, method**

-

- ```java

- @AIMemoryBudget(AIMemoryBudget.AllocationPolicy.ZERO_ALLOCATION)

- public static int calculateFastFibonacci(int n) { ... }

- ```

-

- Restricts heap allocations, autoboxing, or object instantiation inside high-performance critical sections.

-

- **Allocation Policies:** `ZERO_ALLOCATION`, `NO_AUTOBOXING`, `NO_NEW_OBJECTS`.

-

- ---

-

- ### `@AIPure` — Mark side-effect-free pure mathematical functions

-

- Use on: **method**

-

- ```java

- @AIPure(reason = "Memoized by callers that assume referential transparency — no logging or caching side effects")

- public static int add(int a, int b) { return a + b; }

- ```

-

- Declares that a method is a pure mathematical function. Must be deterministic (same input leads to same output) and have zero side effects.

-

- ---

-

- ### `@AIDomainModel` — Enforce Domain-Driven Design boundaries

-

- Use on: **class**

-

- ```java

- @AIDomainModel(allow = {"java.math.BigDecimal"})

- public class ImmutableProductPrice { ... }

- ```

-

- Enforces DDD boundaries by preventing external/framework imports. The compiler will scan and block any imports from Spring, JPA/Hibernate, Jackson, etc. unless explicitly whitelisted.

-

- ---

-

- ### `@AIExtensible` — Mark open-closed polymorphic extension hooks

-

- Use on: **class**

-

- ```java

- @AIExtensible(AIExtensible.Strategy.STRATEGY_PATTERN)

- public interface TaxCalculatorStrategy { ... }

- ```

-

- Signals that a class or interface must be extended using polymorphic designs (Open-Closed Principle). Prompts the AI to introduce strategy or visitor patterns rather than accumulating massive conditional/switch statements.

-

- **Strategies:** `STRATEGY_PATTERN`, `VISITOR_PATTERN`, `FACTORY`.

-

- ---

-

- ### `@AIInputSanitized` — Enforce input parameter sanitization

-

- Use on: **parameter, field**

-

- ```java

- public static void executeDatabaseQuery(

- @AIInputSanitized({AIInputSanitized.SanitizerType.SQL_INJECTION}) String sqlRawInput) { ... }

- ```

-

- Enforces sanitization pipelines on input parameters or fields before they reach queries, HTML renderers, or files.

-

- **Sanitizer Types:** `SQL_INJECTION`, `XSS`, `PATH_TRAVERSAL`, `LDAP`.

-

- ---

-

- ### `@AISecureLogging` — Mask sensitive variables in log statements

-

- Use on: **field, parameter**

-

- ```java

- public static void registerUserSession(

- String username,

- @AISecureLogging(AISecureLogging.MaskingPolicy.HASH) String passwordRaw) { ... }

- ```

-

- Protects sensitive variables from being logged directly or leaked in console outputs.

-

- **Masking Policies:** `OMIT`, `HASH`, `MASK_CREDIT_CARD`, `MASK_EMAIL`.

-

- **Compile-time warnings:**

-

- - `@AISecureLogging` + `@AIIgnore` on the same element — redundant (`@AIIgnore` already completely excludes the element)

-

- ---

-

- ### `@AIExplain` — Require Chain-of-Thought mathematical/architectural explanations

-

- Use on: **class, method**

-

- ```java

- @AIExplain(AIExplain.ComplexityLevel.HIGH)

- public static double runComplexMatrixMath(double[][] a, double[][] b) { ... }

- ```

-

- Enforces step-by-step mathematical/architectural Chain-of-Thought (CoT) explanations of any modifications.

-

- **Complexity Levels:** `HIGH`, `MEDIUM`, `LOW`.

-

- ---

-

- ### `@AIPrototype` — Declare rapid disposable spikes

-

- Use on: **class**

-

- ```java

- @AIPrototype(reason = "Throwaway Q3 Kafka spike — no error handling on purpose; production must not depend on it")

- public class DraftKafkaIntegrationSpike { ... }

- ```

-

- Declares a rapid framework prototype. Relaxes standard strict quality rules (e.g. required i18n, coverage) within the class, but prevents it from leaking into stable production code.

-

- ---

-

- ### `@AISunset` — Ultra-strict api sunset deprecation guardrail

-

- Use on: **class, method, field**

-

- ```java

- @AISunset(replacement = PricingService.class, jira = "DEBT-742")

- public static double deprecatedLegacyCalculatePrice(double basePrice) { ... }

- ```

-

- AI models are strictly prohibited from adding any new references/calls to elements annotated with `@AISunset`.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `replacement` | `Class<?>` | `Object.class` | Fully qualified class replacement for the sunset API element |

- | `jira` | `String` | *(required)* | JIRA or issue tracking ticket for deprecation/sunset progress (e.g. "DEBT-123") |

-

- **Compile-time warnings:**

-

- - `@AISunset` + `@AIDraft` on the same element — contradictory (sunset elements must not be actively drafted or expanded)

- - `@AISunset` with blank `jira` — missing required JIRA issue key warning

-

- ---

-

- ### `@AITemporary` — Warn or block expired temporary logic and hotfixes

-

- Use on: **class, method**

-

- ```java

- @AITemporary(expiresOn = "2028-12-31", reason = "Hotfix workaround until upstream updates their API.")

- public static void temporaryUpstreamBypass() { ... }

- ```

-

- Hard stop for hotfixes, temporary stubs, or quick hacks. Warns or fails compilation once the local clock date exceeds the expiration date.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `expiresOn` | `String` | *(required)* | Expiration date in ISO format YYYY-MM-DD (e.g. "2026-06-30") |

- | `reason` | `String` | *(required)* | Rationale behind this temporary workaround |

-

- **Compile-time warnings:**

-

- - `@AITemporary` with a blank `expiresOn` — missing required expiration date

- - `@AITemporary` with an invalid `expiresOn` format (not YYYY-MM-DD)

- - `@AITemporary` where local date is after `expiresOn` — expired logic warning

-

- ---

-

- ### `@AIGenerated` — Redirect edits to the true source

-

- Use on: **class, method, field**

-

- ```java

- @AIGenerated(from = "src/main/resources/openapi/orders.yaml",

- regenerateWith = "mvn generate-sources",

- editInstead = "src/main/resources/openapi/orders.yaml")

- public class OrdersApiStub { ... }

- ```

-

- A **redirect**, not a wall. `@AILocked` can only say "stop", which makes an agent give up or route around the obstacle; this names where the change belongs. `@AIIgnore` is wrong in the opposite direction — an agent must still *read* generated types to understand behavior, it must only never *write* them.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `from` | `String` | *(required)* | The schema, template, IDL, or upstream repo this is generated from |

- | `regenerateWith` | `String` | `""` | Command that regenerates it (e.g. `"mvn generate-sources"`) |

- | `editInstead` | `String` | `""` | The file a human should actually change, when it differs from `from` |

-

- **Compile-time warnings:**

-

- - `@AIGenerated` + `@AIIgnore` — contradictory; generated code must stay readable

- - `@AIGenerated` + `@AIDraft` — contradictory; drafting output that gets overwritten is pointless

- - `@AIGenerated` with neither `regenerateWith` nor `editInstead` — a dead end rather than a redirect

-

- ---

-

- ### `@AILoadBearing` — "This looks wrong and is deliberate"

-

- Use on: **class, method, field, parameter**

-

- ```java

- @AILoadBearing(invariant = "Sessions are never deallocated while the dispatch source is live",

- breaksIf = "Freeing here reintroduces a use-after-free crash under load (#412)",

- suppressAudit = true)

- private final List<Session> retained = new ArrayList<>();

- ```

-

- Unlike `@AILocked`, edits are welcome — as long as the invariant survives. Also covers the **intentional omission** case (a decorator deliberately not applied), which nothing else can express because there is no element to annotate for something that is not there.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `invariant` | `String` | *(required)* | What must remain true after any change |

- | `breaksIf` | `String` | `""` | The concrete failure — crash, leak, silent desync |

- | `suppressAudit` | `boolean` | `false` | Tells reviewers and scanners the oddity is not a defect |

-

- **Compile-time warnings:**

-

- - `@AILoadBearing` with a blank `breaksIf` — advisory; the failure mode is what makes the rule stick

- - `@AILoadBearing(suppressAudit = true)` + `@AIAudit` — contradictory instructions to the same reviewer

-

- ---

-

- ### `@AIBannedApi` — Forbid symbols you cannot annotate

-

- Use on: **class, method**

-

- ```java

- @AIBannedApi(forbidden = {"java.lang.System.out", "java.lang.System.err"},

- useInstead = "the injected org.slf4j.Logger",

- reason = "Console output bypasses structured logging")

- public class OrderService { ... }

- ```

-

- Hosted on the **consumer** and pointing outward, because the symbols teams actually ban — `java.util.Date`, `System.out`, a framework's `@Scheduled` — are stdlib or third-party and cannot be annotated at all. `@AIArchitecture(cannotReference)` bans a *layer*, not a *symbol*, and carries no replacement.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `forbidden` | `String[]` | *(required)* | The forbidden symbols, types, or packages |

- | `useInstead` | `String` | `""` | The sanctioned replacement |

- | `reason` | `String` | `""` | Why the API is banned here |

-

- **Compile-time warnings:**

-

- - `@AIBannedApi` with an empty `forbidden[]` — no-op; nothing is banned

- - `@AIBannedApi` with a blank `useInstead` — advisory; a ban with no route invites a worse substitute

-

- ---

-

- ### `@AIThreadAffinity` — Safe on exactly one thread

-

- Use on: **class, method**

-

- ```java

- @AIThreadAffinity(value = AIThreadAffinity.Affinity.NAMED,

- thread = "Swing EDT",

- marshalVia = "SwingUtilities.invokeLater",

- symptomIfViolated = "Silent repaint corruption; no exception on most JDKs")

- public void refreshTable() { ... }

- ```

-

- The inverse of `@AIThreadSafe`, which promises safety from *any* thread. These are opposite claims: tagging an EDT-pinned method `@AIThreadSafe` states something false, and leaving it untagged invites "let's move this off the main thread". An AI asked to make it thread-safe adds a lock — precisely the wrong fix, because the requirement is not mutual exclusion but *which* thread runs the call.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `value` | `Affinity` | *(required)* | `MAIN_ONLY`, `NEVER_MAIN`, `BACKGROUND_ONLY`, or `NAMED` |

- | `thread` | `String` | `""` | The thread's name when `value` is `NAMED` |

- | `marshalVia` | `String` | `""` | How a caller on the wrong thread hands work across |

- | `symptomIfViolated` | `String` | `""` | What going wrong looks like — usually only under load |

-

- **Compile-time warnings:**

-

- - `@AIThreadAffinity` + `@AIThreadSafe` — contradictory; opposite claims, so one of them is false

- - `@AIThreadAffinity(NAMED)` with a blank `thread` — the required thread is unidentifiable

- - `@AIThreadAffinity` with a blank `marshalVia` — advisory; the caller is told "no" with no way to comply

-

- ---

-

- ### `@AIKeepInSync` — Duplicated at sites that must move together

-

- Use on: **class, method, field**

-

- ```java

- @AIKeepInSync(mirrors = {"pom.xml:<version>", "README.md badge", "docs/CHANGELOG.md"},

- reason = "The release version is asserted in three places and drifts silently",

- enforcedBy = "ProjectFactsConsistencyTest")

- public static final String VERSION = "1.3.0";

- ```

-

- The element is free to change — the failure mode is a *partial* change that desyncs a mirror no compiler checks. `@AIContract` freezes one signature so it cannot change at all; neither it nor `@AISchemaSafe` expresses "edit A ⇒ you must also edit B". Mirrors routinely point outside the compilation unit, so VibeTags can only *name* them, not verify them.

-

- | Attribute | Type | Default | Description |

- |---|---|---|---|

- | `mirrors` | `String[]` | *(required)* | The sites that must move together with this element |

- | `reason` | `String` | `""` | Why the duplication exists and what desync would break |

- | `enforcedBy` | `String` | `""` | The parity test or CI check; its absence means drift is not caught |

-

- **Compile-time warnings:**

-

- - `@AIKeepInSync` with an empty `mirrors[]` — no-op; nothing is kept in sync

- - `@AIKeepInSync` + `@AIContract` — NOTE; verify the mirrors track something other than the frozen signature

-

- ---

-

- ## Annotation Combinations

-

- | Combination | Result |

- |---|---|

- | `@AIContext` + `@AIAudit` | Guide implementation AND enforce security checks |

- | `@AIDraft` + `@AIContext` | Request implementation with style constraints |

- | `@AIPrivacy` (field) + `@AIContext` (class) | Class-level guidance with PII fields protected |

- | `@AICore` + `@AIPerformance` | Hot-path core logic with strict complexity rules |

- | `@AIContract` + `@AIPerformance` | Contract-frozen signature with performance budget |

- | `@AIContract` + `@AIContext` | Frozen signature with guidance on internal implementation |

- | `@AILocked` + `@AIDraft` | **Warning**: contradictory — don't combine |

- | `@AIIgnore` + `@AIPrivacy` | **Warning**: redundant — `@AIIgnore` already excludes |

- | `@AIContract` + `@AIDraft` | **Warning**: contradictory — frozen signature can't need drafting |

- | `@AIGenerated` + `@AILocked` | Belt-and-braces on generated output; `@AIGenerated` alone is usually better, since it redirects instead of dead-ending |

- | `@AILoadBearing` + `@AIExplain` | Supply the rationale AND require one back for any change |

- | `@AIBannedApi` + `@AIArchitecture` | Ban specific symbols AND the layers they live in |

- | `@AIThreadAffinity` + `@AIThreadSafe` | **Warning**: contradictory — opposite claims, one is false |

- | `@AIGenerated` + `@AIIgnore` | **Warning**: contradictory — generated code must stay readable |

- | `@AILoadBearing(suppressAudit)` + `@AIAudit` | **Warning**: contradictory — one suppresses findings, the other mandates them |

- | `@AIContract` + `@AILocked` | **Warning**: overlapping intent — consider using only `@AILocked` |

- | `@AITestDriven` + `@AIContext` | Enforce TDD workflow AND guide implementation style |

- | `@AITestDriven` + `@AIPerformance` | Any change must include tests AND meet complexity constraints |

- | `@AITestDriven` + `@AIIgnore` | **Warning**: contradictory — `@AIIgnore` excludes element from AI context |

- | `@AITestDriven` + `@AILocked` | **Warning**: contradictory — `@AILocked` prohibits all changes |

- | `@AIThreadSafe` + `@AIPerformance` | Concurrent code with strict complexity budget |

- | `@AIThreadSafe` + `@AIAudit` | Preserve sync invariant AND audit each change for new bugs |

- | `@AIImmutable` + `@AIThreadSafe(IMMUTABLE)` | **Warning**: redundant — `@AIImmutable` already implies thread-safety |

- | `@AIDeprecated` + `@AIContext` | Mark for removal AND guide migration approach |

- | `@AIDeprecated` + `@AILocked` | **Warning**: contradictory — locked preserves; deprecated routes callers away |

- | `@AIObservability` + `@AIPerformance` | Instrumented hot-path code with budget AND dashboard dependencies |

- | `@AIObservability` + `@AICore` | Core logic whose metrics feed dashboards — change with extreme caution |

- | `@AIRegulation` + `@AIAudit` | Compliance clause AND mandatory security audit |

- | `@AIRegulation` + `@AIPrivacy` | PII handler tied to a specific GDPR/HIPAA/PCI-DSS clause |

- | `@AIRegulation` + `@AILocked` | Compliance code that must not be modified at all |

- | `@AIArchitecture` + `@AIAudit` | Enforce layer boundaries AND audit each change for illegal imports |

- | `@AIArchitecture` + `@AIContext` | Layer constraints with guidance on permitted patterns within that layer |

- | `@AILegacyBridge` + `@AILocked` | Compatibility shim that must not be touched at all |

- | `@AILegacyBridge` + `@AIContext` | Bridge code with guidance on what internal logic *can* be changed |

- | `@AIPublicAPI` + `@AIContract` | Whole-class backward-compat rule AND per-method frozen signature (belt-and-suspenders) |

- | `@AIPublicAPI` + `@AITestDriven` | Public API change must include tests proving backward compatibility |

- | `@AISchemaSafe` + `@AIPrivacy` | Persistent entity with PII fields that must not appear in logs or fixtures |

- | `@AISchemaSafe` + `@AIRegulation` | Schema tied to a compliance clause (GDPR erasure table, PCI card-data store) |

- | `@AIStrictTypes` + `@AIPerformance` | Typed domain model AND strict complexity budget |

- | `@AIStrictTypes` + `@AIRegulation` | Type-safe financial or PII handler tied to a regulatory clause |

- | `@AIStrictExceptions` + `@AIAudit` | Precise error handling AND audit every change for swallowed exceptions |

- | `@AIStrictExceptions` + `@AIObservability` | Error handler whose log statements feed dashboards — must not be silenced |

- | `@AIInternationalized` + `@AIContext` | i18n enforcement with guidance on which bundle/framework to use |

- | `@AIStrictClasspath` + `@AIPerformance` | Compile-time-only deps AND strict complexity budget |

- | `@AIParallelTests` + `@AITestDriven` | Tests must be parallel-safe AND include coverage for every change |

- | `@AIIdempotent` + `@AIDraft` | **Warning**: contradictory — idempotent declares a stable contract; draft marks it as unfinished |

- | `@AIIdempotent` + `@AIContext` | Idempotent operation with guidance on which deduplication approach to use |

- | `@AIFeatureFlag` + `@AILocked` | **Warning**: contradictory — locked freezes code; feature flag implies conditional execution |

- | `@AIFeatureFlag` + `@AIContext` | Flag-gated code with guidance on how to manage the flag lifecycle |

- | `@AISecure` + `@AIIgnore` | **Warning**: contradictory — `@AIIgnore` hides the element; `@AISecure` requires AI visibility for security review |

- | `@AISecure` + `@AIAudit` | Security-critical code that must also be audited on every change |

- | `@AISecure` + `@AIPrivacy` | Security-critical PII handler — must not be weakened AND values must never leak |

- | `@AISecure` + `@AICore` | Core security logic — treat all changes with extreme caution AND flag for security review |

- | `@AISandboxOnly` + `@AIDomainModel` | **Warning**: contradictory — sandbox mocks should not be subjected to framework-free domain model constraints |

- | `@AISunset` + `@AIDraft` | **Warning**: contradictory — sunset elements must not be actively drafted or expanded |

- | `@AISecureLogging` + `@AIIgnore` | **Warning**: redundant — `@AIIgnore` already completely excludes this element |

- | `@AIMemoryBudget` + `@AIPerformance` | Enforce zero-allocation along with O(1) latency constraints on hot-path logic |

- | `@AIPure` + `@AIMemoryBudget` | Enforce deterministic pure functions that have a zero allocation footprint |

- | `@AIExplain` + `@AICore` | Core sensitive logic requiring high-fidelity Sequence/Class diagrams for any modification |

-

- ---

-

- ## Granular Rules

-

- When the granular rule directories exist, VibeTags generates **one rule file per annotated class** instead of a single monolithic config file. Each rule file is automatically scoped to its class (e.g., `**/OrderService.java`). Orphaned files for classes that lose their annotations are cleaned up automatically.

-

- | Directory | Platform | Format |

- |---|---|---|

- | `.claude/rules/*.md` | Claude Code | YAML front-matter (`paths:`) + Markdown |

- | `.github/instructions/*.instructions.md` | GitHub Copilot | YAML front-matter (`applyTo:`) + Markdown |

- | `.cursor/rules/*.mdc` | Cursor | YAML front-matter + Markdown |

- | `.windsurf/rules/*.md` | Devin Desktop, formerly Windsurf (fallback directory) | YAML front-matter + Markdown |

- | `.devin/rules/*.md` | Devin Desktop (preferred directory) | YAML front-matter (`trigger: glob`) + Markdown |

- | `.trae/rules/*.md` | Trae IDE | YAML front-matter + Markdown |

- | `.roo/rules/*.md`, `.rooignore` | Zoo Code (fork of the retired Roo Code; reads the same paths) | Markdown |

- | `.continue/rules/*.md` | Continue | YAML front-matter + Markdown |

- | `.tabnine/guidelines/*.md` | Tabnine | Markdown |

- | `.amazonq/rules/*.md` | Amazon Q (deprecated) | Markdown |

- | `.ai/rules/*.md` | Universal AI standard (deprecated) | Markdown |

- | `.pearai/rules/*.md` | PearAI (deprecated) | YAML front-matter + Markdown |

- | `.kiro/steering/*.md` | Amazon Kiro | Markdown |

- | `.grok/rules/*.md` | Grok Build | Markdown |

- | `.agents/rules/*.md` | Antigravity | Markdown |

- | `.aiassistant/rules/*.md` | JetBrains AI Assistant | Markdown |

- | `.augment/rules/*.md` | Augment Code | Markdown |

-

- Enable by creating the directories:

- ```bash

- mkdir -p .cursor/rules .devin/rules .trae/rules .roo/rules

- mkdir -p .continue/rules .tabnine/guidelines

- mkdir -p .kiro/steering .grok/rules

- mkdir -p .agents/rules .aiassistant/rules .augment/rules

- mkdir -p .claude/rules .github/instructions

- ```

-

- ---

-

- ## Transitive Guardrails — rules that arrive from a dependency

-

- An agent working in an application reads *that* application's `CLAUDE.md`, never the one belonging

- to a library it depends on. A library can publish its package-level guardrails, and any project

- that opts in renders them into its own AI configuration.

-

- Both halves are file-presence opt-ins, like everything else here. Neither file exists by default.

-

- **Publishing (the library).** Annotate `package-info.java`, then add `.vibetags-manifest`:

-

- ```java

- // src/main/java/com/acme/crypto/api/package-info.java

- @AISecure(aspect = "Never construct a raw Cipher; go through CryptoManagerFactory.")

- @AIThreadSafe(strategy = AIThreadSafe.Strategy.IMMUTABLE,

- note = "Every product of the factory is safe to share between threads.")

- package com.acme.crypto.api;

-

- import se.deversity.vibetags.annotations.AISecure;

- import se.deversity.vibetags.annotations.AIThreadSafe;

- ```

-

- ```bash

- # first non-comment line is the coordinate consumers will see

- echo "com.acme:crypto-core:2.4.0" > .vibetags-manifest

- ```

-

- The build writes `vibetags/manifests/com.acme.crypto.api.json` into the class output and the normal

- `jar` task packages it. (Not `META-INF/` — javac's `CLASS_PATH` location skips archive directories

- whose names are not valid package identifiers, so a manifest there is unreadable from a processor.)

-

- **Consuming (the application).**

-

- ```bash

- touch .vibetags-transitive

- ```

-

- ```markdown

- <!-- appended to CLAUDE.md, after everything your own code declares -->

- ## Inherited Guardrails (dependencies)

-

- - `com.acme.crypto.api` (from com.acme:crypto-core:2.4.0)

- - @AISecure: aspect=Never construct a raw Cipher; go through CryptoManagerFactory.

-

- ## Inherited Context (dependencies)

-

- - `com.acme.crypto.api` (from com.acme:crypto-core:2.4.0)

- - @AIThreadSafe: strategy=IMMUTABLE; note=Every product of the factory is safe to share between threads.

- ```

-

- Worth knowing:

-

- - **The project's own rules come first, always.** The inherited block is appended last. That

- ordering *is* the precedence model — the output is prose an agent reads, not a ruleset a compiler

- applies, so a library cannot outrank the project consuming it.

- - **Every inherited rule names its artifact**, because a dependency is contributing text an agent

- will act on and the reader has to see whose text it is.

- - **Only packages the compilation imports are looked up**, so a hundred instrumented dependencies

- do not become a hundred pages of prompt. `-Avibetags.manifest.max=<n>` caps the advisory tier

- further; the six safety buckets are never dropped, and a cap that drops anything says so.

- - **Only package-level annotations travel.** Class- and method-level guardrails stay local — a

- consumer cannot act on a rule about a class it never sees. Thirteen annotations accept

- `ElementType.PACKAGE`: `@AISecure`, `@AIPrivacy`, `@AICore`, `@AIAudit`, `@AIRegulation`,

- `@AIArchitecture`, `@AIPublicAPI`, `@AIBannedApi`, `@AIThreadSafe`, `@AIImmutable`,

- `@AIDeprecated`, `@AIContext`, `@AIStrictClasspath`.

- - **kapt, ECJ and JPMS need a hand.** Discovery needs the compiler's Tree API and the classpath;

- where either is missing VibeTags reports a `NOTE` rather than pretending it found nothing, and

- the manifests are supplied with `-Avibetags.manifest.dir=<dir>` or

- `-Avibetags.manifest.packages=a.b,c.d`. Plain Gradle needs none of that.

- - **Markers are resolved against `-Avibetags.root`.** A build that pins the root at a module

- directory needs `.vibetags-transitive` in that directory, not only at the reactor root.

-

- ---

-

- ## Advanced Configuration

-

- ### Processor options (Maven)

-

- ```xml

- <plugin>

- <groupId>org.apache.maven.plugins</groupId>

- <artifactId>maven-compiler-plugin</artifactId>

- <configuration>

- <compilerArgs>

- <!-- Set project name in llms.txt / llms-full.txt H1 -->

- <arg>-Avibetags.project=MyProjectName</arg>

- <!-- Custom log path (relative to project root or absolute) -->

- <arg>-Avibetags.log.path=logs/vibetags.log</arg>

- <!-- Log level: TRACE, DEBUG, INFO, WARN, ERROR, OFF -->

- <arg>-Avibetags.log.level=DEBUG</arg>

- <!-- Override output root directory (every module of a reactor needs this) -->

- <arg>-Avibetags.root=${maven.multiModuleProjectDirectory}</arg>

- <!-- Name this module explicitly, if it cannot be read off the compiled sources -->

- <arg>-Avibetags.module=payments-core</arg>

- <!-- CI: verify the committed files match the annotations instead of writing them -->

- <arg>-Avibetags.check=true</arg>

- <!-- Opt-in enforcement: fail the build on a guarded signature change -->

- <arg>-Avibetags.enforce=locked,contract,publicapi</arg>

- <!-- Transitive: coordinate published in this library's manifests -->

- <arg>-Avibetags.manifest.origin=com.acme:crypto-core:2.4.0</arg>

- <!-- Transitive: read manifests from a directory (kapt/ECJ/JPMS fallback) -->

- <arg>-Avibetags.manifest.dir=build/vibetags-manifests</arg>

- <!-- Transitive: look up these packages explicitly, when imports cannot be read -->

- <arg>-Avibetags.manifest.packages=com.acme.crypto.api,com.acme.audit</arg>

- <!-- Transitive: cap inherited advisory rules (safety buckets are never dropped) -->

- <arg>-Avibetags.manifest.max=50</arg>

- </compilerArgs>

- </configuration>

- </plugin>

- ```

-

- ### Enforcing mode (opt-in)

-

- Guardrails are advisory by default: they go into the agent's context so a mistake is less likely.

- For the families whose promise can be *proved* from the compiler's model, `-Avibetags.enforce` turns

- that into a hard stop.

-

- ```bash

- mvn compile -Avibetags.baseline.update=true # record and commit .vibetags-baseline

- mvn compile -Avibetags.enforce=contract # thereafter, a signature change fails the build

- ```

-

- | Family | What it checks |

- |---|---|

- | `locked` | An `@AILocked` element's visible shape is unchanged |

- | `contract` | An `@AIContract` signature is unchanged — name, parameters, return type, checked exceptions |

- | `publicapi` | Ditto for `@AIPublicAPI` |

- | `all` | All of the above |

-

- Method bodies, comments and formatting are invisible to it, so reformatting a locked file is not a

- violation. `@AICallersOnly`, `@AIStrictClasspath`, `@AIThreadSafe` and `@AITestDriven` are **not**

- enforceable — proving them needs call-graph or body analysis a processor cannot do portably — and

- naming one is reported rather than silently ignored. An intended change is approved by re-running

- with `-Avibetags.baseline.update=true` and committing the diff, so it gets reviewed.

-

- ### Processor options (Gradle)

-

- ```groovy

- tasks.withType(JavaCompile) {

- options.compilerArgs += [

- '-Avibetags.project=MyProjectName',

- '-Avibetags.log.path=logs/vibetags.log',

- '-Avibetags.log.level=DEBUG'

- ]

- }

- ```

-

- ---

-

- ## Diagnosing Issues

-

- | Symptom | Cause | Fix |

- |---|---|---|

- | Green build, no `VibeTags:` line in the compile log at all | The processor never ran: only `vibetags-annotations` is wired up, or JDK 23+ ignored a class-path processor | Put `vibetags-processor` on `annotationProcessorPaths` / the `annotationProcessor` configuration (step 1) |

- | Green build, files generated, but not in your project | `VibeTags: Root resolved:` points somewhere else: a Gradle worker, kapt, or an IDE compile | Set `-Avibetags.root` (step 2) |

- | `cannot find symbol: class AILocked` | `vibetags-annotations` is missing from the compile classpath | Add it as an ordinary dependency (step 1) |

- | Nothing changed after creating a platform file | An incremental build with no changed sources never starts `javac` | `mvn clean compile`, or touch a source file |

- | `[NOTE] AGENTS.md left untouched because other AI config files are present` | Working as designed: `AGENTS.md` is managed only when it is the sole AI config file | Paste a `VIBETAGS-START`/`VIBETAGS-END` pair into it to have it managed; otherwise ignore (see step 3) |

- | `error: cannot find symbol` … `symbol: method value()` on an `@AI*` annotation | Positional shorthand used on an annotation that has no `value()` element | Use named elements: `@AILocked(reason = "…")`; see the [Element cheat sheet](#element-cheat-sheet--read-this-before-your-first-annotation) |

- | `[WARNING] VibeTags: unrecognized option 'vibetags.…'` | Typo in a `-A` option name | The message lists every supported option; fix the spelling |

- | No files updated after compile | Target files don't exist | `touch CLAUDE.md` (or whichever platform file) then recompile |

- | `[NOTE] No AI config files found` | No opt-in files present | Create one or more platform files (see step 2) |

- | A module's guardrails are missing from the reactor root | That module never reached the root | Give it `-Avibetags.root=<reactor>`; VibeTags warns with *"generated its guardrails as its own root"* when it can tell |

- | `[WARNING] … rewritten with a completely different set of elements` | A compilation replaced a module's guardrails with an unrelated set | Almost always a round that could not see the sources it should have — check this module's annotation processing before committing the regenerated files |

- | `[WARNING] removed N scoped rule file(s) … while writing only M` | The build deleted more guardrails than it produced | Same cause; do not accept the deletion until you know why |

- | `[WARNING] could not identify the compiling module` | Sources are not under `-Avibetags.root` | Set `-Avibetags.root`, or name it with `-Avibetags.module=<name>` |

- | Guardrails differ between `mvn compile` and `mvn test` | Pre-1.0.1-RC8 processor | Upgrade — `compile` and `test-compile` now own separate sidecars |

- | Gradle appends a second set of `VIBETAGS-MODULE` regions | Pre-1.0.1-RC8 processor | Upgrade, then delete the stray `.vibetags-mod-<hash>` file once |

- | `[WARNING] @AIIgnore used but .cursorignore is missing` | Orphaned annotation | Create the missing file to fully support that platform |

- | `[WARNING] contradictory @AIDraft and @AILocked` | Both annotations on same element | Remove one of them |

- | `[WARNING] @AIAudit has no checkFor items` | Empty `checkFor` array | Add at least one vulnerability string |

- | `[WARNING] contradictory @AIContract and @AIDraft` | Both annotations on same element | Remove one — a frozen signature can't also need drafting |

- | `[WARNING] overlapping @AIContract and @AILocked` | Both annotations on same element | Use only `@AILocked` if no changes at all are intended |

- | `[WARNING] contradictory @AITestDriven and @AIIgnore` | Both annotations on same element | Remove one — `@AIIgnore` excludes the element entirely |

- | `[WARNING] contradictory @AITestDriven and @AILocked` | Both annotations on same element | Remove one — `@AILocked` prohibits all changes |

- | `[WARNING] @AITestDriven has invalid coverageGoal` | `coverageGoal` outside 0–100 | Set a value between 0 and 100 (inclusive) |

- | `[WARNING] @AIImmutable on … but field … is not final` | Non-final, non-static field on `@AIImmutable` class | Make the field `final`, or drop `@AIImmutable` |

- | `[WARNING] contradictory @AIDeprecated and @AILocked` | Both annotations on same element | Pick one — locked preserves, deprecated routes callers away |

- | `[WARNING] @AIThreadSafe(IMMUTABLE) and @AIImmutable` | Both annotations on same type | Use `@AIImmutable` alone — immutability already implies thread-safety |

- | `[WARNING] @AIObservability declares no metrics, traces, or logs` | Empty annotation | Add at least one `metrics`/`traces`/`logs` entry |

- | `[WARNING] @AIRegulation has a blank 'standard'` | Required `standard` is empty/whitespace | Name the standard (e.g., `"GDPR"`, `"PCI-DSS"`) |

- | `[WARNING] contradictory @AIIdempotent and @AIDraft` | Both annotations on same element | Remove one — idempotent declares a stable contract; draft implies it's unfinished |

- | `[WARNING] contradictory @AIFeatureFlag and @AILocked` | Both annotations on same element | Remove one — locked freezes; feature flag implies conditional execution |

- | `[WARNING] @AIFeatureFlag has no flag key` | Blank `flag` attribute | Set the flag key (e.g., `flag = "checkout.new-flow"`) |

- | `[WARNING] @AISecure has no aspect` | Blank `aspect` attribute | Specify the security concern (e.g., `aspect = "authentication"`) |

- | `[WARNING] contradictory @AISecure and @AIIgnore` | Both annotations on same element | Remove `@AIIgnore` — security-critical code must remain visible to AI for review |

- | `[WARNING] contradictory @AISandboxOnly and @AIDomainModel` | Both annotations on same element | Sandbox mocks should not be subjected to framework-free domain model constraints |

- | `[WARNING] contradictory @AISunset and @AIDraft` | Both annotations on same element | Sunset elements must not be actively drafted or expanded |

- | `[WARNING] redundant @AISecureLogging and @AIIgnore` | Both annotations on same element | `@AIIgnore` already completely excludes this element; `@AISecureLogging` is redundant |

- | `[WARNING] @AISunset has a blank 'jira'` | Blank `jira` attribute | Specify the JIRA issue ticket key (e.g., `jira = "DEBT-123"`) |

- | `[WARNING] @AITemporary has a blank 'expiresOn'` | Blank `expiresOn` attribute | Specify an ISO date (`expiresOn = "YYYY-MM-DD"`) |

- | `[WARNING] @AITemporary has an invalid 'expiresOn' date format` | Format not YYYY-MM-DD | Use strict `YYYY-MM-DD` syntax (e.g., `"2026-06-30"`) |

- | `[WARNING] Temporary logic in … has expired` | Current date is past `expiresOn` | The temporary hotfix/hack has expired; clean it up immediately |

- | `[WARNING] @AIArchitecture has a blank 'belongsTo'` | Blank `belongsTo` layer | Specify the layer name (e.g., `belongsTo = "domain"`) |

-

- ---

- ## Supported Output Files

- | File(s) | Platform |

- | `CLAUDE.md`, `.claudeignore` (deprecated) | Claude / Claude Code |

- | `CLAUDE.local.md` | Claude Code (local override) |

- | `.claude/rules/*.md` | Claude Code (granular per-class rules) |

- | `.claude/skills/vibetags-guardrails/SKILL.md` | Claude Code (Skill) |

- | `.cursorrules`, `.cursorignore` | Cursor (traditional) |

- | `.cursor/rules/*.mdc` | Cursor (granular per-class rules) |

- | `.windsurfrules` | Devin Desktop, formerly Windsurf (traditional, legacy) |

- | `.windsurf/rules/*.md` | Devin Desktop, formerly Windsurf (granular per-class rules, fallback directory) |

- | `.devin/rules/*.md` | Devin Desktop (granular per-class rules, preferred directory, `trigger: glob`) |

- | `.devin/rules/+vibetags-safety.md`, `.windsurf/rules/+vibetags-safety.md` | Devin Desktop (written with each directory: the always-on safety tier, `trigger: always_on`) |

- | `.devinignore` | Devin Desktop (exclusion list) |

- | `.trae/rules/*.md` | Trae IDE (granular per-class rules) |

- | `CONVENTIONS.md`, `.aider.conf.yml`, `.aiderignore` | Aider |

- | `.roo/rules/*.md`, `.rooignore` | Zoo Code (fork of the retired Roo Code; reads the same paths) |

- | `CONVENTIONS.md`, `.aiderignore` | Aider |

- | `QWEN.md`, `.qwen/commands/refactor.md`, `.qwenignore` | Qwen |

- | `GEMINI.md`, `.aiexclude`, `gemini_instructions.md` (deprecated) | Gemini |

- | `.gemini/styleguide.md` | Gemini Code Assist (GitHub PR reviewer) |

- | `.greptile/rules.md` | Greptile (AI PR reviewer) |

- | `.greptile/config.json` | Greptile (`@AIIgnore` paths; VibeTags owns only a span inside `ignorePatterns`) |

- | `greptile.json` | Greptile (legacy form; VibeTags owns only a span inside `instructions` and `ignorePatterns`) |

- | `.antigravityignore` | Antigravity AI (deprecated) |

- | `AGENTS.md`, `.codex/config.toml`, `.codex/rules/` | Codex CLI |

- | `.github/copilot-instructions.md`, `.copilotignore` (deprecated) | GitHub Copilot |

- | `.github/instructions/*.instructions.md` | GitHub Copilot (granular per-class rules) |

- | `.rules` | Zed Editor |

- | `.cody/config.json`, `.codyignore` (deprecated) | Sourcegraph Cody |

- | `.supermavenignore` (deprecated) | Supermaven |

- | `.continue/rules/*.md` | Continue (granular per-class rules) |

- | `.tabnine/guidelines/*.md` | Tabnine (granular per-class rules) |

- | `.amazonq/rules/*.md` | Amazon Q (granular per-class rules; deprecated) |

- | `.ai/rules/*.md` | Universal AI standard (granular; deprecated) |

- | `llms.txt` | Windsurf Cascade / all LLM agents |

- | `llms-full.txt` | Large-context LLMs (Claude, Gemini) |

- | `.pearai/rules/*.md` | PearAI (granular per-class rules; deprecated) |

- | `.mentatconfig.json` | Mentat (deprecated) |

- | `sweep.yaml` | Sweep (GitHub App; deprecated) |

- | `.plandex.yaml` | Plandex (deprecated) |

- | `.doubleignore` | Double.bot (deprecated) |

- | `.interpreter/profiles/vibetags.yaml` | Open Interpreter (deprecated) |

- | `.codeiumignore` | Codeium (Devin Desktop reads it under this legacy name) |

- | `.clinerules` (deprecated) | Cline AI assistant (single file) |

- | `.clinerules/*.md` | Cline AI assistant (granular per-class rules, `paths:` front matter; same path as the file, so a project has one or the other) |

- | `.clinerules/+vibetags-safety.md` | Cline AI assistant (written with the directory: the always-loaded safety tier, no front matter) |

- | `.junie/AGENTS.md` | JetBrains Junie (checked first; not the root `AGENTS.md`) |

- | `.junie/guidelines.md` | JetBrains Junie (legacy, still supported) |

- | `.kiro/steering/*.md` | Amazon Kiro (granular per-class rules) |

- | `.grok/rules/*.md` | Grok Build (granular per-class rules) |

- | `.agents/rules/*.md` | Antigravity (granular per-class rules) |

- | `.aiassistant/rules/*.md` | JetBrains AI Assistant (granular per-class rules) |

- | `.augment/rules/*.md` | Augment Code (granular per-class rules) |

- | `.goosehints` | goose (Block) |

- | `DESIGN.md` | AI design agents (Cursor, Claude, Copilot, etc.) |

- | `.void/rules.md` | Void Editor (deprecated) |

- | `.coderabbit.yaml` | CodeRabbit (AI PR reviewer) |

- | `.pr_agent.toml` | Qodo/Codium PR-Agent (AI PR reviewer) |

- | `ellipsis.yaml` | Ellipsis (AI PR reviewer; deprecated) |

- | `.roomodes` | Zoo Code (fork of the retired Roo Code; reads the same paths), "VibeTags Architect" custom mode |

- | `.repomixignore` | Repomix (context packer) |

- | `.gitingestignore` | Gitingest (context packer) |

- | `.gptignore` | GPT context packer |

- | `.ghostcoderignore` | Ghostcoder (deprecated) |

- | `.piecesignore` | Pieces for Developers (deprecated) |