Install this CLAUDE.md template.
Name: Slack Bot Project Template
Save to: ./CLAUDE.md in the current project

---
# CLAUDE.md — Slack Bot (Bolt.js + TypeScript)

## Project overview
<!-- One-sentence description of what this Slack bot does -->

## Tech stack
- **Framework**: Slack Bolt.js v4
- **Language**: TypeScript
- **Runtime**: Node.js 22
- **Package manager**: npm
- **Hosting**: AWS Lambda / Railway / Render

## Development commands
```bash
npm run dev          # start with hot reload (nodemon + ts-node)
npm run build        # compile TypeScript
npm run start        # run compiled JS in production
npm run tunnel       # start ngrok tunnel for local Slack events
```

## Project structure
```
src/
  app.ts             # Bolt app initialization & middleware
  events/            # event listeners (message, app_mention, etc.)
  commands/          # slash command handlers
  actions/           # interactive component handlers (buttons, modals)
  views/             # modal and home tab view builders
  utils/             # shared helpers
```

## Slack app configuration
- **Socket Mode**: enabled for local dev (no public URL needed)
- **Event Subscriptions**: `message.channels`, `app_mention`, `app_home_opened`
- **Slash Commands**: register at https://api.slack.com/apps/YOUR_APP_ID/slash-commands
- **OAuth Scopes**: `chat:write`, `channels:history`, `commands`, `app_mentions:read`

## Coding conventions
- Each event/command/action gets its own file in the appropriate directory
- Use `app.event()`, `app.command()`, `app.action()` — never raw HTTP handlers
- Always `await ack()` immediately in command and action handlers
- Use Block Kit Builder (https://app.slack.com/block-kit-builder) to design complex layouts
- Error responses should use ephemeral messages (`response_type: "ephemeral"`)

## Environment variables
```
SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
SLACK_APP_TOKEN=xapp-...     # for Socket Mode
```

## Common pitfalls
- Forgetting to `await ack()` within 3 seconds causes Slack to show "operation_timeout"
- Socket Mode requires the `SLACK_APP_TOKEN` (xapp-), not the bot token
- Bolt.js expects the raw request body for signature verification — don't parse it first
- Use `say()` for channel messages, `respond()` for command/action responses