chore: add GitHub skills and instruction files for support-query-builder (#427)

Agent-Logs-Url: https://github.com/AniTrend/support-query-builder/sessions/c14fa43e-3fed-457b-bae3-9b152f630d4e

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: wax911 <7859175+wax911@users.noreply.github.com>

Author: Copilot

.github/instructions/build-logic.instructions.md

@@ -0,0 +1,17 @@
+---
+description: Use when editing Gradle files, module dependencies, version catalog entries, GitHub workflows, or buildSrc logic in support-query-builder.
+applyTo: build.gradle.kts, settings.gradle.kts, gradle/**/*.toml, buildSrc/**/*.kt, */build.gradle.kts, .github/workflows/*.yml
+---
+
+# Build Logic Guidance
+
+- Prefer the shared `co.anitrend.support.query.builder.plugin` plugin and `buildSrc` helpers over duplicating Android, Kotlin, Spotless, publishing, or test configuration in individual modules.
+- The pinned Java and Kotlin toolchain is 21. Keep new build logic compatible with `.java-version` (set to `21.0.8`) and the shared Android configuration. Systems are expected to have `jenv` installed; the `.java-version` file is what `jenv local` reads to align the active JDK.
+- Add or update dependency versions in `gradle/libs.versions.toml` first, then reference the alias from modules or build logic.
+- Keep module dependency changes aligned with the existing graph: `:core` and `:annotations` are JVM-only with no project dependencies; `:core:ext` depends only on `:core`; `:processor` depends only on `:annotations`.
+- `:annotations` and `:core` and `:processor` are classified as Kotlin library group (JVM-only, no Android plugin). `:core:ext` is an Android library. `:sample` is an Android application excluded from CI.
+- Shared Android defaults come from `buildSrc/.../ProjectConfiguration.kt`, including `compileSdk = 35`, `minSdk = 23`, `targetSdk = 35`, Java 21 compatibility, and `JvmTarget.JVM_21`.
+- Shared formatting comes from `buildSrc/.../ProjectSpotless.kt` and the license header file under `spotless/copyright.kt`.
+- Shared publishing behavior comes from `buildSrc/.../ProjectMaven.kt`; all published artifacts use the group `co.anitrend.query.builder` and are distributed via JitPack.
+- If you need a new convention across many modules, prefer adding it once in `buildSrc` instead of repeating it in each `build.gradle.kts` file.
+- When validating Gradle changes locally, pair the work with the existing `jenv-gradle-low-ram` skill if JDK alignment or memory pressure becomes a problem.

.github/instructions/context-maintenance.instructions.md

@@ -0,0 +1,16 @@
+---
+description: Use when making architecture changes, module graph changes, package ownership changes, public API shifts, build logic updates, or editing repository customizations in support-query-builder. Keeps instructions, skills, and consumer-facing context aligned with current repository behavior.
+applyTo: build.gradle.kts, settings.gradle.kts, gradle/**/*.toml, buildSrc/**/*.kt, */build.gradle.kts, */src/main/**/*.kt, .github/instructions/*.md, .github/skills/**, README.md
+---
+
+# Context Maintenance Guidance
+
+- When a change materially alters repository reality, update the relevant repo guidance in the same patch instead of leaving instructions and skills stale.
+- Treat the following as context-bearing assets that may need maintenance after major changes: `.github/instructions/*.md`, `.github/skills/**`, and `README.md`.
+- Audit repo guidance when you change module boundaries, dependency direction, package ownership, shared build conventions, or consumer-facing extension points.
+- Audit the reference-map and build-dependencies skills when a module gains a new responsibility, a new package root becomes important, or the build and publishing workflow changes.
+- Remove or rewrite contradictory guidance instead of layering new instructions on top of obsolete ones.
+- Prefer updating an existing instruction or skill when the workflow still fits; add a new instruction or skill only when a genuinely new recurring concern appears.
+- Keep changes specific and low-churn: update only the files whose guidance is no longer true.
+- If a change affects how downstream apps should discover, import, or configure support-query-builder APIs, update the relevant consumer-facing guidance in the same change.
+- If repository memory is available, record durable repo facts after significant architectural or workflow changes so future tasks start with current context.

.github/instructions/context.instructions.md

@@ -1,89 +1,56 @@
 ---
 applyTo: **
-description: This file describes the architecture and module structure of the support-query-builder project.
+description: Use when understanding support-query-builder architecture, module boundaries, consumer-facing APIs, annotation processing, Room integration, or shared Gradle/buildSrc behavior.
 ---
 
-# Support Query Builder Architecture
+# Support Query Builder Context
 
-The support-query-builder project is a Kotlin library that provides a fluent SQL query builder with annotation processing capabilities for Android Room database integration. Its design goal is to generate type-safe SQL queries dynamically while maintaining compile-time verification through annotation processing.
+- `support-query-builder` is a reusable Kotlin library, not an app. Favor reusable abstractions, extension points, and stable consumer-facing APIs over app-specific behavior.
+- The library's primary purpose is to provide a fluent, type-safe SQL query builder that integrates with Android Room via generated schema objects and `SupportSQLiteQuery`.
+- Treat the published Dokka site as part of the product surface: `https://anitrend.github.io/support-query-builder/`.
 
-## Module Structure
+## Module Groups
 
-The project is organized into distinct Gradle modules, each with specific responsibilities:
+- Core JVM modules: `:annotations`, `:core`, `:processor`
+- Android integration module: `:core:ext`
+- Development-only module: `:sample` (excluded from CI via `settings.gradle.kts`)
 
-### Core Modules
-- **`:core`** - The main query builder library containing the core SQL query construction logic. This module provides the fluent builder API with support for complex queries including joins, unions, and chaining operations. It contains no Android-specific dependencies, making it a pure Kotlin library that can be used in any JVM environment.
-- **`:core:ext`** - Extension functions for the core module, primarily providing integration with Android Room's `SupportSQLiteQuery`. The main function `asSupportSQLiteQuery()` converts query builder instances to Room-compatible query objects.
+## Dependency Direction
 
-### Annotation Processing
-- **`:annotations`** - Contains the annotation definitions used to mark Room entities for processing. This module is dependency-free and only defines the annotations that other modules consume.
-- **`:processor`** - Kotlin annotation processor (KAPT) that inspects Room entity annotations (`@Entity`, `@ColumnInfo`, `@Embedded`) and generates corresponding schema object classes. These generated objects mirror the entity structure and provide type-safe column references for the query builder.
+- `:annotations` is a JVM-only API module with no project dependencies. It only defines the `@EntitySchema` annotation and is the lowest layer.
+- `:core` is a pure JVM Kotlin module with no project dependencies. It owns the entire query builder API surface: `QueryBuilder`, `AbstractQueryBuilder`, `IQueryBuilder`, `Criteria`, `From`, `Order`, `Projection`, and their DSL helpers.
+- `:core:ext` is an Android library that depends on `:core`. It bridges the query builder to Room's `SupportSQLiteQuery` via extension functions.
+- `:processor` is a JVM KAPT module that depends on `:annotations`. It reads Room entity annotations and generates schema object classes using KotlinPoet and `auto-service`.
+- `:sample` depends on everything and is an Android application used for local development only.
+- Avoid introducing new dependencies that cause lower modules to depend on higher-layer ones.
 
-### Development and Testing
-- **`:sample`** - Example application demonstrating library usage. This module is excluded from CI builds but serves as a practical reference for integration patterns and usage examples.
+## Package Expectations
 
-## Architecture Principles
+- `:annotations` exposes `co.anitrend.support.query.builder.annotation` — the `@EntitySchema` annotation.
+- `:core` exposes `contract/`, `criteria/`, `from/`, `order/`, `projection/`, and the top-level `QueryBuilder` and `dsl/` entrypoints.
+- `:core:ext` exposes `co.anitrend.support.query.builder.core.ext` — the `asSupportSQLiteQuery()` extension and related Room helpers.
+- `:processor` exposes `extensions/`, `factory/`, `logger/`, and `model/` under `co.anitrend.support.query.builder.processor`. The `EntitySchemaProcessor` is the KAPT entry point.
 
-### Type Safety
-The library emphasizes compile-time type safety through:
-- Generated schema objects that mirror Room entity definitions
-- Fluent builder API that prevents malformed SQL construction
-- Extension functions that seamlessly integrate with Room's type system
+## Build And Tooling Facts
 
-### Room Integration
-The library is designed specifically for Room database integration:
-- Annotation processor reads Room entity annotations directly
-- Generated queries are compatible with Room's `@RawQuery` annotation
-- Support for Room's `SupportSQLiteQuery` interface through extension functions
+- All modules apply the shared `co.anitrend.support.query.builder.plugin` Gradle plugin from `buildSrc`.
+- Shared Android defaults live in `buildSrc/.../ProjectConfiguration.kt`: `compileSdk = 35`, `minSdk = 23`, `targetSdk = 35`, Java 21 source/target compatibility, and `JvmTarget.JVM_21` for Kotlin.
+- The repo Java pin is `.java-version = 21.0.8`. Systems are expected to have `jenv` installed; `.java-version` is picked up by `jenv local` to set the active JDK automatically. `buildSrc/.../ProjectConfiguration.kt` must stay aligned: `JavaVersion.VERSION_21` for Java source/target compatibility and `JvmTarget.JVM_21` for Kotlin must both match the `.java-version` major version (21).
+- Kotlin library group (JVM-only, no Android plugin): `:annotations`, `:core`, `:processor`. All other non-sample modules are Android libraries.
+- Dependency versions belong in `gradle/libs.versions.toml` before they are referenced from module build files.
+- Spotless and ktlint are enforced centrally via `buildSrc/.../ProjectSpotless.kt`, with the license header sourced from `spotless/copyright.kt`.
+- Publishing is configured centrally in `buildSrc/.../ProjectMaven.kt`; artifacts are distributed through JitPack under group `co.anitrend.query.builder`.
 
-### Modularity
-The multi-module approach ensures:
-- Core logic is separate from Android-specific integrations
-- Annotation processing is isolated for clean build dependencies
-- Extensions can be optionally included based on project needs
+## Documentation Contract
 
-## Build System
+- Dokka is configured centrally and the published site documents the public API surface.
+- When changing public behavior, update KDoc in the same change.
+- Document what the API does, when to use it, and what a consumer must provide or expect.
 
-The project uses Gradle with Kotlin DSL and includes:
-- Custom build plugins in `buildSrc` for consistent configuration
-- Android library configuration for Room compatibility
-- Annotation processor configuration for code generation
-- JitPack integration for distribution
+## Working Heuristics
 
-## Key Components
-
-### Query Builder Core
-The core module provides a fluent API for constructing SQL SELECT queries with support for:
-- Table selection and aliasing
-- Column projection with type safety
-- JOIN operations (INNER, LEFT, RIGHT, FULL)
-- WHERE clause construction with parameter binding
-- GROUP BY and HAVING clauses
-- ORDER BY with multiple columns
-- UNION and UNION ALL operations
-- Subquery support
-
-### Schema Generation
-The annotation processor generates Kotlin object classes that:
-- Mirror Room entity class structure
-- Provide compile-time column name verification
-- Support nested objects for `@Embedded` annotations
-- Generate table metadata for query construction
-
-### Room Extensions
-Extension functions bridge the query builder with Room:
-- Convert builder instances to `SupportSQLiteQuery`
-- Handle parameter binding for dynamic queries
-- Maintain compatibility with Room's query execution model
-
-## Documentation
-
-Full documentation is available at: https://anitrend.github.io/support-query-builder/
-
-The documentation includes:
-- API reference for all public classes and methods
-- Integration guides for Room database usage
-- Examples of complex query construction
-- Best practices for annotation processor usage
-
-This modular architecture ensures the library remains focused on its core purpose while providing flexible integration options for different use cases and maintaining compatibility with the Android ecosystem.
+- Put new query builder logic in `:core` if it has no Android dependency; put Room-specific glue in `:core:ext`.
+- Annotation additions go in `:annotations` first; corresponding processor changes go in `:processor` in the same change.
+- Prefer shared build logic changes in `buildSrc` over copy-pasting Gradle configuration into individual modules.
+- When running Gradle locally, use the `jenv-gradle-low-ram` skill to align the JDK and manage memory pressure before invoking `./gradlew`.
+- When unsure where code belongs, consult the dependency direction above and confirm it before editing.

.github/instructions/kdoc-dokka.instructions.md

@@ -0,0 +1,19 @@
+---
+description: Use when adding or changing public Kotlin APIs, KDoc, Dokka output, class docs, function docs, or property docs in support-query-builder modules.
+applyTo: annotations/src/main/**/*.kt, core/src/main/**/*.kt, core/ext/src/main/**/*.kt, processor/src/main/**/*.kt
+---
+
+# KDoc And Dokka Guidance
+
+- Treat KDoc as consumer documentation. The generated Dokka site is how downstream apps learn the library surface.
+- Document every new or changed public or protected class, interface, object, enum, annotation, function, and property that a consumer may touch.
+- Write documentation for someone outside this repo who does not already know the architecture. Explain what the API is for, when to use it, and which module or workflow it belongs to.
+- For abstract base types such as `AbstractQueryBuilder`, document the extension contract: what subclasses must override, invariants they must preserve, and when callbacks are invoked.
+- For builder types and DSL functions, document the expected call sequence, which methods are required vs optional, and how the final query is materialized.
+- For extension functions such as `asSupportSQLiteQuery()`, document the receiver, side effects, threading or lifecycle assumptions, and any important nullability or mutation behavior.
+- For annotation types such as `@EntitySchema`, document which annotation processor reads them, what code gets generated, and how the consumer should use the generated output.
+- Preserve the existing house style when possible: a short summary first, then focused detail, with `@param`, `@property`, `@return`, `@throws`, `@see`, and `@since` where they add value.
+- Do not invent version history. Only add `@since` when the version is already known or established in adjacent code.
+- Avoid placeholder KDoc that only restates the type name. Explain behavior, expectations, and integration points.
+- If behavior changes, update the docs in the same patch so the published site stays trustworthy.
+- There are no internal package suppressions in this project; document all public-facing code.

.github/skills/jenv-gradle-low-ram/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: jenv-gradle-low-ram
+description: 'Align jenv with .java-version and run Gradle reliably on low-RAM machines. Use for Java mismatch errors, Gradle OOMs, daemon memory pressure, and selecting safe build flags.'
+argument-hint: 'Describe your target task and available RAM, for example: assembleDebug on 8GB RAM'
+---
+# Jenv + Gradle Low-RAM Workflow
+
+## What This Skill Produces
+
+- A shell where `java` and Gradle use the Java version pinned by `.java-version`.
+- A repeatable Gradle command profile tuned for constrained memory.
+- Verification checks to confirm version alignment and build stability.
+
+## When To Use
+
+- Any time when `./gradlew` is about to be invoked in this repository.
+- Especially important for low-RAM machines where daemon/worker pressure can destabilize builds.
+- Required when verifying that Java from `.java-version` is the active runtime for Gradle.
+
+## Procedure
+
+1. Detect the required Java version.
+
+```bash
+cat .java-version
+```
+
+The expected output is `21.0.8`. Systems in this project are expected to have `jenv` installed; the `.java-version` file is read by `jenv local` to pin the active JDK for the working directory.
+
+2. Verify `jenv` is installed and initialized.
+
+```bash
+command -v jenv
+jenv versions
+jenv version
+```
+
+Decision point:
+
+- If `jenv` is not found, install it from https://github.com/jenv/jenv and run `eval "$(jenv init -)"` in your shell startup, then re-open the shell and retry.
+- If `jenv` is found but `jenv version` does not match `.java-version`, continue to step 3.
+
+3. Align local Java to the repository pin.
+
+```bash
+required_java="$(cat .java-version)"
+jenv local "$required_java"
+```
+
+Decision point:
+
+- If `jenv local` fails because the version is missing, install that JDK and run `jenv add <jdk-path>`, then retry.
+
+4. Confirm runtime alignment before any Gradle task.
+
+```bash
+java -version
+./gradlew -version
+```
+
+Quality check:
+
+- Gradle JVM version in `./gradlew -version` must match `.java-version` major version (21).
+
+5. Run Gradle with low-memory-safe defaults.
+
+Preferred one-off profile for building a debug variant:
+
+```bash
+./gradlew --no-daemon --max-workers=2 \
+  -Dorg.gradle.jvmargs="-Xmx1536m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8" \
+  :core:assembleDebug
+```
+
+For running unit tests:
+
+```bash
+./gradlew --no-daemon --max-workers=2 \
+  -Dorg.gradle.jvmargs="-Xmx1792m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8" \
+  :core:test :processor:test
+```
+
+For running all tests across modules:
+
+```bash
+./gradlew --no-daemon --max-workers=2 \
+  -Dorg.gradle.jvmargs="-Xmx1792m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8" \
+  test
+```
+
+6. If memory pressure continues, downgrade concurrency.
+
+```bash
+./gradlew --no-daemon --max-workers=1 -Dorg.gradle.parallel=false :core:test
+```
+
+7. If builds are stable and you want persistence, prefer user-local Gradle overrides (avoid committing repo-wide memory changes).
+
+Suggested entries for `~/.gradle/gradle.properties`:
+
+```properties
+org.gradle.daemon=false
+org.gradle.parallel=false
+org.gradle.workers.max=2
+org.gradle.jvmargs=-Xmx1536m -XX:MaxMetaspaceSize=512m -Dfile.encoding=UTF-8
+```
+
+## Troubleshooting Branches
+
+- `jenv version` correct but `java -version` wrong:
+  Ensure shell init runs `eval "$(jenv init -)"` and enable export plugin with `jenv enable-plugin export`.
+- `Gradle daemon disappeared unexpectedly`:
+  Retry with `--no-daemon --max-workers=1` and lower `-Xmx` if the OS is reclaiming memory aggressively.
+- Kotlin compile OOM:
+  Keep workers low, disable parallel, and run module-targeted tasks (for example `:core:test` or `:processor:test`) instead of full-project builds.
+- KAPT out of memory (`:processor` module):
+  Add `-Dkapt.use.worker.api=false` to avoid spawning an extra worker process during annotation processing.
+
+## Completion Checks
+
+- `.java-version` and `jenv version` resolve to the same Java release (`21.0.8`).
+- `./gradlew -version` reports the expected JVM (major version 21).
+- Target Gradle task completes without OOM or daemon crash.
+- Machine remains responsive during build (no prolonged swap thrash).
+
+## Fast Invocation Examples
+
+- "Align my shell to `.java-version` and run debug build with 8GB RAM settings"
+- "I get class file major version errors; fix jenv and verify Gradle JVM"
+- "Run unit tests with a low-memory Gradle profile and fallback if OOM occurs"
+- "Run only the processor module tests without spawning extra KAPT workers"