fix(core): subordinate the coordinate skill's teammate count to the configured cap - #9403
Draft
yiliang114 wants to merge 1 commit into
Draft
fix(core): subordinate the coordinate skill's teammate count to the configured cap#9403yiliang114 wants to merge 1 commit into
yiliang114 wants to merge 1 commit into
Conversation
…onfigured cap The skill stated an absolute "one to three" while the real ceiling is `agents.team.maxTeammates` (default MAX_TEAMMATES = 10), enforced by a throw in spawnTeammate. team_create's own prompt already derives its number from the setting; the skill did not, so lowering the cap to one or two left the skill instructing a spawn that fails outright. Express the guidance relative to the cap rather than as a second absolute, and give the reason for preferring few teammates — past roughly three the leader spends more of its turn reconciling reports than working. Refs #9399
yiliang114
requested review from
LaZzyMan,
doudouOUC,
tanzhenxin and
wenshao
as code owners
August 18, 2026 11:08
Collaborator
|
✅ Qwen Triage finished — CI landed green on ✅ Qwen Triage 已完成 —— |
Collaborator
|
Thanks for the PR! Template: the substantive sections are all present and well filled in — what it does, why it's needed, and a reviewer test plan with before/after evidence. The boilerplate Problem: real, and I verified it against the code rather than taking the description's word. The binding ceiling is Direction: aligned. A self-consistency fix inside the agent-team feature, which is under active development (claude-code's CHANGELOG carries a steady stream of teammate-related entries). No direction concerns. Size: not applicable — one Markdown skill file, 3+/3-. It lives under Approach: minimal and exactly on goal. All three absolute-count statements are rewritten (frontmatter description, spawn step, bounded-coordination bullet) and nothing else is touched. The new wording also supplies the rationale for preferring fewer teammates that the old text asserted without support. Nothing I'd cut. Risk: no elevated risk signals (no high-risk path matches). Moving on to code review. 🔍 中文说明感谢贡献！ 模板：核心章节齐全且填写完整——做了什么、为什么需要、以及带 before/after 证据的 reviewer test plan。样板章节 问题：真实存在，已对照代码核实而非仅凭描述。真正的上限是 方向：对齐。这是 agent-team 功能内部的自洽性修复，该功能正在活跃开发中（claude-code 的 CHANGELOG 有大量 teammate 相关条目）。无方向性问题。 规模：不适用——单个 Markdown skill 文件，3+/3-。文件位于 方案：最小改动，完全围绕目标。三处写死的人数表述全部改写（frontmatter 描述、spawn 步骤、bounded-coordination 条目），未触碰其他内容。新文案还补上了"为什么人少更好"的理由（旧文案只断言不论证）。没有可砍的部分。 风险：无升级风险信号（未命中高风险路径）。 进入代码审查 🔍 — Qwen Code · qwen3.8-max Reviewed at |
Collaborator
Code reviewMy independent take before reading the diff: rewrite the absolute "three" statements so the configured cap is the binding constraint (keeping roughly three as a soft recommendation), and fix the frontmatter description that also hardcodes "up to three". The PR does exactly that — nothing more. Every claim in the description checks out against the code:
No code paths change, no blockers, no convention violations. The claim under review is what the skill says, and that is fully verified above; a docs-style wording change gives an A/B or sandboxed lane nothing behavioural to settle. TestingCI signal on the reviewed commit, fetched via API (never running PR code here). CI classified this commit as docs-only, so the heavy matrix is skipped by design and the ubuntu job runs the classifier/gate path: Final CI results for
One row per check name (latest run); skipped checks omitted; failures sort first. / 每个检查名一行（取最新一次运行），省略 skipped，失败项排在最前。 The 中文说明代码审查读 diff 前的独立方案：把写死的"three"改写为以配置上限为准（保留大约三个的软建议），并修正同样写死"up to three"的 frontmatter 描述。PR 的做法与此一致，且没有任何多余改动。 描述中的每项声明都已对照代码核实：
无代码路径变更、无阻塞问题、无规范违反。本次审查的对象是 skill 的表述内容，已在上文完整核实；docs 类措辞变更没有 A/B 或沙箱通道可以验证的运行时行为。 测试CI 信号来自 API 拉取（此处从不运行 PR 代码）。该提交被 CI 分类为 docs-only，因此重型矩阵按设计跳过，ubuntu 任务只跑分类/门槛步骤。 — Qwen Code · qwen3.8-max Reviewed at |
Collaborator
|
Confidence: 5/5 — minimal wording fix from a maintainer, every factual claim verified against the code, and nothing in the diff can break a code path. Stepping back: this is the kind of small fix that's easy to eyeball and hard to fault. The skill and the runtime disagreed about who sets the teammate ceiling; the PR makes the runtime's configured number binding and keeps "roughly three" as a recommendation — now with the reason attached, which the old text lacked. Every claim checks out (cap default 10, spawn-time throw, Approval deferred until CI lands green on 中文说明置信度：5/5 —— 维护者提交的最小化措辞修复，每项事实声明均已对照代码核实，diff 不影响任何代码路径。 整体来看：这是一个无可挑剔的小修复。skill 与运行时在"谁决定 teammate 上限"上互相矛盾；PR 让运行时的配置值成为硬约束，并把"大约三个"保留为软建议——现在补上了旧文案缺失的理由。每项声明都与代码一致（默认上限 10、spawn 时 throw、 批准将延迟到 CI 在 — Qwen Code · qwen3.8-max Reviewed at |
Contributor
Code Coverage Summary
CLI Package - Full Text ReportCore Package - Full Text ReportFor detailed HTML reports, please see the 'coverage-reports-22.x-ubuntu-latest' artifact from the main CI run. |
qwen-code-ci-bot
approved these changes
Aug 18, 2026
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
LGTM, looks ready to ship — CI landed green after the review. ✅
yiliang114
marked this pull request as draft
August 18, 2026 11:38
qwen-code-ci-bot
left a comment
qwen-code-ci-bot
left a comment
Collaborator
There was a problem hiding this comment.
Partially reviewed — gaps disclosed. Suggestions are inline.
Not reviewed: reverse audit — stopped before round 3 by the review time budget.
— qwen3.8-max via Qwen Code /review (v0.21.13)
|
|
||
| 1. Create one team and one self-contained task per current investigation workstream. Do not queue an implementation task while read-only teammates are idle because tasks are auto-assigned. | ||
| 2. Spawn one to three named investigation teammates with `read_only: true`. Do not pass `model`; use the session-default model unless the selected agent definition explicitly overrides it. | ||
| 2. Spawn named investigation teammates with `read_only: true` — one per workstream, and prefer three at most. Never exceed the team's configured cap, which `team_create` reports; spawning past it fails outright. Do not pass `model`; use the session-default model unless the selected agent definition explicitly overrides it. |
Collaborator
There was a problem hiding this comment.
[Suggestion] The "configured cap" this wording defers to is not currently configurable through user settings: loadCliConfig's agents projection (packages/cli/src/config/config.ts) copies every agents key except team, and the settings schema labels agents.team "Reserved for future use" without declaring maxTeammates — so team-create.ts always reads undefined and the cap is always MAX_TEAMMATES (10). The PR's premise (and its motivating scenario of lowering the cap) rests on a dead switch. — Failure scenario: set agents.team.maxTeammates: 2 in settings.json following this wording → no error and no effect; the cap stays 10, team_create still advertises "max 10 teammates per team", and the "configured cap" promise is false.
Witness (probe):
loadCliConfig({ agents: { team: { maxTeammates: 2 }, maxParallelAgents: 3 } })
→ getAgentsSettings(): { team: undefined, control: 3 } // sibling key passes, `team` dropped
adding `team: settings.agents.team` to the projection → same probe passes
Either wire the setting through for real — add team: settings.agents.team to the agents projection, declare maxTeammates (default 10) under agents.team in the settings schema, and drop the "Reserved for future use" label (the probe verifies the projection half) — or word the skill against the hard maximum (10) rather than a "configured cap".
— qwen3.8-max via Qwen Code /review (v0.21.13)
| ## Keep coordination bounded | ||
|
|
||
| - Use one teammate for a narrow task and no more than three for this workflow. | ||
| - Use one teammate for a narrow task. Past roughly three, the leader spends more of its turn reconciling reports than doing the work, so add a fourth only when the workstreams are genuinely independent — and never past the configured cap. |
Collaborator
There was a problem hiding this comment.
[Suggestion] The cap this workflow now treats as its hard boundary counts LIFETIME spawns, not concurrent teammates: teamFile.members is push-only (the only splice is spawnTeammate's spawn-failure rollback) and shutdown never removes a member — so this skill's own flow (N investigators → shut down → one writer) consumes N+1 slots. — Failure scenario: with cap 3 — the number this skill itself recommends, reachable via core Config params.agents by SDK hosts — spawn three investigators, shut all three down, and the writer spawn throws Maximum number of teammates (3) reached. with zero active teammates; team_delete, the only reset, destroys the shared task/message state. At the default cap 10, repeated spawn/shutdown cycles exhaust the budget mid-flow in long sessions.
Witness (probe on this PR's code):
maxTeammates: 3 → spawn 3 investigators → all shutdown_approved → all CANCELLED
→ teamFile.members.length still 3 → writer spawnTeammate throws
"Maximum number of teammates (3) reached."
with a slot-freeing fix applied: members length 0, writer spawn passes (probe flips)
Deeper fix (probe-verified): free the slot on terminal status in TeamManager (note members is also read by findMemberByName/broadcast/assignTeammateColor). Minimal fix: state the lifetime semantics here so the writer's slot is budgeted.
Suggested change
| - Use one teammate for a narrow task. Past roughly three, the leader spends more of its turn reconciling reports than doing the work, so add a fourth only when the workstreams are genuinely independent — and never past the configured cap. | |
| - Use one teammate for a narrow task. Past roughly three, the leader spends more of its turn reconciling reports than doing the work, so add a fourth only when the workstreams are genuinely independent — and never past the configured cap. The cap counts every teammate spawned over the team's lifetime, including shut-down ones, so budget the worktree writer into it: with a cap of N, spawn at most N−1 investigation teammates when implementation is expected. |
— qwen3.8-max via Qwen Code /review (v0.21.13)
|
|
||
| 1. Create one team and one self-contained task per current investigation workstream. Do not queue an implementation task while read-only teammates are idle because tasks are auto-assigned. | ||
| 2. Spawn one to three named investigation teammates with `read_only: true`. Do not pass `model`; use the session-default model unless the selected agent definition explicitly overrides it. | ||
| 2. Spawn named investigation teammates with `read_only: true` — one per workstream, and prefer three at most. Never exceed the team's configured cap, which `team_create` reports; spawning past it fails outright. Do not pass `model`; use the session-default model unless the selected agent definition explicitly overrides it. |
Collaborator
There was a problem hiding this comment.
[Suggestion] The companion user-facing page docs/users/features/multi-agent-coordination.md:17 still says "The leader creates a team, assigns up to three independent workstreams…" — an unqualified absolute this change removes from the skill, with no mention of the cap the PR's rationale is built on. Before this PR the two texts agreed. — Failure scenario: a reader of the /coordinate docs is told the workflow stops at three workstreams, while the new skill text explicitly permits a fourth teammate for genuinely independent workstreams (default cap is 10) — the docs now understate shipped behavior, and any future cap-guidance change must be made in two places that are already out of sync.
Reword the docs sentence in the same cap-relative shape, e.g.:
The leader creates a team, assigns one teammate per workstream (typically three at most, never past the team's teammate cap), and uses the existing team tools for messages and task state.
— qwen3.8-max via Qwen Code /review (v0.21.13)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Makes the bundled
coordinateskill express its teammate count relative to the configured cap instead of stating a second, independent number.The real ceiling is
agents.team.maxTeammates, defaulting toMAX_TEAMMATES = 10, enforced by a throw inTeamManager.spawnTeammate. Theteam_createtool's own workflow prompt already derives its number from that setting. The skill did not — it said "one to three" and "no more than three for this workflow" as absolutes.The skill now says: one teammate per workstream, prefer three at most, never exceed the configured cap that
team_createreports. It also states why few is preferred, which the old wording asserted without support: past roughly three, the leader spends more of its turn reconciling reports than doing the work.Why it's needed
A hard ceiling and a workflow recommendation are different kinds of statement, and a workflow recommending fewer than the ceiling allows is legitimate. The defect is narrower than "two sources of truth": the skill's number was not subordinate to the cap. Setting
agents.team.maxTeammatesto 1 or 2 left the skill instructing the model to spawn up to three, which fails at spawn time withMaximum number of teammates (N) reached.— a failure the model then has to recover from mid-workflow.Stating the rationale matters for the same reason: a model told "no more than three" with no reason will trade it away under pressure, where one told what actually degrades will not.
Reviewer Test Plan
How to verify
packages/core/src/skills/bundled/coordinate/SKILL.mdand confirm no absolute teammate count is stated as a rule, and that the configured cap is named as the binding constraint.agents.team.maxTeammatesto2, run/coordinateon a goal with three obvious workstreams, and confirm the leader spawns at most two rather than attempting a third and handling a spawn failure.No code paths change;
MAX_TEAMMATES, the setting, and thespawnTeammateguard are all untouched.Evidence (Before & After)
Before:
After:
Tested on