CAMEL-23701: Make generated archetype projects more AI-relevant

[k-krawczyk]

Summary

Applies the same treatment as CAMEL-23702 (#24063), but to the Maven archetypes instead of the JBang export.

• Renames ReadMe.txt to README.md in all six archetypes and rewrites the content in Markdown, with the documentation links refreshed to https and to the current camel.apache.org/manual/writing-components.html location.
• Adds an AGENTS.md to every generated project: the Apache Camel LLM index (https://camel.apache.org/llms.txt), the .html -> .md documentation trick, a pointer to the Camel CLI and the Camel MCP server with an explicit "do not invent component URIs or options" instruction, plus the project layout, the build/run commands and the conventions of that archetype.
• Updates the six archetype-metadata.xml file sets accordingly — the readme is listed explicitly there, so the rename alone would have silently dropped it.
• Adds a camel-archetypes entry to the 4.23 upgrade guide. When this PR was opened, camel-4x-upgrade-guide-4_23.adoc did not exist yet and the PR created it; main has since been prepared for 4.23 and created the file itself, so after the rebase this PR only adds a section to it.
• camel-archetype-spring states in both generated files that the archetype is deprecated, pointing at Camel on Spring Boot or camel init.

Drive-by fix

camel-archetype-api-component declared its readme in the __artifactId__-component/ file set while the file actually lives at the project root, so no readme was generated at all. Reproduced against the released archetype:

mvn archetype:generate -DarchetypeGroupId=org.apache.camel.archetypes \
  -DarchetypeArtifactId=camel-archetype-api-component -DarchetypeVersion=4.21.0 ...

produces a project with pom.xml and the two modules, and no readme. This PR moves the entry to a root file set, so the readme is generated again.

Notes

The .md file sets are deliberately left unfiltered, as ReadMe.txt was. Markdown headings start with #, which is the Velocity directive prefix, so the generated docs are kept free of interpolation rather than risking mangled output. Consequently the content uses no ${artifactId}-style placeholders.

Verification

• ./mvnw install -Dquickly -f archetypes/pom.xml — BUILD SUCCESS.
• mvn archetype:generate run for all six archetypes against the locally installed 4.22.0-SNAPSHOT: README.md and AGENTS.md are generated at the root of every project, with no unresolved ${...} or __x__ tokens.
• The generated content was checked against the actual generated trees (MainApp / MyRouteBuilder, MyApplication / MyBean / MyConfiguration, camel-context.xml, META-INF/services/.../<scheme>, the DataFormat implementation), so it does not describe files that are not there.
• apache-rat-plugin:check on the archetypes module: 0 unapproved (**/*.md is excluded in the root POM).
• All referenced URLs return HTTP 200, including the .md variant of the manual page.

The archetype integration tests under src/test/resources/projects-disabled are disabled, so verification was done by generating projects manually as described above.

Reported by Claude Code on behalf of Karol Krawczyk

[orpiske]

I did a quick manual review and it looks good to me. Thanks @k-krawczyk !

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[davsclaus]

Nice work — this is a clean, well-structured PR that follows the pattern established by #24063 (JBang export). The camel-archetype-api-component bug fix is confirmed valid (the ReadMe.txt was declared in the __artifactId__-component/ fileSet but the file lives at the project root, so no readme was ever generated).

One required change: the upgrade guide entry needs to move to the 4.23 guide since 4.22.0 is being built and released. The camel-4x-upgrade-guide-4_23.adoc file doesn't exist yet, so it will need to be created.

Minor suggestions (non-blocking):

• The camel-archetype-spring AGENTS.md could mention that this archetype is deprecated and suggest Spring Boot instead, so AI agents don't invest effort in a deprecated project unknowingly.
• The camel-archetype-dataformat AGENTS.md reference link points to writing-components.html — inherited from the old readme and probably the closest available page, but slightly off-target for data formats.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

[davsclaus]

Just mind that 4.22.0 is released soon so this PR will go into 4.23. But we need to wait until main branch has been prepared for this.

[github-actions]

🧪 CI tested the following changed modules:

• archetypes/camel-archetype-api-component
• archetypes/camel-archetype-component
• archetypes/camel-archetype-dataformat
• archetypes/camel-archetype-java
• archetypes/camel-archetype-main
• archetypes/camel-archetype-spring
• docs

---

🔬 Scalpel shadow comparison — Scalpel: 7 tested, 0 compile-only — current: 6 all tested

Maveniverse Scalpel detected 7 affected modules (current approach: 6).

⚠️ Modules only in Scalpel (1)

• docs

Skip-tests mode would test 7 modules (7 direct + 0 downstream), skip tests for 0 (generated code, meta-modules)

Modules Scalpel would test (7)

• camel-archetype-api-component
• camel-archetype-component
• camel-archetype-dataformat
• camel-archetype-java
• camel-archetype-main
• camel-archetype-spring
• docs

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

All tested modules (7 modules)

• Camel :: Archetypes :: API Component
• Camel :: Archetypes :: Component
• Camel :: Archetypes :: Data Format
• Camel :: Archetypes :: Java Router
• Camel :: Archetypes :: Main
• Camel :: Archetypes :: Spring XML Based Router (deprecated)
• Camel :: Docs

---

⚙️ View full build and test results

[k-krawczyk]

Thanks @davsclaus, @orpiske, @oscerd and @Croway for the reviews. All three points are addressed in f9b9947.

Required change — upgrade guide moved to 4.23. The entry is now in a new camel-4x-upgrade-guide-4_23.adoc, created with the same header as the other guides and a == Upgrading Camel 4.22 to 4.23 section, and removed from the 4.22 guide. I also added the xref for it in camel-4x-upgrade-guide.adoc, otherwise the new page would be orphaned from the index.

On the timing: I created the 4.23 guide here so the PR is complete, but I understand the merge should wait until main has been prepared for 4.23. If you would rather create that file yourself as part of preparing the branch, say so and I will drop it from this PR and rebase.

Suggestion 1 — deprecated Spring archetype. Both the README.md and the AGENTS.md of camel-archetype-spring now state that the archetype is deprecated and point at Camel on Spring Boot or camel init, so an agent knows before investing effort. Good catch.

Suggestion 2 — data format link. The camel-archetype-dataformat docs now reference https://camel.apache.org/manual/data-format.html for the concept, next to the existing writing-components page for the implementation details. Link verified.

Re-verified after the change: archetypes rebuild, apache-rat-plugin:check reports 0 unapproved, and I regenerated projects from the spring and dataformat archetypes to confirm the new content lands correctly.

Reported by Claude Code on behalf of Karol Krawczyk

[atiaomar1978-hub]

Code review (Bugbot + Grok)

AI-generated review on behalf of @atiaomar1978-hub

Solid follow-up to CAMEL-23702 / #24063 — the README.md + AGENTS.md direction for archetypes is exactly what AI-assisted contributors need. The api-component readme fileSet fix is a real bug fix (verified: readme was silently dropped). Velocity left unfiltered for # headings is the right call.

Bugbot: no bugs found.

Grok + manual check: a few doc accuracy issues undermine the AI-guidance goal — mostly packaged path layout in java/main archetypes and one incorrect registration hint. Details in inline comments.

Verdict: Request changes on the inline items; happy to re-review once fixed and CI is green.

[atiaomar1978-hub]

These paths omit the package directory. The java sources fileSet uses packaged="true", so generated projects place classes under src/main/java/<package>/MyRouteBuilder.java and .../MainApp.java, not at the src/main/java/ root.

Please use <package>/MyRouteBuilder.java (or src/main/java/<package>/...) so agents don't create default-package files.

[atiaomar1978-hub]

MainApp registers routes explicitly via main.configure().addRoutesBuilder(new MyRouteBuilder()) — there is no component/package scanning in this archetype.

Suggest: "Add routes as RouteBuilder classes and register them on Main the same way as MyRouteBuilder." Drop the scanning clause to avoid misleading agents.

[atiaomar1978-hub]

Same packaged-layout issue as AGENTS.md: with packaged="true", routes and MainApp live under src/main/java/<package>/, not directly under src/main/java/. Align README with the actual generated tree.

[atiaomar1978-hub]

The main archetype also uses packaged="true" for Java sources. Listing flat src/main/java/MyRouteBuilder.java, MyApplication.java, etc. will mislead agents — please document src/main/java/<package>/... (same for the test class on line 18).

[atiaomar1978-hub]

Worth adding the actual registration hook from the generated template: @org.apache.camel.spi.annotations.Dataformat("<scheme>") on the DataFormat class (plus keeping getDataFormatName() in sync). This archetype does not use a META-INF/services file — agents may invent one without this hint.

[atiaomar1978-hub]

Minor clarity: line 27 says proxies/config are generated — this line then says "Annotate the endpoint with @UriEndpoint..." which could imply editing generated code.

Suggest splitting: hand-written endpoint/configuration classes may use @UriEndpoint / @UriParam; generated API proxies and collections from camel-api-component-maven-plugin should not be hand-edited.

[atiaomar1978-hub]

Creating/linking the 4.23 upgrade guide while main is still on 4.22.0-SNAPSHOT may be premature (see @davsclaus feedback on similar PRs). Fine to keep the file in this PR, but consider holding merge until main is bumped to 4.23 — otherwise the index advertises a 4.23 guide from a 4.22 tree.

[atiaomar1978-hub]

Test coverage follow-up

AI-generated on behalf of @atiaomar1978-hub

Checked automated test coverage for this PR — no test files are added or modified. Verification is manual only (as noted in the PR description). That gap is worth addressing given the api-component readme regression this PR fixes.

Current state

Area	Coverage
This PR	0 test file changes across 26 files
Archetype ITs	Exist under src/test/resources/projects-disabled/ in all 6 archetypes — projects-disabled means they do not run in CI (Maven archetype plugin expects projects/)
JBang precedent (CAMEL-23702 / #24063)	ExportTest.shouldGenerateContent and shouldGenerateJavaContent assert AGENTS.md and readme.md exist after export — automated guard for the same feature on the JBang side
Archetypes module	archetype.test.skip=true under skipTests, fastinstall, and release profiles

What manual verification covers (per PR)

✅ mvn archetype:generate for all six archetypes
✅ README.md + AGENTS.md present at project root
✅ No unresolved ${...} / __x__ tokens
✅ URL checks

What is not guarded by CI

• README.md / AGENTS.md emitted at all (regression like api-component readme in wrong fileSet)
• api-component readme at project root vs under *-component/ module
• Doc content accuracy (packaged paths, @Dataformat, etc.)
• Upgrade guide index linkage

Suggestions (pick one — ordered by ROI)

Option A — Minimal archetype IT (recommended)
Rename projects-disabled → projects for at least build-it goal on each archetype (or start with api-component + java). Extend the generated-project assertion to verify:

README.md exists at project root
AGENTS.md exists at project root
no ReadMe.txt
(api-component) README.md NOT only under *-component/

This would have caught the pre-4.22 api-component bug automatically.

Option B — Shared unit test in archetypes/ parent
One parameterized JUnit test (similar spirit to ExportTest) that runs archetype:generate into a temp dir for each archetype artifactId and asserts the two markdown files exist. Keeps ITs disabled but adds a fast smoke test in default CI.

Option C — Follow-up JIRA
If enabling ITs is blocked on ARCHETYPE-574 (noted in archetype.properties), open a follow-up to re-enable once fixed — but Option B could land independently.

Verdict on test coverage

Insufficient for merge without follow-up — acceptable for docs-only archetype change if manual verification is repeated each release, but not ideal for a change whose main bug was silent fileSet misconfiguration. Recommend Option A or B in this PR or an immediate follow-up before 4.23.

Happy to re-review if tests are added.

[atiaomar1978-hub]

Test coverage: This fileSet fix is exactly the kind of regression automated archetype ITs would catch — before this PR, ReadMe.txt was listed under artifactId-component/ while the file lived at project root, so no readme was generated (reproduced on 4.21.0). Consider adding/re-enabling a build-it archetype IT that asserts README.md and AGENTS.md exist at the generated project root.

[atiaomar1978-hub]

Test coverage: No automated test validates generated AGENTS.md presence or content. JBang ExportTest already asserts AGENTS.md exists after export (#24063). Archetypes have IT scaffolding under src/test/resources/projects-disabled/ but it is disabled — a minimal smoke IT per archetype would lock this in.

[k-krawczyk]

Thanks @atiaomar1978-hub — the inline findings were all correct and are fixed in 376bf6a. I verified each one against the templates rather than taking them at face value, and each held up:

• Packaged layout (java, main). Both archetypes declare packaged="true" on the src/main/java fileSet, so the generated classes land under src/main/java/<package>/. The readme and AGENTS.md now say so. This one is embarrassing on my side: I had the generated trees in front of me when verifying the original change and never diffed them against the paths I had written.
• No route scanning in the java archetype. MainApp registers explicitly with main.configure().addRoutesBuilder(new MyRouteBuilder()), so the scanning clause is gone and the guidance points at that call instead.
• Data format registration. The template carries @org.apache.camel.spi.annotations.Dataformat("${scheme}") and has no META-INF/services file, so AGENTS.md now documents the annotation and keeping getDataFormatName() in sync.
• api-component clarity. Split as suggested: the plugin-generated API proxies must not be hand-edited, while the endpoint and configuration classes under *-component/src/main/java are hand-written and carry @UriEndpoint / @UriParam.

Re-verified after the change: archetypes rebuild, apache-rat-plugin:check reports 0 unapproved across all seven modules, and I regenerated the java and main projects to compare the documented paths against the actual tree.

On the 4.23 upgrade guide — agreed, and that matches @davsclaus. The file is here so the PR is complete; if you would rather it landed with the branch preparation, I will drop it and rebase.

On test coverage

You are right that this change is unguarded, and that the api-component fileSet bug is exactly what an automated check should have caught. I looked into both of your options before answering, and neither works as written:

Option A — enabling the archetype ITs. goal.txt for build-it is install, so the IT does not just generate a project, it builds it with Maven: resolving dependencies and compiling the generated sources. On top of that archetype.properties carries a TODO pointing at ARCHETYPE-574, and archetype.test.skip=true is set in the skipTests, fastinstall and release profiles. This looks deliberately disabled rather than forgotten, so re-enabling it is a CI cost decision for a committer, not something I want to slip into a docs PR.

Option B — a JUnit smoke test in the archetype modules. This does not run at all today. I added a trivial test and executed mvn test on camel-archetype-java: with packaging=maven-archetype the test phase runs eight goals — enforcer, license, formatter, impsort, resources, generate-and-attach-archetype-catalog, testResources — and neither compiler:testCompile nor surefire:test is among them. The test is never compiled, let alone executed. Making it work needs explicit plugin bindings added to the archetype poms.

What I would suggest instead. The bug class here is a mismatch between archetype-metadata.xml and the files on disk. That is checkable without generating or building anything: parse each archetype-metadata.xml, resolve every <fileSet> directory plus its concrete <include> entries against archetype-resources/, and assert that each one exists and that README.md and AGENTS.md are declared somewhere. Milliseconds, no network, no new dependencies — and it would have failed on the api-component bug before this PR.

It still needs somewhere to live, which means either adding testCompile and surefire bindings to the six archetype poms, or a small jar module under archetypes/. That is a structural change to the archetypes module and belongs in its own ticket rather than here. I am happy to open a follow-up JIRA and implement it — just say which placement you would accept.

Reported by Claude Code on behalf of Karol Krawczyk

[atiaomar1978-hub]

Bugbot & Grok Re-Review Report

AI-generated review on behalf of the operator.

PR: CAMEL-23701 — Make generated archetype projects more AI-relevant
HEAD: 376bf6a65
Verdict: Approve with follow-ups — prior inline accuracy issues are fixed; direction is solid; merge should wait until main is prepared for 4.23 (per @davsclaus).

---

Executive summary

This is a clean follow-up to CAMEL-23702 / #24063 (JBang export). All six archetypes now emit README.md + AGENTS.md with the shared LLM/CLI/MCP guidance block. The api-component readme fileSet bug (readme silently never generated) is a genuine fix. Velocity left unfiltered for # headings is the correct tradeoff.

Prior review threads (packaged paths, java no-scan, @Dataformat registration, api hand-written vs generated, spring deprecation, 4.23 upgrade guide) are addressed in f9b994720 / 376bf6a65.

---

Bugbot findings

Must-fix

#	Finding
1	Hold merge until main is on 4.23 — Root pom.xml is still 4.22.0-SNAPSHOT, but this PR adds camel-4x-upgrade-guide-4_23.adoc with == Upgrading Camel 4.22 to 4.23. Matches @davsclaus: ship when branch is prepared, not while advertising a 4.23 guide from a 4.22 tree.

No blocking bugs in generated markdown or metadata at HEAD.

Should-fix

#	File	Finding
2	camel-archetype-main/.../AGENTS.md:26-29	MyApplication uses new Main(MyApplication.class) (MyApplication.java:31), which package-scans for RouteBuilder and @Configuration beans in the same package. AGENTS only mentions @BindToRegistry / explicit registration — omits that routes/config in <package> are auto-discovered. Agents may invent addRoutesBuilder or place routes outside the scanned package. (Java archetype correctly says it does not scan.)
3	camel-archetype-dataformat/.../AGENTS.md:28 and README.md:21	Still links writing-components.html for "Writing the implementation". That page covers Component/Endpoint SPI, not DataFormat. data-format.html (line 27) is the right concept page. Drop or reword the writing-components link so agents aren't sent to component SPI docs.
4	Test coverage gap	Zero test file changes. Archetype ITs live under projects-disabled/ (not run in CI). The api-component fileSet bug this PR fixes is exactly what an automated check would catch. Author's proposed metadata-vs-disk validation test is a good follow-up JIRA — recommend tracking before 4.23.
5	Review threads	reviewDecision is still CHANGES_REQUESTED. Prior inline findings appear fixed at HEAD — resolve outdated threads and re-request review so approvers re-check latest commits.

Nice-to-have

#	Finding
1	Component/dataformat AGENTS use flat src/main/java while fileSets are packaged="true" — java/main were fixed to <package>/; align for consistency.
2	Pre-existing wrong name="camel-archetype-java" on several archetype-metadata.xml descriptors (component, dataformat, spring, main) — not introduced here.
3	Dataformat AGENTS says "stream instead of buffering" but stub template uses byte[] — add one-liner that stub is illustrative.
4	Velocity unfiltered .md tradeoff is correct; if personalization wanted later, use #[[ ... ]]# literal sections.

---

Grok findings

Design assessment

Area	Assessment
README.md rewrites	Clear Markdown; https links; AI section → AGENTS.md + llms.txt ✅
AGENTS.md ×6	Shared "don't invent URIs" block matches JBang agents.md.ftl pattern ✅
archetype-metadata.xml	All six declare README.md + AGENTS.md; api root fileSet fix restores silent-drop bug ✅
api-component readme bug	Confirmed: was under __artifactId__-component/, file at project root — never generated ✅
Spring deprecation	README + AGENTS Status sections; points to Spring Boot / camel init ✅
Upgrade guide	Informational only (existing projects keep ReadMe.txt); 4.23 placement correct per timing discussion ✅
Velocity filtering	.md fileSets intentionally unfiltered — # headings safe; no ${artifactId} in titles ✅
RAT / build	**/*.md excluded in root POM; ./mvnw install -Dquickly -f archetypes/pom.xml passes ✅

Prior fixes verified at HEAD (376bf6a65)

Issue	Status
Packaged layout paths (java, main)	✅ Fixed — src/main/java/<package>/...
Java archetype: no route scanning	✅ Fixed — explicit addRoutesBuilder
Data format: @Dataformat annotation, no META-INF/services	✅ Fixed
api-component: generated vs hand-written split	✅ Fixed
Spring deprecation notice	✅ Fixed
Upgrade guide moved to 4.23	✅ Fixed

What looks good

• Drive-by api-component fileSet fix prevents silent readme omission
• Manual verification documented (archetype:generate ×6, token checks, URL 200 checks)
• Content checked against actual generated trees (not generic boilerplate)
• Consistent AGENTS structure across all six archetypes
• No Velocity interpolation risk in markdown headings

---

Test coverage (re-confirmed)

Area	Status
Test files changed	0
Archetype ITs	Under projects-disabled/ — not run in CI
JBang precedent (#24063)	ExportTest asserts AGENTS.md / readme.md — archetypes have no equivalent
Author's Option A (enable ITs)	Blocked: build-it runs full install, ARCHETYPE-574, archetype.test.skip=true
Author's Option B (JUnit in archetype poms)	Blocked: packaging=maven-archetype skips surefire today
Suggested follow-up	Metadata-vs-disk validation (no generate/build) — good JIRA candidate

Verdict on tests: Acceptable for docs-only change with manual verification, but not ideal given the bug class. Track follow-up JIRA before 4.23.

---

Recommended actions

1. Before merge: Wait for 4.23 branch prep (@davsclaus)
2. Author: Fix main archetype AGENTS package-scan guidance; reword dataformat writing-components link
3. Reviewers: Resolve fixed inline threads; re-request review on HEAD
4. Follow-up JIRA: Archetype metadata fileSet validation test (author proposal)

---

Bottom line: Ready to approve once 4.23 timing is right and the two remaining AGENTS doc gaps are addressed (or tracked as follow-ups). The api-component fix and AGENTS.md direction are valuable contributions.

[davsclaus]

Nice work on this PR — the archetype modernization and the AGENTS.md additions are well done, and the api-component readme bug fix is a real fix (confirmed that ReadMe.txt was declared in the __artifactId__-component/ file set but lived at project root, so no readme was ever generated).

Highlights:

• Each AGENTS.md is properly tailored to its archetype (api-component describes the multi-module layout and signature files; dataformat describes marshal/unmarshal conventions; spring notes the deprecation).
• The unfiltered file sets for .md files correctly avoid Velocity interpreting Markdown # headings as directives.
• Upgrade guide entry is clean and follows the existing pattern.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

[k-krawczyk]

Rebased onto main (cd29991cf36d) — the branch was 45 commits behind and had become conflicting.

There was exactly one conflict, an add/add on docs/user-manual/modules/ROOT/pages/camel-4x-upgrade-guide-4_23.adoc. When this PR was opened that file did not exist, so the PR created it; main has since been prepared for 4.23 and created the file itself, with a camel-a2a section. Both sections are kept, camel-a2a first, then camel-archetypes.

Two follow-on effects of main catching up, both benign:

• The PR no longer touches camel-4x-upgrade-guide-4_22.adoc. The entry was originally added there and moved to 4.23 in f9b9947; main's 4.22 guide never had it, so the net diff against main is now empty for that file.
• The PR no longer touches the upgrade guide index either — main added the xref for the 4.23 guide as part of preparing the branch, and the two changes coincided, so there is no duplicate link.

Nothing outside the upgrade guide changed in the rebase: the diff against main is still the same 24 archetype files, +333/-104 in total. I re-checked that camel-archetypes appears once in the 4.23 guide, that all six archetype-metadata.xml files are well-formed and declare README.md and AGENTS.md, and that no source file still references ReadMe.txt.

The verification section in the description was run before the rebase, against 4.22.0-SNAPSHOT. I have not re-generated the six projects since; the rebase touched only the docs, so the generated output is unaffected.

@davsclaus — you noted that this should wait until main was prepared for 4.23. That has happened (main is on 4.23.0-SNAPSHOT), and the conflict is resolved, so this is ready to merge whenever it suits you.

Reported by Claude Code on behalf of Karol Krawczyk