build-consensus
About
This skill enables distributed agreement without a central authority using mechanisms like threshold voting and quorum sensing. It covers proposal generation, advocacy dynamics, and deadlock resolution for scenarios where a group must decide without a designated leader. Developers can use it when centralized decision-making is a bottleneck or when designing automated systems like distributed databases or multi-agent AI that require consensus.
Quick Install
Claude Code
Recommendednpx skills add pjt222/agent-almanac -a claude-code/plugin add https://github.com/pjt222/agent-almanacgit clone https://github.com/pjt222/agent-almanac.git ~/.claude/skills/build-consensusCopy and paste this command in Claude Code to install this skill
Documentation
Build Consensus
Collective agreement across distributed agents w/o central authority — scout advocacy, threshold quorum sensing, commit dynamics from honeybee swarm decisions.
Use When
- Group must decide between many options w/o designated leader
- Centralized decision = bottleneck or single point of failure
- Stakeholders diff info/perspectives must be integrated
- Past decisions suffered groupthink (premature conv) or analysis paralysis (no conv)
- Designing auto systems needing consensus (distributed DBs, multi-agent AI)
- Complements
coordinate-swarmwhen coordination needs explicit collective decisions
In
- Required: Decision (binary, select from N, param set)
- Required: Participating agents (team, services, voters)
- Optional: Known options w/ prelim quality assessments
- Optional: Urgency (time budget)
- Optional: Acceptable err rate (group occasionally pick 2nd-best?)
- Optional: Current failure mode (groupthink, deadlock, flip-flop)
Do
Step 1: Generate Proposals — Independent Scouting
Decision space explored before advocacy begins.
- Assign scouts to independently explore:
- Each scout evaluates w/o knowing others' findings
- Independent eval prevents early herding → popular-but-mediocre
- Scout count: min 3 per serious option (reliability)
- Scouts produce structured assessments:
- Option ID
- Quality score (normalized 0-100 or categorical: poor/fair/good/excellent)
- Key strengths + risks
- Confidence (how thoroughly evaluated?)
- Aggregate reports w/o filter — all above min quality enter advocacy
→ Independently evaluated proposals w/ scores + assessments. No option eliminated by single evaluator; perspective diversity preserved.
If err: Scouts converge on same option w/o independent eval → scouting not truly independent. Rerun w/ explicit info barriers. Too many survive → raise min threshold. Too few → lower or add scouts.
Step 2: Advocacy Dynamics (Waggle Dance)
Scouts advocate preferred options, intensity proportional to quality.
- Each scout advocates top-rated:
- Intensity proportional to quality (better → more vigorous)
- Public — all observe
- Present evidence + quality, not just pref
- Uncommitted observe + evaluate:
- Follow up by inspecting independently
- Own inspection confirms → join advocacy
- Inspection shows lower quality → don't join
- Cross-inspection dynamics:
- Weaker advocates naturally lose followers as agents verify
- Stronger gain through confirmed quality
- Self-correcting: exaggerated advocacy fails verification
Advocacy Dynamics:
┌─────────────────────────────────────────────────────────┐
│ Scout A advocates Option 1 (quality 85) ──→ ◉◉◉◉◉ │
│ Scout B advocates Option 2 (quality 70) ──→ ◉◉◉ │
│ Scout C advocates Option 3 (quality 45) ──→ ◉ │
│ │
│ Uncommitted agents inspect: │
│ Agent D inspects Option 1 → confirms → joins ◉◉◉◉◉◉ │
│ Agent E inspects Option 2 → confirms → joins ◉◉◉◉ │
│ Agent F inspects Option 3 → disagrees → inspects Opt 1│
│ → confirms → joins ◉◉◉◉◉◉◉│
│ │
│ Over time: Option 1 advocacy grows, Option 3 fades │
└─────────────────────────────────────────────────────────┘
→ Advocacy for best option(s) grows as agents verify. Weaker fades. Group converges naturally w/o any agent dictating.
If err: No convergence (2 options neck-and-neck) → genuinely equivalent, proceed to quorum w/ either or tiebreaker. Converges too fast on mediocre → increase eval independence (more scouts, stricter barriers) + mandatory cross-inspection.
Step 3: Quorum Threshold + Commit
Commit threshold → collective action.
- Set quorum:
- Simple: 50% + 1
- Important: 66-75%
- Critical/irreversible: 80%+
- Rule: higher stakes → higher quorum → slower but more reliable
- Monitor commit accumulation:
- Track # committed per option over time
- Transparent (all see state)
- No commit withdrawal mid-cycle (prevents oscillation)
- Quorum reached:
- Winning option = collective decision
- Losers ack (no rogue agents)
- Implement immediately — delay erodes commit
→ Clear quorum moment, enough agents independently committed. Legitimate because emerged from independent eval, not authority.
If err: Quorum never reached in time → escalate Step 4. Reached but agents unhappy → advocacy too short, committed w/o adequate eval. Wrong consensus (discovered after) → independent scouting insufficient, increase scout diversity + eval thoroughness next cycle.
Step 4: Deadlock Resolution
Break gridlock when natural process stalls.
- Diagnose type:
- Genuine tie: Equally good → flip coin; delay cost exceeds picking "wrong" equal
- Info deficit: Can't eval well → invest more scouting before re-advocacy
- Faction: Entrenched subgroups refuse to cross-inspect → mandatory rotation, advocates inspect opposing
- Option proliferation: Too many fragment commit → eliminate bottom 50%, re-advocate
- Apply resolution:
- Tie: random or merge if compatible
- Deficit: time-boxed scouting extension
- Faction: forced cross-inspection round
- Proliferation: ranked elimination tournament
- After res, reset quorum clock, re-run Step 3
→ Deadlock resolved via intervention. Visible + accepted as fair process even if indiv preferred diff outcome.
If err: Deadlocks recur on same decision → framing wrong. Step back: decomposable into smaller independent decisions? Scope reduction? "Try both and see"? Sometimes best consensus = "time-boxed experiment".
Step 5: Consensus Quality
Eval whether process produced good decision, not just decision.
- Post-decision:
- Winning option independently verified by ≥N agents?
- Speed appropriate (not too fast/groupthink, not too slow/paralysis)?
- Process surfaced info missed by single decider?
- Agents committed to impl or merely compliant?
- Health metrics:
- Time to quorum: decreasing = learning; increasing = complexity/dysfunction
- Scout-to-commit ratio: scouting per commit. High = difficult or low trust
- Post-decision regret rate: how often group wishes diff?
- Feed learnings back:
- Adjust thresholds based on importance + past accuracy
- Adjust scout count based on complexity
- Adjust time budgets based on historical time-to-quorum
→ Feedback loop improves quality over time. Group learns to scout better, advocate honestly, commit confidently.
If err: Poor metrics (high regret, slow) → audit for structural fails: insufficient scout diversity, advocacy w/o verification, thresholds too low. Rebuild failing stage vs overhauling whole.
Check
- Proposals via independent scouting (no herding)
- Advocacy proportional to assessed quality
- Uncommitted verified advocated options
- Quorum appropriate for importance
- Quorum reached + implemented promptly
- Deadlock mechanism available (even if unused)
- Post-decision quality assessment done
Traps
- Skip independent scouting: Jump to advocacy → groupthink. Consensus quality = eval quality
- Equal advocacy, unequal options: Same advocacy regardless of quality → random selection. Must be proportional
- Commit withdrawal: Un-commit → oscillation. Once committed in cycle, stay until resolves
- Consensus = unanimity confusion: Consensus = sufficient agreement, not total. Waiting 100% = permanent deadlock
- Ignore losing side: Losers have info group needs. Concerns should inform impl even if don't block
→
coordinate-swarm— foundational coordination framework supporting signal-based consensusdefend-colony— collective defense often needs rapid consensus under threatscale-colony— consensus mechanisms adapt when group size changes significantlydissolve-form— morphic controlled dismantling; consensus before dissolution criticalplan-sprint— sprint planning involves team consensus on scopeconduct-retrospective— retrospectives = consensus-building about process improvementbuild-coherence— AI self-app variant; maps bee democracy to single-agent multi-path reasoning
GitHub Repository
Related Skills
content-collections
MetaThis skill provides a production-tested setup for Content Collections, a TypeScript-first tool that transforms Markdown/MDX files into type-safe data collections with Zod validation. Use it when building blogs, documentation sites, or content-heavy Vite + React applications to ensure type safety and automatic content validation. It covers everything from Vite plugin configuration and MDX compilation to deployment optimization and schema validation.
polymarket
MetaThis skill enables developers to build applications with the Polymarket prediction markets platform, including API integration for trading and market data. It also provides real-time data streaming via WebSocket to monitor live trades and market activity. Use it for implementing trading strategies or creating tools that process live market updates.
creating-opencode-plugins
MetaThis skill helps developers create OpenCode plugins that hook into 25+ event types like commands, files, and LSP operations. It provides the plugin structure, event API specifications, and implementation patterns for JavaScript/TypeScript modules. Use it when you need to intercept, monitor, or extend the OpenCode AI assistant's lifecycle with custom event-driven logic.
sglang
MetaSGLang is a high-performance LLM serving framework that specializes in fast, structured generation for JSON, regex, and agentic workflows using its RadixAttention prefix caching. It delivers significantly faster inference, especially for tasks with repeated prefixes, making it ideal for complex, structured outputs and multi-turn conversations. Choose SGLang over alternatives like vLLM when you need constrained decoding or are building applications with extensive prefix sharing.
