Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
207 changes: 207 additions & 0 deletions examples/08-slack-to-pr/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
# 08: Slack to PR

Mention the factory in one Slack channel to request a code change. Progress,
questions, and the pull request link stay in the same thread; a human reviews
and merges. This example replaces the intake in
[`01-single-repo-quickstart`](../01-single-repo-quickstart) with Slack mentions.

## What it demonstrates

- A `slack` / `app_mention` trigger scoped to one channel with the `channels`
alias, and what Warp does with mentions that fall outside it.
- The `integrations` list declaring Slack, and the setup the files cannot do
for you: installing the app, inviting it to the channel, linking accounts.
- The thread as the work item's home. The acknowledgement, any clarifying
question, and the result all land in the thread that started the work,
and plain replies there continue it.
- A foreman prompt that confirms the deliverable before work starts and asks
one question instead of guessing.
- Two agents and one runner; both agents inherit `model` and `runner` from
`agentDefaults`.

## Tree

```
factory.yaml integrations: slack; one repository
agents/
foreman/agent.md FOREMAN, confirms in the thread, dispatches, reports the PR
implementer/agent.md IMPLEMENT, turns the request into a PR
automations/
slack-intake/automation.md slack/app_mention, filtered to your-intake-channel
runners/
linux-small.yaml 2 vCPU / 4 GB, node:22-bookworm-slim
```

## How Slack intake is routed

The one automation subscribes to `slack` / `app_mention` and filters on
`channels: [your-intake-channel]`:

- `app_mention` fires when someone @-mentions the factory's Slack app in a
channel the app has joined. Plain channel messages, direct messages, and
reactions are different events and never match this trigger.
- `channels` is the authoring alias for `channel_ids`. It takes exact channel
names, with or without a leading `#`, and Warp resolves each name through
the team's Slack connection when the definition is applied. A name must
resolve to exactly one channel the app can see, so invite the app before
the definition syncs. The validator defers this lookup and passes with the
placeholder in place; the apply is what fails on an unresolved name.
- Filter keys combine with AND and an absent key is a wildcard. `app_mention`
also accepts `users` (Slack usernames or email addresses) and `keywords`
(case-insensitive substrings of the message), so `keywords: [please]` or
`users: [alex@example.com]` would narrow intake further. See the
[trigger reference](https://docs.warp.dev/factories/automation-triggers/)
for the full key list.

What happens to Slack activity this definition does not match:

- **A mention in any other channel** does not match this automation, so
this route adds no 👀 reaction, reply, or work item. Other automations may
still handle it.
- **A direct message** is a `message_dm` event, which this definition does
not subscribe to, so this route starts nothing. Add a `message_dm`
automation like [`02-sdlc-issue-to-pr`](../02-sdlc-issue-to-pr) if DMs
should count.
- **A plain reply in a thread that already has a work item** can continue
that work item without a new mention: Warp classifies whether the reply is
meant for the factory, and the automation's filter is not consulted again.
To require a mention for replies too, set
`slack.autoRespondToThreadReplies: false` on the integration entry:

```yaml
integrations:
- type: slack
slack:
autoRespondToThreadReplies: false
```

Two cautions when you extend this. A channel message that mentions the app
also emits `app_mention`, so adding a `message_posted` trigger on the same
channel starts two runs per mention. And filters decide when work starts,
not what the app can read: its bot scopes cover history in every channel it
has joined, and the person mentioning the factory still has to have linked
their Slack account to a member of the factory's Warp team, or the app asks
them to connect one instead of starting work.

## Make it yours

1. Replace `acme/api-service` in `factory.yaml` with a repository your Warp
team's GitHub installation can reach. The agents never name the
repository; the factory has exactly one.
2. Connect Slack. Select Slack when you create the factory, or connect it
later from the factory's **Settings**; finish the install with **Add to
Slack** if your workspace needs administrator approval. The `integrations`
entry in `factory.yaml` declares that the factory uses Slack; it does not
connect it. Then invite the app to the intake channel. Private channels
always need an invitation.
Inspect existing automations: reuse or narrow an `app_mention` handler,
and avoid a `message_posted` handler that also matches the same mentions.
Preserve unrelated triggers.
3. Replace `your-intake-channel` in `automations/slack-intake/automation.md`
with that channel's name. Do step 2 first: the name is resolved against
the Slack connection when the definition is applied, and an unresolved
name fails the apply.
4. Link accounts. Everyone who will mention the factory must link their Slack
account to their Warp account; the app prompts them the first time they
mention it, and connecting the app does not link anyone. Work is
attributed to the linked Warp user.
5. Adjust `alias` in `factory.yaml`; it is the handle the app answers to in
Slack, written as `@Intake` below.
6. Swap the runner's `dockerImage` for your stack, and optionally change
`agentDefaults.model` (any Warp Agent model ID).

To register the definition, create a factory in Warp with a GitHub-backed
definition pointing at your copy of this directory. The registered root is
the directory containing `factory.yaml`; pushes to the production branch sync
it after the `warp/factory-config` check passes. The
[Slack integration docs](https://docs.warp.dev/factories/integrations/slack/)
cover the install, channel invitations, and account linking in detail.

## Sample task and expected output

The sample assumes `acme/api-service` is a Node service with an HTTP router
and a test script the runner image can run (`npm test`). Any repository
works as long as the runner image carries its toolchain.

In `#your-intake-channel`:

> @Intake add a `GET /healthz` route that returns `{"status":"ok"}` with a
> 200, and a test that covers it.

What you should see, in order:

1. The app reacts to the message with 👀, and a work item appears in the
factory dashboard.
2. The foreman replies in the thread with one sentence restating the
deliverable, along the lines of "Adding a `GET /healthz` route that
returns `{"status":"ok"}` with a 200, plus a test; the PR will land in
this thread."
3. A branch named like `factory/healthz-route` appears on `acme/api-service`
with a pull request against the default branch. The description links the
Slack thread and includes the test command and its result.
4. The foreman replies in the same thread with the PR link and how the change
was verified. Nobody merges; a human reviews the PR.

Two more mentions worth sending on a first run:

- The same request in a channel that is not `#your-intake-channel`: nothing
happens. No reaction, no reply, no work item.
- `@Intake make the API faster`: the foreman replies with one clarifying
question, such as which endpoint is slow and what response time counts as
fixed, and stops. No branch, no PR. Answer in the thread; the reply
continues the same work item.

A request the factory cannot act on, such as a change to a repository that
is not attached or something that is not a code change, gets a one-sentence
reply saying so, and the foreman stops. A mention that is not a request at
all, such as a thank-you, gets no reply.

## Validate it

From the repository root:

```bash
python3 scripts/validate_factory_files.py examples/08-slack-to-pr
```

This runs Warp's parser over the tree, so a misspelled event name or an
unsupported filter key fails here. The channel name is reported as a
deferred resolution, not a failure. The `warp/factory-config` check on your
definition pull request dry-runs the change against your team, and the
apply resolves the name through your Slack connection; those are where an
unresolved name fails.

A first real run should prove four things: a mention in the intake channel
gets a 👀 and a one-sentence acknowledgement in the thread; the same thread
ends with a PR link; a mention in another channel starts nothing; and a
vague mention gets one question and no PR.

## Set it up with a prompt

Paste this into any agent that can edit your definition repository and reach
Warp's validation service:

- the factory's foreman, in a Slack thread or from the factory dashboard,
- the factory web composer, or
- Factory MCP, from a connected coding agent such as the Warp Agent.

Fill in the four values first.

```text title="Set up Slack intake for my repository"
Read the example at
https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/08-slack-to-pr
and set up the same factory for my repository. Copy its tree into my
definition repository and replace these placeholders:

- acme/api-service in factory.yaml -> <owner/repository>
- your-intake-channel in automations/slack-intake/automation.md -> <#channel>
- alias: Intake in factory.yaml -> <handle the app should answer to>
- node:22-bookworm-slim in runners/linux-small.yaml -> <image with my toolchain>

Keep the single-channel app_mention trigger, the foreman and implementer
agents, and the one runner. Reuse or narrow existing handlers so a mention
matches only one route, preserving unrelated triggers. Validate the
definition and open a pull request without applying it.
List what I still have to do by hand: connect Slack to the factory, invite
the app to the channel, and have each requester link their Slack account.
```
41 changes: 41 additions & 0 deletions examples/08-slack-to-pr/agents/foreman/agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
description: Entry point for Slack intake. Confirms the request in its thread, dispatches implementation, reports the PR back.
agentType: FOREMAN
---
# Foreman

Handle Slack mentions and requester communication in the original thread.
Delegate code changes to the implementation agent and report its result;
do not implement yourself.

## Input
- The Slack message that mentioned the factory, the thread it is in, and the
requester's Slack identity.

## Output
- A reply in the originating thread that restates the deliverable, then a
reply in the same thread with the pull request link when the work is done.
Every message you send goes in that thread; never post at the channel's top
level or in a different channel.

## Procedure
1. Read the message and its thread. If the mention is not a request at all (a
thank-you, chatter, a question meant for a human), stop silently.
2. If it is a request this factory cannot act on, such as a change to a
repository that is not attached to it, or something that is not a code
change, say so in the thread in one sentence and stop.
3. Restate the request as one concrete deliverable. If you cannot, or
something you need is missing (which component, which behavior, what
"done" looks like), ask exactly one clarifying question in the thread and
stop. Do not guess; the requester's reply in the thread continues this
work item.
4. Reply in the thread with the deliverable in one sentence before any work
starts, so the requester can correct you early.
5. Dispatch the implementation agent with the request in the requester's
exact words, the thread link, and the requester's Slack user ID.
6. When it reports back, verify the pull request exists and links the thread,
then reply in the thread with the PR link and how the change was verified.
If it reports that it could not finish, relay the reason in the thread and
stop.

A human always reviews and merges the pull request. Never merge.
28 changes: 28 additions & 0 deletions examples/08-slack-to-pr/agents/implementer/agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
description: Turns a Slack request into a reviewable pull request.
agentType: IMPLEMENT
---
# Implementation

Implement and verify the Slack deliverable, then open a PR for human review.
Report to the foreman only; it handles requester communication.

## Input
- From the foreman: the request in the requester's words, the Slack thread
link, and the requester's Slack user ID.

## Output
- A pull request against the default branch, from a branch named
`factory/<short-slug>`, containing the change, tests for the changed
behavior, and a description that links the Slack thread and states how the
change was verified.
- A completion report to the foreman with the PR link and the test evidence,
or the reason you could not finish.

## Procedure
1. Read the referenced code before writing anything.
2. Keep the change scoped to the deliverable the foreman gave you. If it
grows, report back instead of expanding the PR.
3. Run the repository's tests and linters. Put the commands and their results
in the PR description.
4. Open the PR and report back.
12 changes: 12 additions & 0 deletions examples/08-slack-to-pr/automations/slack-intake/automation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
triggers:
- provider: slack
event: app_mention
filter:
channels: [your-intake-channel]
---
Someone @-mentioned the factory in the intake channel. Treat the message and
its thread as a work request for this factory's repository. Reply in the same
thread with one sentence that restates the deliverable, drive it to a pull
request, and post the PR link back in that thread. If the request is too
vague to restate, ask one clarifying question in the thread and stop.
16 changes: 16 additions & 0 deletions examples/08-slack-to-pr/factory.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
schemaVersion: v1alpha1
name: slack-to-pr
description: >-
Work intake from Slack: an @-mention in one designated channel starts a
task, the foreman confirms the request in the thread, an implementation
agent opens a pull request, and the foreman reports the PR link back in
that same thread.
alias: Intake
repositories:
- owner: acme
name: api-service
integrations:
- type: slack
agentDefaults:
model: auto
runner: linux-small
12 changes: 12 additions & 0 deletions examples/08-slack-to-pr/runners/linux-small.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
description: >-
Small runner for a single Node service. The image provides the toolchain:
node:22-bookworm-slim already has Node and npm, so no setup command has to
install them. Swap the image for whatever your repository builds with.
instanceShape:
vcpus: 2
memoryGb: 4
platform:
os: linux
arch: x86_64
linux:
dockerImage: node:22-bookworm-slim
Loading