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

311
CONSTITUTION_PUBLISHING.md Normal file
View File

@@ -0,0 +1,311 @@
# Constitution Publishing
The bot can publish and maintain its constitution as a pinned thread on Mastodon, creating a transparent, versioned record of governance rules.
## How It Works
### Constitutional Version Control
When you publish or update the constitution:
1. **Previous Version Deprecated**: The old pinned constitution gets a deprecation notice
2. **New Version Posted**: Constitution is split into a thread (~450 chars per post)
3. **Thread Pinned**: First post is pinned to the bot's profile
4. **History Preserved**: Old versions remain visible with deprecation notices
5. **ID Tracked**: Post ID saved to `config/.constitution_post_id` for future updates
### Thread Format
```
📜 CONSTITUTION (Updated: 2026-02-10)
Thread 🧵 [1/5]
[Constitution content...]
[2/5]
[More content...]
[3/5]
[More content...]
```
### Deprecation Notice (on old versions)
```
⚠️ DEPRECATED: This constitution has been superseded.
Changes: Updated voting thresholds and added new roles
Please see my profile for the current pinned constitution.
```
## Publishing Methods
### Method 1: Via Bot Command (Recommended)
Ask the bot directly via Mastodon:
```
@govbot please publish the current constitution
```
The bot will:
- Read `constitution.md`
- Check authority per constitution
- Post and pin the thread
- Report success/failure
### Method 2: Helper Script
Use the provided script for direct publishing:
```bash
# Basic usage
python scripts/publish_constitution.py
# With change summary
python scripts/publish_constitution.py --summary "Added role-based permissions"
# Custom constitution file
python scripts/publish_constitution.py --constitution docs/governance.md
# Full options
python scripts/publish_constitution.py \
--constitution constitution.md \
--summary "Updated voting thresholds" \
--config config/config.yaml
```
**Script options:**
- `--summary` / `-s`: Description of changes (shown in deprecation notice)
- `--constitution` / `-c`: Path to constitution file (default: `constitution.md`)
- `--config`: Path to config file (default: `config/config.yaml`)
### Method 3: Python API
Programmatically publish from your own code:
```python
from src.govbot.utils.config import load_config
from src.govbot.platforms.mastodon import MastodonAdapter
# Load config and connect
config = load_config("config/config.yaml")
adapter = MastodonAdapter(config.platform.mastodon.model_dump())
adapter.connect()
# Publish constitution
result = adapter.execute_skill(
skill_name="publish_constitution",
parameters={
"constitution_text": constitution_text,
"change_summary": "What changed in this version",
},
actor="@admin"
)
print(result["message"])
```
## Profile Integration
### Update Profile to Reference Constitution
The bot can also update its profile to highlight the constitution:
```python
# Via bot command
@govbot update your profile to mention the constitution in your bio
# Via Python API
adapter.execute_skill(
skill_name="update_profile",
parameters={
"display_name": "Govbot",
"note": "🤖 Governance bot for democratic communities.\n\n📜 Constitution pinned to profile.",
"fields": [
{"name": "Constitution", "value": "📜 See pinned post"},
{"name": "Governance", "value": "Consensus-based"},
{"name": "Source Code", "value": "github.com/you/repo"},
{"name": "Contact", "value": "@admin"}
]
},
actor="@admin"
)
```
Profile fields appear as a table on the bot's profile page.
## Best Practices
### Initial Publication
When first setting up the bot:
1. **Finalize Constitution**: Make sure `constitution.md` is complete
2. **Set Profile**: Update bio and fields to reference constitution
3. **Publish Constitution**: Run publish script or ask bot
4. **Verify**: Visit bot's profile to confirm pinned thread
### Updating Constitution
When making changes:
1. **Edit File**: Update `constitution.md` with changes
2. **Write Summary**: Prepare clear description of what changed
3. **Test Locally**: Use CLI mode to test if needed
4. **Publish Update**: Run script with `--summary` flag
5. **Verify**: Check that:
- Old version has deprecation notice
- New version is pinned
- Profile still references constitution
### Version Control
Consider maintaining constitution in git:
```bash
# Track changes
git add constitution.md
git commit -m "Update voting thresholds from 60% to 66%"
# Publish to Mastodon
python scripts/publish_constitution.py \
--summary "Update voting thresholds from 60% to 66%"
# Push to repo
git push
```
This gives you:
- **Git history**: Full version control with diffs
- **Mastodon thread history**: Public, timestamped versions
- **Deprecation chain**: Links between versions
## Example Workflow
### Scenario: Updating Voting Rules
```bash
# 1. Edit constitution
nano constitution.md
# (Change "50% majority" to "60% supermajority")
# 2. Test understanding (optional)
python -m src.govbot.governance.constitution "What is the voting threshold?"
# Verify it understands the new rule
# 3. Commit to git
git add constitution.md
git commit -m "Increase voting threshold to supermajority"
# 4. Publish to Mastodon
python scripts/publish_constitution.py \
--summary "Increased voting threshold from 50% to 60%"
# Output:
# 📜 Loaded constitution from constitution.md (4532 chars)
# 🔌 Connecting to https://govbot.modpol.net...
# ✅ Connected as @govbot
# 📤 Publishing constitution...
# Change summary: Increased voting threshold from 50% to 60%
# ✅ Constitution published as 8-post thread and pinned to profile.
# Previous version marked as deprecated.
# 📊 Details:
# - Thread length: 8 posts
# - First post ID: 123456789
# - Previous post ID: 123456700 (deprecated)
# 🔗 View at: https://govbot.modpol.net/@govbot
# ✨ Done!
# 5. Verify
# Visit https://govbot.modpol.net/@govbot
# - New thread is pinned
# - Old thread has deprecation notice
```
## Technical Details
### File Storage
The current constitution post ID is stored in:
```
config/.constitution_post_id
```
This file is **gitignored** but tracked by the bot to find the previous version when updating.
### Thread Splitting Algorithm
The bot splits constitution into chunks:
1. **Split by paragraphs**: Preserves semantic boundaries
2. **Combine into chunks**: Up to 450 chars each (leaving room for thread indicators)
3. **Add thread indicators**: `[1/8]`, `[2/8]`, etc.
4. **First post header**: Includes emoji, date, and thread indicator
5. **Post sequentially**: Each replies to the previous
### Post Visibility
Constitution posts are always:
- **Public visibility**: Anyone can see and share
- **Threaded**: Each post replies to previous
- **Pinned**: First post pinned to profile (max 5 pins)
### Mastodon API Requirements
Publishing requires:
- `write:accounts` scope (for pinning/unpinning)
- `write:statuses` scope (for posting)
- Bot must be connected and authenticated
## Troubleshooting
### "Failed to pin constitution"
**Cause**: Too many posts already pinned (max 5)
**Solution**: Manually unpin old posts from web interface at Settings → Profile → Pinned posts
### "Constitution file not found"
**Cause**: File path incorrect
**Solution**: Verify file exists:
```bash
ls -la constitution.md
```
### "Not authorized to publish"
**Cause**: Bot doesn't have authority per constitution
**Solution**: Either:
- Grant bot authority in constitution
- Use script directly (bypasses authorization check)
### "Previous version not found"
**Cause**: `.constitution_post_id` file missing or contains invalid ID
**Solution**:
- First publication: This is normal, ignore
- Subsequent: Old version won't be deprecated (but new version will still pin)
## Future Enhancements
Potential improvements:
- **Diff Display**: Show exact changes between versions
- **Amendment Tracking**: Link to governance processes that authorized changes
- **Multilingual**: Publish translations as separate threads
- **Rich Formatting**: Use custom emojis or instance-specific formatting
- **Automatic Publishing**: Trigger on git push or governance process completion
## See Also
- [PLATFORM_SKILLS.md](PLATFORM_SKILLS.md) - All available platform skills
- [ARCHITECTURE.md](ARCHITECTURE.md) - How the bot works
- [Mastodon API - Update Credentials](https://docs.joinmastodon.org/methods/accounts/#update_credentials)
- [Mastodon API - Pin Status](https://docs.joinmastodon.org/methods/statuses/#pin)