Contributing Guidelines & Tests
Relevant source files
The following files were used as context for generating this wiki page:
Oh My OpenCode is a community-driven project that requires high technical standards for code quality and verification. The project enforces a strict development workflow centered around the Bun runtime, TypeScript, and Test-Driven Development (TDD) to ensure the reliability of its multi-model agent orchestration system.
The following documentation outlines the mandatory protocols for contributors, ranging from local development setup to the specific verification strategies used by AI agents during task execution.
Sources: CONTRIBUTING.md:1-10, AGENTS.md:144-148
Development Environment & Workflow
The project is built exclusively using the Bun runtime. Traditional package managers like npm or yarn are strictly forbidden to maintain environment consistency.
Prerequisites & Setup
Contributors must ensure their environment meets the following specifications:
- Bun: Latest version (only supported package manager).
- TypeScript: Version 5.7.3+ for advanced type checking.
- OpenCode: Version 1.0.150+ for testing the plugin integration.
Sources: CONTRIBUTING.md:31-35, AGENTS.md:162-163
Build Commands
Standard lifecycle commands are managed through Bun:
| Command | Action |
|---|---|
bun run build | Full build (ESM + TypeScript declarations + JSON schema) |
bun run typecheck | Validates TypeScript without emitting files |
bun run rebuild | Cleans build output and performs a fresh build |
bun test | Executes the test suite (163+ test files) |
Sources: CONTRIBUTING.md:86-93, AGENTS.md:179-184
Code Style Conventions
The project follows a specific structural pattern to maintain the codebase's 115k+ lines of TypeScript:
- Kebab-case: Used for all directory naming.
- Barrel Pattern: Exports must use
export * from "./module"inindex.tsfiles. - Tool Structure: Every tool must contain
index.ts,types.ts,constants.ts,tools.ts, andutils.ts.
Sources: CONTRIBUTING.md:98-105, AGENTS.md:166-170
Testing & Verification Strategy
Testing is mandatory and follows a zero-tolerance policy for failures. The project utilizes a BDD (Behavior-Driven Development) approach with specific commenting styles (//#given, //#when, //#then).
Test-Driven Development (TDD)
Contributors must adhere to the Red-Green-Refactor cycle:
- RED: Write a failing test first.
- GREEN: Implement the minimum code required to pass the test.
- REFACTOR: Clean up the code while ensuring tests stay passing.
Sources: AGENTS.md:154-159, src/agents/prometheus/plan-template.ts:74-84
Agent-Executed QA Scenarios
Beyond traditional unit tests, every task generated or executed by the system (e.g., via Prometheus or Hephaestus) must include Agent-Executed QA Scenarios. These scenarios are designed for the AI agent to verify work without human intervention.
The diagram shows the automated verification flow where agents use specific tools to provide evidence for completion.
Sources: src/agents/prometheus/plan-template.ts:98-112, src/agents/hephaestus.ts:316-325
Mandatory Verification Tools
| Tool | Usage | Requirement |
|---|---|---|
lsp_diagnostics | Code Linting/Typing | Must return zero errors on all modified files. |
Playwright | Frontend/UI | Required for any browser-related tasks. |
Git Master | Version Control | Must be used for all commit and rebase operations. |
Bash | Build/Test | Build command must exit with code 0. |
Sources: src/agents/hephaestus.ts:316-335, sisyphus-prompt.md:28-35
Contribution Protocols
Language Policy
English is the only language for all project communications, including PR titles, commit messages, and code comments. Non-English contributions are automatically rejected to ensure global accessibility.
Sources: CONTRIBUTING.md:16-25, AGENTS.md:104-114
Pull Request Process
The project uses a specific branch hierarchy. Contributors must never target the master branch directly.
All feature work must target the dev branch. The master branch is reserved for production releases handled by GitHub Actions.
Sources: AGENTS.md:65-75, CONTRIBUTING.md:133-145
Prohibited Anti-Patterns
- Type Suppression: Never use
as any,@ts-ignore, or@ts-expect-error. - Direct Publishing: Never run
bun publishlocally; deployment is managed via GitHub Actionsworkflow_dispatch. - Shotgun Debugging: Agents and contributors are forbidden from making random changes hoping to fix issues; root causes must be identified.
- Unverified Reports: Agents must never self-report completion without providing evidence (logs, screenshots, or test results).
Sources: AGENTS.md:175-178, src/agents/hephaestus.ts:340-344, sisyphus-prompt.md:387-393
Conclusion
Contributing to Oh My OpenCode requires a commitment to automated excellence. By combining strict TDD practices with agent-led verification and a centralized Bun-based workflow, the project ensures that its complex orchestration logic remains stable and maintainable across all 11 specialized agent models.