dan/ops-jrz1
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
ops-jrz1/specs/002-slack-bridge-integration/tasks.md
Dan ca379311b8 Add Slack bridge integration feature specification 
Includes spec, plan, research, data model, contracts, and quickstart guide
for mautrix-slack Socket Mode bridge deployment.
2025-10-26 14:36:44 -07:00

15 KiB
Raw Blame History

Tasks: Matrix-Slack Bridge Integration

Input: Design documents from /specs/002-slack-bridge-integration/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md

Tests: Manual integration testing only (no automated test tasks per spec.md testing strategy)

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

  • [P]: Can run in parallel (different files, no dependencies)
  • [Story]: Which user story this task belongs to (e.g., US1, US2, US3, US4)
  • Include exact file paths in descriptions

Path Conventions

  • Infrastructure configuration project (NixOS modules)
  • Primary files: modules/mautrix-slack.nix, hosts/ops-jrz1.nix, secrets/secrets.yaml
  • Documentation: docs/worklogs/*.org

Phase 1: Setup (Shared Infrastructure)

Purpose: Slack app configuration and secrets preparation (external prerequisites)

  • T001 Create Slack app using mautrix-slack app manifest from https://github.com/mautrix/slack/blob/main/app-manifest.yaml
  • T002 Enable Socket Mode in Slack app settings and generate app-level token (xapp-) with connections:write scope
  • T003 Install Slack app to chochacho workspace and copy bot token (xoxb-)
  • T004 [P] Document app setup process in docs/worklogs/2025-10-22-slack-app-setup.org
  • T005 Verify Slack app has all 29 required bot scopes per research.md section 2

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core infrastructure that MUST be complete before ANY user story can be implemented

⚠️ CRITICAL: No user story work can begin until this phase is complete

  • T006 Add slack-oauth-token and slack-app-token to secrets/secrets.yaml using sops secrets/secrets.yaml
  • T007 Verify secrets decrypt correctly on VPS using ssh root@45.77.205.49 'sops -d /path/to/secrets.yaml'
  • T008 Update modules/mautrix-slack.nix to change workspace from "delpadtech" to "chochacho"
  • T009 Verify PostgreSQL database mautrix_slack exists using ssh root@45.77.205.49 'sudo -u postgres psql -l | grep mautrix_slack'
  • T010 Verify Matrix homeserver conduwuit is running on port 8008 using ssh root@45.77.205.49 'curl -s http://localhost:8008/_matrix/client/versions'

Checkpoint: Foundation ready - user story implementation can now begin in parallel

Phase 3: User Story 1 - Slack to Matrix Message Delivery (Priority: P1) 🎯 MVP

Goal: Relay messages from Slack to Matrix within 5 seconds with sender identity preserved

Independent Test: Send test message in Slack #dev-platform, verify appears in Matrix room within 5 seconds with correct sender

Implementation for User Story 1

  • T011 [US1] Update hosts/ops-jrz1.nix to enable services.mautrix-slack with homeserverUrl http://127.0.0.1:8008 and serverName clarun.xyz
  • T012 [US1] Configure database connection in hosts/ops-jrz1.nix with uri postgresql:///mautrix_slack?host=/run/postgresql
  • T013 [US1] Set logging.level to "debug" in hosts/ops-jrz1.nix for initial deployment troubleshooting
  • T014 [US1] Deploy configuration to VPS using nixos-rebuild switch --flake .#ops-jrz1 --target-host root@45.77.205.49 --build-host localhost
  • T015 [US1] Verify mautrix-slack service started using ssh root@45.77.205.49 'systemctl status mautrix-slack'
  • T016 [US1] Check service logs for startup errors using ssh root@45.77.205.49 'journalctl -u mautrix-slack -n 50'
  • T017 [US1] Verify appservice registration file created at /var/lib/matrix-appservices/mautrix_slack_registration.yaml
  • T018 [US1] Add appservice registration to Matrix homeserver configuration (conduwuit continuwuity.toml)
  • T019 [US1] Restart Matrix homeserver to load appservice using ssh root@45.77.205.49 'systemctl restart matrix-continuwuity'
  • T020 [US1] Open Matrix DM with @slackbot:clarun.xyz and verify bot responds
  • T021 [US1] Authenticate bridge by sending "login app" command and providing bot token and app token
  • T022 [US1] Verify Socket Mode connection established in logs using ssh root@45.77.205.49 'journalctl -u mautrix-slack -f | grep -i socket'
  • T023 [US1] Accept invitation to Matrix room for #dev-platform channel
  • T024 [US1] Test Slack→Matrix relay by posting "Test message from Slack" in #dev-platform and verifying it appears in Matrix within 5 seconds
  • T025 [US1] Verify sender identity preserved (message shows from ghost user @slack_USERID:clarun.xyz)
  • T026 [US1] Test emoji preservation by posting message with emoji in Slack and verifying emoji appears in Matrix
  • T027 [US1] Test multi-line message formatting by posting multi-line message in Slack and verifying line breaks preserved in Matrix
  • T028 [US1] Test file attachment by uploading file to Slack and verifying link appears in Matrix
  • T029 [US1] Document US1 validation results in docs/worklogs/2025-10-22-us1-slack-to-matrix-validation.org

Checkpoint: At this point, User Story 1 should be fully functional and testable independently

Phase 4: User Story 2 - Matrix to Slack Message Delivery (Priority: P1)

Goal: Relay messages from Matrix to Slack within 5 seconds with Matrix username preserved

Independent Test: Send test message from Matrix room, verify appears in Slack channel within 5 seconds with Matrix username

Implementation for User Story 2

  • T030 [US2] Test Matrix→Slack relay by posting "Test message from Matrix" in bridged Matrix room and verifying it appears in Slack within 5 seconds
  • T031 [US2] Verify Matrix username appears in Slack message (bridge bot posts with sender attribution)
  • T032 [US2] Test markdown formatting by posting message with bold and italic in Matrix and verifying formatting converted in Slack
  • T033 [US2] Test user mention by mentioning another Matrix user and verifying translated to Slack @username format
  • T034 [US2] Test attachment posting from Matrix and verify link appears in Slack
  • T035 [US2] Verify bidirectional message flow works simultaneously (send messages from both sides)
  • T036 [US2] Document US2 validation results in docs/worklogs/2025-10-22-us2-matrix-to-slack-validation.org

Checkpoint: At this point, User Stories 1 AND 2 should both work independently (full bidirectional communication)

Phase 5: User Story 3 - Bridge Service Reliability (Priority: P2)

Goal: Bridge starts automatically on boot and recovers from failures without manual intervention

Independent Test: Reboot server and verify bridge auto-starts within 2 minutes, or simulate network failure and verify auto-recovery

Implementation for User Story 3

  • T037 [US3] Verify systemd service has Restart=always in modules/mautrix-slack.nix serviceConfig
  • T038 [US3] Verify service has After=network-online.target postgresql.service matrix-continuwuity.service in systemd dependencies
  • T039 [US3] Test auto-start by rebooting VPS using ssh root@45.77.205.49 'reboot'
  • T040 [US3] Verify bridge service started automatically within 2 minutes using systemctl status mautrix-slack
  • T041 [US3] Verify messages relay successfully after reboot without manual intervention
  • T042 [US3] Test connection recovery by simulating Slack API outage (temporarily revoke token, then restore)
  • T043 [US3] Verify bridge reconnects automatically after token restored without manual restart
  • T044 [US3] Test Matrix homeserver recovery by restarting conduwuit using ssh root@45.77.205.49 'systemctl restart matrix-continuwuity'
  • T045 [US3] Verify bridge re-establishes connection to Matrix automatically
  • T046 [US3] Test configuration error handling by temporarily breaking config and verifying clear diagnostic message in logs
  • T047 [US3] Verify health indicators logged (connection status, last message timestamp, error count) using journalctl -u mautrix-slack --since "1 hour ago"
  • T048 [US3] Document US3 validation results including recovery times in docs/worklogs/2025-10-22-us3-reliability-validation.org

Checkpoint: All P1 and P2 user stories should now be independently functional

Phase 6: User Story 4 - Bridge Configuration Management (Priority: P3)

Goal: Administrators can configure channel bridges declaratively without code or manual restarts

Independent Test: Add new channel to configuration, reload config, verify new bridge established automatically

Implementation for User Story 4

  • T049 [US4] Review automatic portal creation behavior from research.md section 5 (channels auto-bridge on activity)
  • T050 [US4] Document conversation_count configuration parameter in hosts/ops-jrz1.nix (controls initial sync count)
  • T051 [US4] Test adding new channel by inviting Slack bot to #general using /invite @Matrix Bridge in Slack
  • T052 [US4] Verify portal auto-created when message sent in #general without configuration change
  • T053 [US4] Accept Matrix room invitation for #general and verify messages relay
  • T054 [US4] Test removing channel bridge by kicking bot from Slack channel and verifying portal becomes inactive
  • T055 [US4] Document active bridges by querying database using ssh root@45.77.205.49 'sudo -u mautrix_slack psql mautrix_slack -c "SELECT * FROM portal;"'
  • T056 [US4] Test configuration error handling by setting invalid conversation_count value and verifying error message
  • T057 [US4] Document channel management workflow in docs/worklogs/2025-10-22-us4-channel-management.org
  • T058 [US4] Update CLAUDE.md with channel management patterns and common commands

Checkpoint: All user stories should now be independently functional

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Production readiness and documentation

  • T059 [P] Change logging.level from "debug" to "info" in hosts/ops-jrz1.nix for production
  • T060 [P] Create comprehensive deployment worklog in docs/worklogs/2025-10-22-slack-bridge-deployment-complete.org
  • T061 [P] Update platform-vision.md to mark Milestone 1 (Working Slack Bridge) as complete
  • T062 Validate all success criteria from spec.md SC-001 through SC-008
  • T063 Run through quickstart.md steps to verify deployment guide accuracy
  • T064 [P] Create backup of bridge database using ssh root@45.77.205.49 'sudo -u postgres pg_dump mautrix_slack > mautrix_slack_backup.sql'
  • T065 [P] Document monitoring commands and health check procedures in CLAUDE.md
  • T066 Monitor bridge stability for 7 days and collect uptime metrics for SC-003 validation
  • T067 [P] Create troubleshooting guide for common issues (exit code 11, Socket Mode disconnects, auth failures)

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies - can start immediately (external Slack app configuration)
  • Foundational (Phase 2): Depends on Setup completion - BLOCKS all user stories
  • User Stories (Phase 3-6): All depend on Foundational phase completion
    • US1 and US2 are both P1 priority but US2 depends on US1 being tested first (builds on Slack→Matrix foundation)
    • US3 (P2) can be tested after US1+US2 work
    • US4 (P3) can be implemented after core messaging validated
  • Polish (Phase 7): Depends on all desired user stories being complete

User Story Dependencies

  • User Story 1 (P1): Can start after Foundational (Phase 2) - No dependencies on other stories
  • User Story 2 (P1): Can start after US1 validated - Builds on Slack→Matrix relay working
  • User Story 3 (P2): Can start after US1+US2 - Tests existing bridge reliability
  • User Story 4 (P3): Can start after US1+US2 - Tests channel management on working bridge

Within Each User Story

  • US1: Setup → Deploy → Authenticate → Test Slack→Matrix → Validate
  • US2: Test Matrix→Slack → Validate (uses infrastructure from US1)
  • US3: Test auto-start → Test recovery → Monitor health indicators
  • US4: Test auto portal creation → Test removal → Document management

Parallel Opportunities

  • Phase 1 (T001-T005): All can run in parallel (different Slack app configuration steps)
  • Phase 2: Most tasks sequential (dependencies on secrets, config, services)
  • User Stories: Cannot truly parallelize due to shared bridge instance and sequential validation needs
  • Phase 7 polish tasks: Most marked [P] can run in parallel (different files/documentation)

Parallel Example: Phase 1 (Slack App Setup)

# All Slack app configuration tasks can proceed in parallel:
Task: "Create Slack app using manifest"
Task: "Document app setup process"
Task: "Verify scopes"

Parallel Example: Phase 7 (Polish)

# Documentation and monitoring tasks can run in parallel:
Task: "Change logging level to info"
Task: "Create deployment worklog"
Task: "Update platform-vision.md"
Task: "Create database backup"
Task: "Document monitoring commands"
Task: "Create troubleshooting guide"

Implementation Strategy

MVP First (User Stories 1 + 2)

  1. Complete Phase 1: Slack App Setup (external)
  2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
  3. Complete Phase 3: User Story 1 (Slack→Matrix)
  4. VALIDATE US1: Test independently, verify <5 second latency, verify sender identity
  5. Complete Phase 4: User Story 2 (Matrix→Slack)
  6. VALIDATE US2: Test independently, verify bidirectional flow works
  7. STOP and VALIDATE MVP: Full bidirectional messaging working
  8. Deploy/demo if ready

Incremental Delivery

  1. Complete Setup + Foundational → Foundation ready
  2. Add User Story 1 → Test independently → MVP partial (read-only Slack via Matrix)
  3. Add User Story 2 → Test independently → MVP complete (full bidirectional)
  4. Add User Story 3 → Test independently → Production ready (auto-recovery)
  5. Add User Story 4 → Test independently → Admin friendly (easy channel management)
  6. Each story adds value without breaking previous stories

Single-Person Sequential Strategy

Given infrastructure configuration nature (single bridge instance):

  1. Complete Setup (Phase 1) - Slack app external setup
  2. Complete Foundational (Phase 2) - Core infrastructure
  3. Implement User Story 1 (Phase 3) - Validate thoroughly before proceeding
  4. Implement User Story 2 (Phase 4) - Builds on US1, validate bidirectional
  5. Implement User Story 3 (Phase 5) - Test reliability features
  6. Implement User Story 4 (Phase 6) - Test channel management
  7. Polish (Phase 7) - Production hardening and documentation

Notes

  • [P] tasks = different files, no dependencies
  • [Story] label maps task to specific user story for traceability
  • Each user story should be independently completable and testable
  • Manual testing throughout (no automated test suite per spec.md)
  • Commit after each task or logical group
  • Stop at any checkpoint to validate story independently
  • Infrastructure project: tasks are configuration updates, not traditional code
  • Bridge uses interactive authentication (tokens via Matrix chat, not NixOS config)
  • Automatic portal creation means no static channel mapping configuration needed
  • Health monitoring via systemd journal logs (basic indicators per FR-011a)