AlexandrAI AGENTS.md
agents-md

Personal Work Agent Slack Connector Agent Guide

Project-specific AGENTS.md guidance for the Personal Work Agent Slack connector boundary, platform files, tests, cursor or client behavior, ingestion, validation, and redaction rules.

AGENTS.md

Guidance for coding agents working on the Personal Work Agent Slack connector boundary.

Project Overview

The Slack connector boundary keeps platform-specific API access, cursor sync, event normalization, and case creation separate from the generic runtime. Use this guide when changing Slack request shapes, sync cursors, watch-profile scoping, ingest mapping, validation behavior, or connector-specific tests.

This document is intentionally narrower than the broad connector guide. It is for agents already touching Slack-specific files.

Project Map

  • src/workagent/connectors/slack_client.py
  • src/workagent/connectors/slack_sync.py
  • src/workagent/connectors/slack_format.py
  • src/workagent/connectors/slack_send.py
  • src/workagent/services/slack_ingest.py
  • src/workagent/services/slack_cycle.py

Relevant tests:

  • tests/test_slack_client.py
  • tests/test_slack_sync.py
  • tests/test_slack_ingest.py
  • tests/test_slack_format.py
  • tests/test_slack_send.py
  • tests/test_slack_cycle.py

Setup Commands

bashuv run pytest tests/test_slack_client.py tests/test_slack_sync.py tests/test_slack_ingest.py tests/test_slack_format.py tests/test_slack_send.py tests/test_slack_cycle.py -q
uv run pytest tests/test_connector_validation.py tests/test_platform_event_normalization.py -q
make lint

Connector Notes

  • Slack has both ingestion and outbound send behavior.
  • Keep channel cursor handling, formatting, and send artifacts separate.

Change Rules For Agents

  • Keep raw platform API calls in connector client files.
  • Keep pagination, cursor parsing, and batch construction in connector sync files when a sync file exists.
  • Keep platform event to local case conversion in the matching ingest service when an ingest service exists.
  • Use credentials through the configured credential resolver and secret store; do not pass raw token values into cases.
  • Preserve watch-profile and query scoping before broad collection.
  • Normalize remote IDs consistently so duplicate events do not create duplicate local cases.
  • Keep platform-specific errors typed and covered by focused tests.

Verification

bashuv run pytest tests/test_slack_client.py tests/test_slack_sync.py tests/test_slack_ingest.py tests/test_slack_format.py tests/test_slack_send.py tests/test_slack_cycle.py -q
make lint

Run runtime factory tests too if connector registration changes.

Security Notes

Slack data can include private workspace content, user identifiers, files, tickets, messages, and credentials. Do not publish tokens, private endpoints, tenant identifiers, message bodies, file links, or account-specific IDs. Use placeholders in examples.

PR Checklist

  • Client behavior is covered by platform tests.
  • Cursor and duplicate handling are covered when sync exists.
  • Ingest conversion is covered when ingest exists.
  • Credential handling stays resolver-owned and redacted.