Contributing

Development Setup

git clone https://github.com/styrene-lab/omegon.git
cd omegon
cd core && cargo build -p omegon
cargo test -p omegon

Branch Policy

Trunk-based development on main. No long-lived feature branches.

Direct commits to main for single-file fixes, typos, config tweaks
Feature branches (feature/<name>) for multi-file work — must merge within one week
No branch may accumulate more than ~50 commits before merging. If it does, decompose it.

Conventional Commits

All commits must follow the Conventional Commits spec:

feat(tui): surface SegmentMeta as response header tag
fix(providers): handle rate-limit 429 with exponential backoff
chore(release): 0.15.2-rc.5
refactor(memory): extract semantic search into separate module
docs: update provider matrix in FAQ
test: add snapshot test for rounded borders

Testing Requirements

Every non-trivial code change must include tests
cargo test -p omegon must pass with zero failures
cargo check must produce zero warnings
Snapshot tests (via cargo-insta) are accepted with cargo insta test --accept
Tests must pass before merge

Release Workflow

Releases use the just task runner:

# Cut a release candidate (bump, test, commit, tag, build, sign)
just rc

# Sign with Apple Developer ID (YubiKey — optional)
just sign

# Publish: push to origin, trigger CI, build docs, link binary
just publish

# Cut a stable release (strip -rc.N suffix)
just release

What `just publish` Does

Pre-flight: verifies clean working tree, binary exists, tag exists, version matches
Pushes to origin with tags — triggers three CI workflows:
- release.yml — builds binaries for 4 platforms, signs with cosign, creates GitHub Release
- site.yml — rebuilds docs site, pushes container to GHCR, ArgoCD auto-deploys
Builds docs site locally (verification)
Links signed binary to /opt/homebrew/bin/omegon
Runs post-publish smoke test

Crate Structure

Crate	Purpose
`omegon`	Binary — TUI, agent loop, providers, tools, cleave orchestrator
`omegon-git`	Git operations — worktree management, merge, diff
`omegon-memory`	Project memory — facts, episodes, semantic search, knowledge graph
`omegon-secrets`	Credential storage — keychain, encrypted file, Vault
`omegon-traits`	Shared traits and types across crates
`opsx-core`	OpenSpec engine — spec parsing, verification, lifecycle

Feature Proposals

New features should start with a design tree node, not a PR. Use design_tree_update(create) to propose a new exploration, add research and open questions, and let the design converge before writing code. This prevents throwaway work and ensures architectural coherence.