This file is the entry point for AI agents and new developers working in the workspace. It holds workspace-wide conventions only. What the products are and how they fit together is in docs/architecture/OVERVIEW.dox; the safety and quality approach is in docs/safety/SAFETY_AND_QUALITY_PLAN.dox; each product describes itself in its own README.md and CLAUDE.md (read those before doing real work in a product). Tools you need to install: REQUIREMENTS.dox.

Layout and product names

The workspace is organised by RCA layer. Folder = product name = GitHub repository name (since 2026-09-22; each of the 17 bula173/* product repos was renamed to match its folder/product name — Conan package names were left as-is, see the Conan table further down).

platform/protocol_adapters/ vs plain application/ (2026-09-23): a product goes under platform/protocol_adapters/ only if it implements an RTE-defined OSAdapter/ProtocolAdapter vtable (e.g. Platform_Protocol_DDS implements rte_osadapter_flow_t, Platform_Protocol_JRU implements rte_osadapter_log_t) — a swappable backend for a seam Platform_RTE itself declares. A standalone library with no Platform_RTE dependency and no seam implementation (Platform_Protocol_KM114, Platform_Protocol_KM038 — pure off-line message-format codecs) sits directly under application/ instead, alongside RBC_GP/GA/SA, even though its name still starts with Platform_Protocol_ (repo names are not renamed when a product moves folders, same as the old-repository-name note below).

application/ vs services/ (2026-09-23): application/ is RBC_GP/GA/SA plus anything that runs embedded on the same hardware as one of them (Platform_Protocol_KM114/KM038, linked into RBC_GP's own vital build; RBC_Maintenance_Web, linked into and running inside RBC_GP's Gateway process). services/ is for products that get their own dedicated hardware and talk to the RBC only over a network boundary via the Gateway (RBC_TrainCommServer, RBC_AI_Diagnostic_Server) — a deployment-topology distinction, not a naming or RCA-layer one. RBC_Maintenance_Web was briefly moved to services/ and moved back the same day once this criterion was settled — see its own CLAUDE.md for the record.

The old repository names (safeAPIFreamwork, safeAPIBackendPosix, safeCommFreamwork, safeApiProtocolAdapterDDS, safeAPIRBC2oo2GP/GA/SA, safeAPIRBC2oo2TestEnv, CommServer, SimCore, TrainRBCSim, ILRBCSim, CTCRBCSim, SAPIMacOSToolchain, LinuxMacOSToolchain, QNXMacOSToolchain, FreeRTOSToolchain) were swept from documentation workspace-wide on 2026-09-22, including dated ADRs and other point-in-time text — a deliberate exception to the usual "leave historical text as written" rule, because the confusion of two names for one product outweighed preserving exact period wording here. Naming lineage (what was called what, and when) is recorded as prose in WORKSPACE_HISTORY.dox, not by leaving old names scattered through unrelated documents. Conan recipe names are a separate, unrelated naming scheme and were not touched (see the Conan table further down); GitHub keeps every old repository name as a redirect, so old links and git remote URLs still resolve regardless.

Product documentation mirror

GitHub's web UI never inlines a submodule's content; a folder under application/, platform/ or test/ shows only as a link to that product's own repo at a pinned commit. docs/products/ is a mirrored, committed snapshot of every product's README.md, CLAUDE.md and markdown docs/ (never the generated, gitignored docs/api/), so a product's documentation reads directly in this repo. Not the source of truth — regenerate it (./syncProductDocs.sh) and commit the result whenever a submodule pointer is bumped, the same manual-regeneration posture dist/ and the Conan cache already have. The always-current, generated-HTML alternative is the published docs site (.github/workflows/docs.yml); this mirror is for reading directly in the repo, e.g. on GitHub's web UI or a local clone with no build step.

Path rules

• Projects find each other by the workspace layout (application/* finds ../../platform/Platform_RTE). A flat sibling checkout of the old repository names still works as a fallback in most CMake files.
• Scripts take the workspace root as WORKSPACE_ROOT and address products by path.
• Docker builds use the workspace root as build context and copy products in the same layout.
• A product consumes another product only through its dist/ (or Conan package), never its src/ or build/. The exceptions are the documented header-only reaches between RBC_GA, RBC_SA and RBC_GP.

Documentation format (2026-09-25)

Documentation is written as Doxygen .dox pages (\page, \section, \subpage, \ref), not Markdown, so pages can be organised into a hierarchy: each product's DOCUMENTATION.dox is the parent page of all its pages. Exceptions kept as Markdown because GitHub or a tool reads them by name: every README.md (also the Doxygen main page of its product), CLAUDE.md, SKILL.md, GEMINI.md, licence files, GitHub issue and PR templates, and the generated docs/products/README.md index. Authoring rules: a page id unique per product, and text containing a C comment end marker uses /// line comments instead of /** */. Link to another product's page with a GitHub URL, not \ref (each product is its own Doxygen site). Doxygen 1.18 crashes at random in its comment scanner (identical input passes on one run and segfaults on the next); rerun the build, and the docs workflow retries three times.

Squeez tool usage

This workspace uses the squeez helper to keep agent output concise and high-signal. Use it when you want to compress notes or update the repo's stored guidance in a terse, technical form.

• Run squeez update to refresh the current compression setup and stored summaries from the working directory.
• Prefer ultra-compressed, factual phrasing: short sentences, no filler, explicit file paths and commands, and direct action-oriented updates.
• Keep tool usage consistent with the repo-level guidance: brief progress updates in commentary, and concise technical notes in project docs.

This is a workflow/tooling note for agent output, not a build or safety requirement.

TODO.dox and ISSUES.dox

Both files hold open items only; done work is deleted from them and lives in git history.

• TODO.dox: planned work as checkable items. Delete an item when it is done.
• ISSUES.dox: real defects, one entry each (found, symptom, investigated, status). Delete the entry when the fix is verified; put the reason and the fix in the commit message. A review pass records its findings under safety_quality/.

Plans and defects stay separate: a phase may reference an issue it depends on, but defects are not sub-bullets of a feature.

The dist/ convention

Whatever a product hands to another lives under its own dist/. It is generated, gitignored (dist/* plus !dist/.gitkeep) and regenerated by the product's own build step.

• C products: cmake --install build --prefix . installs headers, libraries, binaries and the CMake package config to dist/<platform>/, where <platform> is CMAKE_SYSTEM_NAME-CMAKE_SYSTEM_PROCESSOR (Darwin-arm64, Linux-x86_64, Linux-aarch64, QNX-x86_64). One architecture's install never overwrites another's. A consumer uses find_package(RteFramework) with CMAKE_PREFIX_PATH=<product>/dist/<platform>; the package config bakes in its own platform subdirectory. The install layout and the template's prefix resolution must stay in step (platform/Platform_RTE/cmake/RteFrameworkConfig.cmake.in). Products offer -DRTE_USE_INSTALLED_FRAMEWORK=ON (and similar) to consume dist/ instead of the default add_subdirectory() against source.
• Python products: python -m build --outdir dist produces a wheel and sdist. A downstream product installs with pip install --find-links <product>/dist <package>; transitive dependencies resolve when every product's dist/ is on --find-links. Maintain a standard pyproject.toml in every Python product (packages are published to JFrog Artifactory); do not replace it with setup.py.

Conan

Every product also has a conanfile.py, so the workspace can be driven through one package manager. Both paths (plain dist/ and Conan) must keep working; a change that breaks one is a regression. Adding Conan makes the build chain depend on an external tool and its network-fetched cache, which a safety assessment must account for.

Submodules

This root repo (bula173/RBC_Template, private) references every product as a git submodule: a pinned commit, not merged history. A change committed inside a product is not reflected here until its pointer is bumped (git submodule update --remote <path>, then commit at the root). Forgetting the bump is the main footgun. Cloning one product directly is unaffected. bootstrapWorkspace.sh clones every product at its branch tip instead of the pinned commit. Platform_Protocol_SafeComm and RBC_Test_CommServer were added locally first; check .gitmodules for the current state.

Safety posture

C products target MISRA C:2023 (deviations per MISRA Compliance:2020) and EN 50128; each states its own rules in its own CLAUDE.md, and those still name MISRA C:2012 until they are updated. The Python and Docker products are tooling: do not apply MISRA or EN 50128 rules to them. Details: the safety and quality plan. When the RBC wire layout changes, update the Python mirror (test/simulators/RBC_Test_Sim_Core/src/simcore/rbc_wire.py) with it.

Adding a product

Mirror the existing layout: git init, a README.md (responsibility, exposed interfaces, required interfaces, build), a CLAUDE.md for working notes, .claude/ for skills, a .gitignore before the first commit, and a dist/ produced by its own build if others consume it. Then add it to the tables in this file, README.md and docs/architecture/OVERVIEW.dox.

History

Workspace-level decisions and their consequences: docs/architecture/WORKSPACE_HISTORY.dox.