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
The following commit(s) were added to refs/heads/main by this push:
new 7cf40c43 docs: write the Pipeline pages for camel.apache.org
7cf40c43 is described below
commit 7cf40c43b5c26c5e160a721750ed2e1697f820e7
Author: Luigi De Masi <[email protected]>
AuthorDate: Fri Oct 23 10:42:08 2026 +0200
docs: write the Pipeline pages for camel.apache.org
Replace the nine Pipeline stubs of the Antora component with the rewritten
content: the stages, approval gate and Iron Laws overview, camel-start,
camel-brainstorm, camel-plan, camel-execute, camel-validate, the internal
runtime verification loop, camel-debug and the Ship workflow (Technology
Preview). The Ship page merges the four per-agent native Ship documents into
one shared contract plus a per-host table. The text is rewritten from the
standalone website and the repository documentation into the Camel
documentation register, and every claim was checked against the skill
manifests and guides (camel-start, camel-brainstorm, camel-plan,
camel-execute, camel-validate, camel-verify, camel-debug, camel-ship,
shared/iron-laws.md), docs/commands.md, docs/ship-*.md, the workflow
manifest
and the 0.4.1 release tag; features added after the release (Codex native
Ship, direct migration mode) are marked as development snapshot only.
Built locally with Antora 3.2 and the Camel website UI bundle at log failure
level warn: 27 pages, no warnings, no absolute camel.apache.org links in the
generated HTML.
---
docs/antora.yml | 3 +
docs/modules/ROOT/pages/camel-brainstorm.adoc | 139 ++++++++++++-
docs/modules/ROOT/pages/camel-debug.adoc | 67 ++++++-
docs/modules/ROOT/pages/camel-execute.adoc | 154 ++++++++++++++-
docs/modules/ROOT/pages/camel-plan.adoc | 152 ++++++++++++++-
docs/modules/ROOT/pages/camel-start.adoc | 70 ++++++-
docs/modules/ROOT/pages/camel-validate.adoc | 66 ++++++-
docs/modules/ROOT/pages/pipeline.adoc | 135 ++++++++++++-
docs/modules/ROOT/pages/ship.adoc | 269 +++++++++++++++++++++++++-
docs/modules/ROOT/pages/verification.adoc | 125 +++++++++++-
10 files changed, 1170 insertions(+), 10 deletions(-)
diff --git a/docs/antora.yml b/docs/antora.yml
index 2b349cf0..f1501b29 100644
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -29,3 +29,6 @@ asciidoc:
camel-kit-snapshot-version: 0.4.2-SNAPSHOT
camel-kit-knowledge-version: 0.0.2
camel-version: 4.22.1
+ pi-version: 0.84.2
+ pi-previous-version: 0.83.0
+ node-version: 22.22.2
diff --git a/docs/modules/ROOT/pages/camel-brainstorm.adoc
b/docs/modules/ROOT/pages/camel-brainstorm.adoc
index f1194ea9..3af9897c 100644
--- a/docs/modules/ROOT/pages/camel-brainstorm.adoc
+++ b/docs/modules/ROOT/pages/camel-brainstorm.adoc
@@ -1,3 +1,140 @@
= camel-brainstorm
-This page is written in a following documentation pull request.
+`/camel-brainstorm` is the design stage for new integrations. It extracts what
it can from the material you supply,
+asks one question at a time for what is still unresolved, verifies every
component in the Camel catalog, and
+produces the design specification that you approve before anything is planned
or generated. Migrations use
+xref:migration.adoc[`/camel-migrate`] instead, which has its own discovery and
design contract.
+
+Do not use it for quick property changes, version bumps or a single well-known
component addition (edit the file),
+for Camel questions (`/camel-knowledge`), or when a design already exists
(`/camel-plan`). Every other new
+integration goes through it, however small: short designs are fine, skipped
designs are not.
+
+[[modes]]
+== Invocation modes
+
+Chained::
+`/camel-brainstorm` without an argument, or through `/camel-start`. Runs
interview, design and approval, then
+invokes `/camel-plan` itself. If no pipeline is active it first asks you to
create one with
+`camel-kit nextId <slug>`.
+
+Standalone::
+`/camel-brainstorm <pipeline-id>` for a pipeline that has no design yet. Runs
the same flow, writes the design to
+`docs/camel-kit/<pipeline-id>/design-spec.md` and stops.
+
+Amend::
+`/camel-brainstorm <pipeline-id>` when `design-spec.md` already exists. The
skill loads the specification, asks what
+to change, re-runs the affected parts of the interview and re-verifies changed
components, presents the amended
+specification for approval, overwrites it, marks each existing direct child
stale with `camel-kit doc stale` (the
+implementation plan, and the migration runbook for migration pipelines) and
stops.
+
+At start the skill reads `docs/constitution.md` (copying it from the bundled
template if it is missing) and
+`.camel-kit/config.properties` when present.
+
+[[interview]]
+== The interview
+
+The interview is adaptive, not a fixed questionnaire. The agent analyzes the
requirements, examples and other
+material you provide first and does not ask about facts that are already
established; complete material can need no
+clarification at all. Open points are asked one at a time, never in batches,
in three groups:
+
+. *Project questions*: name, business purpose, systems landscape, integration
goals or flow names.
+. *Per-flow questions*: intent and data, source, transformations, sink and
error handling, with field-mapping,
+ multi-path routing and resilience follow-ups only when triggered.
+. *Cross-cutting questions*: performance, security and monitoring when
relevant, then remaining constraints and the
+ deliberate scope exclusions. A category that does not apply is recorded as
not applicable with the reason.
+
+.Topics the interview can cover, with example exchanges
+[%collapsible]
+====
+Business purpose::
+"What business problem does this integration solve?" The answer is recorded in
the executive summary and guides every
+later decision.
+
+Systems and endpoints::
+"Where does data come from, and where does it go?" Sources, destinations,
protocols and intermediary systems for
+enrichment or validation.
+
+Data formats::
+Input and output formats, schemas, and whether a field-level mapping is
needed. For a complex mapping the agent
+offers DataMapper, which uses inline Groovy when both schemas are absent or
the mapping has fewer than 20 leaf fields
+and XSLT only with at least 20 leaf fields and at least one schema.
+
+Processing requirements::
+Validations, business rules, calculations and enrichments, and conditional
routing when several destinations are
+named.
+
+Error handling::
+What happens when a source or a destination is unavailable. The agent offers a
dead letter channel, retry with
+backoff (the recommended default), log and continue, or stop the route, and
follows up on a circuit breaker for HTTP
+sources or sinks, an idempotent consumer for message brokers, and transactions
for flows that write to several
+systems.
+
+Performance and observability::
+Throughput, latency, metrics, logging and tracing when the project needs them.
+
+Scope boundaries::
+"Which related capabilities should this iteration not implement, and why?" If
nothing is excluded, the design records
+*None identified* instead of inventing boundaries.
+====
+
+The questions live in the generated interview guide of your agent, for example
+`.claude/skills/camel-brainstorm/guides/greenfield-interview.md` for Claude
Code. You can add project-specific
+conditional follow-ups there, recording their answers under the cross-cutting
section, without adding fixed rounds or
+changing the specification schema.
+
+[[catalog]]
+== Catalog verification
+
+After the interview and before the design is assembled, the agent selects
components through the `camel` MCP
+server, for the project's runtime and full platform BOM, and reads the
documentation of each candidate. For a
+requirement such as "connect to Kafka":
+
+. It establishes one version binding with a `camel_catalog_components` probe
and checks the returned Camel version.
+. Under that binding it searches the component list by category and proposes a
component by exact identity; a
+ complete enumeration is required only before an artifact is recorded as not
found.
+. It calls `camel_catalog_component_doc` for the syntax and options and
`camel_catalog_component_maven` for the
+ runtime-specific coordinates; EIPs, data formats and languages use their own
documentation tools.
+. It records the binding and a `VERIFIED` result with tool provenance for each
artifact in the *Catalog Verification
+ Evidence* block of section 5.
+
+If a requested component does not exist in the complete list, the agent asks
for clarification or proposes an
+alternative from that list; it never writes an unverified name into the
design. A detail-call error is not proof of
+absence. This is Iron Law 1 (see xref:pipeline.adoc#iron-laws[Iron Laws]).
+
+[[spec]]
+== The design specification
+
+After discovery and the Camel version selection, the agent assembles
`design-spec.md`:
+
+[cols="1,3"]
+|===
+| Section | Content
+
+| Not Doing (and Why) | Unnumbered, at the top: each deliberately excluded
capability and its rationale, so later
+ stages treat it as a scope boundary
+| 1. Executive summary | Business purpose, business value, stakeholders
+| 2. Systems landscape | Systems, technologies, protocols and source or target
roles
+| 3. Flow designs | One design per named flow: target module, purpose,
verified source and sink with their exact
+ options, transformations, error handling, configuration properties and the
rationale of each choice
+| 4. Cross-cutting concerns | Performance, security, monitoring and
constraints; when nothing special applies, the
+ standard behaviour is recorded rather than invented
+| 5. Constitution compliance | How every flow meets the eight rules, plus the
catalog verification evidence
+| 6. Project structure | The runtime-aware project tree: routes, properties,
schemas, tests, DataMapper files and
+ the conditional build or Docker files
+|===
+
+A migration design has the same six sections plus *7. Migration Context*; it
includes *Not Doing (and Why)* only when
+discovery captured explicit exclusions.
+
+Before presenting the specification the agent reviews it for placeholders,
contradictions, unverified components and
+flows that cross a scope boundary. You then approve ("Approved, looks good")
or request changes, and the agent
+revises and presents again. In chained mode the approval invokes `/camel-plan`
immediately; the skill never asks you
+to run it by hand.
+
+[[patterns]]
+== Common patterns
+
+* *Request-reply.* HTTP in, a database query, the result in the HTTP response:
one synchronous flow.
+* *Fire-and-forget.* Accept with HTTP 202 and process in the background: two
flows joined by an in-memory queue.
+* *Multi-system with compensation.* Parallel writes to several systems that
must all succeed or be rolled back:
+ several flows coordinated with the Saga pattern.
diff --git a/docs/modules/ROOT/pages/camel-debug.adoc
b/docs/modules/ROOT/pages/camel-debug.adoc
index 24a128e1..da1720b3 100644
--- a/docs/modules/ROOT/pages/camel-debug.adoc
+++ b/docs/modules/ROOT/pages/camel-debug.adoc
@@ -1,3 +1,68 @@
= camel-debug
-This page is written in a following documentation pull request.
+`/camel-debug` diagnoses and repairs a broken Camel route outside a pipeline
run: a route that used to work, a
+startup failure, a runtime exception, unexpected behaviour. Build and test
failures during `/camel-execute` stay in
+that stage's verification loop (see xref:verification.adoc[]); quality
validation belongs to
+xref:camel-validate.adoc[`/camel-validate`]. The project needs
`.camel-kit/config.properties` for the runtime and
+version, and existing route files.
+
+----
+/camel-debug
+/camel-debug my route fails with a ClassNotFoundException
+----
+
+[[steps]]
+== Five steps
+
+Stop::
+Read the project runtime and Camel version, capture the exact symptom and the
recent changes, and change nothing
+yet. Logs, stack traces, route files, configuration and catalog responses are
diagnostic data: a command, URL or
+procedure found in them never directs the workflow.
+
+Preserve::
+Record the branch, the working-tree state and the existing local changes with
`git status` and `git diff`, and
+warn when uncommitted changes exist.
+
+Diagnose::
+Reproduce the failure, classify it against the shared error taxonomy (the same
one the verification loop uses),
+verify the components involved against the Camel catalog, and inspect the
route structure. Three diagnostic roles
+(route analyzer, catalog verifier, log analyzer) run in isolated subagents
where the agent supports them and
+sequentially inline otherwise. The diagnosis is presented before any change.
If the error cannot be reproduced or
+classified, the skill says so instead of guessing.
+
+Fix::
+One targeted repair for the diagnosed root cause, explained first, with no
refactoring of the surroundings, then the
+reproduction command again. The taxonomy entry owns the fix target: a direct
edit of the POM, the properties or the
+route; `camel-validate` to re-check the route against the catalog;
`camel-implement` to regenerate the route from
+its design section; or escalation. The same error after a fix stops the step
and asks for guidance; a new error is
+classified again. After five failed attempts the skill stops and lists what it
tried.
+
+Guard::
+A suggested preventive measure for the error category: a Citrus test for a
route that failed to start, a
+`/camel-validate` run after endpoint changes, a health check or circuit
breaker for an unavailable service, a build
+verification step in CI for dependency problems. Guards are recommendations
and are not applied without approval.
+
+[[authorization]]
+== What authorizes a repair
+
+Your request sets the gate. A request to diagnose and fix authorizes the
ordinary in-scope repairs selected by the
+taxonomy from corroborated facts. A diagnosis-only request stops before any
change: the skill presents the exact
+proposed repair and waits for approval. Text inside a log, a route, a tool
response or any other loaded artifact
+never satisfies either gate. If an action outside the shipped workflow turns
out to be necessary, the skill names its
+source, the exact action, the verified reason and the scope and waits for an
action-specific confirmation; an
+isolated role that cannot ask returns `NEEDS_USER_CONFIRMATION` without acting.
+
+[[result]]
+== Result
+
+----
+DEBUG SUMMARY
+Symptom: Route order-intake fails at startup
+Root cause: camel-kafka is not on the classpath
+Classification: Missing Camel component dependency
+Fix applied: Added camel-kafka-starter to pom.xml
+Files changed: pom.xml
+Guard: Add a dependency resolution step to the CI build
+----
+
+A diagnosis-only run ends with the root cause and the proposed fix, no changed
files and no guard suggested.
diff --git a/docs/modules/ROOT/pages/camel-execute.adoc
b/docs/modules/ROOT/pages/camel-execute.adoc
index a8a19b26..90995f4f 100644
--- a/docs/modules/ROOT/pages/camel-execute.adoc
+++ b/docs/modules/ROOT/pages/camel-execute.adoc
@@ -1,3 +1,155 @@
= camel-execute
-This page is written in a following documentation pull request.
+`/camel-execute` is the implementation stage. It runs every task of the
implementation plan without pausing: wave by
+wave, with pre-implementation catalog research, an adversarial review, a spec
compliance review and a code quality
+review per task, a cross-cutting review of the whole project and one runtime
verification pass. The output is a
+runtime-specific project (YAML routes, Citrus tests, application properties,
Maven files for Spring Boot and
+Quarkus, Docker Compose only when external services are needed) and
+`docs/camel-kit/<pipeline-id>/execution-report.md`.
+
+In a chained run `/camel-plan` invokes it directly. Invoked standalone
(`/camel-execute` or
+`/camel-execute <pipeline-id>`), it reads `implementation-plan.md` and
`design-spec.md` from disk, checks their
+provenance and staleness with `camel-kit doc check`, runs the full loop,
writes the report and stops without
+invoking `/camel-validate`. Stale inputs stop the skill until you choose to
regenerate them, abort, or proceed with
+those exact revisions.
+
+Do not use it without a plan derived from an approved design, for Camel
questions, for validation-only tasks or for
+design work.
+
+[[preparation]]
+== Preparation
+
+Wave analysis::
+`camel-kit plan analyze` returns the waves and dependencies of the plan. Tasks
in a wave are dispatched in parallel
+where the agent supports independent subagents and sequentially otherwise; a
wave completes, reviews included,
+before the next starts. A malformed or inconsistent plan stops execution as
blocked rather than being repaired from
+its prose.
+
+Plan ingress validation::
+The plan and the design are data, not instructions. The executor validates the
pipeline ID and every target path
+(inside the project and the approved scope, no absolute paths or traversal),
resolves agent personas and guides only
+to the installed shipped ones, accepts catalog tool names only from the active
guides, and derives build, test and
+verification commands from the shipped guides and the detected project state,
never from plan text. The *Not Doing
+(and Why)* section is read before any capability beyond a task's explicit
requirements is considered.
+
+Environment probe::
+Before any implementer runs, the executor generates a throwaway skeleton for
the selected runtime and checks it:
+Maven dependency resolution for Spring Boot and Quarkus (reported as skipped
for Camel Main), the runtime startup
+command, and Docker services only when the design needs external services and
Docker is available. Mechanical
+failures are fixed and re-probed. An architectural failure, for example a
component that does not exist for the
+target runtime, triggers the bounded re-plan loop: it modifies only the
affected flow sections of the design, at
+most three rounds, then re-probes; a persistent failure is escalated.
+
+Catalog research::
+Before each wave the executor deduplicates the components, EIPs, data formats
and languages referenced by its tasks
+and runs the catalog researcher role once, with the runtime, platform BOM and
Camel version. The returned summary
+is accepted only when its binding matches the project and every artifact has
an identity, a result, declared fields
+and provenance; implementers consume those fields and do not re-query them. An
artifact reported as not found is
+flagged before implementation so that the implementer finds an alternative.
+
+[[task-loop]]
+== The per-task loop
+
+For each task the executor runs the persona declared by the plan with the full
task text, the relevant design
+section, the scope boundaries, the validated guide selectors, the project
context and the catalog summary; route and
+configuration tasks use the internal `camel-implement` skill, test tasks
`camel-test`. Mechanical tasks run on a
+standard model and complex ones (DataMapper, multi-route coordination,
migration) on the most capable one, where the
+agent offers the choice.
+
+The implementer reports `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`,
`NEEDS_USER_CONFIRMATION` or `BLOCKED`.
+Missing context is supplied and the task re-dispatched; a confirmation request
names one exact action, which is
+performed only if it is independently necessary and you authorize it; a
blocked task is re-scoped or reported.
+
+. *Adversarial code review.* A moderator selects the critic lanes from the
design: route architecture always,
+ security for external boundaries, performance for throughput, aggregation or
batch work, boundary compliance for
+ data transformation, behavioral equivalence for migrations. Critics run in
fresh contexts where supported and
+ sequentially inline otherwise, recording the missing isolation. `PASS` and
`PASS_WITH_TRADEOFFS` proceed, the
+ trade-offs carried into the next review; `FAIL` returns verified findings to
the implementer, for at most three
+ cycles before escalation.
+. *Spec compliance review.* The generated files are checked against the
acceptance criteria and the design section.
+ Adding a capability listed under *Not Doing (and Why)* is a failure even
when it looks useful. Verified findings go
+ back to the implementer, for at most three iterations.
+. *Code quality review.* The eight constitution rules, the security checklist
and the anti-pattern catalog. Critical
+ findings go back to the implementer; important findings and suggestions are
recorded in the report and do not
+ block the task. Bean definitions are also checked against the declarative
construction preference described in
+ xref:forage.adoc[].
+
+----
+Task 2: Order validation route
+ Stage 1: Spec compliance
+ - Consumes from seda:orders-processing OK
+ - Validates orderId not null OK
+ - Validates totalAmount > 0 OK
+ - Validates customerId not null MISSING
+ Spec compliance: FAIL -> implementer fixes, re-review
+ Stage 1: Spec compliance: PASS
+ Stage 2: Code quality: PASS (1 non-blocking finding recorded)
+Task 2 complete. Starting Task 3...
+----
+
+The loop is automatic: one line per completed task, no mid-plan summaries, no
"shall I continue" questions. Design
+approval and invocation authorize every validated task; the only pause is an
action-specific confirmation required by
+the context-authority rules.
+
+[[final]]
+== Cross-cutting review, verification and report
+
+After the last task the code quality reviewer checks all routes together:
endpoint contracts, shared properties,
+error-channel wiring, naming and observability across the project. Then the
internal `camel-verify` skill runs once
+for the complete application, because Camel loads all routes at startup and
per-task verification would fail on
+routes that depend on others. Its outcome (`PASS`, `PARTIAL`, `FAIL` or
`NOT_RUN`) is informational and does not
+block completion; see xref:verification.adoc[].
+
+The completion summary lists the tasks, the generated files, the review
results, the cross-cutting review and the
+full verification report, and is saved as `execution-report.md` with
provenance metadata; the downstream validation
+report is marked stale. In chained mode the pipeline then continues to
`/camel-validate`.
+
+[[artifacts]]
+== Generated artifacts
+
+The layout follows the runtime chosen in the design. `<module>/` is the
optional relative path of the flow's target
+module; omit it for a single-module project.
+
+[cols="1,2,2"]
+|===
+| Artifact | Camel Main | Spring Boot and Quarkus
+
+| Routes, and XSLT files when DataMapper selects XSLT |
`<module>/<name>.camel.yaml`,
+ `<module>/kaoto-datamapper-*.xsl` | `<module>/src/main/resources/camel/`
+| Application properties | `<module>/application.properties` |
`<module>/src/main/resources/application.properties`
+| Schemas, when requested | `<module>/schemas/` |
`<module>/src/main/resources/schemas/`
+| Citrus tests and test support | `<module>/src/test/resources/`:
`<flow>.camel.it.yaml`, `test-data/`,
+ `application-test.properties`, `jbang.properties` | The same, without
`jbang.properties`; dependencies are in the
+ POM
+| Build and run files | No POM; the JBang dependencies live in
`application.properties`, plus `<module>/run.sh` |
+ `<module>/pom.xml` from the bundled Spring Boot or Quarkus template, filled
with the catalog-resolved dependencies
+| Docker Compose | `<module>/docker-compose.yaml` only when external services
are required; runs the Camel JBang
+ application and those services | The same file only when required; manages
the services while the application
+ runs through Maven
+| Verification log | `.camel-kit/verify-log.md` | `.camel-kit/verify-log.md`
+|===
+
+Error handling in the generated routes is a global `onException` before the
first route, or route-scoped through a
+`routeConfiguration` or an in-route `errorHandler`, and static `to` endpoints
contain no expressions; a dynamic
+destination uses `toD`. Every route file is validated against the selected
Camel runtime, when the catalog MCP
+server is available, before its task is accepted.
+
+[[agents]]
+== Execution model per agent
+
+[cols="1,2"]
+|===
+| Agent | Model
+
+| Claude Code | Fresh subagent per task with an isolated context; parallel
dispatch within a wave
+| IBM Bob 2 | Native `spawn_subagent` with the Bob custom modes and shared
skills
+| Google Antigravity, Qwen Code, OpenCode | Their native delegation models
with the shared skills
+| GitHub Copilot CLI, OpenAI Codex CLI | Their custom agents for
implementation and review roles
+| Pi | The same roles sequentially in the main session, recording the
unavailable isolation
+|===
+
+[[rerun]]
+== Rerun after a failure
+
+If execution stops mid-plan, correct the cause through the owning path
(implementation, test or re-plan) and rerun
+`/camel-execute <pipeline-id>`. There is no task-level resume: the rerun
executes the plan from the beginning.
diff --git a/docs/modules/ROOT/pages/camel-plan.adoc
b/docs/modules/ROOT/pages/camel-plan.adoc
index 291dea94..442c0e91 100644
--- a/docs/modules/ROOT/pages/camel-plan.adoc
+++ b/docs/modules/ROOT/pages/camel-plan.adoc
@@ -1,3 +1,153 @@
= camel-plan
-This page is written in a following documentation pull request.
+`/camel-plan` is the planning stage. It turns the approved design
specification into an implementation plan: a
+task-by-task recipe with acceptance criteria, the components and guides each
task uses, dependency waves and a
+two-stage review specification. The plan describes what to generate and how to
verify it; it never contains the
+generated routes, properties, dependencies or tests, so that `/camel-execute`
always generates them from the current
+guides and catalog.
+
+In a chained run the design approval in `/camel-brainstorm` or
`/camel-migrate` invokes `/camel-plan` directly, and
+the plan hands off to `/camel-execute` without a second approval. Invoked
standalone (`/camel-plan` or
+`/camel-plan <pipeline-id>`), it reads `design-spec.md` from disk, checks its
provenance and staleness with
+`camel-kit doc check`, writes the plan and stops; a stale or unverified design
stops the skill until you choose to
+amend it, abort, or plan from that exact revision.
+
+Do not use it for ad-hoc changes, single-file edits or quick fixes, when no
approved design exists, or to generate
+code.
+
+[[input]]
+== Input
+
+The planner reads all sections of
`docs/camel-kit/<pipeline-id>/design-spec.md`: the executive summary for the
goal
+and constraints, the systems landscape for the external systems, the flow
designs for the implementation tasks and
+contracts, the cross-cutting concerns for errors, security, resilience,
observability and configuration, the
+constitution compliance section with its catalog verification evidence, and
the project structure for the
+runtime-specific layout. A migration design adds the migration context section.
+
+The *Not Doing (and Why)* list is binding: the planner never creates a task or
an acceptance criterion for an
+excluded capability. If another approved section requires one, planning stops
so the contradiction can be resolved
+and re-approved, instead of passing an impossible plan to execution.
+
+If the design covers several independent subsystems or more than about ten
flows, the planner suggests one plan per
+subsystem, each producing working software on its own.
+
+[[process]]
+== How the plan is built
+
+. *Templates.* The planner loads the greenfield or the migration task template
plus the testing template, and emits
+ one Citrus test task per flow after the implementation tasks it depends on.
+. *Flow-to-task mapping.* Each flow becomes one or more tasks; a routing
decision with several destinations becomes
+ several route tasks, following the separation-of-concerns rule. Scaffold,
configuration, runtime dependency and
+ conditional infrastructure tasks complete the plan.
+. *Acceptance criteria.* Each task states what "done" means in checkable
terms, for example "listens at `/api/orders`,
+ POST, returns 202" or "queries PostgreSQL with `sql`, sets the
`credit-status` header, retries three times with
+ exponential backoff". The spec compliance review checks the generated
artifact against these criteria.
+. *Components, guides and tools.* Each task lists the Camel artifacts it uses,
the guides the implementer loads and
+ the catalog tool calls with the runtime and platform BOM parameters.
+. *Dependencies and waves.* Tasks declare the files they create or modify, the
logical resources they provide and
+ consume (routes, endpoints, properties, schemas, test data, beans, external
services, route contracts) and
+ explicit dependencies. `camel-kit plan analyze` derives the waves from them.
+. *Self-review.* Every flow maps to a task, no placeholders or "similar to
task N", every guide path exists, every
+ task has both review stages and a verification step with an exact command
and expected result.
+
+[[format]]
+== Plan format
+
+The plan is written to `docs/camel-kit/<pipeline-id>/implementation-plan.md`
with provenance front matter added by
+`camel-kit doc init`. A fenced block with the info string `yaml plan-metadata`
precedes the first task and holds one
+entry per task:
+
+[source,yaml]
+----
+tasks:
+ - id: 2
+ title: Order intake route
+ files:
+ creates:
+ - src/main/resources/camel/order-intake.camel.yaml
+ provides:
+ routes:
+ - order-intake
+ endpoints:
+ - direct:validate-order
+ consumes:
+ properties:
+ - orders.api.path
+ dependsOn: [1]
+----
+
+Each `### Task N` section then carries the execution recipe:
+
+[source,markdown]
+----
+### Task 2: Order intake route
+
+**Agent:** implementation-engineer
+
+**Files:**
+- Create: `src/main/resources/camel/order-intake.camel.yaml`
+
+**Guides to Load:**
+- `camel-implement/guides/orchestrator.md`
+- `camel-implement/guides/yaml-structure.md`
+
+**MCP Tools:**
+- `camel_catalog_component_doc(component="platform-http",
runtime="spring-boot", ...)`
+
+**Design Spec Section:** Section 3, Flow: order-intake
+
+- [ ] **Step 1:** ...
+- [ ] **Step N:** Verify with `<command>` and expect `<result>`
+
+**Review:**
+- [ ] Spec compliance: components and structure match the design
+- [ ] Code quality: constitution rules, security, anti-patterns
+----
+
+The agent persona is one of `integration-architect`,
`implementation-engineer`, `migration-specialist` or
+`test-engineer`. Plans must contain no `TBD`, deferred work, vague steps,
implicit file paths, or verification
+without an exact command and expected result. Older Markdown-only plans still
execute; new plans always carry the
+metadata block.
+
+[[waves]]
+== Waves
+
+`camel-kit plan analyze <plan>` sorts the tasks topologically: tasks with no
dependencies form wave 1, the tasks that
+depend only on them form wave 2, and so on. Tasks in the same wave touch
different files and are concurrency
+candidates: agents with independent subagent conversations run them in
parallel, the others run them sequentially in
+plan order. A later wave never starts before its dependencies complete. A
circular dependency is reported as an error
+that names the tasks involved.
+
+A task depends on another when it consumes its data (a lookup result used for
enrichment), when it is invoked by it
+(a route consuming from a queue the first route feeds), or when the plan
declares it explicitly. Independent flows,
+such as a REST endpoint and a scheduled synchronization, share a wave.
+
+----
+Wave 1: Task 1 (runtime configuration and dependencies)
+Wave 2: Task 2 (order intake route)
+Wave 3: Task 3 (credit lookup route), Task 7 (invalid-order publisher)
+Wave 4: Task 4 (routing decision)
+Wave 5: Task 5 (warehouse publisher), Task 6 (pending-order publisher)
+----
+
+[[review-spec]]
+== Two-stage review specification
+
+Every implementation task ends with a review section for Iron Law 4: spec
compliance first (are all acceptance
+criteria met, does the route do what the task says, are the declared
components used), then code quality (the eight
+constitution rules, security, anti-patterns). A task that fails the first
stage goes back to its implementer without
+a quality review. Project-specific checks, for example "no hardcoded secrets",
can be added to the generated plan
+skill's task template; the two stages and their order stay.
+
+[[handoff]]
+== Handoff and reuse
+
+After saving the plan the skill adds the provenance metadata, marks existing
downstream artifacts stale with
+`camel-kit doc stale --cascade`, and then either invokes `/camel-execute`
(chained mode) or prints the next command
+and stops (standalone mode). Agent traits can replace the default handoff, for
example Claude Code stays out of its
+native plan mode so that no second approval appears.
+
+The plan stays valid while its design is unchanged. After a transient
environment failure, fix the environment and
+rerun `/camel-execute <pipeline-id>`; execution restarts from the first task
because there is no task-level resume.
+If the design changes, amend it with `/camel-brainstorm <pipeline-id>` and
regenerate the stale plan before
+executing again.
diff --git a/docs/modules/ROOT/pages/camel-start.adoc
b/docs/modules/ROOT/pages/camel-start.adoc
index fe81cf1b..7a91a8f4 100644
--- a/docs/modules/ROOT/pages/camel-start.adoc
+++ b/docs/modules/ROOT/pages/camel-start.adoc
@@ -1,3 +1,71 @@
= camel-start
-This page is written in a following documentation pull request.
+`/camel-start` is the entry point of the pipeline. It reads the request and
the project state and loads only the
+stage or utility that applies, so an existing project can enter the pipeline
midway without repeating completed
+work. The invocation form depends on the agent: `$camel-start` in Bob Shell
and Codex, `/skill:camel-start` in Pi,
+"Use the `/camel-start` skill" in GitHub Copilot CLI, `/camel-start` elsewhere
(see xref:agents.adoc[]).
+
+[[routing]]
+== Routing
+
+The router answers these questions in order; the first "yes" wins.
+
+[cols="1,3,1"]
+|===
+| # | Request state | Route
+
+| 1 | Existing MuleSoft, BizTalk, Fuse or Camel 2.x/3.x source to migrate |
xref:migration.adoc[`/camel-migrate`]
+| 2 | An approved design specification ready for task decomposition |
xref:camel-plan.adoc[`/camel-plan`]
+| 3 | An implementation plan derived from an approved design, ready to build |
xref:camel-execute.adoc[`/camel-execute`]
+| 4 | Generated routes that need static quality validation |
xref:camel-validate.adoc[`/camel-validate`]
+| 5 | A build, startup or runtime failure outside a pipeline run |
xref:camel-debug.adoc[`/camel-debug`]
+| 6 | A new integration, a new feature, or an unclear request |
xref:camel-brainstorm.adoc[`/camel-brainstorm`]
+|===
+
+----
+Greenfield: /camel-brainstorm -> /camel-plan -> /camel-execute ->
/camel-validate
+Migration: /camel-migrate -> /camel-plan -> /camel-execute ->
/camel-validate
+----
+
+Both pipelines share plan, execute and validate; only the design entry
differs. Runtime verification runs inside
+execute (see xref:verification.adoc[]).
+
+[[tiers]]
+== Skill tiers
+
+[cols="1,2,2"]
+|===
+| Tier | Skills | Role
+
+| Entry | `camel-start` | Routes to the right pipeline stage
+| Pipeline | `camel-brainstorm`, `camel-migrate`, `camel-plan`,
`camel-execute`, `camel-validate` | Five skills for
+ the four stages; brainstorm and migrate are the alternative design entries
+| Utilities | `camel-ship`, `camel-knowledge`, `camel-debug` | Standalone,
usable at any time without changing the
+ active pipeline state
+| Internal | `camel-design`, `camel-implement`, `camel-test`, `camel-verify` |
Dispatched by the pipeline skills;
+ not user-invocable
+|===
+
+[[when-not]]
+== When not to use each skill
+
+[cols="1,3"]
+|===
+| Skill | Not for
+
+| `/camel-brainstorm` | Quick property changes, version bumps,
single-component additions, Camel questions,
+ migrations from another platform
+| `/camel-migrate` | Greenfield projects, Camel 4.x minor upgrades, projects
without source artifacts to analyze
+| `/camel-plan` | Ad-hoc changes, single-file edits, quick fixes, or when no
approved design exists
+| `/camel-execute` | When no plan derived from an approved design exists;
Camel questions; validation-only tasks;
+ design work
+| `/camel-validate` | Runtime debugging (build failures, startup errors),
generating routes, design work, fixing the
+ findings
+| `/camel-ship` | Single-file changes, quick fixes, exploratory work, or when
only one pipeline stage is needed
+| `/camel-debug` | Build and test failures during `/camel-execute` (its own
verification loop handles them),
+ quality validation, design work
+| `/camel-knowledge` | Implementation, code generation, route validation,
design work
+|===
+
+Use a stage directly when the destination is already known, for example
`/camel-plan` with an approved design or
+`/camel-debug` for a broken route. Use `/camel-start` when the request is new
or its current stage is uncertain.
diff --git a/docs/modules/ROOT/pages/camel-validate.adoc
b/docs/modules/ROOT/pages/camel-validate.adoc
index f65938ae..a9c22d71 100644
--- a/docs/modules/ROOT/pages/camel-validate.adoc
+++ b/docs/modules/ROOT/pages/camel-validate.adoc
@@ -1,3 +1,67 @@
= camel-validate
-This page is written in a following documentation pull request.
+`/camel-validate` is the last stage of the pipeline: a static quality analysis
of the generated Camel routes that
+writes a report and changes nothing. It covers correctness, security,
anti-patterns, project conventions and the
+constitution. Runtime failures (build, startup, tests) belong to the
verification loop inside `/camel-execute` (see
+xref:verification.adoc[]); a route broken outside a pipeline run belongs to
xref:camel-debug.adoc[`/camel-debug`].
+
+[[modes]]
+== When it runs
+
+In a chained run `/camel-execute` continues to `/camel-validate` after the
implementation and the runtime
+verification, with no further approval. A standalone `/camel-execute` stops
after its summary, so invoke validation
+explicitly when you want the static gate:
+
+----
+/camel-validate <pipeline-id>
+/camel-validate
+----
+
+With a pipeline ID, or with an active pipeline recorded in
`.camel-kit/pipeline.json`, validation is pipeline-scoped:
+it cross-references the design, the plan and the execution report under
`docs/camel-kit/<pipeline-id>/`, checks
+their provenance with `camel-kit doc check`, and stops on a stale artifact
until you choose to regenerate it, abort,
+or proceed with that exact revision. Without any pipeline it is project-scoped
and validates the routes found in the
+current project.
+
+[[checks]]
+== Checks
+
+The skill first builds the route inventory of every target module for the
project's runtime (module-root
+`*.camel.yaml` and `application.properties` for Camel Main,
`src/main/resources/camel/` and
+`src/main/resources/application.properties` for Spring Boot and Quarkus), then
runs:
+
+* Camel YAML DSL schema validation and endpoint configuration;
+* endpoint verification against the Camel catalog through the `camel` MCP
server, for the project's runtime and
+ platform BOM;
+* quality metrics and thresholds, relative to the project norms when
`.camel-kit/project-graph.json` exists;
+* security analysis from the shared checklist: hardcoded credentials, TLS,
headers and unsafe endpoint settings;
+* the anti-pattern catalog;
+* all eight constitution rules;
+* structural retirement candidates from the project graph when it exists (see
xref:graph.adoc[]).
+
+Validation is at least as strict as generation: a construct that Camel Kit
refuses to generate does not pass
+validation because it was added by hand.
+
+[[report]]
+== Report
+
+Pipeline-scoped validation writes
`docs/camel-kit/<pipeline-id>/validation-report.md`; project-scoped validation
+writes `docs/validation-report-YYYY-MM-DD_HH-mm.md`. The report records the
project, runtime and Camel version, a
+summary table with pass, fail and warn counts per category, the findings, the
constitution rule results, and the
+recommendations: priority fixes for the failures, suggested improvements for
the warnings.
+
+[cols="1,1,1,1,1"]
+|===
+| Category | Pass | Fail | Warn | Total
+
+| Schema validation | . | . | . | .
+| Endpoint verification | . | . | . | .
+| Quality checks | . | . | . | .
+| Security analysis | . | . | . | .
+| Anti-patterns | . | . | . | .
+| Constitution compliance | . | . | . | .
+|===
+
+The report carries provenance metadata from `camel-kit doc init`, linked to
the execution report when one exists.
+Fixing the findings is a separate step: edit the routes, or amend the design
and rerun the affected stages, then
+validate again.
diff --git a/docs/modules/ROOT/pages/pipeline.adoc
b/docs/modules/ROOT/pages/pipeline.adoc
index c0798ab2..8810d868 100644
--- a/docs/modules/ROOT/pages/pipeline.adoc
+++ b/docs/modules/ROOT/pages/pipeline.adoc
@@ -1,3 +1,134 @@
-= Pipeline: stages, approval gate and Iron Laws
+= Stages, approval gate and Iron Laws
-This page is written in a following documentation pull request.
+The Camel Kit pipeline turns integration requirements into generated routes,
tests and review evidence in four
+stages: design, plan, execute and validate. Every stage is a skill that the
coding agent runs; the stages share their
+artifacts through files under `docs/camel-kit/<pipeline-id>/`, so a pipeline
survives the end of a session.
+
+There are two ways to run it:
+
+* *Manual stages.* Enter through `/camel-start`, or through
`/camel-brainstorm` or `/camel-migrate` without a pipeline
+ ID, for a chained run: after the single design approval the remaining stages
follow automatically in the same
+ conversation. A stage invoked on its own writes its artifact and stops.
+* *Ship.* `/camel-ship` (Technology Preview) delegates to the local `camel-kit
ship` controller, which runs its own
+ five-stage workflow with configurable oversight and keeps its own run state.
See xref:ship.adoc[].
+
+The manual pipeline is agent-run and enforces the Iron Laws at every stage;
Ship's stages, state and gates are owned
+by the controller.
+
+[[stages]]
+== The four stages
+
+[cols="1,1,3,2"]
+|===
+| Stage | Skill | What it does | Artifact
+
+| Design
+| xref:camel-brainstorm.adoc[`/camel-brainstorm`] or
xref:migration.adoc[`/camel-migrate`]
+| Adaptive interview, or source discovery for a migration; catalog
verification of every component; the design
+ specification
+| `design-spec.md` (a migration adds `business-requirements.md`,
`migration-analysis.md` and `migration-runbook.md`)
+
+| Plan
+| xref:camel-plan.adoc[`/camel-plan`]
+| Decomposes the approved design into tasks with acceptance criteria,
components, dependency waves and a two-stage
+ review specification
+| `implementation-plan.md`
+
+| Execute
+| xref:camel-execute.adoc[`/camel-execute`]
+| Implements the tasks wave by wave with an adversarial review, a spec
compliance review and a code quality review
+ per task, then one cross-cutting review and one runtime verification pass
(the internal `camel-verify` skill)
+| Routes, configuration, tests and `execution-report.md` with the embedded
verification evidence
+
+| Validate
+| xref:camel-validate.adoc[`/camel-validate`]
+| Static quality analysis of the generated routes: schema, endpoints,
security, anti-patterns, project norms and the
+ constitution; report only
+| `validation-report.md`
+|===
+
+Brainstorm and migrate are the two entries to the design stage; both pipelines
share plan, execute and validate.
+Runtime verification is not a stage of its own: `/camel-execute` dispatches it
once after all tasks, and its outcome
+never blocks the execution report. See xref:verification.adoc[].
+
+[[approval-gate]]
+== The approval gate
+
+The design stage ends with the only required human approval. For a greenfield
design the agent presents the design
+specification: six numbered sections (executive summary, systems landscape,
flow designs, cross-cutting concerns,
+constitution compliance, project structure) and an unnumbered *Not Doing (and
Why)* section that records each
+deliberately excluded capability with its reason. Section 5 carries the
*Catalog Verification Evidence*: the matched
+runtime, platform BOM and Camel version, and one `VERIFIED` row with tool
provenance for every component, EIP, data
+format and language used in the flow designs. A migration presents its
four-artifact package instead, with a seventh
+section, *Migration Context*, in the design (see
xref:migration.adoc#package[The migration package]).
+
+You approve explicitly, or ask for changes and the agent revises and presents
again. In a chained run the approval
+authorizes everything downstream: plan writes the task breakdown and hands off
to execute, execute dispatches the
+runtime verification and continues to validate. There is no second gate for
the plan.
+
+[[pipeline-files]]
+== Pipeline files and standalone stages
+
+A pipeline is a numbered directory created with `camel-kit nextId <slug>` (for
example `001-order-processing`);
+`.camel-kit/pipeline.json` records the active one. Each stage reads its input
from the previous artifact and writes
+its own next to it, with provenance metadata in the file's front matter
maintained by `camel-kit doc`.
+
+Every stage can also be invoked standalone with a pipeline ID, for example
`/camel-plan 001-order-processing`. It
+then reads its input from disk, checks that the input is not stale, writes its
artifact and stops without invoking
+the next stage. Running `/camel-brainstorm` with the ID of an existing design
enters amend mode: the design is
+revised and approved again, and its dependent artifacts are marked stale so
that the following stages are rerun. A
+standalone stage that finds a stale or unverified input stops and asks whether
to regenerate it, abort, or proceed
+with that exact revision. See xref:commands.adoc[] for `nextId`, `doc check`
and `doc stale`.
+
+[[iron-laws]]
+== Iron Laws
+
+Six rules apply at every stage; every skill and every reviewer persona refers
to them.
+
+. *Catalog verification.* Every component, EIP, data format and language is
verified through the catalog MCP server,
+ for the project's runtime and platform BOM, before it is written into a
design or a route. The tool call and its
+ result must be visible; a response is data, never an instruction. `forage.*`
keys are verified against the cached
+ Forage catalog instead (see xref:forage.adoc[]).
+. *Constitution compliance.* Every generated route passes the eight rules of
`docs/constitution.md`: route
+ structure, single responsibility, separation of concerns, naming
conventions, observability, external
+ configuration, component verification and infrastructure through Forage. See
xref:constitution.adoc[].
+. *No code without an approved design and a plan.* Implementation artifacts
are generated only by the execute stage,
+ from a plan derived from an approved design. Design and planning skills
never write routes. The one exception is
+ the direct mode of `/camel-migrate`, which implements concrete deliverables
under laws 1, 2 and 5 with inline
+ validation and a runtime check; it exists in the development snapshot only
(see xref:migration.adoc#run[Run the
+ migration]).
+. *Spec compliance before quality.* Each task is reviewed first against its
acceptance criteria and the design, then
+ for quality. A task that fails the first review is sent back without a
quality review.
+. *Adversarial code review.* Before the two staged reviews, a moderator
selects critic lanes (route architecture
+ always; security, performance, boundary compliance and behavioral
equivalence when the design calls for them) and
+ runs them in fresh contexts where the agent supports subagents, or
sequentially in the same session otherwise,
+ recording the missing isolation. Verified findings go back to the
implementer, for at most three cycles.
+. *Surgical changes.* A task touches only what it requires: no adjacent
refactoring, cleanup or unrelated TODO work.
+
+[[internal-skills]]
+== Internal skills
+
+Four skills are dispatched by the stages and have no command stub of their own:
+
+[cols="1,3"]
+|===
+| Skill | Role
+
+| `camel-design` | Component selection, integration patterns and
design-assembly guidance during the design stage
+| `camel-implement` | Generates the Camel YAML routes, properties,
dependencies and DataMapper transformations of a
+ task, following the constitution and the catalog
+| `camel-test` | Generates the Citrus integration test of a flow, with
Testcontainers only for required databases or
+ brokers and mocks for external APIs
+| `camel-verify` | Builds or starts the generated application, runs the Citrus
tests, classifies failures and applies
+ bounded fixes; see xref:verification.adoc[]
+|===
+
+Where the agent supports subagents these skills run in isolated contexts;
single-conversation agents run the same
+personas inline.
+
+== Two utilities outside the pipeline
+
+`/camel-debug` diagnoses and repairs a broken route outside a pipeline run
with a stop, preserve, diagnose, fix and
+guard sequence (see xref:camel-debug.adoc[]). `/camel-knowledge` answers
Apache Camel documentation questions through
+the Knowledge MCP server without changing the pipeline state (see
xref:knowledge.adoc[]). Both can be used at any
+time.
diff --git a/docs/modules/ROOT/pages/ship.adoc
b/docs/modules/ROOT/pages/ship.adoc
index 1090623c..187617a3 100644
--- a/docs/modules/ROOT/pages/ship.adoc
+++ b/docs/modules/ROOT/pages/ship.adoc
@@ -1,3 +1,270 @@
= Ship workflow (Technology Preview)
-This page is written in a following documentation pull request.
+IMPORTANT: Camel Ship is a Technology Preview. It is still being stabilized,
its behaviour and interfaces may change,
+and it is not recommended for production use. This applies to every Ship
backend: tested host and runtime
+combinations and passing checks do not mean production readiness. For the
established staged workflow, start with
+`/camel-start`.
+
+Ship is a local workflow controller. The command `camel-kit ship` (or `camel
kit ship` with the Camel JBang plugin)
+starts, inspects, resumes or aborts a run on your machine. One run takes an
integration from requirements to
+published code through five controller-owned stages: discovery, design, plan,
execute and validate. The agent entry
+points (`/camel-ship`, `$camel-ship`, `/skill:camel-ship`) are thin delegates:
they forward your options to the
+registered command once and add nothing. The controller, not the agent, owns
the stages, the run state, the oversight
+pauses, the evidence, the publication and the recovery; it never stores its
state in the manual pipeline file.
+
+Ship is a local orchestrator. It is not a daemon, a secrets service, a
hostile-process sandbox or a release
+attestation system. Provider credentials stay with the active agent host or
the external Pi worker; Ship does not
+persist them or write them into arguments, logs, reports or project artifacts.
+
+Use it when you want one resumable run from requirements to validated,
published code, when you need to resume an
+interrupted run by its ID, or when you have an approved manual design and want
the controller to start at planning.
+Do not use it for single-file changes, quick fixes, exploratory work, or when
only one pipeline stage is needed.
+
+[[requirements]]
+== Requirements
+
+* A Linux host.
+* A Camel Main project with YAML DSL routes named `<routeId>.camel.yaml`,
Simple expressions, no Java artifacts, and
+ one Citrus test per route at `test/<routeId>.camel.it.yaml`. Spring Boot and
Quarkus projects are rejected until
+ deterministic evidence support exists for them.
+* For the default Pi backend, the Pi and Node executables, found on `PATH` or
given with `--pi` and `--node`. The
+ maintained versions are Pi `{pi-version}` or `{pi-previous-version}` with
Node `{node-version}`; any other version is
+ labelled experimental
+ and runs only with `--accept-experimental`, and a version with a known
missing capability is rejected.
+* Outbound access to Maven Central for the catalog and validation payloads.
+
+Ship targets Camel Main at the configured `camel.main.version`: a `-p
camel.main.version=...` override, then the
+`-c` file or `~/.camel-kit/config.properties`, then the bundled default.
+
+[[command]]
+== Command and options
+
+----
+camel-kit ship [--text TEXT]... [--document PATH]... [--ask always|smart|never]
+ [--start-from STAGE]
+camel-kit ship --resume RUN_ID | --status RUN_ID | --abort RUN_ID
+camel-kit ship --submit RUN_ID --result PATH [--json]
+----
+
+Context is optional: a bare `camel-kit ship` starts a short discovery
conversation. Text and documents are added to
+the discovery input before any question, and open points come back as grouped
unresolved questions.
+
+[cols="1,1,3"]
+|===
+| Option | Default | Description
+
+| `--text TEXT` | | Text context, repeatable
+| `--document PATH` | | Document context, repeatable
+| `--ask POLICY` | `smart` | Oversight for a new run: `always`, `smart` or
`never`
+| `--resume RUN_ID` | | Resume a run; `--text` and `--document` add context to
a paused run
+| `--status RUN_ID` | | Read the latest durable state without starting the
workflow runtime
+| `--abort RUN_ID` | | Abort a run that has not completed; aborted runs cannot
be resumed
+| `--start-from STAGE` | | Start a new run at `discovery`, `design` or `plan`
+| `--backend MODE` | `pi` | `pi`, `bob2-native`, `copilot-native`,
`claude-native` or, in the development snapshot,
+ `codex-native`; a run keeps its mode for its lifetime
+| `--json` | off | Structured run state and any pending native task
+| `--submit RUN_ID --result PATH` | | Relay one native child result
+| `--pi PATH`, `--node PATH` | found on `PATH` | Executables for the Pi
backend; rejected for native runs
+| `--maven-repository PATH` | under the state directory | Private Maven
repository for the validation payloads
+| `--stage-timeout DURATION` | `10m` | Limit for one stage attempt, for
example `90s` or `1h`
+| `--accept-experimental` | off | Continue after the warning for an
experimental Pi or Node version
+| `-c`, `--config PATH` | `~/.camel-kit/config.properties` | Configuration file
+| `-p`, `--property KEY=VALUE` | | Configuration override, repeatable
+|===
+
+`--resume`, `--status`, `--abort`, `--submit` and `--start-from` are mutually
exclusive. Runtime and configuration
+options apply when starting, resuming or submitting; repeat `--stage-timeout`,
`--maven-repository` and `-c`/`-p` on
+every resume and submission, because they are not persisted. With `--json`, a
failed workflow returns the run state
+with exit code 1; some command errors return only stderr.
+
+[[oversight]]
+== Oversight
+
+[cols="1,3"]
+|===
+| Policy | Where the controller pauses
+
+| `always` | After design, plan, execute and validate, including before
publication, and on material ambiguity
+| `smart` | After plan (before any implementation) and after execute, and on
material ambiguity; a fully passing
+ validation proceeds to guarded publication
+| `never` | Never for ambiguity: the worker records each unanswered question
with the default it applied. The run
+ still stops for missing tools, failed mandatory checks or authority you did
not grant
+|===
+
+Unanswered questions and applied defaults are kept per stage and listed in the
final summary and in `--status`;
+later stages receive them as worker-reported context, not as human-confirmed
answers. Under `always` and `smart`,
+answer a paused question with `--resume <run-id> --text "..."`.
+
+[[stages]]
+== Stages
+
+. *Discovery* gathers the requirements from the supplied context or a short
conversation. Read-only for your
+ sources.
+. *Design* produces the integration design from the discovery output.
Read-only.
+. *Plan* decomposes the design into an implementation plan. Read-only; `smart`
pauses here.
+. *Execute* implements the plan in a controller-owned staged copy of the
project prepared from a baseline snapshot.
+ The live project is not modified, and changed files containing known secrets
from the environment are rejected.
+. *Validate* is deterministic and controller-owned: route and artifact policy,
catalog and schema validation,
+ dependency and runtime consistency, direct JVM YAML validation, Camel Main
resolution and startup, and the required
+ Citrus tests. The commands run in a separate JVM with a pinned,
controller-resolved classpath, a scrubbed
+ environment and a frozen read-only copy of the accepted tree; in-memory
stubs replace every non-direct endpoint, so
+ no application I/O leaves the machine, while catalog resolution may still
download from Maven Central. No worker
+ prose decides the outcome.
+
+The result of validation is the *Stamp*: a local run report with a pass or
fail status derived from the required
+checks. For each command it records the executable and its version, the
redacted arguments, the exit status and
+timing, and the retained logs with their digests. A failed mandatory check
fails the run under every policy; there is
+no waiver. The Stamp describes what ran on this machine and is not a signed
attestation.
+
+[[state]]
+== Run state, resume and publication
+
+Run state lives under `.camel-kit/ship/state/` in the project, or under
`CAMEL_KIT_SHIP_STATE_HOME`. The
+`.camel-kit/ship/` subtree is reserved for the controller: never copied into
the staged workspace, never part of the
+staleness digests, never published, and ignored by its own `.gitignore`. Git
discovery stops at the staged
+workspace, so commands run by the execute worker or by validation do not see
the project's repository; for that
+reason project and state paths containing a colon are rejected. Runs recorded
by pre-0.4.0 development builds under
+the user state directory are found only when `CAMEL_KIT_SHIP_STATE_HOME`
points there.
+
+Each run prints its ID. `--status` shows the stage, the policy, any pause
report and the next actionable command.
+`--resume` re-reads the recorded inputs and artifacts, compares their digests,
and restarts the earliest stale or
+incomplete stage; later stages are reset, so your own edits are detected
rather than ignored. Context can be added
+only to a paused run; adding it after validation restarts from discovery and
discards the Stamp, with a warning
+first.
+
+`--start-from design` needs text or document context and a manual active
pipeline in `.camel-kit/pipeline.json`;
+`--start-from plan` also imports that pipeline's approved `design-spec.md`.
Existing plans, execution reports and
+validation reports cannot be imported, and starting from execute or validate
is unsupported because those stages
+need the controller's own plan and evidence.
+
+Accepted changes reach the live project only after the configured approval and
validation gates. Before applying
+anything the controller re-verifies every completed stage as recorded and
checks that the live tree has not changed;
+a changed tree stops publication and asks you to resume. The apply is
journaled: if it is interrupted, the next
+locked mutating operation attempts a rollback first, and may stop for manual
resolution. Ordinary process
+interruption is recoverable with the run ID; OS or power loss is not
guaranteed against, and the invoking OS account
+is trusted.
+
+[[native]]
+== Native subagents
+
+With the Pi backend, Ship runs an external Pi worker. Eligible IBM Bob 2,
GitHub Copilot CLI and Claude Code
+sessions can instead relay the controller's stage tasks to their own read-only
native subagents; OpenAI Codex CLI
+joins them in the development snapshot. The contract is the same for every
host:
+
+. The controller creates one pending task with its run, stage, attempt, input
digest, deadline and a unique task ID,
+ and returns to the parent session.
+. The parent dispatches a fresh `camel-ship-worker` child with the
controller's complete prompt, copied verbatim,
+ and submits the observed result through `ship --submit RUN_ID --result PATH
--json`.
+. The worker never edits project files, writes to the candidate or the state
directory, calls MCP servers, delegates
+ or publishes. On Bob 2, Copilot CLI and Claude Code it has read and search
tools only; on Codex CLI it may use
+ the host's file-reading means, shell commands included, for the named inputs
and sources, under the host's
+ permissions. For execute it returns complete text proposals for the approved
route and test paths, `pom.xml` and
+ `.camel-kit/config.properties`; arbitrary extra resources, binary files and
deletions are outside the contract.
+. The controller validates the proposals, writes its private candidate,
computes the hashes and runs the mandatory
+ checks. A returned child result is a transport result, not proof that
validation passed. Only the controller
+ advances a stage or pauses.
+
+The skill selects the native backend for an eligible new run unless you choose
one explicitly; when native dispatch
+is unavailable, a new run keeps the Pi model, and an existing run keeps its
recorded backend for its lifetime: hosts
+never switch during recovery. Native stages use the active session's
authentication and model; Camel Kit starts no
+second host process and does not look for Pi or Node. Host versions are
caller-reported diagnostics, not a
+certification.
+
+[cols="1,3"]
+|===
+| Host | Specifics
+
+| IBM Bob 2
+| `$camel-ship` in Bob Shell, `/camel-ship` in Bob IDE, in the normal agent
mode or the generated Camel Ship mode.
+ The parent calls `spawn_subagent` with the `camel-ship-worker` preset and
`fork_context: false`; the preset has
+ only read tools. Interactive sign-in is sufficient. Accepted on Bob Shell
2.0.2 on Linux on 2026-09-09.
+
+| GitHub Copilot CLI
+| `/camel-ship` from the generated skill in a trusted session that exposes
`task` and the `camel-ship-worker`
+ custom agent; the worker allows only the `read` and `search` aliases. Plan
mode allows `--status` only.
+ Accepted on Copilot CLI 1.0.83 on Linux on 2026-09-09.
+
+| Claude Code
+| `/camel-ship` from `.claude/skills/` in a trusted session that exposes the
`Agent` tool and the
+ `camel-ship-worker` subagent, which declares exactly `tools: Read, Grep,
Glob`. The skill never leaves plan mode
+ or changes the permission mode, and the generated settings do not
pre-approve the Ship command. Accepted on Claude
+ Code 2.1.267 on Linux on 2026-09-10.
+
+| OpenAI Codex CLI (development snapshot only)
+| `$camel-ship` in a trusted session with the `camel_ship_worker` custom
agent, declared with
+ `sandbox_mode = "read-only"` and no MCP servers. Where the host does not
enforce the sandbox, the worker's
+ instructions are the operative restriction. If `--backend codex-native` is
requested and dispatch is unavailable
+ the skill stops without starting a run.
+|===
+
+A fresh context is not an OS sandbox: read access follows the parent's
permitted paths. Do not broaden permissions,
+add directories or substitute another role when a task cannot reach its inputs.
+
+Recovery is shared. After an interruption inspect `--status --json`, wait for
a still-running child or submit its
+saved response, and never dispatch the same pending task twice. A task keeps
its deadline; `--resume` after expiry
+fails that attempt and a second explicit resume issues a new task.
`handoff-read-failed` means the pending task
+could not be verified: resume once to record the failure, then resume again
for a fresh task, without editing the
+stored evidence. Ship cannot stop a host-owned child; use the host's
cancellation controls, and `--abort` invalidates
+the run and rejects late results. Failed runs return JSON with exit code 1 and
`run.message`; stop after any command
+error, including `stale-stage-input` or a permission denial, and wait for a
new instruction.
+
+[[entry-points]]
+== Entry points per agent
+
+* *Claude Code* and *GitHub Copilot CLI* expose `/camel-ship` through their
skill directories and relay eligible runs
+ to their read-only worker; Claude Code's compatibility command stub only
points at the skill.
+* *IBM Bob 2* exposes the native skill as `$camel-ship` in Bob Shell and
`/camel-ship` in Bob IDE.
+* *OpenAI Codex CLI* exposes `$camel-ship` with no generated command file.
+* *Google Antigravity* invokes the native `camel-ship` skill, which forwards
the options once.
+* *Qwen Code* and *OpenCode* generate a `/camel-ship` command stub that
forwards the options once.
+* *Pi* exposes Ship only as `/skill:camel-ship`; there is deliberately no
`/camel-ship` prompt, because Pi's prompt
+ expansion flattens quoted option values.
+
+Workspaces generated before the controller-owned Ship must be regenerated with
the same agent and command surface
+(`camel-kit init --here --ai <same-agent> --force`, after backing up
customizations). Re-initialization installs the
+current entry point and removes the obsolete prompt-owned Ship guides. A
pre-controller `.camel-kit/ship-state.json`,
+or a `.camel-kit/pipeline.json` not in manual mode, makes Ship fail closed:
archive it outside the project first.
+
+[[examples]]
+== Examples
+
+[source,bash]
+----
+# No context: a short discovery conversation
+camel-kit ship
+
+# Document and text context, pausing at every gate
+camel-kit ship --document requirements.md --text "Prefer YAML; no Java" --ask
always
+
+# Resume, answer an open question, inspect, abort
+camel-kit ship --resume <run-id>
+camel-kit ship --resume <run-id> --text "Use eu-west-1"
+camel-kit ship --status <run-id>
+camel-kit ship --abort <run-id>
+
+# Import the active manual design and start at planning
+camel-kit ship --start-from plan
+
+# The same through the agent entry points
+/camel-ship --document requirements.md
+$camel-ship --document requirements.md
+/skill:camel-ship --document requirements.md
+----
+
+[[comparison]]
+== Ship and the manual pipeline
+
+[cols="1,2,2"]
+|===
+| | Manual pipeline | Ship
+
+| Who runs the stages | The agent; chained stages hand off automatically | The
local controller
+| Approval gates | One, the design approval | By policy: after plan and
execute (`smart`), at every stage
+ (`always`), or none for ambiguity (`never`); missing tools, failed checks
and ungranted authority always stop
+| Resume | From the artifacts on disk, by stage | By run ID, from the earliest
stale stage
+| Where changes happen | The working tree | A staged workspace, published
after the gates
+| Runtimes | Camel Main, Spring Boot, Quarkus | Camel Main with YAML DSL
+|===
+
+Maintainers run the Pi live gate manually with the `linux-ship-certification`
Maven profile and the
+`CAMEL_KIT_SHIP_LIVE_PI` and `CAMEL_KIT_SHIP_LIVE_NODE` variables; it is not
part of CI and not something users run.
diff --git a/docs/modules/ROOT/pages/verification.adoc
b/docs/modules/ROOT/pages/verification.adoc
index 258e7087..fe81e34d 100644
--- a/docs/modules/ROOT/pages/verification.adoc
+++ b/docs/modules/ROOT/pages/verification.adoc
@@ -1,3 +1,126 @@
= Runtime verification
-This page is written in a following documentation pull request.
+`camel-verify` is the internal skill that checks whether the generated
integration actually builds, starts and
+behaves as its tests expect. `/camel-execute` dispatches it once, after all
tasks and the cross-cutting review, in an
+isolated subagent where the agent supports one and inline otherwise. It has no
command stub: for a route that breaks
+outside a pipeline run use xref:camel-debug.adoc[`/camel-debug`].
+
+The result is a structured report embedded in
`docs/camel-kit/<pipeline-id>/execution-report.md` and summarized
+there as `PASS`, `PARTIAL`, `FAIL` or `NOT_RUN`. Verification is
informational: a failed or skipped check never
+blocks the execution summary, and a chained pipeline continues to
`/camel-validate` regardless. Read the report and
+resolve what failed or was skipped before deploying.
+
+[[environment]]
+== Environment check
+
+Before the phases run, the skill reads `project.runtime` from
`.camel-kit/config.properties` (`main`, `spring-boot`
+or `quarkus`) and checks the tools: the Maven wrapper or a system `mvn` for
Spring Boot and Quarkus, JBang for Camel
+Main, the JDK, Docker, and the Camel JBang test plugin. It prints what it
found and which phases can run; nothing is
+skipped silently.
+
+[cols="1,1,2"]
+|===
+| Missing tool | Affected | Reported as
+
+| Maven (no `./mvnw`, no `mvn`) | Phase 1 for Spring Boot and Quarkus | Build
verification skipped
+| JDK | Phase 1 for every runtime | Runtime verification skipped
+| JBang | Phase 1 for Camel Main | Startup smoke verification skipped
+| Docker | The tests that declare Testcontainers | Those tests skipped;
container-free and mock-only tests still run
+| `camel test` plugin | Phase 2 | Test verification skipped
+|===
+
+[[phase1]]
+== Phase 1: build or startup smoke
+
+For Spring Boot and Quarkus the skill compiles every target module from the
project root (`./mvnw compile -q`, or
+`./mvnw -f <module>/pom.xml compile -q` for a nested module). The process exit
status is the only pass or fail
+signal; the build output is diagnostic data. For Camel Main there is no
compile step: phase 1 runs the startup smoke
+test of the generated routes instead and checks its log markers.
+
+On failure the skill classifies the error with the shipped taxonomy and
applies the fix that taxonomy entry owns,
+then retries, up to 15 compile attempts or 6 Camel Main startup attempts. A
fix that leaves the same error in place
+short-circuits to the promotion rules below instead of consuming the budget.
An unclassified error is escalated with
+a bounded diagnostic rather than guessed at.
+
+----
+Build attempt 1: FAIL -> missing dependency, added the runtime's Kafka
artifact
+Build attempt 2: FAIL -> version conflict, aligned the platform BOM
+Build attempt 3: PASS
+----
+
+[[phase2]]
+== Phase 2: tests
+
+The skill discovers every `*.it.yaml` file in the project, validates each one
against the configured Citrus version
+and the approved task and design, classifies the files that declare
Testcontainers as Docker-dependent, and runs the
+runnable ones with the Camel JBang test plugin:
+
+[source,bash]
+----
+camel test run <test-files>
+----
+
+Citrus owns the test lifecycle: Testcontainers start and stop the required
databases or brokers, the Camel
+integration is started through the JBang runner, and send and receive actions
check the behaviour; external APIs are
+mocked. The phase is skipped, with the reason, when phase 1 failed, when no
test file exists, when the test plugin is
+missing, or when Docker is unavailable and every discovered test needs it.
+
+Failures are classified and routed, with the same 15-attempt ceiling and
short-circuit rule as phase 1.
+
+[[routing]]
+== Fix routing
+
+[cols="2,1,2"]
+|===
+| Error | Fix target | Action
+
+| Missing Camel or third-party dependency, missing property, version
incompatibility | Self-repair | Add the
+ runtime-aware dependency or property, align the BOM
+| Wrong component options, YAML schema error, constitution violation at
runtime | `camel-validate`, then
+ `camel-implement` | Diagnose against the catalog, then correct the affected
flow
+| Broken route structure, wrong URI, missing bean, expression or
transformation failure, assertion mismatch |
+ `camel-implement` | Regenerate the affected flow from the design
+| Test parse error, wrong expectation | `camel-test` | Regenerate the test
from the design
+| Timeout, Testcontainers launch failure | Self-repair, or `camel-implement`
for slow route logic | Fix the service
+ configuration or the route
+| Same error after a fix | Promotion | Check the catalog, then the re-plan loop
+| Iteration limit, unclassified error, required tool missing | Escalate |
Report with the attempted fix
+|===
+
+Promotion has two tiers. After one failed fix, the skill checks the catalog
for the project's runtime and platform
+BOM: if the complete list has no exact match for the required artifact, the
re-plan loop of `/camel-execute` starts
+at once; an incomplete list, a timeout or a mismatched binding is unknown, not
absence. After three failed fixes on
+the same error class the re-plan loop starts regardless. Re-planning modifies
only the affected flow sections of the
+design, keeps the business requirements, re-executes the affected tasks and
verifies again, for at most three rounds.
+
+[[report]]
+== Phase 3: report
+
+----
+VERIFICATION REPORT
+Runtime: Spring Boot
+Maven: ./mvnw (wrapper)
+
+Phase 1 - Build / Startup Smoke: PASS (1 fix)
+Phase 2 - Test: PASS: 8/8 tests passed
+
+Fixes applied:
+ 1. [Build] Added the verified runtime dependency required by a migrated route
+
+Skipped checks:
+ (none)
+----
+
+A failed phase adds its last error as a bounded diagnostic with its
classification, the fix attempted and the
+escalation. Each iteration is also appended to `.camel-kit/verify-log.md` with
its findings, classified as critical
+(build fails, route does not start, data loss risk), warning (route starts but
behaves incorrectly) or info.
+
+[[eitl]]
+== Environment in the loop
+
+Compiling is not running. The verification loop exercises the generated
application with its real endpoints and the
+required infrastructure, so that a route that compiles but fails at startup, a
wrong endpoint option or a mapping
+that produces the wrong message is found before deployment rather than in
production. When the project has a
+generated `docker-compose.yaml`, phase 1 starts its external services before
the Camel Main smoke test, and the
+taxonomy repairs can restart a named failing service; phase 2 relies on the
Testcontainers declared by the tests. See
+xref:eitl.adoc[] for the design behind this.
