Fix conflicting agent instructions and stale workflow guidance

.claude/agents/code-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: code-reviewer
-description: 'Independent multi-agent code reviewer for Apache Pinot. Spawns 8 domain-specialized sub-reviewers in parallel (config-backcompat, concurrency-state, architecture, performance, correctness-nulls, testing, naming-api, process-scope), aggregates their findings, de-duplicates by (principle, file, line), and produces a consolidated report ranked by severity. Use proactively after writing or modifying code, especially before commits and PRs.\n\n**IMPORTANT — Minimal context rule:** Caller provides ONLY (1) review scope (e.g. "unstaged changes", "branch vs master", specific paths) and (2) a one-line change description. Never pass opinions or analysis — each sub-reviewer forms its judgment independently by reading the code and the principles KB.\n\nExamples:\n<example>\nuser: "I''ve added the new authentication feature. Can you check if everything looks good?"\nassistant: Invokes code-reviewer with prompt: "Review unstaged changes. Change: added authentication feature to broker."\n<commentary>\nMinimal context — just scope and one-line summary. No opinions about the code.\n</commentary>\n</example>\n<example>\nassistant just wrote a utility function and wants to validate it.\nassistant: Invokes code-reviewer with prompt: "Review unstaged changes in pinot-common. Change: added partition ID utility function."\n<commentary>\nProactive review after writing code. No analysis of what might be wrong.\n</commentary>\n</example>\n<example>\nuser: "I think I''m ready to create a PR for this feature"\nassistant: Invokes code-reviewer with prompt: "Review all changes on this branch vs master. Change: new config validation for upsert tables."\n<commentary>\nPre-PR review. Scope is branch diff, description is one line.\n</commentary>\n</example>'
+description: Review Apache Pinot diffs or designs using applicable correctness, compatibility, and safety checks. Delegate substantial independent checks when useful.
 model: inherit
 color: red
 ---

.claude/skills/bench-compare/SKILL.md

@@ -16,7 +16,7 @@
 # specific language governing permissions and limitations
 # under the License.
 name: bench-compare
-description: Run a Pinot JMH benchmark twice — once on a baseline commit, once with the current changes — and report both sets of results side by side. Uses a git worktree so the user's working tree is never disturbed.
+description: Compare baseline and current Pinot JMH benchmark results using an isolated baseline worktree.
 ---
 
 # /bench-compare

.claude/skills/flaky-analyze/SKILL.md

@@ -16,7 +16,7 @@
 # specific language governing permissions and limitations
 # under the License.
 name: flaky-analyze
-description: Pull recent GitHub Actions failures for a Pinot test class and analyze whether they share a root cause. Uses the gh CLI. Surfaces stack traces, failure patterns, and a candidate hypothesis — does not auto-fix.
+description: Investigate intermittent Pinot test failures in GitHub Actions and report evidence and likely causes.
 ---
 
 # /flaky-analyze

.claude/skills/precommit/SKILL.md

@@ -16,7 +16,7 @@
 # specific language governing permissions and limitations
 # under the License.
 name: precommit
-description: Run Pinot's mandatory pre-commit checks (spotless, license, checkstyle) and compiler warning checks on only the modules affected by the current diff. Auto-fixes what it can, reports what it can't.
+description: Validate and fix Pinot pre-commit checks on affected modules before a commit or PR.
 ---
 
 # /precommit

.claude/skills/quickstart/SKILL.md

@@ -16,7 +16,7 @@
 # specific language governing permissions and limitations
 # under the License.
 name: quickstart
-description: Launch a local Pinot quickstart cluster (batch, hybrid, streaming, upsert, etc.) with the right script, building the binary distribution first if needed.
+description: Start and verify a local Pinot quickstart using the modes supported by the current checkout.
 ---
 
 # /quickstart

.claude/skills/review-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-architecture
-description: Review Apache Pinot diffs for architectural concerns — module boundaries, SPI vs. impl separation, circular deps, misplaced logic (broker code in server, server code in controller), abstraction choice (interface vs. abstract class), plugin layering, and layering violations between pinot-spi / pinot-common / pinot-core / pinot-segment-spi / pinot-segment-local. Trigger keywords — new interface, abstract class, package move, module, SPI, broker-server boundary, plugin, shaded.
+description: Review Apache Pinot architecture when module dependencies, SPI boundaries, abstractions, or class placement change.
 domain: kb/code-review-principles.md#3-code-architecture--module-design
 triggers:
   - diff adds/moves classes across module boundaries

.claude/skills/review-concurrency-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-concurrency-state
-description: Review Apache Pinot diffs for concurrency, state management, visibility, atomic state transitions, lock changes, Helix IdealState updates, upsert metadata safety, consumer/stream ingestion races, and shared-observer correctness. Trigger keywords — synchronized, volatile, AtomicReference, ConcurrentHashMap, ReentrantLock, StampedLock, Helix, IdealState, ZkClient, version-checked write, upsert metadata, consumer coordinator, stream partition.
+description: Review Apache Pinot concurrency and state safety when locks, shared callbacks, lifecycle, or distributed metadata change.
 domain: kb/code-review-principles.md#2-state-management--concurrency
 triggers:
   - diff adds/removes synchronized / volatile / Atomic* / lock types

.claude/skills/review-config-backcompat/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-config-backcompat
-description: Review Apache Pinot diffs for configuration and backward-compatibility risks. Covers config key renames, SPI signature changes, schema/enum additions, feature-flag defaults, multi-level config override validation, rolling-upgrade safety, REST/JSON/Protobuf field evolution, and segment/DataTable format versioning. Trigger keywords — config key, config rename, SPI, feature flag, enum, schema type, DataTable version, segment version, Protobuf, Thrift, REST endpoint, @Deprecated, mixed-version, rolling upgrade, ZooKeeper schema.
+description: Review Apache Pinot compatibility when configs, public APIs, SPI contracts, or serialized formats change.
 domain: kb/code-review-principles.md#1-configuration--backward-compatibility
 triggers:
   - diff touches config constants (*ConfigConstants.java, *Config.java)

.claude/skills/review-correctness-nulls/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-correctness-nulls
-description: Review Apache Pinot diffs for correctness issues — null handling, type dispatch, numeric precision (INT/LONG/BIG_DECIMAL), exhaustive switch coverage for DataType / IndexType, resource leaks in close/destroy paths, off-by-one errors in row iteration, and silent wrong-result risks. Trigger keywords — null, Nullable, Optional, getStoredType, DataType switch, IndexType switch, close, destroy, realtime persist, precision, BigDecimal, isNullable, null vector.
+description: Review Apache Pinot correctness when null handling, numeric types, dispatch, or resource lifecycles change.
 domain: kb/code-review-principles.md#5-correctness--safety
 triggers:
   - diff touches null-vector / null-bitmap / null-enabled code paths

.claude/skills/review-naming-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-naming-api
-description: Review Apache Pinot diffs for naming, API design, and public-surface hygiene — method and class names; REST JSON field names; SPI method names; enum constant names (permanent); consistency with existing patterns; fully-qualified class names inline (disallowed); Javadoc on new public classes. Trigger keywords — public API, SPI, REST, @JsonProperty, enum name, class rename, method rename, Javadoc.
+description: Review Apache Pinot naming and API conventions when public names, signatures, or documentation change.
 domain: kb/code-review-principles.md#7-naming--api-design
 triggers:
   - diff adds or renames public classes/methods/fields

.claude/skills/review-performance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-performance
-description: Review Apache Pinot diffs for performance regressions in hot paths — per-row allocations, autoboxing, virtual dispatch in tight loops, large synchronized sections on the query path, unnecessary ByteBuffer copies, string concat in loops, and missing fast-paths for common types. Trigger keywords — TransformOperator, FilterOperator, ForwardIndexReader, segment scan, per-row, query hot path, allocation, autoboxing, JMH, benchmark.
+description: Review Apache Pinot performance when hot paths change or a PR makes benchmark or efficiency claims.
 domain: kb/code-review-principles.md#4-performance--efficiency
 triggers:
   - diff touches pinot-query-runtime/**/operator/**, pinot-core/**/operator/**, transform/aggregation function

.claude/skills/review-process-scope/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-process-scope
-description: Review Apache Pinot diffs for process and scope discipline — PR size, single-concern commits, commit message clarity, referenced issues/PRs on reverts, anti-patterns like "add retry to fix flake", labels (backward-incompat), rolling-upgrade notes, and TODO hygiene. Trigger keywords — revert, retry, flake, TODO, backward-incompat, rolling upgrade, PR description.
+description: Review Apache Pinot change scope and process when assessing PR descriptions, reverts, retries, or compatibility notes.
 domain: kb/code-review-principles.md#8-process--scope
 triggers:
   - diff is > ~500 changed lines or spans > 4 modules

.claude/skills/review-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-testing
-description: Review Apache Pinot diffs for test coverage and test quality — positive + negative cases, real dictionaries vs mocks, rolling-upgrade / mixed-version tests, null-handling toggle coverage, exhaustive type coverage for aggregators/operators, integration-test base-class choice (reject standalone clusters unless special setup is needed; prefer `CustomDataQueryClusterIntegrationTest`), assertion quality, and regression tests that reproduce the bug. Trigger keywords — Test, TestNG, JUnit, Mockito, mock, integration test, assertEquals, assertThrows, regression, null handling test, mixed version, CustomDataQueryClusterIntegrationTest, BaseClusterIntegrationTest.
+description: Review Apache Pinot regression coverage and test quality when behavior or tests change.
 domain: kb/code-review-principles.md#6-testing-strategies
 triggers:
   - diff adds or modifies any src/test/** file

.claude/skills/run-test/SKILL.md

@@ -16,7 +16,7 @@
 # specific language governing permissions and limitations
 # under the License.
 name: run-test
-description: Run a single Pinot JUnit/TestNG test class by name. Auto-detects the owning Maven module and builds the correct ./mvnw invocation, including the integration-test flags when needed.
+description: Run a named Pinot test class or method in its owning Maven module.
 ---
 
 # /run-test

AGENTS.md

@@ -43,72 +43,26 @@ repo. It is intentionally short and focused on day-to-day work.
 - pinot-integration-tests: end-to-end validation suites.
 - pinot-distribution: packaging artifacts.
 
-## pinot-plugins modules
-- pinot-input-format: input format plugin family.
-  - pinot-arrow: Apache Arrow input format support.
-  - pinot-avro: Avro input format support.
-  - pinot-avro-base: shared Avro utilities and base classes.
-  - pinot-bson: MongoDB BSON input format support.
-  - pinot-clp-log: CLP log input format support.
-  - pinot-confluent-avro: Confluent Schema Registry Avro input support.
-  - pinot-confluent-json: Confluent Schema Registry JSON input support.
-  - pinot-confluent-protobuf: Confluent Schema Registry Protobuf input support.
-  - pinot-orc: ORC input format support.
-  - pinot-json: JSON input format support.
-  - pinot-parquet: Parquet input format support.
-  - pinot-csv: CSV input format support.
-  - pinot-thrift: Thrift input format support.
-  - pinot-protobuf: Protobuf input format support.
-- pinot-file-system: filesystem plugin family.
-  - pinot-adls: Azure Data Lake Storage (ADLS) filesystem support.
-  - pinot-hdfs: Hadoop HDFS filesystem support.
-  - pinot-gcs: Google Cloud Storage filesystem support.
-  - pinot-s3: Amazon S3 filesystem support.
-- pinot-batch-ingestion: batch ingestion plugin family.
-  - pinot-batch-ingestion-common: shared batch ingestion APIs and utilities.
-  - pinot-batch-ingestion-spark-base: shared Spark ingestion base classes.
-  - pinot-batch-ingestion-spark-3: Spark 3 ingestion implementation.
-  - pinot-batch-ingestion-hadoop: Hadoop MapReduce ingestion implementation.
-  - pinot-batch-ingestion-standalone: standalone batch ingestion implementation.
-- pinot-stream-ingestion: stream ingestion plugin family.
-  - pinot-kafka-base: shared Kafka ingestion base classes.
-  - pinot-kafka-3.0: Kafka 3.x ingestion implementation.
-  - pinot-kafka-4.0: Kafka 4.x ingestion implementation.
-  - pinot-kinesis: AWS Kinesis ingestion implementation.
-  - pinot-pulsar: Apache Pulsar ingestion implementation.
-- pinot-minion-tasks: minion task plugin family.
-  - pinot-minion-builtin-tasks: built-in minion task implementations.
-- pinot-metrics: metrics reporter plugin family.
-  - pinot-dropwizard: Dropwizard Metrics reporter implementation.
-  - pinot-yammer: Yammer Metrics reporter implementation.
-  - pinot-compound-metrics: compound metrics implementation.
-- pinot-segment-writer: segment writer plugin family.
-  - pinot-segment-writer-file-based: file-based segment writer implementation.
-- pinot-segment-uploader: segment uploader plugin family.
-  - pinot-segment-uploader-default: default segment uploader implementation.
-- pinot-environment: environment provider plugin family.
-  - pinot-azure: Azure environment provider implementation.
-- pinot-timeseries-lang: time series language plugin family.
-  - pinot-timeseries-m3ql: M3QL language plugin implementation.
-- assembly-descriptor: Maven assembly descriptor for plugin packaging.
+When locating a plugin implementation, consult [kb/plugin-modules.md](kb/plugin-modules.md).
 
 ## Build and test
-- Build JDK: Use JDK 21+ for Pinot services and the default build; client and SPI artifacts still target Java 11 bytecode.
-- Runtime JRE: Broker/server/controller/minion run on Java 21+.
-- Default build: `./mvnw clean install`
-- Faster dev build: `./mvnw verify -Ppinot-fastdev`
-- Full binary/shaded build:
-  `./mvnw clean install -DskipTests -Pbin-dist -Pbuild-shaded-jar`
-- Build a module with deps: `./mvnw -pl pinot-server -am test`
-- Single test example: `./mvnw -pl pinot-segment-local -Dtest=RangeIndexTest test`
-- Quickstart (after build): `build/bin/quick-start-batch.sh`
+- Build JDK: Use JDK 25+ for Pinot services and the default build; client and SPI artifacts still target Java 11 bytecode.
+- Runtime JRE: Broker/server/controller/minion run on Java 25+.
+- Default to affected modules and their dependencies: `./mvnw -pl <module> -am test`.
+- Faster module build: `./mvnw -pl <module> -am verify -Ppinot-fastdev`. This profile skips style and license checks;
+  it does not replace applicable pre-push validation.
+- Single test example: `./mvnw -pl pinot-segment-local -am -Dtest=RangeIndexTest -Dsurefire.failIfNoSpecifiedTests=false test`.
+  See [kb/skills/run-test.md](kb/skills/run-test.md) for dependency availability and evidence reuse.
+- Full reactor build, when the task requires it: `./mvnw clean install`.
+- Full binary/shaded distribution, when required: `./mvnw clean install -DskipTests -Pbin-dist -Pbuild-shaded-jar`.
+- Local cluster startup: follow [kb/skills/quickstart.md](kb/skills/quickstart.md) for the smallest required build and readiness checks.
 
 ## Integration tests
 - Single integration test example: `./mvnw -pl pinot-integration-tests -am -Dtest=OfflineClusterIntegrationTest -Dsurefire.failIfNoSpecifiedTests=false test`
 
 ## Coding conventions and hygiene
 - Add class-level Javadoc for new classes; describe behavior and thread-safety.
-- Use Javadoc comments with either `/** ... */` or `///` syntax (per JEP-467); service code targets Java 21 by default.
+- Use Javadoc comments with either `/** ... */` or `///` syntax (per JEP-467); service code targets Java 25 by default.
 - Keep license headers on all new source files.
 - Use `./mvnw license:format` to add headers to new files.
 - Preserve backward compatibility across mixed-version broker/server/controller.
@@ -137,13 +91,9 @@ repo. It is intentionally short and focused on day-to-day work.
 - Run `./mvnw license:check` to validate license headers.
 
 ## Pre-commit checks
-Before pushing a commit, always run the following checks on the affected modules and fix any failures:
-1. `./mvnw spotless:apply -pl <module>` — auto-format code.
-2. `./mvnw checkstyle:check -pl <module>` — validate style conformance.
-3. `./mvnw license:format -pl <module>` — add missing license headers to new files.
-4. `./mvnw license:check -pl <module>` — verify all files have correct license headers.
-
-Do not push until all four checks pass cleanly.
+Before pushing, follow [kb/skills/precommit.md](kb/skills/precommit.md) for affected-module formatting, license headers,
+checkstyle, and license validation. That procedure defines applicability, execution order, evidence reuse, and when
+compiler warning checks are needed. Fix failures within the authorized scope; do not push with applicable checks failing.
 
 ## Change guidance
 - Query changes often touch broker planning and server execution; verify both.
@@ -171,15 +121,14 @@ should read kb/ directly.
     `review-concurrency-state`, `review-architecture`, `review-performance`,
     `review-correctness-nulls`, `review-testing`, `review-naming-api`,
     `review-process-scope`.
-- `kb/agents/code-reviewer.md` — orchestrator that dispatches the eight review
-  skills in parallel, aggregates findings, and emits a consolidated severity-
-  ranked report.
+- `kb/agents/code-reviewer.md` — review procedure that selects relevant domains,
+  delegates substantial independent checks, and verifies consolidated findings.
 - `kb/code-review-principles.md` — Pinot-specific review principles cited by id
   (e.g. `C2.4`, `C6.1`) from the review skills.
-- `kb/CLAUDE.md` — kb/ authoring rules (one source of truth, terse, AI-optimized).
+- `kb/claude.md` — kb/ authoring rules (one source of truth, terse, AI-optimized).
 
 **For non-Claude agents:** when a task matches a skill name (e.g. user asks for
 a pre-commit check, a benchmark comparison, a flaky-test investigation, or a
 code review), read the corresponding `kb/skills/<name>.md` and follow its
-procedure. For a full code review, read `kb/agents/code-reviewer.md` and run the
-eight review skills as it describes.
+procedure. For a full code review, follow `kb/agents/code-reviewer.md` and cover
+the domains relevant to the diff; small changes can be reviewed directly.