docs: add AI agent guidelines and security model reference

Author: Croway

AGENTS.md

@@ -0,0 +1,294 @@
+# Apache Camel Spring Boot - AI Agent Guidelines
+
+Guidelines for AI agents working on this codebase.
+
+## Project Info
+
+Apache Camel Spring Boot provides Spring Boot auto-configuration and starter modules for Apache Camel components.
+
+- Version: 4.21.0-SNAPSHOT
+- Java: 17+
+- Build: Maven (use `./mvnw` wrapper)
+- Issue tracker: [JIRA (CAMEL project)](https://issues.apache.org/jira/browse/CAMEL)
+- Related repository: [apache/camel](https://github.com/apache/camel) — Camel core
+
+## AI Agent Rules of Engagement
+
+These rules apply to ALL AI agents working on this codebase.
+
+### Attribution
+
+- All AI-generated content (GitHub PR descriptions, review comments, JIRA comments) MUST clearly
+  identify itself as AI-generated and mention the human operator.
+  Example: "_Claude Code on behalf of [Human Name]_"
+
+### PR Volume
+
+- An agent MUST NOT open more than 10 PRs per day per operator to ensure human reviewers can keep up.
+- Prioritize quality over quantity — fewer well-tested PRs are better than many shallow ones.
+
+### Git branch
+
+- An agent MUST NEVER push commits to a branch it did not create.
+- If a contributor's PR needs changes, the agent may suggest changes via review comments,
+  but must not push to their branch without explicit permission.
+- An agent should prefer to use his own fork to push branches instead of the main
+  apache/camel-spring-boot repository. It avoids filling the main repository with a long list
+  of uncleaned branches.
+- An agent must provide a useful name for the git branch. It should contain the global topic
+  and issue number if possible.
+- After a Pull Request is merged or rejected, the branch should be deleted.
+
+### JIRA Ticket Ownership
+
+- An agent MUST ONLY pick up **Unassigned** JIRA tickets.
+- If a ticket is already assigned to a human, the agent must not reassign it or work on it.
+- Before starting work, the agent must assign the ticket to its operator and transition it to
+  "In Progress".
+- Before closing a ticket, always set the correct `fixVersions` field.
+  Note: `fixVersions` cannot be set on an already-closed issue — set it before closing,
+  or reopen/set/close if needed.
+
+### PR Description Maintenance
+
+When pushing new commits to a PR, **always update the PR description** (and title if needed) to
+reflect the current state of the changeset. PRs evolve across commits — the description must stay
+accurate and complete. Use `gh pr edit --title "..." --body "..."` after each push.
+
+### PR Reviewers
+
+When creating a PR, **always identify and request reviews** from the most relevant committers:
+
+- Run `git log --format='%an' --since='1 year' -- <affected-files> | sort | uniq -c | sort -rn | head -10`
+  to find who has been most active on the affected files.
+- Use `git blame` on key modified files to identify who wrote the code being changed.
+- Cross-reference with the [committer list](https://home.apache.org/committers-by-project.html#camel)
+  to ensure you request reviews from active committers (not just contributors).
+- For component-specific changes, prefer reviewers who have recently worked on that component.
+- For cross-cutting changes (core, auto-configuration), include committers with broader project
+  knowledge.
+- Request review from **at least 2 relevant committers** using `gh pr edit --add-reviewer`.
+- When all comments on the Pull Request are addressed (by providing a fix or providing more
+  explanation) and the PR checks are green, re-request review on existing reviewers so that they
+  are aware that the new changeset is ready to be reviewed.
+
+### Merge Requirements
+
+- An agent MUST NOT merge a PR if there are any **unresolved review conversations**.
+- An agent MUST NOT merge a PR without at least **one human approval**.
+- An agent MUST NOT approve its own PRs — human review is always required.
+
+### Code Quality
+
+- Every PR must include tests for new functionality or bug fixes.
+- Every PR must include documentation updates where applicable.
+- All generated files must be regenerated and committed (CI checks for uncommitted changes).
+
+### Asynchronous Testing: Use Awaitility Instead of Thread.sleep
+
+Do **NOT** use `Thread.sleep()` in test code. It leads to flaky, slow, and non-deterministic tests.
+Use the [Awaitility](https://github.com/awaitility/awaitility) library instead, which is already
+available as a test dependency in the project.
+
+**Example — waiting for a route to be registered:**
+
+```java
+import static org.awaitility.Awaitility.await;
+
+await().atMost(20, TimeUnit.SECONDS)
+       .untilAsserted(() -> assertEquals(1, context.getRoutes().size()));
+```
+
+**Rules:**
+
+- New test code MUST NOT introduce `Thread.sleep()` calls.
+- When modifying existing test code that contains `Thread.sleep()`, migrate it to Awaitility.
+- Always set an explicit `atMost` timeout to avoid hanging builds.
+- Use `untilAsserted` or `until` with a clear predicate — do not replace a sleep with a
+  busy-wait loop.
+
+### Issue Investigation (Before Implementation)
+
+Before implementing a fix for a JIRA issue, **thoroughly investigate** the issue's validity and
+context. Camel is a large, long-lived project — code often looks "wrong" but exists for good
+reasons. Do NOT jump straight to implementation after reading the issue description and the
+current code.
+
+**Required investigation steps:**
+
+1. **Validate the issue**: Confirm the reported problem is real and reproducible. Question
+   assumptions in the issue description — they may be incomplete or based on misunderstanding.
+2. **Check git history**: Run `git log --oneline <file>` and `git blame <file>` on the affected
+   code. Read the commit messages and linked JIRA tickets for prior changes to understand *why*
+   the code is written the way it is.
+3. **Search for related issues**: Search JIRA for related tickets (same component, similar
+   keywords) to find prior discussions, rejected approaches, or intentional design decisions.
+4. **Understand the broader context**: If the issue involves a module that replaced or deprecated
+   another, understand *why* the replacement was made and what was intentionally changed vs.
+   accidentally omitted. Check the [apache/camel](https://github.com/apache/camel) repository
+   for design documents in `proposals/` if the affected area touches core Camel behaviour.
+5. **Check if the "fix" reverts prior work**: If your proposed change effectively reverts a prior
+   intentional commit, stop and reconsider. If the revert is still justified, explicitly
+   acknowledge it in the PR description and explain why despite the original rationale.
+
+**Present your findings** to the operator before implementing. Flag any risks, ambiguities, or
+cases where the issue may be invalid or the proposed approach may conflict with prior decisions.
+
+### Knowledge Cutoff Awareness
+
+AI agents have a training data cutoff and may not know about recent releases, API changes, or
+deprecations in external projects. **Never make authoritative claims about external project state
+based solely on training knowledge.**
+
+- When a JIRA issue, PR, or code references a specific version of an external dependency (e.g.,
+  Spring Boot 4.0, JUnit 6, Jakarta EE 11), **verify it exists** by checking official sources
+  (web search, Maven Central, release notes) before questioning or relying on it.
+- When implementing or reviewing changes that depend on external project behavior, verify the
+  current state rather than assuming training data is up to date.
+- If uncertain about whether something exists or has changed, say so and verify — do not
+  confidently assert something is wrong based on potentially stale knowledge.
+
+### Git History Review (When Reviewing PRs)
+
+When reviewing PRs, apply the same investigative rigor:
+
+- Check `git log` and `git blame` on modified files to see if the change conflicts with prior
+  intentional decisions.
+- Verify that "fixes" don't revert deliberate behavior without justification.
+- Search for related JIRA tickets that provide context on why the code was written that way.
+
+## Security Model
+
+This project shares the same security model as [Apache Camel core](https://github.com/apache/camel).
+The canonical security model document is maintained in the `apache/camel` repository at
+[`docs/user-manual/modules/ROOT/pages/security-model.adoc`](https://github.com/apache/camel/blob/main/docs/user-manual/modules/ROOT/pages/security-model.adoc).
+
+camel-spring-boot is an auto-configuration layer — it wraps Camel components with
+`@ConfigurationProperties` and Spring Boot lifecycle integration but does not define its own
+trust boundaries, consumers, producers, header filtering, or deserialization paths. The Camel
+core security model's trust assumptions, in-scope vulnerability classes, and out-of-scope
+categories apply directly.
+
+When triaging security reports or reviewing security-sensitive PRs in this repository, refer to
+the Camel core security model for:
+
+- **Trust assumptions**: Route authors and deployment operators are fully trusted; external
+  message senders are untrusted.
+- **In-scope classes**: Unsafe deserialization, XXE, expression injection, path traversal, SSRF,
+  header/bean-dispatch abuse, auth bypass, information disclosure, insecure defaults,
+  query injection.
+- **Out-of-scope**: Route-author code, explicit opt-ins, DoS via unthrottled routes, deployer
+  misconfiguration of management surfaces, unreachable transitive CVEs, scanner reports
+  without PoC.
+
+For reporting vulnerabilities, see [`SECURITY.md`](SECURITY.md).
+
+## Structure
+
+```
+camel-spring-boot/
+├── core/                # Core auto-configuration (CamelAutoConfiguration, actuator, vault)
+│   ├── camel-spring-boot/     # Main auto-configuration module
+│   └── camel-spring-boot-xml/ # XML (JAXB) route loading variant
+├── components-starter/  # ~425 generated starter modules, one per Camel component
+├── core-starter/        # Starters for core Camel modules
+├── dsl-starter/         # Starters for Camel DSL modules (YAML, Groovy, Kotlin, etc.)
+├── tooling/             # Maven plugins for code generation (starters, BOMs, catalog)
+├── catalog/             # Spring Boot runtime provider for Camel catalog
+├── tests/               # Integration tests and fat-jar tests
+└── archetypes/          # Maven archetype for new Camel Spring Boot projects
+```
+
+## Build
+
+```bash
+# Build a specific starter (preferred — always build in the module directory)
+cd components-starter/camel-aws2-s3-starter && mvn verify
+
+# Build core module
+cd core/camel-spring-boot && mvn verify
+
+# Fast install (skip tests)
+mvn install -Dfastinstall
+
+# Run a single test
+cd components-starter/camel-aws2-s3-starter && mvn verify -Dtest=S3ComponentTest
+
+# Format/install without tests
+cd <module> && mvn -DskipTests install
+```
+
+Do NOT parallelize Maven jobs — builds are resource-intensive.
+
+## Code Generation
+
+Most code in `components-starter/` is **generated** by the Maven plugins in `tooling/`. For each
+Camel component, the generator produces:
+- `*ComponentAutoConfiguration.java` — Spring Boot `@AutoConfiguration` that registers the
+  component bean
+- `*ComponentConfiguration.java` — `@ConfigurationProperties` class exposing component options
+  as `camel.component.<name>.*`
+- `*ComponentConverter.java` — Type converter for complex property types
+- `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` — Registers
+  auto-configuration classes
+
+Generated code blocks are delimited by `<!--START OF GENERATED CODE-->` / `<!--END OF GENERATED CODE-->`
+in POM files. Do not manually edit generated sections.
+
+### Auto-Configuration Pattern
+
+Each starter's auto-configuration class follows a consistent pattern:
+1. `@AutoConfiguration(after = CamelAutoConfiguration.class)` — ensures CamelContext is available
+2. `@ConditionalOnHierarchicalProperties` — enables/disables via `camel.component.<name>.enabled`
+3. `ComponentCustomizer` bean copies Spring Boot properties onto the Camel component
+
+The core `CamelAutoConfiguration` in `core/camel-spring-boot` is the central configuration that
+all starters depend on.
+
+### Creating/Deleting Starters
+
+```sh
+./starter-create <component-name>    # Create a new starter
+./starter-delete <component-name>    # Delete a starter
+```
+
+These invoke the `camel-spring-boot-generator-maven-plugin` under `tooling/`.
+
+### Relationship with Camel Core
+
+This project depends on `apache/camel` for component implementations. The `camel-version` property
+must match the target Camel release. When Camel core adds/removes/changes a component, the starters
+here must be regenerated.
+
+## Conventions
+
+Code style:
+- Do NOT use Records or Lombok (unless already present in the file)
+- Do NOT change public API signatures without justification
+- Do NOT add new dependencies without justification
+- Maintain backwards compatibility for public APIs
+
+Import style:
+- Do NOT use fully qualified class names (FQCNs) in Java code. Always add an `import` statement
+  and use the simple class name.
+- Exception: when two classes share the same simple name, import the most-used one and qualify
+  the other.
+
+Tests: `*Test.java` (JUnit 5)
+
+## Commits
+
+```
+CAMEL-XXXX: Brief description
+```
+
+Reference JIRA when applicable.
+
+## Links
+
+- https://camel.apache.org/camel-spring-boot/latest/
+- https://github.com/apache/camel-spring-boot
+- https://github.com/apache/camel
+- https://issues.apache.org/jira/browse/CAMEL
+- dev@camel.apache.org
+- https://camel.zulipchat.com/