Modpol/agentic-govbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Slack platform adapter and comprehensive platform skills system

Browse Source 
Major Features:
- Implemented full Slack channel-bot adapter with Socket Mode
- Added 35+ Mastodon platform skills across 7 categories
- Created constitution publishing system for Mastodon

Slack Adapter (NEW):
- Full PlatformAdapter implementation (1071 lines)
- Socket Mode for real-time events
- 16 channel-scoped governance skills
- User group management as channel "roles"
- Channel access control and management
- Message pinning and moderation
- Platform limitations documentation
- Comprehensive setup guide (SLACK_SETUP.md)

Mastodon Platform Skills (ENHANCED):
- Account Moderation (9 skills): suspend, silence, disable, mark sensitive, delete status
- Account Management (4 skills): approve, reject, delete data, create account
- Report Management (4 skills): assign, unassign, resolve, reopen
- Federation Management (4 skills): block/unblock domains, allow/disallow federation
- Security Management (4 skills): block IP/email domains
- Constitution Management (2 skills): publish constitution, update profile
- Documented web-only limitations (role management requires tootctl)

Constitution Publishing:
- Publish constitution as pinned Mastodon thread
- Automatic deprecation of previous versions
- Version control with change summaries
- Thread splitting for long documents
- CLI tool: scripts/publish_constitution.py
- Documentation: CONSTITUTION_PUBLISHING.md

Configuration & Integration:
- Added SlackConfig model with bot_token, app_token, channel_id
- Updated PlatformConfig to support type: slack
- Added slack-sdk>=3.33.0 dependency
- Bot.py now routes to Slack adapter
- Updated example config with Slack section

Documentation:
- SLACK_SETUP.md: Complete Slack setup guide
- PLATFORM_SKILLS.md: All 35+ Mastodon skills documented
- CONSTITUTION_PUBLISHING.md: Constitution publishing guide
- Updated README.md: Merged QUICKSTART, added Slack to supported platforms
- Updated PLATFORMS.md: Slack marked as implemented with examples
- Updated .gitignore: Added instance-specific state files

Security:
- All sensitive files properly gitignored
- Instance-specific state (.constitution_post_id) excluded
- Credentials properly handled in config

Breaking Changes: None

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Nathan Schneider
2026-02-10 22:46:48 -07:00
parent a0785f09cf
commit 54beddb420
16 changed files with 3675 additions and 489 deletions
Download Patch File Download Diff File Expand all files Collapse all files

629
SLACK_SETUP.md Normal file
View File

@@ -0,0 +1,629 @@
# 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!