This is an automated email from the ASF dual-hosted git repository. luigidemasi pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/camel-kit.git
commit 8e58ae665e6b0c1267cfde41f7e84a8b423f08fc Author: Jinal Sarvaiya <[email protected]> AuthorDate: Wed Nov 18 12:47:14 2026 +0000 fix #161: Document Camel YAML DSL guidance coverage in architecture --- docs/modules/ROOT/pages/architecture.adoc | 44 ++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/docs/modules/ROOT/pages/architecture.adoc b/docs/modules/ROOT/pages/architecture.adoc index 51b77552..0639f2cb 100644 --- a/docs/modules/ROOT/pages/architecture.adoc +++ b/docs/modules/ROOT/pages/architecture.adoc @@ -35,9 +35,8 @@ front matter against it. | 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 + the MCP setup; the development snapshot adds fifteen Camel YAML DSL rules that the agent sees even + before a skill is loaded (see <<camel-yaml-guidance,Camel YAML DSL guidance>> below) | `AGENTS.md`, or the agent's own entry file (`CLAUDE.md`, `QWEN.md`, `.github/copilot-instructions.md`) | 2. Skills @@ -59,6 +58,45 @@ front matter against it. See xref:skills.adoc[], xref:mcp.adoc[], xref:knowledge.adoc[], xref:graph.adoc[] and xref:forage.adoc[] for each layer. +[[camel-yaml-guidance]] +=== Camel YAML DSL guidance + +The development snapshot includes fifteen Camel 4.22 YAML DSL rules in the generated agent instructions. These rules +cover placement and value types, `routeConfiguration`, HTTP and mail headers, dependency loading, and ActiveMQ +acknowledgement modes. The +https://github.com/apache/camel-kit/blob/main/kit/camel-kit-core/src/main/resources/templates/shared/agents-md.md#camel-422-rules[maintained +rule list] lives in the shared template and is copied into agent-specific templates during the build. + +**Coverage by agent:** + +* *Claude Code, Bob 2, Qwen, OpenCode*: Use the shared template (`templates/shared/agents-md.md`). These agents load +the rules from their entry file (`CLAUDE.md`, `AGENTS.md`, `QWEN.md`) immediately when the project is opened, before +any skill invocation. +* *Antigravity, Codex CLI, GitHub Copilot CLI, Pi*: Use agent-specific templates +(`templates/{antigravity,codex,copilot,pi}/agents-md.md`) that include the same rule set. Loading behavior varies: +** *Antigravity and Codex CLI*: Rules are available from `AGENTS.md` when the project is opened. +** *GitHub Copilot CLI*: Rules load from `.github/copilot-instructions.md` on first invocation or when the +instructions are refreshed. +** *Pi*: Rules are loaded when Pi reads `AGENTS.md` as project context, typically on first skill invocation or when +the project is explicitly trusted. + +**Schema validation vs. runtime verification:** + +Rule 4 instructs the agent to run `camel validate` on the final YAML file after the last edit. This validates the +route against the Camel YAML DSL schema and catches structural errors, type mismatches, and invalid placements. +However, passing the schema check does not guarantee the route will run successfully. + +Rule 5 makes this explicit: the configured runtime must be launched and all endpoints exercised before the +integration is declared working. Schema validation is a static check; runtime verification requires: + +1. Starting the application (Camel Main via the run script, Spring Boot via `./mvnw spring-boot:run`, or Quarkus via +`./mvnw quarkus:dev`) +2. Reading the startup log for errors, warnings, and successful endpoint bindings +3. Exercising every endpoint with actual requests or events to verify the integration behavior + +This distinction ensures that syntactically valid YAML routes are also functionally correct and that environment +dependencies, service connectivity, and runtime configuration are validated before the work is considered complete. + [[prompt-is-the-product]] == The prompt is the product
