All jobs

Add a Custom Workflow Builder Step to a Slack Bolt App

Yes. An agent adds a custom step your Slack Bolt app serves to Workflow Builder: the manifest entry, an app.function handler, tests, and a PR with install steps.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the app first. In an app like slack-samples/bolt-js-getting-started-app, app.js is the whole program: an App in Socket Mode with SLACK_BOT_TOKEN and SLACK_APP_TOKEN, one app.message('hello', ...) listener that posts a section block with a button, one app.action('button_click', ...) that acknowledges and replies, and an async start on PORT or 3000. manifest.json declares a bot user, the scopes channels:history, chat:write and im:history, bot events message.channels and message.im, interactivity on, Socket Mode on and org_deploy_enabled true. package.json is type: module with @slack/bolt at ^5.1.0 (5.1.0 in the lock file) and a single start script; there is no test runner. AGENTS.md asks for no code comments and for the reason behind a change to go in the pull request description, and .github/workflows/dependencies.yml auto-merges Dependabot's patch and minor updates.

A custom step is a function the app serves to Workflow Builder. The agent adds send_greeting to a new functions section in manifest.json, with a title, a description, an input_parameters block of user_id (type slack#/types/user_id, required) and message (type string), and an output_parameters block with the posted message's timestamp, and subscribes the bot to the function_executed event, which is how Slack delivers a step run to the app. In code, app.function('send_greeting', async ({ inputs, complete, fail, client }) => ...) reads inputs.user_id and inputs.message, posts the message with client.chat.postMessage, which the existing chat:write scope covers, and calls complete with the outputs; the catch branch calls fail with the error message so the workflow shows why it stopped rather than hanging on a step that never finished.

To make the step testable without a workspace, the agent moves the listeners out of app.js into listeners/ (messages.js, actions.js, functions.js) with a register(app) entry point, the layout the Bolt starter template uses, so app.js keeps only the App construction and the start call. It adds node:test tests in tests/functions.test.js that invoke the step handler with fake inputs, a stub client.chat.postMessage, and recording complete and fail, asserting that a successful post completes with the timestamp and a thrown error fails with its message; package.json gains a test script of node --test. It runs node --check app.js and npm test, and because the manifest is applied by hand in the app's settings (the README's step 0), the pull request lists exactly what to paste and where.

The agent cannot install the app or open Workflow Builder from the sandbox, and says so: the manifest change adds no scope, so an existing install keeps working, but the new functions block must be saved in the app configuration before the step appears in the Builder's step picker under the app's name. Socket Mode needs no change, because function_executed arrives over the same connection as the message events.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a custom Workflow Builder step to this Slack Bolt app. Read app.js, manifest.json, package.json, package-lock.json, AGENTS.md and README.md first. In manifest.json add a functions section with a send_greeting step: title, description, input_parameters user_id (slack#/types/user_id, required) and message (string), and output_parameters with the posted message timestamp; add function_executed to the bot events. Move the listeners into listeners/ (messages.js, actions.js, functions.js) with a register(app) entry so app.js only builds and starts the App. Implement app.function('send_greeting') to post inputs.message to inputs.user_id with client.chat.postMessage, call complete with the outputs on success and fail with the error message on failure. Add tests/functions.test.js using node:test with a stub client and recording complete and fail, and a test script of node --test. Follow AGENTS.md: no code comments, reasons in the pull request. Run node --check app.js and npm test until they pass, then open a pull request that explains how to update the app manifest in the app settings and where the step appears in Workflow Builder.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request changes app.js, manifest.json and package.json, and adds listeners/messages.js, listeners/actions.js, listeners/functions.js, listeners/index.js and tests/functions.test.js. Its description shows the manifest diff, quotes the node --test summary from the sandbox, and gives the three steps a maintainer takes next: paste the manifest into the app's settings, reinstall only if a scope was added (none was), and open Workflow Builder to find send_greeting under the app's name.

It records the reasons AGENTS.md keeps out of the code: why every path calls complete or fail, why the listeners moved into modules (so a handler can be called in a test without starting a socket), and why the step takes a user id rather than a channel, which is the shape Workflow Builder's own person picker provides.

Before merging, a reviewer runs the app once against a development workspace, adds the step to a test workflow, and checks the posted message and the output variable in the Builder. A step that must pause for a button press later is the natural follow-up, and the description points at the interactivity pattern for it.

Run it on every Linear issue labelled slack-step

An automation on the Project with a linear trigger on linear.issue.labeled, slack-step in config.labels, and the prompt 'this issue describes a step a workflow builder should be able to add; declare it in manifest.json, implement it in listeners/functions.js with complete and fail on every path, test it with node --test, and open a pull request' starts one run per labelled issue once the first step exists. The trigger adds the issue after the prompt and fills in nothing else, so a request for a step that looks up a customer and a request for one that files a ticket each get their own function and test.

A team that maintains several Bolt apps sends this body once per repository from its own server, each POST /o/{org}/sessions with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own manifest: an app that already serves steps gets the new one in the same section, and an app on HTTP mode instead of Socket Mode gets the same handler with the pull request noting that the request URL already receives the event.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A custom step is small and unforgiving: a manifest and a handler that disagree on a parameter name, a path that returns without complete or fail, or a listener that cannot be exercised without a live socket, and the step silently never finishes in a workflow. The agent reads the manifest and the app as they are, keeps the change to the shape Slack documents, and leaves a test that runs in any sandbox.

The test output and the diff stay with the run, so a reviewer sees the success and failure paths asserted before touching a workspace. A team with several apps runs the same request across all of them at once.

Frequently asked questions

Do I have to reinstall the app?

Only if the manifest adds a scope. This step posts with chat:write, which the app already has, so saving the updated manifest in the app's settings is enough. A step that reads channel history or files would need its scope added and a reinstall, and the pull request would say so.

Does this work in Socket Mode?

Yes. The function_executed event reaches the app over the same Socket Mode connection as the message events, so nothing about hosting changes. An app that moves to HTTP mode later keeps the same handler.

Where does the step show up?

In Workflow Builder's step picker, under the app's name, in any workspace where the app is installed. The manifest's org_deploy_enabled is already true in this app, so an organization-wide install exposes it across workspaces.

What happens if the handler never calls complete?

The workflow waits on that step, which is why the handler wraps the Slack call in a try and calls fail with the error message in the catch, and why the test asserts both paths. A step that intentionally pauses for a button must call complete or fail from the action handler instead, after acknowledging it.

More Slack Bolt jobs

More jobs like this: Hand off a long task

Keep reading