Standup Bot

A reliable Slack bot for automated daily standup prompts and PTO/out-of-office announcements.

Features

• Daily Standup Prompts - Schedule recurring standup reminders at specific times
• Interactive Submissions - Team members submit updates through easy-to-use modals
• PTO Management - Automatically announce team members who are out of office
• Multi-Schedule Support - Create multiple standup schedules per channel
• Timezone-Aware - Handles timezones and DST transitions correctly
• Reliable Scheduling - Custom asyncio-based polling scheduler ensures jobs fire on time

Quick Start

Prerequisites

• Python 3.10+
• Slack workspace with admin access

Installation

git clone https://github.com/YOUR_USERNAME/standup-bot.git
cd standup-bot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Slack App Setup

1. Go to api.slack.com/apps
2. Create a new app (from manifest or scratch)
3. Add OAuth scopes: commands, chat:write, channels:read, users:read
4. Enable Socket Mode and create an App-Level Token
5. Install the app to your workspace

Configuration

Create a .env file with your Slack credentials:

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_SIGNING_SECRET=your-signing-secret

# Optional
DATA_DIR=./data
DATABASE_NAME=standup.db
DEFAULT_TIMEZONE=America/New_York
WORKDAY_START_TIME=09:00

Run

python scripts/init_db.py  # First time only
python3 -m src.main

Usage

Standup Schedules

Command	Description
/standup	Create or manage standup schedules

Creating a schedule:

1. Run /standup in a channel
2. Configure: name, time, timezone, active days, questions
3. Click "Create"

Managing schedules:

• Edit - Modify configuration
• Pause/Resume - Temporarily disable/enable
• Delete - Remove permanently

PTO/Out of Office

Command	Description
/pto	Add or manage PTO entries

Adding PTO:

1. Run /pto from any channel
2. Set start date, end date, optional note
3. Select channels for announcements
4. Click "Add PTO"

Daily announcements post automatically at the configured time (default: 9 AM).

Architecture

Built with:

• Python 3.10+ with asyncio
• Slack Bolt SDK (AsyncApp with Socket Mode)
• SQLite with WAL mode (PostgreSQL-ready)
• Custom polling scheduler for reliable job execution

standup-bot/
├── src/
│   ├── handlers/      # Slack event handlers
│   ├── models/        # Database models
│   ├── scheduler/     # Polling scheduler
│   ├── services/      # Business logic
│   └── utils/         # Helpers (blocks, formatters, timezone)
├── scripts/           # Database initialization
├── docs/              # Architecture & requirements docs
└── data/              # SQLite database (created at runtime)

Why a Custom Scheduler?

V1 used APScheduler but jobs frequently missed their scheduled times by minutes or hours. V2 uses a custom asyncio polling scheduler that:

• Checks the database every 30 seconds for due jobs
• Fires jobs within a 15-second window or skips them (fail-fast)
• Uses database-backed execution logs to prevent duplicates
• Survives restarts with no missed jobs

See docs/architecture.md for details.

Troubleshooting

Problem	Solution
Bot not starting	Check .env variables, verify tokens in Slack app settings
Schedules not firing	Verify schedule is active, check timezone, ensure bot is in channel
Modal errors	Run /standup from the target channel (not DMs)

Useful logs:

• === STANDUP JOB TRIGGERED === - Job fired successfully
• Scheduler tick: - Scheduler is running (every 30s)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

See docs/product_requirements.md for feature specifications.

License

MIT License - see LICENSE for details.