Development Guide

Everything you need to contribute to QuantumReef — from cloning the repo to merging your first pull request. We follow Orion-OS principles: elegant systems, glass-box transparency, and truth over theater.

Prerequisites

Tool	Version	Purpose
Node.js	≥20 LTS	JavaScript runtime for frontend and CLI packages
pnpm	≥9	Monorepo package manager
Rust	stable (≥1.78)	Tauri backend compilation
Tauri CLI	2.x	Desktop app development and bundling
Git	≥2.40	Version control
Xcode (macOS)	≥15	Required for macOS/iOS targets
Android Studio (optional)	≥2024	Required for Android mobile target

bash

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update stable

# Install pnpm
npm install -g pnpm

# Install Tauri CLI
cargo install tauri-cli --version "^2"

Setting Up the Dev Environment

Clone and Install

bash

# Clone the repository
git clone https://github.com/pt-act/QuantumReef-main.git
cd quantumreef

# Install all workspace dependencies
pnpm install

# Copy environment config
cp .env.example .env.local
# Edit .env.local and add any required API keys for testing

Start the Desktop App in Dev Mode

bash

# Start the full desktop app (Tauri + SolidJS hot reload)
pnpm dev

# This runs:
# 1. Vite dev server for the SolidJS frontend (http://localhost:5173)
# 2. Tauri in dev mode (opens a native window with hot reload)

Start the Landing Site in Dev Mode

bash

cd QuantumReef-Landing
pnpm dev
# Opens at http://localhost:3000

Start the CLI Daemon in Dev Mode

bash

cd packages/owpenbot
pnpm dev
# Starts the daemon at http://localhost:7070

Build Commands

Command	Description
pnpm build	Build all packages (frontend + desktop + CLI)
pnpm build:app	Build the SolidJS frontend only
pnpm build:desktop	Build the Tauri desktop app for the current platform
pnpm build:desktop --target universal-apple-darwin	Build a universal macOS binary (Intel + Apple Silicon)
pnpm build:cli	Build the quantumreef CLI binary
pnpm build:landing	Build the Next.js marketing/docs site
pnpm bump:patch	Bump all package versions (patch)
pnpm bump:minor	Bump all package versions (minor)
pnpm bump:major	Bump all package versions (major)

Release builds

Production desktop builds are created by GitHub Actions on tag push. You rarely need to run pnpm build:desktop locally unless you are debugging the build pipeline. See the Release Process section below.

Running Tests

All Tests

bash

# Run all tests across all packages
pnpm test

# Run tests in watch mode (re-runs on file change)
pnpm test:watch

# Run tests with coverage report
pnpm test:coverage

Package-specific Tests

bash

# Frontend component and store tests
pnpm test --filter packages/app

# Engine adapter unit tests
pnpm test packages/app/src/lib/engines

# CLI and daemon tests
pnpm test --filter packages/owpenbot

# Rust backend tests
cd packages/desktop/src-tauri && cargo test

Testing Philosophy

QuantumReef follows the Orion-OS focused testing philosophy: 2–8 tests per feature group, maximum 10 gap-fill tests per feature, totalling 16–34 tests per significant feature. We favour fast, meaningful tests over comprehensive coverage metrics.

Test Type	Where	When to Write
Unit	*.test.ts alongside source	Engine adapter methods, store mutations, utility functions
Component	*.test.tsx with solid-testing-library	Complex interactive components, keyboard navigation
Integration	tests/integration/	Engine client ↔ mock engine server round-trips
E2E	tests/e2e/ with Playwright	Critical user flows: create session, send prompt, switch engine
Rust	src-tauri/src/*/.rs #[test]	IPC command handlers, process management, mobile pairing

Code Style

TypeScript / SolidJS

400-line component limit — enforced by pre-commit hook (scripts/check-component-size.sh). Approaching 350? Start extracting.
Biome for formatting and linting — run pnpm lint and pnpm format
Strict TypeScript — no any, no ts-ignore without a comment explaining why
Named exports preferred over default exports (easier to grep and refactor)
Async state scoped to the component that owns it — no global loading spinners

bash

# Check formatting
pnpm lint

# Auto-fix formatting
pnpm format

# Type-check without emitting
pnpm typecheck

Rust

Format with cargo fmt before committing
Lint with cargo clippy -- -D warnings
Document all public functions and structs with doc comments
Avoid unwrap() in production paths — use proper error propagation with ?

Branch Naming

Branch Pattern	Use Case
feat/short-description	New features (e.g. feat/fractal-agent-panel)
fix/short-description	Bug fixes (e.g. fix/session-abort-hang)
docs/short-description	Documentation only (e.g. docs/engine-client-api)
refactor/short-description	Refactoring without behaviour change
chore/short-description	Tooling, dependencies, CI changes
release/vX.Y.Z	Release preparation branches

All branches should be created from main. Rebase (do not merge) when keeping your branch up to date.

Submitting Pull Requests

Fork the repo and create a feature branch from main
Make your changes. Keep commits atomic and well-described (Conventional Commits format)
Run pnpm test, pnpm lint, and pnpm typecheck — all must pass
Open a PR against main with the provided PR template filled in
A maintainer will review within 3 business days. Address review comments via new commits (do not force-push during review)
Once approved, a maintainer will squash-merge into main

PR Title Convention

bash

# Format: type(scope): description
feat(engines): add Kiro CLI engine adapter
fix(sessions): resolve abort hang on OpenCode timeout
docs(api): document permissions.reply() method
chore(deps): bump tauri to 2.1.0

Draft PRs welcome

Open a draft PR early to get feedback on your approach before investing in a full implementation. Tag it [WIP] in the title and set it to draft status.

Release Process

Releases are triggered by pushing a version tag. The GitHub Actions Release App workflow builds the desktop app for macOS (universal), Linux (AppImage + deb), and Windows (NSIS installer), then creates a GitHub Release with all artefacts attached.

bash

# 1. Ensure main is green
gh run list --workflow "CI" --limit 5

# 2. Bump versions across all packages
pnpm bump:patch   # or :minor or :major

# 3. Commit the version bump
git add -A
git commit -m "chore: bump to v0.4.3"
git push origin main

# 4. Tag and push
git tag v0.4.3
git push origin v0.4.3

# 5. Monitor the release workflow
gh run list --workflow "Release App" --limit 3

# 6. Verify the release
gh release view v0.4.3

Re-running a Failed Release

bash

# Re-trigger the release workflow for an existing tag
gh workflow run "Release App" \
  --repo pt-act/quantumreef \
  -f tag=v0.4.3

Getting Help

If you are stuck, here is where to look and who to ask:

Resource	Link / Command
GitHub Discussions	https://github.com/pt-act/QuantumReef-main/discussions
Issue tracker	https://github.com/pt-act/QuantumReef-main/issues
Architecture docs	/docs/contributing/architecture
Engine Client API	/docs/api/engine-client-api
Open a question issue	Use the 'Question' issue template on GitHub

First-time contributors

Look for issues labelled good first issue on GitHub — these are scoped specifically to be approachable without deep codebase knowledge. Each comes with context links and a suggested approach.