opencode-swarm 7.57.0 → 7.58.1

package/.opencode/skills/brainstorm/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: brainstorm
+description: >
+  Full execution protocol for MODE: BRAINSTORM -- structured discovery dialogue, approach selection, spec drafting, QA gate selection, and transition handling.
+---
+
+# Brainstorm Protocol
+
+This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.
+
+### MODE: BRAINSTORM
+Activates when: user invokes `/swarm brainstorm`; OR uses phrases like "brainstorm", "let's think through", "think this through with me", "workshop this idea"; OR the problem is fuzzy/exploratory and the user has not yet written (or does not want to directly dictate) a spec.
+
+Use BRAINSTORM when requirements need to be drawn out through structured dialogue before committing to a spec. Use SPECIFY when the user has already articulated clear requirements.
+
+MODE: BRAINSTORM runs seven phases in strict order. Do not skip phases. Do not collapse phases. Each phase has a clear entry signal and a clear exit signal.
+
+**Phase 1: CONTEXT SCAN (architect + explorer, parallel).**
+- Delegate to `the active swarm's explorer agent` to map the relevant portion of the codebase. Scope the explorer to the area most likely affected by the topic.
+- In parallel, read any existing `.swarm/spec.md`, `.swarm/plan.md`, and `.swarm/knowledge.jsonl` entries that are relevant.
+- Run CODEBASE REALITY CHECK on any claims the user made in their topic statement. Surface discrepancies before moving forward.
+- Exit when you have a confident map of: (a) existing code and patterns, (b) relevant prior decisions, (c) what is actually unknown.
+
+**Phase 2: DIALOGUE (architect ↔ user).**
+- Ask EXACTLY ONE focused question per message. Wait for the user's answer before asking the next.
+- Prioritize questions that materially change scope, risk, or architecture. Skip questions whose answers can be responsibly defaulted — use informed defaults and say so.
+- Hard cap: no more than SIX questions total in this phase. Stop sooner if uncertainty has collapsed.
+- Each question must include: (a) why it matters, (b) the default you will use if the user doesn't answer, (c) the concrete options you're weighing.
+- Exit when: remaining ambiguity can be defaulted safely, or the user explicitly says "good, move on" or equivalent.
+
+**Phase 3: APPROACHES (architect, optionally with SME).**
+- Produce 2-4 distinct candidate approaches. Each approach must have: name, one-paragraph summary, primary tradeoff it optimizes for, primary risk it accepts, rough integration surface.
+- For high-risk domains (auth, payments, data mutation, public API, schema, concurrency, security-sensitive parsing), delegate to `the active swarm's sme agent` for domain research first.
+- Present the approaches to the user and recommend one with explicit reasoning. The user can pick, modify, or reject.
+- Exit when the user has chosen (or agreed to your recommended) approach.
+
+**Phase 4: DESIGN SECTIONS (architect).**
+- Draft the structural design of the chosen approach. Include: data model / entities, major components / modules, integration points, invariants, failure modes, rollout considerations.
+- Keep design technology-aware (this is NOT the spec — BRAINSTORM design notes can reference frameworks and patterns).
+- Name the design sections explicitly so you can reference them in the spec without duplicating.
+- Exit with a design outline the user can skim in under two minutes.
+
+**Phase 5: SPEC WRITE + SELF-REVIEW (architect + reviewer).**
+    - Generate `.swarm/spec.md` following the same SPEC CONTENT RULES that MODE: SPECIFY uses: WHAT/WHY only, no tech stack, no implementation details, FR-### / SC-### numbering, Given/When/Then scenarios, `[NEEDS CLARIFICATION]` markers only for items that survive the clarification funnel: inventory all material uncertainties without numeric cap → classify each (self_resolved/critic_resolved/research_needed/user_decision/deferred_nonblocking) — **overconfidence guard:** if the default is not directly supported by user request, spec, or recorded context, classify as `user_decision` rather than `self_resolved` → consult critic_sounding_board — critic responds per SoundingBoardVerdict: UNNECESSARY→DROP, RESOLVE→RESOLVE, REPHRASE→REPHRASE, APPROVED→ASK_USER — **always-surface protection:** always-surface categories must not receive UNNECESSARY/DROP; override to APPROVED/ASK_USER → record resolved items as assumptions → surface only survivors as markers with decision packet format (grouped by category, recommended defaults, blocking vs optional markers).
+- Cross-reference design sections by name where relevant context helps (but keep HOW out of the spec).
+- Delegate to `the active swarm's reviewer agent` for an independent review of the draft spec. Reviewer must flag: requirements that encode HOW, untestable requirements, missing edge cases, silent assumptions.
+- Apply reviewer feedback. If reviewer rejects, iterate once and re-review. After two rounds, surface remaining disagreements to the user.
+- Write the final spec to `.swarm/spec.md`.
+- Exit when reviewer signs off (or user explicitly accepts remaining disagreements).
+
+**Phase 6: QA GATE SELECTION (architect, dialogue only).**
+Now ask the user which QA gates to enable for this plan -- do not select on their behalf.
+
+Present the eleven gates with their defaults (DEFAULT_QA_GATES) as a single user-facing question. Offer the user a one-shot choice: accept defaults, or customize. The eleven gates are:
+- reviewer (default: ON) -- code review of coder output
+- test_engineer (default: ON) -- test verification of coder output
+- sme_enabled (default: ON) -- SME consultation during planning/clarification
+- critic_pre_plan (default: ON) -- critic review before plan finalization
+- sast_enabled (default: ON) -- static security scanning
+- council_mode (default: OFF) -- multi-member council gate (recommended for high-impact architecture, public APIs, schema/data mutation, security-sensitive code)
+- hallucination_guard (default: OFF) -- when enabled, mandatory per-phase API/signature/claim/citation verification via critic_hallucination_verifier at PHASE-WRAP; phase_complete will REJECT phase completion unless .swarm/evidence/{phase}/hallucination-guard.json exists with an APPROVED verdict (recommended for claim-heavy or research-heavy work)
+- mutation_test (default: OFF) -- when enabled, runs mutation testing on source files touched this phase via generate_mutants + mutation_test + write_mutation_evidence at PHASE-WRAP; FAIL verdict blocks phase_complete; WARN is non-blocking (recommended for projects with coverage gaps or safety-critical code)
+- council_general_review (default: OFF) -- when enabled, MODE: SPECIFY runs convene_general_council on the draft spec before the critic-gate; the architect runs a curated web_search pass, dispatches council_generalist / council_skeptic / council_domain_expert in parallel with a shared RESEARCH CONTEXT block, deliberates on disagreements, and synthesizes the result directly into the spec (recommended for novel architecture, unclear best practices, or high-risk design decisions). Requires council.general.enabled: true and a configured search API key in the resolved config: global ~/.config/opencode/opencode-swarm.json, then project .opencode/opencode-swarm.json overrides.
+- drift_check (default: ON) -- when enabled, mandatory per-phase drift verification via critic_drift_verifier at PHASE-WRAP; compares implemented changes against spec.md intent; hard-blocks phase_complete when spec.md exists and drift evidence is missing or REJECTED; advisory-only when no spec.md exists (recommended for all projects with a specification)
+- final_council (default: OFF) - when enabled, after all phases complete the architect dispatches the same five phase-council members (`critic`, `reviewer`, `sme`, `test_engineer`, `explorer`) at project scope, collects `CouncilMemberVerdict` objects, and calls `write_final_council_evidence`. This is not General Council mode and does not require `council.general.enabled`.
+
+One question, one message, defaults pre-stated. Wait for the user's answer.
+
+If the user answered the gate question, immediately follow up with ONE more question: "How many coders should run in parallel? (default: 1, range: 1-4)" -- if the user says a number > 1, also write a `## Pending Parallelization Config` section to `.swarm/context.md` alongside the gate selection:
+```
+## Pending Parallelization Config
+- parallelization_enabled: true
+- max_concurrent_tasks: <user's number>
+- council_parallel: false
+- locked: true
+- recorded_at: <ISO timestamp>
+```
+If the user accepts the default (1), skip writing this section entirely -- serial execution is the default and needs no config.
+
+After asking the parallelization question (regardless of whether the user chose serial or parallel), immediately follow up with ONE more question: "Commit frequency for completed tasks? (default: phase-level only; optional per-task checkpoint commit after each task completion)".
+
+If the user chooses per-task commits, write this section to `.swarm/context.md`:
+```
+## Task Completion Commit Policy
+- commit_after_each_completed_task: true
+- recorded_at: <ISO timestamp>
+```
+If the user keeps the default phase-level behavior, do not write this section.
+
+<!-- BEHAVIORAL_GUIDANCE_START -->
+GATE SELECTION IS MANDATORY — these thoughts are WRONG and must be ignored:
+  ✗ "I'll use the defaults — they're probably fine"
+    → WRONG: defaults are not the user's decision. The user must be asked every time.
+  ✗ "The user didn't mention gates, so defaults are fine"
+    → WRONG: silence is not consent. The gate dialogue is not optional.
+  ✗ "I'll handle it in MODE: PLAN after the spec is done"
+    → WRONG: ## Pending QA Gate Selection must exist in context.md BEFORE save_plan is called.
+      save_plan will reject with QA_GATE_SELECTION_REQUIRED if this section is absent.
+  ✗ "This feature is simple — gates are obvious"
+    → WRONG: complexity does not exempt this step. Gate selection is mandatory for ALL plans.
+  ✗ "I already know which gates are right for this project"
+    → WRONG: the architect does not configure gates. The user configures gates. Always ask.
+  ✗ "council_general_review is off by default, I don't need to mention it"
+    → WRONG: every gate is presented with its default stated. The user opts in or accepts the default explicitly.
+
+MANDATORY PAUSE: Do NOT write the spec summary (step 7). Do NOT suggest next steps.
+You are BLOCKED until ALL THREE of these conditions are met:
+  (1) The gate selection question has been presented to the user in a single message
+  (2) The user has responded (accept defaults OR customized list)
+  (3) The elected gates have been written to .swarm/context.md under "## Pending QA Gate Selection"
+<!-- BEHAVIORAL_GUIDANCE_END -->
+
+Do NOT call `set_qa_gates` yet — `plan.json` does not exist at this point. Once the user answers, write the elected gates to `.swarm/context.md` under a new section:
+```
+## Pending QA Gate Selection
+- reviewer: <true|false>
+- test_engineer: <true|false>
+- sme_enabled: <true|false>
+- critic_pre_plan: <true|false>
+- sast_enabled: <true|false>
+- council_mode: <true|false>
+- hallucination_guard: <true|false>
+- mutation_test: <true|false>
+- council_general_review: <true|false>
+- drift_check: <true|false>
+- final_council: <true|false>
+- recorded_at: <ISO timestamp>
+```
+MODE: PLAN applies these after `save_plan` succeeds via `set_qa_gates`.
+- Exit with the elected gates recorded in `.swarm/context.md` (NOT yet persisted to plan.json).
+
+**Phase 7: TRANSITION.**
+- Summarize: (a) chosen approach, (b) design sections produced, (c) spec written, (d) QA gates selected, (e) remaining `[NEEDS CLARIFICATION]` markers.
+- Offer the user two next steps: `PLAN` (go to MODE: PLAN and write plan.md) or `CLARIFY-SPEC` (resolve remaining markers first).
+- Do NOT proceed to PLAN or CLARIFY-SPEC automatically — wait for user direction.
+
+BRAINSTORM RULES:
+- No skipping phases. Each phase's exit condition must be met before moving on.
+- One question per message in DIALOGUE — never batch.
+- Always offer an informed default for every question.
+- The spec produced in Phase 5 must still satisfy the SPEC CONTENT RULES (no tech stack, no implementation details).
+- QA gates elected in Phase 6 are persisted during MODE: PLAN after `save_plan` succeeds and are ratchet-tighter from that point — once persisted you cannot undo them later in the session.

package/.opencode/skills/clarify/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: clarify
+description: >
+  Full execution protocol for MODE: CLARIFY -- structured clarification funnel with critic review before surfacing user decisions.
+---
+
+# Clarify Protocol
+
+This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.
+
+### MODE: CLARIFY
+Ambiguous request → Run the clarification funnel
+Clear request → MODE: DISCOVER
+
+### Clarification Funnel
+
+Before surfacing any clarification question to the user, the architect MUST run this four-stage funnel. The goal is to limit unnecessary user interruption, not planning completeness.
+
+#### Stage 1: Inventory All Material Uncertainties
+
+Identify ALL uncertainties that could affect:
+- Scope boundaries
+- User-visible behavior
+- Destructive behavior or data loss
+- Security/privacy posture
+- Backward compatibility
+- Migrations or rollout strategy
+- Cost/performance tradeoffs
+- Operational complexity
+- QA gate selection or enforcement strictness
+- Architecture choice among materially different paths
+- Dependency or platform assumptions
+
+There is NO hard cap on the internal inventory. Record every material uncertainty found.
+
+#### Stage 2: Classify Each Uncertainty
+
+Classify each item as exactly one of:
+- `self_resolved`: answered from the user request, spec, plan, codebase reality check, `.swarm/context.md`, repo conventions, or an informed default. **If the default is not directly supported by user request, spec, or recorded context, classify as `user_decision` rather than `self_resolved`.**
+- `critic_resolved`: sent to Critic Sounding Board and resolved by the critic.
+- `research_needed`: needs SME/explorer/domain lookup before user escalation.
+- `user_decision`: only the user can decide because it affects product scope, risk tolerance, policy, budget, UX, rollout, or destructive behavior.
+- `deferred_nonblocking`: useful follow-up detail that does not block a correct initial plan and can be explicitly recorded as an assumption or follow-up.
+
+#### Stage 3: Consult Critic Sounding Board
+
+Before asking the user any clarification question, the architect MUST consult `critic_sounding_board` with the candidate question set and context.
+
+For each item classified as `research_needed` or `user_decision` in Stage 2, send it to the critic. The critic responds with a verdict from `SoundingBoardVerdict` (see `src/agents/critic.ts`). The mapping between critic verdicts and funnel actions is:
+
+| Critic Verdict (SoundingBoardVerdict) | Funnel Action | Meaning |
+|---|---|---|
+| `UNNECESSARY` | DROP | Item is unnecessary or answerable from existing context |
+| `RESOLVE` | RESOLVE | Critic supplies the answer or recommended default |
+| `REPHRASE` | REPHRASE | Question is valid but should be clearer, narrower, or grouped |
+| `APPROVED` | ASK_USER | User decision is genuinely required |
+
+**Hard constraint:** Items in the Always-Surface Categories list (below) MUST NOT receive `UNNECESSARY`/`DROP` from the critic — only `REPHRASE` or `APPROVED`/`ASK_USER` are allowed. If the critic attempts to `UNNECESSARY`/`DROP` an always-surface item, override to `APPROVED`/`ASK_USER`.
+
+**Overconfidence guard:** If the critic attempts to self-resolve an item by supplying an answer (verdict `RESOLVE`) but the underlying default is not directly supported by user request, spec, or recorded context, the architect MUST classify the item as `user_decision` rather than `self_resolved`. Unsupported defaults must not be silently accepted.
+
+Update classifications based on critic response:
+- `UNNECESSARY`/`DROP` → reclassify as `self_resolved` and record the reason.
+- `RESOLVE` → reclassify as `critic_resolved` and record the answer as an assumption.
+- `REPHRASE` → update the question wording and keep as candidate.
+- `APPROVED`/`ASK_USER` → confirm as `user_decision`.
+
+Record all resolved items as explicit assumptions before proceeding.
+
+#### Stage 4: Surface User Decision Packet
+
+If any items remain classified as `user_decision` after Stage 3, present them as a structured decision packet — NOT as an arbitrary subset.
+
+The packet MUST include for each decision:
+- Category grouping (scope, security, compatibility, performance, UX, rollout, QA policy)
+- Why the decision matters
+- Recommended default when safe
+- Options being weighed
+- Impact of accepting the default
+- Blocking vs optional marker
+
+The architect MAY ask questions one at a time in interactive mode, but MUST preserve and report the full unresolved list. The architect MUST NOT drop unresolved decisions because of a session question cap.
+
+### Always-Surface Categories
+
+The critic may improve wording or confirm prior context, but these categories MUST be surfaced to the user unless already explicitly answered by the user or by recorded context:
+- Scope boundaries: what is in or out
+- Data loss or destructive behavior
+- Security/privacy risk tolerance
+- Backward compatibility or migration policy
+- Breaking changes to existing APIs, contracts, or interfaces
+- New dependency additions or version changes
+- Deprecation decisions for existing features or APIs
+- Cross-platform impact (Windows/macOS/Linux differences)
+- Cost/performance tradeoffs
+- User-visible behavior and UX choices
+- Release/rollout strategy
+- Optional QA gates or stricter enforcement modes
+- Any choice that changes whether the work is advisory vs hard-blocking
+
+### Assumptions Recording
+
+All items resolved in Stages 2-3 (self_resolved, critic_resolved, deferred_nonblocking) MUST be recorded as explicit assumptions in the spec, plan, or `.swarm/context.md`. Silently dropping resolved uncertainties is a protocol violation — every uncertainty that entered the funnel must have a recorded outcome.

package/.opencode/skills/clarify-spec/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: clarify-spec
+description: >
+  Full execution protocol for MODE: CLARIFY-SPEC -- resolving spec clarification markers and maintaining spec/planning alignment.
+---
+
+# Clarify Spec Protocol
+
+This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.
+
+### MODE: CLARIFY-SPEC
+Activates when: `.swarm/spec.md` exists AND contains `[NEEDS CLARIFICATION]` markers; OR user says "clarify", "refine spec", "review spec", or "/swarm clarify" is invoked; OR architect transitions from MODE: SPECIFY with open markers.
+
+CONSTRAINT: CLARIFY-SPEC must NEVER create a spec. If `.swarm/spec.md` does not exist, tell the user: "No spec found. Use `/swarm specify` to generate one first." and stop.
+
+1. Read `.swarm/spec.md` (read current spec FIRST before making any changes).
+2. Scan for ambiguities beyond explicit `[NEEDS CLARIFICATION]` markers:
+   - Vague adjectives ("fast", "secure", "user-friendly") without measurable targets
+   - Requirements that overlap or potentially conflict with each other
+   - Edge cases implied but not explicitly addressed in the spec
+   - Acceptance criteria (SC-###) that are not independently testable
+3. Present all spec modifications using delta format with ## ADDED/MODIFIED/REMOVED Requirements sections:
+   - ## ADDED Requirements: New requirements being added to the spec
+   - ## MODIFIED Requirements: Existing requirements being revised (show old vs new)
+   - ## REMOVED Requirements: Requirements being deleted (show what was removed)
+4. Delegate to `the active swarm's sme agent` for domain research on ambiguous areas before presenting questions.
+5. Present questions to the user ONE AT A TIME (max 8 per session):
+   - Offer 2–4 multiple-choice options for each question
+   - Mark the recommended option with reasoning (e.g., "Recommended: Option 2 because…")
+   - Allow free-form input as an alternative to the options
+5. After each accepted answer:
+   - Immediately update `.swarm/spec.md` with the resolution
+   - Replace the relevant `[NEEDS CLARIFICATION]` marker or vague language with the accepted answer
+   - If the answer invalidates an earlier requirement, update it to remove the contradiction
+6. Stop when: all critical ambiguities are resolved, user says "done" or "stop", or 8 questions have been asked.
+7. Report a ## Clarification Summary: total questions asked, requirements added/modified/removed, remaining open ambiguities (if any), and suggest next step (`PLAN` if spec is clear, or continue clarifying).
+
+CLARIFY-SPEC RULES:
+- FR-ID increment rule: When adding new requirements, find the highest existing FR-ID and increment from there (FR-001 → FR-002). Never reuse or skip FR-IDs.
+- One question at a time — never ask multiple questions in the same message.
+- Do not modify any part of the spec that was not affected by the accepted answer.
+- Always write the accepted answer back to spec.md before presenting the next question.
+- Max 8 questions per session — if limit reached, report remaining ambiguities and stop.
+- Do not create or overwrite the spec file — only refine what exists.
+
+### Scoped Funnel Protocol (CLARIFY-SPEC only)
+
+CLARIFY-SPEC handles **already-surfaced** `[NEEDS CLARIFICATION]` markers and spec ambiguities — it does not perform open-ended discovery of new uncertainties. The full four-stage clarification funnel (inventory, classify, consult critic, surface) described in the clarify skill applies to MODE: CLARIFY and MODE: PLAN, not here.
+
+However, before surfacing each marker question to the user, CLARIFY-SPEC MUST:
+
+1. **Consult `critic_sounding_board`** with the candidate marker question and surrounding spec context to check whether the question wording can be improved or the item can be resolved from existing context.
+2. **Apply the overconfidence guard:** If the critic supplies a `RESOLVE` verdict with a default answer, but that default is not directly supported by user request, spec, or recorded context, classify the item as `user_decision` rather than `self_resolved`.
+3. **Apply always-surface protection:** If the marker belongs to an always-surface category (scope boundaries, destructive behavior, security/privacy, backward compatibility, breaking API changes, new dependencies, deprecations, cross-platform impact, cost/performance tradeoffs, user-visible UX, rollout strategy, QA gates), the item MUST NOT receive `UNNECESSARY`/`DROP` from the critic — override to `APPROVED`/`ASK_USER`.
+
+Critic verdict mapping (see `src/agents/critic.ts` `SoundingBoardVerdict`): `UNNECESSARY`→DROP, `RESOLVE`→RESOLVE, `REPHRASE`→REPHRASE, `APPROVED`→ASK_USER.
+
+This scoped protocol is lighter than the full funnel because CLARIFY-SPEC starts from known markers rather than open uncertainty inventory, but it still protects against overconfident self-resolution and premature dropping of important questions.

package/.opencode/skills/codebase-review-swarm/INSTALL.md

@@ -0,0 +1,75 @@
+# Installation
+
+The canonical portable package is the folder `codebase-review-swarm/` containing `SKILL.md`, `references/`, `assets/`, `scripts/`, and optional Codex metadata in `agents/openai.yaml`.
+
+## Repository-local install
+
+### Codex and OpenCode
+
+From the opencode-swarm repository root into another repository:
+
+```sh
+TARGET_REPO=/path/to/repo
+mkdir -p "$TARGET_REPO/.agents/skills"
+cp -R .opencode/skills/codebase-review-swarm "$TARGET_REPO/.agents/skills/"
+```
+
+Then invoke explicitly as `$codebase-review-swarm` or ask for a comprehensive codebase review. Codex scans `.agents/skills` from the current directory to repo root. OpenCode also supports `.agents/skills`.
+
+### opencode-swarm repository layout
+
+Within the opencode-swarm plugin repository, keep the full canonical protocol in:
+
+```sh
+.opencode/skills/codebase-review-swarm/
+```
+
+Keep `.claude/skills/codebase-review-swarm/` and `.agents/skills/codebase-review-swarm/` as thin adapters that point to the canonical OpenCode skill.
+
+### Claude Code
+
+From the repository root:
+
+```sh
+TARGET_REPO=/path/to/repo
+mkdir -p "$TARGET_REPO/.claude/skills"
+cp -R .opencode/skills/codebase-review-swarm "$TARGET_REPO/.claude/skills/"
+```
+
+Claude Code discovers project skills under `.claude/skills/<skill-name>/SKILL.md`.
+
+### OpenCode alternative for other repositories
+
+```sh
+TARGET_REPO=/path/to/repo
+mkdir -p "$TARGET_REPO/.opencode/skills"
+cp -R .opencode/skills/codebase-review-swarm "$TARGET_REPO/.opencode/skills/"
+```
+
+## User-global install
+
+```sh
+mkdir -p ~/.agents/skills
+cp -R .opencode/skills/codebase-review-swarm ~/.agents/skills/
+```
+
+For Claude-only global use:
+
+```sh
+mkdir -p ~/.claude/skills
+cp -R .opencode/skills/codebase-review-swarm ~/.claude/skills/
+```
+
+## Suggested repository instruction
+
+Add this to `AGENTS.md`, `CLAUDE.md`, or equivalent repository agent instructions:
+
+```markdown
+When asked for a comprehensive codebase review, QA audit, security/supply-chain review, AI-slop review, accessibility review, performance/observability review, or enhancement catalog, invoke `$codebase-review-swarm`. Run Phase 0 inventory first, stop for review-mode selection unless the user already selected tracks, and do not modify source files.
+```
+
+## Validation
+
+```sh
+python3 .opencode/skills/codebase-review-swarm/scripts/validate-skill-package.py .opencode/skills/codebase-review-swarm
+```

package/.opencode/skills/codebase-review-swarm/README.md

@@ -0,0 +1,44 @@
+# Codebase Review Swarm Skill v8.2
+
+Portable Agent Skill for OpenCode, Codex, and Claude Code. It converts the v7 codebase-review swarm prompt into a progressive-disclosure skill package with a short routing-focused `SKILL.md`, detailed protocol references, parseable schemas, report template, optional Codex metadata, and deterministic helper scripts.
+
+## Contents
+
+```text
+codebase-review-swarm/
+  SKILL.md
+  INSTALL.md
+  README.md
+  agents/
+    openai.yaml
+  assets/
+    jsonl-schemas.md
+    review-report-template.md
+  references/
+    compatibility-and-research-notes.md
+    full-v7-source-prompt.md
+    review-protocol-v8.2.md
+  scripts/
+    init-review-run.py
+    validate-skill-package.py
+```
+
+## Design summary
+
+- Canonical opencode-swarm repo path: `.opencode/skills/codebase-review-swarm/`.
+- Claude path: `.claude/skills/codebase-review-swarm/` as a thin adapter to the canonical OpenCode skill.
+- Codex path: `.agents/skills/codebase-review-swarm/` as a thin adapter with `agents/openai.yaml`.
+- Portable user install paths may still use `.agents/skills/`, `.opencode/skills/`, or `.claude/skills/` depending on host.
+- Frontmatter is intentionally portable: required `name` and `description`, plus harmless metadata.
+- Long instructions are split into references/assets to preserve routing quality and context budget.
+- Focused track selections expand depth inside the selected domain; multi-track/all-track selections add waves rather than sacrificing per-track quality.
+- The full v7 prompt is preserved verbatim for detailed track checklists.
+- Standards are current as of 2026-06-08: ASVS 5.0.0, OWASP LLM Top 10 2025, SLSA v1.2, WCAG 2.2 AA, OpenTelemetry.
+
+## Primary command
+
+```text
+$codebase-review-swarm
+```
+
+Begin at repository root. The skill runs Phase 0 inventory, stops for review mode selection unless preselected, then performs selected exhaustive tracks with coverage closure, review-depth planning, non-diluting multi-track execution, and critic validation.

package/.opencode/skills/codebase-review-swarm/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: codebase-review-swarm
+description: Run 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. Performs Phase 0 inventory, selected exhaustive tracks with non-diluting depth, coverage closure, reviewer/critic validation, and writes .swarm/review-v8 artifacts without modifying source files.
+license: MIT
+metadata:
+  version: "8.2.0"
+  generated: "2026-06-08"
+  source_prompt: "codebase-review-swarm-prompt-v7"
+  artifact_root: ".swarm/review-v8/runs/<run_id>/"
+---
+
+# Codebase Review Swarm
+
+Use this skill when the user asks for a deep codebase audit, full QA review, security review, supply-chain review, AI-slop/provenance review, UI/accessibility review, performance/observability review, or enhancement catalog. Do not use it for ordinary bug fixing, feature implementation, or quick PR comments unless the user explicitly wants the full evidence-gated review workflow.
+
+You are the Architect/orchestrator. You produce a verified review report and supporting artifacts. You do not modify source files. Source edits, automatic fixes, dependency upgrades, and remediation patches are out of scope unless the user starts a separate implementation task after the report.
+
+## Load order
+
+Read these files before executing:
+
+1. `references/review-protocol-v8.2.md` - authoritative workflow, phases, track contracts, and standards.
+2. `assets/jsonl-schemas.md` - exact parseable block formats for inventory, candidates, validation, critic, and coverage artifacts.
+3. `assets/review-report-template.md` - final `review-report.md` structure.
+4. `references/full-v7-source-prompt.md` - full source prompt and long track checklists; load only when the concise protocol is insufficient for a selected track or output format.
+
+Optional deterministic helpers:
+
+- `scripts/init-review-run.py` creates the `.swarm/review-v8/runs/<run_id>/` artifact tree and warns if `.swarm/` is not ignored.
+- `scripts/validate-skill-package.py` checks the local skill package shape.
+
+## Non-negotiable invariants
+
+1. **No Quote, No Claim.** Every repo-derived factual claim must cite exact relative file path, line or range, verbatim excerpt, and what the excerpt proves.
+2. **Coverage closure.** Every selected-track coverage unit must end `REVIEWED`, `NOT_APPLICABLE`, `SKIPPED_WITH_REASON`, or `BLOCKED`. A final report is forbidden while any selected-track unit is `UNASSIGNED` or `UNREVIEWED`.
+3. **Depth scales with focus and never dilutes with breadth.** Selecting one track concentrates effort into that track: increase coverage granularity, caller/callee tracing, deterministic tool use, runtime validation attempts, test/claim comparison, and critic passes for that domain. Selecting multiple tracks or all tracks does not permit any track to be shallower than it would be in a single-track run; decompose into more passes, smaller batches, or sequential waves instead.
+4. **Candidates are not findings.** Explorer output is candidate evidence only. Reviewer validation filters false positives. Critic validation is mandatory for CRITICAL/HIGH defects and all report-eligible enhancements. Final whole-report critic must PASS before completion.
+5. **Deterministic before judgment.** Mechanically check imports, manifests, lockfiles, package existence, route wiring, CLI scripts, framework signatures, public exports, and test assertions before subjective reasoning. Run safe SAST, dependency scanners, linters, typecheckers, tests, or MCP/security scanners when available and relevant.
+6. **Disproof required.** Every candidate records the alternative interpretation that would make it wrong and where that interpretation was checked. CRITICAL/HIGH candidates lacking a clear disproof model must be downgraded before validation.
+7. **Runtime validation when runtime matters.** Static review is insufficient for routing, auth/session state, async ordering, database state, feature flags, bundling, rendering, LLM/tool execution, MCP permissions, or cross-platform shell behavior. Run the smallest safe validation or mark the item `UNVERIFIED`.
+8. **Separate defects from enhancements.** Defects are shipped behavior that is wrong, unsafe, broken, misleading, or materially incomplete. Enhancements improve working code without implying breakage. Do not duplicate the same root issue in both forms.
+9. **Evidence-based AI slop only.** Never report "looks generated" findings. Quote concrete repeated patterns, phantom APIs/dependencies, confident stubs, stale API usage, excessive churn, mock-only tests, or unmodified scaffold defaults.
+10. **Quality over speed.** Parallelize only independent scopes. If quality and concurrency conflict, quality wins.
+11. **No fixed budget compression.** Never fit the review to an assumed time/token budget by sampling selected scopes, increasing batch size, reducing validation, or omitting low-salience files. When scope is large, split work; when splitting is insufficient, mark precise coverage units `BLOCKED` or `SKIPPED_WITH_REASON` rather than producing a weaker report.
+
+## Current standards to apply
+
+Use these baselines unless repository policy explicitly requires stricter or older controls:
+
+- OWASP ASVS 5.0.0 for web application control review.
+- OWASP Top 10 for LLM Applications 2025 for LLM, agent, RAG, and model-output security.
+- SLSA v1.2 and OpenSSF Scorecard checks for build/release provenance and repository hygiene.
+- WCAG 2.2 AA for UI accessibility.
+- OpenTelemetry semantic model: traces, metrics, logs, baggage/context propagation where applicable.
+
+## Execution outline
+
+1. Run Phase 0 inventory in the strict dependency order from `references/review-protocol-v8.2.md` and write the source-of-truth packet.
+2. Stop after Phase 0 and ask the user to choose review mode unless the original request already selected tracks and explicitly authorized continuing.
+3. Build coverage units for the selected tracks and write a `review-depth-plan.md` that proves each selected track receives full-depth treatment.
+4. Generate candidates by selected track only, using exact scope assignments and quoted evidence. Focused selections must expand depth within selected tracks; multi-track selections must add waves, not dilute depth.
+5. Validate candidates in small local reasoning batches.
+6. Run inline critic for CRITICAL/HIGH defects, enhancement critic for all kept enhancements, and final whole-report critic.
+7. Write `review-report.md` only after coverage closure and final critic PASS.
+8. Final response reports only the run path, selected tracks, counts summary, highest-risk items, coverage limitations, and confirmation that no source files were modified.

package/.opencode/skills/codebase-review-swarm/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Codebase Review Swarm"
+  short_description: "Evidence-gated full-repo audit with Phase 0 inventory, non-diluting selected-track depth, coverage closure, reviewer/critic validation, and .swarm artifacts."
+  default_prompt: "Use $codebase-review-swarm to run a quote-grounded codebase review. Begin at repository root with Phase 0 inventory."
+policy:
+  allow_implicit_invocation: false