Build System & Platform Packages
Relevant source files
The following files were used as context for generating this wiki page:
The Build System and Platform Packages module manages the lifecycle of the oh-my-opencode tool, from project initialization and requirement gathering to cross-platform binary distribution. It employs a multi-package architecture to support diverse operating systems and architectures, ensuring that environment-specific binaries are delivered efficiently via NPM.
The system utilizes specialized agents like Prometheus for strategic planning and Metis for gap analysis to verify build requirements before execution. The distribution layer relies on a structured release process that synchronizes versions across the main package and several platform-specific satellite packages.
Sources: script/publish.ts, src/agents/prometheus/identity-constraints.ts:1-20
Multi-Platform Distribution Architecture
The project is distributed as a main package (oh-my-opencode) that utilizes optionalDependencies to pull in platform-specific binaries. This architecture allows users to install a single package while receiving only the binary relevant to their specific system.
Supported Platforms and Architectures
The build system targets the following seven platform/architecture combinations:
| Platform | Architecture | Package Name Suffix |
|---|---|---|
| Darwin (macOS) | arm64 | darwin-arm64 |
| Darwin (macOS) | x64 | darwin-x64 |
| Linux | x64 | linux-x64 |
| Linux | arm64 | linux-arm64 |
| Linux (musl) | x64 | linux-x64-musl |
| Linux (musl) | arm64 | linux-arm64-musl |
| Windows | x64 | windows-x64 |
Sources: script/publish.ts:13-21, packages/darwin-arm64/package.json:2
Dependency and Version Synchronization
The publish.ts script ensures that all platform packages and the main package stay in version lockstep. When a new version is released, the script performs the following synchronization:
- Updates the version field in the main
package.json. - Iterates through all
PLATFORM_PACKAGESand updates their individualpackage.jsonfiles. - Updates the
optionalDependenciesblock in the main package to point to the new version of each platform package.
Sources: script/publish.ts:50-77
The Release and Publishing Pipeline
The publishing process is automated through a sequence of version bumping, changelog generation, and batched NPM uploads.
Versioning and Logic
The system supports standard Semantic Versioning (SemVer) with additional logic for pre-releases.
The diagram shows the logical flow of the release pipeline from version detection to final GitHub release creation.
Sources: script/publish.ts:25-50, script/publish.ts:211-255
Batched Publishing Strategy
To prevent OIDC (OpenID Connect) token expiration during CI/CD runs, the platform packages are published in batches of two. This prevents the sequential overhead of NPM publishing from exceeding the lifespan of the authentication token.
Sources: script/publish.ts:216-228
Project Initialization and Metadata Generation
The system includes built-in commands like /init-deep to generate hierarchical project knowledge bases (AGENTS.md). This process involves complex scoring of the directory structure to determine where documentation is warranted.
Scoring Matrix for Documentation
| Factor | Weight | Source |
|---|---|---|
| File count | 3x | Bash analysis |
| Reference centrality | 3x | LSP analysis |
| Symbol density | 2x | LSP analysis |
| Export count | 2x | LSP analysis |
| Module boundary | 2x | index.ts or __init__.py |
Sources: src/features/builtin-commands/templates/init-deep.ts:143-152
Execution Workflow
The initialization process uses TodoWrite to register phases for user visibility and recovery.
The sequence diagram illustrates the parallel discovery and generation of project metadata files.
Sources: src/features/builtin-commands/templates/init-deep.ts:28-36, src/features/builtin-commands/templates/init-deep.ts:182-205
Build Planning and Verification
The build system relies on the Prometheus planning agent to generate work plans before any modifications are made. This ensures that every task has an associated Agent-Executed QA Scenario.
Verification Requirements
Every planned task must include a verification strategy that requires zero human intervention. The system supports multiple verification tools based on the deliverable type:
| Deliverable Type | Primary Tool | Verification Method |
|---|---|---|
| Frontend/UI | Playwright | DOM assertion and screenshots |
| TUI/CLI | interactive_bash | Run command in tmux and validate stdout |
| API/Backend | Bash (curl) | Request/Response assertion |
| Library/Module | Bash (Bun/Node) | REPL import and function calls |
Sources: src/agents/prometheus/plan-template.ts:100-112
Plan Generation Protocol
Before a plan is generated to .sisyphus/plans/*.md, a mandatory consultation with the Metis agent occurs. Metis reviews the research findings and interview summary to identify gaps, guardrails, and missing acceptance criteria.
Sources: src/agents/prometheus/plan-generation.ts:68-88
Summary
The oh-my-opencode build system is a sophisticated orchestration of platform-specific packaging and agent-driven planning. By utilizing a multi-package satellite architecture and batched publishing, it ensures stable cross-platform distribution. Simultaneously, the integration of specialized planning and review agents (Prometheus, Metis) guarantees that build tasks are verified through automated, agent-executed QA scenarios before implementation.