# debatewiki opencode plugin - Skills Specification

## Overview

This document specifies the skills provided by the debatewiki opencode plugin following the agentskills.io standard. Each skill is designed to be used independently or as part of a larger workflow.

## Skills Directory Structure

```
skills/
├── consensus-skill.js          # Main JavaScript skill implementation
├── consensus-skill.py          # Python skill implementation
├── consensus-skill.md          # Skill documentation
├── consensus-skill.yaml        # Skill configuration (agentskills.io standard)
├── README.md                   # Skills overview documentation
├── USAGE_GUIDE.md              # Detailed usage instructions
└── SKILLS_REGISTRY.yaml        # Complete skills registry
```

## Skill Specifications

### 1. consensus-voting

**Name**: `consensus-voting`
**Version**: `1.0.0`
**Category**: `analysis`
**Tags**: `["consensus", "voting", "decision-making", "multi-agent"]`

#### Description
Calculates voting consensus among multiple agents with a configurable threshold. Determines if a sufficient proportion of agents agree on a proposition.

#### Execution
- **Type**: `script`
- **Language**: `javascript`
- **Path**: `./consensus-skill.js`
- **Function**: `calculateVotingConsensus`
- **Timeout**: `30000ms`

#### Parameters
- `messages` (required): Array of messages from agents containing votes
  - `agent_name` (string): Name of the agent providing the message
  - `content` (string): Content of the message, should contain vote information
- `threshold` (optional, default: 0.7): Minimum agreement ratio required for consensus (0-1)

#### Input Format
```json
{
  "messages": [
    {
      "agent_name": "string",
      "content": "string"
    }
  ],
  "threshold": "number (0-1)"
}
```

#### Output Format
```json
{
  "achieved": "boolean",
  "agreement_ratio": "number (0-1)",
  "summary": "string",
  "votes": "object"
}
```

#### Example Usage
```bash
node skills/consensus-skill.js calculateVotingConsensus '{"messages": [{"agent_name": "proponent", "content": "vote: yes"}, {"agent_name": "opponent", "content": "vote: no"}, {"agent_name": "moderator", "content": "vote: yes"}], "threshold": 0.6}'
```

#### Example Output
```json
{
  "achieved": true,
  "agreement_ratio": 0.6666666666666666,
  "summary": "Voting Consensus (threshold: 60%)\n- Total votes: 3\n- Yes votes: 2\n- Agreement: 66.7%\n- Result: ACHIEVED\n\nVotes:\n- Yes (2): proponent, moderator\n- No (1): opponent\n",
  "votes": {
    "proponent": true,
    "opponent": false,
    "moderator": true
  }
}
```

### 2. consensus-deliberation

**Name**: `consensus-deliberation`
**Version**: `1.0.0`
**Category**: `analysis`
**Tags**: `["consensus", "deliberation", "multi-round", "multi-agent"]`

#### Description
Calculates deliberation consensus through multi-round discussions. Evaluates convergence of agent positions over time.

#### Execution
- **Type**: `script`
- **Language**: `javascript`
- **Path**: `./consensus-skill.js`
- **Function**: `calculateDeliberationConsensus`
- **Timeout**: `30000ms`

#### Parameters
- `messages` (required): Array of messages from agents across multiple rounds
  - `agent_name` (string): Name of the agent providing the message
  - `content` (string): Content of the message, may contain round and stance information
- `max_rounds` (optional, default: 10): Maximum rounds for deliberation algorithm
- `convergence_threshold` (optional, default: 0.85): Minimum convergence ratio required for consensus (0-1)

#### Input Format
```json
{
  "messages": [
    {
      "agent_name": "string",
      "content": "string"
    }
  ],
  "max_rounds": "number",
  "convergence_threshold": "number (0-1)"
}
```

#### Output Format
```json
{
  "achieved": "boolean",
  "agreement_ratio": "number (0-1)",
  "summary": "string",
  "convergence_history": "array<number>",
  "rounds_count": "number"
}
```

#### Example Usage
```bash
node skills/consensus-skill.js calculateDeliberationConsensus '{"messages": [{"agent_name": "agent1", "content": "round: 1, stance: support"}, {"agent_name": "agent2", "content": "round: 1, stance: oppose"}], "max_rounds": 5, "convergence_threshold": 0.8}'
```

#### Example Output
```json
{
  "achieved": false,
  "agreement_ratio": 0,
  "summary": "Deliberation Consensus\n- Max Rounds: 5\n- Convergence Threshold: 80%\n- Final Convergence: 0.0%\n- Result: NOT ACHIEVED\n\nRound Progress:\n- Round 1: 0.0% convergence\n\nNote: Max rounds reached without convergence.\n",
  "convergence_history": [0],
  "rounds_count": 1
}
```

### 3. extract-votes

**Name**: `extract-votes`
**Version**: `1.0.0`
**Category**: `analysis`
**Tags**: `["votes", "extraction", "parsing", "multi-agent"]`

#### Description
Extracts votes from agent messages. Identifies vote expressions in message content.

#### Execution
- **Type**: `script`
- **Language**: `javascript`
- **Path**: `./consensus-skill.js`
- **Function**: `extractVotes`
- **Timeout**: `10000ms`

#### Parameters
- `messages` (required): Array of messages from agents to extract votes from
  - `agent_name` (string): Name of the agent providing the message
  - `content` (string): Content of the message, may contain vote information

#### Input Format
```json
{
  "messages": [
    {
      "agent_name": "string",
      "content": "string"
    }
  ]
}
```

#### Output Format
```json
{
  "votes": "object"
}
```

#### Example Usage
```bash
node skills/consensus-skill.js extractVotes '{"messages": [{"agent_name": "proponent", "content": "I vote yes on this proposal"}, {"agent_name": "opponent", "content": "My vote is no"}]}'
```

#### Example Output
```json
{
  "proponent": true,
  "opponent": false
}
```

### 4. extract-positions

**Name**: `extract-positions`
**Version**: `1.0.0`
**Category**: `analysis`
**Tags**: `["positions", "stances", "extraction", "parsing", "multi-agent"]`

#### Description
Extracts positions/stances from agent messages. Identifies agent positions in discussions.

#### Execution
- **Type**: `script`
- **Language**: `javascript`
- **Path**: `./consensus-skill.js`
- **Function**: `extractStances`
- **Timeout**: `10000ms`

#### Parameters
- `messages` (required): Array of messages from agents to extract positions from
  - `agent_name` (string): Name of the agent providing the message
  - `content` (string): Content of the message, may contain position information

#### Input Format
```json
{
  "messages": [
    {
      "agent_name": "string",
      "content": "string"
    }
  ]
}
```

#### Output Format
```json
{
  "stances": "object"
}
```

#### Example Usage
```bash
node skills/consensus-skill.js extractStances '{"messages": [{"agent_name": "agent1", "content": "My stance is support for this idea"}, {"agent_name": "agent2", "content": "I oppose this proposal"}]}'
```

#### Example Output
```json
{
  "agent1": "support",
  "agent2": "oppose"
}
```

## Progressive Disclosure of Information

### Basic Usage
For simple use cases, users can call the skills directly with minimal parameters.

### Advanced Usage
For complex scenarios, users can utilize all available parameters to customize behavior.

### Full Configuration
For integration with other systems, users can reference the complete YAML configuration in `consensus-skill.yaml`.

## When to Call Each Skill

### consensus-voting
- **Trigger Condition**: When you need to determine if a voting threshold has been met
- **Context**: Multi-agent decision making, polling, agreement verification
- **Frequency**: As needed when voting consensus is required

### consensus-deliberation
- **Trigger Condition**: When you need to evaluate convergence over multiple rounds of discussion
- **Context**: Multi-stage negotiations, iterative decision making, position tracking
- **Frequency**: During multi-round deliberation processes

### extract-votes
- **Trigger Condition**: When you need to parse vote information from messages
- **Context**: Pre-processing for consensus calculation, vote auditing
- **Frequency**: Before running consensus algorithms

### extract-positions
- **Trigger Condition**: When you need to identify agent positions in discussions
- **Context**: Position tracking, stance analysis, opinion monitoring
- **Frequency**: During ongoing discussions to monitor agent positions

## Integration Points

These skills can be integrated with OpenCode through:

1. **MCP (Model Control Protocol)**: As external tools accessible to agents
2. **Custom Commands**: Through slash commands in OpenCode
3. **Hooks**: As part of automated workflows
4. **Background Tasks**: For continuous processing

## Error Handling

Each skill implements proper error handling:
- Invalid inputs return descriptive error messages
- Missing required parameters are reported with expected schema
- Processing errors include context information
- Skills fail gracefully without affecting the main system

## Performance Characteristics

- Lightweight execution with minimal resource usage
- Fast response times (typically < 100ms for small inputs)
- Scalable with input size
- Thread-safe execution

## Security Considerations

- All inputs are validated before processing
- No external dependencies required for core functionality
- Outputs are sanitized to prevent injection
- Runs in isolated execution environment