---

name: migrate-slack-agents description: Migrate a classic single-bot Slack install to one provisioned Slack app per existing agent group while preserving agent identities, workspaces, memory, and wiring behavior — or record the operator's choice to stay on classic, which remains supported. Use when /update-nanoclaw surfaces the Slack agents requirement, or standalone any time later.

Migrate classic Slack agents

Turn every agent group wired through the classic instance='slack' adapter into a named slack-<slug> bot without replacing the agent group. This is an operator-guided, resumable data migration. It never creates an agent group and never edits an agent workspace.

Migration is optional. Classic single-bot Slack remains fully supported; this skill first offers the choice, and staying on classic is a valid outcome that also satisfies the update requirement.

Hard invariants:

• Never call create_agent or ncl groups create.
• Never change an agent_groups.id or write under groups/<folder>/.
• Never merge the channels branch; fetch and copy skill-owned files only.
• Never print token values. Show key names and masked presence only.
• Keep classic rows, credentials, and the shared Slack app available for rollback until the operator explicitly approves cutover.

Phase 1: Detect classic state

Run from the NanoClaw project root. Read the central DB only through the sanctioned wrapper.

Classic state requires all four signals:

1. src/channels/index.ts contains the Slack barrel import import './slack.js';.

2. .env has a non-empty unsuffixed SLACK_BOT_TOKEN and either a non-empty SLACK_APP_TOKEN or SLACK_SIGNING_SECRET. Check presence without echoing values.

3. This query returns at least one row:

   pnpm exec tsx scripts/q.ts data/v2.db "SELECT mg.id, mga.id, mga.agent_group_id FROM messaging_groups mg JOIN messaging_group_agents mga ON mga.messaging_group_id=mg.id WHERE mg.channel_type='slack' AND mg.instance='slack' ORDER BY mg.id, mga.agent_group_id"
   

4. At least one wired group does not yet have complete named-instance coverage: a stable slug, both SLACK_BOT_TOKEN_<SUFFIX> and SLACK_APP_TOKEN_<SUFFIX>, that slug in SLACK_INSTANCES, and the expected slack-<slug> messaging-group/wiring rows.

If the classic conjunction is absent and there is no partial state, stop with:

Nothing to migrate: this install does not have the classic shared-bot Slack state.

This is a successful no-op. If only some signals exist, make no changes; report the inconsistent or partial state instead of guessing. If every wired group already has complete named coverage, report that the migration is already complete and proceed only to the update-requirement acknowledgement in Phase 9.

Phase 1b: Offer the choice

Classic state confirmed does not mean migration is required. Present the decision to the operator before touching anything, in words like these:

Your classic Slack setup keeps working as-is — nothing forces this migration. The new Slack experience adds Slack agent spawning (create new agents straight from Slack, each with its own provisioned bot and avatar) plus UX improvements — per-agent identities, DM onboarding, multi-agent rooms. Say the word and we'll run the upgrade now — or run /migrate-slack-agents later manually.

If the operator chooses to stay on classic: make no changes, acknowledge the update requirement now using the Phase 9 ack command (the requirement records a decision, not only a completed migration), state that classic Slack continues working unchanged, and stop. Re-running this skill later re-offers the migration.

If the operator chooses to migrate, continue to Phase 2.

Phase 2: Inventory and propose the map

Before any mutation, capture every classic surface and its complete behavior:

pnpm exec tsx scripts/q.ts data/v2.db "SELECT ag.id, ag.name, ag.folder, mg.id, mg.platform_id, mg.name, mg.is_group, mg.unknown_sender_policy, mga.id, mga.engage_mode, mga.engage_pattern, mga.sender_scope, mga.ignored_message_policy, mga.session_mode, mga.threads, mga.priority FROM messaging_groups mg JOIN messaging_group_agents mga ON mga.messaging_group_id=mg.id JOIN agent_groups ag ON ag.id=mga.agent_group_id WHERE mg.channel_type='slack' AND mg.instance='slack' ORDER BY ag.id, mg.id, mga.priority DESC"
pnpm exec tsx scripts/q.ts data/v2.db "SELECT ad.agent_group_id, ad.local_name, ad.target_type, ad.target_id FROM agent_destinations ad JOIN messaging_groups mg ON ad.target_type='channel' AND ad.target_id=mg.id WHERE mg.channel_type='slack' AND mg.instance='slack' ORDER BY ad.agent_group_id, ad.local_name"

Classify each surface as DM, channel, or MPIM. A D… conversation is a DM; use Slack conversations.info with the classic bot token to distinguish an MPIM from a channel when the stored id is ambiguous, returning only type/id metadata and never the token.

Choose one stable, unique slug per agent group using the flow's normalization: lowercase, replace non-alphanumerics with -, trim -, and add a numeric suffix if an env key, SLACK_INSTANCES entry, or named DB instance is already claimed by another group. Once any migration state exists, never change that group's slug. Include the group commonly called “master”; it also gets its own provisioned app.

Slugs are de-duplicated, but the Slack-visible bot display name comes from the agent group's name — and Slack allows two apps with identical display names in one workspace, leaving humans a mention picker with twins told apart only by avatar. If any two migrating groups share a display name, flag it in the dry-run and have the operator differentiate the names before provisioning; renaming at this point is free, while renaming after provisioning requires a manifest update.

Present a dry-run table with:

• agent group id, name, folder, and chosen slug;
• every old messaging-group id, type, platform id, and destination name;
• the full old wiring row and unknown-sender policy;
• the proposed slack-<slug> surface and whether it is new, partial, or done.

For a channel, map the old row to a sibling with the same platform_id and instance='slack-<slug>'. DMs and MPIMs need new conversation ids as described in Phase 6. Ask the operator to confirm the entire map before continuing.

Phase 3: Install the current Slack agents payloads

First run /update-skills for the installed Slack channel only and require its structured result to report success: true and refreshed. That refreshes the barrel-registered /add-slack payload; it deliberately does not install companion skills, credentials, wirings, or restarts.

Resolve the remote that points at nanocoai/nanoclaw the same fork-aware way /update-skills does; do not assume it is origin. Fetch, but never merge:

source setup/lib/channels-remote.sh
channels_remote="$(resolve_channels_remote)"
git fetch "$channels_remote" channels

From $channels_remote/channels, materialize every file under .claude/skills/slack-a2a-rooms/ and then every file under .claude/skills/slack-agent-flow/ with git ls-tree + git show. Read each new SKILL.md completely and apply its own Apply steps, in that order. The order is load-bearing and mirrors setup/channels/companions.ts. The standard driver may apply each document:

pnpm exec tsx setup/lib/skill-driver.ts .claude/skills/slack-a2a-rooms
pnpm exec tsx setup/lib/skill-driver.ts .claude/skills/slack-agent-flow

Do not continue unless both report fully applied and their own build/tests pass. Source contracts: .claude/skills/add-slack/SKILL.md, setup/channels/companions.ts, and the two fetched companion SKILL.md files.

Phase 4: Get provisioning authority

Pause and ask the operator to choose and complete one authority path:

1. Managed broker — enroll/validate the registry install token, then have the operator connect the intended Slack workspace through the broker OAuth flow. The flow accepts NANOCLAW_INSTALL_TOKEN or the enrolled account.
2. Direct Slack — the operator supplies a valid SLACK_MANAGER_TOKEN in .env for apps.manifest.create + apps.managedInstall.

Never select a path, workspace, or authority on the operator's behalf. Confirm the intended workspace matches the classic bot's auth.test team before any app is created. See src/provisioning/slack-app.ts and the fetched flow's provision.ts for the two transport contracts.

Phase 5: Provision every existing group

Choose an existing classic Slack-wired group with a Slack approver as the stable source group. It supplies the operator identity and authenticates the origin slack instance; it is not cloned. For every inventoried group, including the source/master group, run the installed finish primitive with the recorded slug and defer room creation:

pnpm exec tsx scripts/slack-agent-flow-finish.ts \
  --group <existing-agent-group-id> \
  --name <stable-slug> \
  --source-group <source-agent-group-id> \
  --origin-instance slack \
  --room none

Do not pass --restart yet. Run all groups first. The script reuses a complete suffixed token pair, creates the operator DM and its wiring idempotently, and does not create an agent group. On a partial pair, finish the existing Slack app installation and retry the same slug; never choose a new slug or create a second app. Ensure every completed slug is present exactly once in SLACK_INSTANCES, including reuse cases. The exact CLI contract is documented at the top of scripts/slack-agent-flow-finish.ts.

Phase 6: Recreate surfaces and clone behavior

For each old wiring:

• Channel: the operator or an authorized Slack API caller must invite the new bot to the existing channel. Use the same channel platform_id.
• DM: use the operator DM created by the finish script. Every other user must open a new DM with the new bot; use that new DM id.
• MPIM: recreate the membership with the new bot. Slack forks it to a new conversation id; use the new id.

Create each sibling through ncl messaging-groups create, copying name, is_group, and unknown_sender_policy. Then use ncl wirings create with --channel-type slack, the resolved --platform-id, --instance slack-<slug>, and the existing --agent-group-id. Pass the recorded --engage-mode, --engage-pattern, --sender-scope, --ignored-message-policy, --session-mode, --priority, and thread policy; omit --threads when the old value is NULL, otherwise pass true or false.

ncl messaging-groups create --channel-type slack --platform-id <new-or-reused-platform-id> --instance slack-<slug> --name "<recorded-name>" --is-group <0-or-1> --unknown-sender-policy <recorded-unknown-sender-policy>
ncl wirings create --channel-type slack --platform-id <new-or-reused-platform-id> --instance slack-<slug> --agent-group-id <existing-agent-group-id> --engage-mode <recorded-engage-mode> --sender-scope <recorded-sender-scope> --ignored-message-policy <recorded-ignored-policy> --session-mode <recorded-session-mode> --priority <recorded-priority>

If a legacy pattern row has NULL engage_pattern, pass . to preserve its match-all runtime behavior. Do not accept adapter defaults in place of any recorded behavior field. These create operations are idempotent on their natural keys/pairs and create the companion destination row.

Show these operator-visible warnings verbatim:

• DM platform_ids are bot-specific (old DMs can't be copied; only the operator DM is auto-resolved — other DMs need re-opening per user).
• user_dms cache is not instance-aware.
• MPIM membership changes fork conversations (new IDs).
• Existing sessions stay on the old rows (session history does not transfer — new instances start fresh sessions).
• Destination names collide → suffixed (reconcile deliberately, preserve the original local name where the old wiring is retired