Engineering Invariants and Contributing
Relevant source files
The following files were used as context for generating this wiki page:
The engineering culture of the opencode-swarm project is defined by a rigorous set of non-negotiable invariants designed to ensure the stability, portability, and safety of the swarm orchestration plugin across various host environments. These invariants serve as a root engineering contract for all contributors—whether human or automated agents—to prevent regressions in complex cross-platform scenarios including Windows, macOS, and Linux.
This document outlines the core technical constraints, the tiered Quality Assurance (QA) pipeline, and the mandatory pull request workflows required to maintain the project's integrity. For specific implementation details regarding agent roles, refer to AGENTS.md.
Core Engineering Invariants
The project operates under a "Prime Directive": preserving runtime contracts that keep the plugin loadable, portable, bounded, recoverable, and safe. Sources: AGENTS.md:31-33
1. Architectural and Runtime Safety
The plugin must remain compatible with Node-ESM and OpenCode v1 plugin shapes. This includes a total ban on top-level bun: imports and a requirement that the main bundle (dist/index.js) remains loadable by standard Node.js. Sources: AGENTS.md:52-54
| Invariant | Critical Requirement | Rationale |
|---|---|---|
| Plugin Init | Must complete in bounded time; use withTimeout for environmental work. | OpenCode hosts silently drop plugins that take too long to resolve. |
| Subprocesses | Array-form spawn only; explicit cwd; mandatory timeout. | Prevents zombie processes and platform-specific shell interpretation bugs. |
| Containment | Runtime state MUST live only under the .swarm/ directory. | Prevents repository pollution and ensures state portability. |
| Plan Durability | .swarm/plan-ledger.jsonl is the authoritative ledger. | Derived files (plan.md, plan.json) are projections and can be overwritten. |
Sources: AGENTS.md:40-105
2. Platform Portability (Windows First-Class)
Windows is treated as a first-class citizen. Code must handle .cmd extensions for binaries, case-sensitivity differences (Linux vs. others), and path separators. Hardcoding / or \ is strictly prohibited; developers must use path.join(). Sources: AGENTS.md:83-88, src/agents/coder.ts:140-142
Pull Request Workflow
Every contribution follows a strict end-to-end pipeline to ensure that versioning, changelogs, and quality gates are applied consistently.
The PR Lifecycle
The project uses release-please to automate versioning based on Conventional Commits. Manual edits to package.json versions or CHANGELOG.md are forbidden as they cause release pipeline conflicts. Sources: contributing.md:95-103
A descriptive Markdown fragment must be added to docs/releases/pending/<slug>.md for every user-visible change. Sources: contributing.md:38-41
Commit Message Standards
Commit messages and PR titles must follow the Conventional Commits format: <type>(<scope>): <description>. Sources: contributing.md:120-125
| Type | semver Bump | Purpose |
|---|---|---|
feat | minor | New features or capabilities. |
fix | patch | Bug fixes or correctness improvements. |
perf | patch | Performance enhancements. |
docs / chore | none | Documentation or maintenance; does not trigger release. |
Sources: contributing.md:131-143
Automated Quality Assurance (QA) Gates
The project employs a tiered QA gate system enforced by both runtime hooks and CI checks. These gates ensure that no code is merged without verification of syntax, logic, and security.
Tiered Testing Pipeline
Tests are executed in five tiers, starting from quality checks and moving to build verification. All tests must use bun:test. Sources: contributing.md:44-71
Sources: contributing.md:44-71
Architect and Coder Constraints
The Architect agent is the orchestrator and is forbidden from writing code directly. All implementation must be delegated to the Coder agent, which operates under a "Write Blocked Protocol." If a tool returns "WRITE BLOCKED," the Coder must stop and request the Architect to explicitly declare_scope for the target files. Sources: src/agents/architect.ts:167-175, src/agents/coder.ts:175-185
Mandatory Invariant Audit
Every Pull Request must include an "Invariant Audit" section in the description. Developers must provide concrete evidence (test output, command logs) for every invariant touched by their changes. Sources: AGENTS.md:164-183
## Invariant audit
- 1 (plugin init): not touched
- 2 (runtime portability): touched — verified with `node --input-type=module -e "await import('./dist/index.js')"`
- 3 (subprocesses): touched — checked `spawn` calls for mandatory timeouts
...
Sources: AGENTS.md:164-183
Summary
The opencode-swarm repository prioritizes runtime safety and platform portability over development speed. By enforcing 12 non-negotiable engineering invariants and a tiered QA pipeline, the project ensures that the swarm orchestration engine remains stable across diverse environments. Adherence to the Conventional Commit standard and the mandatory invariant audit ensures that every change is traceable, verified, and safely deployable.