Developer Guide
Table of Contents
Quick reference for the ORE Studio developer workflow. The
* Workflow Recipes section links to the key recipes organised by
phase — use it to find the right recipe for any routine operation.
The * External Resources section lists the dashboards, CI
pipelines, and community links you'll reach for every day.
Workflow Recipes
Setup
First-time checkout and environment initialisation.
| Recipe | What it does |
|---|---|
| How do I set up a development environment? | Install all required packages on Ubuntu/Debian/WSL with one script, then initialise the database. |
| How do I initialise the checkout environment? | Generate the .env file, NATS certificates, and IAM keys for a local checkout with compass env init. |
| How do I manage the checkout environment with compass? | Show, diff, and update the .env — credential generation, masked variable listing, env-format versioning. |
| How do I list available CMake presets? | Run cmake --list-presets to see all configure presets defined in CMakePresets.json. |
Build
Configure CMake and compile the project.
| Recipe | What it does |
|---|---|
| How do I configure the project? | Pick a CMake preset and run configure — the once-per-checkout step before building. |
| How do I build the system? | Build with compass build (preset from .env), or directly with cmake --build --preset. |
| How do I format C++ sources with clang-format? | Run the format or check-format CMake target to reformat or verify all C++ sources. |
| How do I generate PlantUML diagrams? | Build all PlantUML diagrams with the mad target. |
Test
Run the test suite and investigate failures.
| Recipe | What it does |
|---|---|
| How do I run the tests? | Run the full or per-component test suite, with optional logging and result analysis. |
| How do I see an overview of the test run? | Use compass test results to parse Catch2 XML output and display per-suite stats and failures. |
| How do I enable test logging? | Turn on test-suite logging with compass test logging on/off/status. |
| How do I investigate a test failure? | Run a failing suite with logging on, parse results, drill into per-test logs, add targeted logging. |
| How do I run SQL in the environment? | Run ad-hoc SQL, files, or an interactive psql session against the local database via compass sql. |
Develop
Orient, journal, work a task, and keep the repo clean.
| Recipe | What it does |
|---|---|
| How do I orient a new session? | Run compass bearings for a full cold-start briefing: project, sprint, last session, key recipes. |
| How do I see where we are? | Use compass where / compass status to report the current version, sprint, and in-flight work. |
| How do I get a sprint or story status? | Use compass sprint status and compass story status to see done, in-progress, and not-started items. |
| How do I know what I was working on? | Use compass journal where and compass task start to recover session context after a restart. |
| How do I use the session journal? | Clock on to work with compass task start; use compass journal for restart recovery and fleet overlap detection. |
| How do I start a unit of work with compass? | Use compass story new or compass task new to fetch main, create a branch, and scaffold documents. |
| How do I work a task? | Full procedure: BACKLOG → STARTED → DONE, with Notes and Result fields. |
| How do I search docs with compass? | Use compass search to full-text-search the org-roam doc graph. |
| How do I add a doc with compass? | Use compass add to create a story/task/sprint/recipe/… document via ores.codegen. |
| How do I see what every worktree is doing? | Use compass fleet to list each git worktree's branch, story, task, and open PR. |
| How do I start the ORE Studio services? | Start NATS and all backend services with compass services start; stop and check status with companion verbs. |
| How do I run the ores shell? | Launch ores.shell with NATS and login defaults from .env via compass shell; scripted sessions with -f. |
| How do I run codegen? | Invoke ores.codegen to generate code from a JSON model — set up the venv, run the wrapper, find the output. |
PR and Review
Open, monitor, address reviews, and merge pull requests.
| Recipe | What it does |
|---|---|
| How do I create a PR? | Open a pull request with compass pr create — title validation, structured body, Traceability table. |
| How do I monitor a PR until green? | Drive a PR to green CI and zero unresolved threads via compass pr checks. |
| How do I fix a failing CI check? | Identify the failing check via gh, read the run log, apply the fix as a new commit. |
| How do I address PR review comments? | Read comments via compass review, apply fixes as new commits, reply, resolve threads. |
| How do I find PRs with unattended reviews? | Use compass review pending to triage PRs with unresolved threads. |
| How do I merge a PR? | Merge with compass pr merge — guard rails on threads and CI, merge commit only, branch cleanup. |
Deploy
Build and publish the site, skills, and settings.
| Recipe | What it does |
|---|---|
| How do I serve the site locally? | Compile and preview the org-mode site before pushing with compass site serve. |
| How do I deploy the site? | Build the ORE Studio website locally with compass build --direct site. |
| How do I deploy the skills? | Build the Claude Code skills bundle with compass build --direct skills. |
| How do I deploy the settings? | Regenerate .claude/settings.json from its literate org source with compass build --direct settings. |
| How do I deploy all org-mode artefacts? | Build site, skills, settings, and diagrams in one shot with the deploy_org CMake target (diagrams need cmake). |
Release
Version bumps, release notes, and sprint close-out.
| Recipe | What it does |
|---|---|
| How do I bump the project version? | Bump the version in CMakeLists.txt, vcpkg.json, workflow filenames, and readme badges. |
| How do I generate release notes? | Scaffold release_notes.org from merged-PR data and the closing sprint's stories; tag and open a draft GitHub release. |
| How do I generate sprint health charts? | Use compass sprint charts to extract git/PR metrics and render the four sprint health PNGs. |
Agile
Backlog, sprint planning, and task lifecycle.
| Recipe | What it does |
|---|---|
| How do I open a new sprint? | Scaffold a new sprint folder, set its mission, wire into the version manifest. |
| How do I plan a sprint? | Set the mission, score captures against sprint goals, promote winners into stories. |
| How do I refine the backlog? | Scan, clarify, cull, and re-prioritise captures in a backlog housekeeping session. |
| How do I capture ideas from freeform text? | Decompose unstructured notes into well-structured captures filed in inbox/. |
| How do I triage and promote captures? | Move inbox captures into triaged buckets and promote a capture into a story or task. |
External Resources
Source and Documentation
| Resource | Link |
|---|---|
| GitHub | github.com/OreStudio/OreStudio |
| Doxygen | orestudio.github.io — Doxygen API docs |
| Site | orestudio.github.io/OreStudio |
| DeepWiki | deepwiki.com/OreStudio/OreStudio |
Community
| Resource | Link |
|---|---|
| Discord | discord.gg/ztAaxmsnUJ |
Build and Quality
| Resource | Link |
|---|---|
| CDash Dashboard | my.cdash.org — OreStudio |
| CI — Linux | continuous-linux.yml |
| CI — Windows | continuous-windows.yml |
| CI — macOS | continuous-macos.yml |
| CI — Nightly Linux | nightly-linux.yml |
| CI — Nightly Format | nightly-format.yml |
| Releases | github.com/OreStudio/OreStudio/releases |
Code Style
| Resource | Link |
|---|---|
| C++ clang-format config | C++ code style: clang-format configuration — literate source, all settings documented. |
| Format recipe | How do I format C++ sources with clang-format? |
Design and UX
| Resource | Link |
|---|---|
| UX Language | UX Language — colour semantics, badge catalogue, entity window anatomy. |
| UI design principles | UI design principles — typography, colour, spacing, motion. |
| Icon guidelines | Icon guidelines — icon inventory and semantic usage. |