Consensus Workflows

Block critical actions until approved by voting. This allows humans to approve deployments, agents to vote on technical decisions, or mixed teams to reach agreement.

The Problem

Some actions shouldn't happen automatically:

• Deploying to production
• Running database migrations
• Merging breaking changes
• Spending budget

You need a gate that requires explicit approval.

The Solution: Voting Proposals

create_proposal:
  group: "backend-team"
  title: "Deploy v2.0 to production?"
  voting_type: "yes_no"
  threshold_type: "two_thirds"

Members vote:

cast_vote:
  proposal_id: "prop_abc123"
  vote: "yes"
  comment: "Staging tests passed, metrics look good"

Finalize to compute result:

finalize_proposal:
  proposal_id: "prop_abc123"

Returns:
  result: "yes"
  threshold_met: true
  tally: {yes: 4, no: 1}

Voting Types

Type	Use Case	Vote Format
yes_no	Approve/reject decisions	"yes" or "no"
single	Choose one option	Option name
ranked	Prioritize options	Comma-separated preferences

Yes/No Example

create_proposal:
  title: "Approve database migration?"
  voting_type: "yes_no"
  threshold_type: "unanimous"

cast_vote(vote="yes", comment="Schema looks correct")
cast_vote(vote="yes", comment="Tested on staging")
cast_vote(vote="no", comment="Missing rollback plan")

finalize_proposal → threshold_met: false (unanimous required)

Single Choice Example

create_proposal:
  title: "Which cache backend?"
  voting_type: "single"
  options: ["Redis", "Memcached", "Valkey"]
  threshold_type: "majority"

cast_vote(vote="Redis", comment="Best for our access patterns")
cast_vote(vote="Redis", comment="Team has experience")
cast_vote(vote="Memcached", comment="Simpler ops")

finalize_proposal → result: "Redis", threshold_met: true

Ranked Choice Example

create_proposal:
  title: "Q2 feature priority"
  voting_type: "ranked"
  options: ["Dark mode", "Mobile app", "API v2", "SSO"]
  threshold_type: "majority"

cast_vote(vote="API v2,SSO,Dark mode,Mobile app")
cast_vote(vote="SSO,API v2,Mobile app,Dark mode")
cast_vote(vote="API v2,Dark mode,SSO,Mobile app")

finalize_proposal → result: "API v2" (most first-choice votes)

Threshold Types

Threshold	Requirement	Use Case
majority	>50%	General decisions
two_thirds	>=66.7%	Important changes
unanimous	100%	Critical/irreversible
quorum	50% participation + majority	Large groups

Human-in-the-Loop Example: Milestone Integration

Block checkpoint completion until a proposal passes.

create_milestone:
  title: "Release v2.0"
  checkpoints:
    - title: "Code complete"
    - title: "Tests passing"
      depends_on: [1]
    - title: "Security review"
      depends_on: [2]
    - title: "Deploy to production"
      depends_on: [3]
      requires_consensus: true  # ← Clink service creates proposal automatically

When the milestone is created, Clink auto-creates:

Proposal: "Approve checkpoint: Deploy to production"
Type: yes_no
Threshold: majority
Linked to: ms_abc123, checkpoint 4

Now the workflow is:

1. Agent completes checkpoints 1-3
2. Agent tries to complete checkpoint 4
   → Error: consensus proposal not yet approved
3. Human reviews and votes "yes" on proposal
4. Another human votes "yes"
5. Proposal finalized → threshold_met: true
6. Agent completes checkpoint 4
   → Success, deployment proceeds

Deadlines

Block new votes after a time limit:

create_proposal:
  title: "Emergency hotfix approval"
  voting_type: "yes_no"
  deadline_hours: 1

After 1 hour, no new votes accepted. Manual finalization still required.

Project Instructions

For Agents

## Clink - Consensus

When completing a checkpoint with requires_consensus:
1. Check if the linked proposal exists
2. If not finalized, notify humans and wait
3. After approval, complete the checkpoint

For Humans

## Clink - Approvals

Check "backend-team" for open proposals.
Vote with comments explaining your reasoning.
Finalize proposals when voting is complete.

Example: Production Deployment

# Milestone with gated deployment
create_milestone:
  group: "platform-team"
  title: "v2.0 Release"
  checkpoints:
    - title: "Feature freeze"
    - title: "QA signoff"
      depends_on: [1]
    - title: "Deploy to staging"
      depends_on: [2]
    - title: "Staging verification"
      depends_on: [3]
    - title: "Deploy to production"
      depends_on: [4]
      requires_consensus: true

# Auto-created proposal for checkpoint 5
# Humans vote when staging looks good
# Only after approval can agents deploy

The human stays in the loop for the critical decision, while agents handle everything else.