Contributing

Contributing to OMP

OMP is open-contribution. All changes go through pull requests — no direct pushes to main.

PR Workflow

Fork & branch — branch off main; use the format type/short-description (e.g. feat/mcp-retry).
Write the code — keep diffs focused; one logical change per PR.
Tests first — all new behaviour must be covered; CI will block if coverage drops.
Push & open PR — fill the PR template; link the related issue.
Review cycle — address reviewer comments in-place; avoid force-pushes during review.
Merge — squash+merge into main by a maintainer; branch is auto-deleted.

Code Style

TypeScript Strict mode. No any. Prefer unknown + narrowing.

Formatting Biome handles formatting and linting. Run bun run check before pushing.

Imports Absolute imports from src/. Group: std → external → internal → types.

Naming camelCase for variables/functions, PascalCase for types/classes, SCREAMING_SNAKE for constants.

Commit Conventions

Follow Conventional Commits. Subject ≤ 72 chars.

feat(agents): add retry backoff to executor
fix(mcp): resolve tool schema validation race
docs(contributing): add PR checklist
chore(deps): bump @anthropic-ai/sdk to 0.24.0

Types: feat, fix, docs, style, refactor, test, chore. Use ! suffix or BREAKING CHANGE: footer for breaking changes.

Testing Requirements

Unit tests for all new functions with observable side-effects.
Integration tests for any new agent tool or MCP endpoint.
Coverage gate: existing module coverage must not drop; new files must reach ≥ 80 %.
Run tests locally with bun test before pushing.
Snapshot tests need explicit reviewer approval — prefer behaviour assertions.

Issue Templates

Bug Report

OMP version + OS
Minimal reproduction
Expected vs. actual behaviour
Relevant logs

Feature Request

Problem statement
Proposed solution
Alternatives considered
Acceptance criteria

RFC / ADR

Open a ADR draft first
Reference prior art
Discuss on the issue before coding