Swarm Consensus

/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.