Skip to content

feat: add Captain, a built-in assistant with confirm-to-apply changes - #15326

Closed
buluoray wants to merge 2 commits into
mainfrom
feat/crewmate-assistant-integration
Closed

buluoray wants to merge 2 commits into
mainfrom
feat/crewmate-assistant-integration

Conversation

@buluoray

@buluoray buluoray commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Give every user a built-in assistant, Captain, that finds things in Kiro Crew, walks them to the exact control on the live page, and makes the changes they ask for after a single confirmation, so nobody has to learn the dashboard first.

New users land in a dashboard full of pages and settings they have not seen, and the answer to "where is X?" or "turn on Y" is a search through Settings or the docs. Creating a crewmate opens a technical dialog. There is no one in the product a person can simply ask, and nothing that can make a setting, schedule or crewmate change for them while keeping them in control. A static map of locations is also not enough: the control a person needs is often behind a collapsed sidebar, a closed menu, an unselected item or an off switch, and is placed differently on a phone.

Why it matters

The first minutes decide whether someone keeps using Kiro Crew. A newcomer who can ask in their own words, see the exact control highlighted on the screen in front of them, and confirm a prepared change with one press gets real work done on day one, and learns the product by using it. Existing users get the same help for the long tail of settings without reading docs.

Not a goal

  • Applying any change without the user's own press, or adding a path that bypasses approvals, governance or the security policy. Trust-root files (security policy, profiles, admission policy, computer-use) get no proposal kind at all.
  • Reading another member's private memory. Captain reads only its own memory and, read-only, the user's Global preferences document.
  • Changing the default member, its template or its conversations.
  • Replacing the existing settings pages, the MCP server form or the crewmate editor. Captain's changes replay the same routes those pages call.
  • Letting the model drive the page. A guide only highlights and explains; every click is the user's, and Captain's own words appear only inside the guide panel, attributed to it.

What changed (motivation → approach → change)

Approach: one built-in crewmate with a narrow, approval-free toolset that can only READ or PROPOSE. Everything that changes state is a card the user presses; the gateway, not the model, owns what the card does. Pointing at the UI uses the live page, not a remembered map.

  • Captain member (kirocrew-captain): installed once, protected from delete and re-keying, private memory, a read-only view of the user's Global preferences. First open of the dashboard lands in Captain's conversation. Its pre-tool narration is folded into the turn's activity row, so a turn shows one answer.
  • kirocrew-guide MCP: find_ui, search_docs, find_setting, diagnose_settings, guide actions and propose_change / get_change_status. Labels come back in the dashboard's own language (the tab sends it with each chat request), so Captain quotes what the screen shows.
  • Change cards for settings, schedules and reminders, crewmates and their tools, MCP servers, connections, secrets (typed into a secure field Captain never sees), app trust and denied-command rules. The store is MACed under a vault subkey and every record's plan is rebuilt from kind + params on load; a write step is persisted before its route runs, and every transition is saved before it is broadcast, so an interrupted write is never replayed. Agent-written card text and parameters are refused when the output redactors would change them.
  • Live UI map for guides: generated location index (curated + auto-stamped buttons, 12 languages), live observation of the user's tab, reveal scopes (open the collapsed sidebar, menu or tab first), selection steps ("this crewmate is already open — Next"), gate steps (a setting that must be on), viewport re-planning at step boundaries. A guide only highlights and explains; the user clicks.
  • Guide panel: anchored beside its target, Captain's own short intro and per-step note attributed to it, a press on the target finishes the step, the finish chip retires itself.
  • Crewmates page: guided crewmate creation inside the page, receipt in the chat, phone roster.
  • Docs: MCP architecture, crew-log types, crew mode, dashboard handlers, history, memory, config, feature map. Strings in all 12 locales.

Product direction was agreed with the maintainer in the design discussion; no accepted RFC is claimed, so the First Principles lane may need a maintainer decision.

Backwards compatibility

Compatible: the default member, its template and conversations are untouched; Captain is an added member and every change it makes goes through routes that already exist. Existing create/update/delete routes refuse only the reserved kirocrew-captain key and Captain's display name, which no existing member can hold. The first-run landing moves from the plain chat to Captain only when Captain exists.

Removes nothing: no route, key, file or capability is taken away; the new refusals apply only to the new reserved Captain identity.

Tests

  • Backend: Captain install/protection, prompt composition and spec-byte goldens, change-card store (MAC, tamper rebuild, persist-before-publish, interrupted writes, parameter and text redaction, fresh-install key birth), guide routes, live observation, reveal/selection/gate steps, re-plan, find_ui in 12 locales, crew-log types, composition contracts. Related set: 4,012 pass; two teardown errors in test_crew_log_writer.py appear only under xdist and the file passes alone.
  • Frontend: change cards (incl. read failures and OAuth re-read errors), guide layer (placement beside the target, notes, select confirm, finish chip, target press), Captain narration folding, first-run landing, uiLocations, i18n: 2,517 pass.
  • Every review-round fix has a test that goes red when the fix is reverted.
  • Gates: black, isort, flake8, mypy, subprocess-encoding, i18n check, gen:ui --check, docs-lint, production build.

Manual verification

Several rounds of new-user QA in isolated pods built from this branch (desktop 1280×800 and phone 390×844, English and 中文 UI): "where is my chat history" / 会话历史在哪里, adding an MCP server, editing a crewmate's tools, the Developer Mode setting, a reminder card proposed, set and undone, first-run Skip all landing in Captain. Each issue found was fixed and re-checked in a fresh pod.

Screenshots / video

A new question gets one answer with the guide card in the same reply:

02-guide-offer

The guide panel sits beside its target, with Captain's own note under the step:

03-guide-step-note

A reminder card, then the same card after Set reminder:

06-change-card

06c-change-card-applied

The whole guide flow:

09-guide-flow.webm
More

First open lands in Captain:

01-captain-first-open

First-run Skip all lands in Captain's conversation:

01b-landing

Editing a crewmate's tools: confirm the selected crewmate, then the panel beside Permissions:

04-crewmate-permissions

A setting guide highlights the switch on its settings page:

05-setting-guide

A setting Captain cannot change gets a path instead of a card:

06b-theme-not-changeable

中文 UI: labels match the screen:

07-zh-guide

Phone (390×844):

08-mobile-guide

Related Issues

Follows #15097 (goal-focused crewmate onboarding).

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

@buluoray
buluoray requested a review from a team as a code owner September 30, 2026 06:41
@buluoray
buluoray requested review from kyleseaman and removed request for a team September 30, 2026 06:41
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of 8bfbeda4578a61eca5055099afed10810bfa7f3d — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

No recorded maintainer decision backs superseding the RFC's first-run flow and Crewmates landing — the description itself defers that call to a maintainer.

Watch

  • docs/request-for-change/rfc-crewmates-launch.md (screen 08, landing rule §02) records the auto-open Meet CrewMates chapter and the empty-state hero this PR removes in favor of landing on the Assistant; the description claims design-discussion approval but states "No separate accepted RFC... is claimed; the First Principles lane may require a maintainer decision." Merging rewrites a recorded product presentation on an unrecorded approval, so the next contributor finds the RFC and the shipped product disagreeing with no superseding entry.
    Clears when: a maintainer records the superseding decision (RFC amendment or decisions entry) or confirms the approval on the PR.
  • guide_catalog.py's settings exclusion (_EXCLUDED_SETTING_TABS + _EXCLUDED_SETTING_SEGMENTS) is a denylist over the generated settings registry, so a future credential- or trust-adjacent setting added outside those tabs with an unrecognized id segment becomes agent-guidable by default — the catalog widens silently with every registry addition, in the permissive direction, for a surface whose stated risk is "an agent-chosen nudge" at exactly those controls.
    Clears when: the registry generator carries a fail-closed guidable/sensitive flag per setting, or a snapshot test pins the exact guidable-id set so an addition is an explicit diff.

[DESIGN-REVIEWED] 8bfbeda

Description read

[DESCRIPTION-READ] 0b0137666cc792085dcd503e9dcdac637fec0a2eb3f77e1f5f15524a11f1a5a8

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 Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 1567f43d87b83d208947980a8626b78251a1a3f1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1567f43

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

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🔴 BLOCK

Premise-level review of 1567f43d87b83d208947980a8626b78251a1a3f1 — 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/CONCERNS are advisory.

First-Principles-Verdict: BLOCK

Product-shape change without accepted RFC: every install now gets Captain and lands in its chat, and the Meet CrewMates chapter no longer opens on its own.

Not justified as shipped

  • Item 2 — product shape, no decision recorded: "First open of the dashboard lands in Captain's conversation." The description says "no accepted RFC is claimed". The base RFC list has no entry for Captain or an assistant.
  • Item 3 — undeclared, framing contradicted: the description says "Removes nothing", but the diff deletes the chapter's tour-end and first-visit auto-open. The deleted pin's own words: "so an existing user is not interrupted mid-task on their next load". The PR gives no evidence that pin was wrong.

What this change ships

Inventory (8 items) — 5 justified

Intent: let anyone ask a built-in assistant to find, point at, and (after one confirmation) apply Kiro Crew changes. ADDITION.

  1. A protected Captain crewmate is installed on every install — product shape (default member)
  2. First open and first-run Skip all land in Captain's chat, not plain chat — product shape (changed default)
  3. Meet CrewMates no longer opens by itself after the tour or on the first Crewmates visit — undeclared, deleted pin
  4. Captain sends a one-time greeting turn on first open — justified
  5. Change cards that apply settings, schedules, crewmates, MCP, secrets and rules on a press — justified
  6. Live-page guides that highlight the target control — justified
  7. The kirocrew-captain key and Captain's display name are refused for other members — justified
  8. The chat tab sends the dashboard language with each request — justified

Blockers

  • Product-shape change without accepted RFC: Captain as the default first-run landing, replacing the chapter's auto-open
    Items 1–3 change what every new user gets without choosing. In App.tsx, useFinishFirstRun wraps markOnboarded, and useMeetCrewmatesGate loses tourEndDue and pageEntryDue. The base list has none of the four statuses (accepted, in-progress, partial, implemented) on any Captain or first-run RFC. Grepping captain|built-in assistant|first-run land in docs/request-for-change/ finds 0 files.
    Clears when: an RFC covering a built-in Captain as the first-run landing has merged with a non-draft status on the base (then push or rebase), or a maintainer posts /ai-review override first-principles 1567f43d87b83d208947980a8626b78251a1a3f1: <decision>.

[FIRST-PRINCIPLES-REVIEWED] 1567f43

Description read

[DESCRIPTION-READ] 0d4bd2c00fc8f093684a1341800264c9ee38637be17bfef3d32a18f69f12dc93

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 Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

UX-level review of 8bfbeda4578a61eca5055099afed10810bfa7f3d — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

Draft-vs-suggestion ambiguity, a self-contradicting empty roster, and a stale settings highlight each left the blind reader unable to tell what state they were in.

Watch

  • The draft-kept notice names neither side. onDraftKept={() => setDraftKept(true)} (MembersPage) discards the proposal the flow hands back, so the banner says only "Your crewmate draft was kept. The new suggestion hasn't replaced it." — the reader "genuinely cannot tell which part is my draft and which is the new suggestion" (shot-16). Hits every Assistant-proposed create over an edited draft; risk is creating the wrong crewmate. Fix: quote the unused proposal's goal in the notice.
  • Shot-17 shows "1 crewmate", "No crewmates yet", and a visible default row at once; the reader "can't tell if I have a crewmate or not". The count/hero copy predate this PR, but this PR rebuilds the hero (Advanced link) and the mobile ?view=roster path to it. Fix in this surface: exclude default from the header count or suppress the hero when a row renders beneath it.
  • Stale highlight between guide actions (shot-15). settings.show enters via settingsRoute(entry) which pins highlight=<id> in the URL; after Next, the "Default Model" row keeps glowing while the next action's Continue pill is up — "the purple highlight briefly points at the wrong thing". Every multi-action guide through Settings. Fix: strip the highlight param when the step is acknowledged.
  • "Advanced" is a bare adjective naming three things: the "+" menu row, the hero link, and the full form's own inner "Advanced" disclosure (all create_advanced). The reader was hesitant — "not for me" — and never connected it to the full form. Rename the menu row/hero link for the outcome, e.g. "Advanced form".

Suggestions

  • Unify the template field across the two creation surfaces: wizard says "Starting setup" → "Standard (built in)", form says "Built from" → "kirocrew — the standard setup (default)"; the reader read them as "the same thing with two names". One label, one default-option label.
  • Give the step-2 name chips a visible group label ("Suggested names"), since Radar/Scribe/Fixer already appeared on step 1 meaning example goals.

[UX-REVIEWED] 8bfbeda

Description read

[DESCRIPTION-READ] c138055888daaafd3a0c65e6c8e999eb8c6d65df67c4b4a0daaaec555236d806

That sha256 names everything this verdict read: the PR description, plus the 25 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.

@buluoray

buluoray commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor Author

First-open Assistant welcome, desktop and mobile. These captures use the real production SPA with synthetic API fixtures; they are layout evidence, not live-agent verification. The welcome UI matches published head 42111fa.

First-open Assistant desktop

First-open Assistant mobile

The local two-ghost redesign previews have been withdrawn. The author requested preserving the original onboarding composition. No redesign commit was pushed.

@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 Sep 30, 2026
Base automatically changed from fix/crewmate-onboarding-goals to main September 30, 2026 07:32
@CrysisDeu
CrysisDeu requested a review from a team September 30, 2026 07:32
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 30, 2026
@buluoray
buluoray force-pushed the feat/crewmate-assistant-integration branch from 0ff7ab8 to 37f99ac Compare September 30, 2026 08:11
@buluoray

Copy link
Copy Markdown
Contributor Author

span=00f168ba45d8

  • Screen 08 auto-open reversal needs a superseding record

Disposition: needs-a-decision

The Assistant-chat landing replaces the automatic Meet CrewMates presentation that the 2026-09-28 screen-08 amendment requires.
This is a product-owner call, not a code defect: it clears only when the owner records a superseding screen-08 amendment or a docs/decisions/ entry. Put to the maintainer directly.

@buluoray

Copy link
Copy Markdown
Contributor Author

span=61b329078faa

  • Item 1: default-only landing opens Assistant chat

Disposition: needs-a-decision

The landing change is intentional and was approved in the design discussion, but that discussion is not an on-record decision.
Needs a maintainer: an accepted RFC on the base branch, or /ai-review override first-principles <head>: <decision>. The author will not self-authorize it.

@buluoray

Copy link
Copy Markdown
Contributor Author

span=9e80944c85d8

  • Item 2: reverses the accepted screen-08 amendment

Disposition: needs-a-decision

Removing automatic Meet CrewMates presentation contradicts rfc-crewmates-launch.md screen 08 (2026-09-28).
Same root decision as the Blockers item; only a superseding record or a maintainer override clears it.

@buluoray

Copy link
Copy Markdown
Contributor Author

span=5a348f0f44b5

  • Item 3: default agent identity, prompt and name change

Disposition: needs-a-decision

The default member adopts the managed Assistant template and label for users who have not customized it.
Product-shape; covered by the same maintainer decision. Custom templates and explicit opt-out are preserved in code.

@buluoray

Copy link
Copy Markdown
Contributor Author

span=1966778e66f9

  • Item 4: existing uncustomized default chats rebind at the next turn

Disposition: needs-a-decision

Eligible default DMs adopt the Assistant template at a safe turn boundary without an explicit choice.
Product-shape; covered by the same maintainer decision. Adoption keeps history and memory, defers while busy, and respects opt-out.

@buluoray

Copy link
Copy Markdown
Contributor Author

span=229dea81cf85

  • Blockers: product-shape change without accepted RFC

Disposition: needs-a-decision

Items 1-4 share one root cause: the Assistant/in-page default shape has no accepted RFC or recorded decision.
Needs a maintainer decision (RFC merged non-draft, or a first-principles override). No code change can clear it; the author will not self-authorize the override.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 30, 2026
@buluoray
buluoray force-pushed the feat/crewmate-assistant-integration branch from 37f99ac to abb5250 Compare September 30, 2026 08:46
@buluoray

Copy link
Copy Markdown
Contributor Author

span=2f6082500a24

  • Feature-map update leaves the Crew Members row stale

Disposition: fixed

Fixed in abb5250: the Crew Members row now documents the Assistant landing (a roster holding only default opens Assistant, not an empty-state hero), the explicit ?view=roster narrow roster, and embedded creation (guided flow and the Advanced form, no modal).
docs-lint passes on the updated map.

@buluoray

Copy link
Copy Markdown
Contributor Author

span=975deb4da91b

  • Sticky footer covers the report-toggle copy mid-scroll

Disposition: rebutted

The shot captures a mid-scroll frame: the step body scrolls and the footer is the shell's pinned footer (PINNED_FOOTER_CLASS), the same one the original onboarding chapters use; the full "Off:" text is readable by scrolling the step.
Adding a scroll-edge fade would change the shared original onboarding shell, which this PR keeps unchanged by request.

@buluoray

Copy link
Copy Markdown
Contributor Author

span=de5ca72c07d2

  • Two Back controls on one mobile screen

Disposition: rebutted

The header control is labelled with its destination ("Back to chat") and leaves setup keeping the draft; the footer "Back" is the original onboarding step control, unchanged from the shipped flow.
Renaming the original step control would alter the existing onboarding for every entry point, outside this PR's scope.

@buluoray

Copy link
Copy Markdown
Contributor Author

span=408c1f389f9a

  • "Advanced" names a mode rather than an outcome

Disposition: rebutted

Advisory suggestion. "Advanced" sits directly under "New crewmate" in the same + menu, so the pair reads as the guided and the full create path; the row opens the full create form in place.
Kept as is for this PR; a rename would ship new copy in 12 locales without a reported problem beyond the suggestion.

@buluoray

Copy link
Copy Markdown
Contributor Author

span=9c48c46c4d79

  • Existing-conversation migration and accepted multi-step guide unconfirmed end to end

Disposition: rebutted

Live attempt on head abb5250: an isolated pod was started to record an existing default DM (created on the ordinary template) crossing the adoption boundary; the pod's own sandbox prerequisite refused to run agents on this host (sandbox: BLOCKED -- cannot pin .../diag), a host environment condition, not this diff.
The paths are covered below the live layer: test_default_assistant_adoption.py pins next-turn template-only adoption, busy/prewarm deferral, rollback and opt-out; verify-assistant-guide.mjs drives an accepted multi-step guide end to end in the real built SPA at 1440/390/320px (recording attached in the PR body). A live ACP recording is pending a host that can run pods; the PR description states this limit.

@buluoray

buluoray commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles f86ca3c: maintainer decision — every install gets a built-in personal Assistant member, the Crewmates page lands on the Assistant chat, Meet CrewMates opens only on an explicit create action, and the four-field New crewmate dialog moves behind Advanced; this supersedes rfc-crewmates-launch §02 and the §08 2026-09-28 amendment

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

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

maintainer decision — every install gets a built-in personal Assistant member, the Crewmates page lands on the Assistant chat, Meet CrewMates opens only on an explicit create action, and the four-field New crewmate dialog moves behind Advanced; this supersedes rfc-crewmates-launch §02 and the §08 2026-09-28 amendment

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

@buluoray

buluoray commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

Opus 5 findings on 45e2419524, fixed in 568994e8b8:

  • Blocking, guide bounds as bare literals: fixed. guide_catalog now owns both caps (MAX_ACTIONS, new GUIDE_ID_MAX_LEN). validation.py (the actions item cap, both guide_id max_lens and the id pattern), mcp_guide.py (maxItems, both maxLengths, and the "1-N actions" description) and guide_runs._GUIDE_ID_MAX all read them. test/test_guide_bounds_shared.py checks every bound against the constants and that none is restated as a literal; putting "maxItems": 8 back turns it red.
  • target_missing could never resume: fixed. The tracker stays on while the guide is target_missing, keeps ticking after it reports the miss, and report() lets a target_missing guide send observed (and nothing else). A new GuideLayer test drives a step to target_missing, then reveals the later control and expects ['target_missing', 'observed']; reverting either the tracking gate or the report() gate turns it red.
  • ?create=1 link seeded the flow past its input limits: fixed. draftFromParams drops control characters and cuts name/goal to the flow's own NAME_MAX/JOB_MAX (now exported from MeetCrewmatesFlow), and both createDraftFromHref and the ?create=1 effect use it. createDraftLimits.test.ts covers both entry points; reverting createDraftFromHref turns it red.

Not changed: Frontend Tests (1)/(2) on 45e2419524 (hoverVariantPolicy, SessionActionsMenu.duplicate) fail identically on a clean origin/main checkout; #16210 fixes them.

@buluoray

buluoray commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

Fixed in 0d7130761d:

  • GPT 5.6 (fenced), forks of a hand-authored Assistant template got managed plumbing: fixed. fork_refresh._origin_is_owned now treats a lineage ending at kirocrew-assistant as owned only when that file carries the installer's provenance (_is_installed_assistant_spec, the same check the installer and the hook sanitizer use). The origin is read once per refresh pass. A fork of a hand-authored kirocrew-assistant.json is now a custom-template fork: governance still runs, plumbing does not. test_an_assistant_fork_is_plumbed_only_when_the_installer_wrote_its_origin covers both cases; removing the provenance check turns the hand-authored case red.
  • Backend Lint: fixed. mcp_guide.py and validation.py are black-formatted.

Frontend Tests (hoverVariantPolicy) is still the inherited main failure that #16210 fixes.

@buluoray

buluoray commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

Fixed in b23b62995f:

  • GPT 5.6 (fenced), a hand-written Assistant spec could pass as installer-owned: fixed. Content is no longer the proof. The installer writes assistant_template_installed.json in the config dir just before it creates kirocrew-assistant.json, and _is_installed_assistant_spec now requires that marker as well as the name and header. A file that exists without the marker is always its author's: the installer refuses it and leaves the marker unwritten, and the hook sanitizer and fork refresh (which share the predicate) leave it alone. The marker goes down before the file, so a crash between the two only causes a fresh create on the next run.
    • test_a_foreign_file_with_the_installer_heading_is_still_left_alone is the reviewer's case: a hand-written spec opening with # Kiro Crew Assistant stays byte-identical. Dropping the marker check turns it red.
    • test_a_fresh_install_writes_its_marker covers the create path.
  • Backend Tests (Windows) (1), test_an_owner_binds_no_name_another_module_owns: fixed. fork_refresh reads ASSISTANT_AGENT_FILENAME through the agent facade instead of importing its own copy.

Frontend Tests (hoverVariantPolicy) is still the inherited main failure that #16210 fixes.

@buluoray

buluoray commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles b23b629: maintainer decision — every install gets a built-in personal Assistant member, the Crewmates page lands on the Assistant chat, Meet CrewMates opens only on an explicit create action, and the four-field New crewmate dialog moves behind Advanced; this supersedes rfc-crewmates-launch §02 and the §08 2026-09-28 amendment

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

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

maintainer decision — every install gets a built-in personal Assistant member, the Crewmates page lands on the Assistant chat, Meet CrewMates opens only on an explicit create action, and the four-field New crewmate dialog moves behind Advanced; this supersedes rfc-crewmates-launch §02 and the §08 2026-09-28 amendment

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

@buluoray

buluoray commented Oct 3, 2026

Copy link
Copy Markdown
Contributor Author

GPT 5.6 F1 (agent_files.py:67, foreign Assistant template misclassified as managed) -- fixed in 5497406602.

Confirmed in source: crew_template_refs dropped kirocrew-assistant from the export warning by filename alone (_MANAGED_TEMPLATES), never asking whether the on-disk spec was the installer's.

Fix: portability._managed_templates(agents_dir) now keeps kirocrew-assistant managed only when kirocrew-assistant.json is absent (the destination's installer writes it) or agent._is_installed_assistant_spec accepts it (installer marker + spec shape). A hand-written or unreadable spec is named in the export warning like any other unbundled template. missing_crew_templates resolves the agents dir once and passes it through.

Test: test_portability.py::TestCrewTemplateWarnings::test_a_hand_written_assistant_template_is_named_in_the_export covers absent / foreign / owned; reverting the filter to _MANAGED_TEMPLATES turns it red. 290 tests across portability, the assistant installer and the agent facade/contract suites pass; the black and comment-history gates pass.

@buluoray

buluoray commented Oct 3, 2026

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles 5497406: maintainer decision — every install gets a built-in personal Assistant member, the Crewmates page lands on the Assistant chat, Meet CrewMates opens only on an explicit create action, and the four-field New crewmate dialog moves behind Advanced; this supersedes rfc-crewmates-launch §02 and the §08 2026-09-28 amendment

@github-actions

github-actions Bot commented Oct 3, 2026

Copy link
Copy Markdown
Contributor

Human judgment recorded

@buluoray marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for 549740660297f228a65b7247aa871399df54e032.

maintainer decision — every install gets a built-in personal Assistant member, the Crewmates page lands on the Assistant chat, Meet CrewMates opens only on an explicit create action, and the four-field New crewmate dialog moves behind Advanced; this supersedes rfc-crewmates-launch §02 and the §08 2026-09-28 amendment

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

@buluoray

buluoray commented Oct 3, 2026

Copy link
Copy Markdown
Contributor Author

GPT 5.6 F1 (GuideContext.tsx:248, a reloaded commit step loses the creation result) -- fixed in 5a5d16efad.

Confirmed in source: requestHeadersFor returned headers only while the guide was active, but the gateway's begin_commit (guide_runs.py) also accepts target_missing, and a committed step can only leave target_missing through the save itself (the tracker reports observed only for reach steps). After a reload re-entered at the goal step, the 10 s wait expired before the user reached Create, and the save went out with no guide headers.

Fix: requestHeadersFor now attaches the headers while the owned guide is active or target_missing, matching the gateway. The ownership, action-id and committed-step checks are unchanged.

Test: GuideLayer.test.tsx "still attaches guide headers to the save once a committed step went target_missing" -- starts at the commit step with Create absent, lets it go target_missing, and asserts the headers (and that another action's save gets none). Restoring the active-only check turns it red.

This push also rebases onto main (the PR was conflicting): docs/feature-map/README.md keeps main's new roster-listing sentence in this PR's Crew Members row, and MembersPage.tsx's effect dependencies take both sides' additions (listedMembers, defaultAgentSettled, orderedMembers, searchParams). Local: tsc -b, eslint, i18n:check, 637 vitest tests, 1054 backend tests, and the black and comment-history gates pass.

@buluoray

buluoray commented Oct 3, 2026

Copy link
Copy Markdown
Contributor Author

GPT 5.6 F1 (agent_files.py:67, foreign Assistant templates enter managed refresh) -- fixed in e146dd5e01.

Confirmed in source: agent_capabilities.py decided "Crew owns this parent" by filename alone in three places -- the builtin source label in _source, the _REBUILT_FIELDS vouch in _unvouched, and the hooks/includeMcpJson refresh in _maintain_owned -- so a hand-written kirocrew-assistant.json had its fork's hooks replaced and its MCP setting forced off.

Fix: one predicate, _is_owned_template(path, spec), now backs all three (through _parent_is_owned(snap) for the two snapshot sites). For every owned filename except the Assistant's it is unchanged; for kirocrew-assistant.json it also requires agent._is_installed_assistant_spec, the installer-marker check the installer, hook sweep, fork refresh and export warning already use. The remaining filename uses in the repo either refuse (template read-only, publish-name reservation) or rebuild only through installers that already skip a foreign Assistant file.

Test: test_agent_capabilities.py::test_hand_written_assistant_parent_is_not_refreshed_as_owned -- a foreign Assistant parent is labelled custom, and its fork keeps the author's hooks and includeMcpJson. Making the predicate trust the filename again turns it red. 1082 tests across capabilities, the assistant installer, agent, facade/contract and portability suites pass; black and comment-history gates pass.

@buluoray

buluoray commented Oct 5, 2026

Copy link
Copy Markdown
Contributor Author

The Goal, Why it matters and Not a goal sections were rewritten at the PR owner's explicit request, to match the PR's current scope: the built-in assistant is now Captain, with find_ui lookups, on-page guides and confirm-to-apply change cards, on top of the in-page crewmate setup the original goal described. The branch was also rebased onto main at e0a7a66 and squashed to two commits; Captain's protections in the agents handlers now live in dashboard/agent_admin/* after #16786.

Copy link
Copy Markdown
Contributor

PR triage (automated, evidence-based) — head fb49997504, merge base e0a7a66497

1. Name collision with #16376 (open PR) — needs a merge discussion. Both PRs reserve the same agent/template id kirocrew-captain for two different agents:

  • this PR: agent_files.py:52-53 ASSISTANT_MEMBER_NAME = ASSISTANT_TEMPLATE_NAME = "kirocrew-captain", installed by agent_materialization/assistant_agent.py (a read/propose-only assistant every install gets).
  • feat(session-control): add a crew captain that can steer conductors it did not create #16376: agent_files.py CAPTAIN_AGENT_NAME = "kirocrew-captain", installed by conductor_agents.py as a goal conductor, and dashboard/session_control.py lets a person-opened slot running the kirocrew-captain template (or a crew member bound to it) reach every session in its workspace, past the creator fence.

If both land, whichever installer runs second either refuses the other's file (this PR's marker check) or overwrites it. Worse, this PR's Captain is a person-opened crew member on the kirocrew-captain template, so #16376's predicate would give the built-in assistant cross-session control it was never designed to have. One of the two needs a different id before either merges.

2. Rebase needed. git merge-tree against current origin/main (173 commits ahead of the merge base) conflicts in 9 files: crew_log/emit.py, dashboard/server.py, docs/agent-spec-fields.md, test/test_agent_refactor_spec_bytes.py, CrewmateMessage.tsx, MembersPage.tsx, MembersPage.test.tsx, SkillsTab.tsx, store/chatSlice.ts.

3. Security blocker already raised, so no separate review. The forged change_cards.json path (dashboard/change_cards.py:190-194: _load_text reloads every record with a valid id, plan included, without rebuilding it from kind+params; website/src/api/cards.ts:148 sendCardStep then fetch(step.path) with no same-origin or /api/ check) is P0-class. An agent that can write the data-home root can choose which route the owner's Apply sends. The open Opus/GPT reviews already raise it, so this comment adds no second request-changes. It still has to be fixed before merge.

No merged PR on main implements this feature, and no other open PR duplicates it.

@buluoray

buluoray commented Oct 6, 2026

Copy link
Copy Markdown
Contributor Author

Scope update, requested by @buluoray (the PR owner): the Goal, Why it matters and Not a goal sections were rewritten because the scope was widened on request, not by an agent on its own.

What was added beyond the earlier revision:

  • Guides now use the live page: a generated location index (curated plus auto-stamped buttons), live observation of the user's tab, and reveal / selection / gate steps, so a guide can open a collapsed sidebar or menu first, ask the user to pick an item, or point at a setting that must be on.
  • Captain can write a short intro and a per-step note shown in the guide panel, attributed to Captain, length-capped and plain text only.
  • First-run Skip all lands in Captain's conversation.
  • Change cards are MACed and their plans rebuilt on load; every write step is persisted before its route runs.

Head is now 5da66ff on origin/main 3343351. Screenshots and a short video are in the description.

Captain is a built-in crewmate that answers how-to and where-is
questions, points at the page with a guide, and prepares Kiro Crew
changes the user confirms with one press instead of hand-editing
settings.

- Captain agent template, private memory identity and read-only access
  to the user's Global preferences; first-open greeting turn.
- kirocrew-guide MCP: find_ui (packaged dashboard location index),
  search_docs, guide actions, settings diagnosis, and propose_change /
  get_change_status for change cards (settings, schedules, crewmates,
  tools, MCP servers, connections, secrets, app trust, denied rules).
- Change-card store and routes: the gateway owns the plan, risk and
  status; apply and undo replay it through existing routes. One-shot
  reminders resolve their run time server-side.
- Guide runs: one tab claims a guide, progress and finish reasons go to
  the crew log.
- Docs: MCP architecture, crew-log session types, crew mode, feature map.
The dashboard renders Captain's proposals as change cards in the
conversation, runs on-page guides, and keeps crewmate creation inside
the Crewmates page.

- Change cards: one card from proposal to its result line; reminder
  cards say "Set reminder", count down to the run time and retire the
  button the moment that time passes instead of failing on press.
- Guide layer: arrow and panel on the target control, cross-tab claim,
  recovery after navigation, leave guards.
- Crewmates page: Captain conversation, guided creation flow with
  receipts and Advanced form, phone roster view.
- uiLocations descriptors and the generator for the find_ui index;
  strings in all 12 locales.
@github-actions

github-actions Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/security_posture.py

  • No approval on 1567f43 yet.

A human reviewer with write access must approve the CURRENT head and
paste this template into the approval, every field filled
(N/A needs a reason):

## Sensitive change review
- What rule changed:
- Before -> after (what was allowed/blocked, now):
- Worst case if wrong (breaks commands / leaks secret / locks user out):
- Evidence checked (which sandbox result proves it):
- No regression:
  - Tools still work (which tools/commands were run, result):
  - Backward compatible (old config / old data / old callers still work, how checked):
  - Existing tests (which suites passed on this head):
- How to undo:

raise GuideCatalogError(
"invalid_text", f"{field_name}: no links; the guide points at the dashboard itself"
)
if any(ch in text for ch in _GUIDE_TEXT_MARKUP) or _GUIDE_TEXT_MD_LINK_RE.search(text):
@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author

Closing in favour of #18301.

After the team review, the guides and change cards became a platform capability that every crewmate and dashboard session gets, instead of belonging to one built-in assistant. #18301 carries that platform half (tracked in #18300), including the review fixes from this PR's rounds. The first-crewmate welcome will follow as a separate PR stacked on #18301.

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

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants