Repository navigation
feat: Meet CrewMates first-run flow that creates the first crewmate - #12927
Conversation
|
Intent: Give a brand-new user (no crewmates, no custom agents) a four-step first-run path from "what is a crewmate" to owning one with a standing job and a schedule, using the shipped onboarding chrome and the existing agent/cron APIs. |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Confirm the in-PR RFC amendment: accepted screen 08 decided a "Slack DM" report choice; this ships a status row instead — runtime constraint verified ( Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: give a first-run user a guided path from "what is a crewmate" to owning one with a standing job — an ADDITION, covered by
Evidence checked: roster skip is real ( [FIRST-PRINCIPLES-REVIEWED] cbcf162 |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the localStorage-only Suggestions
[DESIGN-REVIEWED] cbcf162 |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsThe first crewmate's own schedule is invisible in its wake pane, and the Slack row states "Off" for an unread Slack — both advisory, neither blocks. FINDING — website/src/components/MeetCrewmatesFlow.tsx:344 — the schedule is bound with FINDING — website/src/components/MeetCrewmatesFlow.tsx:786 — [OPUS-REVIEWED] cbcf162 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
UX Review (Fable 5) — 🟡 CONCERNSUX-level review of UX-Verdict: CONCERNS "Ask the agent" on the flow's error notices is vocabulary this first-run user was never taught, and the reader avoided it; the transitions GIF is blank. Watch
Suggestions
[UX-REVIEWED] cbcf162 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
|
Ships dark. The flow is behind the existing Crew Members feature preview (Settings → Developer → Feature Previews, |
f938239 to
daf2e1f
Compare
GPT 5.6 Review —
|
GPT 5.6 Review —
|
daf2e1f to
de05346
Compare
de05346 to
197f33f
Compare
|
span=afaae5c82a69
|
|
span=56704161f83d
|
|
span=9b01b09e763d
|
|
span=b2e03d9a649b
|
|
span=5c5d1e3af4db
|
|
span=42865c6a409c
|
|
span=3216f4be30d3
|
|
|
span=33f7b000336f
|
|
span=49f321101c97
|
|
|
span=6cbf44c41e0a
|
|
span=31af23768d0e
|
|
span=4378d8b709aa
|
|
span=7d02248701fc
|
|
span=73e5f15283f2
|
|
span=afaae5c82a69
|
|
span=d9fed3403e15
|
|
span=fb1b6e543adc
|
|
span=2ba22d72034b
|
|
span=5f9b0cb1395c
|
|
span=487c65022710
|
GPT 5.6 Review —
|
A user with no crewmates and no custom agents had no path from "what is a crewmate" to owning one: the Crewmates page empty state sent them to the crew editor, a form that assumes they already know what to fill in. This adds a four-step first-run chapter in the shipped split-screen chrome: meet the idea (three example crewmates), name the first one and pick what it is built from, give it a standing job with a schedule and a place to report, then open its chat. Create reuses the existing writes: POST /api/agents makes the crewmate (the job text lands in its description, the roster's "what it is for" field) and POST /api/crons binds a schedule to it through member_id so the job runs on the crewmate's own memory. A taken name stays on step 3 with an ErrorNotice; a failed schedule still reaches "ready" and says so. The flow fires once, after the Customize tour, gated on zero crewmates beyond the built-in default row and zero installed agents beyond the built-ins, so an existing user with custom agents (who gets the opt-in step instead) never sees it. Completion or dismissal is recorded as the new dashboard.crewmates_onboarded flag through the theme endpoints; a workspace that was already onboarded counts as done and reaches the flow from the Crewmates page instead, which also keeps the E2E and capture harnesses (seeding only mc-onboarded) clear of it.
|
span=33f7b000336f
|
|
span=44cf54d1606b
|
|
span=8bd2dfd2e02f
|
|
span=b4396c191a80
|
|
span=d9fed3403e15
|
Problem / Motivation
A new user has no crewmates and no custom agents, and nothing tells them what a crewmate is or gets them one. The Crewmates page's empty state sends them to the crew editor, a form that assumes they already know what to fill in. The Customize tour ends and the product's headline idea — a teammate that keeps working while you are away — is never shown.
Why it matters
CrewMates is the launch story. A first-run user who never meets one uses Kiro Crew as a chat box and misses the point of the product; the first crewmate is the moment the idea becomes real, and today that moment has no path.
What changed (motivation → approach → change)
POST /api/agentsthenPOST /api/cronsbound to the crewmateImplements the accepted RFC:
docs/request-for-change/rfc-crewmates-launch.md(screen 08, "Meet CrewMates onboarding"). The RFC's screen 08 carries an implementation amendment recording the Slack status row, the "Starting setup" wording and the name grammar.Goal: take a user from "what is a crewmate" to owning one, in the same first-run chrome the other chapters use, without a new form or a new API.
Approach: a four-step chapter (
components/MeetCrewmatesFlow.tsx) on the shippedOnboardingChapterShell, mounted inApp.tsxinsideOnboardingShellHostafter the Customize tour. It fires once, only while the Crew Members preview is on (Settings → Developer → Feature Previews,PREVIEW_CREW— the switch that already shows the Crewmates page, so the flow ships dark and launches with it), and only when the roster holds nothing beyond the built-indefaultrow and every installed agent is one Kiro Crew wrote itself — the server'skirocrew_ownedflag alone decides (hooks/useMeetCrewmatesGate.ts). An existing user with custom agents gets the opt-in step instead, so the two never both fire. The Crewmates page (pages/members/MembersPage.tsx) re-opens it on demand (mc-start-meet-crewmates) when onlydefaultis on the roster. Steps slide (Framer Motion,prefers-reduced-motionhonoured); Tab is trapped and Escape means Not now before the crewmate exists and Close after.Change: Create reuses the two existing writes.
POST /api/agentsmakes the crewmate with the job text as itsdescription(the roster's "what it is for" field).POST /api/cronsbinds the schedule to it throughmember_id= that immutable identity (never the display name, which the server late-resolves and a same-named remake could capture), so the job runs on the crewmate's own memory. Delivery is mechanical, never an instruction to the model: the job is created non-silent, so every run rings the bell and — when Slack is connected — reaches the owner's Slack DM through the runtime's own leg (the Slack row on step 3 therefore only states that fact in its label line — "Slack DM — Active" / "Off" — with the toggle column left empty; it is not a switch, because the runtime offers no such choice), and Its own chat maps tohide_in_chat, the one delivery choice the runtime does offer; the message is the job text alone. The crewmate's identity is held only from a clean create response (the immutablemember_idthe server allocates with its member memory;POST /api/agentsnow returns it besidememory_store) and is the one thing the flow binds to or reconciles against; nothing is claimed by display name, since two openings prefill the same example name and a same-named crewmate the flow cannot prove it made is someone else's. A 409agent_existsis therefore a taken name on every attempt (back on step 2 with the error under the field, an "Open the Crew Members page" button on that notice — the wizard otherwise gave no way there — and the suggestion chip carrying that name marked "already exists"), a refused create (other 4xx) says "could not be created" inline, and a create with no usable answer (dropped response, 5xx) stops on step 3 saying the crewmate "may or may not have been created", posts no schedule, and carries a button to the Crew Members page (the page's shipped title, which every notice in the flow now uses; the rename is the sibling PR) so the user checks before making a second one. The Crew Members entry's gloss is a block line under its button (beside it, the phrase wrapped mid-sentence in the narrow list and read as part of the control); the page's "no crewmate yet" test is the gate's ownhasNoCrewmates, so the page and the auto-fire cannot disagree. Step-1 copy: the Fixer example says "failing checks" (not "red CI"), and the footnote quotes “default” and no longer restates the panel's memory/chat/notes line. Every failure is anErrorNoticefollowingerrors-use-error-notice: the agent hand-off is on where nothing can be lost (the eligibility notice, the step-4 schedule notices, the "done" notice on steps 1 and 4; it closes the flow the way that step's own exit does, because the chat sits behind the dialog) and off beside the unsaved name and job on steps 2–3, each notice naming the draft. A failed eligibility read is shown byApp.tsxas a dismissible notice (MeetCrewmatesEligibilityNotice) instead of silently never firing — its remedy is an Open Meet CrewMates button that fires the same event as the Crew Members entry, not the name of a page the user may already be on: a taken name sends the user back to step 2 with the error under the name field,POST /api/agents(handlers/agents.py) now refuses a crew name that failsvalidation._AGENT_NAME_RE(invalid_agent_name) — the fix lives at that route, for every client of it, becauseGET /api/membersskips such a row (kirocrew agent createstill writes a name unchecked; a pre-existing level left as it is); the flow previews the same grammar under the name field as the user types (a plain warning-coloured hint that appears only once the name fails, not anErrorNotice) and disables Next until it passes, and a server refusal lands under the field like a taken name; the cronmessageis the job text itself; a schedule the server refused (4xx) still reaches step 4 and says the schedule was not saved, with a button to the Schedule page on the notice, while a schedule write with no usable answer (a dropped response, a 5xx) is reconciled againstGET /api/crons— only a job that IS the one asked for (member_id= the held identity, same name, same message, same schedule) means saved; an older or foreign job on the crewmate is not evidence — and only when that read fails too says it may not have been saved, pointing at the Schedule page instead of inviting a duplicate, a failed read of the custom agents or of the Slack status says so on its step, and a refused write of the "done" flag (markCrewmatesOnboardedawaits its PUT) is shown on the current step when it is the create-time write, or on the next entry when it is the write at exit. "Done" is persisted the moment the crewmate exists while the ready step stays open (onCreated) and again when the user leaves (onDone); an exit never waits for the server — the chapter closes at once and persists afterwards, since several exits navigate (/members,/schedule) and a full-screen chapter gated on a round trip would cover the page the user just asked for — and a refusal marks nothing locally (markCrewmatesOnboardedapplies the render cache, the pending-mark clear and the in-memory flag only after the server accepted), so this browser is still due the chapter after a reload, as the notice says, rather than seeding a completion the server never recorded; the flow does not auto-fire again within the same session. "Only when I ask" posts no schedule and step 4 then says nothing about reports or the Schedule page. Completion or dismissal is recorded as a newdashboard.crewmates_onboardedflag (config/infra:sections.py,loader.py,config-baseline.json), read onGET /api/theme/bootand written throughPUT /api/config/theme(handlers/core.py,api/client.ts), mirrored inhooks/useTheme.tsxlike the other first-run flags. A workspace that was already onboarded counts as done and reaches the flow from the Crew Members page, which also keeps the E2E and capture harnesses (they seed onlymc-onboarded) clear of it — with one exception that protects the launch's own target user: a FIRST tour completion (markOnboardedwhile not yet onboarded — never a replay from Settings) leaves anmc-crewmates-pendingmark on that browser, so a new user who reloads or restarts between the tour and this chapter is still due it (the seed and the boot rule both honour the mark; it is cleared when the chapter is marked done). Only a workspace onboarded with no such mark — before this shipped, or from another machine — is treated as an existing install. All copy is in the catalog (components.meetCrewmatesFlow.*,pages.membersPage.meet_crewmates,website/src/i18n/locales/en.jsonplus the 11 translations and the regenerateden-XA.json) in the 12 languages; specs and the feature map name the flow. The ~60 new keys × 12 languages grow the translations chunk past its budget, soscripts/check-bundle-size.mjsraises thetbudget to the usual 5% over the new measured size.Backwards compatibility
Compatible: one new optional boolean on
DashboardConfigwith aFalsedefault; the theme endpoints accept it beside the existing flags and reject nothing they accepted before. No route, key or default changes.Tests
test/gui_user/scenarios/meet-crewmates-flow.yaml(agentic gui-user scenario, tiernightly, featuremembers) — a tester with the new-user persona turns on the Crew Members preview, opens the empty Crew Members page (seedrich, no members: the roster holds only the built-indefaultrow), clicks Meet CrewMates, walks the four steps with the prefilled Radar / job / "Every morning at 9:00" and Create Radar, then Open Radar's chat; expects a Radar row in the roster, an open conversation for Radar and no more Meet CrewMates button. Runs nightly viagui-user-test.yml; its static schema check runs in CI, andtest/gui_user/test_scenarios_and_report.pylists it in the shipped roster (37 scenarios, 5 nightly).website/src/components/MeetCrewmatesFlow.test.tsx— closed renders nothing; step 1 lists the three examples with the counter; Not now and Escape reportdismissedwithout writing; step 2 prefills Radar, a chip swaps name and job, an empty name blocks Next; Back works; Create posts the crewmate (description= the job) then a non-silentschedule withmember_id,cron 0 9 * * *,hide_in_chat: falsewhile Its own chat is on, firesonCreated, keeps the ready step open and reportscompletedonly on Open chat; a 409agent_existsreturns to step 2 with the error under the name field (aria-invalid, cleared on edit), a button to the Crew Members page that reports a dismissal, the matching chip marked taken, and no schedule; an unanswered create stops on step 3 with the "may or may not" notice and its Crewmates-page button, posts no schedule and never reads the roster by name; a 409 after an unanswered create is a taken name; a refused create (4xx) is the inline notice with no button; the schedule is posted withmember_id= the identity from the create response; the schedule reconcile counts only the exact job asked for and ignores another job on the crewmate (other message or schedule) and the same job on another identity; a 4xx schedule lands on "ready" saying "not saved"; an unanswered schedule write whose job (matched by the rosterslug) the Schedule list then shows counts as saved, and one the list does not show says "may not have been saved"; "Only when I ask" posts no cron and shows no schedule copy; a name with a space disables Next with the grammar as a plain hint under the field (no alert) and posts nothing; a serverinvalid_agent_namelands under the name field on step 2;isValidCrewmateNamecases; the schedule-failure notice's Schedule button completes the flow; a suggestion chip never overwrites a job the user typed; a failed custom-agent read shows anErrorNoticeand still offers the default agent; the Slack row is a status row (plain "Active" / "Off" text plus the reason, no pill so it cannot read as a disabled switch), never a switch; a step-1 example row preselects its crewmate and opens step 2; entering a step seats focus on a control inside the NEW step (the seat runs from the incoming step's own mount, afterAnimatePresence mode="wait"has removed the outgoing one, so it can never land on a control about to unmount and leave the Tab trap open); the eligibility notice renders its message, the agent hand-off and Dismiss, and its Open button fires the start event then dismisses; the Slack state word sits in the label line ("Slack DM — Off");scheduleFor,builtFromOptionsand the two gate predicates.test/test_agents_roster_contract.py—POST /api/agentsrefusesIssue Radar,-radar,radar-,Радар,ra/darand a 65-char name withinvalid_agent_nameand stores nothing.test/test_config_api.py— the Hypothesis create round-trip (names drawn from all Unicode letters and digits) now expects400 invalid_agent_nameand an untouchedconfig.jsonfor any name failing_AGENT_NAME_RE, before the memory-store rule is judged; the strategy stays wide so that branch runs; a created crew's response carries a non-emptymember_id.test/test_meet_crewmates_builtin_pin.py— the flow'sAGENT_NAME_REpreview agrees withvalidation._AGENT_NAME_REon a probe set (spaces, edge dashes, non-ASCII, 63/64 chars).website/src/hooks/useMeetCrewmatesGate.test.tsx— anykirocrew_owned: truerow counts as built-in; a row flagged false, or without the flag, is a custom agent; a persist refused atonCreatedis shown while the ready step is up andonDonestill closes at once (before the server answers); a persist refused at exit closes at once too and is carried to the next entry until a write succeeds; a refusal marks nothing locally (no render cache, pending mark intact, flag false) and does not auto-fire again that session while the entry still opens it; a failed eligibility read setseligibilityError(dismissible) while the flow stays closed and the page entry still opens it; the real gate against the realuseTheme: closed until the tour ends, opens, stays open throughonCreated, closes ononDone; a new user who reloads between the tour and the chapter (server says onboarded, browser holdsmc-crewmates-pending) is still offered it, and finishing it clears the mark; stays closed (and reads nothing) while the Crew Members preview is off; stays closed with an existing crewmate or an installed custom agent; an already-onboarded workspace counts as done yet the Crewmates page event still opens it.test/test_api_theme_config.py— the payload carriescrewmates_onboarded; PUT persists it and rejects a non-boolean.test/test_config_loader.py— defaultFalse, round-trips.website/src/test/App.importChapterReopen.test.tsx— theme mock carries the two new members.Manual verification
Static gates locally (tsc, eslint, i18n gates, phantom-classes, black/isort/flake8/mypy, docs lint, feature map, jscpd,
npm run build); CI runs the suites. The flow below was driven through its own buttons by Playwright against a Vite dev server of this head, every/api/*answered by fixtures; the capture asserted 135 checks per run (one dialog, step counter, vocabulary, theme, no raw keys, every footer button inside the viewport, the two writes' bodies:POST /api/agentswith the job asdescription,POST /api/cronswithmember_id= the identity the create returned, non-silent,hide_in_chat: false,0 9 * * *, a message that is the job text alone).Screenshots / video
Screenshots: real components rendered against stubbed
/api(Vite + Playwright); backend exercised by CI only. 1440x900. Every frame below was driven through the flow's own buttons; the capture asserts the state before each shot.Step transitions 1 → 4 (slide between steps, footer cross-fade), dark:
Entry point and every introduced error / busy state (dark)
defaultrow: the Meet CrewMates entry with its one-line gloss as a block line under the buttonThe page behind the scrim still reads "Crew Members": the roster rename is a sibling PR of the launch, not this one. A fresh workspace's roster carries the built-in
defaultrow (the main assistant), which is why the entry condition is "onlydefault", not "empty".Related Issues
Part of the CrewMates launch (screen 08). The job text is stored in the existing
descriptionfield; if a dedicated standing-job field lands in a sibling PR, this flow should write it too (one-line follow-up). A failed roster or installed-agent read in the gate itself keeps the automatic chapter closed on purpose (fail-safe: do not interrupt when unsure); the Crewmates page entry stays available.Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)