slack-connect

name	slack-connect
description	Set up Slack as a notification channel for your Egregore — creates the workspace app, invites the bot, and binds a channel. Use for /slack-connect, 'connect slack', or 'set up slack notifications'.

Set up Slack as a notification channel for your Egregore.

Arguments: $ARGUMENTS (none expected)

When to invoke

Trigger phrases:

• "set up slack", "connect slack", "slack-connect"
• "add slack notifications", "slack channel", "notify us on slack"

Disambiguation:

• "set up telegram" → /telegram-connect
• "set up teams" → /teams-connect
• "send a message to slack" → NOT this — use the separate notification consent protocol in .claude/context/notification-consent.md

What this does

Connects one Slack channel to Egregore notifications using an app the org creates in its own workspace. After this, everything that plans a group notification may also resolve Slack as a receiving channel; all resolved channels are shown before separate dispatch approval.

The privacy contract, stated plainly to the user: the install screen will say only "Send messages as @Egregore." The app cannot read messages — the manifest requests one scope, chat:write. The workspace owns the app and the token; revoking either cuts Egregore off instantly.

Works in both modes. Check which one first:

MODE=$(jq -r '.mode // "connected"' egregore.json 2>/dev/null)

• local — the token stays in the gitignored .env on this machine and messages go straight from here to Slack. No Egregore server is in the path.
• connected — the token is stored on the org's row so the hosted service can deliver group notifications from any member's session.

Only Step 5 differs between the modes.

Step 0: Prerequisites

1. A Slack workspace where this person can install apps. Some workspaces require admin approval for new apps — if theirs does, the install in Step 2 turns into a request the admin must approve first.
2. Nothing to install locally. No CLI, no cloud account.

Step 1: Create the app from the manifest (human, ~1 min)

Show the manifest:

cat slack-app/manifest.yml

(If this instance doesn't carry slack-app/, fetch it from the framework repo.)

Guide them: https://api.slack.com/apps → Create New App → From a manifest → pick their workspace → paste the manifest → Create.

Step 2: Install and copy the bot token (human, 2 clicks + 1 paste)

Settings → Install App → Install to Workspace → Allow.

Then copy the Bot User OAuth Token from the same page. It starts with xoxb-. Validate the prefix when they paste it:

• xoxb- — correct.
• xoxp- (user token) or xapp- (app-level token) — wrong item on the page; point them back to Install App → Bot User OAuth Token.

Do not store it anywhere yet.

Step 3: Invite the bot to the channel (human, 1 line)

In the target channel: /invite @Egregore (or channel name → Integrations → Add apps). With only chat:write, the bot can post solely in channels it is a member of — skipping this yields not_in_channel at send time.

Step 4: Channel ID (human pastes, agent validates)

Ask for the channel ID: channel name → About tab → Channel ID at the bottom (or the /archives/C… segment of a channel link).

Validate: must match ^[CG][A-Z0-9]{6,}$. A D… id is a DM — not supported; ask for a channel.

Smoke-test the token before persisting anything (no message is sent):

curl -sS https://slack.com/api/auth.test -H "Authorization: Bearer <TOKEN>"

"ok":true proves the token and names the workspace — confirm it is the one they expect. invalid_auth here means a mispasted or revoked token; fix now, not at send time.

Step 5: Persist

Local mode — token to .env (gitignored — never commit), channel to .egregore-state.json (NOT egregore.json — the state file is untracked and shared across worktrees):

printf 'SLACK_BOT_TOKEN=%s\n' '<TOKEN>' >> .env
jq '.slack_channel_id = "<CHANNEL_ID>" | .slack_channel_name = "<#channel-name>"' \
  .egregore-state.json > .egregore-state.json.tmp && mv .egregore-state.json.tmp .egregore-state.json

Connected mode — store on the org so any member's session can deliver:

API_URL=$(jq -r '.api_url' egregore.json)
KEY=$(grep '^EGREGORE_API_KEY=' .env | cut -d= -f2-)
curl -sS -X POST "$API_URL/api/org/slack" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"channel_id":"<CHANNEL_ID>","bot_token":"<TOKEN>","channel_name":"<#channel-name>"}'

Expect {"status":"connected", …}.

Step 6: Verify with separate exact notification consent

Follow .claude/context/notification-consent.md. Connecting Slack is not consent to send a test message. Prepare after configuration is final:

PLAN_JSON=$(bash bin/notify.sh plan group "Slack channel connected — this message reached you through Egregore.")

Show every resolved receiving channel—potentially Telegram, Teams, and Slack—and the exact message in a dedicated Send / Edit / Cancel checkpoint. Only dispatch after Send is selected for that preview.

Troubleshooting quick table

Symptom	Cause → fix
invalid_auth	Wrong, revoked, or other-workspace token → Step 2, re-copy from Install App
not_in_channel	Bot not invited to the channel → Step 3
channel_not_found	Wrong channel ID, or a private channel the bot isn't in → Step 4 / invite it
missing_scope	App not created from the manifest → recreate from Step 1, reinstall
account_inactive	App was uninstalled from the workspace → reinstall
ratelimited	Transient — retried automatically
Install becomes an approval request	Workspace requires admin approval → the admin approves, then continue
Local plan omits slack from channels	Half-configured: SLACK_BOT_TOKEN missing from .env or slack_channel_id missing from .egregore-state.json

After

Emit telemetry (fire-and-forget):

bash bin/telemetry.sh emit "slack-connect" '{"command":"slack-connect"}' 2>/dev/null &