docs/constitution.md

# Camel-Kit Constitution

> Eight non-negotiable rules enforced on every generated route. All other design guidance (error handling strategy, retry policy, throttling, resilience patterns, idempotency, transactions, data format choices, deployment) lives in `/camel-brainstorm` and `/camel-migrate`, where it is applied context-specifically during flow design.

---

## Document Control

| Property | Value |
|----------|-------|
| Version | 2.2 |
| Last Updated | 2026-07-07 |

---

## Rules

> These 8 rules define what makes a good Camel route. They are enforced by **Iron Law 2 (Constitution Compliance)** across all pipeline phases. See `skills/shared/iron-laws.md` for the full set of six iron laws.

### 1. Route Structure

Every route MUST have a **source** (`from:`) and a **sink** (final `to:`).

- `direct:` and `seda:` sub-routes are exempt — they may omit an external sink.
- **Violation:** routes without a source or sink fail validation.
- Pass-through routes with no processing steps trigger a WARNING.

---

### 2. Single Responsibility

One route = one clear purpose, explainable in one sentence.

- If a description requires "and … and …", split into multiple routes.
- **Violation:** routes with more than 7 processing steps trigger a review WARNING.

---

### 3. Separation of Concerns

Decompose complex integrations into discrete, composable routes.

- Pattern: **Ingestion → Processing → Delivery**
- Use `direct:` for synchronous internal routing, `seda:` for asynchronous.
- Keep business logic in beans; keep integration logic in routes.

---

### 4. Naming Conventions

Use consistent, meaningful names throughout.

**Route IDs:** `<domain>-<action>[-<qualifier>]`
```
order-ingestion
customer-enrichment
inventory-lookup
```

**Internal endpoints:** `direct:<route-id>` · `seda:<domain>-<purpose>`

**Headers/Properties:** `CamelCase` for Camel built-ins · `kebab-case` for custom (`order-id`, `correlation-id`)

- **Violation:** route IDs not matching the convention trigger a WARNING.

---

### 5. Observability

Every route MUST declare a `routeId` and a `description`.

- Use correlation IDs (e.g. `X-Correlation-ID`) to trace requests across routes.
- Log at decision points, not at every step.
- **Violation:** routes without a `routeId` fail validation.

---

### 6. External Configuration

Never hardcode connection strings, credentials, or environment-specific values.

- Use `{{PLACEHOLDER}}` syntax for all configurable values.
- Configuration hierarchy (highest priority first): environment variables → system properties → `application.properties` → bundled defaults.
- **Violation:** hardcoded credentials or connection strings fail validation.

---

### 7. Component Support Verification

Every component used in a route MUST be verified as **available** in the target Camel version.

- **Primary check:** Call `camel_catalog_component_doc` (via Camel MCP) to check whether the component exists in the Apache Camel catalog for the target version.
- **If a component is NOT found:**
  1. Raise a WARNING to the user explaining the availability status.
  2. Search for an alternative that provides equivalent functionality.
  3. Present the warning and the suggested alternative to the user before proceeding. Let the user decide whether to accept the component or switch to the alternative.
- **Automated verification:** `/camel-execute` dispatches internal runtime verification to check component availability at build and startup time, catching missing components that passed design-time validation.
- **Violation:** WARNING — this is not a validation blocker, but users must be clearly informed of the availability implications.

---

### 8. Infrastructure via Forage

Declare infrastructure beans with `forage.*` properties when Forage covers them; follow the configuration ladder (Forage → component properties → hand-rolled bean with a stated reason). Hand-rolled bean definitions (`camel.beans.*` or YAML `beans`) require a one-line reason comment.

- **Violation:** an unknown `forage.*` key, or a hand-rolled bean (`camel.beans.*` or YAML `beans`) with a Forage (rung-1) equivalent and no reason comment, fails validation. A hand-rolled bean where only a rung-2 scalar alternative exists triggers a WARNING.

---

## Project Customizations

> Extend or override the rules above for project-specific needs.

### Allowed Components
```yaml
# allowedComponents:
#   - kafka
#   - http
#   - jpa
```

### Naming Overrides
```yaml
# routeIdPattern: "myteam-{domain}-{action}"
```

### Error Handling Overrides
```yaml
# deadLetterPatterns:
#   order: kafka:order-dlq
#   default: kafka:integration-dlq
```

### Security Requirements
```yaml
# security:
#   requireTLS: true
#   sensitiveHeaders: [Authorization, X-API-Key, Cookie]
```

---

## References

- [Apache Camel Error Handler](https://camel.apache.org/manual/error-handler.html)
- [Enterprise Integration Patterns](https://www.enterpriseintegrationpatterns.com/)