@desplega.ai/agent-swarm 1.10.8 → 1.20.0

package/DEPLOYMENT.md

@@ -7,7 +7,11 @@ This guide covers all deployment options for Agent Swarm MCP.
 - [Docker Compose (Recommended)](#docker-compose-recommended)
 - [Docker Worker](#docker-worker)
 - [Server Deployment (systemd)](#server-deployment-systemd)
+- [Graceful Shutdown & Task Resume](#graceful-shutdown--task-resume)
 - [Environment Variables](#environment-variables)
+- [Slack Integration](#slack-integration)
+- [GitHub App Integration](#github-app-integration)
+- [Sentry Integration](#sentry-integration)
 - [System Prompts](#system-prompts)
 - [Service Registry (PM2)](#service-registry-pm2)
 - [Publishing (Maintainers)](#publishing-maintainers)
@@ -71,8 +75,21 @@ GITHUB_NAME=Your Name
 |--------|---------|
 | `swarm_api` | SQLite database persistence |
 | `swarm_logs` | Session logs |
-| `swarm_shared` | Shared workspace between agents |
-| `swarm_worker_*` | Personal workspace per worker |
+| `swarm_shared` | Shared workspace between agents (`/workspace/shared`) |
+| `swarm_lead` | Lead agent's personal workspace (`/workspace/personal`) |
+| `swarm_worker_*` | Personal workspace per worker (`/workspace/personal`) |
+
+### Graceful Shutdown
+
+The docker-compose example uses `stop_grace_period: 60s` to allow graceful task pause during deployments. When a container receives SIGTERM:
+
+1. In-progress tasks are **paused** (not failed)
+2. Task state and progress are preserved
+3. After restart, paused tasks are automatically **resumed** with context
+
+This enables zero-downtime deployments. See [Graceful Shutdown & Task Resume](#graceful-shutdown--task-resume) for details.
+
+> **Important:** Use stable `AGENT_ID` values for each worker to enable task resume after restarts.
 
 ---
 
@@ -111,7 +128,7 @@ docker run --rm -it \
 docker run --rm -it \
   -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
   -e API_KEY=your-api-key \
-  -e WORKER_SYSTEM_PROMPT="You are a Python specialist" \
+  -e SYSTEM_PROMPT="You are a Python specialist" \
   -v ./logs:/logs \
   -v ./work:/workspace \
   ghcr.io/desplega-ai/agent-swarm-worker
@@ -120,7 +137,7 @@ docker run --rm -it \
 docker run --rm -it \
   -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
   -e API_KEY=your-api-key \
-  -e WORKER_SYSTEM_PROMPT_FILE=/workspace/prompts/specialist.txt \
+  -e SYSTEM_PROMPT_FILE=/workspace/prompts/specialist.txt \
   -v ./work:/workspace \
   ghcr.io/desplega-ai/agent-swarm-worker
 
@@ -160,12 +177,15 @@ The Docker worker image uses a multi-stage build:
 - **Languages**: Python 3, Node.js 22, Bun
 - **Build tools**: gcc, g++, make, cmake
 - **Process manager**: PM2 (for background services)
+- **CLI tools**: GitHub CLI (`gh`), sqlite3
+- **Agent tools**: `wts` (git worktree manager), `cc-ai-tracker` (code change tracking)
 - **Utilities**: git, git-lfs, vim, nano, jq, curl, wget, ssh
 - **Sudo access**: Worker can install packages with `sudo apt-get install`
 
 **Volumes:**
 
-- `/workspace` - Working directory for cloning repos
+- `/workspace/personal` - Agent's personal workspace (isolated per agent)
+- `/workspace/shared` - Shared workspace between all agents
 - `/logs` - Session logs
 
 ### Startup Scripts
@@ -265,6 +285,56 @@ sudo systemctl stop agent-swarm
 
 ---
 
+## Graceful Shutdown & Task Resume
+
+Agent Swarm supports graceful task handling during deployments and container restarts.
+
+### How It Works
+
+When a worker container receives SIGTERM (e.g., during `docker-compose down` or Kubernetes rollout):
+
+1. **Grace period starts** - Worker waits for active tasks to complete (default: 30s, configurable via `SHUTDOWN_TIMEOUT`)
+2. **Tasks are paused** - Any tasks still running after the grace period are marked as `paused` (not `failed`)
+3. **State preserved** - Task progress and context are saved to the database
+4. **On restart** - Worker automatically fetches and resumes its paused tasks with full context
+
+### Task States During Shutdown
+
+| State | Description |
+|-------|-------------|
+| `in_progress` | Task completes normally if it finishes within grace period |
+| `paused` | Task is paused for resume after restart |
+| `failed` | Only used if pause API fails (fallback) |
+
+### Configuration
+
+```bash
+# Grace period before force-pausing tasks (milliseconds)
+SHUTDOWN_TIMEOUT=30000
+
+# Docker compose stop grace period (should be >= SHUTDOWN_TIMEOUT + buffer)
+stop_grace_period: 60s
+```
+
+### Resume Behavior
+
+When a worker starts, it:
+
+1. Registers with the MCP server
+2. Checks for paused tasks assigned to its `AGENT_ID`
+3. Resumes each paused task with context:
+   - Original task description
+   - Previous progress (if any was saved)
+   - Notification that this is a resumed task
+
+### Best Practices
+
+- **Use stable Agent IDs** - Set explicit `AGENT_ID` for each worker to enable resume after restarts
+- **Save progress regularly** - Workers should call `store-progress` during long tasks
+- **Test deployments** - Verify tasks resume correctly in staging before production
+
+---
+
 ## Environment Variables
 
 ### Docker Worker Variables
@@ -273,24 +343,168 @@ sudo systemctl stop agent-swarm
 |----------|----------|-------------|
 | `CLAUDE_CODE_OAUTH_TOKEN` | Yes | OAuth token for Claude CLI (run `claude setup-token`) |
 | `API_KEY` | Yes | API key for MCP server |
-| `AGENT_ID` | No | Agent UUID (assigned on join if not set) |
+| `AGENT_ID` | No | Agent UUID (assigned on join if not set). **Keep stable for task resume.** |
+| `AGENT_ROLE` | No | Role: `worker` (default) or `lead` |
+| `AGENT_NAME` | No | Display name for the agent (auto-generated if not set) |
 | `MCP_BASE_URL` | No | MCP server URL (default: `http://host.docker.internal:3013`) |
 | `SESSION_ID` | No | Log folder name (auto-generated if not provided) |
-| `WORKER_YOLO` | No | Continue on errors (default: `false`) |
-| `WORKER_SYSTEM_PROMPT` | No | Custom system prompt text |
-| `WORKER_SYSTEM_PROMPT_FILE` | No | Path to system prompt file |
+| `YOLO` | No | Continue on errors (default: `false`) |
+| `SYSTEM_PROMPT` | No | Custom system prompt text |
+| `SYSTEM_PROMPT_FILE` | No | Path to system prompt file |
 | `STARTUP_SCRIPT_STRICT` | No | Exit on startup script failure (default: `true`) |
+| `SHUTDOWN_TIMEOUT` | No | Grace period in ms before pausing tasks (default: `30000`) |
+| `MAX_CONCURRENT_TASKS` | No | Maximum parallel tasks per worker (default: `1`) |
 | `SWARM_URL` | No | Base domain for service URLs (default: `localhost`) |
 | `SERVICE_PORT` | No | Host port for exposed services (default: `3000`) |
 | `PM2_HOME` | No | PM2 state directory (default: `/workspace/.pm2`) |
+| `GITHUB_TOKEN` | No | GitHub token for git operations |
+| `GITHUB_EMAIL` | No | Git commit email (default: `worker-agent@desplega.ai`) |
+| `GITHUB_NAME` | No | Git commit name (default: `Worker Agent`) |
+| `SENTRY_AUTH_TOKEN` | No | Sentry Organization Auth Token for issue investigation |
+| `SENTRY_ORG` | No | Sentry organization slug |
 
 ### Server Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `MCP_BASE_URL` | Base URL for the MCP server | `https://agent-swarm-mcp.desplega.sh` |
-| `PORT` | Port for self-hosted MCP server | `3013` |
+| `PORT` | Port for MCP HTTP server | `3013` |
 | `API_KEY` | API key for server authentication | - |
+| `MCP_BASE_URL` | Base URL (for setup command) | `https://agent-swarm-mcp.desplega.sh` |
+| `SWARM_URL` | Base domain for service discovery | `localhost` |
+| `APP_URL` | Dashboard URL for Slack message links | - |
+| `ENV` | Environment mode (`development` adds prefix to Slack agent names) | - |
+| `SCHEDULER_INTERVAL_MS` | Polling interval for scheduled tasks | `10000` |
+| `DATABASE_PATH` | SQLite database file path | `./agent-swarm-db.sqlite` |
+
+---
+
+## Slack Integration
+
+Enable Slack for task creation and agent communication via direct messages.
+
+### Setup
+
+1. Create a Slack App at https://api.slack.com/apps
+2. Enable Socket Mode (for real-time events without public webhooks)
+3. Add required scopes: `chat:write`, `users:read`, `users:read.email`, `channels:history`, `im:history`
+4. Install to workspace and copy tokens
+
+### Configuration
+
+```bash
+# Required for Slack
+SLACK_BOT_TOKEN=xoxb-...      # Bot User OAuth Token
+SLACK_APP_TOKEN=xapp-...      # App-Level Token (Socket Mode)
+SLACK_SIGNING_SECRET=...      # Signing Secret (optional for Socket Mode)
+
+# Disable Slack (if not using)
+SLACK_DISABLE=true
+
+# Optional: Filter allowed users
+SLACK_ALLOWED_EMAIL_DOMAINS=company.com,partner.com  # Comma-separated email domains
+SLACK_ALLOWED_USER_IDS=U12345678,U87654321           # Comma-separated user IDs to always allow
+```
+
+### User Filtering
+
+By default, all Slack users can interact with the bot. To restrict access:
+
+- **Email domains**: Only users with matching email domains can send messages
+- **User ID whitelist**: Specific user IDs are always allowed (useful for admins or service accounts)
+
+If both are set, a user must match **either** an allowed domain **or** be in the user ID whitelist.
+
+---
+
+## GitHub App Integration
+
+Enable GitHub webhooks for automated task creation from PR reviews and issue assignments.
+
+### Setup
+
+1. Create a GitHub App at https://github.com/settings/apps/new
+2. Set webhook URL to your server: `https://your-server.com/github/webhook`
+3. Generate a webhook secret
+4. (Optional) Generate a private key for bot reactions
+
+### Configuration
+
+```bash
+# Required for GitHub webhooks
+GITHUB_WEBHOOK_SECRET=your-webhook-secret
+
+# Optional: Disable GitHub integration
+GITHUB_DISABLE=true
+
+# Optional: Bot name for @mentions (default: agent-swarm-bot)
+GITHUB_BOT_NAME=your-bot-name
+
+# Optional: Enable bot reactions (requires GitHub App)
+GITHUB_APP_ID=123456
+GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----
+# Or use base64-encoded private key:
+GITHUB_APP_PRIVATE_KEY=base64-encoded-key
+```
+
+### Supported Events
+
+| Event | Action |
+|-------|--------|
+| PR assigned to bot | Creates task for lead agent |
+| Review requested from bot | Creates review task |
+| PR/Issue comment @mentioning bot | Creates task with context |
+| Issue assigned to bot | Creates task for lead agent |
+
+### Bot Reactions
+
+If GitHub App credentials are provided, the bot can react to comments/issues to acknowledge receipt.
+
+---
+
+## Sentry Integration
+
+Docker workers include `sentry-cli` pre-installed, enabling agents to investigate and triage Sentry issues directly.
+
+### Setup
+
+1. Create an Organization Auth Token at `https://sentry.io/settings/{org}/auth-tokens/` with scopes:
+   - `event:read` - Read issues and events
+   - `project:read` - Read project data
+   - `org:read` - Read organization info
+
+2. Add to `.env.docker` or `.env`:
+   ```bash
+   SENTRY_AUTH_TOKEN=your-auth-token
+   SENTRY_ORG=your-org-slug
+   ```
+
+3. Verify authentication in a worker:
+   ```bash
+   sentry-cli info
+   ```
+
+### Agent Commands
+
+| Command | Description |
+|---------|-------------|
+| `/investigate-sentry-issue <url-or-id>` | Investigate a Sentry issue, get stacktrace, and triage |
+
+### Usage
+
+Workers can use the `/investigate-sentry-issue` command to:
+- Get issue details and stacktraces
+- Analyze breadcrumbs and context
+- Resolve, mute, or unresolve issues
+
+Example:
+```
+/investigate-sentry-issue https://sentry.io/organizations/myorg/issues/123456/
+```
+
+Or just the issue ID:
+```
+/investigate-sentry-issue 123456
+```
 
 ---
 
@@ -319,14 +533,14 @@ bunx @desplega.ai/agent-swarm lead --system-prompt-file ./prompts/coordinator.tx
 docker run --rm -it \
   -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
   -e API_KEY=your-api-key \
-  -e WORKER_SYSTEM_PROMPT="You are a Python specialist." \
+  -e SYSTEM_PROMPT="You are a Python specialist." \
   ghcr.io/desplega-ai/agent-swarm-worker
 
 # Using system prompt file
 docker run --rm -it \
   -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
   -e API_KEY=your-api-key \
-  -e WORKER_SYSTEM_PROMPT_FILE=/workspace/prompts/specialist.txt \
+  -e SYSTEM_PROMPT_FILE=/workspace/prompts/specialist.txt \
   -v ./work:/workspace \
   ghcr.io/desplega-ai/agent-swarm-worker
 ```
@@ -334,7 +548,7 @@ docker run --rm -it \
 ### Priority
 
 - CLI flags > Environment variables
-- Inline text (`*_SYSTEM_PROMPT`) > File (`*_SYSTEM_PROMPT_FILE`)
+- Inline text (`SYSTEM_PROMPT`) > File (`SYSTEM_PROMPT_FILE`)
 
 ---
 

package/Dockerfile.worker

@@ -30,7 +30,7 @@ RUN apt-get update && apt-get install -y \
     # Python
     python3 python3-pip python3-venv \
     # Common utilities
-    jq tree htop unzip zip tar gzip \
+    jq tree htop unzip zip tar gzip sqlite3 \
     # Network tools
     openssh-client \
     # sudo for package installation
@@ -42,9 +42,6 @@ RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
     && apt-get install -y nodejs \
     && rm -rf /var/lib/apt/lists/*
 
-# Install PM2 globally for process management
-RUN npm install -g pm2
-
 # Install GitHub CLI
 RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
     && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
@@ -102,6 +99,26 @@ USER root
 COPY --from=builder /build/agent-swarm /usr/local/bin/agent-swarm
 RUN chmod +x /usr/local/bin/agent-swarm
 
+# Install step (at the end to leverage caching)
+
+# Install PM2 globally for process management
+RUN npm install -g pm2
+
+# Install ai-tracker for tracking AI vs human code changes
+RUN pip3 install --break-system-packages cc-ai-tracker
+
+# Install wts (git worktree manager) globally for agents
+RUN npm install -g @desplega.ai/wts@latest
+
+# Install sentry-cli for issue investigation
+RUN npm install -g @sentry/cli
+
+# Install qa-use (QA tool) globally
+RUN npm install -g @desplega.ai/qa-use@latest
+
+# Install qa-use dependencies
+RUN qa-use install-deps
+
 # Copy commands
 COPY --chown=worker:worker plugin/commands/* /home/worker/.claude/commands/
 COPY --chown=worker:worker plugin/agents/* /home/worker/.claude/agents/

package/MCP.md

@@ -14,6 +14,13 @@
   - [get-task-details](#get-task-details)
   - [store-progress](#store-progress)
   - [my-agent-info](#my-agent-info)
+  - [cancel-task](#cancel-task)
+  - [slack-reply](#slack-reply)
+  - [slack-read](#slack-read)
+  - [slack-post](#slack-post)
+  - [slack-list-channels](#slack-list-channels)
+  - [inbox-delegate](#inbox-delegate)
+  - [get-inbox-message](#get-inbox-message)
 - [Task Pool Tools](#task-pool-tools)
   - [task-action](#task-action)
 - [Messaging Tools](#messaging-tools)
@@ -28,6 +35,12 @@
   - [unregister-service](#unregister-service)
   - [list-services](#list-services)
   - [update-service-status](#update-service-status)
+- [Scheduling Tools](#scheduling-tools)
+  - [list-schedules](#list-schedules)
+  - [create-schedule](#create-schedule)
+  - [update-schedule](#update-schedule)
+  - [delete-schedule](#delete-schedule)
+  - [run-schedule-now](#run-schedule-now)
 
 ---
 
@@ -121,6 +134,78 @@ Returns your agent ID based on the X-Agent-ID header.
 
 *No parameters*
 
+### cancel-task
+
+**Cancel Task**
+
+Cancel a task that is pending or in progress. Only the lead or task creator can cancel tasks. The worker will be notified via hooks.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `taskId` | `uuid` | Yes | - | The ID of the task to cancel. |
+| `reason` | `string` | No | - | Reason for cancellation. |
+
+### slack-reply
+
+**Reply to Slack thread**
+
+Send a reply to a Slack thread. Use inboxMessageId for inbox messages, or taskId for task-related threads.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `message` | `string` | Yes | - | The message to send to the Slack thread. |
+
+### slack-read
+
+**Read Slack thread/channel history**
+
+Read messages from a Slack thread or channel. Use inboxMessageId or taskId to read from a thread you have context for, or provide channelId directly for channel history (leads only).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `inboxMessageId` | `uuid` | No | - | Read thread history for an inbox message. |
+| `taskId` | `uuid` | No | - | Read thread history for a task. |
+
+### slack-post
+
+**Post new message to Slack channel**
+
+Post a new message to a Slack channel. This creates a new message (not a thread reply). Requires lead privileges.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `channelId` | `string` | Yes | - | The Slack channel ID to post to. |
+| `message` | `string` | Yes | - | The message content to post. |
+
+### slack-list-channels
+
+**List Slack channels**
+
+List Slack channels the bot is a member of. Use this to discover available channels for reading messages.
+
+*No parameters*
+
+### inbox-delegate
+
+**Delegate inbox message to worker**
+
+Delegate an inbox message to a worker agent by creating a task. The task inherits Slack context for replies.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `inboxMessageId` | `uuid` | Yes | - | The inbox message ID to delegate. |
+| `agentId` | `uuid` | Yes | - | The worker agent to delegate to. |
+
+### get-inbox-message
+
+**Get inbox message details**
+
+Returns detailed information about a specific inbox message, including full content and Slack context. Only accessible to the lead agent who owns the message.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `inboxMessageId` | `uuid` | Yes | - | The ID of the inbox message to retrieve. |
+
 ## Task Pool Tools
 
 *Messaging*
@@ -191,10 +276,11 @@ Reads messages from a channel. If no channel is specified, returns unread messag
 
 **Update Profile**
 
-Updates the calling agent's profile information (description, role, capabilities).
+Updates the calling agent's profile information (name, description, role, capabilities).
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
+| `name` | `string` | No | - | Agent name. |
 | `description` | `string` | No | - | Agent description. |
 
 ## Services Tools
@@ -247,3 +333,74 @@ Update the health status of a registered service. Use this after a service becom
 | `serviceId` | `uuid` | No | - | Service ID to update. |
 | `name` | `string` | No | - | Service name to update (alternative to serviceId). |
 
+## Scheduling Tools
+
+*Scheduling*
+
+### list-schedules
+
+**List Scheduled Tasks**
+
+View all scheduled tasks with optional filters. Use this to discover existing schedules.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `enabled` | `boolean` | No | - | Filter by enabled status |
+| `name` | `string` | No | - | Filter by name (partial match) |
+
+### create-schedule
+
+**Create Scheduled Task**
+
+Create a new scheduled task that will automatically create agent tasks at specified intervals. Either cronExpression or intervalMs must be provided.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `description` | `string` | No | - | Human-readable description of the schedule |
+| `tags` | `array` | No | - | Tags to apply to created tasks |
+| `timezone` | `string` | No | "UTC" | Timezone for cron schedules |
+
+### update-schedule
+
+**Update Scheduled Task**
+
+Update an existing scheduled task. Only the creator or lead agent can update schedules.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `scheduleId` | `string` | No | - | Schedule ID to update |
+| `name` | `string` | No | - | Schedule name to update (alternative to ID) |
+| `newName` | `string` | No | - | New name for the schedule |
+| `taskTemplate` | `string` | No | - | New task template |
+| `cronExpression` | `string` | No | - | New cron expression |
+| `intervalMs` | `number` | No | - | New interval in milliseconds |
+| `description` | `string` | No | - | New description |
+| `taskType` | `string` | No | - | New task type |
+| `tags` | `array` | No | - | New tags |
+| `priority` | `number` | No | - | New priority |
+| `targetAgentId` | `string` | No | - | New target agent ID |
+| `timezone` | `string` | No | - | New timezone |
+| `enabled` | `boolean` | No | - | Enable or disable the schedule |
+
+### delete-schedule
+
+**Delete Scheduled Task**
+
+Delete a scheduled task permanently. Only the creator or lead agent can delete schedules.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `scheduleId` | `string` | No | - | Schedule ID to delete |
+| `name` | `string` | No | - | Schedule name to delete (alternative to ID) |
+
+### run-schedule-now
+
+**Run Schedule Now**
+
+Immediately execute a scheduled task, creating a task right away. Does not affect the regular schedule timing.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `scheduleId` | `string` | No | - | Schedule ID to run |
+| `name` | `string` | No | - | Schedule name to run (alternative to ID) |
+

package/README.md

@@ -52,6 +52,81 @@ The dashboard runs at `http://localhost:5173` by default.
 
 ---
 
+## GitHub Integration
+
+Agent Swarm can receive tasks from GitHub via webhooks. When someone mentions `@agent-swarm-bot` (or your configured bot name) in an issue, PR, or comment, a task is automatically created for the lead agent.
+
+### Setup
+
+1. Create a GitHub App at https://github.com/settings/apps/new
+2. Set the webhook URL to `https://your-server.com/api/github/webhook`
+3. Generate a webhook secret and add to `.env`:
+   ```bash
+   GITHUB_WEBHOOK_SECRET=your-secret
+   GITHUB_BOT_NAME=agent-swarm-bot  # optional, default: agent-swarm-bot
+   ```
+4. Enable webhook events: Issues, Issue comment, Pull request, Pull request review comment
+5. Install the app on your repositories
+
+### Agent Commands
+
+| Command | Description |
+|---------|-------------|
+| `/implement-issue` | Read issue, implement changes, create PR |
+| `/review-pr` | Analyze and review a pull request |
+| `/create-pr` | Create PR from current branch changes |
+| `/close-issue` | Close issue with summary comment |
+| `/respond-github` | Comment on an issue or PR |
+
+---
+
+## Sentry Integration
+
+Docker workers include `sentry-cli` pre-installed, enabling agents to investigate and triage Sentry issues directly. This is useful for debugging errors reported via Slack alerts.
+
+### Setup
+
+1. Create an Organization Auth Token at `https://sentry.io/settings/{org}/auth-tokens/` with scopes:
+   - `event:read` - Read issues and events
+   - `project:read` - Read project data
+   - `org:read` - Read organization info
+
+2. Add to `.env.docker`:
+   ```bash
+   SENTRY_AUTH_TOKEN=your-auth-token
+   SENTRY_ORG=your-org-slug
+   ```
+
+3. Verify authentication in a worker:
+   ```bash
+   sentry-cli info
+   ```
+
+### Agent Commands
+
+| Command | Description |
+|---------|-------------|
+| `/investigate-sentry-issue <url-or-id>` | Investigate a Sentry issue, get stacktrace, and triage |
+
+### Usage
+
+Workers can use the `/investigate-sentry-issue` command to:
+- Get issue details and stacktraces
+- Analyze breadcrumbs and context
+- Resolve, mute, or unresolve issues
+
+Example:
+```
+/investigate-sentry-issue https://sentry.io/organizations/myorg/issues/123456/
+```
+
+Or just the issue ID:
+```
+/investigate-sentry-issue 123456
+```
+
+---
+
 ## Quick Start
 
 The recommended setup: run the API locally, run a Docker worker, and connect Claude Code as the lead agent.