Skip to content

feat(team-lead): team-management rules decided by mechanisms that already exist - #18856

Closed
chenmingwei23 wants to merge 3 commits into
feat/18049-lead-crewmatefrom
feat/18813-team-mgmt-rules
Closed

chenmingwei23 wants to merge 3 commits into
feat/18049-lead-crewmatefrom
feat/18813-team-mgmt-rules

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A team lead that decides how to run its team from the mechanisms already in the tree, instead of from feel.

The shipped kirocrew-team-lead crewmate knows how to run a work ITEM and
almost nothing about running a TEAM. Its skill and charter cover the
do-it-yourself test, the dispatch order, the patrol cycle and the board, so
every rule it carries is about one item at a time. The questions a lead hits
between items have no answer anywhere in the tree:

  • How many sessions may I stand up right now, and when do I stop?
  • A third conducting level is not allowed. What actually stops me, and why is
    that the rule rather than a number I could ask to have raised?
  • Two lines of work have converged on the same files. Do I merge them, and how?
  • I can no longer hold the whole fleet in one patrol read. What then?
  • Two children could write the same file. Who owns it?

Every one of them has a mechanism that could decide it, and three of those
mechanisms will REFUSE the lead rather than negotiate: the ledger's depth cap,
the server's per-creator session ceiling, and the approval gate on
session_adopt. With no rule naming them, the lead guesses.

Why it matters

The failures are not slow, they are silent, and each one reads as ordinary
progress on the board.

A lead that dispatches a wave without reading capacity gets refusals partway
through it, so half a wave runs and the other half looks like a slow start. The
same lead whose capacity probe FAILS has no rule at all today: the reading
comes back unknown and the decision falls back to feel at exactly the moment
there is no information to make it with. Two lines left unmerged keep handing
work back and forth, and the handoffs cost rounds that never show up as a red.
A fleet grown past one patrol read loses items quietly, because a truncated
read looks exactly like a short one. Two children writing one file clobber each
other, and an author grading its own work reports the result it already
believes.

All of them land on the owner as a goal taking longer than it should, with
nothing on the board to point at.

Not a goal

  • No runtime change. Nothing here alters what any tool does; the diff is skill
    text, charter text, tests and an RFC.
  • Not raising the ledger depth cap. The guard mismatch is tracked in
    #18127 and is not
    touched here.
  • No new rule for a lead that is NOT a crewmate. The dashboard half of the
    tracker rule applies only where the board verbs answer.
  • No second copy of a rule either surface already states. Where guidance
    exists, this change adds only the mechanism that enforces it.
  • No tracker tooling. The tracker is an ordinary worker with a tracking item,
    not a new session kind or a new verb.

What changed (motivation → approach → change)

Goal: give the lead a decidable answer for the five calls above.

Approach, over the two alternatives considered. Writing the rules as judgement
("merge when the lines feel entangled") was rejected because it reproduces the
problem in prose. Adding runtime enforcement was rejected as far too large for
guidance that is read before the call is made, and because three of the five
mechanisms already refuse at the server. What is left is to NAME the deciding
mechanism in the document the lead reads first, and to pin that naming with
tests.

What was built:

the call the mechanism that decides it
how big a wave may be resource_status before every wave and every reseed wave; queue on tight, critical or unknown; give capacity back with action=close plus session_close; the ceiling is the server's MAX_SLOTS_PER_CREATOR and MAX_LIVE_SLOTS, never a count the lead holds
what stops a third conducting level MAX_DEPTH in work_ledger.py is what refuses; the guard admits a depth that does not yet agree with it, so the already-stated one-level tree is the safe one and the cap is never asked to be raised
whether two lines merge three readings (same files, one line down to a single item, handoffs bouncing); merge by action=close plus a reseed carrying the artifacts; session_adopt is named as what this is NOT, since it moves sessions, sits outside the auto-approved set and is the owner's call
whether to add a tracker a concrete trigger -- the compact ledger read comes back cut, items span more than one ledger, or the lead skips items -- answered by ONE worker that writes one summary item and reports, never decides
who may write a shared file one owner per shared file, one integrator per output, and review dispatched to a different child than the author

The shipped surface is the subtraction of everything already stated. The
charter already carries its own ## Capacity section and its own one-level
nesting rule, so this adds no second copy of either. Capacity gains exactly one
sentence, inside the section that was already there: a posture of unknown
means the reading failed, so it takes the same lighter path as tight. The
one-level instruction is not restated at all; the skill names only the
mechanism that enforces it and the mismatch being tracked. What the charter
gains as its own section is the three calls it had no text for -- merging two
lines, adding a tracker, and ownership.

The split between the two files follows from that. The skill carries the
reading (when to probe, all four posture words, the ceilings, the trigger, the
refusal to expect); the charter carries one short pointer per rule it did not
already have, because a procedure stated twice is a procedure that drifts until
a reader follows neither copy.

The decision is recorded in the RFC one-pager added here,
docs/request-for-change/rfc-team-lead-management.md, so the reasoning and the
text that implements it land together.

Backwards compatibility

Compatible: the diff adds prose to one skill document and one prompt string,
adds tests, and adds an RFC. No field, key, type, validator or tool signature
changes, so nothing main accepts today stops being accepted.

Removes nothing: the single deleted line is a reflow of the charter's existing
capacity sentence, which is rewritten in place and keeps every instruction it
carried. The repository's own take-away detector agrees -- running
.github/scripts/take_away_check.py over this diff reports no take-away shape,
so no reader list is required.

Tests

A new class, TestTeamLeadCarriesTeamManagementRules in
test/test_team_lead_agent.py: one test per rule plus a positive control, 6
passed.

Each test and the behaviour it locks in:

  • test_the_probe_reads_both_texts -- the positive control, and it runs first.
    Every other assertion is an in against two strings, which an empty string
    would satisfy on the absence half, so this one locks in that both texts
    arrived with content and that a phrase genuinely absent from both is reported
    absent.
  • test_capacity_gates_every_wave_including_a_reseed -- locks the reading into
    the skill (when to probe, all FOUR posture words so a list of three cannot
    come back, the two server ceilings) and locks the charter to the single
    sentence it gains, so a second copy of the rest cannot be added there.
  • test_the_depth_cap_is_named_without_restating_the_one_level_rule -- locks
    in MAX_DEPTH, work_ledger.py, the tracked mismatch and the no-raise
    clause, AND asserts an absence: the one-level instruction must appear in the
    skill and NOT inside the new section. That is what keeps this change from
    growing a second copy of a rule already stated.
  • test_merging_two_lines_closes_and_reseeds -- locks the merge to the ledger
    operation and keeps session_adopt named as what it is not.
  • test_a_tracker_is_dispatched_when_one_read_stops_fitting -- locks the
    concrete trigger and the reports-never-decides charter.
  • test_one_owner_per_shared_file_and_one_integrator_per_output -- locks both
    halves plus the separate-reviewer clause.

How the pins are built: the skill text is partitioned down to the
team-management section before the assertions run, so a pinned phrase has to
sit in the rule that owns it rather than anywhere in the file; and every pin is
a mechanism NAME (resource_status, MAX_DEPTH, work_ledger.py,
action=close, session_adopt, reseed wave), so wording can be copy-edited
without rewriting a test.

The pins were shown to bite after the surface was reduced: rewording the
unknown clause in the charter reddens the capacity test, and removing
MAX_DEPTH from the skill section reddens the depth test. Each mutation fails
exactly its own test, and restoring the files returns 6 passed. No assertion
was loosened to make the reduced surface pass.

Manual verification

N/A -- unit coverage sufficient: the change is document text, and the tests
read the shipped skill file and the installer-emitted charter rather than a
copy, so the assertion target is the artifact a lead actually receives.

Also run locally, all green: semgrep --config semgrep/ over both changed
Python files, the comment-history gate against this branch's base (it caught
one real marker in an added docstring, which was rewritten in present tense),
ast.parse on agent.py after each prompt edit, and
.github/scripts/take_away_check.py over the full diff.

Every mechanism named in the text was grepped in this tree before it was
written: MAX_DEPTH = 2 in work_ledger.py, MAX_LIVE_SLOTS and
MAX_SLOTS_PER_CREATOR in dashboard/state.py, the four POSTURE_* constants
and the failure path that returns unknown in resource_status.py, the ledger
close action, and the comment in agent.py recording that session_adopt is
withheld from this agent's auto-approved set.

Related Issues

Fixes #18813

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

Contributions are accepted under the project's Apache-2.0 license; see the
Licensing section of CONTRIBUTING.md.

@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners October 10, 2026 12:55
@chenmingwei23
chenmingwei23 requested review from cruisercohen and removed request for a team October 10, 2026 12:55
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 10, 2026
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 099ca65a1afc92d64bab4b9e350ac30dd63df197 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 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Before merge, fix the RFC index row: it says team-lead/SKILL.md "does not exist" and that "nothing" has landed, but this PR edits that skill.

[DESIGN-REVIEWED] 099ca65

Description read

[DESCRIPTION-READ] 9ca324491b2b063b33a11870f5d6df8743c4986afbae93723e6681b24cd2dd3f

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 099ca65a1afc92d64bab4b9e350ac30dd63df197 — 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: CONCERNS

Queuing on unknown reverses the fail-open rule that resource_status.py documents, and the description never says so.

Not justified as shipped

  • Item 1 — inherited: "unknown is the posture of a reading that FAILED, and it queues like tight" contradicts _classify's "An unreadable probe (available_gb < 0) is unknown → fail-open". under_pressure deliberately leaves unknown out, and the admission gate admits it (resource_status.py:948). A host whose probe never reads would queue every wave, permanently.
    Subtraction: delete the unknown sentence from the charter and drop unknown from the skill's "any of the last three".
    Clears when: the sentence is deleted, or a linked issue shows fail-open on unknown caused a reported overload.
  • Item 6 — duplicate of builtin_skills/team-lead/SKILL.md §6: the description promises "one short pointer per rule", but each charter bullet restates the full triggers and procedure for three rules (merge, tracker, ownership).
    Subtraction: shrink each charter bullet to the rule's name plus "see the team-lead skill".
    Clears when: the charter bullets no longer restate the triggers and procedure.

What this change ships

Inventory (7 items) — 5 justified

Intent: give the team lead a rule for each team-level call, naming the mechanism that already decides it. ADDITION.

  1. The lead queues waves when the capacity reading failed (unknown) — inherited
  2. The lead probes capacity before reseed waves and closes finished children — justified
  3. The skill names MAX_DEPTH as what refuses a third level — justified
  4. The lead merges two lines by close-and-reseed, not session_adopt — justified
  5. The lead dispatches one tracker worker when one read stops fitting — justified
  6. The charter gains a "Running the team itself" section — duplicate of SKILL.md §6
  7. A new RFC with its own in-progress status, plus a README index row — justified

[FIRST-PRINCIPLES-REVIEWED] 099ca65

Description read

[DESCRIPTION-READ] d33292b1b68bd985bee1c451b7d49018eabad3c5034873fb3a8dfe8f1c26d5a5

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 Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings that block the merge.

FINDING — src/kiro_crew/builtin_skills/team-lead/SKILL.md:188 — the skill tells the lead to send a tracker that "reads every ledger and the pull requests, writes one summary item -- and the dashboard_write fields", but that job is sent to an ordinary worker, and a worker cannot do it. Its only grants are work_brief/work_report. /api/work-ledger reads only the caller's own ledger, so the worker gets no_ledger. work-ledger is also OS-masked in sandbox.py, so it cannot read the files directly. Creating an item is a conductor-only action. dashboard_write refuses outside a crewmate's own thread. So the lead waits for a summary that cannot hold any board data, and the charter's matching line in agent.py says the same → Fix: in both texts, describe the tracker's output as its own work_report, built from data the lead gives it in the brief. Drop "reads every ledger", "one summary item" and the dashboard_write clause.

[OPUS-REVIEWED] 099ca65

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

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

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 099ca65

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

@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 Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18813-team-mgmt-rules branch from ef9fa56 to 61bfef0 Compare October 10, 2026 13:06
@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 Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18813-team-mgmt-rules branch from 61bfef0 to d9e33f4 Compare October 10, 2026 13:49
@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: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Oct 10, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

This PR gives the team-lead crewmate rules for running a team: an unknown capacity reading takes the same lighter path as tight, plus rules for merging two lines (close one and reseed the survivor, not session_adopt), a single tracker worker, and one owner per shared file. I read the diff (the src/kiro_crew/agent.py charter text, the new team-lead SKILL.md, the RFC and test/test_team_lead_agent.py). The guidance only points at mechanisms that already exist and adds no new code paths. GPT, Opus and Design reviews pass on head d9e33f4, but the First Principles CONCERNS on that head has no disposition yet. HOLD because the base is feat/18049-lead-crewmate, not main, and the PR adds an RFC (a product decision). Let it land through its feature branch, or retarget it to main after #18049's branch merges, and answer the First Principles items. — crew-pr-reviewer

Every agent shipped for running work is either a leader that cannot
write a file or a worker that cannot create a session. A conductor spec
withholds fs_write and code deliberately, which is what makes "never
does a work item's work itself" true against its tool list; the worker
keeps the writers and mounts nothing that can dispatch. So a one-line
fix on a critical path costs a whole dispatch, or a six-item goal runs
in series in one session with no board and no evaluator.

kirocrew-team-lead is the union. Its installer never overwrites the
template's tool list, so the writers and shell arrive from the template
and the dispatch servers are appended; every auto-approve is an existing
grant tuple reused verbatim, with the bare whole-server entry subtracted
so the per-verb list is a real narrowing rather than a wildcard with
names beside it. work_report stays withheld: it writes into a parent's
record, and this crewmate is the root of its own goal.

The product ships the template and creates no crewmate. The dashboard
verbs resolve their crew from the session and answer only in a crewmate
thread, and the server behind them is opt_in with no spec permitted to
emit it, so the record is what completes the agent -- and binding one is
the operator's own `kirocrew agent create --kiro-agent
kirocrew-team-lead`, which the RFC and the skill document.

The installer attributes the file BEFORE it validates grant shape, and
only an ABSENT path is written into. A file of this name that declares
another name, does not mount both servers this agent leads through, does
not parse, or cannot be read deterministically is left untouched and the
install declined at ERROR: no backup is written and the agent stays
unselectable under that name until the operator removes or renames it.
That is the dashboard-author contract rather than the derived worker's
overwrite, and the difference is the remedy -- the worker spec is
re-checked before every dispatch and has no operator path out, while
this one is optional and selected by name. A read that may succeed later
holds for one rebuild instead, so no file is judged on one bad read.

The team-lead builtin skill is a delta over goal-conductor: the echo,
the intake hook, the do-it-yourself test, the nested-conductor default
and the dashboard, with dispatch, patrol, acceptance, stop conditions,
durable state and capacity pointed at rather than restated.
@chenmingwei23
chenmingwei23 force-pushed the feat/18049-lead-crewmate branch from 463bfbc to 5e05a42 Compare October 10, 2026 20:15
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18813-team-mgmt-rules branch from d9e33f4 to 8cedd7c Compare October 10, 2026 20:43
@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 Oct 10, 2026
1. reset_agent_model swallowed every exception from the ownership
   predicate into False. A transient read of the ownership record was
   therefore treated as "not our write", so the reset rewrote the spec
   without renewing its recorded digest and every later start refused it,
   with no heal path for this stem. Distinguish "answered: not ours"
   (stay False) from "could not read ownership" (the strict readers'
   transient classes): the latter propagates so the reset aborts before
   mutating the file.

2. The team-lead KAS payload is built from the on-disk spec before the
   admission gate's unbounded queue wait. A governance refresh during the
   wait rebuilds the disk spec (stripping any grant the tightened ceiling
   removes), but the already-built payload still carries the old grants
   and is what session/new registers. The disk re-read at admission
   cannot see this. Record the governance generation the payload was
   built under and recheck it at admission and at activation (create and
   resume); a mismatch refuses the start so it is rebuilt against the
   live ceiling. The team-lead stem mirrors no default and so had no
   DerivedSpecSnapshot bracketing its consume window; this is the
   owned-stem companion to that check.

3. On the native kiro-cli path the team lead was consumed inside no
   bracket at all. Both guards answered None there for different
   reasons: require_fresh_derived_spec by its scope guard, because the
   team lead mirrors no default, and the generation recheck because that
   path builds no KAS payload and so recorded nothing. Two "not
   applicable"s are not "verified", and None was conflating "not our
   agent" with "our agent, nothing recorded" -- the second is an
   unanswered question, which may not be admitted. The bracket now
   records the governance answer itself before the read that fixes the
   consumed bytes (the skill projection, or kiro-cli's own disk read at
   set_mode) and rechecks it after the activation returns, terminating
   the session on a mismatch. stale_payload_generation_reason takes the
   agent as a required argument so the two None cases are decided rather
   than collapsed, and the admission site asks only where a payload
   exists, so a native start is not refused for a question not yet due.

4. The dashboard model PATCH recorded model_managed BEFORE confirming
   ownership. That confirmation propagates a transient ownership-read
   failure by contract, so the raise arrived with the sidecar already
   claiming the pin and with nothing written to the file -- a
   half-applied state whose spec reproduces no recorded digest, so every
   later start refuses it and the next rebuild carries a pin the bytes
   never received. Settle ownership first and reuse the one result for
   the digest renewal, so that failure aborts with nothing written and
   the decision and the renewal cannot disagree.

Adds regression tests for all four, including the over-tight controls:
an unchanged generation admits a native start, a governance move leaves
a non-team-lead start alone, and the admission site stays quiet on a
host with no payload.
@chenmingwei23
chenmingwei23 force-pushed the feat/18049-lead-crewmate branch from 5e05a42 to 961546e Compare October 10, 2026 21:29
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 10, 2026
The team-lead crewmate had rules for running a work ITEM and none for running
a TEAM, so the calls a lead makes between items -- how big a wave may be, what
stops a third conducting level, whether two lines merge, when the board
outgrows one patrol read, and who may write a shared file -- were decided from
feel while a mechanism in the tree could have decided each one.

The skill gains a section naming those mechanisms: resource_status and its
four posture words with the server's own session ceilings, MAX_DEPTH as what
refuses a third level, close-and-reseed as the merge, the concrete trigger for
a tracker worker, and single ownership per shared file and per output.

The charter adds only what it does not already carry. Its capacity section
gains one sentence -- a posture of unknown means the reading failed, so it
takes the same lighter path as tight -- and its new section covers the three
calls it had no text for. The one-level nesting instruction is not restated,
because both surfaces already carry it and a procedure stated twice drifts
until a reader follows neither copy.

Tests pin each rule to its mechanism on the surface that carries it, assert
the absence of a duplicate instruction, and run a positive control first so an
empty read cannot pass. An RFC one-pager records the decision.
@chenmingwei23
chenmingwei23 force-pushed the feat/18813-team-mgmt-rules branch from 8cedd7c to 099ca65 Compare October 10, 2026 21:53
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18049-lead-crewmate branch from 961546e to c2ecacf Compare October 10, 2026 22:34
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18049-lead-crewmate branch 2 times, most recently from 966c7da to f09b12e Compare October 11, 2026 00:26
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Closing: the five team-management rules are being folded into #18128, which is being slimmed to a default agent installed like kirocrew-research plus the team-lead skill. Tracked by #18813.

@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 11, 2026
@bolichen97
bolichen97 deleted the feat/18813-team-mgmt-rules branch November 6, 2026 07:23
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.

2 participants