{"owner":"ktorio","repo":"ktor","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Agent Guidelines (Ktor)\n\nThis file is the primary playbook for agentic coding tools working in this repository.\n\n## Critical Workflow Rule\n\n**NEVER return control to the user without ensuring:**\n1. Tests pass: `./gradlew :module-name:jvmTest` (and other platforms if touched)\n2. Code compiles: `./gradlew :module-name:assemble`\n3. Code is formatted and linting passes: run `./gradlew :module-name:formatKotlin`, then `./gradlew :module-name:lintKotlin`\n4. ABI validated: `./gradlew :module-name:updateKotlinAbi` (if public/protected API changed)\n\nPrefer this order to fail fast.\nAlways prefer **module-specific** commands (`:module-name:task`) over project-wide commands.\n\n## Project Requirements\n\n- JDK 21 is required.\n- Kotlin Multiplatform: JVM, JS, Native.\n- Apple targets require Xcode + command line tools.\n- Android targets are optional and enabled when Android SDK is available (`ANDROID_HOME` or `local.properties` `sdk.dir`).\n\n## Project Layout\n\n### Gradle module structure (flattened)\nThe project uses a **flattened Gradle structure** (see `settings.gradle.kts`). Nested directory paths do NOT translate to nested Gradle project names.\nExample: `ktor-client/ktor-client-curl` → `:ktor-client-curl` (not `:ktor-client:ktor-client-curl`).\n\n### Source set layout (platform-centric)\nKotlin Multiplatform sources use a flattened, platform-centric layout (do not re-introduce `src/<platform>Main/...`).\n\n```text\ncommon/src\njvm/src\njvm/resources\njvm/test\njvm/test-resources\n...\n```\n\nBuild logic enforces \"no surprise source sets\": manually registering extra source sets is rejected.\nTo add a new target/source set, add the directory or enable the target via `gradle.properties` (`target.<name>=true`).\n\n## Build Commands\n\n**Important**: Always prefer running tasks on the specific module you touched, not the entire project.\n\n### Common tasks\n```bash\n./gradlew :module-name:assemble          # Build the module\n```\n\nRun tests:\n```bash\n./gradlew :module-name:jvmTest           # Run JVM tests for the module\n./gradlew :module-name:allTests          # Run tests across all platforms for the module\n./gradlew :module-name:jvmTest --tests \"fully.qualified.TestClassName\" # Run a specific test\n./gradlew :module-name:jvmTest --tests \"fully.qualified.TestClassName.methodName\" # Run a specific test method\n```\n\nLinting:\n```bash\n./gradlew :module-name:formatKotlin      # Format the module\n./gradlew :module-name:lintKotlin        # Lint the module\n```\n\n## Code Style Guidelines\n\n### Formatting (EditorConfig is authoritative)\n- Kotlin style: IntelliJ + `KOTLIN_OFFICIAL` (`.editorconfig`).\n- Indent: 4 spaces (JSON/YAML: 2); max line length: 120; end of line: LF.\n- Use `./gradlew :module-name:formatKotlin` rather than manual formatting.\n\n### Imports\n- Star imports are preferred for `io.ktor.*` (configured in `.editorconfig`).\n\n### Naming\n- Follow Kotlin conventions unless the surrounding package has a strong established pattern.\n- Tests: prefer descriptive test names in backticks: `describe what is being tested`.\n\n### Types and API design\n- Prefer `internal` by default; keep the public surface intentional.\n- Public API requires KDoc (parameters, return, and notable exceptions).\n- Public-but-not-for-users APIs that cannot be `internal` should use `@InternalAPI`.\n- Keep `@OptIn(...)` scope minimal.\n- All types used as receivers in DSL should be annotated with `@KtorDsl` (for example, all plugin configs).\n\n### Error handling\n- `require(...)` for argument validation, `check(...)` for state validation, `error(\"...\")` for unreachable states.\n- Throw specific exceptions appropriate to the layer (IO parsing: `IOException`/`EOFException`; validation: Ktor exceptions like `BadRequestException`).\n- Make error messages actionable; include the problematic value/context.\n\n### Logging\n- Prefer Ktor log helpers where present.\n- Avoid noisy logs in hot paths.\n\n### Documentation and comments\n- Avoid redundant comments; add them only for tricky invariants or platform-specific behavior.\n- Keep KDoc correct when behavior/signatures change.\n- New source files must include the repository copyright header.\n\n## Development Practices\n\n- Prefer TDD where feasible: add/adjust tests, then implement.\n- For multiplatform changes: start JVM-first unless the task requires another platform.\n- Keep local-only build knobs (for example, developer `gradle.properties` overrides) out of commits.\n- If asked to create commits: use imperative mood and include `KTOR-<NUM>` when there is a related YouTrack issue.\n\n### Adding or removing modules\n\n- Module names must start with `ktor-`.\n- The project uses a flattened Gradle structure with custom DSL in `settings.gradle.kts` (see Project Layout section).\n- When modules are added/removed or new targets enabled, run `./update-artifact-dumps.sh` to update published artifact lists in `gradle/artifacts`.\n  Publishing will fail if these dumps are stale.\n\n## Binary Compatibility and ABI Validation\n\nBinary compatibility is **enforced** using Kotlin Gradle Plugin ABI validation.\nAll public API changes must be tracked in `/api/` directories within modules.\n\n### Release branches and API policy\n\n- Patch releases are maintained in `release/<major>.x` (for example, v3 uses `release/3.x`, v4 uses `release/4.x`).\n- The next minor release is developed on `main`.\n- Public API changes are allowed only for minor/major releases (typically on `main`), not for patch releases (on `release/<major>.x`).\n- Breaking changes are **only allowed in major version releases**.\n- The repo includes an interactive helper `./switch-base-branch.sh` for switching a feature branch base between `main` and `release/<major>.x`.\n  For agents: use `--dry-run` to print the git commands, then run them after user approval.\n\n### Validation commands\n```bash\n./gradlew :module-name:checkKotlinAbi    # Validate ABI compatibility\n./gradlew :module-name:updateKotlinAbi   # Update ABI signature files after changes\n```\n\n### Rules\n- **All** `public`/`protected` API changes require updating `api/*.api` dumps.\n- API changes must be **intentional and well-documented**.\n"},"files":{"AGENTS.md":"# Agent Guidelines (Ktor)\n\nThis file is the primary playbook for agentic coding tools working in this repository.\n\n## Critical Workflow Rule\n\n**NEVER return control to the user without ensuring:**\n1. Tests pass: `./gradlew :module-name:jvmTest` (and other platforms if touched)\n2. Code compiles: `./gradlew :module-name:assemble`\n3. Code is formatted and linting passes: run `./gradlew :module-name:formatKotlin`, then `./gradlew :module-name:lintKotlin`\n4. ABI validated: `./gradlew :module-name:updateKotlinAbi` (if public/protected API changed)\n\nPrefer this order to fail fast.\nAlways prefer **module-specific** commands (`:module-name:task`) over project-wide commands.\n\n## Project Requirements\n\n- JDK 21 is required.\n- Kotlin Multiplatform: JVM, JS, Native.\n- Apple targets require Xcode + command line tools.\n- Android targets are optional and enabled when Android SDK is available (`ANDROID_HOME` or `local.properties` `sdk.dir`).\n\n## Project Layout\n\n### Gradle module structure (flattened)\nThe project uses a **flattened Gradle structure** (see `settings.gradle.kts`). Nested directory paths do NOT translate to nested Gradle project names.\nExample: `ktor-client/ktor-client-curl` → `:ktor-client-curl` (not `:ktor-client:ktor-client-curl`).\n\n### Source set layout (platform-centric)\nKotlin Multiplatform sources use a flattened, platform-centric layout (do not re-introduce `src/<platform>Main/...`).\n\n```text\ncommon/src\njvm/src\njvm/resources\njvm/test\njvm/test-resources\n...\n```\n\nBuild logic enforces \"no surprise source sets\": manually registering extra source sets is rejected.\nTo add a new target/source set, add the directory or enable the target via `gradle.properties` (`target.<name>=true`).\n\n## Build Commands\n\n**Important**: Always prefer running tasks on the specific module you touched, not the entire project.\n\n### Common tasks\n```bash\n./gradlew :module-name:assemble          # Build the module\n```\n\nRun tests:\n```bash\n./gradlew :module-name:jvmTest           # Run JVM tests for the module\n./gradlew :module-name:allTests          # Run tests across all platforms for the module\n./gradlew :module-name:jvmTest --tests \"fully.qualified.TestClassName\" # Run a specific test\n./gradlew :module-name:jvmTest --tests \"fully.qualified.TestClassName.methodName\" # Run a specific test method\n```\n\nLinting:\n```bash\n./gradlew :module-name:formatKotlin      # Format the module\n./gradlew :module-name:lintKotlin        # Lint the module\n```\n\n## Code Style Guidelines\n\n### Formatting (EditorConfig is authoritative)\n- Kotlin style: IntelliJ + `KOTLIN_OFFICIAL` (`.editorconfig`).\n- Indent: 4 spaces (JSON/YAML: 2); max line length: 120; end of line: LF.\n- Use `./gradlew :module-name:formatKotlin` rather than manual formatting.\n\n### Imports\n- Star imports are preferred for `io.ktor.*` (configured in `.editorconfig`).\n\n### Naming\n- Follow Kotlin conventions unless the surrounding package has a strong established pattern.\n- Tests: prefer descriptive test names in backticks: `describe what is being tested`.\n\n### Types and API design\n- Prefer `internal` by default; keep the public surface intentional.\n- Public API requires KDoc (parameters, return, and notable exceptions).\n- Public-but-not-for-users APIs that cannot be `internal` should use `@InternalAPI`.\n- Keep `@OptIn(...)` scope minimal.\n- All types used as receivers in DSL should be annotated with `@KtorDsl` (for example, all plugin configs).\n\n### Error handling\n- `require(...)` for argument validation, `check(...)` for state validation, `error(\"...\")` for unreachable states.\n- Throw specific exceptions appropriate to the layer (IO parsing: `IOException`/`EOFException`; validation: Ktor exceptions like `BadRequestException`).\n- Make error messages actionable; include the problematic value/context.\n\n### Logging\n- Prefer Ktor log helpers where present.\n- Avoid noisy logs in hot paths.\n\n### Documentation and comments\n- Avoid redundant comments; add them only for tricky invariants or platform-specific behavior.\n- Keep KDoc correct when behavior/signatures change.\n- New source files must include the repository copyright header.\n\n## Development Practices\n\n- Prefer TDD where feasible: add/adjust tests, then implement.\n- For multiplatform changes: start JVM-first unless the task requires another platform.\n- Keep local-only build knobs (for example, developer `gradle.properties` overrides) out of commits.\n- If asked to create commits: use imperative mood and include `KTOR-<NUM>` when there is a related YouTrack issue.\n\n### Adding or removing modules\n\n- Module names must start with `ktor-`.\n- The project uses a flattened Gradle structure with custom DSL in `settings.gradle.kts` (see Project Layout section).\n- When modules are added/removed or new targets enabled, run `./update-artifact-dumps.sh` to update published artifact lists in `gradle/artifacts`.\n  Publishing will fail if these dumps are stale.\n\n## Binary Compatibility and ABI Validation\n\nBinary compatibility is **enforced** using Kotlin Gradle Plugin ABI validation.\nAll public API changes must be tracked in `/api/` directories within modules.\n\n### Release branches and API policy\n\n- Patch releases are maintained in `release/<major>.x` (for example, v3 uses `release/3.x`, v4 uses `release/4.x`).\n- The next minor release is developed on `main`.\n- Public API changes are allowed only for minor/major releases (typically on `main`), not for patch releases (on `release/<major>.x`).\n- Breaking changes are **only allowed in major version releases**.\n- The repo includes an interactive helper `./switch-base-branch.sh` for switching a feature branch base between `main` and `release/<major>.x`.\n  For agents: use `--dry-run` to print the git commands, then run them after user approval.\n\n### Validation commands\n```bash\n./gradlew :module-name:checkKotlinAbi    # Validate ABI compatibility\n./gradlew :module-name:updateKotlinAbi   # Update ABI signature files after changes\n```\n\n### Rules\n- **All** `public`/`protected` API changes require updating `api/*.api` dumps.\n- API changes must be **intentional and well-documented**.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Agent Guidelines (Ktor)\n\nThis file is the primary playbook for agentic coding tools working in this repository.\n\n## Critical Workflow Rule\n\n**NEVER return control to the user without ensuring:**\n1. Tests pass: `./gradlew :module-name:jvmTest` (and other platforms if touched)\n2. Code compiles: `./gradlew :module-name:assemble`\n3. Code is formatted and linting passes: run `./gradlew :module-name:formatKotlin`, then `./gradlew :module-name:lintKotlin`\n4. ABI validated: `./gradlew :module-name:updateKotlinAbi` (if public/protected API changed)\n\nPrefer this order to fail fast.\nAlways prefer **module-specific** commands (`:module-name:task`) over project-wide commands.\n\n## Project Requirements\n\n- JDK 21 is required.\n- Kotlin Multiplatform: JVM, JS, Native.\n- Apple targets require Xcode + command line tools.\n- Android targets are optional and enabled when Android SDK is available (`ANDROID_HOME` or `local.properties` `sdk.dir`).\n\n## Project Layout\n\n### Gradle module structure (flattened)\nThe project uses a **flattened Gradle structure** (see `settings.gradle.kts`). Nested directory paths do NOT translate to nested Gradle project names.\nExample: `ktor-client/ktor-client-curl` → `:ktor-client-curl` (not `:ktor-client:ktor-client-curl`).\n\n### Source set layout (platform-centric)\nKotlin Multiplatform sources use a flattened, platform-centric layout (do not re-introduce `src/<platform>Main/...`).\n\n```text\ncommon/src\njvm/src\njvm/resources\njvm/test\njvm/test-resources\n...\n```\n\nBuild logic enforces \"no surprise source sets\": manually registering extra source sets is rejected.\nTo add a new target/source set, add the directory or enable the target via `gradle.properties` (`target.<name>=true`).\n\n## Build Commands\n\n**Important**: Always prefer running tasks on the specific module you touched, not the entire project.\n\n### Common tasks\n```bash\n./gradlew :module-name:assemble          # Build the module\n```\n\nRun tests:\n```bash\n./gradlew :module-name:jvmTest           # Run JVM tests for the module\n./gradlew :module-name:allTests          # Run tests across all platforms for the module\n./gradlew :module-name:jvmTest --tests \"fully.qualified.TestClassName\" # Run a specific test\n./gradlew :module-name:jvmTest --tests \"fully.qualified.TestClassName.methodName\" # Run a specific test method\n```\n\nLinting:\n```bash\n./gradlew :module-name:formatKotlin      # Format the module\n./gradlew :module-name:lintKotlin        # Lint the module\n```\n\n## Code Style Guidelines\n\n### Formatting (EditorConfig is authoritative)\n- Kotlin style: IntelliJ + `KOTLIN_OFFICIAL` (`.editorconfig`).\n- Indent: 4 spaces (JSON/YAML: 2); max line length: 120; end of line: LF.\n- Use `./gradlew :module-name:formatKotlin` rather than manual formatting.\n\n### Imports\n- Star imports are preferred for `io.ktor.*` (configured in `.editorconfig`).\n\n### Naming\n- Follow Kotlin conventions unless the surrounding package has a strong established pattern.\n- Tests: prefer descriptive test names in backticks: `describe what is being tested`.\n\n### Types and API design\n- Prefer `internal` by default; keep the public surface intentional.\n- Public API requires KDoc (parameters, return, and notable exceptions).\n- Public-but-not-for-users APIs that cannot be `internal` should use `@InternalAPI`.\n- Keep `@OptIn(...)` scope minimal.\n- All types used as receivers in DSL should be annotated with `@KtorDsl` (for example, all plugin configs).\n\n### Error handling\n- `require(...)` for argument validation, `check(...)` for state validation, `error(\"...\")` for unreachable states.\n- Throw specific exceptions appropriate to the layer (IO parsing: `IOException`/`EOFException`; validation: Ktor exceptions like `BadRequestException`).\n- Make error messages actionable; include the problematic value/context.\n\n### Logging\n- Prefer Ktor log helpers where present.\n- Avoid noisy logs in hot paths.\n\n### Documentation and comments\n- Avoid redundant comments; add them only for tricky invariants or platform-specific behavior.\n- Keep KDoc correct when behavior/signatures change.\n- New source files must include the repository copyright header.\n\n## Development Practices\n\n- Prefer TDD where feasible: add/adjust tests, then implement.\n- For multiplatform changes: start JVM-first unless the task requires another platform.\n- Keep local-only build knobs (for example, developer `gradle.properties` overrides) out of commits.\n- If asked to create commits: use imperative mood and include `KTOR-<NUM>` when there is a related YouTrack issue.\n\n### Adding or removing modules\n\n- Module names must start with `ktor-`.\n- The project uses a flattened Gradle structure with custom DSL in `settings.gradle.kts` (see Project Layout section).\n- When modules are added/removed or new targets enabled, run `./update-artifact-dumps.sh` to update published artifact lists in `gradle/artifacts`.\n  Publishing will fail if these dumps are stale.\n\n## Binary Compatibility and ABI Validation\n\nBinary compatibility is **enforced** using Kotlin Gradle Plugin ABI validation.\nAll public API changes must be tracked in `/api/` directories within modules.\n\n### Release branches and API policy\n\n- Patch releases are maintained in `release/<major>.x` (for example, v3 uses `release/3.x`, v4 uses `release/4.x`).\n- The next minor release is developed on `main`.\n- Public API changes are allowed only for minor/major releases (typically on `main`), not for patch releases (on `release/<major>.x`).\n- Breaking changes are **only allowed in major version releases**.\n- The repo includes an interactive helper `./switch-base-branch.sh` for switching a feature branch base between `main` and `release/<major>.x`.\n  For agents: use `--dry-run` to print the git commands, then run them after user approval.\n\n### Validation commands\n```bash\n./gradlew :module-name:checkKotlinAbi    # Validate ABI compatibility\n./gradlew :module-name:updateKotlinAbi   # Update ABI signature files after changes\n```\n\n### Rules\n- **All** `public`/`protected` API changes require updating `api/*.api` dumps.\n- API changes must be **intentional and well-documented**.\n","category":"root","tokens":1520}]}