Swarm Consensus

---
name: swarm-consensus
description: When 2+ independent perspectives must agree before a risky Yana AI action — dispatching review subagents synchronously via the Task tool, resolving their findings by priority (Safety > Correctness > Performance > Style), and blocking on any Safety-severity finding. Replaces an earlier async message-bus/vote design that was never actually wired into the running system.
origin: yana-ai (rewritten 2026-07-03 — see "What changed" below)
license: Apache-2.0
version: 2.0.0
compatibility: yana-ai >= 0.43.0
---

# /swarm-consensus

## When to Use

- Multiple perspectives must agree before a high-risk action lands — e.g. a write to `core/rules/`, `core/hooks/`, `core/gates/`, or `core/agents/` (see `core/rules/54-bft-consensus-law.md` for the exact trigger paths)
- "Security review should be able to block anything a code change tries to ship"
- Fan-out: one question dispatched to N subagents, findings aggregated

## Do NOT use for

- Single-agent decisions (no second opinion needed)
- Low-stakes read-only tool calls (dispatching a reviewer is overkill)
- Anything needing a persistent, always-on second process — that's not how Task-tool subagents work; see "What changed" below

---

## The real mechanism: synchronous dispatch, not async voting

There is one Claude Code session. When it needs a second opinion, it dispatches a Task-tool subagent, which runs to completion and returns a plain-text report *in the same turn*. There is no separate vote-casting step, no polling for messages, no timeout window — the dispatch either returns a report or it doesn't finish.

```
Main agent identifies a change needs review (per 54-bft-consensus-law.md's
category table: rule changes, enforcement code, agent personas, or
integrity/lock files)
         │
         ▼
Dispatch both required reviewers synchronously, via the Task tool,
scoped to the specific diff — per subagent-policy.md's dispatch template
         │
         ├──→ Reviewer 1 (e.g. security-team/security-auditor.md) reports
         └──→ Reviewer 2 (e.g. architecture-auditor.md or code-auditor.md) reports
         │
         ▼
Main agent applies conflict-resolution.md's priority order across both
reports: Safety > Correctness > Performance > Style
         │
         ├── Any Safety-severity finding? → BLOCK, escalate to human
         │   (conflict-resolution.md Strategy C)
         ├── Correctness finding that breaks an enforced gate/test? → BLOCK
         └── Otherwise → proceed, log a short resolution note
```

## Dispatching reviewers

Use the Task tool directly — this is not a shell command, so there's no `bash swarm-orchestrator.sh request` step. The dispatch prompt follows `subagent-policy.md`'s template: state the task, the scope, and that the subagent must not write/edit/commit — only report.

```
Dispatch (conceptual, not literal shell):
  Agent(security-team/security-auditor.md, scope: "review this diff to
    core/hooks/foo.sh for security issues, read-only, report findings")
  Agent(code-auditor.md, scope: "review this diff to core/hooks/foo.sh
    for correctness/quality, read-only, report findings")

Both run, both return text reports in this turn — no polling, no
"wait for vote" step.
```

## Resolving findings

Apply `conflict-resolution.md`'s existing priority table directly — this skill does not invent a second one:

```
1. Safety (security/data-integrity)   — always wins, always blocks
2. Correctness                         — wins unless a Safety conflict exists
3. Performance                         — after Correctness
4. Style/cleanup                       — lowest priority
```

If two reviewers give conflicting recommendations at the *same* priority level, that's a genuine conflict — escalate to the human per `conflict-resolution.md` Strategy C. Don't average, don't pick the more convenient one, don't silently proceed.

## Fan-out to more than 2 reviewers

For a broader question (not the specific 2-reviewer infra-write case), dispatch as many subagents as the question needs, in parallel (multiple `Agent` calls in the same response), and collect all reports before synthesizing — this is the same pattern `conflict-resolution.md` already documents for general subagent dispatch, not a special "swarm" mode.

```
Rule: dispatch independent reviewers in parallel when their scopes don't
overlap (see conflict-resolution.md's "Phòng ngừa conflict từ đầu" —
scoping subagents narrowly from the start is cheaper than resolving
conflicts after the fact)
Rule: a subagent that never returns (crashes, times out) is a finding in
itself — don't silently treat missing output as "no objection"
```

---

## Anti-Fake-Pass Checklist

```
❌ Proceeding with an infra write after a Safety-severity finding, because
   a second reviewer's report looked clean
❌ Treating "the subagent didn't report anything" as approval — a missing
   or crashed report is not a clean bill of health
❌ Dispatching only one reviewer when 54-bft-consensus-law.md's category
   table calls for two
❌ Skipping dispatch because the change "is small" — the trigger-path
   match in 54-bft-consensus-law.md is the gate, not the diff size
❌ A subagent attempting Write/Edit/commit/push during "review" — banned
   categorically by subagent-policy.md, not something this skill needs
   to re-check
```

## What changed (2026-07-03)

This skill used to describe an async architecture: `swarm-orchestrator.sh request/vote/tally` over a file-based message bus, a TypeScript `SwarmCoordinator` client polling `agent-message-bus.sh recv` for RESPONSE messages, veto broadcasts, and split-brain locking for concurrent leader election. None of that was ever wired into the automatic pipeline — `swarm-orchestrator.sh` remains real, working, optional manual tooling (see `core/rules/54-bft-consensus-law.md`) for a human coordinating separate concurrent Claude Code sessions, but it was never how a single session's own review-before-write actually happens. This rewrite describes the mechanism that's actually running.