End-user guide for designing, implementing, and verifying Apache Camel integrations with AI coding assistants.
Camel-Kit is an AI-powered toolkit that guides you through designing, planning, implementing, and validating Apache Camel integrations. Instead of writing boilerplate code by hand, you work with an AI coding assistant that follows a structured pipeline: understand the requirements, design the integration, plan and execute the implementation, verify it at runtime inside execute, and run the final static validation stage.
| Concept | What It Is |
|---|---|
| Business Requirements | The requirements output from the brainstorm phase. Captures business purpose, systems landscape, flow summaries, and integration requirements. |
| Design Spec | The pipeline design contract. Describes each flow's source, processing steps, sink, error handling, data transformation, configuration, dependencies, and test criteria. |
| MCP (Model Context Protocol) | Real-time catalog queries. The AI assistant queries the Camel MCP server to verify components, EIPs, data formats, and expression languages exist in your exact Camel version -- never relying on training data. |
| Constitution | Eight route quality rules enforced on every generated route: route structure, single responsibility, separation of concerns, naming conventions, observability, external configuration, component support verification, and infrastructure via Forage. |
| Iron Laws | Six non-negotiable pipeline rules: MCP catalog verification, constitution compliance, no code without an approved design and task plan, spec compliance before quality, adversarial review before staged review, and surgical changes. |
Before diving into commands and workflows, it helps to understand the principles behind Camel-Kit's design. These explain why the pipeline is structured the way it is and what makes it different from simply asking an AI assistant to generate code.
The most common way to use an AI coding assistant is: describe what you want, get code back. For simple tasks this is fine. For enterprise integrations -- multiple systems, error handling, data transformation, version-specific configuration -- this approach consistently produces code that looks correct but fails at runtime.
The problem is not that AI is bad at writing code. The problem is that it skips understanding. It never asks “what should happen when Kafka is unavailable?” or “do you need idempotent processing?” -- it guesses, and its guesses are drawn from training data that may be outdated or wrong for your version.
Camel-Kit enforces a strict separation: understand before designing, design before planning, plan before coding. The design phase has a deliverable that you approve before anything else proceeds. After design approval, planning and execution flow continuously.
This means you are never surprised by what the AI produces. If the design is wrong, you catch it before any code exists. If the plan is wrong, you catch it before code is generated.
There is a critical difference between a rule and a gate. A rule says “you should verify components before using them” -- the AI can skip this when it feels confident. A gate says “you cannot write this component into the spec until MCP confirms it exists” -- there is no way to proceed without satisfying the condition.
Camel-Kit uses gates everywhere:
| Gate | What It Blocks |
|---|---|
| User approval after design | Cannot start planning until you confirm the design spec matches your intent |
| Environment probe | Cannot start implementing until all applicable checks pass; runtime-specific or unavailable checks are recorded as skipped, while runtime startup remains required |
| MCP catalog verification | Cannot use a component until the live catalog confirms it exists in your Camel version |
| Constitution validation | Routes without a routeId, with hardcoded credentials, or with unsupported components fail validation -- not warned, failed |
| Two-stage review | Spec compliance is checked before code quality. Cannot skip to quality review on a route that doesn't match the design. |
As a user, gates mean you stay in control. The AI cannot build momentum on a wrong assumption because the pipeline physically blocks it from advancing.
AI assistants know about Apache Camel from their training data -- broadly but imprecisely, and often months out of date. Camel-Kit replaces this with skills: structured instruction files that teach the AI exactly how to perform each task.
Skills tell the AI:
All supported targets use shared markdown skills with agent-specific traits and native configuration.
When an AI generates code and reviews its own work, it tends to confirm its own choices. Camel-Kit prevents this:
This is why you may see the AI fix something during review that it didn't catch during implementation -- each review applies a distinct contract, with fresh context where the agent supports it.
Code that passes static analysis can still fail at runtime -- wrong component options for the target version, missing dependencies at startup, external services not running. Research has shown that AI models cause approximately 30% of runtime errors that are invisible to static analysis (Li et al., “Environment-in-the-Loop”, ICSE 2026). The fix is not better prediction -- it is actual execution in a real environment.
Camel-Kit applies this principle through its verification loop (now internal to /camel-execute), which implements a structured feedback loop. For standalone quality checks after execution, use /camel-validate:
The key idea: every error is classified against a structured Camel-specific taxonomy, and each classification has a deterministic fix target. A ClassNotFoundException means a missing dependency in pom.xml -- the loop fixes it and retries. A FailedToCreateRouteException means broken route YAML -- the loop routes the fix to the implementation skill. An unclassified error is escalated to you with a structured diagnosis.
This means:
The verification loop treats code, dependencies, and the execution environment as a single unit that must co-evolve. For a Maven-based route using Kafka, full Docker-backed verification ensures the matching dependency is in pom.xml, the broker is available, and the connection properties are configured -- not just that the route YAML is syntactically correct. Camel Main and unavailable Docker paths report their non-applicable checks as skipped.
Technology Preview: Camel Ship is still being stabilized. Its behavior and interfaces may change, and it is not recommended for production use. For the established staged workflow, start with /camel-start.
The standalone /camel-ship workflow additionally requires Linux. Its default backend needs Pi and Node; eligible Bob 2, Copilot CLI, Claude Code and OpenAI Codex CLI sessions can use their own native children. See Bob native Ship, Copilot native Ship, Claude Code native Ship and Codex CLI native Ship. Its current deterministic evidence path accepts Camel Main projects with Camel YAML DSL route artifacts; Spring Boot and Quarkus Ship projects are not yet supported.
This guide describes Camel Kit 0.4.1. The standalone CLI and the 0.4.1 Camel JBang plugin provide the equivalent camel-kit and camel kit command forms. Development continues at 0.4.2-SNAPSHOT; see installation for release and development channels.
# Install JBang if you don't have it curl -Ls https://sh.jbang.dev | bash -s - app setup # Create a new project (choose your AI assistant) camel-kit init order-processing # IBM Bob 2 (default) camel-kit init order-processing --ai claude camel-kit init order-processing --ai bob2 # IBM Bob 2 camel-kit init order-processing --ai antigravity camel-kit init order-processing --ai codex camel-kit init order-processing --ai copilot camel-kit init order-processing --ai pi camel-kit init order-processing --ai qwen camel-kit init order-processing --ai opencode
To initialize inside an existing directory:
camel-kit init --here --ai claude camel kit init --here --ai codex
Use --ai bob2 for both Bob Shell and Bob IDE. These entry points are verified with Bob Shell 2.0.2 and Bob IDE 2.1.0. In Bob Shell, start from the initialized project root, open /skills or type $camel-, and select one of the nine public skills: camel-start, camel-brainstorm, camel-migrate, camel-plan, camel-execute, camel-validate, camel-ship, camel-knowledge, and camel-debug. Enter the request after the skill name, for example:
$camel-migrate MuleSoft flows in src/main/mule $camel-ship --document requirements.md --text "Preserve HTTP status codes"
Bob Shell's native skill picker uses $camel-*. Its / picker contains built-in commands and MCP prompts; /camel-* workflow names in this guide correspond to $camel-* skills in Bob Shell. Bob IDE exposes the same native skills through /camel-*. Legacy command stubs remain installed for compatibility. $camel-ship forwards the supplied options to the registered camel-kit ship or camel kit ship command once, without adding defaults.
Generated .bob/skills/*/SKILL.md files set both user_invocable: true and user-invocable: true for the nine public skills. The four internal helpers remain hidden. The verified Shell and IDE versions skip migrating .bob/commands/ stubs when same-name native skills already exist, so those stubs cannot repair hidden skill metadata or create duplicate entries.
Run camel-kit doctor (or camel kit doctor) to diagnose hidden public skills. Doctor reports each affected SKILL.md as FAIL with regeneration instructions, including when a nested metadata.user-invocable value overrides the top-level field.
If only $camel-start appears in the skill picker, upgrade to a build containing the #213 fix, exit Bob, and regenerate from the project root using the same command surface as the original initialization:
camel-kit init --here --ai bob2 --force # Or, for a workspace initialized through the Camel JBang plugin: camel kit init --here --ai bob2 --force
Commit or back up customized generated files first: --force overwrites them. Restart Bob after regeneration. Earlier 0.4.0-SNAPSHOT builds can still contain the defect. Until you upgrade, set both invocation fields to true only in the nine public skills listed above, then restart Bob; leave internal helpers unchanged. Regeneration with an older build overwrites that workaround. MCP prompts such as /camel:camel_migrate_pr are separate from Camel-Kit's migration workflow.
All defaults (Camel version, BOM versions, MCP server versions) are read from a built-in distribution.properties file. You can override any property in two ways:
Per-invocation overrides (highest priority):
camel-kit init my-integration --ai claude -p "camel.main.version=4.18.4"
Persistent user config (applies to all invocations): Create ~/.camel-kit/config.properties with your overrides:
camel.main.version=4.18.4 camel.quarkus.version=4.18.3 quarkus.platform.version=3.33.3.2
Or point to a custom config file:
camel-kit init my-integration --ai claude -c /path/to/my-config.properties
The resolution order is: -p flags > -c file (or ~/.camel-kit/config.properties) > built-in JAR defaults.
When you run camel-kit init in a terminal that supports a native image protocol (Kitty, iTerm2, Sixel), the command displays a split-screen TUI with a logo on the left and a live task list on the right. The TUI shows animated progress for each initialization step and exits automatically when all tasks complete.
In terminals without image support, the output falls back to an ASCII art banner above colored text.
The tree below is a union reference. init creates the shared project files plus only the agent-native assets selected by --ai; it does not generate all target layouts together.
order-processing/
.camel-kit/
config.properties # Project config (Camel version, runtime)
docs/
constitution.md # 8 route quality rules
.mcp.json # MCP server config (agent-specific location)
AGENTS.md # Codex, Pi, or OpenCode project instructions
.agents/skills/ # Codex project skills when --ai codex is selected
.codex/
config.toml # Codex project MCP servers
agents/ # Codex custom agents
.github/ # GitHub Copilot CLI assets when --ai copilot is selected
.pi/ # Pi skills, prompt templates, and guard extension when --ai pi is selected
pom.xml # Maven project with Camel BOM
mvnw / mvnw.cmd # Maven wrapper
The init command checks prerequisites (Java, JBang, Camel JBang, test plugin), copies skill files, configures MCP, and sets up the Maven wrapper so you can start designing immediately. If the target directory already contains a camel-kit project (AGENTS.md or .camel-kit/), init warns and exits — use --force to overwrite.
With --ai codex, both camel-kit init and the Camel JBang plugin form camel kit init generate repository-scoped Codex resources. Trust the repository so Codex can load .codex/config.toml; Codex also skips any user-added project hooks until trust. Then start with $camel-start; /skills lists project skills and /mcp shows the three configured servers. Camel-Kit preserves unrelated valid project config, does not create .codex/commands/, and does not change global Codex settings, authentication, or hooks.
After initialization, run doctor from the workspace root:
camel-kit doctor # or, when installed as a Camel JBang plugin: camel kit doctor
doctor checks the generated configuration, command stubs where applicable, skill files, runtime-supported MCP filtering and permission fields, project graph, command prefix, prerequisites, and common stale generated references. It also verifies that internal skills such as camel-verify are present as skills but not exposed as user command stubs. For Codex, it validates the TOML config, the camel, camel-knowledge, and citrus server allowlists and prompt approval modes, plus required fields in all custom-agent files. It prints PASS, WARN, and FAIL findings with remediation text. External tools such as JBang and Camel JBang are reported as warnings when unavailable; broken generated workspace files are failures.
For automation:
camel-kit doctor --json camel kit doctor --json
Camel-Kit follows a four-stage pipeline: Design, Plan, Execute, Validate. You approve the design output, then planning, execution, and static validation auto-proceed under that approval.
/camel-start is the meta-router. In order, it selects migration for existing MuleSoft, BizTalk, Fuse, or Camel 2.x/3.x source; planning for an approved design spec; execution for an implementation plan; validation for generated routes; debugging for build, startup, or runtime failures outside a pipeline; and brainstorming for new or unclear work.
Each pipeline run creates a directory under docs/camel-kit/ to persist artifacts across sessions:
docs/camel-kit/001-order-processing/ business-requirements.md <- migration only migration-analysis.md <- migration only design-spec.md <- brainstorm output (Phase 1) migration-runbook.md <- migration only; operational companion to the design implementation-plan.md <- plan output (Phase 2) execution-report.md <- execute output (Phase 3) validation-report.md <- validate output (Phase 4)
For migration, provenance runs from business requirements to migration analysis to design, then branches. The migration-runbook.md and implementation-plan.md are independent direct children of design-spec.md; planning never uses the runbook as input.
Starting a pipeline:
# Generate a pipeline ID and create the directory camel-kit nextId order-processing # Output: 001-order-processing
When using the Camel JBang plugin, run camel kit nextId order-processing instead.
The pipeline state is tracked in .camel-kit/pipeline.json, which records the active pipeline ID. Each skill reads this file to know where to find and save artifacts.
Session resilience: Because all artifacts are saved to disk, you can close your session and resume later. The pipeline picks up where you left off based on which artifacts already exist.
Every pipeline stage supports standalone invocation. Brainstorm uses a pipeline ID for new or amend mode; plan, execute, and validate use it to load their inputs from disk. Migration accepts an optional pipeline ID for a package-only run. Standalone stages do not auto-invoke the next stage:
# Run plan standalone (reads design-spec.md from disk) /camel-plan 001-order-processing # Run execute standalone (reads implementation-plan.md from disk) /camel-execute 001-order-processing # Build a migration package standalone /camel-migrate 002-legacy-orders
In standalone mode, skills read their input from pipeline artifacts on disk instead of conversation context, and they do NOT auto-invoke the next stage. This enables:
If you need to change a design spec after downstream artifacts have been generated:
# Amend an existing design spec /camel-brainstorm 001-order-processing
When brainstorm detects that design-spec.md already exists, it enters amend mode:
camel-kit doc stale --reason "design spec was amended" --cascade <child-path> -- implementation-plan.md, plus migration-runbook.md for migration pipelinesStaleness is tracked in structured YAML frontmatter within each artifact. You can check any artifact's status:
camel-kit doc check docs/camel-kit/001-order-processing/implementation-plan.md
To regenerate stale implementation artifacts, run each stale stage standalone: /camel-plan 001-order-processing, then /camel-execute 001-order-processing. Re-planning does not regenerate the independent migration-runbook branch; a stale runbook must be regenerated by /camel-migrate before operational use.
See camel-kit doc for the full CLI reference.
/camel-brainstorm)The design phase is an interactive interview that produces the design spec. The AI asks questions one at a time -- never in batches -- to understand your integration before designing it.
What it covers:
Output: Business requirements and a design spec under docs/camel-kit/<PIPELINE_ID>/.
After the user reviews and approves the design spec, the pipeline transitions automatically to the plan phase.
/camel-plan)The plan phase reviews the approved design spec and decomposes it into bite-sized implementation tasks. The plan is a recipe, not the meal -- it describes exactly what to generate and how, without containing any generated code.
What it produces:
yaml plan-metadata with file, logical, and explicit task dependencies for wave analysisOutput: An implementation plan (docs/camel-kit/<PIPELINE_ID>/implementation-plan.md).
The structured metadata block mirrors the Markdown tasks. Each task entry includes id, title, grouped files, logical provides and consumes resources, and explicit dependsOn task IDs. Logical resources include endpoints, routes, properties, schemas, test data, beans, external services, and route contracts. Older Markdown-only plans still work, but new plans use the metadata block so /camel-execute can avoid parallelizing tasks with hidden dependencies.
After the plan is complete, the pipeline transitions automatically to the execute phase. There is no separate plan approval gate -- the design approval authorizes all downstream work. The environment probe (first step of execute) validates feasibility before code generation begins.
/camel-execute)The execute phase runs all tasks from the plan autonomously, without pausing between tasks. It first analyzes task dependency waves, probes the target environment, and batch-verifies the Camel catalog artifacts needed by each wave. For each task, it orchestrates:
camel-implement -- generates Camel YAML routes, properties, pom.xml dependencies, and DataMapper transformations from the approved design spec and implementation plancamel-test -- generates Citrus integration tests After each task's implementation, an adversarial critic pre-filter runs before the sequential spec-compliance and code-quality reviews. Subagent-capable targets use independent moderator and critic contexts. If a review fails, the task is sent back for fixes before moving on. After all tasks complete, execute performs a cross-cutting review and dispatches camel-verify once for the 3-phase build-or-smoke, Citrus-test, and report loop.Output: Working YAML routes, test files, an execution report, and a verification report.
Bean generation and review follow the infrastructure order: Forage, then component scalar configuration, then a custom bean if needed. Custom beans prefer verified declarative constructors/properties, factory methods or supported builders. The target runtime and library API must support the chosen form, including argument conversions and cleanup. Scripts remain available when initialization cannot be expressed declaratively, with a concrete reason recorded beside the bean. Missing verification is reported as a concern, not treated as proof that a script is required. This preference does not change message transformations or DataMapper engine selection.
/camel-validate)Validation is the final, static quality gate. It checks route schemas, endpoint URIs, project-relative quality thresholds, security, anti-patterns, and all constitution rules. It reports findings without modifying the routes. Pipeline-scoped runs write docs/camel-kit/<PIPELINE_ID>/validation-report.md; a standalone project-scoped run with no pipeline writes docs/validation-report-YYYY-MM-DD_HH-mm.md.
Suppose you need an order processing integration that reads orders from Kafka, validates and enriches them, then writes to a PostgreSQL database.
# 1. Initialize the project camel-kit init order-processing --ai claude cd order-processing # 2. Start the workflow (in your AI assistant) /camel-start # The AI asks about your business requirements, systems, and data flows. # After the interview, it presents a design spec with: # - Business requirements covering the order processing domain # - Flow design for order-ingestion (Kafka -> validate -> enrich -> PostgreSQL) # - Error handling: dead letter queue on kafka:orders-dlq # You review and approve the design. # 3. /camel-start routes to /camel-brainstorm, then the pipeline auto-transitions to /camel-plan # The AI creates an implementation plan with tasks: # Task 1: Project scaffolding (pom.xml, application.properties) # Task 2: Order ingestion route (Kafka source, SQL sink) # Task 3: Integration tests # No separate plan approval — pipeline auto-transitions to /camel-execute. # 4. /camel-execute starts with the environment probe, then implements # The AI executes all tasks: # - Generates route YAML with MCP-verified components # - Validates against the constitution # - Generates Citrus tests # - Runs verification (build, startup, behavioral) # Final report shows all tasks completed.
/camel-migrateUse /camel-migrate when you have an existing integration built on another platform and want to move it to Apache Camel.
/camel-migrate
| Platform | Versions | What It Scans |
|---|---|---|
| MuleSoft Mule | 3.x, 4.x | XML flows, DataWeave transformations, connectors |
| Apache Camel | 2.x, 3.x | Java DSL, XML DSL, Blueprint |
| JBoss Fuse | 6.x, 7.x | Fuse-specific configurations and components |
| Microsoft BizTalk | 3.x, 4.x | Orchestrations (.odx), maps (.btm), pipelines (.btp), bindings (.xml) |
MuleSoft migrations now benefit from the project graph. When a project contains MuleSoft XML files, the graph automatically detects them via XML namespace sniffing (mulesoft.org/schema/mule) and parses all flows, sub-flows, connectors, endpoints, transforms, error handlers, and DataWeave scripts. The migration skill gets instant flow topology -- connectors used per flow, sub-flow call chains, DataWeave complexity -- without manual XML deep-dives.
Previously, only Maven dependencies were captured in the graph for MuleSoft projects. Now, the MuleXmlFlowParser and DataWeaveParser provide full structural analysis of the source project.
DataWeave .dwl files are analyzed for version declarations, input/output content types, function definitions, and field access patterns. This helps identify complex transformations that need manual attention during migration -- multi-function scripts, recursive field access, or format conversions that have no direct XSLT equivalent.
BizTalk migrations now benefit from the project graph. When a project contains BizTalk artifacts, the graph automatically detects them via XML namespace sniffing (schemas.microsoft.com/BizTalk) and parses all orchestrations, maps, pipelines, and port bindings. The migration skill gets instant artifact topology -- adapters used per orchestration, map functoid complexity, pipeline component chains, port bindings -- without manual XML deep-dives.
The BizTalkParser analyzes:
This helps identify proprietary BizTalk patterns that need manual attention during migration -- scripting functoids, custom pipeline components, WCF-specific configurations.
BizTalk-to-Camel adapter mapping highlights:
| BizTalk Adapter | Camel Equivalent | Notes |
|---|---|---|
| FILE | file | Direct drop-in replacement for file system operations |
| FTP / FTPS | ftp / ftps | Connection pooling via Camel configuration |
| SFTP | sftp | SSH key authentication supported |
| SQL | sql / jdbc | sql for queries, jdbc for batch operations |
| WCF-BasicHttp / WCF-WSHttp | cxf | SOAP 1.1/1.2 support via camel-cxf |
| HTTP / HTTPS | http / https | RESTful endpoint support |
| MSMQ | jms | Map to ActiveMQ or other JMS provider |
| SMTP / POP3 / IMAP | mail | All from camel-mail artifact |
| MQ Series | jms | Via IBM MQ JMS bindings |
| SAP | sap | Requires SAP JCo libraries (licensed) |
--source-platform flag: Auto-detection works in most cases (no flag needed). For projects with non-standard layouts, use --source-platform {platform} to explicitly declare the source platform:
camel-kit init my-migration --ai claude --source-platform mulesoft camel-kit init my-migration --ai claude --source-platform biztalk
The command scans all project artifacts, detects the source platform automatically, and builds one migration package:
Phase 1: Business Analyst -- reads all source files and builds a complete inventory of flows and connectors. Identifies which components have direct Camel equivalents and which are proprietary (e.g., Anypoint MQ). For proprietary connectors, it presents alternatives and lets you decide. Then it asks only the business questions the source code cannot answer -- purpose, SLAs, compliance requirements.
Behavioral analysis -- materializes migration-analysis.md between the two vendor phases. It records each behavioral assumption, evidence gap, and risk as Confirmed, Inferred, or Unknown, with its evidence, impact, validation, owner, and disposition. It never treats the whole migration as API-compatible by default.
The same artifact includes a source-retirement candidate audit. A usable graph accelerates and corroborates the audit; without one, bounded source scanning produces the same coverage, reachability, broken-reference, candidate, and evidence-gap sections. Candidates remain in scope unless a specific user-approved exclusion is backed by named owner and runtime validation evidence; approving the package alone is not that decision.
Migration strategy -- classifies each independently switchable scope as Incremental candidate, Single cutover required, or Undetermined - evidence needed, after reconciling every discovered ingress/root into exactly one non-overlapping scope. Incomplete, conflicting, TBD, or merely structural operational evidence stays undetermined. Incremental or strangler guidance is included only when the existing controllable seam is currently confirmed and the target conditions are confirmed design constraints with pre-cutover validation obligations. This identifies design candidacy, not cutover readiness. Single cutover required needs a named validated source and operational-control boundary with a closed, operator-confirmed inventory plus complete confirmed evidence that every seam candidate inside it is absent or unsafe; anything outside or unconfirmed remains undetermined. The business requirements record the result under Migration Strategy, and the design carries it into Migration Strategy Constraints.
Phase 2: Integration Architect -- maps each source component to its Camel equivalent, converts transformations (e.g., DataWeave to field mapping tables), and asks only what the source artifacts cannot answer (authentication details, retry strategy, missing endpoint URLs).
Operational runbook -- after the final design and Camel Main eligibility checks, generates migration-runbook.md from the validated package, current operational evidence, and explicit operator decisions. The runbook is registered as a direct child of the design. It preserves every scope classification and referenced MIG-###/SRC-### status; it does not turn an Incremental candidate or Single cutover required classification into cutover readiness, and it gives an undetermined scope no concrete cutover procedure. The runbook covers ownership, prerequisites, configuration and data readiness, deployment, cutover entry/actions/exit, operational validation, rollback, reconciliation, soak, and the separate source-retirement decision.
Missing operational facts appear exactly as Unknown — operator decision required: <missing fact>. Camel-Kit does not invent commands, endpoints, thresholds, durations, contacts, owners, environment values, or credentials. Credential material is never copied into the runbook; only validated secret references may be recorded.
The migration produces business requirements, the behavioral analysis, a design spec compatible with /camel-brainstorm, and the operational runbook. This means the implementation pipeline is identical:
/camel-migrate --> /camel-plan --> /camel-execute --> /camel-validate
The migration output is fully compatible with the greenfield pipeline. From the plan phase onward, there is no difference between a migrated project and a greenfield project; camel-plan consumes the design spec, not the runbook. Approving the four-artifact migration package allows the pipeline to proceed to planning, but does not resolve recorded unknowns or authorize source exclusions, infrastructure provisioning, deployment, operating an external traffic control, cutover, traffic switching, rollback, message/data reconciliation, or source retirement. Retirement requires a separate named operator decision after operational validation, reconciliation, and soak have passed; every operational action still requires the named operator's separate execution-time authorization.
/camel-verify (Internal to /camel-execute)Verification is a structured 3-phase feedback loop that builds the project, runs Citrus integration tests via camel test run, diagnoses errors, applies fixes, and retries until all tests pass or the iteration limit is reached. Citrus tests are self-contained: Testcontainers manage external services and camel:jbang:run starts the Camel integration within the test.
When it runs:
/camel-execute, after all implementation tasks and their reviews complete/camel-verify is not a standalone user-facing command. For standalone quality checks after execution, use /camel-validate.| Phase | What It Does |
|---|---|
| 1. Build Verification | Compiles Spring Boot or Quarkus projects with Maven and classifies build errors. Camel Main runs its startup smoke test instead. |
| 2. Test Verification | Runs Citrus integration tests via camel test run. Citrus tests are self-contained: Testcontainers start external services, camel:jbang:run starts the Camel integration, send/receive actions validate behavior. |
| 3. Report | Structured summary of all phases, fixes applied, and issues found. |
Each phase uses a structured error taxonomy organized by build/smoke and test failures. Every error is classified into a category with a fix target:
| Fix Target | Examples |
|---|---|
| Self-repair | Missing dependency in pom.xml, missing property in application.properties, Docker service restart |
| Route to internal handling | Wrong component options (static diagnosis/report via /camel-validate, then implementation correction), broken route YAML, test syntax error |
| Re-plan | Persistent architectural failures trigger automatic design-spec modification via the re-plan loop (max 3 rounds) |
| Escalate to user | Unclassified errors, same error after fix attempt, iteration limit (15) reached, re-plan limit (3) reached |
Verification adapts to available tools. If Maven is missing, build verification is skipped. If Docker is unavailable, test verification is skipped (Testcontainers requires Docker). If the camel test CLI is unavailable, test verification is skipped. Every skipped phase is reported explicitly -- nothing fails silently.
Camel-Kit automatically handles data transformation during the design phase. The AI determines the transformation engine, gathers field mappings, and writes the canonical mapping specification to the design spec. Implementation is handled by /camel-execute.
| Engine | When Used | Output |
|---|---|---|
| XSLT | 20 or more field mappings AND at least one schema exists | External .xsl file, xslt-saxon: URI in route, .kaoto metadata for Kaoto IDE visual editing |
| Groovy | Fewer than 20 field mappings, OR no schemas for both source and target | Inline Groovy script in YAML route, no external files |
The engine is chosen automatically during the design phase. You do not need to pick one -- the rules are applied based on your field mappings and schemas:
XSLT:
{flow-name}-datamapper-{id}.xsl)xslt-saxon: URI.kaoto metadata file for Kaoto IDE visual editingGroovy:
XSLT transformations include Kaoto DataMapper metadata, allowing you to visually edit field mappings in the Kaoto IDE after generation. Groovy transformations have no visual editor support -- they are edited directly in the YAML route file.
| Type | Example |
|---|---|
| Direct copy | orderId --> orderId |
| Nested flattening | order.customer.name --> customerName |
| Date formatting | ISO 8601 --> dd-MM-yyyy |
| Concatenation | firstName + lastName --> fullName |
| Calculation | price * quantity --> lineTotal |
| Conditional (IF) | IF amount > 1000 THEN HIGH ELSE NORMAL |
| Conditional (CHOOSE) | Switch-case style multi-branch logic |
| Collection iteration | FOR-EACH items[], transform each item |
| Parameter usage | Use Camel headers/variables in transformation |
When working with existing projects -- whether migrating from another platform, extending an established codebase, or validating a generated project -- Camel-Kit can build a property graph of the entire project structure. The graph captures classes, methods, Camel routes, endpoints, Maven dependencies, configuration properties, and -- for MuleSoft projects -- flows, sub-flows, connectors, endpoints, transforms, error handlers, and DataWeave scripts, and -- for BizTalk projects -- orchestrations, shapes, maps, functoids, pipelines, pipeline components, ports, and adapters. Typed edges represent the relationships between nodes (extends, calls, routes-from, routes-to, depends-on, configures, flow-contains, calls-subflow, uses-connector, references-dwl, biztalk-orchestration-contains, biztalk-uses-map, biztalk-uses-schema, biztalk-calls-orchestration, biztalk-port-binding, biztalk-functoid-chain, biztalk-pipeline-stage).
| Capability | What It Does | When It Helps |
|---|---|---|
| Route flow tracing | Follows the complete message path through a route chain, including cross-route links via direct:, seda:, and vm: endpoints | Understanding how data flows end-to-end through a multi-route integration |
| Impact analysis | Traces upstream and downstream dependencies of any node -- a route, a class, a configuration property | Before changing a shared bean or endpoint, knowing which routes will be affected |
| Retirement-candidate detection | Reports graph-covered unused-dependency, unreferenced-route, and stale-property candidates for owner validation | Reviewing possible leftovers without claiming they are dead or safe to remove |
| Route topology mapping | Maps route-to-route connections to determine which routes are independent | Claude uses this to dispatch independent routes to parallel subagents during /camel-execute |
| Project norm extraction | Computes statistical norms from the codebase -- naming patterns, error handling coverage, route complexity (P75 step count) | Validation uses project-specific thresholds instead of hardcoded defaults |
| DI-aware dependency tracking | Detects dependency injection annotations (@Inject, @Autowired, @Value, @ConfigProperty) and creates USES_TYPE edges for injected fields and constructor parameters | Understanding which services are injected into routes, processors, or beans -- traces dependencies across interface boundaries |
| Property-based bean wiring | Parses application.properties for Camel's PropertyBindingSupport syntax (#class:, #bean:, #autowired, #type:) to discover beans instantiated or referenced in configuration | Finding beans that exist only in properties files, not in source code -- critical for migration projects where beans are configured via properties |
| Interface expansion | Creates DEPENDS_ON_VIA_INTERFACE shortcut edges and expands queries to traverse across interface boundaries via GraphQuery.expandWithInterfaces() | Tracing dependencies when a route injects OrderService interface but needs to know the concrete OrderServiceImpl dependencies |
| MuleSoft flow analysis | Parses MuleSoft XML configs into graph nodes (flows, sub-flows, connectors, endpoints, transforms, error handlers) and DataWeave scripts | Understanding MuleSoft project structure before migration -- no manual XML deep-dives required |
| BizTalk artifact analysis | Parses BizTalk orchestrations (.odx), maps (.btm), pipelines (.btp), and bindings into graph nodes (orchestrations, shapes, maps, functoids, pipelines, components, ports, adapters) | Understanding BizTalk project structure before migration -- 38 shape element names recognized, 45 functoid type mappings |
The graph is consumed transparently by multiple skills:
/camel-validate -- Validation thresholds adapt to the project's actual patterns. A route with 15 steps is acceptable in a project where existing routes average 12 steps, but flagged in a project where they average 5. The graph check reports structural retirement candidates and its coverage limits rather than proving code is dead.camel-implement -- The AI matches the project's existing conventions (naming patterns, bean reuse, dependency versions) rather than inventing new ones.camel-test -- Route topology awareness lets the AI understand upstream and downstream dependencies, generating tests that cover integration points rather than just individual routes./camel-migrate -- Phase 0 uses graph evidence to accelerate structural analysis before any code is translated, then reconciles it with bounded source scans. Per-route impact analysis in Phase 2 identifies cross-cutting concerns for each route being migrated. MuleSoft graph support parses XML flows, sub-flows, connectors, and DataWeave scripts; BizTalk graph support parses orchestrations, maps, pipelines, and bindings. Missing graph nodes or edges remain evidence gaps rather than proving that source is unused.# Build the project graph camel-kit graph generate # View graph statistics (node/edge counts by type) camel-kit graph stats # Extract project norms for validation camel-kit graph project-norms # Extract implementation conventions camel-kit graph project-context # Map route topology (connections between routes) camel-kit graph route-topology # Extract migration context for a specific route (JSON output) camel-kit graph migration-context <routeId> [--depth N]
The graph is stored in .camel-kit/project-graph.json and rebuilt automatically when relevant commands detect changes. For greenfield projects where no code exists yet, the graph is not generated -- all skills fall back to sensible defaults. The graph enhances but never gates: its presence improves output quality, but its absence never blocks the pipeline.
The migration-context command performs a bounded, bidirectional traversal of the local project graph from a specific route, including interface-boundary expansion. The default depth is 3 and the result is capped at 50 expanded nodes, so the report is useful local context rather than a complete dependency map.
Example usage:
camel-kit graph migration-context order-ingestion-route camel-kit graph migration-context order-ingestion-route --depth 5
Output structure:
{ "route": "processOrders", "runtime": "spring-boot", "components": ["kafka", "http", "bean"], "routes": [ { "id": "route:processOrders", "from": "kafka:orders", "file": "src/main/resources/routes/orders.camel.yaml" } ], "services": [ { "class": "com.example.OrderService", "bean": true, "beanName": "orderService" } ], "artifacts": [ { "groupId": "org.apache.camel", "artifactId": "camel-kafka", "version": "4.14.4" } ], "properties": [ { "key": "camel.component.kafka.brokers", "value": "localhost:9092", "edgeType": "REFERENCES_PROPERTY", "target": "component:kafka" } ], "warnings": [ { "type": "synthetic-node", "name": "UnknownService", "reason": "Node was inferred, not parsed from source" } ] }
What it includes from the reached nodes:
project.runtime from .camel-kit/config.properties, or unknown when unavailableInterface expansion lets the traversal cross interface/implementation relationships, but the depth and 50-node limits still apply. The command itself makes no Knowledge MCP calls; documentation, CVE, release, or JIRA lookups are separate MCP operations.
For MuleSoft projects, graph generate automatically detects Mule XML files (namespace sniffing for mulesoft.org/schema/mule) and parses them using the MuleXmlFlowParser. DataWeave .dwl files are parsed by the DataWeaveParser. No explicit configuration is required -- if the project contains MuleSoft artifacts, they are included in the graph automatically. Use graph stats to see MuleSoft-specific node counts (MULE_FLOW, MULE_SUB_FLOW, MULE_CONNECTOR, MULE_ENDPOINT, MULE_PROCESSOR, MULE_TRANSFORM, MULE_ERROR_HANDLER, DATAWEAVE_SCRIPT).
For BizTalk projects, graph generate automatically detects BizTalk artifacts (namespace sniffing for schemas.microsoft.com/BizTalk) and parses them using the BizTalkParser. Orchestration (.odx), map (.btm), pipeline (.btp), and binding (.xml) files are analyzed. Use graph stats to see BizTalk-specific node counts (BIZTALK_ORCHESTRATION, BIZTALK_SHAPE, BIZTALK_MAP, BIZTALK_FUNCTOID, BIZTALK_SCHEMA, BIZTALK_PIPELINE, BIZTALK_PIPELINE_COMPONENT, BIZTALK_PORT, BIZTALK_ADAPTER, BIZTALK_MESSAGE).
Camel-Kit presents the same workflow and output contracts across supported AI coding assistants. All supported targets use shared markdown skills with agent-specific traits and native configuration.
| Agent | Init Flag | How /camel-execute Dispatches Work |
|---|---|---|
| Claude (Anthropic Claude Code) | --ai claude | Dispatches subagents in parallel per independent task |
| Bob 2 (IBM Bob, default) | --ai bob2 | Uses native spawn_subagent plus Bob custom modes and shared skills |
| Antigravity (Google Antigravity) | --ai antigravity | Parent dispatches bounded worker/reviewer roles; owns decisions and reports |
| OpenAI Codex CLI | --ai codex | Uses AGENTS.md, .agents/skills, seven .codex/agents, and .codex/config.toml |
| GitHub Copilot CLI | --ai copilot | Uses .github/skills, .github/agents, .github/mcp.json, and repository safety hooks |
| Pi | --ai pi | Uses .pi/skills, .pi/prompts, .mcp.json through pi-mcp-adapter, and a project guard extension |
| Qwen (Alibaba Qwen CLI) | --ai qwen | Keeps workflows in the primary session and dispatches 4 bounded implementation/review/test/validation leaves |
| OpenCode | --ai opencode | Dispatches through 9 agents with granular, leaf-bounded permission control |
All agents follow the same route, property, test, and report contracts. Their agent-native configuration and assistant assets differ according to the selected --ai target, as does how they manage the pipeline internally:
| If you value... | Consider |
|---|---|
| Speed (parallel implementation of independent flows) | Claude, Bob 2, or Codex CLI |
| Safety (strictest tool restrictions per phase) | Bob 2, or OpenCode |
| Single intent router (describe the work, then follow one guided pipeline) | Any target through /camel-start |
| Customizability (override policies, compose instructions) | Antigravity or GitHub Copilot CLI |
| GitHub-native agent workflows (skills, custom agents, hooks, MCP) | GitHub Copilot CLI |
| Codex-native repository workflows (skills, custom agents, sandbox, approvals, MCP) | OpenAI Codex CLI |
| Fine-grained file permissions (auto-allow test dirs, ask for source) | OpenCode |
| Aspect | What You'll Notice |
|---|---|
| Dispatch transparency | Claude, Bob 2, and Codex show subagent dispatch; Antigravity/OpenCode/Copilot delegate to specialized agents; Qwen keeps orchestration visible in the primary session and delegates bounded leaves; Pi runs in the main session |
| Tool restrictions | During brainstorm, Bob modes can physically prevent code edits. Claude relies on skill instructions. Qwen combines primary-session instructions with scoped leaves. Codex keeps the active sandbox and approval policy. OpenCode uses glob-pattern permissions. Copilot uses tool allow/deny permissions and generated safety hooks. Pi uses a generated guard extension plus external sandboxing when needed. |
| Parallel execution | Claude, Bob 2, Codex, and Qwen can dispatch independent work in the same wave; other agents have more limited parallelism |
| MCP approval prompts | Codex uses exact enabled_tools allowlists with prompt approval. Qwen filters each server with includeTools and retains prompts. Antigravity uses native MCP configuration with its permission system. Copilot uses .github/mcp.json plus Copilot's permission system. Pi uses pi-mcp-adapter directTools. OpenCode retains its normal permission prompts. |
| Execution limits | OpenCode templates set per-role step limits; other targets retain their native limits. |
During /camel-execute, the AI must implement multiple tasks, review each one, and fix issues -- all autonomously. How it manages this work internally depends on the agent's native capabilities.
Agents with subagent support (Claude, Bob 2, Antigravity, OpenAI Codex CLI, GitHub Copilot CLI, Qwen, OpenCode) dispatch each pipeline task to a fresh, isolated subagent. The subagent receives only the information it needs -- the task description, the relevant design spec section, and the skill guides -- and works in its own context window. When it finishes, a separate reviewer subagent checks the output. This isolation prevents cross-contamination: a mistake in one task cannot leak into the next, and the reviewer has no bias from having written the code.
The execution loop for these agents:
Claude and Bob 2 use camel-kit plan analyze waves from structured task metadata, logical dependencies, and file overlap, then dispatch independent tasks to subagents in the same wave. For Bob 2, the parent Bob task calls spawn_subagent; multiple spawn calls in one turn run in parallel. Bob 2 reserves built-in explore for factual discovery, generates camel-worker for implementation/test/fix/verification from broad execute/debug orchestration modes, and generates a read/MCP-only camel-reviewer for catalog research, knowledge research, and independent review. The parent supplies each call with the complete selected role from .bob/personas/. Standalone restricted implement and test modes keep mutations inline; test retains its path-scoped edit restriction.
Pi executes these contracts inline and records the missing isolation. Other targets retain their native tool and permission boundaries.
Skills are shared markdown instruction files that every supported AI target loads and follows. The equalization layer keeps these behaviors consistent:
The dispatch model is internal to the agent. For most agents, you run the same commands (/camel-brainstorm, /camel-execute, etc.) and get the same artifacts. For Codex CLI, start with $camel-start and inspect project skills with /skills. For GitHub Copilot CLI, use the same skill names through Copilot project skills; start with a direct instruction such as “Use the /camel-start skill.” Run /skills list to inspect available project skills.
For contributor-level details on each agent's architecture (template files, permission models, dispatch internals), see Agent Architectures.
Camel-Kit integrates with the Apache Camel MCP (Model Context Protocol) server to provide real-time catalog queries and validation. This ensures the AI assistant never guesses component names or options from training data.
| Capability | Description |
|---|---|
| Component catalog | Search and verify 300+ Camel components by name or category |
| EIP catalog | Verify Enterprise Integration Patterns exist and get configuration options |
| Data format catalog | Verify data formats (JSON, XML, CSV, etc.) |
| Language catalog | Verify expression languages (Simple, Groovy, XPath, etc.) |
| Route validation | Check endpoint URIs against the catalog schema, catch typos |
| Security analysis | Supplemental route-hardening concerns for corroboration against the canonical checklist |
MCP is auto-configured during camel-kit init. The init command creates agent-specific MCP configuration files:
.mcp.json.bob/mcp.json.agents/mcp_config.json.codex/config.toml.github/mcp.json.mcp.json via pi-mcp-adapter.qwen/settings.jsonopencode.json (default)GitHub Copilot CLI workspaces also get .github/copilot-instructions.md, .github/skills/, .github/agents/, and .github/hooks/camel-kit-safety.json. Internal guide skills copied for custom-agent use are marked so Copilot does not directly or automatically invoke them. The generated hook denies obvious destructive or secret-sensitive shell commands such as git push, broad rm -rf, chmod 777, and reads of common secret files, while leaving normal Copilot permissions in place. Workspace MCP servers from .github/mcp.json load only after the repository folder is trusted.
Codex CLI workspaces get AGENTS.md, .agents/skills/, seven .codex/agents/*.toml role definitions, and .codex/config.toml. Project config and any user-added project hooks load only after repository trust; Camel-Kit itself generates no hooks. Camel-Kit configures the Camel catalog, Camel knowledge, and Citrus servers with their pinned distribution versions, exact enabled_tools lists, and default_tools_approval_mode = "prompt"; it leaves global Codex config, authentication, approvals, and sandbox settings alone.
Pi workspaces also get AGENTS.md, .pi/skills/, .pi/prompts/, .pi/extensions/camel-kit-guard.ts, and .pi/camel-kit-guard-policy.json. Install pi-mcp-adapter with pi install npm:pi-mcp-adapter@2.11.0, run /trust, then invoke /skill:camel-start. For headless validation, use pi -a so Pi loads project resources.
After the agent-specific setup above, the AI assistant automatically uses MCP tools when available.
In addition to the catalog MCP, Camel-Kit configures:
citrus.versionIf the MCP server is unavailable, the AI assistant falls back to bundled component skill files. MCP is never a hard requirement -- it enhances accuracy but the pipeline continues without it.
Start with the workspace diagnostic:
camel-kit doctor camel kit doctor
Use camel-kit doctor --json or camel kit doctor --json in scripts or CI to detect broken generated files. A FAIL means the generated workspace needs repair; a WARN usually means an optional prerequisite or persisted graph file is missing.
Error: Catalog not cached
Solution: Re-run init to re-fetch the catalog:
camel-kit init --here --ai claude
Component 'kafak' not found
Solution: Check for typos. The MCP server suggests corrections when it finds a close match.
./mvnw: No such file or directory
Solution: Re-initialize the project to regenerate the Maven wrapper:
camel-kit init --here --ai claude
When Docker is not installed or not running, verification phases that depend on it are skipped:
Solution: Install Docker and start the Docker daemon for the full Citrus/Testcontainers phase. Manually started external services may help runtime startup checks, but the current verification loop still reports Phase 2 as skipped when Docker itself is unavailable.
If verification fails after multiple fix iterations (the verify loop runs inside /camel-execute):
If a route breaks outside of a pipeline run (e.g., after a manual edit, dependency upgrade, or configuration change), use the standalone debug skill:
/camel-debug
This runs a structured troubleshooting workflow (STOP → PRESERVE → DIAGNOSE → FIX → GUARD) that captures state before making changes, classifies the error, and applies targeted fixes. Unlike the pipeline verification loop (camel-verify), the debug skill is designed for ad-hoc use and does not require an active pipeline.