How to Build an AI Agent Workspace Template That Connects to Linear, GitHub, and Slack

The three-tool loop every dev team runs manually

Every software team using Linear, GitHub, and Slack follows some version of the same loop:

Linear                    GitHub                   Slack
  |                         |                        |
  |  Issue moves to         |                        |
  |  "In Progress"          |                        |
  |  ---------------------->|  Create feature branch  |
  |                         |  ---------------------->| "Branch created for
  |                         |                        |  LIN-423: Add search"
  |                         |                        |
  |                         |  PR opened             |
  |                         |  ---------------------->| "PR #87 ready for
  |                         |                        |  review"
  |                         |                        |
  |                         |  PR merged             |
  |  Status -> "Done"  <----|                        |
  |                         |  ---------------------->| "LIN-423 shipped!"

The pattern is universal. The execution is manual. Someone drags the Linear card, creates the branch by hand, copies the PR link into Slack, and updates the issue when the PR merges. Multiply that by 20 issues a week across a 6-person team and you are looking at hours of pure coordination overhead.

An AI agent that connects all three tools eliminates the busywork. This guide shows you how to build one as a reusable workspace template.

What you are building

A workspace template that gives an AI agent access to Linear, GitHub, and Slack through MCP servers, with a SOUL.md that defines how the agent coordinates work across all three. The template is portable -- anyone can download it, plug in their API keys, and have a working dev workflow agent in minutes.

Template directory structure

dev-workflow-agent/
├── SOUL.md                      # Agent personality + workflow rules
├── AGENTS.md                    # Agent capabilities and boundaries
├── skills/
│   ├── issue-to-branch.md       # Linear issue → GitHub branch
│   ├── pr-notifications.md      # PR events → Slack messages
│   ├── status-sync.md           # GitHub merge → Linear status update
│   └── standup-summary.md       # Daily standup digest
├── .openclaw/
│   └── mcp.json                 # MCP server configs for all 3 services
├── .env.example                 # Required API keys and config
└── README.md                    # Setup and usage instructions

Setting up the MCP servers

The foundation of the template is the MCP configuration. Each service gets its own MCP server entry in .openclaw/mcp.json:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@linear/mcp-server"],
      "env": {
        "LINEAR_API_KEY": "${LINEAR_API_KEY}"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

With this configuration, your agent gains access to tools across all three services:

Linear tools:

• linear_create_issue -- Create new issues with title, description, team, priority
• linear_update_issue -- Change status, assignee, labels
• linear_search_issues -- Query issues by filter criteria
• linear_list_teams -- Enumerate available teams and their workflows

GitHub tools:

• create_branch -- Create a branch from a base ref
• create_pull_request -- Open a PR with title, body, and reviewers
• list_pull_requests -- Query PRs by state and filters
• merge_pull_request -- Merge a PR with specified strategy
• search_repositories -- Find repos by name or topic

Slack tools:

• slack_post_message -- Send a message to a channel
• slack_reply_to_thread -- Reply in a thread
• slack_list_channels -- Enumerate available channels
• slack_add_reaction -- Add an emoji reaction to a message

Environment variables

# .env.example
LINEAR_API_KEY=lin_api_...          # Linear > Settings > API > Personal API keys
GITHUB_TOKEN=ghp_...                # GitHub > Settings > Developer settings > Personal access tokens
SLACK_BOT_TOKEN=xoxb-...            # Slack App > OAuth & Permissions > Bot User OAuth Token

# Workflow configuration
LINEAR_TEAM_ID=TEAM-123             # Your Linear team identifier
GITHUB_ORG=your-org                 # GitHub organization or username
GITHUB_REPO=your-repo               # Default repository
SLACK_CHANNEL_ENGINEERING=#eng      # Primary notification channel
SLACK_CHANNEL_RELEASES=#releases    # Release notification channel

Writing the SOUL.md

The SOUL.md defines who the agent is, what it does, and -- critically -- what it must not do. For a dev workflow agent touching three services, guardrails matter.

# Dev Workflow Agent

You are a development workflow agent for {{GITHUB_ORG}}.
You coordinate work across Linear (project management),
GitHub (code), and Slack (communication).

## Core responsibilities
- When a Linear issue moves to "In Progress", create a
  corresponding GitHub branch using the naming convention:
  `feature/LIN-{number}-{slugified-title}`
- When a GitHub PR is opened, post a notification to
  {{SLACK_CHANNEL_ENGINEERING}} with the PR title, link,
  and associated Linear issue
- When a GitHub PR is merged to main, update the corresponding
  Linear issue status to "Done" and post to
  {{SLACK_CHANNEL_RELEASES}}
- Generate daily standup summaries: what was completed
  yesterday, what is in progress today, any blockers

## Workflow rules
- ALWAYS use the branch naming convention exactly as specified
- ALWAYS link PRs back to Linear issues using
  "Closes LIN-{number}" in the PR description
- NEVER merge PRs -- only humans merge
- NEVER reassign issues without explicit user instruction
- NEVER post to channels outside {{SLACK_CHANNEL_ENGINEERING}}
  and {{SLACK_CHANNEL_RELEASES}} unless asked
- NEVER modify issue priority or labels autonomously

## Error handling
- If a GitHub branch creation fails (e.g., branch already
  exists), notify the assignee via Slack DM
- If a Slack post fails, retry once, then log the failure
  and continue
- If a Linear API call fails, report the error in
  {{SLACK_CHANNEL_ENGINEERING}} with the issue ID

## Tone
Concise and factual. Use the same voice as a well-written
commit message. No emoji in Slack posts unless the team
culture calls for it.

Building the workflow skills

Each skill encodes a specific automation pattern. Writing them as separate files keeps the template modular -- teams can pick the workflows they want and ignore the rest.

Skill 1: Issue-to-branch automation

# Issue to Branch

## Trigger
When a Linear issue is moved to "In Progress" status.

## Steps
1. Get the issue details from Linear:
   - Issue number (e.g., LIN-423)
   - Issue title
   - Assignee
2. Slugify the title: lowercase, replace spaces with hyphens,
   remove special characters, truncate to 50 chars
3. Create branch name: `feature/LIN-{number}-{slug}`
4. Create the branch on GitHub from `main`
5. Post to Slack:

Branch feature/LIN-423-add-full-text-search created for @assignee. Issue: LIN-423 Add full-text search.

6. Add a comment on the Linear issue with the branch name

## Example
Issue: LIN-423 "Add full-text search to dashboard"
Branch: `feature/LIN-423-add-full-text-search`

Skill 2: PR notification pipeline

# PR Notifications

## Trigger
When a GitHub pull request is opened, updated, or merged.

## On PR Opened
1. Extract PR title, number, author, and branch name
2. Parse Linear issue ID from branch name
   (e.g., `feature/LIN-423-...` → LIN-423)
3. Fetch issue details from Linear for context
4. Post to {{SLACK_CHANNEL_ENGINEERING}}:

PR #87 opened by @author: "Add full-text search" Linear: LIN-423 | Branch: feature/LIN-423-add-full-text-search Review: https://github.com/org/repo/pull/87

5. Update Linear issue status to "In Review"

## On PR Merged
1. Parse Linear issue ID from the PR branch
2. Update Linear issue status to "Done"
3. Post to {{SLACK_CHANNEL_RELEASES}}:

Shipped: LIN-423 "Add full-text search" (PR #87)

4. Archive the branch on GitHub

## On PR Review Requested
1. Notify the reviewer via Slack DM:

You have been requested to review PR #87: "Add full-text search" https://github.com/org/repo/pull/87

Skill 3: Status sync

# Status Sync

## Purpose
Keep Linear issue statuses in sync with GitHub activity.

## State Mapping
| GitHub Event              | Linear Status    |
|--------------------------|------------------|
| Branch created           | In Progress      |
| PR opened                | In Review        |
| PR changes requested     | In Progress      |
| PR approved              | In Review        |
| PR merged                | Done             |
| Branch deleted (no PR)   | Backlog          |

## Conflict Resolution
- If a human manually changes status in Linear,
  the human's change takes precedence
- Do not override a status that was changed within
  the last 5 minutes by a human user
- Log any sync conflicts to {{SLACK_CHANNEL_ENGINEERING}}

Skill 4: Standup summary

# Daily Standup Summary

## Schedule
Run at 9:00 AM local time on weekdays.

## Process
1. Query Linear for all issues updated in the last 24 hours
   across {{LINEAR_TEAM_ID}}
2. Group by status change:
   - **Completed**: Issues moved to "Done" yesterday
   - **In Progress**: Issues currently "In Progress" or "In Review"
   - **Blocked**: Issues with "blocked" label or stale
     in "In Progress" for >3 days
3. For each in-progress item, check GitHub for recent commits
   and open PRs
4. Post summary to {{SLACK_CHANNEL_ENGINEERING}}:

## Output Format

Standup Summary — March 23, 2026

✅ Completed (3) • LIN-423 Add full-text search (PR #87 merged) • LIN-419 Fix pagination bug (PR #85 merged) • LIN-421 Update API docs (PR #86 merged)

🔄 In Progress (2) • LIN-425 Refactor auth module (@alice, PR #89 open) • LIN-426 Add export feature (@bob, branch created)

🚫 Blocked / Stale (1) • LIN-420 Migrate database (no activity for 4 days)

The event-driven architecture

The real power of this template emerges when you connect the skills into an event-driven pipeline. Here is the full flow:

Linear Issue Created
        |
        v
[Agent monitors Linear webhook / polling]
        |
        v
Issue moved to "In Progress"
        |
        +----> Create GitHub branch (issue-to-branch skill)
        |              |
        |              +----> Post to Slack (pr-notifications skill)
        |              |
        |              +----> Comment on Linear issue
        |
        v
Developer pushes commits
        |
        v
PR opened on GitHub
        |
        +----> Parse Linear issue from branch name
        |              |
        |              +----> Update Linear status to "In Review"
        |              |
        |              +----> Post PR link to Slack
        |
        v
PR reviewed and merged
        |
        +----> Update Linear status to "Done"
        |              |
        |              +----> Post to #releases Slack channel
        |              |
        |              +----> Archive GitHub branch
        |
        v
[Daily standup skill aggregates everything]

Each arrow represents a single agent action using exactly one MCP tool call. The agent does not need complex orchestration logic -- the SOUL.md workflow rules and individual skills handle the sequencing.

Advanced patterns

Multi-repository support

Many teams work across multiple repos. Extend the template by adding a mapping skill:

# Repository Routing

## Linear Team to GitHub Repo Mapping
| Linear Team   | GitHub Repository     |
|--------------|-----------------------|
| Frontend     | org/frontend-app      |
| Backend      | org/api-server        |
| Mobile       | org/mobile-app        |
| Infra        | org/infrastructure    |

## Routing Rules
- When creating a branch for a Linear issue, check the
  issue's team to determine which GitHub repository to use
- If the issue spans multiple teams, use the primary team's
  repository
- If the team is not in the mapping, ask the user which
  repository to use

Custom label automation

# Label Sync

## Purpose
Mirror GitHub PR labels to Linear issue labels and vice versa.

## Rules
- When a GitHub PR receives a "needs-design-review" label,
  add a "Design Review" tag to the corresponding Linear issue
- When a Linear issue is labeled "urgent", add "priority:high"
  to the corresponding GitHub PR
- When a Linear issue moves to "Done", remove the "in-progress"
  label from the GitHub PR if it exists

Sprint reporting

For teams running sprints, add a weekly summary skill:

# Sprint Report

## Schedule
Run every Friday at 4:00 PM.

## Process
1. Query Linear for the active cycle/sprint
2. Calculate:
   - Total issues in sprint
   - Completed issues
   - Remaining issues
   - Velocity (story points completed)
3. Query GitHub for:
   - PRs merged this week
   - Average time from PR open to merge
   - Number of review cycles per PR
4. Post formatted report to {{SLACK_CHANNEL_ENGINEERING}}

Handling webhooks vs. polling

There are two approaches to triggering agent actions from external events:

Approach 1: Webhook-driven (recommended for managed hosting)

If you deploy the template on managed hosting infrastructure, you can register webhooks with each service:

• Linear webhook: issue.updated events notify the agent when issues change status
• GitHub webhook: pull_request and push events trigger PR notification and status sync skills
• Slack Events API: message events let the agent respond to direct mentions

The webhook approach gives you real-time responsiveness with minimal API calls.

Approach 2: Polling (works anywhere)

For local development or environments without webhook support, the agent can poll each service on an interval:

# Polling Configuration

## Intervals
- Linear: Check for status changes every 2 minutes
- GitHub: Check for new PRs and merges every 3 minutes
- Slack: Check for mentions every 1 minute

## Rate Limit Awareness
- Linear API: 1,500 requests/hour (comfortable with 2-min polling)
- GitHub API: 5,000 requests/hour (comfortable with 3-min polling)
- Slack API: Tier 3 methods at ~50 requests/minute

Polling is simpler to set up but introduces latency and consumes more API quota.

Testing the template

Before sharing your template, test each workflow path:

Manual test checklist

1. Issue-to-branch flow

   • Create a test issue in Linear
   • Move it to "In Progress"
   • Verify: GitHub branch created with correct naming
   • Verify: Slack notification posted
   • Verify: Linear comment added with branch name

2. PR notification flow

   • Open a PR from the test branch
   • Verify: Slack notification with PR link posted
   • Verify: Linear status changed to "In Review"

3. Merge and close flow

   • Merge the test PR
   • Verify: Linear status changed to "Done"
   • Verify: Slack release notification posted

4. Standup summary

   • Run the standup skill manually
   • Verify: Summary includes the test issue in "Completed"

5. Error handling

   • Try creating a branch that already exists
   • Verify: Agent posts error notification instead of crashing

Sharing the template

Once tested, package the template for distribution. The key is making sure no credentials are embedded:

# Verify no secrets leaked into the template
grep -r "sk_\|ghp_\|xoxb-\|lin_api_" . --include="*.md" --include="*.json"

# Push to the community marketplace
clawagora template push dev-workflow-agent:1.0.0

Other developers can then pull and configure it:

clawagora template pull dev-workflow-agent:1.0.0
cd dev-workflow-agent
cp .env.example .env
# Edit .env with their own API keys

Community platforms like ClawAgora make these templates discoverable. Someone searching for "Linear GitHub Slack agent" finds your template, pulls it, configures their keys, and has a working workflow agent without building anything from scratch.

When to use this template vs. native integrations

Linear, GitHub, and Slack all have built-in integrations with each other. The native Linear-GitHub integration creates branches and links PRs. The Slack-GitHub integration posts PR notifications. So why build an agent template?

Use native integrations when:

• You want simple, one-direction notifications
• Your workflow matches the default integration behavior exactly
• You do not need custom logic or conditional routing

Use an agent workspace template when:

• You need custom workflow rules (specific branch naming, conditional notifications, multi-repo routing)
• You want bidirectional sync with conflict resolution
• You need aggregated reporting (standup summaries, sprint reports)
• You want to extend the workflow later without rebuilding integrations
• Your team's process is non-standard and does not fit the built-in integration options

The agent template approach gives you a single place -- the SOUL.md and skills directory -- to define and evolve your workflow. When your process changes, you update the template instead of reconfiguring three separate integration dashboards.

FAQ

Why combine Linear, GitHub, and Slack in a single AI agent workspace?

These three tools form a complete development workflow loop: Linear manages issues and project planning, GitHub handles code and version control, and Slack provides real-time team communication. An AI agent that connects all three can automate the handoffs between them -- creating branches when issues move to "In Progress", posting PR links to the right Slack channel, and updating Linear status when PRs merge. Without integration, developers spend hours each week manually synchronizing state across these tools.

What is an MCP server and how does it connect to Linear, GitHub, and Slack?

MCP (Model Context Protocol) is a standardized interface that lets AI agents interact with external services through tool calls. Each MCP server wraps a specific API -- Linear, GitHub, or Slack -- and exposes it as a set of tools the agent can invoke. Instead of writing custom API integration code, you configure MCP servers in a JSON file and the agent gains access to create issues, open PRs, send messages, and more through a consistent interface.

Do I need API keys for all three services to use this template?

Yes. You will need a Linear API key (personal or OAuth token), a GitHub personal access token with repo scope, and a Slack Bot User OAuth Token with appropriate channel permissions. The template uses environment variable placeholders so you provide your own keys at install time -- nothing is hardcoded. Each service's required scopes and permissions are documented in the template README.

Can I customize the agent's behavior for my team's specific workflow?

Absolutely. The SOUL.md file defines the agent's personality, responsibilities, and guardrails. You can modify the workflow rules -- for example, changing which Linear states trigger branch creation, which Slack channels receive notifications, or what naming conventions to use for branches. The skills directory contains individual workflow scripts that you can edit, remove, or extend independently.

How does the agent handle errors, like a failed GitHub branch creation or Slack API rate limit?

The SOUL.md includes error handling guidelines that instruct the agent to retry transient failures, report persistent errors to a designated Slack channel, and never silently drop actions. For rate limits, the agent queues operations and retries with backoff. You can customize the retry behavior and error notification channel in the template configuration.