Techcle Wiki

Work Package Slack

4 min read

Work Package: Slack Integration

Channel: #ai-dev-gateway-slack
Session: Session 1 (Slack Integration)
Namespace: ai-dev-gateway-slack-lab
Estimated Duration: 3-5 days
Dependencies: API Contract v1.0.0

Objective

Build the Slack connector that handles all Slack-specific interactions and communicates with the backend core via the API contract.

Deliverables

1. Slack App Configuration

  • Create Slack app manifest
  • Configure OAuth scopes
  • Set up webhook URL
  • Configure slash commands
  • Set up interactive components

Files:

  • slack-app-manifest.yaml
  • README-slack-setup.md

2. Webhook Endpoint

File: services/gateway/src/connectors/slack_connector.py

  • FastAPI webhook endpoint /slack/events
  • Signature verification
  • Event parsing and routing
  • Response handling

Endpoints:

  • POST /slack/events - Main webhook receiver
  • POST /slack/interactive - Interactive component handler
  • POST /slack/commands - Slash command handler

3. /opencode start Workflow Form

File: services/gateway/src/connectors/slack_forms.py

  • Load categories from config
  • Load projects from workspaces.yaml
  • Dynamic repository multi-select (from project config)
  • Task title and description fields
  • Complexity suggestion (with override)
  • Priority dropdown

Form Fields:

{
    "category": "Select from config",
    "project": "Text input or select",
    "repositories": "Multi-select checkboxes",
    "task_title": "Text input",
    "task_description": "Textarea",
    "complexity": "Select with AI suggestion",
    "priority": "Select (High/Medium/Low)"
}

4. BMAD Routing Confirmation

File: services/gateway/src/connectors/slack_routing.py

  • Display routing suggestion from backend
  • Show confidence and reasoning
  • Present confirmation buttons
  • Handle user decision
  • Send confirmation to backend

Button Actions:

  • “Yes, Consult Architect”
  • “No, Direct to Builder”
  • “Change to PM/Party Mode”

5. Thread Management

File: services/gateway/src/connectors/slack_threads.py

  • Create thread on work start
  • Post messages to correct thread
  • Handle nested threads for questions
  • Thread context tracking

6. Message Formatting

File: services/gateway/src/connectors/slack_messages.py

  • Progress updates (with emojis and formatting)
  • Question prompts with buttons
  • Deployment confirmations
  • Test results formatting
  • Error messages

Message Types:

  • Progress updates
  • Questions with options
  • Deployment ready
  • Test results
  • Completion notifications

7. Button Interaction Handlers

File: services/gateway/src/connectors/slack_interactions.py

  • Deployment confirmation buttons
  • Question response buttons
  • Namespace lifecycle buttons
  • Approval/rejection buttons

8. SSE Client for Deployment Progress

File: services/gateway/src/connectors/slack_sse_client.py

  • Connect to backend SSE stream
  • Parse events
  • Format and post to Slack thread
  • Handle connection errors and reconnection

9. Error Handling

File: services/gateway/src/connectors/slack_errors.py

  • Format backend errors for Slack
  • User-friendly error messages
  • Retry logic for transient failures
  • Fallback responses

10. Configuration

File: services/gateway/config/slack.yaml

slack:
  app_token: ${SLACK_APP_TOKEN}
  signing_secret: ${SLACK_SIGNING_SECRET}
  webhook_url: https://gateway.example.com/slack/events
  
backend:
  api_url: http://localhost:8000/api
  api_token: ${BACKEND_API_TOKEN}

Testing Strategy

Unit Tests

File: services/gateway/tests/connectors/test_slack_connector.py

  • Webhook signature verification
  • Form submission parsing
  • Message formatting
  • Button interaction handling

Integration Tests

File: services/gateway/tests/integration/test_slack_backend.py

  • Full workflow: form → backend → response
  • SSE stream handling
  • Error scenarios
  • Mock backend API

Mocking: Use api-contract.md to create mock backend responses.

Development Environment

Local Setup

# Install dependencies
cd repos/ai-dev/services/gateway
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
 
# Run locally
uvicorn src.connectors.slack_connector:app --reload --port 3000
 
# Use ngrok for Slack webhooks
ngrok http 3000

Mock Backend

File: services/gateway/tests/mocks/backend_mock.py

from fastapi import FastAPI
 
app = FastAPI()
 
@app.post("/api/sessions/start")
async def mock_start_session(request):
    # Return contract-compliant response
    return {
        "session_id": "sess_mock123",
        "workspace_path": ".builders/test",
        "bmad_routing": {
            "suggested": "architect",
            "confidence": 0.85,
            "reason": "Test routing"
        },
        "status": "awaiting_routing_confirmation"
    }

Dependencies

Python Packages

fastapi==0.110.0
uvicorn==0.27.0
slack-sdk==3.26.0
slack-bolt==1.18.0
httpx==0.26.0
pydantic==2.5.0
pyyaml==6.0.1

External Services

  • Slack workspace (for testing)
  • ngrok (for local webhook testing)
  • Mock backend (provided in this package)

Acceptance Criteria

  • /opencode start command opens form with dynamic fields
  • Form submission creates session via backend API
  • BMAD routing suggestion displays with confirmation
  • Progress updates post to correct thread
  • Questions display with interactive buttons
  • Deployment confirmation flow works end-to-end
  • SSE stream shows real-time deployment progress
  • Test results format correctly with all details
  • All error cases handled gracefully
  • Unit tests: 100% coverage
  • Integration tests: All contract scenarios

Notes

  • Contract Compliance: All API calls must match api-contract.md
  • Testing: Mock backend for all tests, no real backend required
  • Documentation: Include setup guide for Slack app configuration
  • Error Messages: Must be user-friendly and actionable

Handoff to Backend Team

When ready to integrate:

  1. Backend team deploys their API
  2. Update config/slack.yaml with real backend URL
  3. Run integration tests against real backend
  4. Deploy together to test environment

Graph View