The migration workflow converts existing integrations from other platforms to Apache Camel 4.x using YAML DSL. Instead of manual rewriting, the AI analyzes your existing artifacts, builds a dependency graph, and assembles one migration design package with flow-specific sections. After you approve that complete package once, Camel-Kit creates one implementation plan, executes its tasks in dependency waves, runs one project-wide runtime verification pass, and finishes with report-only static validation. Verification and validation record failures, skipped checks, and unavailable tools rather than claiming that every run is fully validated.
Supported platforms:
MuleSoft Mule 3.x/4.x
Microsoft BizTalk Server
Apache Camel 2.x/3.x (including Red Hat Fuse)
Migration Workflow Steps
The migration workflow follows six core steps that apply across all supported platforms. Each step builds on the previous one, ensuring a systematic and verifiable migration.
Initialize for Migration
Navigate to your existing project directory and initialize Camel-Kit with migration support:
cd my-existing-project
camel-kit init --here --ai claude --source-platform <platform>
Key flags:
--here — initialize in the current directory (preserves your existing source)
--source-platform — optionally hint the source platform (mulesoft, camel, or biztalk); omit it to use auto
What gets written or added:
📁- my-existing-project/
📁- src/Your existing source (unchanged)
📄- pom.xmlYour existing POM (unchanged)
📁- **mvnw**Written/refreshed: Maven wrapper launcher for Linux and macOS
📁- **mvnw.cmd**Written/refreshed: Maven wrapper launcher for Windows
📁- **camel-kit-personas/**New: fourteen complete role definitions for subagents
📁- **docs/**
📁- **flows/**New: empty initialization scaffold
📁- **test/**
📁- **data/**New: empty initialization scaffold
📁- **schemas/**New: empty initialization scaffold
📁- **.camel-kit/**
Your existing source files and pom.xml remain untouched. Camel-Kit adds the AI orchestration layer, writes or refreshes the Maven wrapper files, and creates the empty compatibility scaffolds shown above. Migration outputs later use the selected runtime’s paths.
Run the Migration Command
Invoke the migration orchestrator:
/camel-migrate
The AI begins the migration pipeline, coordinating all subsequent steps automatically. You’ll be prompted for platform-specific configuration (connector endpoints, credentials, environment mappings) during the process.
The migration command:
Detects the source platform and artifact types
Analyzes dependencies between flows
Builds one source-analysis and design package with flow-specific sections
Presents that complete package for one design approval
Creates one implementation plan and executes all tasks in dependency waves
Runs one project-wide runtime verification pass, then produces the final static validation report
Vendor Detection and Artifact Discovery
The AI scans your project to identify the source platform and discover all integration artifacts:
Migration order — migrate dependencies before dependents
Flow-specific design — preserve each flow’s behavior and dependencies inside the complete migration package
Dependency waves — independent tasks can share a wave and run concurrently when the selected AI target supports it
Impact analysis — understand which flows are affected by changes
Service wiring — DI-aware analysis traces dependencies through @Inject/@Autowired annotations and across interface boundaries, catching service chains that route-level analysis alone would miss
The migration-context command performs a bounded, bidirectional BFS around one route, with depth 3 by default and at most 50 related nodes. It returns local graph context — detected routes, components, services, Maven artifacts, configuration properties, and warnings — rather than a complete dependency chain. The command performs no MCP call; when needed, the migration skill can query the Knowledge MCP later as a separate documentation lookup.
If circular dependencies are detected, the AI prompts you to break the cycle (see Troubleshooting below).
Complete Migration Design
The AI analyzes every discovered flow and records flow-specific requirements and technical decisions in one migration design package:
Analyzing migration package:
- customer-lookup-flow
- order-validation-flow
- fulfillment-flow
Open design questions:
1. What triggers this flow? (HTTP request, scheduled poll, message queue, etc.)
2. What data transformations occur?
3. What external systems are called?
4. What error handling is required?
5. What are the success/failure criteria?
Generating docs/camel-kit/<pipeline-id>/business-requirements.md...
Generating docs/camel-kit/<pipeline-id>/design-spec.md...
Presenting the complete package for approval...
Design-package artifacts:
business-requirements.md — business logic extracted from the complete source, organized with flow-specific requirements
design-spec.md — technical specifications for the complete migration, including per-flow components, EIPs, and test cases
Camel-Kit presents both documents together and waits for one explicit design approval. That approval authorizes the single downstream plan, execution, verification, and validation sequence.
Plan and Execute
After the complete requirements and design are approved, the AI automatically invokes the planning and execution pipeline (the same pipeline used for greenfield development). For a Spring Boot or Quarkus target, generated routes and tests use the Maven source layout:
For Camel Main, routes and application.properties are generated at the module root; tests remain under src/test/resources.
What happens:
/camel-plan creates one detailed implementation plan from the approved migration design package
/camel-execute groups all plan tasks into dependency waves
Each wave generates the required Camel YAML routes and Citrus integration tests; independent tasks can run concurrently when the selected AI target supports it
After all tasks finish, /camel-execute runs one project-wide runtime verification pass and records the outcome
The pipeline invokes /camel-validate once for final static quality analysis
There is no flow-by-flow approval or deployment loop. The single design approval authorizes the complete downstream sequence.
Internal Verification and Validation
camel-verify runs internally as part of /camel-execute. Unlike the flow-specific Citrus tests generated during implementation, this project-wide pass checks the complete migrated application, runs the applicable Citrus suite across the generated routes, and embeds its verification evidence in docs/camel-kit/<pipeline-id>/execution-report.md. Failed, skipped, or unavailable checks are recorded there; they do not prevent the report-only /camel-validate stage from running.
Runtime verification:
Build / Startup Smoke — compile Spring Boot or Quarkus with the Maven wrapper or system Maven; run a startup smoke test for Camel Main
Behavioral Tests — run discovered Citrus end-to-end scenarios when the required tools are available; tests that declare Testcontainers additionally require Docker
Report — record the runtime, Maven selection, phase outcomes, applied fixes, skipped checks, and any final error
Example output from a successful run:
VERIFICATION REPORT (embedded in execution-report.md)
Runtime: Spring Boot
Maven: ./mvnw (wrapper)
Phase 1 — Build / Startup Smoke: PASS (1 fix)
Phase 2 — Test: PASS: 8/8 tests passed
Fixes applied:
1. [Build] Added the verified runtime dependency required by a migrated route
Skipped checks:
(none)
After runtime verification records its outcome in execution-report.md, the pipeline invokes /camel-validate:
Camel-Kit keeps flow-specific analysis and design detail while planning the migration as one approved package. /camel-execute schedules that plan in dependency waves: prerequisites run before their dependents, while independent tasks are concurrency candidates on AI targets that support parallel dispatch.
Benefits:
Traceability — each migrated route maps back to its source flow and design section
Dependency-safe execution — prerequisite tasks finish before dependent tasks start
Bounded parallelism — independent tasks may share a wave without implying that every AI target runs them concurrently
Complete-system evidence — one project-wide verification section in execution-report.md covers the assembled migration before final static validation
This progress describes tasks within one migration package; it does not imply that individual flows were separately approved, verified project-wide, or declared ready for deployment.
Cause: DataWeave scripts (MuleSoft) or BizTalk maps may use platform-specific functions that do not translate directly to the supported Camel-Kit mapping paths.
Resolution:
Review the selected mapping strategy: inline Groovy when both schemas are absent or the mapping has fewer than 20 leaf fields; XSLT only when the mapping has at least 20 leaf fields and at least one schema
Compare input/output examples from the original DataWeave/map
Confirm and record unsupported constructs as required custom mapping or processor actions
Add behavioral tests to validate the transformation
Example:
Selected strategy: XSLT
Reason: Source and target schemas are available and the mapping has 24 fields.
Unsupported function: source platform custom lookup
Required action: implement and test a custom processor for that lookup
Missing Component Equivalent
Symptom:
Warning: No direct Camel equivalent for connector
Source: Salesforce Connector (MuleSoft)
Recommendation: Use camel-salesforce component with manual configuration
Cause: Some platform-specific connectors may not have exact Camel equivalents, or require additional configuration.
Resolution:
Consult the approved design specification and the verification evidence embedded in execution-report.md for suggested Camel components and recorded gaps
If no component exists, implement a custom processor or use a catalog-verified HTTP component for a documented API fallback
Update the approved design specification and regenerate its stale downstream artifacts
Common mappings:
Salesforce Connector → camel-salesforce
SAP Connector → camel-sap-netweaver or camel-sap-hana
Database Connector → camel-sql or camel-jpa
File Connector → camel-file
HTTP Request → camel-http
Verification Fails
Symptom:
Verification failed: Behavioral test failure
Test: order-validation-flow-integration-test
Expected: 200 OK
Actual: 500 Internal Server Error
Cause: The migrated route may have incorrect configuration (endpoint URLs, credentials, transformation logic) or missing dependencies.
Resolution:
Review the test failure details (stack trace, logs)
Check the migrated route configuration against the original flow
Verify that connector credentials and endpoints are correctly configured
Run the test in debug mode to inspect data at each step
If the issue is environmental (e.g., missing database), document it in the verification section of execution-report.md before deciding whether to proceed
Debugging steps:
In the commands below, replace {module}/ with the target module’s relative path,
or omit the entire prefix when the target is the project root.
# In your AI agent, diagnose the broken migrated route/camel-debug
# Run a generated Citrus test in isolationcamel test run {module}/src/test/resources/order-validation-flow.camel.it.yaml
# Inspect a Spring Boot or Quarkus routecat {module}/src/main/resources/camel/order-validation.camel.yaml
# Camel Main places the route at the module root insteadcat {module}/order-validation.camel.yaml
Summary
The migration workflow automates platform conversion through six steps:
Initialize — add Camel-Kit to your existing project
Detect — discover artifacts and identify the source platform
Graph — analyze dependencies and determine migration order
Design — write one business-requirements.md and design-spec.md package with flow-specific sections
Plan and implement — create one implementation plan, then generate Camel routes and Citrus tests in dependency waves through /camel-execute
Verify and validate — record one project-wide runtime verification outcome, then run /camel-validate for the final report-only static quality analysis
This workflow applies across all supported platforms. For platform-specific details (artifact formats, connector mappings, known limitations), see the platform pages below.