diff --git a/.gitignore b/.gitignore
index 3f9fde51b..53425201b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,3 +23,10 @@ out
 *~
 # OS X generated file
 .DS_Store
+# AI assistant files
+CLAUDE.md
+GEMINI.md
+COPILOT.md
+CURSOR.md
+.cursorrules
+.github/copilot-instructions.md
diff --git a/AI-CODE.md b/AI-CODE.md
new file mode 100644
index 000000000..e6ec598f1
--- /dev/null
+++ b/AI-CODE.md
@@ -0,0 +1,57 @@
+## Tech Stack
+* **Java Version:** 17 (use JAVA_HOME=/usr/lib/jvm/java-25-openjdk-amd64/ to build with a newer JDK, compiler target is 17)
+* **Build Tool:** Maven multi-module (use `./mvnw`)
+* **Key Frameworks:** JUnit 4, Mockito, compile-testing
+
+## Project Architecture
+
+* **parent:** Parent POM with shared dependency and plugin versions
+* **core:** Core library — annotations, descriptors, serialization runtime (`TagReader`/`TagWriter`), `.proto` schema parsing
+* **processor:** Annotation processor for compile-time marshaller and `.proto` schema generation
+* **processor-tests:** Tests for the annotation processor (Java)
+* **processor-tests-kotlin:** Tests for the annotation processor (Kotlin)
+* **types:** Pre-built adapters for common JDK types (`BigDecimal`, `UUID`, `LocalDateTime`, collections, etc.)
+* **integrationtests:** Integration tests
+* **sample-domain-definition:** Sample `.proto` domain definitions used across tests
+* **sample-domain-implementation:** Sample marshaller implementations used across tests
+* **maven-plugin:** Maven plugin for `.proto` schema backward compatibility checks
+
+## Common Build Commands
+* **Full build (skip tests):** `./mvnw install -DskipTests -Dcheckstyle.skip`
+* **Build a single module:** `./mvnw install -pl core -DskipTests -Dcheckstyle.skip`
+* **Build a module and its dependencies:** `./mvnw install -pl processor-tests -am -DskipTests -Dcheckstyle.skip`
+* **Run a single test class:** `./mvnw test -pl core -Dtest=ProtobufUtilTest -Dcheckstyle.skip`
+* **Run a single test method:** `./mvnw test -pl core -Dtest=ProtobufUtilTest#testMethodName -Dcheckstyle.skip`
+* **Processor tests** depend on core+processor being built first:
+  ```bash
+  ./mvnw install -pl core,processor -DskipTests -Dcheckstyle.skip
+  ./mvnw test -pl processor-tests -Dcheckstyle.skip
+  ```
+
+## Key Packages (core module)
+* `org.infinispan.protostream` — Public API: `ProtobufUtil` (entry point), `SerializationContext`, `TagReader`/`TagWriter`, marshaller interfaces
+* `org.infinispan.protostream.annotations` — User-facing annotations: `@ProtoSchema`, `@Proto`, `@ProtoField`, `@ProtoFactory`, `@ProtoAdapter`
+* `org.infinispan.protostream.descriptors` — Proto schema object model: `FileDescriptor`, `Descriptor`, `FieldDescriptor`, `EnumDescriptor`
+* `org.infinispan.protostream.impl` — Runtime implementation: `SerializationContextImpl`, `TagReaderImpl`/`TagWriterImpl`, proto file parser
+* `org.infinispan.protostream.impl.json` — JSON-to-protobuf bridging
+
+## Key Packages (processor module)
+* `ProtoSchemaAnnotationProcessor` — Main JSR 269 processor, entry point for compile-time code generation
+* `MarshallerSourceCodeGenerator` — Generates marshaller Java source code
+* `CompileTimeProtoSchemaGenerator` — Generates `.proto` schema files
+* `types/MirrorTypeFactory` — Compile-time implementation of the `XTypeFactory` abstraction (uses `javax.lang.model` instead of reflection)
+
+## How Serialization Works
+1. Users annotate classes with `@Proto`/`@ProtoField` and create a `@ProtoSchema`-annotated interface
+2. At compile time, the annotation processor generates: marshaller classes, `.proto` schema files, and a `SerializationContextInitializer` implementation
+3. At runtime, `ProtobufUtil.newSerializationContext()` creates a context, the generated initializer registers schemas and marshallers
+4. `ProtobufUtil.toByteArray()`/`fromByteArray()` perform serialization via `TagWriter`/`TagReader`
+
+## Development Standards
+* **Style:** Functional programming patterns where possible; use Records for DTOs
+* **Coding style:** Skip checkstyle with `-Dcheckstyle.skip` during development. Format code before committing.
+* **Commit logs:** Must start with `[#00000] Summary` (issue number)
+* **Git branches:** Name as `issueid/issue_summary`, use `origin/main` as upstream
+
+## Related Projects
+* **Infinispan:** The main consumer of ProtoStream — source code is in ../infinispan
diff --git a/AI-ISSUES.md b/AI-ISSUES.md
new file mode 100644
index 000000000..ea8bc3a10
--- /dev/null
+++ b/AI-ISSUES.md
@@ -0,0 +1,15 @@
+# Issue Creation Instructions
+
+## Issue Tracker
+
+Issues are tracked at https://github.com/infinispan/protostream/issues
+
+ProtoStream does not currently have GitHub issue type templates. Use plain issues with clear titles and descriptions.
+
+## Conventions
+
+- Issue titles should be concise and descriptive
+- Reference related issues and PRs using `#number` format
+- For issues that also affect Infinispan, cross-reference the Infinispan issue using `infinispan/infinispan#number`
+- When creating issues from code investigation, include file paths and line numbers where relevant
+- Commit messages reference issues using `[#00000] Summary` format
diff --git a/AI-TEST.md b/AI-TEST.md
new file mode 100644
index 000000000..ca883d60c
--- /dev/null
+++ b/AI-TEST.md
@@ -0,0 +1,64 @@
+# Testing Instructions
+
+## Test Framework
+
+ProtoStream uses **JUnit 4** across all modules.
+
+| Module              | Test Focus                                      | Test Naming |
+|---------------------|--------------------------------------------------|-------------|
+| core                | Serialization, parsing, descriptors, utilities  | `*Test`     |
+| processor-tests     | Annotation processor code generation            | `*Test`     |
+| processor-tests-kotlin | Kotlin-specific annotation processor tests   | `*Test`     |
+| integrationtests    | Cross-module integration                        | `*Test`     |
+
+## Writing Tests
+
+### Core Module Tests
+
+Most core tests extend `AbstractProtoStreamTest`, which provides helper methods for creating a `SerializationContext` with sample domain schemas and marshallers pre-registered.
+
+```java
+public class MyFeatureTest extends AbstractProtoStreamTest {
+
+   @Test
+   public void testSomething() throws Exception {
+      SerializationContext ctx = createContext();
+      // use ctx to serialize/deserialize
+   }
+}
+```
+
+### Annotation Processor Tests
+
+Processor tests use the `compile-testing` library to verify compile-time behavior:
+
+```java
+@Test
+public void testAnnotationProcessing() {
+   Compilation compilation = Compiler.javac()
+       .withProcessors(new ProtoSchemaAnnotationProcessor())
+       .compile(JavaFileObjects.forSourceString("MyClass", source));
+   assertThat(compilation).succeeded();
+}
+```
+
+### Sample Domain Classes
+
+The `sample-domain-definition` and `sample-domain-implementation` modules provide reusable test domain objects (`User`, `Address`, `Account`, etc.) with their `.proto` schemas and marshallers. Use these in tests rather than creating ad-hoc domain classes when possible.
+
+## Running Tests
+
+```bash
+# Run all tests in a module
+./mvnw test -pl core -Dcheckstyle.skip
+
+# Run a single test class
+./mvnw test -pl core -Dtest=ProtobufUtilTest -Dcheckstyle.skip
+
+# Run a single test method
+./mvnw test -pl core -Dtest=ProtobufUtilTest#testMethodName -Dcheckstyle.skip
+
+# Processor tests (must build core+processor first)
+./mvnw install -pl core,processor -DskipTests -Dcheckstyle.skip
+./mvnw test -pl processor-tests -Dcheckstyle.skip
+```
diff --git a/AI.md b/AI.md
new file mode 100644
index 000000000..52a0b7e50
--- /dev/null
+++ b/AI.md
@@ -0,0 +1,17 @@
+# Project Context: ProtoStream
+
+ProtoStream is a Java serialization library based on Protocol Buffers, part of the Infinispan platform. It provides compile-time annotation processing to generate high-performance protobuf marshallers from annotated Java classes, enums, and records.
+
+## Shared guidelines
+- Use the project's established patterns and terminology. When in doubt, follow the conventions of the module you are working in.
+- Prefer clarity over cleverness. This is a long-lived open-source project with many contributors.
+- Be aware of backward compatibility implications — ProtoStream is used as a core dependency by Infinispan and other projects.
+
+## Coding instructions
+When planning and writing code, read and follow the instructions in AI-CODE.md.
+
+## Testing instructions
+When writing or modifying tests, read and follow the instructions in AI-TEST.md.
+
+## Issue creation instructions
+When creating GitHub issues, read and follow the instructions in AI-ISSUES.md.