Skip to content

feat(members): default headless crew-create to a name-seeded icon - #22644

Merged
iamwhatever merged 1 commit into
mainfrom
kc-wt-20865
Nov 1, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
kc-wt-20865

Conversation

@dodgeblaster

@dodgeblaster dodgeblaster commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A crewmate created without choosing an avatar shows a name-seeded icon, whichever way it was created.

A crewmate made in the UI already gets a name-seeded icon (#20392). One made headlessly — POST /api/agents with no avatar, or kirocrew agent create — stored an empty avatar and rendered the trait "ghostface" #20392 is retiring. So today the default face depends on how the crew was created.

Why it matters

#20392 promised that a crewmate born without an explicit pick is an icon, never a ghost the user did not choose (#18616). That promise only held for the two UI paths; a crew made by CLI or a direct API call was still born a ghost.

Not a goal

  • Re-skinning crews that already exist — an already-set avatar (ghost included) is left exactly as it is.
  • Re-rolling the icon when a crew is renamed.
  • Any change to how avatars render; this only sets the stored default.

What changed (motivation → approach → change)

A headless create stored an empty avatar, which the renderer falls back to as the name's ghost. The fix defaults the avatar from one shared helper, so every create path lands on the same icon the UI posts for that name.

The approach is parity, not a lookalike: the icon must be the same one the UI previews for a given name, and the UI derives it through @dicebear/core's seeded PRNG in website/src/lib/avatarPoses.ts. A new backend module, crew_avatar_seed.py, reproduces that generator exactly — the PRNG, the UTF-16 seed hashing (so an emoji name hashes as its surrogate pair, as in the browser), and the sequence of draws createAvatar makes before the pose/background pick — and tolerates the out-of-range index a max-valued draw yields (as the frontend's ?? fallback does) so no name crashes. A test pins the result name-for-name against the real frontend and pins the @dicebear/core version, so a dependency bump that moves the pick fails the test.

Every create=True path then applies default_icon_avatar(name) when no avatar was supplied: the raw API (dashboard/agent_admin/crew_records.py, importing the helper locally because it runs in the agents facade's injected namespace), the CLI (cli_commands_agent.py), the first-crewmate bootstrap (agent_materialization/first_crewmate.py), and the auto-improvement app's role provisioning (apps/builtins/auto_improvement/backend/crew.py). An explicitly supplied avatar is never overridden — including an explicit ghost reset, which collapses to an empty override but is a deliberate choice of the name-derived ghost. Seeding from the shown name (display_name or key) matches what the roster draws.

Backwards compatibility

Compatible: only an ABSENT avatar on create is affected — it changes from an empty override (which drew the ghost) to a name-seeded icon. An explicitly supplied avatar of any kind is passed through unchanged, and existing crews are not touched.

Removes nothing: no field, path, record or capability is removed; this adds a default where there was none.

Tests

  • test/test_crew_avatar_seed.py — pins the backend seeding to the real frontend output name-for-name (a frozen table captured from @dicebear/core 9.4.3 across ASCII, case, CJK, accented, an astral emoji, trimmed whitespace and a long name); asserts determinism and the exact {kind, pose, bg} shape; proves pick falls back rather than crashes on the out-of-range index a max-valued draw yields; reads the pose list, palette, defaults and the pinned @dicebear/core version back out of the frontend source so a changed art set or a version bump fails the test and forces a re-sync.
  • test/test_api_agents_create_template.py — a no-avatar POST /api/agents stores the name-seeded icon (never an empty override); an explicit icon, ghost, or ghost-reset avatar is not overridden; a free-form name seeds from its shown label.
  • test/test_cli_agent.py — kirocrew agent create stores the same name-seeded icon, including seeding a free-form name from its display label.

Manual verification

N/A — unit coverage pins the stored default on both headless paths and its parity with the frontend; nothing renders differently that the existing avatar tests do not already cover.

Related Issues

Fixes #20865

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 146d639a60709edf20e1b2af291ff2d7eaf8720e touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The change stores a default only when no avatar was given, leaves existing crews alone, and pins Python–frontend parity to the frontend source and the @dicebear/core version.

Notes

  • The Python port of the DiceBear PRNG is a second copy of the generator, kept in sync only by test_crew_avatar_seed.py. A simpler design would have the backend store a {"kind": "icon"} marker and let the frontend choose the pose and background. That is a follow-up, not a fix needed in this PR.

[DESIGN-REVIEWED] 146d639

Description read

[DESCRIPTION-READ] 6499c957928a87eb35fa0c65b97a19daef47d6ac631a05316333dfaa03f0d49d

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 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 146d639a60709edf20e1b2af291ff2d7eaf8720e — 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

The fix is justified by #20865. The issue is its size: 265 lines rebuild DiceBear's random-number generator draw for draw in Python, and that exact parity has no consumer.

Notes

  • Item 6 — oversized: the description says "the icon must be the same one the UI previews for a given name", but a headless create has no UI preview. Both UI paths post their own defaultLookFor(name) (NewCrewmateDialog.tsx:426, AgentTemplatesTab.tsx:475). CrewAvatarBuilder.tsx:450 shows a stored icon's own pose and only seeds when no icon is stored. So matching DiceBear's output removes no harm beyond what any fixed name-to-icon pick removes. Subtraction: replace _Prng, _xorshift, _hash_seed, _utf16_code_units and _advance_for_background in crew_avatar_seed.py with a plain name hash used as an index into POSE_IDS and ICON_BG_PALETTE. Delete EXPECTED, test_dicebear_version_matches_the_capture and test_pick_tolerates_the_max_draw_index.
  • Item 7 — oversized: test_dicebear_version_matches_the_capture turns every future @dicebear/core bump into a red backend test that someone must fix by re-capturing the table. That cost lasts forever and only exists to guard the parity in item 6. Subtraction: it goes away with item 6's subtraction.

What this change ships

Inventory (7 items) — 5 justified

Intent: a crewmate created without picking an avatar shows a name-seeded icon whichever way it was created. FIX (#20865).

  1. POST /api/agents with no avatar now stores a name-seeded icon instead of the ghost — justified
  2. kirocrew agent create now stores a name-seeded icon — justified
  3. The first crewmate created at bootstrap is born with an icon, not the ghost — justified
  4. Crews the auto-improvement app provisions are born with an icon — justified
  5. An explicit ghost or ghost-reset avatar on create is still kept as given — justified
  6. A Python port of DiceBear's generator so the backend pick matches the frontend exactly — oversized: no consumer needs exact parity
  7. A backend test that fails whenever the @dicebear/core version changes — oversized: guards item 6 only

[FIRST-PRINCIPLES-REVIEWED] 146d639

Description read

[DESCRIPTION-READ] 437e1b687c0309d88a664de8d866131499e287298eb7386ecba83d449ea45e6f

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 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 146d639a60709edf20e1b2af291ff2d7eaf8720e — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 146d639

Verdict parsed from the review's SHA-scoped output markers for commit 146d639a60709edf20e1b2af291ff2d7eaf8720e.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 146d639a60709edf20e1b2af291ff2d7eaf8720e 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 Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 146d639a60709edf20e1b2af291ff2d7eaf8720e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 146d639

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

@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 21, 2026
@dodgeblaster
dodgeblaster force-pushed the kc-wt-20865 branch 2 times, most recently from 3334263 to 09ce65a Compare October 21, 2026 03:10
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Moved the default_icon_avatar import in cli_commands_agent.py to a function-local import so the cli_commands facade mirror no longer serves it (fixes the Backend Tests shard-1 facade composition-contract failures: test_every_served_name_is_defined_by_the_owner_serving_it / test_a_star_import_binds_what_the_unsplit_module_bound). Also rebased onto current main (4d5cb47 -> 318f639; no file overlap). CI re-running.

@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
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Backend Tests shard 4 (Backend Tests (3.12, 4) and Backend Tests (Windows) (4)) is red on test/test_telegram_dispatcher.py::TestABusyReplyCarriesItsContext (test_an_injection_reply_on_the_queue_path_audits_exactly_once and test_a_declined_steer_with_an_injection_parent_audits_once_at_the_queue).

This is a pre-existing failure on main, tracked in #24514 (fix in flight). This PR's diff touches only the avatar-seed area (crew_avatar_seed.py and its callers) and does not touch src/kiro_crew/telegram/, so this red is not introduced here. Treating it as an accepted named red and not rebasing to chase the main fix.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 26, 2026
@dodgeblaster
dodgeblaster marked this pull request as ready for review October 27, 2026 16:02
@dodgeblaster
dodgeblaster requested review from a team and KiroCrewCaptain as code owners October 27, 2026 16:02
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 29, 2026
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased onto main cd15d80 to clear the merge conflict in crew_records.py (main added start_template_refusal beside this PR's default-icon block; both kept). Diff unchanged otherwise; CI re-running.

@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 30, 2026
A new crewmate created through the UI gets a name-seeded icon avatar
(#20392), but one created headlessly (POST /api/agents with no avatar, or
`kirocrew agent create`) stored an empty override and rendered the trait
ghost #20392 is retiring. Apply the same default server-side at the shared
create point so every path lands on the same icon.

A new module crew_avatar_seed.py reproduces the frontend's DiceBear-seeded
pick (avatarPoses.ts, @dicebear/core 9.4.3) exactly -- the PRNG, the UTF-16
seed hashing, and the draw sequence createAvatar makes before the pose/bg
pick -- so a given name yields the same icon the UI previews. Both create
paths apply default_icon_avatar(display_name or name) only when no avatar
was supplied; an explicit avatar is never overridden.
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Fixed the Backend Lint red on 558d844: the file-line cap (dashboard/handlers/agents.py at 2,001 lines, cap 2,000). The re-export line this PR added there is gone; crew_records.py imports default_icon_avatar locally instead, matching the start_template_refusal import beside it. Coverage Gate was only downstream of that lint failure. Also rebased onto main 0085b1c (none of the new commits touch this PR's files). New head 146d639; CI re-running.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 30, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:

Approving at 146d639.

This closes the remaining gap from #20392: a mate created without an avatar through POST /api/agents, kirocrew agent create, the first-crewmate bootstrap or the auto-improvement app was still born the name's ghost, while the UI path already gave it a name-seeded icon. All four now store the same {kind: icon, pose, bg} the UI would pick for that name. An explicitly sent avatar, including an explicit ghost reset, is kept. Main does not have this yet, and avatarPoses.ts has not moved since the base, so the parity table still holds.

Checked: dropping the explicit-ghost-reset guard in crew_records.py reddens test_explicit_ghost_reset_is_not_replaced_by_the_icon (both parameters).

Worth knowing: because the first-crewmate bootstrap is included, every new install's first mate now starts as an icon instead of a ghost.

Non-blocking follow-ups:

  • docs/system-specs/modules/crew-mode.md describes the name-seeded icon default only for the New mate dialog. Please add the headless create paths and the explicit-ghost-reset exception.
  • The Python PRNG port means any change to the pose list, the palette or the @dicebear/core version needs a matching change in crew_avatar_seed.py. test_crew_avatar_seed.py will fail until that is done, which is the right guard. A one-line note in avatarPoses.ts pointing at the Python mirror would save the next editor a surprise.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve at 146d639.

A crewmate created without an avatar through POST /api/agents, kirocrew agent create, the first-crewmate bootstrap or the auto-improvement app now stores the same name-seeded icon the UI would pick. An explicit avatar, including an explicit ghost reset, is kept, and an invalid one is still refused (crew_records.py#L543). avatarPoses.ts and the @dicebear/core 9.4.3 pin are unchanged on current main, so the parity table still holds. Checks are green and the branch merges cleanly. Note that every new install's first crewmate now starts as an icon.

AI findings judged non-blocking

  • Design note: a {kind: icon} marker would avoid the Python port. This is an optional alternative, and test_crew_avatar_seed.py fails if the two generators drift (crew_avatar_seed.py#L256).
  • First Principles items 6 and 7: exact DiceBear parity and the version-pin test are oversized. That is a size and maintenance preference; the port is deterministic and cannot crash on any name.

I read the diff, the tests and CI results; I did not run anything locally.

— crew-pr-reviewer (r138)

@iamwhatever
iamwhatever merged commit 692302a into main Nov 1, 2026
94 checks passed
@iamwhatever
iamwhatever deleted the kc-wt-20865 branch November 1, 2026 06:09
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 1, 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.

Default headless crew-create (CLI, raw API) to a name-seeded icon, not the trait ghost

3 participants