Repository navigation
feat: let any crewmate guide users to the control on their screen - #18301
Conversation
Sensitive Change ReviewSensitive files changed:
How to clear this check:
Only the author's comment counts this way. A reviewer can instead |
GPT 6.1 Review — 🔴 changes requested (blocking)GPT 6.1 found at least one blocking issue that must be resolved before merging This comment is updated in place on each push. BLOCKING -- src/kiro_crew/guide_catalog.py:832 -- Load guide catalogs off the gateway event loop
BLOCKING -- docs/feature-map/README.md:412 -- Preserve the active automatic first-run flow in the feature map
[BLOCK-MERGE] 40c156a Adjudication (Opus 5.5) — is blocking on each finding proportionate?F1: Both the file and the rule check out. F2: Both the file and the rule check out. The Meet CrewMates row at False positive or not applicable? A repository writer can comment: |
First Principles Review (Opus 5.5) — 🟡 CONCERNSPremise-level review of First-Principles-Verdict: CONCERNS The Crewmates page rework replaces what New crewmate opens and removes the on-demand Meet CrewMates entry. That is outside the Goal, and the RFC doesn't cover it. Not justified as shipped
What this change shipsInventory (10 items) — 7 justifiedIntent: let a crewmate show a user where a Kiro Crew control is on their own screen. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 40c156a Description read[DESCRIPTION-READ] 74efb9138088993f496b9b527355fef545c1d2d69be7c7bd3a6a8ed3a2c34ae9 That sha256 names the PR description this verdict read. Recompute it with |
| const key = prefix ? `${prefix}.${k}` : k | ||
| if (typeof v === 'string') { | ||
| if (v.includes('{{')) { | ||
| const parts = v.replace(TAG_RE, '').split(/\{\{[^}]*\}\}/).map(noSpace) |
There was a problem hiding this comment.
Rebutted: not an HTML sanitizer.
flatten in findTargetPolicy.ts reads the packaged translation catalog and strips <Trans> tags only to derive comparison parts for templateMatches. Those parts are used by startsWith / endsWith / indexOf to resolve catalog keys and are never inserted into the DOM, so a residual <script fragment stays comparison data. Rendering of untrusted content goes through untrustedContent.ts (DOMParser, no HTML assignment) and DOMPurify.
Record the product owner's 2026-10-08 decision, taken after the team review, so the First Principles lane can read it from the base branch when #18301 and #18317 change default mounts and first-visit landing. Part 1: one read-or-offer MCP server, kirocrew-guide, mounted for the kirocrew template, its crewmates, worker and dashboard sessions. Guides highlight the real control and change cards apply only on the user's press, from a dashboard turn the user sent; trust-root areas are answered in words only. Part 2: Kiro Crew creates one ordinary crewmate, Mate, once. It opens first on the Crewmates page while never chatted with, writes its own welcome, and renames itself through rename_self. default stays the shared fallback crew. The document amends sections of rfc-crewmates-launch, rfc-crewmate-greeting and rfc-crewmates-chatted-list rather than editing those accepted documents. The index gains its row and audit note.
3637e85 to
639dc8c
Compare
|
|
|
|
|
|
357d004 to
8eb25f3
Compare
|
|
|
|
|
|
8eb25f3 to
a038c93
Compare
A crewmate asked "where is X?" or "how do I do Y?" about Kiro Crew can now answer from the dashboard itself instead of from memory. The kirocrew-guide server gains find_ui (a search over a location index generated from the dashboard source, in 12 languages), search_docs (the packaged user docs) and guide_start / guide_status / guide_cancel. A guide is an offer card in the chat. Nothing moves until the user presses Start; then the dashboard opens the page and outlines the real control, step by step, and every click is the user's. Only a turn the user sent from the dashboard may offer one. Trust-root controls (the security policy, approvals, the approval-mode picker, a crewmate's permission picker, computer use, secrets) get no guide and are answered in words. Each offer is also a card row of the conversation and a guide/* entry in the crew log, so it stays where it was offered across a reload.
a038c93 to
40c156a
Compare
|
Scope change, at the owner's request (@buluoray): this PR is now split into three, merged in order.
The change-card code and its tests moved out of this diff; the card row in the conversation stays, because a guide offer is drawn the same way. |
|
This PR was merged into |
Problem / Motivation
Goal: Let any crewmate answer "where is X?" and "how do I do Y?" about Kiro Crew by pointing at the real control on the user's screen, with every click still the user's.
Today a crewmate asked "where do I turn on the terminal?" can only describe the dashboard from memory or tell the user to search Settings and the docs. It cannot see where a control lives on this build or show it on the live page, where the control is often behind a collapsed sidebar, a closed menu or a phone layout. The decision is recorded in
docs/request-for-change/rfc-crewmate-guides-and-mate.md(accepted, merged in #18326). This is the second of three PRs that ship it: Mate (#18406, the base of this PR), then guided tours (this one), then change cards.Why it matters
The long tail of Kiro Crew settings is where people get stuck, new and existing users alike. A crewmate that finds the exact control and walks the user to it on their own screen turns a docs search into a one-message request.
Not a goal
What changed (motivation → approach → change)
Approach: extend the
kirocrew-guideserver from #18406 with tools that can only read or offer. Pointing at the UI uses an index generated from the dashboard source and the live page, not a remembered map; the gateway owns every guide's state.src/kiro_crew/mcp_guide.py):find_ui(search or browse the location index, labels in the user's dashboard language),search_docs(packaged user docs),guide_list_actions/guide_start/guide_status/guide_cancel. Trust-root and caution rules travel in each tool's text and each result'snextline. All seven tools are exactallowedToolsgrants (agent._GUIDE_AUTO_GRANTS,config/defaults.json), through the governance ceiling.ui_index.py,website/scripts/gen-ui-index.mjs,website/src/uiLocations): curated plus auto-stamped controls in 12 languages, generated intosrc/kiro_crew/docs/ui-index.generated.jsonandguidePlans.gen.ts; CI checks it is current.GUIDE_DENY_IDSmarks the approval-mode picker and a crewmate's permission pickerdeny.guide_catalog.py,dashboard/guide_runs.py,dashboard/guide_observe.py,dashboard/handlers/guide.py): registered actions (settings.show,crewmate.create,mcp.open_add,ui.show,ui.find), claim/progress/lease per tab, reveal, select and gate steps, viewport re-planning, and a bounded live observation of one tab. Starting a guide uses feat: welcome users with Mate, a first crewmate they get to name #18406's admission: only a turn the user sent from the dashboard.website/src/guide,GuideLayer.tsx,GuideOfferCard.tsx): the offer is a card in the chat; after Start, the layer opens the page and outlines the control beside a step panel, and a press on the target finishes the step. Each offer is acardrow of the conversation (dashboard/chat_cards.py,cards/ConversationCard.tsx) and aguide/*crew-log entry, so it stays where it was offered across a reload.MembersPage.tsx,MeetCrewmatesFlow.tsx): New crewmate and a crewmate's create link open the embedded flow in place of the chat; Advanced opens the full form.Smaller pieces:
crew_log/emit.py,crew_log/entry_types.py,crew_log/schema.pyandhistory_projection.pyadd theguide/*entries and the display-onlycardrole;chat_runner.pyreads past a card row;security_posture.pylists the guide-row redaction sink and the gate-side catalog;validation.pyholds the argument schemas;dashboard/server.py,server_runtime/mcp_routes.py,dashboard/state.py,chat_handlers.py,ws_event_scope.pyandagent_admin/crew_records.pywire the routes, the sending tab and the crewmate-create hook;src/kiro_crew/appsandwebsite/src/appsmark delete buttonsguideCaution;website/src/api,website/src/store,website/src/hooks,website/src/components,website/src/shell,website/src/surfaces,website/src/lib,website/src/pages,website/src/app-sdk,App.tsxandvite-env.d.tscarry the markers and wiring;src/kiro_crew/agent.pyandsrc/kiro_crew/agent_materialization(service agents) grant the new tools and keep them off background agents;website/src/i18nholds the strings;.github,.gitignoreandsrc/kiro_crew/builtin_skillsrun the index check;src/kiro_crew/docsanddocs/cover MCP, crew log, crew mode, history, config and the feature map;test/gui_useradds scenarios.Backwards compatibility
Compatible: agents that do not mount the server behave as before, and the new routes refuse callers they cannot attribute to a dashboard turn; they accept nothing main accepted before.
Reader: website/src/pages/members/MembersPage.tsx:meet_crewmates -- crew page -- the empty-roster Meet CrewMates button and its locale keys are removed; the empty state's New crewmate hero opens the same flow (
MembersPage.test.tsx)Tests
test_find_ui*.py,test_guide_*.py(routes, runs, observation, reveal/select/gate steps, re-plan, the approval-mode and permission pickers never guided),test_guide_admission.py(real admission for start and reads: channel turns and non-user turns refused, reads still answer),test_guide_server.py(mount, per-tool grants, off-dashboard wording, offer hints),test_search_docs.py, plus updated composition, spec-byte, crew-log and MCP contracts.src/guide/*.test.tsx,src/uiLocations/*.test.ts,cards/ConversationCard.test.tsx,ChatPane.cardColumn.test.tsx,TurnBlock.cardRow.test.tsx,chatSlice.cardRow.test.ts,MeetCrewmatesFlow.test.tsx, Members page cases.not_user_turncheck, the trust-root route check or aGUIDE_DENY_IDSentry reddens a named test.Manual verification
Earlier heads, live on a preview gateway with real model turns: "where do I change the theme?" →
find_ui+guide_start, and Start opened Settings → Display and outlined Theme; "How do I delete a schedule myself? Show me." → a two-step guide ending on the outlined Delete with its caution line, nothing deleted; at 390px the card and step render as a bottom sheet. Gates on this head: black, subprocess-encoding, isort, flake8, mypy, docs-lint, harness parity,tsc,npm run build(with the index check), i18n against origin/main, eslint on changed files; related pytest (about 18.8k tests; the only reds,test_agent_template_skills.pyreorder cases, also fail on origin/main on this host) and vitest (881 targeted; the wider run's other reds also fail on the #18406 branch on this host). Not exercised: Windows and macOS hosts.Screenshots / video
All frames from an earlier head of this branch.
Related Issues
Closes #18300
Part of the RFC in #18326; based on #18406 (Mate); followed by a change-cards PR.
Pattern harvest
Not generalizable: a feature PR.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.