Contributing & Builds

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• script/publish.ts
• AGENTS.md
• src/features/builtin-skills/skills/git-master.ts
• sisyphus-prompt.md

This page outlines the standards and automated processes for contributing to the Oh-My-OpenCode project. It covers development environment setup, strict coding conventions, Test-Driven Development (TDD) requirements, and the automated multi-package publishing workflow.

The project operates under a strict English-only policy for all communications, including code comments, commit messages, and GitHub interactions, to ensure global accessibility and maintainability.
Sources: AGENTS.md:79-106, CONTRIBUTING.md:27-46

Development Environment & Standards

Oh-My-OpenCode is built exclusively using the Bun runtime. Development requires Bun, TypeScript 5.7.3+, and OpenCode 1.0.150+.

Core Tech Stack and Constraints

Category	Requirement	Description
Package Manager	Bun	No npm or yarn allowed. Use bun run, bun build, bunx.
Type Definitions	bun-types	Never use @types/node.
Language	English	Mandatory for all code, comments, and git history.
Testing	TDD	Red-Green-Refactor is mandatory.
PR Target	dev branch	All pull requests must target dev, never master.

Sources: CONTRIBUTING.md:52-60, AGENTS.md:144-180

Git Workflow and Branching

The project follows a specific branching model where master represents the deployed/published state and dev serves as the integration branch. Features are developed in dedicated feature branches and merged into dev for testing before reaching master.

This diagram illustrates the mandatory flow for all code contributions.
Sources: AGENTS.md:14-35

Contribution Guidelines

Test-Driven Development (TDD)

The project enforces a strict TDD policy. Implementation code must never be written before a failing test exists. Tests must be placed in *.test.ts files alongside the source code.

1. RED: Write a test and run bun test to confirm it fails.
2. GREEN: Implement the minimum amount of code required to make the test pass.
3. REFACTOR: Clean up the implementation while ensuring the tests remain green.
   Sources: AGENTS.md:131-142

Git Master Standards

The project employs a specialized "Git Master" logic that enforces atomic commits. Single "giant" commits are treated as failures.

• Atomic Splits: Changes must be split by directory, component type, or concern.
• Commit Count Rule: For $N$ files changed, there must be at least $\lceil N/3 \rceil$ commits.
• Pairing: Test files must always be in the same commit as their implementation.
  Sources: src/features/builtin-skills/skills/git-master.ts:35-65, src/features/builtin-skills/skills/git-master.ts:167-175

This flow represents the logic used to ensure clean, reviewable version history.
Sources: src/features/builtin-skills/skills/git-master.ts:133-165

Build and Automation

Common Commands

Developers use the following Bun-based commands for local development:

• bun run typecheck: Performs static type analysis.
• bun run build: Generates ESM output, TypeScript declarations, and JSON schemas.
• bun run rebuild: Cleans the dist/ directory and performs a fresh build.
• bun test: Executes the 100+ test files in the project.
  Sources: AGENTS.md:188-193, CONTRIBUTING.md:92-100

Multi-Package Publishing Workflow

Oh-My-OpenCode uses a complex multi-package structure, including a main package and seven platform-specific packages (e.g., darwin-arm64, linux-x64). Publishing is handled exclusively through GitHub Actions; local bun publish is strictly forbidden.

This sequence shows the batch-based publishing strategy used to prevent OIDC token expiration during long-running builds.
Sources: script/publish.ts:161-200, script/publish.ts:252-285, AGENTS.md:197-201

Versioning and Tags

The system automatically determines the next version based on the latest registry data and the requested bump type (major, minor, patch).

• Prerelease Handling: Correctly identifies and increments beta versions (e.g., 3.0.0-beta.7).
• Tagging: Creates a git tag and a GitHub release containing a summary of commits and community contributors.
  Sources: script/publish.ts:40-52, script/publish.ts:287-320

Project Complexity Hotspots

When contributing to core logic, developers should be aware of high-complexity files that require careful review:

File	Lines	Responsibility
src/features/builtin-skills/skills.ts	1729	Core skill definitions.
src/features/background-agent/manager.ts	1418	Task lifecycle and concurrency.
src/hooks/atlas/index.ts	757	Master orchestration hook.
Sources: AGENTS.md:205-214

The "Contributing & Builds" framework ensures that Oh-My-OpenCode maintains high code quality through mandatory TDD, atomic git operations, and a fully automated, transparent release cycle.