Skip to content

docs: add rfc for crewmate guides, change cards and mate - #18326

Merged
buluoray merged 1 commit into
mainfrom
docs/rfc-crewmate-guides-and-mate
Oct 9, 2026
Merged

buluoray merged 1 commit into
mainfrom
docs/rfc-crewmate-guides-and-mate

Conversation

@buluoray

@buluoray buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record the product decision behind #18301 and #18317 on main, so their First Principles review can read it from the base branch.

#18301 (platform guides and change cards) and #18317 (Mate, a first crewmate) change product shape: a default-mounted guide server, a crewmate Kiro Crew creates for everyone, a new first landing on the Crewmates page, and a model-written first welcome. The accepted crewmate RFCs say otherwise in places, so both PRs are blocked on "product-shape change without accepted RFC".

Why it matters

Without this record on main, both implementation PRs stay blocked, and the next reader of the crewmate RFCs would find decisions that no longer describe the product.

Not a goal

  • Any code change. This PR adds one RFC and one index row.
  • Rewriting the amended RFCs. They stay as written; this document names the sections it amends.

What changed (motivation → approach → change)

A new RFC, docs/request-for-change/rfc-crewmate-guides-and-mate.md, status accepted, records the product owner's decision of 2026-10-08 after the team review:

  • Part 1: one kirocrew-guide MCP server that only reads or offers. Default-mounted for the kirocrew template, its crewmates, worker and dashboard sessions; granted by exact tool name under the governance ceiling. Change cards apply only on the user's press; widening cards also need an acknowledgement tick. Trust-root areas are answered in words only. Only a dashboard turn the user sent may start a guide or a card. The rules live in tool text, not in an agent prompt.
  • Part 2: Kiro Crew creates one ordinary crewmate, Mate, once. A never-chatted Mate opens first on the Crewmates page (preview on), welcomes the user in a model-written turn, and asks to be named; it renames itself with rename_self. default stays the shared fallback crew and is listed only once its thread has a message.
  • It names the sections it amends in rfc-crewmates-launch.md (§4 screens 02 and 08), rfc-crewmate-greeting.md (§6) and rfc-crewmates-chatted-list.md (§3 landing order), and lists the rejected alternatives.

docs/request-for-change/README.md gains the index row and an audit sentence.

Backwards compatibility

Compatible: documentation only; no code, config or on-disk format changes.

Tests

scripts/docs-lint.sh passes.

Manual verification

N/A -- documentation only. Each "Exists today" claim was checked against main at 4f9c5697b9.

Screenshots / video

Why no screenshot: documentation only; no UI change.

Related Issues

Part of #18300
Part of #18315

Pattern harvest

Not generalizable: a docs-only PR.

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 review from a team and KiroCrewCaptain as code owners October 9, 2026 04:12
@buluoray
buluoray requested a review from bolichen97 October 9, 2026 04:12
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 9, 2026
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.
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision b6233205c2851d8b5b348c8219c102f0bc77d4b8 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@buluoray
buluoray force-pushed the docs/rfc-crewmate-guides-and-mate branch from dc0f5a2 to b623320 Compare October 9, 2026 04:14
@github-actions

github-actions Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

The RFC makes Mate's model-written kickoff the first thing a new user sees on the Crewmates page, but says nothing about what happens when that model turn fails.

Watch

  • First impression depends on a working model call. The RFC says "Mate replaces the 'No crewmates yet' first state" and "Mate's first turn is a hidden kickoff. The model writes the welcome." What breaks: a user with no provider login, no model entitlement, or a provider outage opens the Crewmates page. The hidden turn errors, and the empty-state hero is gone. That user lands in a silent or broken Mate thread on their very first visit. The RFC also never says whether a failed kickoff counts as "never exchanged a message", so it can't tell whether Mate keeps re-opening first and retrying. feat: welcome users with Mate, a first crewmate they get to name #18317 will build whatever this RFC records.
    Clears when: the Part 2 Decision states what a failed or unauthenticated kickoff shows, whether the landing rule retries it, and whether it falls back to the empty or Meet CrewMates state.
  • The status line contradicts the front matter. The front matter says status: accepted, but the body says "maintainer acceptance is being requested on the doc PR." The README row also lists it as accepted. feat: let any crewmate guide users to the control on their screen #18301 and feat: welcome users with Mate, a first crewmate they get to name #18317 would then cite an acceptance that, by the RFC's own text, hasn't happened yet.
    Clears when: a maintainer accepts it on this PR before merge, or the status stays draft until they do.

[DESIGN-REVIEWED] b623320

Description read

[DESCRIPTION-READ] 209f0f7b04dcc9e0741eb93644765d0be6566bd9abf14191c41af717b8585c13

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b623320

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

@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision b6233205c2851d8b5b348c8219c102f0bc77d4b8 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 9, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

One advisory finding, no merge block: the RFC's list of managed MCP servers leaves one out.

FINDING — docs/request-for-change/rfc-crewmate-guides-and-mate.md:180 — the "Exists today" bullet says _MANAGED_MCP_SERVERS "holds kirocrew-cron, kirocrew-core, … kirocrew-debug and kirocrew-panel", but the dict at src/kiro_crew/agent.py:1165 also has the opt-in kirocrew-crew-log entry. Anyone using this as the baseline for where kirocrew-guide fits gets an incomplete server set. → Fix: add kirocrew-crew-log to the list, or write "holds, among others, …".

[OPUS-REVIEWED] b623320

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

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

@buluoray
buluoray enabled auto-merge (squash) October 9, 2026 04:49
@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 9, 2026
@buluoray
buluoray merged commit 87c429a into main Oct 9, 2026
102 checks passed
@buluoray
buluoray deleted the docs/rfc-crewmate-guides-and-mate branch October 9, 2026 05:23
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 9, 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.

2 participants