Camel Kit

Architecture overview

Camel Kit combines two mechanisms to give coding agents accurate and economical access to the Apache Camel ecosystem. Skills are Markdown instruction files that carry the process knowledge: how to design a flow, how to generate YAML, how to validate a route. MCP servers carry the data knowledge: which components exist for a Camel version, which options they accept, whether an endpoint or a Citrus test action is valid. Around them sit a generated instruction file per agent and an optional code intelligence layer.

Repository and release boundaries

kit/ contains the CLI, skills, graph and JBang plugin. knowledge/ contains the standalone Knowledge MCP server and its schema, embedding, indexer and index modules. The root pom.xml is a shared build parent and aggregator, and docs/ is the Antora component for both products. Java packages use org.apache.camel.kit; Maven modules use org.apache.camel.

Kit and Knowledge keep independent versions and releases. Their runtime boundary remains MCP: Kit configures an exact tested server artifact, and Knowledge also serves clients that do not use Kit. Product dependencies belong to their own POMs. The shared parent has its own published version; a product release references a released parent. Index data has separate compatible release channels, automatic client discovery and an optional exact version pin. See releasing and Knowledge MCP for these contracts.

The workflow contract lives in kit/camel-kit-core/src/main/resources/workflow/camel-kit-workflow.yaml. It defines the command names and aliases, the generated command stubs, skill visibility, pipeline stages, artifacts, transitions, MCP servers and their allowed tools. The generators read it for command stubs and tool filters, and tests check the skill front matter against it.

Four layers

Layer What it holds Where

Layer	What it holds	Where
1. Agent instructions	The cross-agent equalization layer: a routing table from user intent to the right command, the six Iron Laws, and the MCP setup; the development snapshot adds fifteen Camel YAML DSL rules (placement and value types, `routeConfiguration`, HTTP and mail headers, dependency loading, ActiveMQ acknowledgement modes) that the agent sees even before a skill is loaded	`AGENTS.md`, or the agent’s own entry file (`CLAUDE.md`, `QWEN.md`, `.github/copilot-instructions.md`)
2. Skills	Thirteen skills in four tiers (entry, pipeline, utilities, internal) plus the shared guides: structured prompts with step-by-step procedures, tool calls, conditions and guide imports, loaded progressively	`kit/camel-kit-core/src/main/resources/skills/`, copied into the agent’s skills directory by `init`
3. MCP servers	Two local servers by default (development snapshot; released versions include all three) (Camel catalog for verification and validation, Knowledge for documentation search), with an optional third (Citrus for test guidance, enabled via `--with-citrus-mcp`)	The agent’s MCP configuration file, generated by `init`
4. Graph CLI (optional)	A property graph of the project built by nine parsers and two post-processors, with fifteen subcommands; every skill works without it	`camel-kit graph`, `.camel-kit/project-graph.json`

1. Agent instructions

The cross-agent equalization layer: a routing table from user intent to the right command, the six Iron Laws, and the MCP setup; the development snapshot adds fifteen Camel YAML DSL rules (placement and value types, routeConfiguration, HTTP and mail headers, dependency loading, ActiveMQ acknowledgement modes) that the agent sees even before a skill is loaded

AGENTS.md, or the agent’s own entry file (CLAUDE.md, QWEN.md, .github/copilot-instructions.md)

2. Skills

Thirteen skills in four tiers (entry, pipeline, utilities, internal) plus the shared guides: structured prompts with step-by-step procedures, tool calls, conditions and guide imports, loaded progressively

kit/camel-kit-core/src/main/resources/skills/, copied into the agent’s skills directory by init

3. MCP servers

Two local servers by default (development snapshot; released versions include all three) (Camel catalog for verification and validation, Knowledge for documentation search), with an optional third (Citrus for test guidance, enabled via --with-citrus-mcp)

The agent’s MCP configuration file, generated by init

4. Graph CLI (optional)

A property graph of the project built by nine parsers and two post-processors, with fifteen subcommands; every skill works without it

camel-kit graph, .camel-kit/project-graph.json

See Skills system, MCP servers, Knowledge MCP, Graph intelligence and Forage configuration catalog for each layer.

The prompt is the product

In the agent-run workflow the generated instructions own the integration behaviour. The compiled CLI supplies initialization and configuration (init), the workspace check (doctor), pipeline document staleness (doc), pipeline IDs (nextId), wave analysis (plan analyze) and the graph; it supports the prompt-owned workflow rather than replacing it. This makes the behaviour portable across the eight supported agents, readable (the instructions an agent follows are plain files in the project), customizable by editing Markdown, and version-configurable through the distribution pins and live catalog queries.

The deliberate exception is Ship, a Technology Preview: /camel-ship is a short delegate to the registered camel-kit ship command, and the workflow controller (stages, run state, oversight, evidence, guarded publication) is compiled code. Eligible hosts relay controller-issued tasks to read-only native subagents and submit the results; the controller keeps the candidate writes, the validation and the publication. See Ship workflow (Technology Preview).

Progressive disclosure and context isolation

Skills load in three levels: the routing surface of camel-start is always present; a skill’s SKILL.md is loaded when the skill is invoked; its guides are loaded only when the instructions reference them. Catalog data is never loaded wholesale: the agent queries the MCP servers for the artifacts a design actually uses. Together these keep the context small enough for constrained models and keep every component verifiable.

Where the agent supports subagents, research, implementation and review run in isolated contexts and only structured summaries flow back to the orchestrator: the catalog researcher verifies a wave’s artifacts and returns a short summary, and reviewers return reports rather than their traces. Runtime verification is isolated on the same terms where the agent’s trait allows it; Qwen Code and OpenCode keep it in their primary executor by design, so its build output stays in that session. Single-conversation agents run every role inline and record the missing isolation.

The orchestration model

brainstorm or migrate  ->  approved design (package)
        plan           ->  implementation plan
        execute        ->  artifacts, execution report with verification evidence
        validate       ->  validation report

The approved design is the only user gate of a chained run; planning, execution and validation follow automatically. For a migration the same gate covers the complete package, runbook included, without authorizing any of the runbook’s operational actions. Execute starts with an environment probe and can enter a bounded re-plan loop (at most three rounds) that modifies only the affected flow sections of the design. Both entries produce the same design specification contract, so plan and execute work identically afterwards; the plan never consumes the migration runbook. See Stages, approval gate and Iron Laws and Environment-in-the-loop.

Three concerns are kept apart in the shipped assets: a skill is a workflow with steps and exit criteria, a persona is a role with a perspective, an output format and composition rules (integration architect, catalog researcher, code quality reviewer, and so on), and a command is the user-facing entry point. Personas never invoke other personas; composition is the job of skills or of the user, and the dispatch depth is one.

One skill set, eight agents

All targets use the same skills, Iron Laws, constitution rules, MCP tool calls and output formats. What differs is handled by templates and traits: the dispatch mechanism (subagents, modes or inline execution), the tool restriction model, the file reading patterns, the parallelization strategy and the configuration format. init reads the agent’s descriptor from the capability registry (kit/camel-kit-core/src/main/resources/agents/registry/), copies the skills, renders the dispatch block and the MCP configuration, and appends the agent’s traits: instruction fragments under templates/traits/<agent>/ that TraitApplicator adds to the generated skill files between idempotent comment sentinels, so re-running init never duplicates them. Each persona is installed as a complete role file in the agent’s persona directory. See Supported AI agents for what each target gets.

Skills, generated instruction files, MCP configuration templates and the active documents are tested as contract surfaces: ResourceConsistencyTest fails the build on stale command names, configuration files, graph access patterns, Knowledge tool names or Iron Law counts, and ShippedAssetStructureTest checks that every manifest skill, guide reference, trait, dispatch template and generated MCP configuration resolves.

Design decisions worth knowing

DataMapper consistency: XSLT generation used to vary between runs because the model re-derived XPaths from the same schema each time. The canonicalize stage now pre-computes the source XPaths and target elements once, at design time, and the implementation uses them verbatim. For model-generated code, an exact template per case beats one template with conditional rules.
Version alignment: distribution.properties ships the defaults, init persists the selected runtime and versions in .camel-kit/config.properties, and every catalog call is bound to those values. Users override with -p flags or a -c file.
Constitution and Iron Laws: The constitution’s eight rules say what makes a good route; the six Iron Laws say when and how the pipeline enforces quality. Iron Law 2 incorporates the constitution; the two are complementary, not overlapping. See Constitution and Iron Laws.
Graph queries in the CLI, not in MCP: Graph analysis moved out of an MCP server into camel-kit graph because a local process call is faster than a round-trip, and a generated project then needs only its MCP servers (two by default; three with --with-citrus-mcp).