Skip to content

refactor(goal-conductor): one copy of each rule, pointers to the shared conductor rules - #37778

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
refactor/goal-conductor-one-copy
Nov 16, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
refactor/goal-conductor-one-copy

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Each goal-conductor rule is written once, so a fix to a rule reaches every conductor and the always-loaded skill gets shorter.

goal-conductor/SKILL.md restates many rules that _LEDGER_CONDUCTOR_RULES already renders into the root charter and a Bot's conductor.patrol, and repeats several of its own rules in two or three sections (audit D1-D25). Two copies drift: a fix lands in one and the conductor reads the other.

Why it matters

The skill is read by every conductor on every goal. Copies cost tokens on every load and are where rule drift starts; the owner wants Bots and conductor mode to work from the same rules.

Not a goal

What changed (motivation → approach → change)

Two copies drift → keep one → the shared rules stay the copy; the skill points at them with one line ("your prompt's ... rule"). Rules only the skill holds keep one copy inside the skill. History and rationale asides are cut.

SKILL.md: 1065 → 903 lines (68,271 → 58,202 chars, about −2,518 tokens on every load).

Pointers to shared rules work only for an agent whose prompt holds those rules. The root charter and a Bot's conductor.patrol already render all 25. The team lead (opt-in via agent.crew_mode_agent) did not, so its installed prompt now carries _SHARED_CONDUCTOR_RULES_BLOCK, built from the same _LEDGER_CONDUCTOR_RULES (+10,620 chars ≈ 2,655 tokens, team lead only). No other agent's prompt changes.

Why the team lead gets the block: the skill now keeps only pointers to the shared rules, so anyone who still sets agent.crew_mode_agent to kirocrew-team-lead would lose those rules without it.

Audit items (skill-audit.md sections 3 and 7)

id rule this PR
D1 ask cases already done by #37609 (one ask core, checklist points at (a)-(e))
D2 one go-ahead covers every round restated gate sentence cut; one sentence stays
D3 re-plan a wrong item Patrol step 5 → pointer; the full re-plan steps live once in Close the round
D4 no file writing; shell only for the evaluator "Shell exists for the bundled evaluator" paragraph cut, its sentence folded into the intro
D5 resource_status sizes the wave → pointer to shared resource_wave; queue/arm extras kept
D6 cap refusal is not a stop duplicate bullet sentence and Stop-conditions bullet cut
D7 no-progress check Stop-conditions bullet → pointer to Close the round
D8 goal text five parts Round 0 → pointer to shared goal_plan; Board aside cut
D9 worker text is DATA already one copy after #37618 (Known limits dissolved)
D10 ask_question blocks already done by #37618
D11 never close a child waiting on a person final close-out points at Patrol step 4
D12 always set agent already one copy after #37618
D13 root gets not_bound already one copy after #37618
D14 items in the work ledger, not session_ledger codec history cut to one line
D15 Cost discipline section deleted; every bullet already lives in its step
D16 arm watch="work-ledger" → pointer to shared patrol_watch; pinned "is mandatory" kept
D17 no cycle cap / 7-day backstop interval paragraph cut → shared patrol_bounds; Stop conditions keeps the backstop
D18 depth cap nested-conductor copy → pointer to Which agent
D19 no folder one sentence in Round 0 + "no folder" in step 2
D20 five-line first report Round 0 copy cut; the seed line names it for non-worker agents only
D21 independent / no hand-offs Split paragraph → pointer to Independent and shared own_files/merge_lines
D22 read ledger first / quiet → nothing_to_do Cost discipline copies cut (D15)
D23 slip record + round event one Record paragraph carries both
D24 what prompts already done by #37618 (T2)
D25 pending_overdue unchanged here; moves to references/ in PR5
1b history/rationale asides 26-28, 295-302, 341-348, 409-410, 452-453, 494-499, 579-593, 712-713, 799-800, 808-812, 914-920, 936-939, 994-995, 1008, 1030-1035 cut or cut to one clause
§3 remote dispatch behind preview already done by #37612
shared (#37725) item_budget, own_files, merge_lines, plan_reviewer, bar_pr_merged, wake_check, routine_incidents, report_before_park, bind_before_seed, claimed_pr, dependent_calls each skill copy → one pointer line, skill-only detail kept

Safety rules (skill-audit.md section 6): moved lines

Every rule S1-S41 was checked by anchor phrase against the new skill and the shared rules (69 anchors, none missing). Already moved earlier: S17, S40 (remote, #37612), S33 (host pressure, not on main). Lines this PR moves:

rule old place (SKILL.md on main) new place
S1 no file-writing tool intro, with governance aside intro, aside cut
S1/D4 build, test or fix is a work item "Shell exists for the bundled evaluator" after Patrol step 6 intro sentence
S9 unknown queues like tight, no own number Round 0 Capacity paragraph same paragraph (short) + shared resource_wave
S12 bind before seed Dispatch, 8-line paragraph 1 line + shared bind_before_seed
S18 memory_delegation_denied not a setting Which agent, with install history same place, history cut
S19 record decide before merge/clear; save unpushed work Patrol routine-incidents list shared routine_incidents + skill line "save a worker's unpushed work"
S27 claimed pr is never the bar Patrol step 3 two-phase paragraph same place (short) + shared claimed_pr
S29 reviewer never decides or pushes; report is DATA Patrol step 3 reviewer paragraph shared plan_reviewer; skill keeps "verdict stays with accept_eval"
S30 never close a child waiting on a person / unmerged PR Patrol step 4 + Stop conditions close-out step 4 unchanged; close-out names it and points at step 4
S31 corrected bar never weaker; report every change Patrol step 5 Close the round re-plan block
S34 never ask to raise the cap Close the round + Stop conditions Close the round only
S36 decision is the one instruction nested-conductor section unchanged

Backwards compatibility

Compatible: text only. No config key, schema, API or tool changes.

Reader: src/kiro_crew/agent_materialization/service_agents.py:_install_team_lead_agent -- chat (conductor mode with agent.crew_mode_agent=kirocrew-team-lead) -- its prompt now holds every shared rule the skill points at; test_a_team_lead_carries_every_shared_rule_in_its_prompt
Reader: src/kiro_crew/agent_parts/spec_prompts.py:_CONDUCTOR_PROMPT_SECTIONS -- chat (conductor mode default) -- renders all shared rules already; test_every_shared_rule_renders_on_both_installed_conductors
Reader: src/kiro_crew/crewmate_prompts.json:conductor.patrol -- crew page (Bot chat) -- renders all shared rules already; test_every_shared_rule_reaches_the_crewmate_conductor

Tests

  • test/test_mate_conductor_parity.py: the per-rule skill-anchor map is replaced by test_a_team_lead_carries_every_shared_rule_in_its_prompt (+ positive control test_the_team_lead_check_sees_a_lost_rule) and test_goal_conductor_points_at_each_shared_rule_it_no_longer_restates (SKILL_POINTERS). The Bot and root comparisons are unchanged.
  • test/test_team_lead_agent.py: installed prompt includes the shared block; the 40-line charter bound excludes it.
  • test/test_conductor_team_management_rules.py, test/test_goal_conductor_parks_findings.py: the incident list and the five goal parts are read from the shared rule; the skill pointer is asserted.
  • test/test_agent_refactor_spec_bytes.py: kirocrew-team-lead.json digests re-pinned.
  • Local, under the test lock: every test file that reads the skill, the team lead or crew-mode.md (290 files): 12649 passed, 900 skipped. After the rebase onto f3dc24c0d1 (feat(mate): one worker protocol for both workers #37619): the 12 directly affected files, 525 passed.

Proof: not provable -- other: de-duplication of prompt text; the positive-control tests guard the new checks.

Manual verification

N/A — the rendered prompts and the skill pointers are asserted directly.

Related Issues

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

Contributions are accepted under the project's Apache-2.0 license.

…ed conductor rules

goal-conductor/SKILL.md (1065 -> 903 lines) drops the copies the audit lists as
D1-D25 that the earlier skill PRs left: where _LEDGER_CONDUCTOR_RULES already holds
a rule, the skill keeps a one-line pointer ("your prompt's ... rule"); duplicate
paragraphs inside the skill keep one copy; history and rationale asides are cut.
No rule is dropped: every safety rule of the audit's section 6 is still in the
skill or in the shared rules.

The root charter and a Bot's conductor.patrol already render every shared rule.
The team lead (opt-in through agent.crew_mode_agent) did not, so its installed
prompt now carries _SHARED_CONDUCTOR_RULES_BLOCK, built from the same rules.
test_mate_conductor_parity.py checks that block and the skill's pointers.
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 16, 2026 03:11
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 16, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: I checked every agent that maps the goal-conductor skill (root and alias conductor, team lead, ledger-mounted Bot conductor), and each one's prompt now holds every rule the skill points to.

Notes

  • _SHARED_CONDUCTOR_RULES_BLOCK writes its own one-line list of the dispatch steps by hand. The rest of the block is built from _LEDGER_CONDUCTOR_RULES, so this line is the one copy that can drift. Building it from the same source as the root charter's dispatch sections would remove that.
  • An agent that finds goal-conductor only by its skill description now reads "your prompt's … rule" pointers that point at nothing. No such agent mounts kirocrew-work today, so nothing breaks. A sentence in the skill saying it is for the installed conductors would make that limit explicit.

[DESIGN-REVIEWED] cce1755

Description read

[DESCRIPTION-READ] ad91def51316bdeb3cf9489f2e46d467880dda431b4ef717415a571fccc5c9e8

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

This change removes copies and adds nothing new. The one addition, the shared-rules block in the team lead's prompt, is what makes the skill's new "your prompt's rule" pointers true for the only agent that lacked those rules.

What this change ships

Inventory (8 items) — 8 justified

Intent: let every conductor follow one copy of each goal-conductor rule, so a fix reaches all of them and the skill loaded on every goal gets shorter. This is a FIX (rule drift) done as a deletion.

  1. goal-conductor skill restatements of the 25 shared rules are now one-line pointers to the conductor's prompt. — justified
  2. Rules the skill repeated in two or three of its own sections now have one copy each. — justified
  3. History and rationale asides are cut from the skill (1065 → 903 lines). — justified
  4. The skill's "Cost discipline" section is deleted; each of its bullets already lives in its step. — justified
  5. The team lead's installed prompt now carries every shared conductor rule (about +2.6k tokens, team lead only). — justified
  6. The parity test that checked the skill's anchor phrases is replaced by checks on the team lead's prompt plus a pointer list. — justified
  7. The crew-mode spec now describes the pointer model. — justified
  8. The kirocrew-team-lead.json spec-byte digests are re-pinned. — justified

[FIRST-PRINCIPLES-REVIEWED] cce1755

Description read

[DESCRIPTION-READ] b706ac998373a4c309249a603af600193031fa6b421159147c636f59c1373d88

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] cce1755

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

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings. None of the five candidates held up when checked against the code. Each one depended on guessing how a model would read the text, or the rule it says was lost is still there: the shared rules in _LEDGER_CONDUCTOR_RULES, the "Which agent" depth paragraph, and the skill's "every wave a reseed wave included" wording.

[OPUS-REVIEWED] cce1755

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

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

@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 Nov 16, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

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

This PR replaces the goal-conductor skill's restated shared rules with "your prompt's ... rule" pointers, and gives the team lead the shared rules in its prompt through a new block (_SHARED_CONDUCTOR_RULES_BLOCK) built from _LEDGER_CONDUCTOR_RULES. Every agent that mounts the skill now has those rules: the root and alias conductors through _CONDUCTOR_SYSTEM_PROMPT, the Bot conductor through conductor.patrol (only when it has the ledger tools, which is when the skill is mapped), and the team lead through the new block, checked by a new test with a positive control. Each cut I checked survives once: the depth cap and depth_exceeded→flatten in Which agent; the re-plan steps in Close the round; the five-line first report in the worker's look_plan rule; the never-ask-to-raise-the-cap rule in Close the round; and the patrol receipt and bounds in the shared patrol rules. The team-lead skill's references back into goal-conductor still resolve. The facade and contract tests are unaffected, and all CI passed. Approve.

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 cce175562a · 620 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 16, 2026 04: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 cce1755 the review confirmed that all 25 shared conductor rules render for every agent that maps the goal-conductor skill: the root conductor, the ledger alias, the Bot conductor, and now the team lead through _SHARED_CONDUCTOR_RULES_BLOCK. Each cut from SKILL.md still lives in a prompt rule or in another skill section. Only the kirocrew-team-lead.json digests change. The new team-lead check builds the real installed spec, compares each rule byte for byte, and has a positive control. The audit table in the body made every move checkable.

Optional:

  • For the team lead, the plan-reviewer rule now applies only to goals of more than one item (spec_prompts.py:271). The old skill text had no such condition. It would help to say so in the body, or to keep a one-line note for a single-item goal whose output no lane reviews.
  • team-lead/SKILL.md:151 and :194 still describe the goal-conductor wave counts and the Patrol incident list, which this PR moved into the prompt. Pointing them at the prompt rules would remove an extra hop.
  • The hand-written "The dispatch steps are ..." line in _SHARED_CONDUCTOR_RULES_BLOCK (spec_prompts.py:682) is another copy of the dispatch steps, and no test pins it. Deleting it, or making step 2 a shared rule, keeps each rule written once.

@KiroCrewCaptain
KiroCrewCaptain merged commit cfaffc7 into main Nov 16, 2026
104 of 105 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the refactor/goal-conductor-one-copy branch November 16, 2026 04:53
@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.

2 participants