Skip to content

feat(members): the first mate enters center stage before it greets - #23222

Merged
iamwhatever merged 1 commit into
mainfrom
feat/first-mate-entrance
Oct 23, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
feat/first-mate-entrance

Conversation

@CrysisDeu

@CrysisDeu CrysisDeu commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The first time a person opens Mate's chat, they meet Mate -- its face enters centre stage, says hello, and flies into the header -- before Mate's greeting streams in.

Every install creates Mate (#18406) and Mate speaks first when its chat opens (mate_welcome.py), but nothing marks the moment a person first meets Mate: the Crewmates page opens on an empty thread and a greeting appears. Someone who has never heard of crewmates sees a chat with a name in it and no sense that this is a teammate who was just handed to them. #23207 asks for the introduction of the first Mate itself, separate from the launch intro (#17154) that introduces the feature.

Why it matters

The greeting introduces Mate's words, not Mate. Without an entrance, the one moment that can make "a crewmate" concrete -- a face, a line, a place it lives -- passes as a plain empty chat, for every new install.

Not a goal

What changed (motivation → approach → change)

Goal: introduce Mate once, in the one tab that is about to receive its first greeting, and never again.

Approach: key the entrance on the greet request's outcome rather than on a marker of its own. POST /api/members/{slug}/greet already answers started for exactly one request ever (the server's O_EXCL claim) and already_greeted / not_empty / busy / an error for every other, so that answer is already the once-only the issue asks for -- a reload, a second tab or a failed turn never hear started. This avoids a second marker and keeps the backend untouched. Mate only (isAssistantMember), since a dashboard-created crewmate's face and name were just chosen by the person.

Change:

  • useFirstGreeting gains an optional onStarted(slot) callback, fired only for the started answer, read through a ref so a new callback identity never re-asks. It fires before startServerTurn so the pane is veiled before the turn's "Working" row could show.
  • New MateEntrance.tsx: the face (150px) centred on the thread column with a role="status" speech bubble ("Hi! I'm your first Mate." while Mate is the only mate; "Hi! I'm {{name}}." once others exist, the same split the kickoff makes), a 1.5 s hold, a 0.9 s flight (translate + scale of a sharp large raster, portaled above every surface like CrewFaceFlight) to the header pill's face slot, a landing pop on the slot's own face and a ring. With no slot box (header not laid out) it cuts to landed instead of flying nowhere. prefers-reduced-motion: no face and no flight -- the bubble alone, static, for the hold.
  • useMembersPageThread owns the state (stage -> landed -> gone), scoped to the thread it was answered for; leaving mid-entrance ends it. While the face is on stage the header pill's slot (member-pill-face), Mate's roster row face and its face in the folded roster's switcher chip hold their place unpainted (data-entrance-empty, box kept), and the chat pane is veiled, fading back as the face lands.
  • Two i18n keys (pages.membersPage.entrance_first_mate, entrance_hello) across all catalogs with en.context.json notes.
  • Spec: docs/system-specs/modules/crew-mode.md "The first Mate's entrance"; rfc-crewmates-launch.md screen 08 amended to record the entrance as separate from the feature intro (RFC status accepted, already on main).

Backwards compatibility

Compatible: useFirstGreeting's new parameter is optional and every existing call is unchanged; CrewmateSwitcher's faceOnStageFor defaults to ''; no API, store or catalog key is renamed or removed.

Removes nothing: the diff only adds a component, an optional callback, optional props and two catalog keys.

Tests

  • MateEntrance.test.tsx (new): opens centre stage with the large face and the line, the slot not yet landed on; flies to the slot's box and lands there (exact end transform), pops the slot face and calls onLanded then onDone; reduced motion shows the line alone and never calls onLanded; a zero slot box cuts to landed; the host's line is what it says.
  • useFirstGreeting.test.tsx: onStarted fires with the slot for started only; stays silent on already_greeted, not_empty, busy, not_owed, no_thread, not_crewmate and on a failed request; the latest callback hears the answer and a new identity never asks again.
  • CrewmateSwitcher.test.tsx: the face of the mate on stage is held unpainted with its place kept; every face painted otherwise.

Ran only the changed test files locally (npx vitest run on the three), plus npx tsc --noEmit, eslint on the touched files, I18N_BASE_REF=origin/main npm run i18n:check, the per-locale style gates and the brand gate. No Python changed.

Manual verification

Recorded the real MembersPage (the capture/members-page.html entry on the Vite dev server) behind a stubbed API with website/scripts/capture-first-mate-entrance.mjs, as a fresh install whose roster is Mate alone with its welcome owed and unclaimed. Each frame asserts its state before it is written: one greet request answered started; the entrance on stage with the line; the pill slot, roster row and switcher face empty with their width kept; the pane veiled; landed with all faces painted; the greeting row delivered the way the WebSocket would, pane unveiled, still one greet. Three negative passes: already_greeted draws no entrance (a reload); reduced motion shows the line alone with the faces in place and removes it after the hold.

Not verified against a live gateway run of the kickoff turn; the greet outcome vocabulary is read from mate_welcome.py (STARTED = "started").

Screenshots / video

Dark, the whole entrance then the greeting:

Mate's face enters centre stage with its line, flies into the header name-pill, then the greeting streams in (dark)

Landed, light and dark:

Landed: the header pill and the folded roster show Mate's face, the greeting in the thread (light)

Landed: the header pill and the folded roster show Mate's face, the greeting in the thread (dark)

More frames: light recording, centre stage, reduced motion, no replay

Light recording of the entrance

Centre stage, dark: the pill slot and the switcher chip empty, the face and line in the middle

Centre stage, light

Reduced motion: the line alone, faces painted from the start

A reload (already_greeted): no entrance, faces painted

Media committed under .github/screenshots/first-mate-entrance/ at the request of the maintainer, referenced by commit-pinned URLs.

Related Issues

Closes #23207

The maintainer waived the captain-triage wait for this issue on 2026-10-22.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@CrysisDeu
CrysisDeu requested review from a team and KiroCrewCaptain as code owners October 22, 2026 23:01
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 22, 2026
@CrysisDeu
CrysisDeu force-pushed the feat/first-mate-entrance branch from f72ab06 to 11231b5 Compare October 22, 2026 23:41
@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 Oct 22, 2026
@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The entrance is keyed on the server's existing once-only started answer, so it adds no new marker and needs no backend change. Rendered evidence of this revision is committed and was admitted.

Notes

  • The pane veil only ends when MateEntrance calls landEntrance/endEntrance. If the component never mounts while entrance is set (for example, crewmateIdentity is undefined), the pane stays at opacity 0 until the person leaves the thread. Clearing the state whenever the stage can't render would remove that path.

[DESIGN-REVIEWED] 871943a

Description read

[DESCRIPTION-READ] 09db72af6eae012f43a2a0cd3951da4e4967057d9beb83de30231425606bfe4f

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 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 6.1 flagged blocking issues on 871943a264f3c7c01fa538bee1d938ab04b639c0; Opus 5.5 adjudication downgraded every one of them. Downgraded: the remedy each one needs is disproportionate to the harm it prevents. Adjudication downgraded all 1 blocking finding(s): the remedy each one requires is disproportionate to the harm it prevents.

This comment is updated in place on each push.

Review details

BLOCKING -- website/src/pages/members/useFirstGreeting.ts:73 -- A delayed greet response lets the greeting appear before the entrance

onStartedRef.current?.(slotKey)
Trigger: On Mate’s first open, greeting frames arrive over the existing WebSocket while the HTTP /greet response is delayed. maybe_start_first_greeting schedules the turn independently; useChatStream updates Redux and the mounted ChatPane, but this callback waits for HTTP success.
Outcome: The greeting appears before Mate’s entrance, then disappears behind the newly veiled pane when started arrives. Calling the callback before startServerTurn does not prevent WebSocket-driven rendering.
Anchor: defect
Fix: Veil the eligible empty Mate thread before issuing /greet; release the veil on a declined outcome or error, and retain it through the entrance on started.

[BLOCK-MERGE-DOWNGRADED] 871943a
[GPT-REVIEWED] 871943a

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

F1: LOW harm, and only cosmetic. The race needs the WebSocket greeting frames to reach the client before the HTTP /greet reply. The server sends that reply right after _dispatch_greeting (src/kiro_crew/dashboard/mate_welcome.py:348-349), but the greeting's first output only comes after the model starts talking (useFirstGreeting.ts:61-62). If the race happens, onStarted still veils the pane and the entrance plays and fades back in (useFirstGreeting.ts:73, MembersPageThread.tsx:622,1086). Nothing is lost and nothing becomes visible that should not.
The real fix means veiling every eligible empty Mate thread before the request. That adds new state shared between the hook and the entrance, plus release paths for every declined outcome and every error. Future readers carry that cost permanently, for a flicker that happens once at most.

[ADJUDICATION] 871943a264f3c7c01fa538bee1d938ab04b639c0 total=1 uphold=0 downgrade=1
DOWNGRADE F1 website/src/pages/members/useFirstGreeting.ts:73 reason=disproportionate-remedy
[GPT-ADJUDICATED] 871943a264f3c7c01fa538bee1d938ab04b639c0

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 871943a264f3c7c01fa538bee1d938ab04b639c0: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 871943a264f3c7c01fa538bee1d938ab04b639c0 — 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: PASS

Nothing blocks. The one open question is whether this counts as a product-shape decision, and the opt-in Crew preview leaves that a judgement call, so it stays a note.

Notes

What this change ships

Inventory (10 items) — 9 justified

Intent: the first time someone opens Mate's chat, they meet Mate as a teammate with a face before its greeting appears. This is an ADDITION.

  1. The first time Mate's chat opens, Mate's face enters centre stage with a hello bubble. — justified
  2. The face flies into the header name pill's slot, then pops with a ring. — justified
  3. The chat pane is hidden until the face lands, then fades back in. — justified
  4. The pill, roster-row and switcher faces stay blank while Mate is on stage. — justified
  5. The line reads "your first Mate" while Mate is the only mate, and "Hi! I'm {name}" once others exist. — justified
  6. With reduced motion, only the static bubble shows. — justified
  7. The greet hook gains an optional onStarted callback. — justified
  8. Two new strings, in every locale. — justified
  9. The launch RFC's screen 08 is amended to record the entrance. — inherited
  10. A capture script, a safe-area allowlist row and screenshots are added. — justified

[FIRST-PRINCIPLES-REVIEWED] 871943a

Description read

[DESCRIPTION-READ] bc09880994434f775a9fc65d4ea51a1f00a2ec05f90c81881fe9d527414edae7

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 Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing blocks. The motion itself still needs a human to watch the committed GIFs: the blind reader saw only one frame of each, so it could not confirm the big face becomes the header face.

Notes

  • During the entrance, CrewmateSwitcher gets faceOnStageFor={entranceFaceHidden ? active.name : ''}, which blanks the face in the top-left switcher chip. The flight never lands there, so the chip just sits empty. The blind reader (shot-01/06) said it "looks broken or unfinished" and was "hesitant" to click it. Keep the chip's face painted and hide only member-pill-face, the one slot the face lands in.
  • entrance_first_mate ("Hi! I'm your first Mate.") left the reader wondering "whether more Mates are coming and whether I'll have to manage them". The greeting that follows doesn't answer that. If that's intended, say it in the kickoff line; if not, drop "first" ("Hi! I'm Mate.").

[UX-REVIEWED] 871943a

Description read

[DESCRIPTION-READ] 79c70d65a389412bb98d103644affeb9a7134cd3f8b0c763f1a9fac633a9eb4d

That sha256 names everything this verdict read: the PR description, plus the 11 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 added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 23, 2026
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 871943a264f3c7c01fa538bee1d938ab04b639c0 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 871943a

Verdict parsed from the review's SHA-scoped output markers for commit 871943a264f3c7c01fa538bee1d938ab04b639c0.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 871943a264f3c7c01fa538bee1d938ab04b639c0: <one-sentence reason>

@CrysisDeu
CrysisDeu force-pushed the feat/first-mate-entrance branch from 11231b5 to c99d6ff Compare October 23, 2026 00:39
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 23, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles c99d6ff: Product owner decision 2026-10-22 (issue #23207): every new install meets its first Mate once before the greeting; the RFC screen 08 amendment in this PR records that decision.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@CrysisDeu marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for c99d6ff2f6813262a15bdf4100c5e730ed10336c.

Product owner decision 2026-10-22 (issue #23207): every new install meets its first Mate once before the greeting; the RFC screen 08 amendment in this PR records that decision.

This decision applies only to this commit. A new push requires a new judgment.

@CrysisDeu
CrysisDeu force-pushed the feat/first-mate-entrance branch from c99d6ff to 01aab93 Compare October 23, 2026 07:02
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 23, 2026
@CrysisDeu

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles 01aab93: Product owner decision 2026-10-22 (issue #23207): every new install meets its first Mate once before the greeting; the RFC screen 08 amendment in this PR records that decision.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@CrysisDeu marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 01aab933e2f9864b8e55efa097ae354ba1f991fd.

Product owner decision 2026-10-22 (issue #23207): every new install meets its first Mate once before the greeting; the RFC screen 08 amendment in this PR records that decision.

This decision applies only to this commit. A new push requires a new judgment.

The first time Mate's chat opens and its greeting is dispatched, Mate
introduces itself before it speaks: the header name-pill's face slot (and
Mate's roster row, and its face in the folded roster's switcher chip) hold
their face unpainted; Mate's face appears large at the centre of the thread
with "Hi! I'm your first Mate." ("Hi! I'm {{name}}." once other mates
exist); after 1.5 s it flies into the pill's face slot, lands with a pop
and a ring, the slot and row fill, and the greeting turn streams in as
before.

Once per thread by construction: `useFirstGreeting` gains an `onStarted`
callback fired only for the greet request the server answers `started`,
the one outcome that means the greeting was dispatched now. A reload, a
second tab or a failed turn hear `already_greeted`, `not_empty` or an
error and show nothing; no second marker is added. Mate only: a mate
created on the New mate card already showed the person its face and name.

`prefers-reduced-motion`: faces painted from the start, the line shown
static for the same 1.5 s, no flight.

Spec: crew-mode.md "The first Mate's entrance"; rfc-crewmates-launch.md
screen 08 records the entrance as separate from the feature intro.

Closes #23207
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 23, 2026
@CrysisDeu
CrysisDeu force-pushed the feat/first-mate-entrance branch from 01aab93 to 871943a Compare October 23, 2026 07:28
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 23, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Human design review is required before this PR can merge. The first Mate entrance changes launch UX, while HTTP/WebSocket ordering and pop cleanup still need maintainer decisions. This comment records the design gate only; it is not a code defect.

@iamwhatever
iamwhatever merged commit 597f93c into main Oct 23, 2026
203 of 207 checks passed
@iamwhatever
iamwhatever deleted the feat/first-mate-entrance branch October 23, 2026 17:42
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(members): the first Mate enters center stage, then flies into its avatar before greeting

3 participants