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
 

Reply via email to