| name | contributing |
| description | End-to-end PR workflow for opencode-swarm. Covers branch setup, conventional commits, mandatory release notes, 5-tier CI checks, and PR submission format. Load this skill before creating branches, commits, or pull requests.
|
Contributing to opencode-swarm
1. Branch Setup
git checkout main && git pull origin main
git checkout -b <type>/<short-description>
bun install --frozen-lockfile
Branch naming: <type>/<short-description> (e.g. feat/add-retry-backoff, fix/plan-sync-race).
2. Commit Message Format (Conventional Commits)
Every commit MUST follow: <type>(<optional scope>): <description>
Rules:
- Description lowercase, no trailing period
- Scope optional but encouraged
| Type | Changelog section | Version bump |
|---|
feat | Features | minor |
fix | Bug Fixes | patch |
perf | Performance | patch |
revert | Reverts | patch |
docs | Documentation | none |
chore | — | none |
refactor | — | none |
test | — | none |
ci | — | none |
build | — | none |
Breaking changes: add BREAKING CHANGE: <description> footer or ! suffix on type (e.g. feat!:). Triggers major bump.
Valid examples:
feat(architect): add retry backoff to SME delegationfix(circuit-breaker): prevent race condition on concurrent invocationsrefactor(swarm): extract phase orchestration into dedicated module
Invalid (rejected by CI):
WIP, fix stuff, Update README, feat: Add feature. (trailing period), Feat: (uppercase)
3. Release Notes (MANDATORY — every PR, no exceptions)
- Read current version:
cat .release-please-manifest.json
- Compute next version based on commit types (feat = minor, fix/perf = patch)
- Create file:
docs/releases/v{NEXT_VERSION}.md
Include:
- What changed (grouped by theme)
- Why (bug report, feature request, hardening)
- Migration steps (if any)
- Breaking changes (if any)
- Known caveats
Even one-line changes need release notes explaining why it matters.
4. Run All Checks Locally (5 tiers, all must pass)
bun run typecheck
bunx biome ci .
bun test tests/unit --timeout 120000
bun test tests/integration ./test --timeout 120000
bun test tests/security --timeout 120000
bun test tests/adversarial --timeout 120000
bun run build
bun test tests/smoke --timeout 120000
If a pre-existing unrelated failure exists, note it in the PR description but do NOT skip other tiers.
5. Push and Open PR
git push -u origin <branch-name>
PR title MUST be a valid conventional commit: <type>(<scope>): <description>
PR body template:
## Summary
- Bullet 1
- Bullet 2
## Test plan
- [ ] Tier 1 quality checks pass
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Security/adversarial tests pass
- [ ] Build + smoke tests pass
6. Do NOT Manually Edit These Files
release-please manages these automatically:
package.json version fieldCHANGELOG.md.release-please-manifest.json
Never replace the release PR body, create tags/releases manually, or edit these files.
7. CI Checks (all must be green)
| Check | Validates |
|---|
quality | TypeScript compiles, Biome lint + format clean |
unit (Ubuntu, macOS, Windows) | Unit tests pass cross-platform |
integration (Ubuntu) | Integration tests pass |
security (Ubuntu) | Security & adversarial tests pass |
smoke (Ubuntu, macOS, Windows) | Package builds & smoke tests pass |
pr-standards | PR title is valid conventional commit |
check-duplicates | PR title not duplicate of open PR |
8. GitHub Actions SHA Pinning
All uses: in .github/workflows/ must be pinned to full 40-char SHA with version comment:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
Find SHA: gh api repos/{owner}/{repo}/git/ref/tags/{tag} --jq '.object.sha'
PR Checklist
