This is an automated email from the ASF dual-hosted git repository. oscerd pushed a commit to branch docs/post-move-housekeeping in repository https://gitbox.apache.org/repos/asf/camel-kit.git
commit 70c4ac0e53fc6ce5e02ff6d680fcd9593c3d423b Author: Andrea Cosentino <[email protected]> AuthorDate: Mon Nov 16 18:26:00 2026 +0100 Fix #162: point repository links at apache/camel-kit and fold duplicated docs into pointers Post-move housekeeping. The Kit README documentation badge and the root README now point at https://camel.apache.org/camel-kit/next/, the CONTRIBUTING upstream remote and the plugin README point at apache/camel-kit, and the former-repository issue links in docs/ship-*.md and docs/user-guide.md are remapped to the issues copied here (#93, #94, #92, #89). docs/camel-kit-overview.md, docs/antigravity.md, docs/ship-codex.md and docs/ship-copilot.md become short pointers to the Antora pages that replaced them, and the links into them now go to the published pages. docs/agent-architectures.md, docs/ship-claude.md, docs/ship-native.md and docs/user-guide.md keep their content: docs/security-model.md cites them as provenance sources, so they can only be reduced together with a revision of those citations. ResourceConsistencyTest now rejects any documentation URL into the former repository. Co-Authored-By: Claude Fable 5.1 <[email protected]> Signed-off-by: Andrea Cosentino <[email protected]> --- CHANGELOG.md | 17 +- CONTRIBUTING.md | 2 +- README.md | 5 +- docs/agent-architectures.md | 4 +- docs/antigravity.md | 73 +--- docs/architecture.md | 2 +- docs/camel-kit-overview.md | 456 +-------------------- docs/commands.md | 2 +- docs/ship-claude.md | 2 +- docs/ship-codex.md | 78 +--- docs/ship-copilot.md | 79 +--- docs/ship-native.md | 6 +- docs/user-guide.md | 4 +- kit/README.md | 8 +- kit/camel-jbang-plugin-kit/README.md | 4 +- .../kit/generator/ResourceConsistencyTest.java | 23 ++ 16 files changed, 81 insertions(+), 684 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0016d747..1adcd66b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -125,6 +125,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- **Post-move housekeeping (#162)** — repository links point at `apache/camel-kit` and the published documentation + at https://camel.apache.org/camel-kit/next/; `docs/camel-kit-overview.md`, `docs/antigravity.md`, + `docs/ship-codex.md` and `docs/ship-copilot.md` are pointers to the Antora pages that replaced them. + `docs/agent-architectures.md`, `docs/ship-claude.md`, `docs/ship-native.md` and `docs/user-guide.md` stay in + place because `docs/security-model.md` cites them as provenance sources. - **Preserve existing project files on `init` (#168)** — `camel-kit init` no longer replaces files the project owns. In `AGENTS.md`, `CLAUDE.md`, `QWEN.md` and `.github/copilot-instructions.md` Camel Kit now writes its content inside a marked block: it appends the block to an existing file and later @@ -740,9 +745,9 @@ Changes since 0.3.1. Ship remains a Technology Preview. - Heavily inspired by [GitHub Spec-Kit](https://github.com/github/spec-kit) - Built for the Apache Camel community -[Unreleased]: https://github.com/luigidemasi/camel-kit/compare/camel-kit-0.4.1...HEAD -[0.4.1]: https://github.com/luigidemasi/camel-kit/compare/camel-kit-0.4.0...camel-kit-0.4.1 -[0.4.0]: https://github.com/luigidemasi/camel-kit/compare/camel-kit-0.3.1...camel-kit-0.4.0 -[0.3.1]: https://github.com/luigidemasi/camel-kit/compare/camel-kit-0.3.0...camel-kit-0.3.1 -[0.3.0]: https://github.com/luigidemasi/camel-kit/compare/camel-kit-0.2.0...camel-kit-0.3.0 -[0.2.0]: https://github.com/luigidemasi/camel-kit/tree/camel-kit-0.2.0 +[Unreleased]: https://github.com/apache/camel-kit/compare/camel-kit-0.4.1...HEAD +[0.4.1]: https://github.com/apache/camel-kit/compare/camel-kit-0.4.0...camel-kit-0.4.1 +[0.4.0]: https://github.com/apache/camel-kit/compare/camel-kit-0.3.1...camel-kit-0.4.0 +[0.3.1]: https://github.com/apache/camel-kit/compare/camel-kit-0.3.0...camel-kit-0.3.1 +[0.3.0]: https://github.com/apache/camel-kit/compare/camel-kit-0.2.0...camel-kit-0.3.0 +[0.2.0]: https://github.com/apache/camel-kit/tree/camel-kit-0.2.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 263e2080..80c27ca5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,7 @@ This project follows the [Apache Software Foundation Code of Conduct](https://ww ``` 3. Add upstream remote: ```bash - git remote add upstream https://github.com/luigidemasi/camel-kit.git + git remote add upstream https://github.com/apache/camel-kit.git ``` ## Development Setup diff --git a/README.md b/README.md index 69146583..3c4da72e 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,9 @@ For released installation commands and a first integration, see the [Kit installation guide](kit/README.md#installation). For standalone documentation search, see [running Knowledge](knowledge/README.md#running-the-mcp-server). -The [shared Antora documentation](docs/modules/ROOT/pages/index.adoc) covers both -products. Its component descriptor is [docs/antora.yml](docs/antora.yml). +The documentation for both products is published at https://camel.apache.org/camel-kit/next/ +from the [shared Antora source](docs/modules/ROOT/pages/index.adoc); its component +descriptor is [docs/antora.yml](docs/antora.yml). ## Repository layout diff --git a/docs/agent-architectures.md b/docs/agent-architectures.md index 7c8a8a37..1dd28272 100644 --- a/docs/agent-architectures.md +++ b/docs/agent-architectures.md @@ -187,7 +187,7 @@ See [Google's skills documentation](https://antigravity.google/docs/skills/), [subagent format](https://antigravity.google/docs/subagents/), [CLI 1.1.6 MCP inheritance support](https://antigravity.google/changelog), and [MCP configuration](https://antigravity.google/docs/mcp/). -For existing projects, follow the [migration instructions](antigravity.md). +For existing projects, follow the [migration instructions](https://camel.apache.org/camel-kit/next/agents.html#retired-targets). --- @@ -480,7 +480,7 @@ marked MCP block. Invalid TOML or conflicting managed server tables fail clearly - **Native repository skills:** all shared Camel-Kit skills use Codex's `.agents/skills/` discovery path. - **Eight custom roles:** pipeline work maps to explicit Codex custom-agent definitions, including a Ship worker with instruction-level restrictions (host enforcement depends on Codex CLI version). -- **Native Ship relay:** eligible sessions dispatch controller-issued stages through `camel_ship_worker` with `--backend codex-native`. See [Codex CLI native Ship](ship-codex.md). +- **Native Ship relay:** eligible sessions dispatch controller-issued stages through `camel_ship_worker` with `--backend codex-native`. See the published [Ship native subagents](https://camel.apache.org/camel-kit/next/ship.html#native) section. - **Parent-owned parallel dispatch:** independent implementation-wave tasks can run together without recursive delegation. - **Trust-gated project config:** MCP configuration loads only for a trusted repository. - **Least-privilege MCP:** exact allowlists and per-call prompt approval for Camel, knowledge, and Citrus tools. diff --git a/docs/antigravity.md b/docs/antigravity.md index 8c966b66..1ddfb955 100644 --- a/docs/antigravity.md +++ b/docs/antigravity.md @@ -1,71 +1,6 @@ # Google Antigravity setup and retired-target migration -Camel Kit `0.4.1` supports Google Antigravity with `--ai antigravity` and IBM Bob 2 with `--ai bob2` -(the default). The `gemini` and `bob` targets have been removed. When upgrading from `0.3.1`, use the -replacement targets and regenerate project assets as described below. - -## Set up Antigravity - -Install Antigravity using [Google's getting-started guide](https://antigravity.google/docs/getting-started). -Install Camel Kit `0.4.1` as described in the [installation instructions](../kit/README.md#installation), then run: - -```bash -camel-kit init my-integration --ai antigravity -``` - -Open the initialized project root in Antigravity. Invoke `/camel-start` in the CLI, or ask it to use the -`camel-start` skill by name. `/skills` lists native CLI skills. The `/camel-*` workflow references in these docs -name skills; some clients expose a different picker or support activation by name. Codex uses `$camel-start`. - -Camel-Kit installs shared skills under `.agents/skills/`, two custom agents under `.agents/agents/`, complete role -personas under `.agents/camel-kit-personas/`, project routing in `AGENTS.md`, and MCP servers in -`.agents/mcp_config.json`: Camel and Camel Knowledge by default, plus Citrus when `--with-citrus-mcp` is passed. Inspect connections in Antigravity's MCP settings -or `/mcp` in the CLI. Existing unrelated MCP servers, settings, and comments are preserved on reinitialization. Tool calls -remain subject to Antigravity's permissions; Camel-Kit does not generate MCP auto-approval policies. - -The primary conversation owns questions, approvals, orchestration, and report writes. It dispatches independent -implementation and review tasks to fresh worker/reviewer contexts using native `invoke_subagent`, with inherited -workspace permissions. The reviewer has no native edit or command tools; its instructions also restrict inherited -MCP tools to research and review. The agents use `inheritMcp: true`, documented in Google's -[CLI 1.1.6 release notes](https://antigravity.google/changelog). If delegation is unavailable, skills run inline and -record missing isolation. - -## Migrate an existing project - -Save your current work before forcing regeneration. As with other targets, `--force` replaces generated -`AGENTS.md` and Camel-Kit skills/configuration. Preserve any custom additions to those generated files first; -custom project rules can live in `GEMINI.md`, which Antigravity also reads. Then run the matching command from the project root: - -```bash -# Former Gemini target -camel-kit init --here --ai antigravity --force - -# Former IBM Bob v1 target -camel-kit init --here --ai bob2 --force - -camel-kit doctor -``` - -A current source-built Camel JBang plugin supports the same options with `camel kit` in place of `camel-kit`. -Review the generated changes before committing them. - -An existing `.agents/mcp_config.json` must contain a JSON object; use `{}` for an empty configuration. Comments -and trailing commas are supported. Fix syntax errors and remove duplicate object keys before reinitializing; Doctor also reports duplicate keys as failures. `AGENTS.md`, `GEMINI.md`, and -every path under `.agents/` must be real files or directories, including custom skills. Replace symbolic links -before initializing. These checks run before Camel-Kit changes project files. - -Antigravity reinitialization removes the four old Camel-Kit-generated `@.gemini/...` imports from `GEMINI.md` -because Antigravity also reads that file. Custom text and imports remain intact. Other `.gemini/` files are retained; -move any custom MCP servers you still need from `.gemini/settings.json` to Antigravity's native MCP configuration -using Google's [MCP schema](https://antigravity.google/docs/mcp/). Old Gemini approval fields and TOML policies do -not configure Antigravity permissions. Move custom skills from `.gemini/skills/<name>/` to `.agents/skills/<name>/`, -checking for name collisions before moving them, then restart Antigravity. Custom Gemini agents or commands need -conversion to Antigravity's native formats; reinit regenerates only the Camel-Kit assets. - -Bob 2 reinitialization replaces the generated gate skills and modes with the shared pipeline and native subagents. -It removes only the known obsolete Bob v1 mode-rule files, preserving neighboring custom rules. In Bob Shell use -`$camel-start` or `/skills`; in Bob IDE use `/camel-start`. - -This is Camel-Kit's target policy. Google's [retirement notice](https://developers.google.com/gemini-code-assist/docs/deprecations/code-assist-individuals) -specifically covers consumer Google sign-in for Gemini CLI and Code Assist; Standard and Enterprise offerings are -outside that retirement notice. +This page moved to the published documentation: [Supported AI agents — Google Antigravity](https://camel.apache.org/camel-kit/next/agents.html#antigravity) +covers the setup, and [Retired targets](https://camel.apache.org/camel-kit/next/agents.html#retired-targets) covers +the migration from the former `gemini` and `bob` targets. The Antora source is +[`docs/modules/ROOT/pages/agents.adoc`](modules/ROOT/pages/agents.adoc). diff --git a/docs/architecture.md b/docs/architecture.md index c3190590..d1b1ace8 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -796,7 +796,7 @@ no later pipeline stage consumes it. **Camel Ship is a Technology Preview:** it is still being stabilized, may change, and is not recommended for production use. This status applies to every backend. -Ship harness entry points delegate to the configured `camel-kit ship` or `camel kit ship` command. The local controller is the sole writer of Ship state and transitions. Eligible Bob 2, Copilot CLI, Claude Code and OpenAI Codex CLI sessions relay controller-issued tasks to native children; the controller accepts bounded proposals, writes its private candidate, and validates before publication. Each run persists its execution mode, and resume cannot change hosts. Copilot uses a synchronou [...] +Ship harness entry points delegate to the configured `camel-kit ship` or `camel kit ship` command. The local controller is the sole writer of Ship state and transitions. Eligible Bob 2, Copilot CLI, Claude Code and OpenAI Codex CLI sessions relay controller-issued tasks to native children; the controller accepts bounded proposals, writes its private candidate, and validates before publication. Each run persists its execution mode, and resume cannot change hosts. Copilot uses a synchronou [...] ### Stage Detection diff --git a/docs/camel-kit-overview.md b/docs/camel-kit-overview.md index bd3942a9..f71d0d1a 100644 --- a/docs/camel-kit-overview.md +++ b/docs/camel-kit-overview.md @@ -1,445 +1,15 @@ # Camel-Kit: AI-Powered Integration Development -## What Is Camel-Kit? - -Camel-Kit is an open-source toolkit that brings structured AI assistance to Apache Camel integration development. It works as a layer on top of Claude Code, IBM Bob 2, Google Antigravity, OpenAI Codex CLI, GitHub Copilot CLI, Pi, Qwen, and OpenCode, giving them domain-specific knowledge and a disciplined workflow for designing, implementing, and verifying integration routes. - -Instead of an engineer writing boilerplate code by hand -- or an AI assistant generating plausible-looking but unverified code from its training data -- Camel-Kit guides the process through a structured pipeline that enforces quality at every step. - ---- - -## The Problem It Solves - -Building enterprise integrations with Apache Camel involves: - -- **Component knowledge** -- Camel has 300+ connectors (Kafka, REST, databases, cloud services, etc.). Each has its own configuration options, version-specific behavior, and compatibility considerations. -- **Pattern knowledge** -- Enterprise Integration Patterns (content-based routing, message splitting, aggregation, dead letter channels) must be applied correctly for reliability and maintainability. -- **Version alignment** -- production deployments require using components and versions that are available and verified in the target Camel version. A component that exists in one version may not exist in another. -- **Quality consistency** -- hand-written or AI-generated routes often miss best practices: missing error handling, hardcoded credentials, unnamed routes that are difficult to debug, overly complex single routes that should be split. - -AI coding assistants can help, but without guardrails they generate code from training data that may reference outdated components, incorrect options, or unsupported versions. The code looks correct but fails at runtime. - -**Camel-Kit solves this by giving the AI real-time access to the live Camel catalog, enforcing quality rules on every generated route, and following a structured pipeline that separates design from implementation.** - ---- - -## Why This Approach Works - -The most common way to use an AI coding assistant is to describe what you want and let it generate code immediately. For simple tasks this works well. For enterprise integrations -- where a single route connects multiple systems, handles errors, transforms data, and must run on a supported platform -- it consistently produces incomplete or incorrect results. The AI makes reasonable-looking assumptions about components, options, and patterns, but those assumptions are drawn from training [...] - -The bottleneck in AI-assisted development is not code generation speed -- it is structured specification. An AI that writes code in seconds but builds the wrong thing wastes more time than an AI that takes twenty minutes to understand the requirements, get human approval, and then build the right thing. - -Camel-Kit is built on a different principle: **understand before designing, design before planning, plan before coding.** - -### Separate Thinking from Doing - -The core insight is that AI assistants produce dramatically better output when the work is decomposed into distinct phases, each with a clear purpose and a concrete deliverable: - -```mermaid -flowchart LR - U["Understand\n(gather requirements)"] -->|"deliverable:\ndesign spec"| D["Design\n(choose components,\ndefine flows)"] - D -->|"deliverable:\nimplementation plan"| P["Plan\n(decompose into tasks)"] - P -->|"deliverable:\nworking code + tests"| A["Act\n(implement + review,\nverify, then validate)"] -``` - -When an AI assistant tries to do all of this in a single step -- jumping straight from a vague requirement to generated code -- it skips the understanding and design phases entirely. It never asks clarifying questions, never considers alternative approaches, and never verifies that its assumptions match the user's intent. The result is code that reflects the AI's best guess rather than the user's actual requirements. - -By separating thinking from doing, each phase can be reviewed independently. A flawed design is caught before any code is written. A flawed plan is caught before any code is generated. The cost of finding and fixing a mistake increases dramatically at each phase -- catching a wrong component choice during design costs one sentence of feedback; catching it during debugging costs hours. - -### Gates, Not Suggestions - -There is a critical distinction in how constraints are applied to AI assistants: **rules** are guidelines the AI can rationalize away; **gates** are hard blockers that must be satisfied before the pipeline can proceed. - -A rule says: *"You should verify components before using them."* The AI can skip this when it feels confident from training data -- and it often does, because its confidence is unrelated to its accuracy. - -A gate says: *"You cannot write a component into the spec until MCP confirms it exists."* There is no way to proceed without satisfying this condition. The gate is objective and verifiable: either the MCP response confirms the component exists, or it doesn't. - -Camel-Kit uses gates at every level: - -```mermaid -flowchart TB - subgraph "Pipeline Gates" - G1["Design spec must be\napproved by user"] --> G2["Each task receives\nadversarial review"] - G2 --> G3["Each task passes\nspec compliance review"] - G3 --> G4["Each task passes\ncode quality review"] - end - subgraph "Verification Gates" - G5["Every component verified\nvia live MCP catalog"] - G6["Every route checked against\n8 constitution rules"] - G7["Runtime verification outcome\nis recorded"] - end - - G4 --> G5 - G5 --> G6 - G6 --> G7 -``` - -- **Iron Laws = hard gates.** "Every component MUST be verified via MCP before being written to any design spec or - YAML file" is not a suggestion -- the pipeline blocks if a component cannot be verified. The AI cannot rationalize - its way past this check. -- **Design approval = the progression gate.** The AI cannot start planning until the user approves the design. That approval authorizes the chained plan, execute, and validate stages; there is no second plan-approval pause. -- **Constitution rules = automated quality gates.** Eight rules are checked during validation. A route without a `routeId` is not flagged as a warning -- it fails validation. A route with hardcoded credentials fails validation. These are pass/fail checks, not advisory notes. -- **Two-stage review = sequential gates.** Spec compliance is checked before code quality. This order matters -- there is no point reviewing code quality on a route that doesn't match the design. The gate enforces the correct sequence. - - -### Skills as Reusable Knowledge - -AI assistants are most effective when given structured, domain-specific knowledge rather than relying on general training data. General-purpose AI models know about Apache Camel the way someone who read the documentation once might -- broadly but imprecisely, with knowledge that may be months or years out of date. - -Camel-Kit addresses this with **skills** -- markdown instruction files that teach the AI exactly how to perform a specific task in the Camel domain: - -- How to conduct a design interview for an integration project -- How to generate a YAML route that follows the constitution rules -- How to validate a route against the live catalog -- How to handle data transformation with the right engine for the complexity level -- How to diagnose and fix runtime errors using a structured error taxonomy - -Skills compose together: the brainstorm skill loads design guides for component selection and EIP patterns; the execute skill loads implementation, validation, testing, and verification guides. Each guide is a self-contained document that the AI reads and follows step by step. - -Because skills are plain markdown, they are easy to read, review, audit, and extend. Adding a new capability to Camel-Kit means writing a new skill guide -- not modifying code. All supported targets use shared markdown skills with agent-specific traits and native configuration. - -### Context Isolation and Role Separation - -When an AI generates code and then reviews its own work, it tends to confirm its own choices. The same biases that led to a design decision make the self-review approve that decision. Effective AI-assisted development separates these roles. - -Camel-Kit enforces role separation at multiple levels: - -- **Implementation and review use distinct contracts.** After each task, a spec compliance reviewer checks whether the output matches the design, then a code quality reviewer checks the constitution. Subagent-capable targets isolate these reviewers from the implementer. -- **Fresh context per task.** When using Claude or Bob 2, each task can be dispatched to a fresh subagent with an isolated context window. The subagent has no memory of previous tasks, no accumulated assumptions, and no temptation to reuse a pattern that worked before but doesn't fit now. -- **Tool restrictions per phase.** Bob 2's brainstorm mode scopes edits to design Markdown and Camel-Kit - configuration state, with read and MCP access. Its command group remains constrained by generated instructions; - the edit boundary is platform-enforced and command discipline is instruction-enforced. - -### Why Not Just Generate Code? - -| Approach | What Happens | -|----------|-------------| -| **"Build me a Kafka-to-PostgreSQL integration"** | AI guesses error handling, transformation format, retry policy, naming conventions, component options. Some guesses are wrong. No gate blocks progression. User discovers issues at runtime. | -| **Understand → Design → Plan → Act** | AI asks about error handling requirements, learns the data format, confirms retry policy, and verifies component options against the live catalog. Design approval gates implementation; the downstream plan, execute, and validate stages then proceed automatically. | - -The structured approach takes longer upfront but eliminates rework. In practice, the total time from requirement to working code is shorter because the AI doesn't generate code that needs to be debugged and rewritten. - ---- - -## How It Works - -### The Pipeline - -Camel-Kit follows a four-stage pipeline with one user approval gate after design: - -The primary `/camel-start` router selects, in order, migration for existing MuleSoft, BizTalk, Fuse, or Camel 2.x/3.x source; planning for an approved design; execution for an implementation plan; static validation for generated routes; standalone debugging for build, startup, or runtime failures; or brainstorming for new and unclear work. - -```mermaid -flowchart LR - subgraph "Phase 1" - B["Design\n/camel-brainstorm"] - end - subgraph "Phase 2" - P["Plan\n/camel-plan"] - end - subgraph "Phase 3" - E["Execute\n/camel-execute"] - end - subgraph "Phase 4" - Q["Validate\n/camel-validate"] - end - - B -->|"user approves\ndesign spec"| P - P -->|"auto-proceeds"| E - E -->|"auto-proceeds"| Q - - E --- N["Environment + catalog"] - E --- I["Implement"] - E --- T["Test"] - E --- V["Review"] - E --- R["Verify"] -``` - -**Phase 1 -- Design.** The AI conducts an interactive interview, asking about the business purpose, the systems that need to connect, data flows, error handling requirements, and transformation needs. It produces business requirements and flow designs in a single design spec. The user reviews and approves before moving forward. - -**Phase 2 -- Plan.** The AI reviews the approved design and decomposes it into bite-sized implementation tasks. Each task specifies exactly what files to create, what components to use, and how to verify the result. In a chained run, execution starts automatically after the plan is written. - -**Phase 3 -- Execute.** The AI probes the target environment, derives dependency waves, batch-verifies catalog artifacts, and implements all tasks autonomously. Each task receives adversarial review followed by spec-compliance and code-quality review. Execute then performs a cross-cutting review and internal runtime verification, producing execution and verification reports. - -**Phase 4 -- Validate.** The final static quality gate checks route schemas, endpoints, project-relative quality thresholds, security, anti-patterns, and all constitution rules. It writes a validation report without modifying the routes. - -### Real-Time Catalog Verification - -Camel-Kit connects to the Apache Camel MCP server, which provides live access to the component catalog. Every component, configuration option, and expression language used in a generated route is verified against the actual catalog for the project's exact Camel version. The AI never relies on training data for component names or options. - -This eliminates a common class of errors: routes that compile but fail at runtime because a component option was renamed, removed, or doesn't exist in the target version. - ---- - -## Key Capabilities - -### Greenfield Development - -Start from scratch with a structured design session. The AI interviews about requirements, designs the integration flows, plans the implementation, and generates production-ready routes with tests. - -```mermaid -flowchart LR - A["/camel-brainstorm"] --> B["/camel-plan"] --> C["/camel-execute"] --> D["/camel-validate"] -``` - -### Migration - -Migrate existing integrations from other platforms to Apache Camel. The AI scans all source artifacts, detects the platform automatically, maps components to Camel equivalents, and produces the same design specification format as greenfield projects. From that point, the pipeline is identical. - -**Supported migration sources:** -- MuleSoft Mule (3.x, 4.x) -- including DataWeave transformation conversion and graph-accelerated flow analysis -- Apache Camel 2.x/3.x -- Java DSL, XML DSL, Blueprint -- JBoss Fuse (6.x, 7.x) -- Microsoft BizTalk (3.x, 4.x) -- including graph-accelerated orchestration, map, pipeline, and binding analysis - - -### Data Transformation (DataMapper) - -Camel-Kit handles data transformation between formats (JSON, XML) automatically during design. It selects the right transformation engine based on complexity: - -- **Simple mappings** (under 20 fields or no schemas) -- generates inline Groovy scripts directly in the route -- **Complex mappings** (20+ fields with schemas) -- generates XSLT stylesheets with visual editing support in the Kaoto IDE - -The engine selection is automatic and transparent. The user only needs to describe the field mappings; the implementation details are handled by the pipeline. - -### Project Graph Analysis - -When working with existing projects -- whether migrating from another platform or extending an established codebase -- the AI needs to understand the project's structure before making changes. Camel-Kit includes a **project graph analyzer** with 9 parsers that parse the entire project into a queryable property graph: classes, methods, Camel routes, endpoints, Maven dependencies, configuration properties, and -- for MuleSoft projects -- flows, sub-flows, connectors, endpoints, transforms, [...] - -The graph now includes **dependency injection awareness** -- it automatically detects the runtime framework (Spring Boot, Quarkus, or Camel Main) from Maven dependencies and traces bean wiring. Classes annotated with @Component, @Service, @Named, or @ApplicationScoped are recognized as managed beans. Fields and parameters annotated with @Inject, @Autowired, @Value, or @ConfigProperty create USES_TYPE edges connecting consumers to the types they depend on. For property-based configuration [...] - -This gives the AI structural intelligence that goes beyond reading individual files: - -| Capability | What It Does | Example | -|-----------|-------------|---------| -| **Route flow tracing** | Follows the complete message path through a route chain, including cross-route links via `direct:`, `seda:`, and `vm:` endpoints | "Show me every processing step an order goes through from Kafka ingestion to database write" | -| **Impact analysis** | Traces upstream and downstream dependencies of any node -- a route, a class, a configuration property | "If I change the `orderProcessor` bean, which routes are affected?" | -| **DI-aware dependency tracking** | Discovers dependency injection relationships through annotation analysis (@Inject, @Autowired, @Value, @ConfigProperty) and property-based bean wiring (#class:, #bean:, #autowired) | "Show all routes and beans that depend on the `CustomerRepository` interface, including classes injected via property configuration" | -| **Interface expansion** | Traces interface-to-implementation relationships, connecting consumers to all concrete implementations of injected interfaces | "This route uses `PaymentProcessor` interface -- which concrete implementations are wired at runtime, and what other routes depend on them?" | -| **Retirement-candidate detection** | Reports graph-covered unused-dependency, unreferenced-route, and stale-property candidates for owner validation; it does not prove they are dead | "This project has 12 Maven dependencies but only 8 are referenced by graph-covered routes" | -| **Route topology mapping** | Maps route-to-route connections to determine which routes are independent | Used by Claude and Bob 2 to dispatch independent routes to parallel subagents for simultaneous implementation | -| **Project norm extraction** | Computes statistical norms from the existing codebase -- naming patterns, error handling coverage, route complexity percentiles | Validation thresholds adapt to the project's actual conventions rather than using hardcoded defaults | -| **Migration context analysis** | Produces bounded structured JSON for nodes reached from a route, including endpoint schemes, bean classes, artifacts, properties, and synthetic-node warnings | Gives migration analysis a focused local topology view without claiming complete dependency coverage | -| **MuleSoft flow analysis** | Parses MuleSoft XML configs into graph nodes (flows, sub-flows, connectors, endpoints, transforms, error handlers) and analyzes DataWeave scripts for complexity | Understanding MuleSoft project structure before migration -- graph-accelerated analysis replaces manual XML deep-dives | -| **BizTalk artifact analysis** | Parses BizTalk orchestrations (.odx), maps (.btm), pipelines (.btp), and bindings into graph nodes (orchestrations, shapes, maps, functoids, pipelines, components, ports, adapters) | Understanding BizTalk project structure before migration -- 38 shape element names recognized, 45 functoid type mappings | - -The graph integrates across multiple pipeline skills: - -- **During validation**, quality thresholds are derived from the project's actual patterns (e.g., the 75th percentile of route step counts) rather than arbitrary fixed limits. A route with 15 steps is acceptable in a project where existing routes average 12 steps, but flagged in a project where they average 5. -- **During implementation**, the AI matches the project's existing conventions -- naming patterns, bean reuse, dependency versions -- rather than inventing new ones that create inconsistency. -- **During testing**, route topology awareness lets the AI understand upstream and downstream dependencies, generating tests that cover integration points rather than just individual routes in isolation. -- **During migration**, graph analysis can surface structural concerns such as circular dependencies, deeply nested route - chains, and graph-covered retirement candidates before code is translated; bounded source scanning closes the stated - coverage. The separate `graph migration-context` query expands bidirectionally from one route across interface - boundaries, with depth 3 by default and at most 50 expanded nodes. Its local JSON output does not call the Knowledge - MCP or guarantee every dependency or call chain. For MuleSoft projects, the graph automatically parses Mule XML flows, - sub-flows, connectors, and DataWeave scripts. For BizTalk projects, it parses orchestrations, maps, pipelines, and - bindings. - -A key design principle: the graph **enhances but never gates**. Greenfield projects work without any graph -- skills fall back to sensible defaults. When working with an existing project, the graph is built automatically and skills consume it for project-aware behavior. The improvement is transparent: better validation thresholds, more consistent naming, smarter test generation -- without requiring any additional user action. - -### Runtime Verification (Environment-in-the-Loop) - -Code that compiles is not necessarily code that works. Research on LLM-based code generation has shown that AI models cause approximately 30% of runtime errors that are invisible to static analysis -- errors that can only be detected by actually building and running the code in a real environment. - -Camel-Kit's verification pipeline is grounded in the **Environment-in-the-Loop** (EiTL) paradigm described by Li et al. in their ICSE 2026 paper *"Environment-in-the-Loop: Rethinking Code Migration with LLM-based Agents"*. The core argument: code generation treated as a code-only problem is fundamentally incomplete. Code, dependencies, and the execution environment are intricately intertwined -- they must co-evolve. Without automated environment interaction, automation is "only half complete." - -#### The Three-Agent Model - -The EiTL paper proposes three collaborating agents: - -```mermaid -flowchart LR - M["M-Agent\n(Migration/Code)"] -->|"candidate code\n+ dependencies"| E["E-Agent\n(Environment)"] - E -->|"code errors"| M - E -->|"test failures"| T["T-Agent\n(Testsuite)"] - T -->|"behavioral\nfeedback"| E - E -->|"env errors"| E -``` - -- **M-Agent** handles code generation and migration semantics -- **E-Agent** is the central verification hub -- it builds environments, runs code, diagnoses failures, and routes errors to the appropriate agent for fixing -- **T-Agent** generates regression tests and verifies behavioral equivalence - -Camel-Kit maps directly to this model: - -| Paper Concept | Camel-Kit Implementation | -|---------------|-------------------------| -| M-Agent (code generation) | `camel-migrate` + `camel-implement` -- produces Camel routes, dependencies, and configuration | -| E-Agent (environment hub) | `/camel-verify` -- builds or smoke-tests, runs Citrus tests, classifies failures, routes fixes, and reports | -| T-Agent (test generation) | `camel-test` -- generates Citrus integration tests with Testcontainers | - -#### The Feedback Loop - -The critical insight from the EiTL paper is that verification must be a **structured, automated loop** -- not a one-shot instruction. A simple "run the app and fix errors" instruction gives the AI no structure for what errors to look for, how to classify them, where to route fixes, or when to stop trying. - -`/camel-verify` first reports which prerequisites are available, then runs a three-phase flow: - -```mermaid -flowchart TB - C["Prerequisites check\nMaven/JDK/JBang/Docker/Camel test"] - P1["Phase 1\nBuild verification\n(or Camel Main smoke test)"] - P2["Phase 2\nCitrus test verification"] - P3["Phase 3\nVerification report"] - - C --> P1 --> P2 --> P3 - P1 -->|"classified failure + fix"| P1 - P2 -->|"classified failure + fix"| P2 -``` - -For Spring Boot and Quarkus projects, Phase 1 compiles with Maven; Camel Main uses its startup smoke test instead. Phase 2 runs existing Citrus tests through `camel test run`, with Testcontainers managing external services. Build and test failures are classified and retried up to 15 times per phase, with persistent architectural failures eligible for the bounded re-plan loop. Missing tools cause the dependent phase to be skipped explicitly: Docker is required for Phase 2, as are the Came [...] - -The later `/camel-validate` stage is separate from this runtime loop. It performs static quality analysis and reports findings without modifying routes. - -#### Co-Evolution: Code + Environment - -A key principle from the EiTL paper is that code changes often require environment changes. When a route uses a Kafka component, the implementation may need: -- `camel-quarkus-kafka` in `pom.xml` (dependency) -- Kafka broker in `docker-compose.yaml` (environment) -- Connection properties in `application.properties` (configuration) -- The broker actually running before the app starts (operational) - -Camel-Kit's execute phase addresses these dimensions through its environment probe and generated implementation artifacts. Runtime verification then checks the available build and test environment; Citrus Testcontainers start external services during Phase 2 when Docker is available. - -#### Why This Matters - -Traditional AI code generation follows a linear flow: generate code, hand it to the user, hope it works. The EiTL approach closes the loop: generate code, build it, run it, test it, diagnose failures, fix them, and retry -- autonomously, with structured error classification that routes each failure to the right fix strategy. The user only sees the final result (or gets escalated when the system is genuinely stuck). - -### Quality Enforcement - -Every generated route is checked against 8 quality rules (the "Constitution"): - -1. **Route structure** -- every route must have a source and a sink -2. **Single responsibility** -- one route, one purpose -3. **Separation of concerns** -- decompose complex integrations into composable routes -4. **Naming conventions** -- consistent, meaningful route IDs and endpoint names -5. **Observability** -- every route must have an ID and description for monitoring -6. **External configuration** -- no hardcoded credentials or connection strings -7. **Component support verification** -- every component verified via MCP catalog -8. **Infrastructure via Forage** -- prefer the supported infrastructure ladder over hand-rolled bean configuration - -These rules are checked automatically during the validation step and recorded in its static report. - ---- - -## Multi-Agent Support - -Camel-Kit works across multiple AI coding assistants with the same design-plan-execute-validate workflow and output contracts. All targets load shared markdown skills with native agent traits. - -| Agent | Provider | -|-------|----------| -| Claude Code | Anthropic | -| IBM Bob 2 | IBM | -| Google Antigravity | Google | -| Codex CLI | OpenAI | -| GitHub Copilot CLI | GitHub | -| Pi | Community | -| Qwen | Alibaba | -| OpenCode | Community | - -**Why this matters:** -- **No vendor lock-in.** Teams can choose the AI agent that best fits their existing toolchain and licensing. -- **Consistent contracts.** Regardless of which agent generates the routes, the same workflow artifacts, quality rules, and catalog checks apply. Agent-native configuration and generated assistant assets differ according to the selected `--ai` target. -- **Future-proof.** Adding support for a new agent requires writing template files for that agent's instruction format, not rewriting the pipeline logic. - -Each target adapts the workflow to its native skills, custom agents, permissions, and invocation syntax. Workflow and output contracts remain aligned. - ---- - -## Architecture at a Glance - -```mermaid -flowchart TB - init["camel-kit init"] - - subgraph templates ["Agent Templates"] - claude["CLAUDE.md\n(Claude)"] - bob["custom_modes.yaml\n(Bob 2)"] - antigravity["AGENTS.md\n(Antigravity)"] - codex["AGENTS.md + .codex/\n(Codex)"] - copilot[".github/ skills + agents\n(Copilot)"] - pi["AGENTS.md + .pi/\n(Pi)"] - qwen["QWEN.md\n(Qwen)"] - opencode["AGENTS.md\n(OpenCode)"] - end - - skills["Shared Skills"] - - subgraph pipeline ["Pipeline Phases"] - design["Design"] - plan["Plan"] - execute["Execute"] - quality["Validate"] - end - - subgraph internal ["Execute — Internal Steps"] - implement["Implement"] - review["Review"] - test["Test"] - verify["Verify"] - end - - subgraph mcp ["MCP Servers"] - catalog["Camel Catalog MCP\nComponent verification\nOption validation\nSecurity analysis"] - knowledge["Knowledge MCP\nDocumentation\nComponent verification"] - citrus["Citrus MCP\nTest actions\nEndpoint schemas\nYAML DSL schema"] - end - - init --> templates - templates --> skills - skills --> pipeline - design --> plan --> execute --> quality - execute --> internal - implement & review --> catalog - implement & review --> knowledge - quality --> catalog - quality --> knowledge - test --> citrus -``` - -**Skills** carry the process knowledge -- how to conduct a design interview, generate a YAML route, and validate against the constitution. All targets share the markdown skills directly. - -**Camel Catalog MCP** provides the data knowledge -- which components exist, what options they accept, whether an endpoint URI is valid. It queries the live catalog for the project's exact Camel version rather than relying on potentially outdated training data. - -**Knowledge MCP** provides documentation and security intelligence -- documentation search, component and CVE/security-advisory lookup, release information, and JIRA issue lookup. - -**Citrus MCP** provides test-generation intelligence -- which Citrus actions, endpoints, schemas, and best practices are valid for the configured Citrus version. - -**Templates** adapt the workflow to each AI agent's native instruction mechanism, including native skills and custom agents. - ---- - -## Benefits Summary - -| Benefit | How | -|---------|-----| -| **Faster integration development** | AI generates routes, tests, and configuration from a design spec. The engineer focuses on requirements and review, not boilerplate. | -| **Higher quality output** | 8 quality rules checked automatically. Every component verified against the live catalog. No hardcoded credentials, unnamed routes, or unsupported components. | -| **Reduced runtime failures** | Real-time catalog verification catches configuration errors at design time. Runtime verification catches remaining issues before deployment. | -| **Migration de-risking** | Automated analysis of MuleSoft, legacy Camel, Fuse, and BizTalk projects. DI-aware graph analysis discovers bean relationships through annotation scanning and property-based wiring, traces interface implementations, and can produce bounded local migration context for a route. Graph-accelerated MuleSoft analysis parses flows, sub-flows, connectors, and DataWeave scripts automatically. Graph-accelerated BizTalk analysis parses orchestrations, maps, pipelines, a [...] -| **No AI vendor lock-in** | Works with multiple AI agents under the same workflow and quality contracts while generating the selected target's native assistant assets. | -| **Maintainable and extensible** | Skills are plain markdown. Adding new capabilities means writing a new skill guide, not modifying code. | - ---- - -## Technology Stack - -| Component | Technology | -|-----------|-----------| -| CLI runtime | Java 17+ / JBang | -| Build system | Maven (with wrapper) | -| Route format | Camel YAML DSL | -| Target runtime | Spring Boot, Quarkus, or JBang | -| Catalog access | Camel MCP server (live catalog queries via Model Context Protocol) | -| Documentation | Knowledge MCP server (Apache Camel docs -- hybrid semantic search) | -| Testing | Citrus MCP + Citrus YAML + Testcontainers | -| IDE support | Kaoto (visual route and DataMapper editing) | -| AI agents | Claude Code, IBM Bob 2, Google Antigravity, OpenAI Codex CLI, GitHub Copilot CLI, Pi, Qwen, OpenCode | - ---- - -## Current Status - -Camel-Kit is an open-source project under the Apache 2.0 license. It is inspired by [GitHub Spec-Kit](https://github.com/github/spec-kit) and adapted for the Apache Camel ecosystem. - -The project is actively developed, with the core pipeline (design, plan, execute, validate), internal runtime verification, migration support, DataMapper, multi-agent parity, and the knowledge layer all functional. +This overview moved to the published documentation at https://camel.apache.org/camel-kit/next/, whose Antora source +is [`docs/modules/ROOT/pages/`](modules/ROOT/pages/). Its former sections now live on these pages: + +| Former section | Published page (Antora source) | +|---|---| +| What Camel-Kit is, the problem it solves, how it works | [Camel Kit](https://camel.apache.org/camel-kit/next/) (`index.adoc`) | +| The pipeline, gates and Iron Laws | [Stages, approval gate and Iron Laws](https://camel.apache.org/camel-kit/next/pipeline.html) (`pipeline.adoc`) | +| Runtime verification (Environment-in-the-Loop) | [eitl.html](https://camel.apache.org/camel-kit/next/eitl.html) (`eitl.adoc`) and [verification.html](https://camel.apache.org/camel-kit/next/verification.html) (`verification.adoc`) | +| Project graph analysis | [graph.html](https://camel.apache.org/camel-kit/next/graph.html) (`graph.adoc`) | +| Migration | [migration.html](https://camel.apache.org/camel-kit/next/migration.html) (`migration.adoc`) | +| Quality enforcement (the constitution) | [constitution.html](https://camel.apache.org/camel-kit/next/constitution.html) (`constitution.adoc`) | +| Multi-agent support | [Supported AI agents](https://camel.apache.org/camel-kit/next/agents.html) (`agents.adoc`) | +| MCP servers and the knowledge layer | [mcp.html](https://camel.apache.org/camel-kit/next/mcp.html) (`mcp.adoc`) and [knowledge.html](https://camel.apache.org/camel-kit/next/knowledge.html) (`knowledge.adoc`) | diff --git a/docs/commands.md b/docs/commands.md index 1d56a787..97f9c1bb 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -942,7 +942,7 @@ Validation is static and report-only: it does not modify routes or fix the findi The preview status applies to every Ship backend. `--accept-experimental` only permits unverified Pi/Node versions; it does not enable Ship or change its preview status. Tested runtime compatibility and passing validation checks do not imply production readiness. -**Purpose:** Start or control the local Ship workflow through the configured Camel-Kit CLI. Harness skills delegate stage decisions and state to the CLI. Eligible Bob 2, Copilot CLI, Claude Code, OpenAI Codex CLI, Qwen Code and OpenCode sessions relay pending work to native subagents; other execution models retain the single CLI invocation. See [Bob native Ship](ship-native.md), [Copilot native Ship](ship-copilot.md), [Claude Code native Ship](ship-claude.md) and [Codex CLI native Ship]( [...] +**Purpose:** Start or control the local Ship workflow through the configured Camel-Kit CLI. Harness skills delegate stage decisions and state to the CLI. Eligible Bob 2, Copilot CLI, Claude Code, OpenAI Codex CLI, Qwen Code and OpenCode sessions relay pending work to native subagents; other execution models retain the single CLI invocation. See [Bob native Ship](ship-native.md), [Claude Code native Ship](ship-claude.md) and, for Copilot CLI and Codex CLI, the published [Ship native subag [...] The registered command is `camel-kit ship` when Camel-Kit is installed standalone and `camel kit ship` when it is installed as a Camel JBang plugin. Harness-native forms such as `/camel-ship`, `$camel-ship`, and `/skill:camel-ship` invoke that configured command prefix. Pi uses `/skill:camel-ship`; Camel-Kit intentionally does not generate a Pi `/camel-ship` prompt because that prompt surface flattens quoted option values. diff --git a/docs/ship-claude.md b/docs/ship-claude.md index 91b086f1..c1201669 100644 --- a/docs/ship-claude.md +++ b/docs/ship-claude.md @@ -2,7 +2,7 @@ **Technology Preview:** Camel Ship is still being stabilized. Its behavior and interfaces may change, and it is not recommended for production use. For the established staged workflow, start with `/camel-start`. See the [Ship command reference](commands.md#camel-ship) for the preview scope. -This development integration implements [#222](https://github.com/luigidemasi/camel-kit/issues/222) using the shared +This development integration implements [#93](https://github.com/apache/camel-kit/issues/93) using the shared [native controller handoff](ship-native.md#controller-handoff). A development build is required. Authenticated acceptance passed on **2026-09-10 with Claude Code 2.1.267 on Linux**, driven headlessly (`claude -p`) in a diff --git a/docs/ship-codex.md b/docs/ship-codex.md index c7714e82..19b9a314 100644 --- a/docs/ship-codex.md +++ b/docs/ship-codex.md @@ -1,75 +1,7 @@ # OpenAI Codex CLI native Ship -**Technology Preview:** Camel Ship is still being stabilized. Its behavior and interfaces may change, and it is not recommended for production use. For the established staged workflow, start with `$camel-start`. See the [Ship command reference](commands.md#camel-ship) for the preview scope. - -This development integration implements [#225](https://github.com/luigidemasi/camel-kit/issues/225) using the shared -[native controller handoff](ship-native.md#controller-handoff). A development build is required. - -After upgrading Camel-Kit, regenerate the project's Codex CLI assets. Preserve customizations before using `--force`: - -```bash -camel-kit init --here --ai codex --force -# Camel JBang plugin installation: -camel kit init --here --ai codex --force -``` - -In a trusted, authenticated Codex CLI session, invoke `$camel-ship` from the generated project skill. The session must -expose the project `camel_ship_worker` custom agent. The parent must already have permission for the complete requested -workflow. Plan mode supports only read-only `ship --status`; starting, resuming, submitting or aborting work requires a -session authorized to implement. Normal permissions, sandbox policies, repository trust, approval policies, other Camel -roles and MCP configuration remain in effect. - -An eligible new run selects `--backend codex-native --json` unless the user explicitly chooses a backend. If the user -explicitly selects `--backend codex-native` but native dispatch is unavailable, the skill reports that this session -cannot service the requested backend and stops without starting a run. If no backend was chosen and native dispatch is -unavailable, a new authorized run keeps the existing CLI/Pi execution model. Existing runs retain their recorded -backend: a `CODEX_NATIVE` run needs an eligible Codex CLI session to dispatch further work. Bob, Copilot, Claude and -Pi runs do not switch to Codex, and Codex runs cannot switch to another host during recovery. - -## Native task and restrictions - -The parent relays the controller's complete prompt by invoking the `camel_ship_worker` custom agent. The prompt must be -copied verbatim, including on retries; its schema and oversight rules cannot be summarized. Model overrides are omitted -so the active session's settings apply. Camel-Kit does not start another Codex process or discover Pi/Node for native -stages. - -The custom agent declares `sandbox_mode = "read-only"` and no `[mcp_servers]` section. Where the host enforces sandbox -restrictions on the child, those restrictions apply. Where they are not enforced, the worker runs under the parent -session's existing authorized permissions — repository trust, sandbox policy and approval settings remain in effect. -The worker is instructed not to edit project files, write to the controller's candidate or state directory, delegate, -or publish; on hosts that enforce `sandbox_mode` the host prevents those actions, otherwise the instruction is the -operative restriction. The worker may use the host's available means to read input and source files (including shell -commands for file reading where that is the host's mechanism). - -The worker returns structured stage results and, for EXECUTE, complete text proposals for the approved route, Citrus -test, `pom.xml` and `.camel-kit/config.properties`. The controller validates those proposals, writes its private -candidate, computes hashes and runs deterministic checks before guarded publication. The native contract does not -accept arbitrary extra resources, binary files or deletions. - -The child's read access follows the repository trust boundary and parent permissions. Do not broaden permissions, -disable sandbox, add tools or substitute another role when a task cannot access its inputs. Linux and the existing -Camel Main/YAML/Simple/Citrus contract remain required. Host versions are caller-reported diagnostics, not release -certification. - -## Recovery - -The shared [resume, timeout and abort contract](ship-native.md#resume-timeout-and-abort) also applies to Codex CLI. The -parent submits the observed child response through `ship --submit RUN_ID --result PATH --json`, retaining the exact -envelope until acknowledged. Identical accepted submissions are idempotent; conflicting, stale, wrong-task and late -aborted-run results are rejected. Only the controller advances stages or pauses for oversight. - -After parent interruption, inspect `--status --json`. Wait for a still-running child or submit its saved response. -If its result is unavailable, do not dispatch the same pending task again. Its deadline is retained; `--resume` after -expiry fails that attempt, and another explicit resume issues a new task. Use Codex's cancellation controls to stop -host-owned children. Ship cannot terminate them; abort invalidates the run and rejects further submissions. The worker -is instructed not to edit the candidate; on hosts that enforce sandbox restrictions the host prevents those actions. -Host cancellation is needed to stop the child process. - -Failed runs return JSON with exit code 1; show `run.message` and wait for explicit resume. Errors may return stderr -without JSON. Stop after command errors, including `stale-stage-input` or permission denial, and obtain a new user request -before resuming or changing arguments. For `handoff-read-failed`, plain status can show the recorded run; explicit resume first records failure, -then a second explicit resume creates a fresh task. Never repair evidence by hand. Repeat the original `--stage-timeout`, -`--maven-repository` and `-c`/`-p` settings on submit/resume; these settings are not persisted for subsequent stages. - -Oversight pauses require an explicit user decision. A returned child result is a transport result, not proof that -validation passed: report the controller's final status, evidence and publication paths. +This page moved to the published documentation: [Ship workflow — Native subagents](https://camel.apache.org/camel-kit/next/ship.html#native) +describes the Codex CLI contract (`camel_ship_worker`, `--backend codex-native`, the development-snapshot status) and +[Entry points per agent](https://camel.apache.org/camel-kit/next/ship.html#entry-points) the `$camel-ship` entry point. +The Antora source is [`docs/modules/ROOT/pages/ship.adoc`](modules/ROOT/pages/ship.adoc). The shared controller +handoff and the resume, timeout and abort contract remain described in [ship-native.md](ship-native.md). diff --git a/docs/ship-copilot.md b/docs/ship-copilot.md index fa2a1650..1244a035 100644 --- a/docs/ship-copilot.md +++ b/docs/ship-copilot.md @@ -1,76 +1,7 @@ # Copilot CLI native Ship -**Technology Preview:** Camel Ship is still being stabilized. Its behavior and interfaces may change, and it is not recommended for production use. For the established staged workflow, start with `/camel-start`. See the [Ship command reference](commands.md#camel-ship) for the preview scope. - -This development integration implements [#226](https://github.com/luigidemasi/camel-kit/issues/226) using the shared -[native controller handoff](ship-native.md#controller-handoff). A development build is required. - -Authenticated acceptance passed on **2026-09-09 with GitHub Copilot CLI 1.0.83 on Linux**. The registered skill completed -all four native stages, paused for explicit SMART approvals, passed all five mandatory checks including Camel startup -and Citrus, and published files independently compared with the requested contents and private candidate. Native -cancellation, timeout and explicit recovery, repeated submissions, stale/conflicting results, abort/late results, -plan-mode refusal and read/tool restrictions were exercised. This evidence covers that CLI version and fixture; -other hosts and versions are not certified by it. - -After upgrading Camel-Kit, regenerate the project's Copilot assets. Preserve customizations before using `--force`: - -```bash -camel-kit init --here --ai copilot --force -# Camel JBang plugin installation: -camel kit init --here --ai copilot --force -``` - -In a trusted, authenticated Copilot CLI session, invoke `/camel-ship` from the generated project skill. The session must -expose the `task` tool and the project `camel-ship-worker` custom agent. The parent must already have permission for the -complete requested workflow. Plan mode supports only read-only `ship --status`; starting, resuming, submitting or -aborting work requires a session authorized to implement. Restricted custom agents cannot use Ship to escape their scope. Normal -permissions, repository hooks, other Camel roles and MCP configuration remain in effect. - -An eligible new run selects `--backend copilot-native --json` unless the user explicitly chooses a backend. If native -dispatch is unavailable, a new authorized run keeps the existing CLI/Pi execution model. Existing runs retain their -recorded backend: a `COPILOT_NATIVE` run needs an eligible Copilot session to dispatch further work. Bob and Pi runs do -not switch to Copilot, and Copilot runs cannot switch to another host during recovery. - -## Native task and restrictions - -The parent relays the controller's complete prompt through `task` with `agent_type: "camel-ship-worker"`, `mode: "sync"` -and a name derived from the controller task ID. Copilot starts a fresh child context; its tool has no `fork_context` -argument. The prompt must be copied verbatim, including on retries; its schema and oversight rules cannot be summarized. -Model and reasoning overrides are omitted so the active session's settings apply. Camel-Kit does not start -another Copilot process or discover Pi/Node for native stages. - -The custom agent allows only Copilot's `read` and `search` tool aliases. It returns structured stage results and, for -EXECUTE, complete text proposals for the approved route, Citrus test, `pom.xml` and `.camel-kit/config.properties`. -The controller validates those proposals, writes its private candidate, computes hashes and runs deterministic checks -before guarded publication. The native contract does not accept arbitrary extra resources, binary files or deletions. - -A fresh context is not an OS sandbox. Read access follows the parent's permitted paths, including any explicitly added -directories. The child is instructed to read only controller inputs and relevant sources; it has no edit, command, MCP -or delegation tools. Do not broaden permissions or substitute another role when a task cannot access its inputs. -Linux and the existing Camel Main/YAML/Simple/Citrus contract remain required. Host versions are caller-reported -diagnostics, not release certification. - -Copilot documents [custom-agent tool restrictions and separate contexts](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents) -and [CLI permissions and task controls](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference). - -## Recovery - -The shared [resume, timeout and abort contract](ship-native.md#resume-timeout-and-abort) also applies to Copilot. The -parent submits the observed child response through `ship --submit RUN_ID --result PATH --json`, retaining the exact -envelope until acknowledged. Identical accepted submissions are idempotent; conflicting, stale, wrong-task and late -aborted-run results are rejected. Only the controller advances stages or pauses for oversight. - -After parent interruption, inspect `--status --json`. Wait for a still-running child or submit its saved response. -If its result is unavailable, do not dispatch the same pending task again. Its deadline is retained; `--resume` after -expiry fails that attempt, and another explicit resume issues a new task. Use Copilot's cancellation controls to stop -host-owned children. Ship cannot terminate them; abort invalidates the run, and read-only children cannot modify the -candidate even if they outlive the parent. - -Failed runs return JSON with exit code 1; show `run.message` and wait for explicit resume. Errors may return stderr -without JSON. Stop after command errors, including `stale-stage-input` or permission denial, and obtain a new user request -before resuming or changing arguments. For `handoff-read-failed`, plain status can show the recorded run; explicit resume first records failure, -then a second explicit resume creates a fresh task. Never repair evidence by hand. Repeat the original `--stage-timeout`, -`--maven-repository` and `-c`/`-p` settings on submit/resume; these settings are not persisted for subsequent stages. - -Oversight pauses require an explicit user decision. Copilot's synchronous return is a transport result, not proof that -validation passed: report the controller's final status, evidence and publication paths. +This page moved to the published documentation: [Ship workflow — Native subagents](https://camel.apache.org/camel-kit/next/ship.html#native) +describes the GitHub Copilot CLI contract (`camel-ship-worker`, `--backend copilot-native`, the accepted CLI version) +and [Entry points per agent](https://camel.apache.org/camel-kit/next/ship.html#entry-points) the `/camel-ship` entry +point. The Antora source is [`docs/modules/ROOT/pages/ship.adoc`](modules/ROOT/pages/ship.adoc). The shared +controller handoff and the resume, timeout and abort contract remain described in [ship-native.md](ship-native.md). diff --git a/docs/ship-native.md b/docs/ship-native.md index 33fdd83e..e8dd42fe 100644 --- a/docs/ship-native.md +++ b/docs/ship-native.md @@ -5,7 +5,7 @@ Development status: authenticated acceptance on 2026-09-09 exercised Bob Shell 2.0.2 on Linux through the registered Ship skill: four native stages, oversight pauses and explicit resume, deterministic validation and publication. Interruption, timeout recovery, abort, repeated submissions and rejection of stale/conflicting results were also checked. -This integration is tracked in [#223](https://github.com/luigidemasi/camel-kit/issues/223) and requires a development build. +This integration is tracked in [#94](https://github.com/apache/camel-kit/issues/94) and requires a development build. Bob IDE and other host versions have not undergone the same live acceptance test. In an eligible Bob 2 session, the generated Ship skill uses Bob's `spawn_subagent` tool. The active Bob session keeps its @@ -74,6 +74,6 @@ Bob handles cancellation of its native call. The Ship CLI cannot terminate a hos the run and rejects later submissions. Because children are read-only, an orphan cannot write into the candidate. Oversight questions stay with the parent, and paused runs continue only through an explicit resume. -Track implementation and host validation in [core #223](https://github.com/luigidemasi/camel-kit/issues/223), under -[shared native handoff #221](https://github.com/luigidemasi/camel-kit/issues/221). Other agent adapters and Pi +Track implementation and host validation in [core #94](https://github.com/apache/camel-kit/issues/94), under +[shared native handoff #92](https://github.com/apache/camel-kit/issues/92). Other agent adapters and Pi compatibility retain their separate tasks. diff --git a/docs/user-guide.md b/docs/user-guide.md index c7c91fa7..7a6daf8b 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -132,7 +132,7 @@ The verification loop treats code, dependencies, and the execution environment a **Technology Preview:** Camel Ship is still being stabilized. Its behavior and interfaces may change, and it is not recommended for production use. For the established staged workflow, start with `/camel-start`. -The standalone `/camel-ship` workflow additionally requires Linux. Its default backend needs Pi and Node; eligible Bob 2, Copilot CLI, Claude Code and OpenAI Codex CLI sessions can use their own native children. See [Bob native Ship](ship-native.md), [Copilot native Ship](ship-copilot.md), [Claude Code native Ship](ship-claude.md) and [Codex CLI native Ship](ship-codex.md). Its current deterministic evidence path accepts Camel Main projects with Camel YAML DSL route artifacts; Spring Boo [...] +The standalone `/camel-ship` workflow additionally requires Linux. Its default backend needs Pi and Node; eligible Bob 2, Copilot CLI, Claude Code and OpenAI Codex CLI sessions can use their own native children. See [Bob native Ship](ship-native.md), [Claude Code native Ship](ship-claude.md) and, for Copilot CLI and Codex CLI, the published [Ship native subagents](https://camel.apache.org/camel-kit/next/ship.html#native) section. Its current deterministic evidence path accepts Camel Main [...] ### Initializing a Project @@ -193,7 +193,7 @@ reports each affected `SKILL.md` as `FAIL` with regeneration instructions, inclu when a nested `metadata.user-invocable` value overrides the top-level field. If only `$camel-start` appears in the skill picker, upgrade to a build containing the -[#213 fix](https://github.com/luigidemasi/camel-kit/issues/213), exit Bob, and regenerate +[#89 fix](https://github.com/apache/camel-kit/issues/89), exit Bob, and regenerate from the project root using the same command surface as the original initialization: ```bash diff --git a/kit/README.md b/kit/README.md index b1d49a72..8e6a2b66 100644 --- a/kit/README.md +++ b/kit/README.md @@ -7,7 +7,7 @@ Part of the [Apache Camel Kit monorepo](../README.md). Source-build commands bel </p> [](https://opensource.org/licenses/Apache-2.0) -[](../docs/modules/ROOT/pages/index.adoc) +[](https://camel.apache.org/camel-kit/next/) > Design, implement, and verify Apache Camel integrations with AI coding > assistants. @@ -67,7 +67,7 @@ Camel JBang and its test plugin are needed for the complete execution and verifi **Technology Preview:** Camel Ship is still being stabilized. Its behavior and interfaces may change, and it is not recommended for production use. For the established staged workflow, start with `/camel-start`. -The optional Ship controller requires Linux and supports Camel Main projects with YAML DSL routes. Its default backend requires Pi and Node. Bob 2, GitHub Copilot CLI and Claude Code can use their own read-only native subagents through the generated Ship skill; the controller writes their proposals and validates the result. Current development builds also support Codex native Ship. See [Bob native Ship](../docs/ship-native.md), [Copilot native Ship](../docs/ship-copilot.md), [Claude Code [...] +The optional Ship controller requires Linux and supports Camel Main projects with YAML DSL routes. Its default backend requires Pi and Node. Bob 2, GitHub Copilot CLI and Claude Code can use their own read-only native subagents through the generated Ship skill; the controller writes their proposals and validates the result. Current development builds also support Codex native Ship. See [Bob native Ship](../docs/ship-native.md), [Claude Code native Ship](../docs/ship-claude.md) and, for C [...] `camel-kit init` checks Java, JBang, Camel JBang, and the Camel test plugin. Missing tools produce warnings but don't block initialization; Docker and Ship prerequisites are checked when those workflows run. @@ -121,7 +121,7 @@ camel kit init my-integration --ai claude To upgrade from `0.3.1`, reinstall the plugin at `0.4.1`. The retired `bob` and `gemini` targets are replaced by `bob2` (the default) and `antigravity`; see the -[migration instructions](../docs/antigravity.md). Back up customized generated files before reinitializing with `--force`. +[migration instructions](https://camel.apache.org/camel-kit/next/agents.html#retired-targets). Back up customized generated files before reinitializing with `--force`. ### Upgrade from 0.4.0 @@ -270,7 +270,7 @@ All supported targets use shared markdown skills with agent-specific traits and --- -See [Antigravity setup and migration from Gemini or Bob v1](../docs/antigravity.md). +See [Google Antigravity](https://camel.apache.org/camel-kit/next/agents.html#antigravity) and [Retired targets](https://camel.apache.org/camel-kit/next/agents.html#retired-targets) in the published documentation. ## Key Features diff --git a/kit/camel-jbang-plugin-kit/README.md b/kit/camel-jbang-plugin-kit/README.md index 42333be7..71024297 100644 --- a/kit/camel-jbang-plugin-kit/README.md +++ b/kit/camel-jbang-plugin-kit/README.md @@ -69,7 +69,7 @@ Release `0.4.1` supports `bob2`, `antigravity`, `claude`, `codex`, `copilot`, `p | `camel kit nextId` | Create the next pipeline ID | | `camel kit ship` | Run or control the local Ship workflow (Technology Preview) | -When upgrading from `0.3.1`, replace the retired `bob` and `gemini` targets with `bob2` and `antigravity`; see [migration guidance](../docs/antigravity.md). +When upgrading from `0.3.1`, replace the retired `bob` and `gemini` targets with `bob2` and `antigravity`; see [migration guidance](https://camel.apache.org/camel-kit/next/agents.html#retired-targets). ## Development @@ -77,7 +77,7 @@ The plugin uses `@CamelJBangPlugin` discovery and delegates its commands to `cam ## Related Projects -- [Camel Kit](https://github.com/luigidemasi/camel-kit) +- [Camel Kit](https://github.com/apache/camel-kit) - [Apache Camel](https://camel.apache.org/) - [Camel JBang](https://camel.apache.org/manual/camel-jbang.html) diff --git a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java index 52a9950f..429d7a3f 100644 --- a/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java +++ b/kit/camel-kit-core/src/test/java/org/apache/camel/kit/generator/ResourceConsistencyTest.java @@ -1748,6 +1748,29 @@ class ResourceConsistencyTest { "The Forage compatibility table must be rendered from distribution.properties"); } + @Test + void repositoryLinksPointAtTheApacheRepository() throws IOException { + Path root = repositoryRoot(); + List<Path> files = new ArrayList<>( + List.of( + root.resolve("README.md"), + root.resolve("kit/README.md"), + root.resolve("CONTRIBUTING.md"), + root.resolve("kit/camel-jbang-plugin-kit/README.md"))); + try (Stream<Path> docs = Files.list(root.resolve("docs"))) { + docs.filter(path -> path.toString().endsWith(".md")).forEach(files::add); + } + + for (Path file : files) { + // The former repository is only referenced by the JBang alias of the published 0.4.1 release and by + // historical CHANGELOG compare links; every URL into it from the documentation is stale (#162). + assertFalse(Files.readString(file).contains("github.com/luigidemasi/camel-kit/"), + file.getFileName() + " links to the former repository (#162)"); + } + assertTrue(Files.readString(root.resolve("kit/README.md")).contains("https://camel.apache.org/camel-kit/next/"), + "The Kit README must point at the published documentation (#162)"); + } + @Test void commandReferenceDefaultsMatchTheDistribution() throws IOException { DistributionConfig distribution = DistributionConfig.loadBundled();
