Slack agent flow (create_agent → provisioned Slack bot)

Composes the Slack extension skills into one conversational flow: a user tells an existing Slack-wired agent "create an agent called Research", and the new agent doesn't just exist as a send_message destination — it arrives in Slack as its own bot. The host provisions a Slack app for it (managed broker, or a workspace manager token), registers it as a slack-<name> instance, hot-starts the adapter in the running host, opens a DM between the new bot and the operator, opens a three-way MPIM (operator + originating bot + new bot) registered as an agent-to-agent room, and wires everything so both agents hear the room. The flow also adds two agent-facing room actions — create_room (one shared room with N agents at once, the team primitive) and add_to_room (grow a room by one agent) — and extends the base create_agent tool with the flow's purpose / allow_guests / room parameters. Non-Slack sessions are untouched: create_agent from any other channel behaves exactly as upstream.

Canonical home. This directory on main is the skill's canonical source — the setup wizard and any direct apply read it from the checkout. The copy on the channels branch is a compatibility mirror for older checkouts whose setup fetches companions from there; edits land here, never there. The payload the Apply steps fetch with from-branch:channels stays on the channels branch, exactly like /add-slack's own.

Prerequisites

All prose below assumes these are already in place, in this order:

1. add-slack — the Slack channel install (src/channels/slack.ts and the shared channel-layer lib src/channels/slack-lib.ts present, with slack.ts exporting its SLACK_DEFAULTS declaration and the multi-instance factory slackInstanceBridgeFactory — the adapter owns SLACK_INSTANCES registration natively, and the flow writes each new agent's tokens under that env-key scheme).
2. slack-a2a-rooms — the bot-sender room policy (src/channels/slack-a2a.ts present), so shared rooms admit the sibling bots' posts.
3. A provisioning credential in .env — NANOCLAW_INSTALL_TOKEN (managed broker) or SLACK_MANAGER_TOKEN (direct workspace-level app creation). Without one, agent creation still works but the Slack leg reports no-credentials and points at the finish script.
4. At least one Slack owner/admin in user_roles — the flow resolves "the operator" from the approver chain (scoped admins → global admins → owners) and needs a slack:U… identity there to open the DM and the room.

Apply

1. Check the Slack payloads are installed

The flow imports the skill-installed Slack channel modules; verify they are in the tree before copying anything. If slack-lib.ts, the SLACK_DEFAULTS export, or the slackInstanceBridgeFactory export is missing, the installed Slack channel payload predates this flow — re-apply the two skills above (or /update-skills) first:

test -f src/channels/slack.ts && test -f src/channels/slack-lib.ts && test -f src/channels/slack-a2a.ts && grep -q "export const SLACK_DEFAULTS" src/channels/slack.ts && grep -q "export function slackInstanceBridgeFactory" src/channels/slack.ts

2. Check the trunk extension seams

Everything this flow plugs into is standard trunk API — the adapter hot-start entry, the delivery batch preview, the mailbox delivery/session helpers, the create-agent notify option, the decline-and-notify overrides, the container tool-extension hook, and the setup wizard's channel registries. This is a trunk version requirement, not an edit: if the check below fails, the NanoClaw trunk is too old for this skill — bring the install up to date (/update-nanoclaw) instead of patching any of these files by hand:

grep -q "export async function startChannelAdapter" src/channels/channel-registry.ts && grep -q "export function registerDeliveryBatchPreview" src/delivery.ts && grep -q "session: Session) => Promise<void>" src/delivery.ts && grep -q "trigger?: boolean" src/session-manager.ts && grep -q "findCliResponse" container/agent-runner/src/db/messages-in.ts && grep -q "Promise<number>" container/agent-runner/src/db/messages-out.ts && grep -q "suppressCreatedNotify" src/modules/agent-to-agent/create-agent.ts && grep -q "dedupeKey?: string" src/modules/permissions/sender-approval.ts && grep -q "declineText?: string" src/modules/permissions/sender-approval.ts && grep -q "fyiText?: string" src/modules/permissions/sender-approval.ts && grep -q "export function extendTool" container/agent-runner/src/mcp-tools/server.ts && grep -q "export function registerChannelPreStep" setup/channels/companions.ts && grep -q "instructions.md" src/project-doc-compose.ts && grep -q "await action.decide" src/guard/guard.ts

The last term requires an async-capable guard seam: the flow's create_agent and room-action guards read container config asynchronously, and on a trunk whose guard() does not await decide a returned Promise would be treated as an allow — the check turns that silent fail-open into a fail-fast here.

3. Copy the shared feature payload from the channels branch

The agents experience needs more than the base adapter: the room-membership module (invite-to-room adoption, group-DM fork carry-over, detach on removal, owner-presence access rule), canvas actions + the container canvas tool + the canvas-work skill (section-scoped canvas edits/reads via the session's own bot identity), DM onboarding (get-started prompts, per-thread DM titles), and their env-file.ts dotenv plumbing. They live on the channels branch; fetch and copy them into place (overwrite — the branch is canonical):

src/env-file.ts
src/env-file.test.ts
src/modules/slack-room-membership/index.ts
src/modules/slack-room-membership/membership.ts
src/modules/slack-room-membership/membership.test.ts
src/modules/slack-room-membership/env-file.ts
src/modules/slack-room-membership/env-file.test.ts
src/modules/canvas-actions/index.ts
src/modules/canvas-actions/handlers.ts
src/modules/canvas-actions/canvas-api.ts
src/modules/canvas-actions/canvas-actions.test.ts
src/modules/slack-onboarding/index.ts
src/modules/slack-onboarding/onboarding.test.ts
src/modules/slack-onboarding/thread-title.test.ts
container/agent-runner/src/mcp-tools/canvas.ts
container/agent-runner/src/mcp-tools/canvas.instructions.md
container/agent-runner/src/mcp-tools/canvas.test.ts
container/skills/slack-construct/SKILL.md
container/skills/slack-construct/instructions.md
container/skills/canvas-work/SKILL.md
container/skills/welcome/addenda/slack.md

The welcome addendum rides with the agents feature deliberately: its tour content describes rooms, canvases, suggested-prompt DMs, and the agents access model — none of which exist on a base /add-slack install.

Register the three host modules in the modules barrel and the canvas tool in the container tool barrel (each append is skipped if already present; these must precede the flow module's own barrel line, which the fence order here guarantees):

import './slack-room-membership/index.js';
import './canvas-actions/index.js';
import './slack-onboarding/index.js';

import './canvas.js';

4. Copy the flow payload

This skill ships its payload alongside this document; copy the files into the tree at the same relative paths (overwrite; the skill's copies are canonical). The host module carries the wrapped create_agent handler and the room actions; the container files carry the room tools, the create_agent extension, the sibling-agent standing-context skill, and the welcome-tour addendum. The two mcp-tools/*.instructions.md fragments and the slack-construct-agents skill's instructions.md are picked up by the CLAUDE.md compose scan; the welcome addendum is consumed by the host's channel-matched addenda mechanism (inert on hosts that predate it) — so copying the files is the whole install:

src/modules/slack-agent-flow/types.ts
src/modules/slack-agent-flow/env-file.ts
src/modules/slack-agent-flow/provision.ts
src/modules/slack-agent-flow/slack-deps.ts
src/modules/slack-agent-flow/orchestrate.ts
src/modules/slack-agent-flow/guard.ts
src/modules/slack-agent-flow/room-actions.ts
src/modules/slack-agent-flow/room-canvas.ts
src/modules/slack-agent-flow/index.ts
src/modules/slack-agent-flow/env-file.test.ts
src/modules/slack-agent-flow/provision.congruence.test.ts
src/modules/slack-agent-flow/provision.prefetch.test.ts
src/modules/slack-agent-flow/orchestrate.test.ts
src/modules/slack-agent-flow/room-actions.test.ts
src/modules/slack-agent-flow/room-canvas.test.ts
scripts/slack-agent-flow-finish.ts
container/agent-runner/src/mcp-tools/rooms.ts
container/agent-runner/src/mcp-tools/rooms.test.ts
container/agent-runner/src/mcp-tools/rooms.instructions.md
container/agent-runner/src/mcp-tools/create-agent-slack.instructions.md
container/skills/slack-construct-agents/SKILL.md
container/skills/slack-construct-agents/instructions.md
container/skills/welcome/addenda/teams-tour.md

5. Register the host module

Append the self-registration import to the module barrel (skipped if the line is already present). It must evaluate after the agent-to-agent module's own registration, which appending at the end guarantees — the flow's create_agent handler re-registers over upstream's:

import './slack-agent-flow/index.js';

6. Register the container room tools

Append the tool-module import to the container MCP-tools barrel (skipped if already present). The module registers create_room / add_to_room and extends the base create_agent tool, so it must evaluate after the base agents module — import order follows document order, and appending at the end guarantees it:

import './rooms.js';

7. Build

The build guards every typed call the flow makes into trunk (delivery registration, DB helpers, channel defaults, the shared Slack lib) against drift:

pnpm run build

8. Validate

The flow's own tests, the shared feature payload's module tests, and the trunk hot-start seam's test run on the host. The room-tool tests run through the already-built agent image, so setup does not require Bun on the host; they also pin the create_agent extension:

pnpm exec vitest run src/modules/slack-agent-flow src/modules/slack-room-membership src/modules/canvas-actions src/modules/slack-onboarding src/env-file.test.ts src/channels/adapter-hot-start.test.ts

source "$PWD/setup/lib/install-slug.sh" && "${CONTAINER_RUNTIME:-docker}" run --rm --entrypoint bun --workdir /app --volume "$PWD/container/agent-runner/src:/app/src:ro" "$(container_image_base):latest" test --preload /app/src/modules/index.ts src/mcp-tools/rooms.test.ts src/mcp-tools/canvas.test.ts

9. Restart the host

The flow module registers at boot, and container mounts are read-only at runtime — restart so the running host picks everything up (new sessions see the container-side files; no image rebuild):

bash setup/lib/restart.sh

How it behaves

• Guard/approval flow is upstream's. The flow re-registers create_agent with the same guard action and precheck as the agent-to-agent module; only the hold question changes when the request originates from a Slack session (it names the Slack provisioning side effects — new app, operator DM, shared room). The room actions get the same trust split: global cli_scope groups act directly, everything else holds for the admin chain, and approved replays re-enter the wrapped handlers automatically.

• Expected boot warning. Because the barrel imports the flow module after the agent-to-agent module, every boot logs Delivery action handler overwritten for create_agent. That warning is the intended signal that the wrapper won the registry — its absence means the barrel line is missing or ordered wrong.

• What a successful run does. Provisions (or reuses) the app — agent-mode by default; allow_guests: true selects the plain, guest-accessible variant — writes SLACK_BOT_TOKEN_<NAME> / SLACK_APP_TOKEN_<NAME> and unions the slug into SLACK_INSTANCES, hot-starts slack-<name>, opens the operator DM and wires it to the new agent group (agent-mode DMs get thread-per-conversation sessions straight from the channel declaration), opens the three-way MPIM with the new bot's token, appends the room's channel id to SLACK_A2A_ROOMS, creates one room messaging group per instance (both mention-gated), creates the room's canvas-tab contract, then posts the DM intro and nudges the originating agent to introduce the new one in the room. The new bot typically answers within ~10 seconds; if it stays silent for a minute, an operator can run bash setup/lib/restart.sh as the fallback.

• Workspaces that gate installs. Where an admin must approve every app install, the workspace refuses the automatic one and the managed service answers with an install link instead of a bot token. The flow does not fall back to hand-building an app: it posts one line into the conversation the create came from — as the ORIGINATING bot, since the origin agent's own reply cannot be delivered while the handler is still running — naming the link to approve, then polls the service (5s, up to 5 minutes) for the bot token the completed install releases. On arrival the rest of the flow runs exactly as if the install had been automatic. On timeout the app parks: SLACK_APP_TOKEN_<NAME>, SLACK_APP_ID_<NAME> and SLACK_INSTALL_URL_<NAME> stay in .env, and asking the same agent for the same name again resumes THAT app — it never provisions a second one. SLACK_INSTALL_WAIT_MS=0 skips the inline wait for installs that always go through a slow approval queue; moves the cadence.

Everything the flow creates at runtime is user data, not skill payload: agent groups, messaging groups, and wirings stay in the central DB; token lines, SLACK_INSTANCES entries, and SLACK_A2A_ROOMS entries stay in .env; provisioned Slack apps stay in the workspace. Removal (see REMOVE.md) never touches any of it — for per-agent teardown of a provisioned bot, follow the slack-managed-agents skill's teardown section.