Skip to content

feat(settings): a step-by-step Slack setup wizard - #39005

Open
iamwhatever wants to merge 2 commits into
mainfrom
feat/slack-setup-wizard
Open

iamwhatever wants to merge 2 commits into
mainfrom
feat/slack-setup-wizard

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Settings → Messaging channels → Slack walks a first-time user from "I have a workspace" to "the bot answered my message" one screen at a time, with a picture of where to click on Slack's pages, and no gateway restart.

Today's panel is a long form: one Create link, two token fields and a member-ID field, with the steps in between left to a guide. A recorded first-time setup took 12 manual steps, 3 pastes and 2 gateway restarts, renamed the app by hand (every one-click app is KiroCrew-kirocrew) and toggled Socket Mode off and on to find the app-level token page.

This is the UI half (C2) of #38917. It stacks on #38918 (C1, the link helpers); until that merges this PR also shows C1's commit.

Why it matters

Slack setup is where people give up. The restarts were never needed (Reconnect applies saved credentials and a first owner), and the rename and token-page hunt go away once the app is named after an alias and the page is linked.

Not a goal

  • A new way to identify the owner. The owner step keeps today's member-ID field + Reconnect; the "message the bot and confirm on this machine" flow is a separate PR after its RFC.
  • Any change to Slack scopes or to how the gateway answers the slash command.
  • Company-specific setup copy (no internal workspace names or request forms). The wizard says it generically; an organization can point at its own guide (see below).

What changed (motivation → approach → change)

New website/src/pages/settings/SlackSetupWizard.tsx, shown at the top of the Slack panel until Slack first connects (and kept open for the last step), reopenable from a "Setup wizard" button:

Step What the user does What the wizard does
1 Workspace Confirms they have a workspace that allows app installs Generic guidance; an optional organization guide link
2 Create Types a short alias, clicks Create Slack app GET /api/slack/manifest?alias= for the link; on click saves slack.command to the command that manifest registers, so "Update the Slack app" later keeps the alias name instead of reverting to KiroCrew-kirocrew
3 Bot token Installs, pastes xoxb- Saves and verifies only that token (auth.test); notes that company workspaces may need admin approval ("Request to Install")
4 App-level token Opens Basic Information (direct link from C1), generates, pastes xapp- Saves and verifies the token; shows "Both tokens are verified. Next: tell Kiro Crew who you are." No reconnect yet
5 Owner Pastes their member ID Saves it and runs Reconnect: no restart
6 Test Opens the bot DM (direct app_redirect link from C1), sends a message Done only when the user confirms they saw a reply; then a Close button hides the wizard

Every step has a schematic (SlackWizardDiagram.tsx, positioned elements, no inline SVG per the use-lucide-icons rule): a simplified frame of the Slack page or client with the target outlined (dashed, so it never reads as a button here) and numbered in click order, under a caption saying it is a picture and not clickable. Colors are theme variables only, so every theme including dark reads; no Slack screenshots are shipped. Words in the pictures go through the catalog; Slack's own button and page names keep Slack's English spelling in every locale (api.slack.com is English-only), with a short role word ("button", "page") beside them in non-Latin locales.

Other changes:

  • SlackPanel.tsx: mounts the wizard; a wizard save re-arms the form's draft sync so a later form save cannot send a stale owner back; the Setup guide link now points to docs/guides/slack-setup.md instead of the oldest doc.
  • messaging.ts: getSlackManifest(alias?), and the two new status URLs.
  • docs/feature-map/README.md: a row for the wizard.
  • slack-manifest.yaml header comment: drop the "toggle Socket Mode off and on" trick, name the direct path and the wizard. Comment only, no scope or field change.
  • Every new string in all 12 authored catalogs plus the regenerated en-XA.
  • website/scripts/capture-slack-setup-wizard.mjs: the screenshot harness below.

Still to come in this PR, after #38938 (slash-command hot reload) merges, because it edits the same files: the optional organization guide link setting (slack.setup_guide_url: https:// only, set on this machine only, rendered with rel="noopener noreferrer"), and the guide update in docs/guides/slack-setup.md. The frontend half of the guide link (safeGuideUrl, rendering, tests) is already here and shows nothing until the setting exists.

Backwards compatibility

Compatible: the wizard uses the existing local-only PUT /api/slack/config and POST /api/slack/reconnect; the form below it is unchanged.

Removes nothing: the panel keeps every field; only the Setup guide link target and a manifest comment change.

Tests

  • New website/src/test/SlackSetupWizard.test.tsx (21 tests): the start step follows the saved config; the org guide renders only for https:// (not http:, javascript:, credentials in the URL) and with rel="noopener noreferrer"; an alias the backend would refuse disables Create and fetches nothing; Create saves the alias's slash command; the bot-token save sends only the token and moves on; a rejected token stays on its step with Slack's error; the app-level token step does not reconnect; the owner step saves and reconnects without a restart; a refused reconnect is described with the panel's own wording; the last step finishes only on "I got a reply"; a read-only remote viewer gets no inputs; every step draws its picture.
  • Local: tsc, eslint, npm run i18n:check with base origin/main (all 19 checks pass), vitest on the Slack panel suites and src/i18n (1345 passed), backend Slack manifest/exfil tests, brand gate.

Proof: not provable -- frontend test (prove.py runs Python only)

Manual verification

Screenshots below come from the real built SPA with canned Slack responses (node website/scripts/capture-slack-setup-wizard.mjs); the harness walks every step and asserts the step, its link and that Create saved slack.command before each shot. The harness surfaced one bug, fixed here: the wizard hid itself as soon as Slack connected, before the test step.

Not tested live (no Slack app was created, no token used):

  • that https://api.slack.com/apps/<A>/general lands on Basic Information with App-Level Tokens (F10);
  • which page Slack lands on right after Create from the manifest link (S1);
  • that https://slack.com/app_redirect?app=<A>&team=<T> opens the bot DM on an Enterprise Grid workspace.

Screenshots / video

Dark theme, every step:

Step 1 workspace
Step 2 create
Step 3 bot token
Step 4 app-level token
Step 5 owner
Step 6 test

Light theme and the finished state

Step 1 light
Step 2 light
Step 3 light
Step 4 light
Step 5 light
Step 6 light
Done dark
Done light

Related Issues

Part of #38917. Stacks on #38918.

Checklist

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 18, 2026 05:25
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🔴 BLOCK

Premise-level review of 90483b9efbbec7fdfc509755726b7b7782f6e820 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: BLOCK

The new ?command= parameter on /api/slack/manifest and deep_link(command=) have zero callers. The comment that justifies them claims the wizard uses them, and the wizard doesn't: it saves slack.command instead.

Notes

  • Item 8 — zero consumers: the frontend reads manifestQ.data?.org_guide_url, but no backend in this diff sends it. The description says "shows nothing until the setting exists." Subtraction: defer safeGuideUrl, the orgGuideUrl prop and their tests to the PR that adds slack.setup_guide_url.

What this change ships

Inventory (10 items) — 8 justified

Intent: help a first-time user set up Slack one screen at a time, with no gateway restart. ADDITION.

  1. A step-by-step wizard at the top of the Slack panel, open until Slack first connects — justified
  2. A "Setup wizard" button that reopens it — justified
  3. Create saves the alias's slash command so "Update the Slack app" keeps the name — justified
  4. A direct link to Basic Information for the app-level token — justified
  5. A direct link to the bot's DM for the test message — justified
  6. A schematic picture on every step — justified
  7. ?command= on the manifest endpoint, plus deep_link(command=) — zero consumers; the comment claims a caller that doesn't exist
  8. An organization guide link fed by org_guide_url — zero consumers; nothing sends it yet
  9. The Setup guide link now points to docs/guides/slack-setup.md — justified
  10. The manifest header comment now names the direct token path — justified

Blockers

The ?command= override has no caller — zero consumers
Trigger: slack_workspace.py says "?command= overrides the command… (the setup wizard passes the saved slack.command)". But the wizard's only call is api.getSlackManifest(alias), and getSlackManifest only builds ?alias=. Grepping command= across website/src: 0 callers. deep_link( with command=: 1 call, and that call is this same unused branch.
Outcome: a public endpoint parameter and a deep_link keyword, with an exfil-redaction caveat, solve the alias-name problem a second way. Item 3 already solves it, and the comment points readers at a caller that isn't there.
Subtraction: delete the asked/valid_command branch, deep_link's command keyword, valid_command, and the endpoint tests in test_slack_manifest_links.py.
Clears when: the ?command= branch and deep_link(command=) are removed, or a caller in this diff passes command=.

[FIRST-PRINCIPLES-REVIEWED] 90483b9

Description read

[DESCRIPTION-READ] 4cf990c277d0863c5fe302c3fcf77356aab7da5dcdfb63c2ac846422d051a6a4

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 90483b9efbbec7fdfc509755726b7b7782f6e820 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the wizard reuses the existing local-only config and reconnect routes, the backend adds only link helpers, and screenshots of every step are attached.

Notes

  • ?command= on GET /api/slack/manifest and deep_link(command=) have no frontend caller here: getSlackManifest(alias?) never sends it. Yet the endpoint docstring says "the setup wizard passes the saved slack.command". Either wire it up or say it belongs to C1 (feat(slack): links for the Slack setup wizard #38918).
  • Clicking Create saves slack.command straight away, and the wizard can be reopened after Slack connects. Someone who reopens it and clicks Create on a working install switches the gateway to /kirocrew-<alias> before any new app exists, so their current app's slash command stops being answered. Consider saving the command only once the new bot token is verified.

[DESIGN-REVIEWED] 90483b9

Description read

[DESCRIPTION-READ] 70e81f1ab4c189a1109e310b94abdba608371573a4f4f409902398e18939612d

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS (a BLOCK with no Trigger and no Outcome does not block)

UX-level review of 90483b9efbbec7fdfc509755726b7b7782f6e820 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

cannot evaluate: missing the panel-level "Setup wizard" reopen button, the wizard's place in the Slack panel, and the step error states. Every screenshot is cropped to the wizard card.

Evidence gaps

  • "Setup wizard" reopen button (slack-wizard-open, in the Slack panel header next to the status badge and Reconnect). After "Close setup wizard" this is the only way back in, and no screenshot shows it. Close it with an uncropped shot of the Slack panel header with the wizard closed.
  • Where the wizard sits in the panel (the "Setup wizard" section above "Get your credentials" and the existing form). No shot shows the two side by side, so nobody can judge the duplicate inputs. Close it with a full-panel shot with the wizard open.
  • Failure states: a rejected token showing Slack's error (ErrorNotice under the step), reconnect_failed on step 5, the alias_invalid warning, manifest_unavailable, and the command_saved_restart notice. Close it with one shot for each.
  • Step 5 "Connect" retry button (slack-wizard-reconnect, shown once an owner is saved). Close it with a shot of step 5 after a reconnect fails.
  • Step 4 basic_info_fallback (the text shown instead of the Basic Information link when there is no URL). Close it with a shot of step 4 without the link.

Notes

  • Step 3 has no link to the Slack app page, unlike steps 2, 4 and 6. The blind reader said: "I don't know how to get to 'the Slack app page'." Add a LinkButton to the app's OAuth & Permissions page.
  • After setup, "Back" still shows next to the "Slack is set up." message, and the reader would not dare click it: "in case it undoes the finished setup". Hide "Back" once gotReply is set.
  • Two descriptions of adding a workspace disagree. Step 1's picture shows "+" then "Add a workspace", but the clients_hint text says "click your profile picture, then Add a workspace". Make one match the other.

[UX-REVIEWED] 90483b9

Description read

[DESCRIPTION-READ] 489bf90323b53157b6987be1ff658122a7113a508e4d10404249009276554031

That sha256 names everything this verdict read: the PR description, plus the 17 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 90483b9efbbec7fdfc509755726b7b7782f6e820 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 90483b9

Verdict parsed from the review's SHA-scoped output markers for commit 90483b9efbbec7fdfc509755726b7b7782f6e820.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 90483b9efbbec7fdfc509755726b7b7782f6e820 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — 🔴 changes requested (blocking)

GPT 6.1 found at least one blocking issue that must be resolved before merging 90483b9efbbec7fdfc509755726b7b7782f6e820. 1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

This comment is updated in place on each push.

BLOCKING -- website/src/pages/settings/SlackPanel.tsx:506 -- Wizard saves discard unrelated unsaved form edits

onSaved={() => { syncArmed.current = true }}
Trigger: During first-time setup, enable session-folder filing and enter a folder name in the form below, then verify and save the first bot token through the wizard. Its success callback arms synchronization; the invalidated slack-config query returns the changed token status and runs the panel’s sync effect.
Outcome: The effect replaces the entire draft with draftFrom(data) and clears the form’s token drafts, silently discarding unrelated edits that the wizard’s token-only save never persisted.
Anchor: residual/crash-data-loss-corruption
Fix: Synchronize only fields saved by the wizard, preserving unrelated dirty fields and token drafts instead of re-arming the whole-form reset.

[BLOCK-MERGE] 90483b9
[GPT-REVIEWED] 90483b9

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

The wizard is open by default until Slack connects (SlackPanel.tsx:295), and the form below it stays rendered and editable at the same time. A wizard save calls onSaved and then invalidates slack-config (SlackSetupWizard.tsx:149-150). That re-arms the sync, and the effect then reseeds the whole draft and clears the token drafts (SlackPanel.tsx:506, SlackPanel.tsx:307-313). This can happen during normal first-time setup and needs no unusual timing or inputs, so a FLAG doesn't fit. I'm upholding it as written.

[ADJUDICATION] 90483b9efbbec7fdfc509755726b7b7782f6e820 total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] 90483b9efbbec7fdfc509755726b7b7782f6e820

[ADJUDICATION-FENCED] 90483b9efbbec7fdfc509755726b7b7782f6e820 fenced=1 flagged=0
UPHOLD-FENCED F1 website/src/pages/settings/SlackPanel.tsx:506 -- Editing the form while the default-open first-setup wizard saves a token is ordinary use, and the re-armed sync at SlackPanel.tsx:307-313 then silently replaces the unsaved form edits.
[GPT-ADJUDICATED-FENCED] 90483b9efbbec7fdfc509755726b7b7782f6e820

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 90483b9efbbec7fdfc509755726b7b7782f6e820 false-positive: <reason, 20 to 500 characters>

@iamwhatever
iamwhatever force-pushed the feat/slack-setup-wizard branch from 26b250a to 90483b9 Compare November 18, 2026 08:33
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 18, 2026
Joe Guo added 2 commits November 18, 2026 08:35
Basic Information page, bot DM link, and a create link that keeps the saved slash command. Refs #38917
@iamwhatever
iamwhatever force-pushed the feat/slack-setup-wizard branch from 90483b9 to 6380ec5 Compare November 18, 2026 08:44

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: checking Automated validation is still running

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant