---
name: setup-scout-slack
description: Set up, install, diagnose, or run the local Scout for Slack Socket Mode app. Use when an operator asks to create a Slack app for Scout, connect Slack to the Scout broker, collect Slack xapp/xoxb credentials, run the Slack bridge doctor, or configure Slack channel defaults.
---

# Set up Scout for Slack

Scout for Slack is an edge adapter: Slack receives requests and renders results;
the local Scout broker and harness own reasoning, tools, conversations, and
flights. Never add an LLM loop, Vercel Chat SDK, or Bolt as the installer/core.

Availability: Scout for Slack is a private preview. `packages/slack` and the
`bun run slack:*` scripts exist only in the private OpenScout source; the public
`oscout/scout` repository and the installed `scout` CLI do not include them. If
the checkout has no `packages/slack`, stop and ask the operator for source
access. Do not substitute another Slack bridge.

## Required workflow

Follow these steps in order and stop at a failed gate.

1. Ask the operator through the host's real `needs_input` / operator-attention
   mechanism whether they administer the target Slack workspace. Do not infer
   this and do not substitute a company workspace they cannot administer. Stop
   if the answer is no; they need a personal/administered workspace.
2. Verify the Scout broker first with `scout doctor` (or the repo's equivalent).
3. From the OpenScout repo, generate the canonical Socket Mode manifest:

   ```bash
   bun run slack:manifest > /tmp/openscout-slack-manifest.json
   bun -e 'const m=await Bun.file("/tmp/openscout-slack-manifest.json").text(); console.log(`https://api.slack.com/apps?new_app=1&manifest_json=${encodeURIComponent(m)}`)'
   ```

   Open the printed URL only after the operator agrees. The manifest source is
   `packages/slack/src/manifest.ts`; do not hand-edit a divergent manifest.
4. Tell the operator to click **Create**, then **Install to Workspace**, in that
   order. Slack requires this human workspace-admin approval.
5. Collect both secrets through `needs_input` / operator attention, never by
   asking the operator to export them in an unrelated shell:
   - `xapp-…`: Basic Information → App-Level Tokens → create/generate a token
     with `connections:write`.
   - `xoxb-…`: OAuth & Permissions → Bot User OAuth Token, after install.
6. Never commit, log, echo, screenshot, or place either token in `state.json`.
   Prefer macOS Keychain or an existing OpenScout secret facility. If a local
   file is unavoidable, keep it outside git under
   `~/Library/Application Support/OpenScout/slack/`, set directory mode `700`
   and file mode `600`, and ensure the bridge receives the values as
   `SLACK_APP_TOKEN` and `SLACK_BOT_TOKEN` environment variables. Do not put
   literal tokens in a LaunchAgent plist.
7. With the broker healthy and both environment variables present, run:

   ```bash
   bun run slack:doctor
   bun run slack:start
   ```

   Report doctor output without secrets. Keep `slack:start` supervised in a
   durable local process if the operator wants it to survive the shell.
8. In Slack, invite Scout to applicable channels. Use `/scout-settings` to set
   project, branch, and optional harness, or set single-project fallbacks with
   `OPENSCOUT_SLACK_DEFAULT_PROJECT`, `OPENSCOUT_SLACK_DEFAULT_BRANCH`, and
   `OPENSCOUT_SLACK_DEFAULT_HARNESS`.

## Boundaries

- The canonical app uses Socket Mode, `app_mention` and `message.im`, plus
  `/scout-settings`; no public webhook or hosted relay is required.
- Do not present Slack as `--harness slack`; it is a host surface.
- Do not add Slack Agents/assistant events, hosted Add to Slack, or automated
  config-token/OAuth flows unless the task explicitly expands scope.
- Computer use is opt-in last-mile assistance only (for example clicking
  **Generate Token**). It is not the installer, must not become daily Chrome
  automation, and must never scrape credentials into a transcript.
- If blocked on a click or secret, emit an explicit operator-attention request
  with the exact next UI location; never wait silently.

## Completion report

Return changed files, commands/checks run, sanitized doctor output, and the
single exact human action still required, if any.