Adding Capabilities to Existing Camel Applications
Learn how to use Camel Kit to add new capabilities to your existing Apache Camel 4 applications without disrupting working code.
A runnable example fixture is available at fixtures/existing-project-spring-boot with a complete workflow example in fixtures/existing-project-example-workflow. |
Overview
Camel Kit can enhance existing Camel 4 applications in addition to creating new greenfield projects. When you run init on an existing project, Camel Kit:
-
Detects your current Camel version, runtime, and DSL
-
Preserves your
pom.xml, existing routes, and configuration (init writes none of them) -
Adds Camel Kit skills; the shipped skill, guide and shared files are refreshed on every reinit, and files you add next to them are never touched
-
Records the versions your pom declares and uses them instead of upgrading or choosing others
The workflow follows the same design → plan → execute → validate pipeline, but with additional safeguards to protect existing functionality.
Prerequisites
Your existing project must meet these requirements:
-
Camel 4.x (Camel 3.x is not supported - use
/camel-migrateto upgrade first) -
Maven-based project structure
-
One of these runtimes:
-
Spring Boot
-
Quarkus
-
Camel Main / JBang
-
-
YAML routes. Projects whose routes are only XML, Java or Groovy are reported as an unsupported combination, and Karaf (
camel-blueprint) is not supported. Camel Kit never converts the DSL or switches the runtime.
Multi-module Maven projects are supported with .camel-kit/ at the root. |
Safe Adoption
Camel Kit init is safe to run over existing projects with these protections:
| What’s Protected | How |
|---|---|
| Never modified during init |
Maven wrapper ( | Skipped if exists and reported under Existing files preserved, with no proposed copy under |
| Use managed blocks - customizations preserved on reinit |
Skill files | Files Camel Kit ships are refreshed on reinit so they match the installed version. Edit a copy, or add your own file next to them: files Camel Kit does not ship are never touched |
Existing routes | Never modified unless explicitly listed in design spec |
Dry-Run Mode
Preview changes before writing files:
camel-kit init --here --ai claude --dry-run The preview lists shared files with a create, replace, merge or preserve action, using the same ownership and replacement rules as initialization. It does not write files or run baseline tests, even when --record-baseline is also supplied. It also runs the validation of initialization: an existing MCP configuration that cannot be merged, such as a .codex/config.toml that is not valid TOML, is rejected by the preview with the message init would give. See Existing projects for file ownership and --replace <path> behavior.
Getting Started
1. Initialize Camel Kit
From your existing project root:
cd my-existing-camel-app
camel-kit init --here --ai claude Camel Kit detects:
Detected existing Maven project (pom.xml found)
Project graph: 41 nodes, 21 edges
Detected: Apache Camel 4.8.0 on Spring Boot (3 routes)
Generated .camel-kit/config.properties with detected metadata
Generated CLAUDE.md and skills init does not run your project’s build or tests. The baseline test status is recorded as not_run. The test baseline has to exist before anything is edited, because results captured afterwards would include the new changes and hide regressions. There are two ways to get it:
-
Pass
--record-baselinetoinit. It runs./mvnw testonce in your project and writes.camel-kit/baseline-test-results.json. -
Otherwise
/camel-executecaptures it as its first step, before the first edit.
If neither happened, /camel-validate reports baseline preservation as UNVERIFIED. It does not run the tests afterwards and call that the baseline.
.camel-kit/baseline-test-results.json stores the outcome of every individual test ([module:]class#method mapped to passed, failed, error or skipped), the Git revision the tests ran against, whether tracked files had uncommitted changes, and whether all test reports were successfully parsed. Validation compares tests by identity, so a test that now fails, was skipped, or disappeared is a regression even when the number of failures is unchanged.
Camel Kit warns when the project uses an unsupported Camel version (3.x), an unsupported runtime or DSL, or when no routes were found in the project graph. In the last case the route baseline is incomplete, so read the existing route sources before changing them.
2. Review Detected Configuration
Check .camel-kit/config.properties:
project.type=existing
project.runtime=spring-boot
project.camelVersion=4.8.0
project.detectedCamelVersion=4.8.0
project.platformBomVersion=4.8.0
project.springBootVersion=3.3.4
project.primaryDsl=yaml
project.routeCount=3
project.hasTests=true
project.baselineTestStatus=not_run
project.configFilesCount=1 project.modules and project.moduleCount appear only for multi-module projects. project.beansCount counts classes the graph recognizes as beans through annotations such as @Component or @Service, plus entries in a Camel YAML beans: block. Beans registered through @Bean methods in @Configuration classes are not counted. project.configFilesCount counts application*.properties and application*.yml / .yaml files. A key that is missing means discovery found nothing for it, not that the project has none.
project.contractFilesCount counts interface contract files (OpenAPI/Swagger/AsyncAPI documents, WSDL, XSD, protobuf and Avro schemas) and .camel-kit/baseline-contracts.txt lists them. Init only inventories these files so later stages can protect them; it does not analyse their content (tracked in #111).
Only values your project declares are recorded. project.camelVersion comes from the camel.version property, an org.apache.camel dependency, or an imported Camel BOM. project.platformBomVersion is the imported camel-spring-boot-bom or quarkus-bom and project.springBootVersion is the imported spring-boot-dependencies or the spring-boot-starter-parent, with ${property} references resolved from the pom. Nothing is filled in from Camel Kit’s own version tables. If a value cannot be established it is left out and reported as a gap.
If the pom shows two runtimes (for example camel-spring-boot-starter and camel-quarkus-core) or two different Camel versions, Camel Kit does not pick one: project.runtime or project.camelVersion is left out and project.discoveryGaps names the evidence. The workflow stops until you align the pom.
Two further keys appear only when needed:
-
project.discoveryGaps- something discovery could not determine, for example conflicting runtimes or Camel versions, a BOM version that could not be resolved, a pom that could not be read, no routes found in the graph or routes in more than one DSL. The workflow inspects the source for these items and asks you about anything still unclear. -
project.unsupportedCombination- the detected runtime or DSL is outside the supported scope (for example a Karaf runtime, or no YAML routes). The workflow stops instead of guessing; Camel Kit never converts the DSL.
3. Add a New Capability
Start the workflow:
# In Claude Code, VS Code, or your AI agent
/camel-start Claude Code detects this is an existing project and asks:
I’ve analyzed your project:
Camel 4.8.0 on Spring Boot 3.3.4
3 existing YAML routes using rest, timer, and http components
Error handling via
errorHandlerwithdeadLetterChannelTests using Spring Boot Test
What new capability would you like to add to this integration?
4. Design the Addition
The brainstorm phase:
-
Reads your existing routes from the project graph
-
Asks only unresolved questions (doesn’t re-ask about runtime, version, or DSL)
-
Identifies integration points with existing routes
-
Produces a design spec with:
-
Requested Additions - what’s being added
-
Integration Points - how new routes connect to existing ones
-
Affected Files - which files will be modified
-
Unchanged Behavior Constraints - routes that must stay the same
-
5. Plan and Execute
The plan phase:
-
Limits changes to approved scope (won’t modify protected files)
-
Preserves your Camel version (no upgrades)
-
Generates new routes in your primary DSL (currently YAML; XML/Java support tracked in #52)
-
Adds dependencies to your existing
pom.xmlin place. It never replaces the pom with a template, and never changes its parent, BOMs or versions
The execute phase:
-
Captures the per-test baseline before the first edit (unless
init --record-baselinealready did) -
Validates scope compliance before and after each task
-
Verifies no unrelated files are touched
-
Checks that versions stay unchanged
6. Validate
The validate phase:
-
Uses the baseline captured before the edits - it never creates one afterwards
-
Separates concerns - validates new routes separately from existing ones
-
Detects regressions per test - compares each baseline test with its current outcome
## Baseline Test Results
| Test | Baseline | Current | Verdict |
|------|----------|---------|---------|
| com.example.OrderTest#create | passed | passed | OK |
| com.example.OrderTest#cancel | failed | failed | Pre-existing failure |
| com.example.UserTest#lookup | passed | failed | REGRESSION |
VERDICT: REGRESSION - 1 baseline test no longer passes A test that disappeared or is now skipped counts as a regression unless the design spec approves it. When no usable baseline exists, the verdict is UNVERIFIED and the report lists what is missing under Unavailable Evidence.
Worked Example: Add REST Endpoint
Scenario
You have an existing Camel 4.8.0 Spring Boot application with:
-
3 YAML routes (REST API for users and health, timer-based task)
-
Spring Boot 3.3.4
-
Tests using
camel-test-spring-junit5
Goal: Add a new REST endpoint /api/orders that follows the same pattern as the existing /api/users endpoint.
This example is based on the fixture at kit/camel-kit-core/src/test/resources/fixtures/existing-project-spring-boot. The outputs below illustrate the workflow on that Camel 4.8.0 fixture. They are not the record of the live workflow run, which used a different version combination; see Recorded Evidence. |
Step-by-Step
-
Initialize
camel-kit init --here --ai claude -
Start the workflow
/camel-start -
Request the new capability
User: "Add a new REST endpoint
/api/ordersthat returns a list of orders, similar to the existing/api/usersendpoint." -
Brainstorm discovers existing structure
Claude: "I see you have existing REST routes using
rest:DSL and platform-http. Should the new/api/ordersendpoint follow the same pattern as/api/users?"User: "Yes, same pattern."
Claude: "Should I create integration tests similar to your existing
ExistingRoutesTest?"User: "Yes."
-
Design spec generated
The spec includes:
## Requested Additions - New route: `get-orders-api` - REST endpoint: `GET /api/orders` - Response format: JSON array of order objects ## Integration Points | New Route | Connects To | Mechanism | |-----------|-------------|-----------| | get-orders-api | Existing REST infrastructure | Uses same `rest:` DSL and platform-http component | ## Affected Files - `src/main/resources/camel/order-routes.yaml` (CREATE) - `src/test/java/org/apache/camel/kit/test/fixture/OrderApiTest.java` (CREATE) ## Unchanged Behavior Constraints - `/api/users` route: MUST remain unchanged - `application.properties`: MUST NOT modify - `pom.xml`: MUST NOT modify (all components already present) -
Plan generated
Tasks include:
-
Create
order-routes.yamlwith new REST route -
Create integration test
-
Validate scope compliance (verify only approved files touched)
-
Verify existing functionality (rerun existing tests)
-
-
Execution
Task 1: Create order-routes.yaml Task 2: Create OrderApiTest Task 3: Validate scope compliance Modified files: order-routes.yaml, OrderApiTest.java (approved) No protected files touched Camel version unchanged (4.8.0) Task 4: Verify existing functionality Existing tests: 3 passed (baseline preserved) New tests: 4 passed -
Validation report
# Validation Report (Existing Project Enhancement) ## Baseline Preservation - Existing routes (3): All passed validation - Existing tests (3): All passed - No regressions detected ## New Capabilities Validation - New route: get-orders-api - PASS - Integration tests: OrderApiTest (4 tests) - PASS VERDICT: Baseline Preserved, New Capability Works
Supported Combinations
| Runtime | Camel Versions | DSL | Status |
|---|---|---|---|
Spring Boot 4.1.1 | 4.22.1 | YAML | Live workflow recorded (design → approval → plan → execute → validate), outcome |
Spring Boot 3.3.4 | 4.8.0 | YAML | Fixture tests only. No live workflow acceptance; see Runtime Catalog Version |
Spring Boot | 4.4.x - 4.7.x | YAML | Expected to work (not tested); see Runtime Catalog Version |
Quarkus | 3.15.x (Camel 4.8.x) | YAML | Expected to work (not tested); see Runtime Catalog Version |
Camel Main | 4.8.x | YAML | Expected to work (not tested) |
Karaf ( | Any | Any | Not supported (reported as |
Camel 3.x | Any | Any | Not supported (use |
Recorded Evidence
Two separate evidence sets stand behind the table above. They used different versions and must not be combined.
| Fixture tests | Live workflow run | |
|---|---|---|
Combination | Camel 4.8.0, Spring Boot 3.3.4, YAML | Camel 4.22.1, Spring Boot 4.1.1, YAML, Temurin 21.0.8 |
What ran | The seven application tests of the checked-in fixture and worked example: three existing-route tests and four tests for the added endpoint | The installed workflow from design through explicit human approval, plan, execute and validate, on 2026-11-13, adding |
Result | The fixture’s tests pass. No agent-driven workflow was accepted on this combination | 3 of 3 baseline tests and 16 of 16 final tests passed, 17 of 17 HTTP probes passed against the running application, and the file, dependency-version and reinitialization preservation checks passed |
Outcome | Fixture-level only |
|
The live run is summarized in the acceptance summary on issue #167. It was a local run of one example. It is not a production certification, and its limits are part of the result:
-
Static-analysis results from before the edits were not available, so the run does not show that static-analysis findings were unchanged.
-
Some commands named in the workflow guides were not supported in that environment. The schema and endpoint checks were recorded with working alternatives: checks against the pinned schema and MCP catalog, and checks against the running application.
-
Other runtimes and version combinations, other DSLs, and the end-to-end workflow across multiple modules were outside the run. Nothing in it measures them.
Limitations
Runtime Catalog Version
Camel Kit starts the Camel MCP server at the version pinned by camel.mcp.version in distribution.properties, which was 4.22.1 when this page was last checked (2026-11-17). With that runner, a Spring Boot or Quarkus catalog request for a Camel version other than the server’s own can be answered with the server’s version, combining component metadata of the requested target with newer EIP and model metadata (CAMEL-26926). The recorded live run was not exposed to this, because the application and the MCP server were both on 4.22.1.
When a catalog response reports a Camel version that differs from the one requested, or from the version recorded in project.camelVersion:
-
Stop the version-bound validation and report the affected checks as unverified. Do not accept the result as evidence for your project’s version.
-
Do not upgrade the application to match the MCP server. Camel Kit never changes the versions of an existing project, and a version upgrade belongs to
/camel-migrate.
CAMEL-26926 is fixed in the Camel source, with the fix assigned to Camel 4.18.6, 4.22.3 and 4.24.0. That does not change the runner Camel Kit installs, and it does not establish end-to-end acceptance for older-target Spring Boot or Quarkus applications. Before relying on a fixed combination, confirm that the MCP artifact is published, that Camel Kit pins it, and that a catalog request for your target version returns that version.
Version 1 Scope
-
Multi-module projects - Discovery supports multi-module Maven projects with
.camel-kit/at the root. Full end-to-end workflow validation across multiple modules is tracked in follow-up work -
YAML DSL only - Version 1 supports YAML DSL. XML, Java and Groovy routes are detected and reported through
project.unsupportedCombinationwhen no YAML routes exist, but the workflow stops instead of planning additions (broader Java DSL support is tracked in issue #52) -
Discovery is a starting point - The graph reads Maven poms, Java/Groovy/XML/YAML routes,
beans:blocks andapplication*.properties/application*.yml. Anything else, such as beans created by@Beanmethods, is not counted and is listed inproject.discoveryGapsor must be inspected in the source -
One runtime - Cannot mix Spring Boot and Quarkus in the same project
Troubleshooting
"No Maven version detected"
Cause: pom.xml uses ${camel.version} property but doesn’t define it, or no Camel version is declared at all. Camel Kit never guesses a version for an existing project.
Fix: Define the property:
<properties>
<camel.version>4.8.0</camel.version>
</properties> "Conflicting runtimes" or "Conflicting Camel versions"
Cause: The pom shows more than one runtime (for example both Spring Boot and Quarkus Camel artifacts) or more than one Camel version (for example camel.version is 4.8.0 but a camel-core dependency says 4.10.0).
Fix: Align the pom. Until then project.runtime or project.camelVersion is not recorded, and /camel-plan and /camel-execute stop. project.discoveryGaps lists the files and artifacts that disagree.
"Unsupported Camel version 3.x"
Cause: Your project uses Camel 3.x.
Fix: Use the migration workflow:
/camel-migrate "Mixed DSL detected"
Cause: Your project has both YAML and XML routes.
Fix: New routes use YAML and the other DSLs are never converted. If you want consistency:
-
Choose one DSL
-
Convert routes to that DSL
-
Reinitialize Camel Kit
"Tests failed after adding capability"
Cause: Regression introduced.
Fix: Check the validation report:
### Regression Analysis
New failures detected:
- TestName: testExistingUserRoute()
Baseline: PASS
Current: FAIL
Reason: Bean 'userDatabaseBean' not found The new route may have accidentally removed a shared bean. Review the execution report and revert problematic changes.
Best Practices
Before You Start
-
Commit your changes -
git commitbefore runningcamel-kit init -
Run tests - Verify existing tests pass
-
Use dry-run - Preview changes with
--dry-run
Next Steps
-
Learn about Camel Kit pipeline
-
Explore available skills
-
Read about design rules
-
See Getting Started for greenfield projects
Current documentation and decisions
See current system documentation and ADRs for the shared lifecycle, stage ownership, documentation-only reconciliation, source-bound review evidence and verification limits.