AGENTS.md — Guidelines for AI Coding Agents in KSP

Welcome! This file defines the mandatory workflow, engineering methodology, and project context for AI coding agents working in the Kotlin Symbol Processing (KSP) repository.

1. Documentation Discovery & Reference Map

1. Read CONTRIBUTING.md First: Before proposing plans or modifying code, read CONTRIBUTING.md. It is the authoritative source for the bug contribution workflow (@Bug / BugState), api/api.base verification (checkApi / updateApi), and writing unit tests in kotlin-analysis-api.
2. Consult Additional Documentation On-Demand: Read the following repository documents when relevant to your task. Documentation can be found in Markdown files, LICENSE, and doc comments in Kotlin source files.

2. Core Engineering Methodology: Scientific Method & Zero Speculation

You are working on a compiler plugin and symbol processing engine. There must be zero speculation, hand-waving, or hallucination.

• The Codebase is the Single Source of Truth: Every claim, diagnosis, or proposed change must be backed by concrete code snippets and traced through the actual codebase.
• Falsify Hypotheses First (Scientific Method):
  • Whenever you form a hypothesis about how a symbol is resolved, how a type is computed, or why a bug occurs, actively try to disprove your hypothesis first using concrete code examples and dataflow examples from the codebase.
  • Trace the exact dataflow end-to-end (e.g., from Resolver entry points to AnnotationResolutionStrategy / Analysis API session calls to KSNode / KSType wrappers to PSI / FIR symbols) and cite the concrete classes, functions, and line ranges involved.
  • Revise your mental model repeatedly whenever the code contradicts your assumptions.
• No Guessing: If an API contract, compiler behavior, or user requirement is ambiguous, inspect the implementation and test suite (kotlin-analysis-api/testData and KSPUnitTestSuite.kt) or ask the user clarifying questions rather than guessing.
• Outline a Detailed Plan First: Always outline a clear, detailed plan supported by code references and dataflow analysis before you begin. Use this plan as your reference when you are making changes.
• Preserve & Synchronize Documentation:
  • Preserve all existing comments and docstrings unrelated to your changes unless explicitly instructed otherwise.
  • Keep Documentation in Sync with Code Changes: Whenever you modify code, behavior, APIs, Gradle properties, or build configurations, you must also update the corresponding KDoc/doc comments and any relevant documentation files in the repository (e.g., README.md, CONTRIBUTING.md, DEVELOPMENT.md, AGENTS.md, or docs/) so that documentation never drifts out of sync with the implementation. This AGENTS.md file must also be kept in sync.

3. License & Legal Compliance

• License: This repository is licensed under the Apache License, Version 2.0 (see LICENSE).
• CLA: Contributions require a Google Contributor License Agreement (CONTRIBUTING.md).
• Copyright Headers: All new source files (.kt, .java) must include the standard Apache 2.0 license header used across the codebase:

/*
 * Copyright <CURRENT YEAR> Google LLC
 * Copyright 2010-<CURRENT YEAR> JetBrains s.r.o. and Kotlin Programming Language contributors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

where <CURRENT YEAR> is the current year.

You will likely find files that do not have a copyright header. The headers may have been lost when moving the file in the editor. Do not restore those.

4. Repository Architecture & Module Guide

Important Note on KSP1: KSP 1.x has been removed and is no longer supported (README.md). All active compiler engine development targets KSP2 (kotlin-analysis-api).

The project consists of Gradle subprojects configured in settings.gradle.kts:

5. Contribution, Bug & Testing Workflows

Read CONTRIBUTING.md.

6. Build, Version Synchronization & Verification Reference

JDK & Kotlin Version Constraints

• Carefully read the Gradle build files for a particular module to find out what its Java and Kotlin constraints are.
• Decoupled Versions (gradle.properties & gradle/libs.versions.toml):
  • buildKotlinVersion / buildKspVersion: Used in gradle.properties to bootstrap and compile the KSP project itself.
  • kotlinBaseVersion (kotlin-base) & agpBaseVersion (agp-base): Duplicated in both gradle.properties and gradle/libs.versions.toml. gradle-plugin's TestConfig loads gradle.properties directly at test runtime—always keep both files in sync.
  • aa-kotlin-base (aaKotlinBaseVersion): The specific (often developmental) Kotlin version used for Analysis API dependencies in :kotlin-analysis-api and :symbol-processing-aa-embeddable.

Essential Gradle Tasks

• Run a single unit test method across all 4 suite configurations:

  Note: Because KSPUnitTestSuite is abstract, use a wildcard or a concrete subclass name with --tests:

  ./gradlew :kotlin-analysis-api:test --tests "*.<testMethodName>"

• Run all Analysis API unit tests:

  ./gradlew :kotlin-analysis-api:test

• Check / Update Public API Signatures (Metalava): Whenever modifying public declarations in :api, verify compatibility against api/api.base:

  ./gradlew :api:checkApi
  ./gradlew :api:updateApi

• Shadow JAR & Relocation Validation:
  • ./gradlew :kotlin-analysis-api:validateShadowJar: Runs jdeps against kotlin-analysis-api/shadow-validation-baseline.txt and verifies no forbidden packages (such as org/apache/log4j/jdbc) leak into the shadow JAR.
  • ./gradlew :symbol-processing-aa-embeddable:shadowJar: Verifies that all bundled classes are relocated into allowed ksp.* namespaces.
• Gradle Plugin Tests:
  • ./gradlew :gradle-plugin:test: Runs tests for the KSP Gradle plugin.
• Run Integration Tests: Integration tests publish all artifacts to <rootProject>/build/repos/test and run Gradle TestKit suites (integration-tests/build.gradle.kts):

  ./gradlew :integration-tests:primaryTest
  ./gradlew :integration-tests:secondaryTest
  ./gradlew :integration-tests:androidTest
  ./gradlew :integration-tests:agpTest

  Integration tests may take a long time to run so it may be helpful to just run a single test or test class when making changes, e.g.,

  ./gradlew :integration-tests:primaryTest --tests "com.google.devtools.ksp.test.primary.<TestClass>.<method>"

  where TestClass is the name of the class containing tests and method is the name of test method/entrypoint.
• Full Verification: Before submitting a pull request to the KSP repository, you must always run the entire ./gradlew check task and check that it completes successfully.

  Note: It may be necessary to pass --rerun-tasks to ensure cached test or task outputs are re-evaluated after changes.

  ./gradlew check --rerun-tasks