opencode-swarm

Guidelines and non-negotiable engineering invariants for modifying opencode-swarm. Load before architecture, plugin initialization, subprocess, tool registration, plan durability, .swarm storage, runtime portability, session/global state, guardrails/retry, chat/system message hooks, or release/cache changes. Authoritative source: AGENTS.md at the repo root and docs/engineering-invariants.md.

Per-task gate dispatch protocol. Documents single-task attribution plus parseable set-dispatch reviewer/test_engineer rows.

Codex adapter for monitoring and fixing CI failures on opencode-swarm PRs. Use when diagnosing failed checks, fixing `package-check` (npm tarball) failures, resolving quality/lint/format errors, fixing macOS cross-platform file I/O failures, or watching a PR until all checks are green.

Codex adapter for running a rigorous, quote-grounded codebase review or security/QA/accessibility/performance/AI-slop/enhancement audit. Use for full-repo or large-subsystem review reports; not for normal implementation.

Mandatory Codex/Copilot publication adapter for opencode-swarm. Use for every GitHub issue assignment that results in code changes, commits, pushes, draft PRs, PR body edits, PR readying, release notes, or CI closeout. Must be loaded before `git push`, `gh pr create`, `gh pr edit`, or `gh pr ready`. Routes to the single canonical source of truth at `.claude/skills/commit-pr/SKILL.md`.

Codex adapter for the opencode-swarm contribution checklist. Use when preparing user-visible changes, release note fragments, local validation, branch hygiene, PR checklist items, or contribution-policy compliance before publishing work.

Codex adapter for opencode-swarm engineering invariants. Use before modifying plugin initialization, subprocesses, runtime portability, .swarm containment, plan durability, test_runner behavior, test-writing patterns, session/global state, guardrails/retry semantics, chat/system hooks, tool registration, release/cache hygiene, or related architecture.

Operational patterns for fork PRs (head repo differs from base repo). Covers GitHub workflow approval after push, force-push protocol, remote naming conventions, stale CI verification, and bot review multi-round awareness. Load when working with fork PRs, cross-repo contributions, or workflow approval issues.

Codex adapter for opencode-swarm destructive-command guardrail changes. Use before modifying src/hooks/guardrails.ts, checkDestructiveCommand, dcNormalizeCommand, shell-wrapper parsing, .swarm destructive-command blocking, or guardrails unit/adversarial tests.

Evidence-first issue and bug investigation for Codex. Use when asked to trace, investigate, root-cause, plan, fix, close, or prepare a PR for a GitHub issue, bug report, regression, failing test, or confusing runtime behavior. Drives intake, reproduction, localization, critic review, implementation, validation, invariant-aware PR closure, and no-gap evidence capture.

Codex adapter for migrating opencode-swarm tests away from Bun mock.module leakage toward _internals dependency-injection seams. Use when touching tests with mock.module, adding test seams, fixing Bun mock isolation failures, or updating source modules for injectable internals.

Codex adapter for addressing pull request review feedback in opencode-swarm. Use when the user asks to fix PR review comments, requested changes, reviewer findings, CI-review notes, or a pasted review summary with low false-positive tolerance.

Codex adapter for independent QA review of opencode-swarm changes. Use after implementation or debugging when the user asks for a QA sweep, regression check, review pass, quality gate, or confidence check before publishing.

Codex adapter for research-before-planning work. Use when a task depends on current external facts, unfamiliar libraries, APIs, standards, security advisories, release notes, product behavior, or repo behavior that must be verified before planning or implementation.

Codex adapter for safely executing opencode-swarm tests. Use whenever Codex needs to run focused tests, per-file isolation loops, CI-equivalent validation, test-impact checks, or diagnose failing/truncated test output without stalling the session.

Guidelines for safe subprocess calls in opencode-swarm. Load before adding, modifying, or reviewing any file that calls spawn, spawnSync, bunSpawn, or child_process. Covers the six required properties, Windows portability, _internals DI seam pattern, and verification grep.

Codex adapter for end-to-end CI monitoring of an already-reviewed PR in opencode-swarm. Use when the user wants the swarm to monitor a reviewed-and-approved PR's CI, research every failure exhaustively, fix end-to-end, iterate until green (max 5 cycles), then merge. Composes ci-fix-monitor for fix recipes.

Codex adapter for complex implementation work using the canonical opencode-swarm implementation workflow. Use for multi-file features, bug fixes, refactors, risky code changes, or tasks that benefit from exploration, scoped planning, implementation, review, and validation.

Codex adapter for closing known PR feedback in opencode-swarm. Use when asked to address pasted review feedback, GitHub review comments or threads, requested changes, CI/check failures, merge conflicts, stale PR branches, or follow-up work that must verify and close all known PR issues.

Codex adapter for deep PR review in opencode-swarm. Use when the user wants a broad, read-only PR review with low false-positive tolerance. The canonical protocol lives in .opencode and owns comment ingestion, CI/conflict/staleness intake, parallel explorer lanes, independent reviewer validation, critic challenge, and the explicit handoff into swarm-pr-feedback for approved fix work.

Codex adapter for post-PR monitoring in opencode-swarm. Use when subscribing to a pull request after opening it, when asked to watch, babysit, or autofix a PR until merge, or when a <pr-activity> wake message or [pr-monitor:...] advisory arrives for a subscribed PR and its events need triage and action.

Codex adapter for enabling a higher-rigor swarm-like workflow in the current Codex thread. Use when the user asks for swarm mode, maximum quality, parallel investigation, extra review rigor, or a swarm-style approach without necessarily invoking the OpenCode Swarm plugin.

Codex adapter for deep technical-debt and CI-stability audits. Use when asked to find test theater, flaky tests, missing or mis-scoped tests, brittle CI/toolchain behavior, structural debt blocking green PRs, or a remediation order for opencode-swarm.

Protocol for splitting test files that exceed the FR-006 500-line hard limit. Covers describe-block extraction, shared helper management, pure-function extraction, mock isolation verification, and cascading-split detection. Load when a test file approaches or exceeds 500 lines.

Codex adapter for disabling a previously requested swarm-like workflow in the current thread. Use when the user says unswarm, stop swarm mode, return to normal mode, simplify the workflow, or stop using extra review/delegation rigor.

Codex adapter for opencode-swarm test authoring rules. Use before creating or modifying any test file in this repository, especially bun:test files, mock.module usage, _internals seams, temp directories, cross-platform tests, or CI-sensitive test structure.

Full execution protocol for MODE: BRAINSTORM -- structured discovery dialogue, approach selection, spec drafting, QA gate selection, and transition handling.

Full execution protocol for MODE: CLARIFY -- structured clarification funnel with critic review before surfacing user decisions.

Full execution protocol for MODE: CLARIFY-SPEC -- resolving spec clarification markers and maintaining spec/planning alignment.

Claude Code adapter for running a rigorous, quote-grounded codebase review or security/QA/accessibility/performance/AI-slop/enhancement audit. Use for full-repo or large-subsystem review reports; not for normal implementation.

Apply when committing, pushing, opening or updating a PR, writing a pull request, creating release notes, or closing out remote CI. Enforces the opencode-swarm invariant audit, release-note fragment workflow, full validation suite, issue comment requirement, and post-PR lifecycle rules.

Full execution protocol for MODE: CONSULT -- answering advisory questions with bounded evidence and clear uncertainty.

Full execution protocol for MODE: COUNCIL -- General Council research, parallel member dispatch, disagreement handling, and synthesis.

Full execution protocol for MODE: CRITIC-GATE -- plan critic review, revision loops, and hard stop before execution.

Full execution protocol for MODE: DEEP_DIVE — read-only codebase audit with parallel explorer waves, 2 independent reviewers, and sequential critic challenge for HIGH/CRITICAL findings. Loaded on demand by the architect when the deep-dive command emits a [MODE: DEEP_DIVE ...] signal.

Full execution protocol for MODE: DEEP_RESEARCH — orchestrator-worker deep research over external sources: decompose, iterative web_search/web_fetch retrieval, parallel sme synthesis, dual-reviewer claim verification, critic challenge of high-stakes claims, and a cited report. Loaded on demand by the architect when the deep-research command emits a [MODE: DEEP_RESEARCH ...] signal.

Full execution protocol for MODE: DESIGN_DOCS — generate or sync structured, language-agnostic design docs (domain.md, technical-spec.md, behavior-spec.md, reference/) for the project under build, with a stable section-ID registry and a design changelog. Loaded on demand by the architect when the design-docs command emits a [MODE: DESIGN_DOCS ...] signal (issue #1080).

Full execution protocol for MODE: DISCOVER -- read-only repository discovery and governance/context mapping.

Persist plans, scope decisions, evidence, and reviewer/critic verdicts to durable files during long or multi-phase tasks so work survives context compaction, session resumes, and handoffs. Use for swarm-mode tasks, before context grows large, when recording approval gates, and when resuming after compaction or a session restart.

Contract for adding, editing, moving, or removing skills in this repository (.claude/skills, .opencode/skills, .agents/skills, any SKILL.md): mirror classifications in src/config/skill-mirrors.ts, dual-tree byte-identical edits, bun run drift:check, bundling via BUNDLED_PROJECT_SKILLS, frontmatter conventions, and how to write trigger descriptions. Load before touching any SKILL.md file.