Repository navigation
Cap Advanced Delivery at 4 threads; tighten subagent discipline - #7
Merged
Merged
Conversation
…discipline Context was draining faster than the work justified. Three causes: reusing a subagent that had already finished its mission, briefs that turn into long-lived threads, and constant follow-ups -- every wake re-reads a child's entire history at the parent's cost. The thread cap was read as a target to fill rather than a ceiling. Advanced Delivery drops from 5 to 4 total threads (1 lead + 3 subagents). Balanced and Lean are untouched. The shared skill and every arrangement's AGENTS snippets now say that acceptance closes a child's mission, that a follow-up may only correct or clarify that same delivery, that a finished child is never reused for new work, and that a child is never woken for status or an acknowledgement.
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Three unresolved review comments require clarifying reuse guidance and adding cap regression coverage.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 1
What changed in this PR
This PR caps Advanced Delivery at four threads and standardizes bounded subagent delegation across arrangements.
Changes:
- Reduces Advanced Delivery from 5 to 4 threads.
- Updates arrangement versions to 0.4.0.
- Revises delegation guidance, documentation, validation records, and changelog entries.
| File | Summary | Review note |
|---|---|---|
skills/codex-orchestration/SKILL.md |
Updates delegation lifecycle and capacity guidance. | — |
README.md |
Updates version and capacity information. | — |
docs/validation.md |
Adds 0.4.0 validation details. | — |
docs/README.pt-BR.md |
Updates translated capacity figures. | — |
docs/orchestration.md |
Updates orchestration guidance. | Nit (3 votes): later guidance still permits resuming completed children. |
docs/installation.md |
Adds upgrade guidance. | — |
docs/configuration.md |
Documents configuration changes. | — |
docs/CHANGELOG.md |
Adds the 0.4.0 changelog entry. | — |
arrangements/lean-delivery/README.md |
Documents shared delegation guidance. | — |
arrangements/lean-delivery/arrangement.toml |
Bumps version to 0.4.0. | — |
arrangements/lean-delivery/AGENTS.with-skill.snippet.md |
Updates delegation instructions. | — |
arrangements/lean-delivery/AGENTS.snippet.md |
Updates delegation instructions. | — |
arrangements/balanced-delivery/README.md |
Documents shared delegation guidance. | — |
arrangements/balanced-delivery/arrangement.toml |
Bumps version to 0.4.0. | — |
arrangements/balanced-delivery/AGENTS.with-skill.snippet.md |
Updates delegation instructions. | — |
arrangements/balanced-delivery/AGENTS.snippet.md |
Updates delegation instructions. | — |
arrangements/advanced-delivery/README.md |
Updates Advanced capacity and lifecycle guidance. | — |
arrangements/advanced-delivery/config.toml |
Lowers the thread cap to 4. | Moderate (1 vote): no regression assertion covers the shipped cap values. |
arrangements/advanced-delivery/arrangement.toml |
Bumps version to 0.4.0. | — |
arrangements/advanced-delivery/AGENTS.with-skill.snippet.md |
Updates delegation instructions. | — |
arrangements/advanced-delivery/AGENTS.snippet.md |
Updates delegation rules. | Moderate (1 vote): role cards still permit resuming a role for new work. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+55
to
+60
| Advanced and Balanced each permit three active children, and Lean two | ||
| (total-thread caps of four, four, and three including the lead). The cap is a | ||
| ceiling, not a target: dispatch a child only when its result pays for its own | ||
| brief and review. Start with one useful child. Advanced leaves room for disjoint | ||
| implementation and investigation; Balanced supports two implementation fronts | ||
| and a bounded check; Lean favors a short implementation-then-review sequence. |
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
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.
Arrangement or component and purpose
Advanced Delivery's
config.toml, the sharedcodex-orchestrationskill, and everyarrangement's AGENTS snippets.
The problem, as measured across sessions: context draining faster than the work
justified. Three causes, and all three looked like efficiency at the time:
project". Every wake makes the child re-read its entire history before answering, and
the parent pays for that, not the child.
each one pays for the whole history again, and the thread grows in a way nobody watches.
because an idle slot looked like waste.
The fix. Advanced Delivery drops from 5 to 4 total threads (1 lead + 3 subagents),
matching Balanced's existing 4. Balanced and Lean are untouched. The shared skill and all
six AGENTS snippets now state that a dispatch carries one bounded mission with a written
acceptance; that acceptance closes the mission; that
followup_taskmay only corrector clarify that same delivery; that a finished child is never reused for new work; that a
child is never woken to ask for status or an "ok"; that the cap is a ceiling, never a
target; that escalation follows demonstrated difficulty, never file count; and that a
brief conveys scope, not authority — a child's artifact is evidence for the parent to
judge, not a decision.
What stays: real parallelism. One lead plus three subagents is meaningful concurrency.
What goes: the incentive to keep a thread alive or refill an idle slot with invented
work.
Note, stated rather than smoothed over: Advanced and Balanced now share the same
numeric thread cap (4 total / 3 children). They remain distinct in model and role
allocation. This is a direct consequence of the change, not an oversight.
This converges with an externally reported caution against running large numbers of
subagents, attributed in community discussion to an OpenAI engineer. No link, date or
exact quote is included, because none was independently verified here.
Changes
arrangements/advanced-delivery/config.toml:max_concurrent_threads_per_session5 to 4.arrangements/{advanced,balanced,lean}-delivery/arrangement.toml: version 0.3.0 to 0.4.0(shared catalog cadence, as in prior releases).
skills/codex-orchestration/SKILL.mdand all sixAGENTS*.snippet.md: the delegationdiscipline above, written into the existing sections rather than appended as a new block.
README.md, per-arrangementREADME.md, anddocs/{orchestration,validation,configuration,installation,CHANGELOG,README.pt-BR}.md:cap figures and a new 0.4.0 changelog/validation entry. No historical entry was altered —
docs/validation.mdkeeps the 0.2.0 record of the old 5/4/3 figures as history..runtime-validation/intentionally left unchanged. It is untracked and gitignored(
git ls-files .runtime-validationreturns 0 files;.gitignore:4), and holds frozenprobe captures — sqlite state, installation IDs, and one
config.tomlfrozen at ahistorical cap of 6 from a 0.1.0-era run. Those are measured evidence of past runs, not
live copies meant to track the source.
Functional evidence
Python 3.14.7 on Windows.
python -X utf8 scripts/validate_catalog.py— 3 arrangements, 35 roles, passed.python -X utf8 scripts/validate_components.py— structural preflight passed.python -X utf8 -m unittest discover -s tests— 39 tests, OK.No test asserts the real arrangements' cap values (
grep -rn advanced-delivery tests/returns nothing; the literal 4 and 5 in
tests/test_catalog.pyare synthetic fixturevalues), so no test change was required. If a future test asserts the real caps, they are
4 / 4 / 3.
No Codex CLI session was run. This is a configuration and prose change; it carries no
new concurrency or saturation measurement, and every new documentation paragraph says so.
Checks