agentic-govbot/SLACK_SETUP.md

# Slack Setup Guide

This guide walks through setting up Govbot for a Slack channel with channel-scoped governance.

## Overview

The Slack adapter enables **channel-scoped governance** where the bot manages a single channel without requiring workspace admin permissions. This makes it ideal for:

- Department or team governance within larger organizations
- Project-specific decision-making channels
- Community spaces within company Slack workspaces
- Testing governance patterns before workspace-wide deployment

## Prerequisites

- Slack workspace (free or paid tier)
- Permission to create Slack apps in the workspace
- Python 3.11+ installed
- Ollama (for local models) or API keys for cloud models

## Capabilities

The Slack adapter provides **16 governance skills** across 5 categories:

### Channel Access Control
- Invite/remove users from the governance channel
- Control who participates in governance

### Channel Management
- Create new channels for working groups
- Archive/unarchive channels
- Set channel topic and purpose
- Rename channels

### User Group Management (Channel "Roles")
- Create user groups as governance roles
- Add/remove users from groups
- Enable/disable groups
- Use groups to tag teams (e.g., @moderators, @council)

### Message Management
- Pin important governance decisions
- Unpin outdated information

### Content Moderation
- Delete messages (requires user:write scope)

## Platform Limitations

**Workspace Admin Only** (not available via channel bot):
- User account management (deactivate, invite new users)
- Workspace settings
- Emoji management
- Billing and plans

**Not Possible via API**:
- Role/permission management (owners, admins)
- Slack Connect (external organizations)
- Enterprise Grid features
- Workflow management

The bot is aware of these limitations and will explain them to users when requested.

## Step 1: Create Slack App

### 1.1 Create App

1. Go to [Slack API Dashboard](https://api.slack.com/apps)
2. Click **"Create New App"**
3. Choose **"From scratch"**
4. Enter:
   - **App Name**: Govbot
   - **Workspace**: Select your workspace
5. Click **"Create App"**

### 1.2 Configure Bot Token Scopes

Navigate to **OAuth & Permissions** → **Scopes** → **Bot Token Scopes**

Add these scopes:

**Essential (Required)**:
- `app_mentions:read` - Receive mentions of the bot
- `chat:write` - Post messages
- `channels:read` - View basic channel info
- `channels:manage` - Manage channels (rename, archive, etc.)
- `channels:history` - Read message history
- `users:read` - Get user information
- `usergroups:read` - View user groups
- `usergroups:write` - Create and manage user groups
- `pins:write` - Pin/unpin messages

**Optional (Enhanced Features)**:
- `channels:write` - Create new channels
- `chat:write.public` - Post to channels bot isn't in
- `im:read` - Read direct messages
- `im:write` - Send direct messages
- `im:history` - Read DM history

**Moderation (If Needed)**:
- `chat:write.customize` - Post as other users (for announcements)
- `users:write` - Modify user accounts (requires admin)

### 1.3 Enable Socket Mode

1. Navigate to **Socket Mode** in the sidebar
2. Click **"Enable Socket Mode"**
3. When prompted, create an app-level token:
   - **Token Name**: govbot-socket
   - **Scopes**: `connections:write`
4. **Save the app token** (starts with `xapp-`) - you'll need this

### 1.4 Enable Events

1. Navigate to **Event Subscriptions**
2. Toggle **"Enable Events"** to On
3. Under **Subscribe to bot events**, add:
   - `app_mention` - When someone mentions the bot
   - `message.im` - Direct messages to the bot
4. Click **"Save Changes"**

### 1.5 Install App to Workspace

1. Navigate to **Install App**
2. Click **"Install to Workspace"**
3. Review permissions and click **"Allow"**
4. **Save the Bot User OAuth Token** (starts with `xoxb-`) - you'll need this

## Step 2: Add Bot to Channel

### 2.1 Create or Select Governance Channel

1. Create a new channel (e.g., `#governance`) or select existing channel
2. Invite the bot to the channel:
   ```
   /invite @Govbot
   ```

### 2.2 Get Channel ID

**Method 1: Via Channel Details**
1. Right-click the channel name
2. Click "View channel details"
3. Scroll to bottom - Channel ID is shown
4. Copy the ID (format: `C0123456789`)

**Method 2: Via URL**
- When viewing the channel, the URL contains the ID:
  `https://app.slack.com/client/T.../C0123456789`
  (The part after the last `/` starting with `C`)

## Step 3: Configure Govbot

### 3.1 Update Configuration File

1. **Copy the example config**:
   ```bash
   cp config/config.example.yaml config/config.yaml
   ```

2. **Edit `config/config.yaml`**:
   ```yaml
   platform:
     type: slack

     slack:
       bot_token: xoxb-your-bot-oauth-token-here
       app_token: xapp-your-app-level-token-here
       channel_id: C0123456789  # Your governance channel ID

   ai:
     # For local models:
     default_model: llama3.2

     # For cloud models:
     # default_model: gpt-4o-mini
     # openai_api_key: your-key-here
     # (or configure with: llm keys set openai)

   governance:
     constitution_path: constitution.md
     db_path: govbot.db
     default_veto_threshold: 0.67
     enable_auto_execution: true
     require_confirmation_for:
       - admin_action
       - moderation

   debug: false
   log_level: INFO
   ```

3. **Test LLM configuration**:
   ```bash
   # Activate virtual environment
   source .venv/bin/activate

   # Test that llm works
   llm "Hello, test message"

   # If using local models, verify Ollama is running
   ollama list
   ```

## Step 4: Initialize Database

```bash
# Activate virtual environment
source .venv/bin/activate

# Create the database
python -c "from src.govbot.db.models import init_db; init_db('govbot.db'); print('Database initialized!')"
```

## Step 5: Test with CLI

Before connecting to Slack, test the bot logic:

```bash
# Run the CLI
python -m src.govbot

# Try these commands:
query What are the rules for proposals?
propose We should have weekly team meetings
processes
exit
```

## Step 6: Install Dependencies

```bash
# Activate virtual environment
source .venv/bin/activate

# Install/update dependencies (includes slack-sdk)
uv pip install -e .
# Or: pip install -e .
```

## Step 7: Run the Bot

```bash
# Activate virtual environment
source .venv/bin/activate

# Start the bot
python -m src.govbot.bot

# You should see:
# INFO - Creating slack platform adapter...
# INFO - Connected to platform successfully
# INFO - Started listening for messages
# INFO - Bot is running. Press Ctrl+C to stop.
```

## Step 8: Test on Slack

### Basic Test

In your governance channel, type:
```
@Govbot help
```

The bot should respond with information about governance commands.

### Create a Proposal

```
@Govbot I propose we add a weekly team retrospective on Fridays
```

The bot should:
- Acknowledge the proposal
- Cite constitutional authority
- Explain voting period and threshold
- Provide voting instructions

### Vote on Proposal

In a thread reply or new message:
```
@Govbot agree
```

### Check Status

```
@Govbot status 1
```

### Test Platform Skills

```
@Govbot what actions can you perform in this channel?
```

### Create a User Group (Role)

```
@Govbot create a user group called "council" for governance leadership
```

## Platform Skills Reference

### Channel Access
- **invite_to_channel**: Add user to governance channel
- **remove_from_channel**: Remove user from channel

### Channel Management
- **create_channel**: Create new channel for working groups
- **archive_channel**: Archive a channel
- **unarchive_channel**: Restore archived channel
- **set_channel_topic**: Update channel topic
- **set_channel_purpose**: Update channel description
- **rename_channel**: Change channel name

### User Groups (Roles)
- **create_user_group**: Create governance role (e.g., @moderators)
- **add_to_user_group**: Add user to role
- **remove_from_user_group**: Remove user from role
- **disable_user_group**: Disable a role

### Message Management
- **pin_message**: Pin important decisions
- **unpin_message**: Unpin messages
- **delete_message**: Remove inappropriate content

## Troubleshooting

### Bot Not Responding

**Check**:
- Bot is invited to the channel (`/invite @Govbot`)
- Bot token (xoxb-...) is correct
- App token (xapp-...) is correct
- Socket Mode is enabled
- Events are subscribed (`app_mention`, `message.im`)
- Bot process is running (check logs)

**Test manually**:
```python
from slack_sdk import WebClient

client = WebClient(token="xoxb-your-token")
response = client.auth_test()
print(f"Bot ID: {response['user_id']}")
print(f"Bot Name: {response['user']}")
```

### Socket Mode Connection Errors

**Check**:
- App token has `connections:write` scope
- No firewall blocking WebSocket connections
- Correct app token (not bot token)

**Enable debug logging**:
```yaml
debug: true
log_level: DEBUG
```

### Permission Errors

**Common issues**:
- Missing bot token scopes (check OAuth & Permissions)
- Bot not invited to channel
- User attempting action they don't have permission for

**Verify scopes**:
```python
from slack_sdk import WebClient

client = WebClient(token="xoxb-your-token")
response = client.auth_test()
print(response)  # Shows which scopes are active
```

### Channel ID Issues

**Symptoms**: Bot responds but actions fail

**Fix**: Verify channel ID
```python
from slack_sdk import WebClient

client = WebClient(token="xoxb-your-token")
response = client.conversations_list()
for channel in response['channels']:
    print(f"{channel['name']}: {channel['id']}")
```

### LLM Errors

**For local models**:
```bash
# Check Ollama is running
ollama list
ollama ps

# Test the model
llm -m llama3.2 "test"
```

**For cloud models**:
```bash
# Check API keys
llm keys list

# Test the model
llm -m gpt-4o-mini "test"
```

### Database Errors

**Reset database**:
```bash
# Backup first!
cp govbot.db govbot.db.backup

# Delete and reinitialize
rm govbot.db
python -c "from src.govbot.db.models import init_db; init_db('govbot.db')"
```

## Security Considerations

**📖 See [SECURITY.md](SECURITY.md) for the complete security guide.**

### Credentials

- **Never commit** `config/config.yaml` to version control (it's in `.gitignore`)
- Store tokens securely
- Use environment variables for production:
  ```bash
  export GOVBOT_PLATFORM__SLACK__BOT_TOKEN="xoxb-..."
  export GOVBOT_PLATFORM__SLACK__APP_TOKEN="xapp-..."
  export GOVBOT_PLATFORM__SLACK__CHANNEL_ID="C0123456789"
  ```
- Rotate tokens periodically via Slack App dashboard
- Use separate apps for development and production

### Access Control

- Limit bot scopes to minimum required
- Don't grant unnecessary permissions
- Monitor bot actions through Slack audit logs
- Review user group membership regularly
- Use channel-specific governance (not workspace-wide)

### Rate Limiting

Slack has rate limits for API calls:
- **Tier 1**: 1 request per second (most methods)
- **Tier 2**: 20 requests per minute (sending messages)
- **Tier 3**: 50 requests per minute (most read operations)

The bot handles rate limits automatically with retries, but be aware for high-volume governance.

## Production Deployment

### Systemd Service

Create `/etc/systemd/system/govbot.service`:

```ini
[Unit]
Description=Govbot Governance Bot (Slack)
After=network.target

[Service]
Type=simple
User=govbot
WorkingDirectory=/home/govbot/agentic-govbot
ExecStart=/usr/bin/python3 -m src.govbot.bot
Restart=always
RestartSec=10

Environment="GOVBOT_PLATFORM__SLACK__BOT_TOKEN=xoxb-..."
Environment="GOVBOT_PLATFORM__SLACK__APP_TOKEN=xapp-..."
Environment="GOVBOT_PLATFORM__SLACK__CHANNEL_ID=C0123456789"
Environment="GOVBOT_LOG_LEVEL=INFO"

[Install]
WantedBy=multi-user.target
```

Enable and start:
```bash
sudo systemctl enable govbot
sudo systemctl start govbot
sudo systemctl status govbot

# View logs
sudo journalctl -u govbot -f
```

### Docker Deployment

Create `Dockerfile`:
```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install -e .

CMD ["python", "-m", "src.govbot.bot"]
```

Build and run:
```bash
docker build -t govbot .
docker run \
  -e GOVBOT_PLATFORM__SLACK__BOT_TOKEN=xoxb-... \
  -e GOVBOT_PLATFORM__SLACK__APP_TOKEN=xapp-... \
  -e GOVBOT_PLATFORM__SLACK__CHANNEL_ID=C0123456789 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/govbot.db:/app/govbot.db \
  govbot
```

### Monitoring

- Monitor Socket Mode connection health
- Track API rate limit usage
- Log all governance actions
- Alert on connection failures
- Monitor database growth
- Track user group membership changes

## Advanced Configuration

### Multiple Channels

To manage multiple governance channels, run multiple bot instances:

```yaml
# config/governance-channel-1.yaml
platform:
  type: slack
  slack:
    bot_token: xoxb-same-token
    app_token: xapp-same-token
    channel_id: C0111111111  # Different channel

governance:
  db_path: govbot-channel1.db  # Separate database
```

### User Groups as Roles

User groups act as channel "roles":

```
# Create governance roles
@Govbot create user group "moderators"
@Govbot create user group "council"
@Govbot create user group "working-group-a"

# Assign members
@Govbot add @alice to moderators
@Govbot add @bob to council

# Use in governance
"Only @moderators can approve reports"
"@council members have veto power"
```

### Custom Constitution

Edit `constitution.md` to define Slack-specific governance:

```markdown
## Slack Governance

### Channel Roles
- **@moderators**: Handle reports and moderation
- **@council**: Make policy decisions
- **Members**: All channel participants

### Channel Management
New channels require:
1. Proposal with clear purpose
2. 2/3 approval from @council
3. Assignment of channel owner

### User Groups
- Creation requires council approval
- Membership changes logged publicly
- Groups reviewed quarterly
```

## Next Steps

- Customize the constitution for your team/department
- Test governance workflows with your team
- Create initial user groups (roles)
- Set up announcement patterns
- Document your Slack governance process
- Gather feedback and iterate

## Getting Help

- Check [README.md](README.md) for general architecture
- Review [PLATFORMS.md](PLATFORMS.md) for platform details
- See [MASTODON_SETUP.md](MASTODON_SETUP.md) for comparison
- Review [Slack API Documentation](https://api.slack.com/docs)
- Open an issue on GitHub for bugs or questions

## Comparison: Slack vs Mastodon

| Feature | Slack | Mastodon |
|---------|-------|----------|
| **Scope** | Channel-scoped | Instance-wide |
| **Admin Powers** | Limited to channel | Full instance admin |
| **Setup** | OAuth app + tokens | OAuth + instance admin |
| **User Management** | User groups only | Full account management |
| **Moderation** | Message deletion | Suspend, silence, ban |
| **Federation** | No | Yes (block domains) |
| **Rate Limits** | Tiered, generous | Per instance config |
| **Best For** | Team/dept governance | Community instance governance |

---

**Important**: This is governance infrastructure for your team. Test thoroughly with a small group before deploying to larger channels!