Skip to content

feat(mate): one worker protocol for both workers - #37619

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
feat/mate-one-worker-protocol
Nov 16, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
feat/mate-one-worker-protocol

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Bot's worker follows the same work protocol as a Conductor mode worker, from one copy of the text, and a test fails when the two drift.

Both workers are bound to one work-ledger item and report on it with work_brief / work_report. Today they read two different prompts. kirocrew-worker gets the full protocol (_WORKER_SYSTEM_PROMPT, about 5.5k characters). A Bot's worker, kirocrew-mate-worker, gets two sentences of it in worker.principles. It is never told the statuses and reason values, which reports wake its conductor, to report progress before it parks, that done is a claim, the summary bar, that decision is the one instruction field, the false-premise and budget: rules, or the dependent-calls rule. It puts its plan in its reply, so the plan never reaches the ledger. No test notices: the only worker parity test holds the coding rules.

Why it matters

A Bot's worker that does not know the statuses reports the wrong one, or none, and its Bot cannot read its state from the ledger. The accepted decision says the Bot and Ultra Mode must work the same way on the ledger; the worker half of that has no guard, so every protocol fix lands on one worker only.

Not a goal

  • Changing what kirocrew-worker is told. Its prompt bytes are unchanged.
  • The conductor side (team-lead gaps, the Bot's ask rule, a Bot without the ledger). Those are separate PRs.
  • Changing any tool, grant, mount or runtime behaviour. This is prompt text and a test.

What changed (motivation → approach → change)

The conductor side already solved this problem with one rule table both conductors render (_LEDGER_CONDUCTOR_RULES, held by test/test_mate_conductor_parity.py). The worker side copies that shape, with no new mechanism.

Piece Before After
Work protocol text inside _WORKER_SYSTEM_PROMPT only _LEDGER_WORKER_RULES in agent_parts/spec_prompts.py, one copy
kirocrew-worker prompt one string joined from _WORKER_PROMPT_SECTIONS; same bytes
Bot worker worker.principles two protocol sentences one placeholder per shared rule, filled in mate_worker.py
Drift guard coding rules only test/test_mate_worker_parity.py

A rule that is not true as written for a Bot's worker stays a kirocrew-worker-only section. A Bot's worker's every turn end also wakes its Bot with a [Worker report] (decision 2026-11-06: "the [Worker report] wake stays"). So it is never told that the report is the ONLY wake or that a silent turn wakes nobody. It is told instead that its Bot also reads its reply, and that only what it reports reaches the ledger. Three other sections stay worker-only for the same reason, each with a one-line reason in the test's allowlist: not_bound (a Bot also hands work over with no item), summary_language (names the goal board) and all_tools (a Bot's worker runs its Bot's kit). The Bot's worker gets one line of its own for not_bound (its reply is its report, so the five plan lines open the reply) and for the summary language.

The module constant MATE_WORKER_PROMPT becomes the function mate_worker_prompt(), like worker_agent.worker_prompt(), and every reader calls it (service_agents.py, context_assembly/agent_spec.py, scripts/crewmate_prompt_preview.py, the tests). Its text still ends with the coding rules, then the ask core and worker tail. It is a function because the rules live behind the kiro_crew.agent facade, which mate_worker must not import at load (test_agent_parts.py holds that only the facade imports agent_parts); src/kiro_crew/agent.py binds the two new names. docs/system-specs/modules/crew-mode.md gains "The two workers stay in step" and a row for the new test.

Covered by docs/decisions/2026-11-06-every-task-a-bot-dispatches-goes-into-its-work-ledger.md ("The Bot and Ultra Mode must work the same way on this") and docs/request-for-change/rfc-conductor-work-ledger.md (status partial; workers report structured data through work_brief / work_report). No new RFC: no default, tool, grant or contract changes, only the Bot worker's prompt text.

Backwards compatibility

Compatible: kirocrew-worker's prompt is byte-identical (the _WORKER_SYSTEM_PROMPT digest pinned in test/test_agent_refactor_contracts.py is unchanged), and every reader of the Bot worker prompt calls mate_worker_prompt() in place of the old constant; nothing outside this repository reads it. The Bot worker spec is rewritten from source on every start, so its new text needs no migration.

The module constant mate_worker.MATE_WORKER_PROMPT is renamed to the function mate_worker.mate_worker_prompt(); every reader on origin/main is switched in this diff:

Reader: src/kiro_crew/agent_materialization/service_agents.py:_install_mate_worker_agent -- chat|crew page -- calls mate_worker_prompt(); test_mate_worker.py
Reader: src/kiro_crew/context_assembly/agent_spec.py:_crewmate_worker_prompt -- chat (claude, codex) -- calls mate_worker_prompt(); test_mate_worker_harnesses.py
Reader: scripts/crewmate_prompt_preview.py:main -- release (maintainer preview) -- calls mate_worker_prompt(); test_crewmate_prompts.py::test_the_ledger_preview_fixture_renders_the_patrol_cleanly

Tests

  • test/test_mate_worker_parity.py (new): the worker prompt is exactly its sections; every section is a shared rule or allowlisted with a reason; every shared rule renders in the Bot's worker prompt; worker.principles names only shared rules; it copies no worker sentence; the Bot's worker is told its reply reaches its Bot and never the two Ultra-only wake sentences; both workers carry the same coding rules (moved here from test_worker_agent.py). Positive controls: a planted worker-only section, a stale allowlist entry and a reworded copy are each caught.
  • test/test_crewmate_prompts.py: the brief-and-report check reads the rendered Bot worker prompt.
  • test/test_agent_refactor_spec_bytes.py: kirocrew-mate-worker.json digests re-pinned for its new prompt; every other spec, kirocrew-worker.json included, keeps its digest.
  • test/fixtures/crewmate_prompts/*.golden.txt refreshed with scripts/crewmate_prompt_preview.py --write; only the worker part changed.

Local, on base c2f1b329a3: 1825 passed across the touched and related test files (worker and conductor parity, crewmate prompts, worker agent, mate worker and harnesses, refactor contracts, spec bytes, composition, ask core); flake-pattern ratchet passed; isort, flake8, mypy, the black gate, the comment-history gate and scripts/docs-lint.sh clean. Semgrep is not installed on this host; CI's SAST lane runs it.

Manual verification

N/A — prompt text only; unit coverage renders the Bot worker prompt and pins kirocrew-worker's bytes.

Related Issues

Closes #37613

Built on #37609 (merged): both workers already end with ASK_CORE plus WORKER_ASK_TAIL from context_assembly/output_contract.py. This PR keeps that tail as it is and does not move it into _LEDGER_WORKER_RULES; the Bot worker's blocked-command line in src/kiro_crew/crewmate_prompts.json keeps #37609's "and no allowed path is left" wording.

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

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 15, 2026 14:03
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Paused by the owner: this change will be redone on top of #37609 after that one merges. The branch stays.

@iamwhatever iamwhatever reopened this Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The PR reuses the conductor side's one-table-plus-parity-test shape, keeps kirocrew-worker's bytes pinned, and switches every reader of the renamed constant in this diff.

Notes

  • mate_worker_prompt() caches its result with lru_cache and reads agent._LEDGER_WORKER_RULES lazily. A placeholder that names no rule then raises KeyError only on the first render, at worker install, not at import. The parity test covers this. Keep that test in the required set so a broken crewmate_prompts.json edit cannot reach a Bot's worker start.

[DESIGN-REVIEWED] f5d94eb

Description read

[DESCRIPTION-READ] 711092de6750bfd996f497067dfdb27aa2116d4d4c50e65127ca163cb70159cd

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 Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f5d94eb

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

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of f5d94eb931e984582b3355bfdaf51bc30f0069d2 — 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. Every item traces to the 2026-11-06 ledger decision or the facade-import rule, and the worker half reuses the shape member.py:861 already uses for the conductor, so it adds no second mechanism.

What this change ships

Inventory (8 items) — 7 justified

Intent: a Bot's worker follows the same ledger work protocol as Conductor mode's worker, from one copy of the text, and drift fails a test. ADDITION (prompt text plus a guard).

  1. A Bot's worker is now told the statuses, reason, which reports wake, progress before parking, done-as-claim, the summary bar, decision, false-premise, budget: and dependent calls — justified
  2. A Bot's worker bound to an item puts its plan in its first progress report, not its reply; with no item, the plan opens the reply — justified
  3. A Bot's worker is told its Bot reads its reply, but only reports reach the ledger — justified
  4. The kirocrew-worker prompt is assembled from named sections into the same bytes — justified
  5. MATE_WORKER_PROMPT constant becomes the lazy, cached mate_worker_prompt(), and all 3 readers are switched — justified
  6. New test_mate_worker_parity.py with an allowlist and positive controls; the coding-rules test moved into it — justified
  7. worker.principles JSON value goes from a string to a line array — undeclared
  8. Spec, RFC seam table, golden fixtures and spec digests updated to the new name and text — justified

[FIRST-PRINCIPLES-REVIEWED] f5d94eb

Description read

[DESCRIPTION-READ] feba0ffe93268dec365f4f9e543e7743ed2a25382cbc032376f94da4b7f6e705

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 Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

Notes:

  • test/fixtures/crewmate_prompts/{ledger,all-met}.golden.txt were regenerated with the "agent file could not be read" conductor wording, because the preview script stubs binding_has_ledger_tools and not binding_ledger_off_reason. No test byte-compares these files; they only help a maintainer read the prompts.

[OPUS-REVIEWED] f5d94eb

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

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

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 695 lines, more than the 400 it may approve on its own.

Approve. The PR moves the worker protocol into one table, _LEDGER_WORKER_RULES. kirocrew-worker's prompt is built from it and gives the same text as before (its pinned digest is unchanged). The Bot's worker worker.principles fills its placeholders from the same table through a lazy, cached mate_worker_prompt(). All three readers of the removed MATE_WORKER_PROMPT constant, and the tests, are switched over; nothing still references it. crewmate_prompts already accepts a list of lines and fill checks placeholders strictly. The new parity test has positive controls and fails on drift. The Bot's worker is never told it is woken only by its reports, which matches the kept [Worker report] wake decision. CI is green. The only flaw is in the golden reading-aid fixtures, which no test compares.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit f5d94eb931 · 695 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@iamwhatever
iamwhatever force-pushed the feat/mate-one-worker-protocol branch from 3fa3d35 to ca8b0b3 Compare November 15, 2026 21:08
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Nov 15, 2026
@iamwhatever
iamwhatever force-pushed the feat/mate-one-worker-protocol branch from ca8b0b3 to a51dbd5 Compare November 15, 2026 22:05
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@iamwhatever
iamwhatever force-pushed the feat/mate-one-worker-protocol branch from a51dbd5 to 6094225 Compare November 15, 2026 23:35
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 15, 2026
@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 Nov 16, 2026
@iamwhatever
iamwhatever force-pushed the feat/mate-one-worker-protocol branch from 6094225 to f5d94eb Compare November 16, 2026 01:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 16, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 16, 2026 02:53

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approving. On this head the review confirmed four things. Joining _WORKER_PROMPT_SECTIONS rebuilds the kirocrew-worker prompt byte for byte, and its value pin and spec digests are unchanged. Only the kirocrew-mate-worker digests move. No reader of MATE_WORKER_PROMPT is left in src, scripts or test. The branch merges cleanly with current main.
Done well: the parity test checks identity against one rule table, and it carries positive controls (a planted section, a stale allowlist entry, a reworded copy) that prove the guard fires.
Optional:

  • Line 5 of test/fixtures/crewmate_prompts/ledger.golden.txt and all-met.golden.txt now has the tracking-off conductor sentence ("could not be read"). That does not match has_ledger_tools: true. The preview script stubs binding_has_ledger_tools but not binding_ledger_off_reason. No test compares the goldens, so only the reading aid is wrong. You could revert that hunk, or fix the stub in a separate change.
  • The earlier "Paused by the owner" comment is still open. Its condition looks met, since this head is built on #37609. A one-line comment would close it on the record.

@KiroCrewCaptain
KiroCrewCaptain merged commit f3dc24c into main Nov 16, 2026
99 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the feat/mate-one-worker-protocol branch November 16, 2026 02:54
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 16, 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(mate): give a Bot's worker the same work protocol as kirocrew-worker

2 participants