Thank you for your interest in contributing to Camel-Kit! This document provides guidelines and information for contributors.
Note: Camel-Kit is heavily inspired by GitHub Spec-Kit. When contributing, we encourage you to explore the spec-kit project to understand the design philosophy that guides this project. The spec-kit team's innovative work on spec-driven development with AI assistants has been foundational to our approach.
This project follows the Apache Software Foundation Code of Conduct. Please be respectful and constructive in all interactions.
git clone https://github.com/YOUR_USERNAME/camel-kit.git cd camel-kit
git remote add upstream https://github.com/luigidemasi/camel-kit.git
# Portable build of all modules using Maven Wrapper ./mvnw clean install # CI always certifies packaged Ship payloads on Linux; reproduce it locally on a Linux host ./mvnw -B -Plinux-ship-certification clean install # Run CLI using JBang (from jbang-catalog.json) jbang camel-kit@. --help # Or run directly from the main JBang script jbang camel-kit-main/src/main/jbang/main/CamelKit.java --help # Run tests ./mvnw test # Package for distribution ./mvnw package # Install locally (after build) ./mvnw install jbang app install --force camel-kit@./
For IntelliJ IDEA or Eclipse:
camel-kit/ ├── camel-kit-main/ # Main JBang CLI module │ └── src/main/jbang/main/ │ └── CamelKit.java # JBang entry point ├── camel-kit-core/ # Core functionality module │ └── src/main/java/io/github/luigidemasi/camelkit/ │ ├── CamelKitMain.java # Picocli CLI main class │ ├── command/ # CLI command implementations │ ├── catalog/ # Catalog fetching logic │ ├── config/ # Configuration handling │ ├── output/ # Output formatting (TUI, logo) │ └── util/ # Utility classes │ └── src/main/resources/ │ ├── distribution.properties # Single source of truth for all config defaults │ ├── skills/ # Skill definitions (markdown instruction files) │ │ ├── camel-start/ # Meta-router and primary entry point │ │ ├── camel-design/ # Design-phase reference guides (internal, loaded by camel-brainstorm) │ │ ├── camel-brainstorm/ # Interactive design session │ │ ├── camel-plan/ # Implementation planning │ │ ├── camel-execute/ # Orchestrated execution │ │ ├── camel-migrate/ # Migration orchestrator │ │ ├── camel-verify/ # Runtime verification │ │ ├── camel-implement/ # YAML generation (internal) │ │ ├── camel-validate/ # Tier 1 user-facing static quality gate │ │ ├── camel-test/ # Test generation (internal) │ │ ├── camel-knowledge/ # Tier 2 user-facing Camel docs utility │ │ └── shared/ # Shared guides (iron laws, DataMapper, MCP) │ └── templates/ # Agent-specific instruction templates │ ├── bob2/ # IBM Bob 2 │ ├── claude/ # Anthropic Claude Code │ ├── antigravity/ # Google Antigravity │ ├── qwen/ # Qwen │ ├── opencode/ # OpenCode │ └── traits/ # Agent-specific trait files (appended to skills at init) │ ├── claude/ # Claude Code traits │ ├── antigravity/ # Google Antigravity traits │ ├── bob2/ # IBM Bob 2 traits │ ├── qwen/ # Qwen traits │ └── opencode/ # OpenCode traits ├── camel-jbang-plugin-kit/ # Camel JBang plugin ├── camel-kit-graph/ # Project graph analysis (9 parsers) │ │ # Parsers: JavaClassParser, CamelRouteParser, MavenPomParser, │ │ # PropertiesParser, DockerComposeParser, OpenApiParser, │ │ # MuleXmlFlowParser, DataWeaveParser, BizTalkParser ├── camel-kit-plugins/ # Plugin extensions ├── docs/ # Documentation │ ├── user-guide.md # End-user walkthrough │ ├── commands.md # Command reference │ ├── architecture.md # Contributor guide │ └── constitution.md # Route quality rules ├── distribution.properties # Root config (source of truth, copied into JAR) ├── examples/ # Link to the separate examples repository ├── pom.xml # Parent Maven POM ├── jbang-catalog.json # JBang catalog definition ├── mvnw, mvnw.cmd # Maven Wrapper scripts ├── README.md ├── CONTRIBUTING.md └── LICENSE
Workflow examples and migration samples are maintained in camel-kit-examples. Submit example changes there; CLI and skill changes belong in this repository.
Before opening an issue:
feature/description - New featuresfix/description - Bug fixesdocs/description - Documentation changescommand/command-name - New slash commandstemplate/template-name - Template enhancementsSync with upstream:
git fetch upstream git rebase upstream/main
Run tests:
./mvnw test
Build the project:
# Portable build ./mvnw clean install # CI always certifies packaged Ship payloads on Linux; reproduce it locally on a Linux host ./mvnw -B -Plinux-ship-certification clean install
Test the CLI:
jbang camel-kit@. init
package io.github.luigidemasi.camelkit.command; import picocli.CommandLine.Command; import picocli.CommandLine.Parameters; /** * Command to process a route specification. */ @Command( name = "route", description = "Process a route specification" ) public class RouteCommand implements Runnable { @Parameters(index = "0", description = "Name of the route") private String routeName; @Override public void run() { // Implementation here } }
# Run all tests ./mvnw test # Run tests for specific module ./mvnw test -pl camel-kit-core # Run with verbose output ./mvnw test -X # Run specific test class ./mvnw test -Dtest=CatalogServiceTest
package io.github.luigidemasi.camelkit.catalog; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.io.TempDir; import java.nio.file.Path; import static org.junit.jupiter.api.Assertions.*; class CatalogServiceTest { @Test void testGetLatestCamelVersion() { CatalogService service = new CatalogService(); String version = service.getLatestCamelVersion(); assertNotNull(version); assertTrue(version.startsWith("4.")); assertEquals(3, version.split("\\.").length); } @Test void testSearchComponents(@TempDir Path tempDir) { // Setup test CatalogService service = new CatalogService(); // Test search var results = service.searchComponents("kafka"); assertFalse(results.isEmpty()); } }
| Type | Location |
|---|---|
| User documentation | docs/user-guide.md |
| Command reference | docs/commands.md |
| Architecture (skills, MCP) | docs/architecture.md |
| API documentation | Docstrings in code |
| Change log | CHANGELOG.md |
Skills are markdown instruction files that guide AI agents. To add a new skill:
Create a new directory in camel-kit-core/src/main/resources/skills/:
skills/camel-{name}/
├── SKILL.md # Skill manifest with YAML frontmatter
└── guides/ # Instruction files loaded on demand
├── main-guide.md
└── helper-guide.md
--- name: camel-{name} description: Brief description with trigger keywords for AI agent discovery user_invocable: false --- # /camel-{name} > One-line description ## Guides | Guide | When to Load | Purpose | |-------|-------------|---------| | `guides/main-guide.md` | Always | Primary instruction guide | | `guides/helper-guide.md` | When X | Conditional reference guide |
Each guide in guides/ is a self-contained markdown file loaded by the agent when the skill is active. See existing skills for examples.
docs/commands.md if user-facingSee Architecture Guide for the full process.
If the skill benefits from agent-specific optimizations (parallel dispatch, tool-specific guidance, state management), add trait files:
templates/traits/{agent}/{skill-name}.append.md # SKILL.md-level trait
templates/traits/{agent}/{skill-name}/{guide-name}.append.md # Guide-level trait
Traits are appended to the corresponding skill files during camel-kit init with idempotent sentinels. Each trait should contain instructions specific to that agent's tools and capabilities — not generic content that belongs in the shared skill.
No code registration is required for a new trait file. TraitApplicator applies SKILL.md-level traits for workflow skills and discovers guide-level traits from the shipped .append.md files under each templates/traits/{agent}/{skill-name}/ directory.
ShippedAssetStructureTest verifies both sides of the contract: trait files must target existing shipped skills or guides, and every shipped trait must appear in generated output for the production generator of its agent.
See Architecture Guide for details on the trait system.
We follow Semantic Versioning:
distribution.properties is the source of truth for distribution and compatibility versions. Edit the reviewed values there, then synchronize the few literals Maven needs while constructing its model:
./tools/sync_distribution_mirrors.py ./tools/sync_distribution_mirrors.py --check
The helper is idempotent, performs no network lookup, and does not certify a version or replace the compatibility evidence required for a release.
pom.xml (parent and all modules)CHANGELOG.mdjbang-catalog.jsonv0.2.0## [0.2.0] - 2024-01-20 ### Added - New feature description ### Changed - Changed feature description ### Fixed - Bug fix description ### Deprecated - Deprecated feature description
Contributors are recognized in:
Thank you for contributing to Camel-Kit!