• Never write any comments in code
• Exception: tests must use // given, // when, // then, // expect, and // and structural comments to separate test phases (does NOT apply to recipe tests using before/beforeAndAfter/after RewriteTest patterns)
• Update AGENTS.md every time project structure is changed
• ktlint must pass (./gradlew ktlintCheck); run the full ./gradlew check before pushing anything

allwrite is a CLI tool and collection of OpenRewrite recipes for automated code transformations across YAML, Gradle, Java/Kotlin, and Spring projects. It wraps OpenRewrite's runtime into a CLI that can run recipes by name, integrate with GitHub Actions, and work with Dependabot PRs.

The documentation site is built with MkDocs from mkdocs.yml, docs/requirements.txt, and the docs/ directory.

• docs/index.md — project overview
• docs/cli.md — CLI reference
• docs/contributing.md — recipe authoring guide
• docs/recipes/index.md — built-in recipes overview and authoring helpers
• docs/recipes/{yaml,gradle,java,spring}/ — individual built-in recipe pages grouped by category
• Every new recipe gets a dedicated page under docs/recipes/ and a matching entry in mkdocs.yml navigation.
• docs/extra.css — documentation layout overrides

Multi-module Gradle project using Hexagonal Architecture (Ports & Adapters).

allwrite-cli  -->  allwrite-runtime  -->  allwrite-api
      |                  |                     ^
      |                  v                     |
      |            allwrite-recipes -----------+
      |                  |
      |                  v
      |            allwrite-spi
      |                  ^
      +-----> allwrite-completions
                    (annotation processor)
      |
      +-----> allwrite-recipes (direct, for recipe classpath)

allwrite/
├── allwrite-api/
│   └── src/main/kotlin/              Incoming port interfaces (RecipeExecutor, RecipeSource, RecipeCoordinates)
│
├── allwrite-cli/
│   ├── src/main/kotlin/              CLI application (commands, infrastructure adapters)
│   │   ├── runner/Main.kt            Entry point
│   │   ├── runner/RunnerModule.kt
│   │   ├── runner/application/       CLI commands (run, ls, external add/update/rm/ls), application logic
│   │   ├── runner/infrastructure/    OS, GitHub, PR manager adapters (incl. external recipe store)
│   │   └── runner/util/              Utility classes
│   ├── src/main/resources/           logback.xml
│   ├── src/test/kotlin/              Unit tests (Kotest FunSpec)
│   └── src/e2e/kotlin/              End-to-end tests
│
├── allwrite-runtime/
│   ├── src/main/kotlin/              Outgoing ports, recipe executor, source file parser
│   ├── src/test/kotlin/              Unit tests (Kotest FunSpec)
│   └── src/testFixtures/kotlin/      Shared test fakes/fixtures
│
├── allwrite-recipes/
│   ├── src/main/kotlin/
│   │   ├── recipes/yaml/            YAML transformation recipes
│   │   ├── recipes/spring/          Spring property/annotation and migration recipes, including conditional dependency and custom Spring Boot 4 migration helpers
│   │   ├── recipes/java/            Java refactoring recipes
│   │   ├── recipes/gradle/          Gradle dependency recipes
│   │   │   ├── *DependencyRewriter.kt  Dedicated helpers for Gradle dependency transforms
│   │   │   ├── AddTomlVersionCatalogPlugin.kt  Add and apply version catalog plugins
│   │   │   ├── AddSettingsPluginRepository.kt  Add gated repositories to Gradle settings files
│   │   │   ├── AppliedPluginDetector.kt  Detect applied Gradle plugins
│   │   │   ├── RemoveLibraryVersionRefs.kt  Remove version references from matching libraries
│   │   │   └── RemoveTomlVersionCatalogLibrary.kt  Remove a library from a TOML version catalog
│   │   ├── recipes/properties/      Properties file recipes
│   │   ├── recipes/toml/            TOML utilities
│   │   └── recipes/util/            Shared recipe utilities
│   ├── src/main/resources/META-INF/rewrite/   Declarative YAML recipes
│   ├── src/test/kotlin/              Unit tests (JUnit 5 + RewriteTest)
│   └── src/testFixtures/kotlin/      Test fixture classes
│
├── allwrite-spi/
│   └── src/main/kotlin/              Recipe base classes (AllwriteRecipe, CliAllwriteRecipe, AllwriteScanningRecipe, CliAllwriteScanningRecipe, RecipeMetadata)
│
├── allwrite-completions/
│   └── src/main/kotlin/              kapt processors + generators
│
├── build-logic/
│   └── src/main/kotlin/
│       ├── conventions/              Convention plugins (kotlin, koin, openrewrite-recipe-library, jreleaser, etc.)
│       └── *.kt                      Custom Gradle tasks (FetchJdkTask, etc.)
│
├── gradle/
│   ├── libs.versions.toml            Central dependency version catalog
│   └── wrapper/
│
├── .github/workflows/               CI, documentation build/publish, and releases
├── docs/                            MkDocs documentation source, recipe catalog, and dependencies
└── mkdocs.yml                       MkDocs site configuration

allwrite-cli/src/main/kotlin/pl/allegro/tech/allwrite/runner/Main.kt

The main() function bootstraps Koin DI, conditionally loads GithubModule when running in GitHub Actions, then delegates to AppEntrypoint.execute(args). AppEntrypoint is implemented by MainCommand (a Clikt command) dispatching to sub-commands.

• Kotlin explicit API mode is enabled — all public declarations require explicit visibility modifiers
• .editorconfig enforces: 4-space indentation, 160 char line length, LF line endings, UTF-8
• Kotlin style: ktlint_code_style = intellij_idea, trailing commas required, no star imports
• YAML files: 2-space indentation
• Shell scripts: 2-space indentation

• Kotlin files: PascalCase class names matching file names
• Test files: *Spec.kt (Kotest) or *Test.kt (JUnit)
• Packages: pl.allegro.tech.allwrite.*
• Koin modules: *Module.kt
• Incoming port interfaces: in pl.allegro.tech.allwrite.api package (allwrite-api module)
• Outgoing port interfaces: under port/outgoing/ in allwrite-runtime
• Fake test implementations: Fake* prefix

• Hexagonal Architecture: Incoming ports (RecipeExecutor, RecipeSource, AppEntrypoint) and outgoing ports (UserProblemReporter, InputFilesProvider, GitMetadata, PullRequestContext, TelemetryPublisher, SystemInfo, ExternalRecipeJarsProvider)
• Koin + KSP DI: Modules annotated with @Module and @ComponentScan, services with @Single
• Convention Plugins: Shared build logic in build-logic/ (conventions.kotlin, conventions.koin, conventions.recipe-classpaths, etc.)
• Template Method: SubCommand abstract class defines run() lifecycle; subclasses implement runSubCommand(). ExternalSubCommand extends SubCommand as a marker for commands nested under the external group. ExternalCommand is a Clikt group command that collects ExternalSubCommand instances as subcommands.
• Observer/Listener: CommandListener instances notified after each command execution (telemetry)
• Recipe Strategy: Recipes can implement ParsingAwareRecipe or PostprocessingRecipe. Base classes: AllwriteRecipe, CliAllwriteRecipe, AllwriteScanningRecipe, CliAllwriteScanningRecipe
• Test Fakes over Mocks: Heavy use of Fake* implementations for test isolation
• Tag-based Recipe Metadata: Custom tag system (group:*, action:*, from:*, to:*, dependabot-artifact:*) for CLI recipe discovery, version matching, and Dependabot integration
• Declarative Recipes: Recipes defined programmatically (Kotlin) or declaratively (YAML under META-INF/rewrite/)

• BaseRunnerSpec — abstract base for runner tests, sets up Koin DI with faked modules
• BaseRuntimeSpec — abstract base for runtime tests
• Test fixtures shared via testFixtures source set
• Recipe tests use OpenRewrite's RewriteTest interface for before/after source assertions

Core: openrewrite (rewrite-core, rewrite-java, rewrite-java-11, rewrite-java-17, rewrite-java-21, rewrite-kotlin, rewrite-yaml, rewrite-toml, rewrite-properties, rewrite-gradle, rewrite-groovy), openrewrite-recipe (rewrite-spring, rewrite-static-analysis), koin-core, koin-annotations, koin-ksp-compiler, clikt, clikt-markdown, markout, markout-markdown, kotlin-reflect, kotlinx-serialization-json, kotlinx-datetime

Infrastructure: ktor-client-core, ktor-client-cio, ktor-client-content-negotiation, ktor-serialization-kotlinx-json, github-client (Spotify), java-semver, snakeyaml, logback-classic, kotlin-logging, slf4j-api

Build-only: kotlinpoet-jvm, mustache-java, auto-service, commons-compress, pgpainless-core, jackson-module-kotlin

Testing: kotest-runner-junit5-jvm, kotest-assertions-core-jvm, kotest-framework-datatest, kotest-extensions-koin, mockk, rewrite-test, junit-jupiter, assertj-core