ct-contribution

Contribution Protocol Skill

You are a contribution protocol agent. Your role is to guide multi-agent consensus workflows through structured decision documentation, conflict detection, and consensus computation using JSON-first formats.

Overview

The Contribution Protocol enables:

• Machine-parseable decisions with confidence scores
• Evidence-based rationale with traceable references
• Automated conflict detection across parallel sessions
• Weighted consensus computation for multi-agent agreement

When to Use

---

Commands

/contribution start <epic-id>

Initialize contribution tracking for an epic.

Usage:

/contribution start T2204
/contribution start T2204 --label rcsd-contrib

Workflow:

1. Verify epic exists and is active
2. Create contribution task under epic
3. Initialize contribution directories
4. Generate contribution ID
5. Return task ID and setup instructions

Parameters:

/contribution submit

Validate and submit the current contribution.

Usage:

/contribution submit
/contribution submit --task T2215

Workflow:

1. Validate contribution JSON against schema
2. Compute checksum for integrity
3. Append entry to CONTRIBUTIONS.jsonl manifest
4. Update task notes with contribution reference
5. Mark contribution status as complete
6. Return submission confirmation

Parameters:

/contribution conflicts [epic-id]

Detect conflicts between contributions for an epic.

Usage:

/contribution conflicts T2204
/contribution conflicts --severity high

Workflow:

1. Load all contributions for epic
2. Group decisions by questionId
3. Compare answers for semantic conflicts
4. Classify conflict type and severity
5. Return conflict report with resolution suggestions

Parameters:

Output:

{
  "epicId": "T2204",
  "conflictCount": 2,
  "conflicts": [
    {
      "questionId": "ARCH-001",
      "severity": "high",
      "positions": [
        {"agentId": "opus-1", "answer": "Position A", "confidence": 0.85},
        {"agentId": "sonnet-1", "answer": "Position B", "confidence": 0.75}
      ]
    }
  ]
}

/contribution status [epic-id]

Show contribution progress and consensus status.

Usage:

/contribution status
/contribution status T2204

Workflow:

1. Query manifest for epic contributions
2. Calculate completion statistics
3. Identify pending conflicts
4. Show consensus progress per question
5. Return status summary

Output:

{
  "epicId": "T2204",
  "totalContributions": 3,
  "complete": 2,
  "partial": 1,
  "blocked": 0,
  "conflictsPending": 2,
  "questionsAnswered": 5,
  "consensusReady": false
}

---

Workflow Guides

Starting a New Contribution

# 1. Verify epic exists
ct show T2204

# 2. Initialize contribution
/contribution start T2204 --label rcsd-contrib

# 3. Create contribution task (if not auto-created)
ct add "Session B: Architecture Analysis" \
  --parent T2204 \
  --labels consensus-source,research \
  --phase core

# 4. Start task
ct start T2215

# 5. Create contribution directory
mkdir -p .cleo/contributions

# 6. Generate contribution ID
source lib/contribution-protocol.sh
CONTRIB_ID=$(contribution_generate_id)
echo "Contribution ID: $CONTRIB_ID"

Writing a Contribution

Create .cleo/contributions/T2215.json:

{
  "$schema": "https://cleo-dev.com/schemas/v2/contribution.schema.json",
  "_meta": {
    "contributionId": "contrib_a1b2c3d4",
    "protocolVersion": "2.0.0",
    "createdAt": "2026-01-26T14:00:00Z",
    "agentId": "opus-1",
    "consensusReady": false
  },
  "sessionId": "session_20260126_140000_abc123",
  "epicId": "T2204",
  "taskId": "T2215",
  "markerLabel": "consensus-source",
  "researchOutputs": [],
  "decisions": [
    {
      "questionId": "ARCH-001",
      "question": "Single file or split file architecture?",
      "answer": "Single JSON file with internal sections",
      "confidence": 0.85,
      "rationale": "Simplifies atomic updates and validation",
      "evidence": [
        {
          "file": "lib/file-ops.sh",
          "section": "atomic_write function",
          "type": "code"
        }
      ]
    }
  ],
  "conflicts": [],
  "status": "draft"
}

Submitting a Contribution

# 1. Validate contribution
/contribution submit --dry-run

# 2. Submit contribution
/contribution submit --task T2215

# 3. Complete task
ct complete T2215

Detecting and Resolving Conflicts

# 1. Check for conflicts
/contribution conflicts T2204

# 2. Review conflict details
jq '.conflicts[] | select(.severity == "high")' .cleo/contributions/CONTRIBUTIONS.jsonl

# 3. Add conflict resolution to contribution
# Edit .cleo/contributions/T2215.json to add:
{
  "conflicts": [
    {
      "questionId": "ARCH-001",
      "conflictId": "conflict_b2c3d4e5",
      "severity": "high",
      "conflictType": "contradiction",
      "thisSession": {
        "position": "Single file architecture",
        "confidence": 0.85,
        "evidence": [...]
      },
      "otherSession": {
        "sessionId": "session_...",
        "position": "Split file architecture",
        "confidence": 0.75,
        "evidence": [...]
      },
      "rationale": "Different priorities: simplicity vs parallelism",
      "resolution": {
        "status": "proposed",
        "resolutionType": "merge",
        "proposal": "Single file with future split option"
      },
      "requiresConsensus": true
    }
  ]
}

# 4. Re-submit with conflict documentation
/contribution submit

---

JSON Format Reference

Authoritative Specification: CONTRIBUTION-FORMAT-SPEC.md

JSON Schema: contribution.schema.json

Decision Object

{
  "questionId": "RCSD-001",
  "question": "The decision question being answered",
  "answer": "Concrete, actionable decision (no hedging)",
  "confidence": 0.85,
  "rationale": "Reasoning with evidence references",
  "evidence": [
    {
      "file": "lib/file-ops.sh",
      "section": "atomic_write function",
      "quote": "temp file -> validate -> backup -> rename",
      "line": 142,
      "type": "code"
    }
  ],
  "uncertaintyNote": "Required if confidence < 0.7",
  "alternatives": [
    {
      "option": "Alternative considered",
      "reason": "Why not chosen"
    }
  ]
}

Confidence Score Semantics

Conflict Severity

---

Library Integration

The skill uses functions from lib/contribution-protocol.sh:

contribution_generate_id()

Generate unique contribution ID.

source lib/contribution-protocol.sh
id=$(contribution_generate_id)
echo "$id"  # contrib_a1b2c3d4

contribution_validate_task()

Validate task against contribution protocol requirements.

source lib/contribution-protocol.sh
result=$(contribution_validate_task "T2215" "T2204" "consensus-source")
echo "$result" | jq '.valid'

contribution_get_injection()

Get injection block for subagent prompts.

source lib/contribution-protocol.sh
injection=$(contribution_get_injection "T2204" ".cleo/agent-outputs/protocol.md")

contribution_create_manifest_entry()

Create a contribution manifest entry.

source lib/contribution-protocol.sh
entry=$(contribution_create_manifest_entry \
  "$CLEO_SESSION" \
  "T2204" \
  "T2215" \
  "opus-1"
)
echo "$entry" | jq '.'

---

Task System Integration

@skills/_shared/task-system-integration.md

Execution Sequence

1. Read task: {{TASK_SHOW_CMD}} {{TASK_ID}}
2. Start task: {{TASK_START_CMD}} {{TASK_ID}} (if not already started)
3. Create/load contribution JSON
4. Document decisions with evidence
5. Check for conflicts with baseline
6. Submit contribution to manifest
7. Complete task: {{TASK_COMPLETE_CMD}} {{TASK_ID}}
8. Return summary message

---

Directory Structure

.cleo/contributions/
├── CONTRIBUTIONS.jsonl      # Append-only manifest
├── T2204.json              # Individual contribution files
├── T2205.json
└── archive/                # Completed epic contributions
    └── T1000/
        ├── CONTRIBUTIONS.jsonl
        └── *.json

---

Manifest Query Patterns

All contributions for an epic

jq -s '[.[] | select(.epicId == "T2204")]' .cleo/contributions/CONTRIBUTIONS.jsonl

Contributions with conflicts

jq -s '[.[] | select(.conflictCount > 0)]' .cleo/contributions/CONTRIBUTIONS.jsonl

Latest contribution for a task

jq -s '[.[] | select(.taskId == "T2215")] | sort_by(.updatedAt) | .[-1]' .cleo/contributions/CONTRIBUTIONS.jsonl

Summary statistics

jq -s '{
  total: length,
  complete: [.[] | select(.status == "complete")] | length,
  partial: [.[] | select(.status == "partial")] | length,
  blocked: [.[] | select(.status == "blocked")] | length,
  totalConflicts: [.[].conflictCount] | add
}' .cleo/contributions/CONTRIBUTIONS.jsonl

---

Completion Checklist

• Epic exists and is active
• Contribution task created with correct parent and label
• Task started
• Contribution JSON created with valid schema
• All decisions include rationale and evidence
• Low confidence decisions include uncertainty notes
• Conflicts with baseline documented
• Contribution submitted to manifest
• Task completed

---

Error Handling

Validation Errors

Recovery Patterns

Checksum mismatch:

# Recompute checksum
jq 'del(._meta.checksum)' .cleo/contributions/T2215.json | sha256sum | cut -c1-16

Missing baseline reference:

# Query for prior contributions
jq -s '[.[] | select(.epicId == "T2204")] | .[0]' .cleo/contributions/CONTRIBUTIONS.jsonl

---

Related Documentation

---

LOOM Stage Binding (T9670)

ct-contribution is bound to LOOM lifecycle stage contribution — the terminal node of the RCASD-IVTR+C pipeline. Use this skill to formalize an Epic's contribution back to canon after its work has converged.

Stage-Transition Contract

The contribution stage is entered from one of two upstream stages depending on the Epic's kind:

research → consensus → architecture_decision → specification → decomposition
                                                                   ↓
                                                            implementation
                                                                   ↓
                                                              validation
                                                                   ↓
                                                                testing  ← (some epics return here)
                                                                   ↓
                                                                release
                                                                   ↓
                                                            contribution  ← (this skill)

The transition is enforced by the playbook runtime defined in ADR-053. The runtime is a deterministic state machine; contribution is its terminal accepting state. Once entered, the Epic is closed in canon.

Acceptance-Gate Evidence

The contribution stage's completion gate is satisfied by emitting at least one of the following ADR-051 evidence atoms, recorded via cleo verify <epicId> --gate contribution --evidence "<atoms>":

Example:

cleo verify T9568 --gate contribution \
  --evidence "decision:D-loom-coverage-001;files:.cleo/contributions/T9568-final.json"
cleo complete T9568

The gate validator (ADR-051 §2.4) rejects an empty evidence string with E_EVIDENCE_MISSING. Stale evidence (modified files after verify but before complete) fails with E_EVIDENCE_STALE.

Open Follow-Up

A future ADR dedicated to the contribution stage's lifecycle gates (covering automated rollup signals from cleo saga rollup, multi-Epic contribution aggregation, and the contribution → "saga close" promotion path) is on the roadmap. File via:

cleo add --kind work --type task --severity P2 \
  --title "T-LOOM-GAP-ADR-CONTRIBUTION: dedicated ADR for contribution stage gates" \
  --relates T9670 \
  --acceptance "ADR drafted under .cleo/adrs/|Cross-referenced from ct-contribution SKILL.md|Validator gate updated"

Until that ADR lands, contribution gates derive from ADR-015 (multi-contributor architecture) and ADR-053 (playbook runtime) — both already referenced in this skill's adrRefs.

---

See also / References

This skill binds to the contribution LOOM lifecycle stage (the final stage of the RCASD-IVTR+C pipeline). Governing ADRs:

• ADR-015 — multi-contributor architecture — defines the multi-contributor consensus mechanics that this stage formalizes for an Epic's downstream return path.
• ADR-053 — playbook runtime — defines the lifecycle state machine; contribution is its terminal node.

LOOM coverage matrix: docs/skills/loom-coverage-matrix.md.