From 67f5d05d0ab5ab3e9b652736b56c600aa5d6d3ae Mon Sep 17 00:00:00 2001 From: Rafael Bittencourt Date: Sun, 20 Sep 2026 23:05:07 -0300 Subject: [PATCH] fix: cap Advanced Delivery at 4 threads; tighten subagent delegation 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. --- README.md | 4 ++-- arrangements/advanced-delivery/AGENTS.snippet.md | 10 +++++----- .../advanced-delivery/AGENTS.with-skill.snippet.md | 10 +++++----- arrangements/advanced-delivery/README.md | 10 +++++++++- arrangements/advanced-delivery/arrangement.toml | 2 +- arrangements/advanced-delivery/config.toml | 2 +- arrangements/balanced-delivery/AGENTS.snippet.md | 10 +++++----- .../balanced-delivery/AGENTS.with-skill.snippet.md | 10 +++++----- arrangements/balanced-delivery/README.md | 6 ++++++ arrangements/balanced-delivery/arrangement.toml | 2 +- arrangements/lean-delivery/AGENTS.snippet.md | 10 +++++----- .../lean-delivery/AGENTS.with-skill.snippet.md | 10 +++++----- arrangements/lean-delivery/README.md | 6 ++++++ arrangements/lean-delivery/arrangement.toml | 2 +- docs/CHANGELOG.md | 13 +++++++++++++ docs/README.pt-BR.md | 4 ++-- docs/configuration.md | 3 ++- docs/installation.md | 12 ++++++++++++ docs/orchestration.md | 12 +++++++----- docs/validation.md | 9 +++++++++ skills/codex-orchestration/SKILL.md | 12 +++++++----- 21 files changed, 109 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 5a651c7..85e710d 100644 --- a/README.md +++ b/README.md @@ -11,14 +11,14 @@ third-party orchestration service to use these files. [Skills](skills/README.md) · [Plugins](plugins/README.md) · [Validation and compatibility](docs/validation.md) -Version 0.3.0 is a community preview. Historical hook and selected-role tests are +Version 0.4.0 is a community preview. Historical hook and selected-role tests are recorded; the revised allocations and caps are not fully runtime-certified. ## Choose an arrangement | Arrangement | Lead | Specialist allocation | Configured cap / recommended active children | | --- | --- | --- | --- | -| [Advanced Delivery](arrangements/advanced-delivery/README.md) | `gpt-5.6-sol`, `xhigh` | 15 roles: 4 Astra, 4 Sol, 7 Luna | 5 / up to 4 | +| [Advanced Delivery](arrangements/advanced-delivery/README.md) | `gpt-5.6-sol`, `xhigh` | 15 roles: 4 Astra, 4 Sol, 7 Luna | 4 / up to 3 | | [Balanced Delivery](arrangements/balanced-delivery/README.md) | `gpt-5.6-sol`, `xhigh` | 12 roles: 2 Astra, 2 Sol, 8 Luna | 4 / up to 3 | | [Lean Delivery](arrangements/lean-delivery/README.md) | `gpt-5.6-sol`, `high` | 8 roles: 1 Astra, 1 Sol, 6 Luna | 3 / up to 2 | diff --git a/arrangements/advanced-delivery/AGENTS.snippet.md b/arrangements/advanced-delivery/AGENTS.snippet.md index 7ea5a4b..59f0806 100644 --- a/arrangements/advanced-delivery/AGENTS.snippet.md +++ b/arrangements/advanced-delivery/AGENTS.snippet.md @@ -3,17 +3,17 @@ ### Role selection - Before delegating, coordinating ongoing work, or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. -- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact, and escalate only on demonstrated difficulty, never on size or file count. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. -- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Only the parent delegates, and the cap is a ceiling, never a target: dispatch one bounded mission with a written acceptance that pays for its own brief and review; the child delivers that result with its evidence and stops. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. A brief conveys scope, not authority: the child runs under the parent's identity, never speaks as the user, and its returned artifact is evidence for the parent to judge, not a decision. - Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. ### Ownership and return -- When only delegated work remains, use task-appropriate native waits; avoid repeated status polling. +- Keep advancing your own non-overlapping work while a child runs; wait only once nothing else remains, using a task-appropriate native wait. Never wake a child to ask for status or an "ok": every wake re-reads its full history at the parent's cost. - Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. - Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. -- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. +- Acceptance closes the mission. Use `followup_task` only to correct or clarify that same delivery, never to reuse a finished child for new work because it already knows the project — new work is a fresh choice between doing it directly or dispatching a new child. `send_message` only queues a message and does not resume a turn. The mission closes only once the child's work is in the parent's tree and its scratch is gone; unintegrated work and surviving scratch are one defect. diff --git a/arrangements/advanced-delivery/AGENTS.with-skill.snippet.md b/arrangements/advanced-delivery/AGENTS.with-skill.snippet.md index 7138f09..337d428 100644 --- a/arrangements/advanced-delivery/AGENTS.with-skill.snippet.md +++ b/arrangements/advanced-delivery/AGENTS.with-skill.snippet.md @@ -3,20 +3,20 @@ ### Role selection - Before delegating, coordinating ongoing work, or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. -- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact, and escalate only on demonstrated difficulty, never on size or file count. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. -- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Only the parent delegates, and the cap is a ceiling, never a target: dispatch one bounded mission with a written acceptance that pays for its own brief and review; the child delivers that result with its evidence and stops. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. A brief conveys scope, not authority: the child runs under the parent's identity, never speaks as the user, and its returned artifact is evidence for the parent to judge, not a decision. - Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. ### Ownership and return -- When only delegated work remains, use task-appropriate native waits; avoid repeated status polling. +- Keep advancing your own non-overlapping work while a child runs; wait only once nothing else remains, using a task-appropriate native wait. Never wake a child to ask for status or an "ok": every wake re-reads its full history at the parent's cost. - Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. - Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. -- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. +- Acceptance closes the mission. Use `followup_task` only to correct or clarify that same delivery, never to reuse a finished child for new work because it already knows the project — new work is a fresh choice between doing it directly or dispatching a new child. `send_message` only queues a message and does not resume a turn. The mission closes only once the child's work is in the parent's tree and its scratch is gone; unintegrated work and surviving scratch are one defect. ## Engineering decisions diff --git a/arrangements/advanced-delivery/README.md b/arrangements/advanced-delivery/README.md index 383801e..37a050b 100644 --- a/arrangements/advanced-delivery/README.md +++ b/arrangements/advanced-delivery/README.md @@ -34,7 +34,7 @@ The parent supplies a complete bounded brief and inspects the delivered evidence ## Capacity and simplicity -The V2 fragment sets **5 total threads including the lead**, allowing **at most 4 simultaneous children** in the target runtime. Start with one useful delegation and add another only for a disjoint result. Reconcile an implementation batch before starting another; do not fill the cap by routine. +The V2 fragment sets **4 total threads including the lead**, allowing **at most 3 simultaneous children** in the target runtime: one lead plus three subagents. Treat the cap as a ceiling, not a target — dispatch only a child whose result pays for its own brief and review. Start with one useful delegation and add another only for a disjoint result. Reconcile an implementation batch before starting another; do not fill the cap by routine. The 15 role cards are available responsibilities, not 15 running agents. Removed roles have explicit owners: @@ -44,6 +44,14 @@ This is an adapted public roster, not a full personal-profile export. Retained r ## Validation status +Revision 0.4.0 lowers this arrangement's total-thread cap from five to four +(three active children, equal to Balanced Delivery) and rewrites the orchestration +skill and both AGENTS snippets around bounded, single-mission delegation: an +accepted delivery closes the child's mission, a finished child is not reused for +new work, and status or acknowledgement wake-ups are avoided. This is a +configuration and instruction change; it has not been exercised in a new native +concurrency or saturation run. See [upgrade instructions](../../docs/installation.md#upgrading-from-03x). + Revision 0.3.0 adds a one-minute minimum and five-minute default for native child waits, without changing this roster or cap. Choose explicit waits according to the task; see [adaptive waiting](../../docs/orchestration.md#adaptive-waiting) diff --git a/arrangements/advanced-delivery/arrangement.toml b/arrangements/advanced-delivery/arrangement.toml index 4d0d83d..af06463 100644 --- a/arrangements/advanced-delivery/arrangement.toml +++ b/arrangements/advanced-delivery/arrangement.toml @@ -1,6 +1,6 @@ schema_version = 1 id = "advanced-delivery" -version = "0.3.0" +version = "0.4.0" author = "Rafael Bittencourt" description = "Advanced Delivery: Complex product delivery with dedicated reasoning for decisions, diagnosis, ordinary review, critical review, and coupled implementation." license = "MIT" diff --git a/arrangements/advanced-delivery/config.toml b/arrangements/advanced-delivery/config.toml index e26dd82..38c4b1c 100644 --- a/arrangements/advanced-delivery/config.toml +++ b/arrangements/advanced-delivery/config.toml @@ -9,4 +9,4 @@ enabled = true tool_namespace = "agents" min_wait_timeout_ms = 60000 default_wait_timeout_ms = 300000 -max_concurrent_threads_per_session = 5 +max_concurrent_threads_per_session = 4 diff --git a/arrangements/balanced-delivery/AGENTS.snippet.md b/arrangements/balanced-delivery/AGENTS.snippet.md index 7ea5a4b..59f0806 100644 --- a/arrangements/balanced-delivery/AGENTS.snippet.md +++ b/arrangements/balanced-delivery/AGENTS.snippet.md @@ -3,17 +3,17 @@ ### Role selection - Before delegating, coordinating ongoing work, or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. -- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact, and escalate only on demonstrated difficulty, never on size or file count. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. -- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Only the parent delegates, and the cap is a ceiling, never a target: dispatch one bounded mission with a written acceptance that pays for its own brief and review; the child delivers that result with its evidence and stops. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. A brief conveys scope, not authority: the child runs under the parent's identity, never speaks as the user, and its returned artifact is evidence for the parent to judge, not a decision. - Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. ### Ownership and return -- When only delegated work remains, use task-appropriate native waits; avoid repeated status polling. +- Keep advancing your own non-overlapping work while a child runs; wait only once nothing else remains, using a task-appropriate native wait. Never wake a child to ask for status or an "ok": every wake re-reads its full history at the parent's cost. - Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. - Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. -- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. +- Acceptance closes the mission. Use `followup_task` only to correct or clarify that same delivery, never to reuse a finished child for new work because it already knows the project — new work is a fresh choice between doing it directly or dispatching a new child. `send_message` only queues a message and does not resume a turn. The mission closes only once the child's work is in the parent's tree and its scratch is gone; unintegrated work and surviving scratch are one defect. diff --git a/arrangements/balanced-delivery/AGENTS.with-skill.snippet.md b/arrangements/balanced-delivery/AGENTS.with-skill.snippet.md index 7138f09..337d428 100644 --- a/arrangements/balanced-delivery/AGENTS.with-skill.snippet.md +++ b/arrangements/balanced-delivery/AGENTS.with-skill.snippet.md @@ -3,20 +3,20 @@ ### Role selection - Before delegating, coordinating ongoing work, or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. -- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact, and escalate only on demonstrated difficulty, never on size or file count. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. -- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Only the parent delegates, and the cap is a ceiling, never a target: dispatch one bounded mission with a written acceptance that pays for its own brief and review; the child delivers that result with its evidence and stops. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. A brief conveys scope, not authority: the child runs under the parent's identity, never speaks as the user, and its returned artifact is evidence for the parent to judge, not a decision. - Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. ### Ownership and return -- When only delegated work remains, use task-appropriate native waits; avoid repeated status polling. +- Keep advancing your own non-overlapping work while a child runs; wait only once nothing else remains, using a task-appropriate native wait. Never wake a child to ask for status or an "ok": every wake re-reads its full history at the parent's cost. - Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. - Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. -- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. +- Acceptance closes the mission. Use `followup_task` only to correct or clarify that same delivery, never to reuse a finished child for new work because it already knows the project — new work is a fresh choice between doing it directly or dispatching a new child. `send_message` only queues a message and does not resume a turn. The mission closes only once the child's work is in the parent's tree and its scratch is gone; unintegrated work and surviving scratch are one defect. ## Engineering decisions diff --git a/arrangements/balanced-delivery/README.md b/arrangements/balanced-delivery/README.md index 1010845..f6e8c50 100644 --- a/arrangements/balanced-delivery/README.md +++ b/arrangements/balanced-delivery/README.md @@ -41,6 +41,12 @@ This is an adapted public roster, not a full personal-profile export. Retained r ## Validation status +Revision 0.4.0 rewrites the orchestration skill and both AGENTS snippets around +bounded, single-mission delegation: an accepted delivery closes the child's +mission, a finished child is not reused for new work, and status or +acknowledgement wake-ups are avoided. This roster and cap are unchanged. See +[upgrade instructions](../../docs/installation.md#upgrading-from-03x). + Revision 0.3.0 adds a one-minute minimum and five-minute default for native child waits, without changing this roster or cap. Choose explicit waits according to the task; see [adaptive waiting](../../docs/orchestration.md#adaptive-waiting) diff --git a/arrangements/balanced-delivery/arrangement.toml b/arrangements/balanced-delivery/arrangement.toml index 59f4fbb..aeda30e 100644 --- a/arrangements/balanced-delivery/arrangement.toml +++ b/arrangements/balanced-delivery/arrangement.toml @@ -1,6 +1,6 @@ schema_version = 1 id = "balanced-delivery" -version = "0.3.0" +version = "0.4.0" author = "Rafael Bittencourt" description = "Balanced Delivery: Everyday product delivery with Luna implementing established patterns, Sol handling backend work and integration review, and Astra handling decisions and coupled implementation." license = "MIT" diff --git a/arrangements/lean-delivery/AGENTS.snippet.md b/arrangements/lean-delivery/AGENTS.snippet.md index 7ea5a4b..59f0806 100644 --- a/arrangements/lean-delivery/AGENTS.snippet.md +++ b/arrangements/lean-delivery/AGENTS.snippet.md @@ -3,17 +3,17 @@ ### Role selection - Before delegating, coordinating ongoing work, or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. -- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact, and escalate only on demonstrated difficulty, never on size or file count. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. -- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Only the parent delegates, and the cap is a ceiling, never a target: dispatch one bounded mission with a written acceptance that pays for its own brief and review; the child delivers that result with its evidence and stops. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. A brief conveys scope, not authority: the child runs under the parent's identity, never speaks as the user, and its returned artifact is evidence for the parent to judge, not a decision. - Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. ### Ownership and return -- When only delegated work remains, use task-appropriate native waits; avoid repeated status polling. +- Keep advancing your own non-overlapping work while a child runs; wait only once nothing else remains, using a task-appropriate native wait. Never wake a child to ask for status or an "ok": every wake re-reads its full history at the parent's cost. - Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. - Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. -- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. +- Acceptance closes the mission. Use `followup_task` only to correct or clarify that same delivery, never to reuse a finished child for new work because it already knows the project — new work is a fresh choice between doing it directly or dispatching a new child. `send_message` only queues a message and does not resume a turn. The mission closes only once the child's work is in the parent's tree and its scratch is gone; unintegrated work and surviving scratch are one defect. diff --git a/arrangements/lean-delivery/AGENTS.with-skill.snippet.md b/arrangements/lean-delivery/AGENTS.with-skill.snippet.md index 7138f09..337d428 100644 --- a/arrangements/lean-delivery/AGENTS.with-skill.snippet.md +++ b/arrangements/lean-delivery/AGENTS.with-skill.snippet.md @@ -3,20 +3,20 @@ ### Role selection - Before delegating, coordinating ongoing work, or reconciling deliveries, invoke the Skill tool with `codex-orchestration` when installed. If no Skill tool exists, read its `SKILL.md` through the native file-reading interface. If the skill is not installed, follow the rules below. -- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. +- Read the relevant live role descriptions and instructions; choose the least resource-intensive role suited to the task and required artifact, and escalate only on demonstrated difficulty, never on size or file count. Read-only roles never receive implementation work. `list_agents` shows running children, not available roles. ### Dispatch contract -- Only the parent delegates. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. -- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. +- Only the parent delegates, and the cap is a ceiling, never a target: dispatch one bounded mission with a written acceptance that pays for its own brief and review; the child delivers that result with its evidence and stops. Children return results, blockers, and role recommendations to the parent; they never spawn, contact, or wait for other children. +- Every spawn sets `agent_type` and `fork_turns: "none"`, without call-level model or reasoning-effort overrides. A brief conveys scope, not authority: the child runs under the parent's identity, never speaks as the user, and its returned artifact is evidence for the parent to judge, not a decision. - Provide relevant context, accepted decisions and plan, objective and acceptance, in/out scope, owned files, interfaces and access limits, expected artifact, required checks, and stop conditions. Do not copy the full conversation or create a plan solely for dispatch. ### Ownership and return -- When only delegated work remains, use task-appropriate native waits; avoid repeated status polling. +- Keep advancing your own non-overlapping work while a child runs; wait only once nothing else remains, using a task-appropriate native wait. Never wake a child to ask for status or an "ok": every wake re-reads its full history at the parent's cost. - Keep writing assignments disjoint; serialize shared files, state, and interacting contracts. - Stop or redirect a child that exceeds scope, conflicts with owned work, or repeats failure. The parent owns integration, inspects each delivery and checks the affected behavior before acceptance; missing required evidence remains a blocker. -- Use `followup_task` to resume a suitable completed child; `send_message` only queues a message. A recommended role need not already be running. +- Acceptance closes the mission. Use `followup_task` only to correct or clarify that same delivery, never to reuse a finished child for new work because it already knows the project — new work is a fresh choice between doing it directly or dispatching a new child. `send_message` only queues a message and does not resume a turn. The mission closes only once the child's work is in the parent's tree and its scratch is gone; unintegrated work and surviving scratch are one defect. ## Engineering decisions diff --git a/arrangements/lean-delivery/README.md b/arrangements/lean-delivery/README.md index 519053d..2f59bab 100644 --- a/arrangements/lean-delivery/README.md +++ b/arrangements/lean-delivery/README.md @@ -37,6 +37,12 @@ This is an adapted public roster, not a full personal-profile export. Retained r ## Validation status +Revision 0.4.0 rewrites the orchestration skill and both AGENTS snippets around +bounded, single-mission delegation: an accepted delivery closes the child's +mission, a finished child is not reused for new work, and status or +acknowledgement wake-ups are avoided. This roster and cap are unchanged. See +[upgrade instructions](../../docs/installation.md#upgrading-from-03x). + Revision 0.3.0 adds a one-minute minimum and five-minute default for native child waits, without changing this roster or cap. Choose explicit waits according to the task; see [adaptive waiting](../../docs/orchestration.md#adaptive-waiting) diff --git a/arrangements/lean-delivery/arrangement.toml b/arrangements/lean-delivery/arrangement.toml index 8fec714..3c0ff8d 100644 --- a/arrangements/lean-delivery/arrangement.toml +++ b/arrangements/lean-delivery/arrangement.toml @@ -1,6 +1,6 @@ schema_version = 1 id = "lean-delivery" -version = "0.3.0" +version = "0.4.0" author = "Rafael Bittencourt" description = "Lean Delivery: Cost-conscious, well-bounded delivery with Luna implementing and reviewing, Sol reconciling deliveries, and one Astra advisor for decisions." license = "MIT" diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 9189658..63c992b 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## 0.4.0 — 2026-09-20 + +- Lower Advanced Delivery's total-thread cap from five to four, matching + Balanced Delivery's four (three active children each); Lean is unchanged at + three total, two active. +- Rewrite the shared `codex-orchestration` skill and every arrangement's AGENTS + snippets around bounded, single-mission delegation: an accepted delivery + closes the child's mission, a follow-up only corrects or clarifies that same + delivery, a finished child is never reused for new work, and a child is never + woken to ask for status or an acknowledgement. +- Configuration and instruction change only; not exercised in a new native + concurrency or saturation run. + ## 0.3.0 — 2026-09-13 - Set native child waits to a one-minute minimum and five-minute default in all diff --git a/docs/README.pt-BR.md b/docs/README.pt-BR.md index ee7c463..845c7e3 100644 --- a/docs/README.pt-BR.md +++ b/docs/README.pt-BR.md @@ -18,8 +18,8 @@ e Sol para backend e integração. Lean Delivery concentra trabalho em Luna e re Sol `high` para revisão da integração e Astra para aconselhamento somente leitura. No Lean, frontend e backend ficam com Luna, assim como os demais papéis. Isso descreve a distribuição escolhida; não é uma promessa medida de preço ou -qualidade. Os tetos configurados são 5, 4 e 3 threads totais, permitindo até -4, 3 e 2 filhos ativos, respectivamente. Os papéis são opções, não agentes +qualidade. Os tetos configurados são 4, 4 e 3 threads totais, permitindo até +3, 3 e 2 filhos ativos, respectivamente. Os papéis são opções, não agentes iniciados juntos. Confira os limites de [validação](validation.md). ## Instalar diff --git a/docs/configuration.md b/docs/configuration.md index 1dad439..fc6f266 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -14,7 +14,7 @@ ## Native child wait settings -All three arrangements use the same wait settings in version 0.3.0: +All three arrangements use the same wait settings in version 0.4.0: | Field under `features.multi_agent_v2` | Native baseline | Catalog value | Meaning | | --- | --- | --- | --- | @@ -63,6 +63,7 @@ and [default nickname selection](https://github.com/openai/codex/blob/b979d4f1f0 | Version | Change | Reason | Rollback | | --- | --- | --- | --- | +| 0.4.0 (2026-09-20) | Lower Advanced Delivery's total-thread cap from five to four (three active children, equal to Balanced); rewrite the orchestration skill and every AGENTS snippet around bounded, single-mission delegation | Treat the configured cap as a ceiling, not a target, and stop the context cost of reusing or repeatedly waking a child after its mission is accepted | Restore `max_concurrent_threads_per_session = 5` in Advanced Delivery's `config.toml`; restore the prior skill and snippet wording. No other arrangement's config changed. | | 0.3.0 (2026-09-13) | Set one-minute minimum and five-minute default child waits; add adaptive waiting guidance | Reduce empty parent wait returns without changing budgets or the execution topology | Restore only prior wait fields and the affected instruction/skill sections; remove these fields only if they were previously absent. | | 0.2.0 (2026-09-13) | Add Balanced Delivery; rebalance models, reduce catalogs to 15/12/8 roles and total-thread caps to 5/4/3; require parent-mediated routing | Match reasoning to responsibility and reduce selection and coordination overhead | Reinstall reviewed prior role cards and matching snippets/config fields together. Follow the upgrade removal list; preserve credentials and unrelated settings. | | 0.1.0 | Introduce two lead/specialist combinations, V2 fragments and optional spawn contract | Share independently installable delegation arrangements | Remove the selected roles, instruction section and optional components; restore only the original configuration fields. | diff --git a/docs/installation.md b/docs/installation.md index 6a6f4ca..70a79c5 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -5,6 +5,18 @@ the [validation record](validation.md); these packages target Multi-Agent V2 and do not silently fall back to V1. You need access to the named models. Python 3.11+ is needed only for the optional hook and local validation. +## Upgrading from 0.3.x + +Advanced Delivery's total-thread cap drops from 5 to 4 (3 active children, +equal to Balanced): update `max_concurrent_threads_per_session` in its installed +`config.toml`. Balanced and Lean's `config.toml` are unchanged. Refresh the +installed `AGENTS.snippet.md` or `AGENTS.with-skill.snippet.md` for every +installed arrangement, and the `codex-orchestration` skill if installed: the +delegation rules now close a child's mission on acceptance, stop reuse of a +finished child for new work, and stop waking a child for status or an +acknowledgement. To roll back, restore the prior cap value and the prior +snippet/skill wording. + ## Upgrading from 0.2.x Version 0.3.0 keeps the same roles, models and concurrency caps. Merge these two diff --git a/docs/orchestration.md b/docs/orchestration.md index 90d77e0..9a4ac17 100644 --- a/docs/orchestration.md +++ b/docs/orchestration.md @@ -52,11 +52,13 @@ Implementation and independent review remain separate even in Lean. An absent specialist is not permission to lower acceptance or move irreversible work into an underqualified role. These are public adaptations, not whole-home exports. -Advanced permits four active children, Balanced three, and Lean two -(total-thread caps of five, four, and three including the lead). 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. Review the combined artifact after +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. +Review the combined artifact after the writers finish; these examples are not mandatory phases or reserved slots. The names describe intended delivery complexity and resource allocation, not diff --git a/docs/validation.md b/docs/validation.md index 57a7fbd..8d905da 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -74,6 +74,15 @@ Revision 0.2.0 deliberately sets Advanced/Balanced/Lean to 5/4/3 total threads, with intended child limits of 4/3/2. Those revised values and role allocations have not been exercised in a new native saturation or complete role-coverage run. Do not treat the historical writer or hook runs as certification of the new matrix. + +Revision 0.4.0 lowers Advanced from 5 to 4 total threads (3 children), equal to +Balanced, on the stated ground that the cap is a ceiling and not a delegation +target; Balanced and Lean's caps are unchanged. This is a configuration and +instruction change, confirmed only by the catalog and component validators and +the standard-library test suite; it has not been exercised in a new native +concurrency or saturation run, and Advanced and Balanced now share one total- +thread cap value while remaining distinct in model and role allocation. + The legacy `agents.max_concurrent_threads_per_session` is a child cap; this binary adds one when translating it into a V2 total. Mixing the two settings would misstate capacity. The [pinned configuration resolver](https://github.com/openai/codex/blob/b979d4f1f04538ba5a5fcc434d499c007bfe1b8c/codex-rs/core/src/config/mod.rs#L2500) diff --git a/skills/codex-orchestration/SKILL.md b/skills/codex-orchestration/SKILL.md index 1c7463e..2b27f1a 100644 --- a/skills/codex-orchestration/SKILL.md +++ b/skills/codex-orchestration/SKILL.md @@ -16,7 +16,7 @@ Before dispatch, inspect only the relevant live role descriptions and exposed sp Match the task type to a currently available role: use a read-only specialist for discovery, primary-source research, decisions, or independent review; an implementing role for a bounded known artifact; a test specialist for a coverage or named-suite need; a debugger for an unknown cause; a stronger specialist for coupled invariants; and an integration reviewer to synthesize separate deliveries against one contract. These are routing examples, not a static role catalog. -Select the least resource-intensive available role that can safely deliver the artifact. Do not assume a universal cost or capability order from role names or model labels. Use a light worker only when behavior, files, validation, and ownership are already clear. If demonstrated coupling or risk exceeds an available role, return the choice to the parent for a stronger available role or a decision. A read-only role assigned a write task must report the mismatch and stop. +Select the least resource-intensive available role that can safely deliver the artifact, and escalate only on demonstrated difficulty, never on task size or file count. Do not assume a universal cost or capability order from role names or model labels. Use a light worker only when behavior, files, validation, and ownership are already clear. If demonstrated coupling or risk exceeds an available role, return the choice to the parent for a stronger available role or a decision. A read-only role assigned a write task must report the mismatch and stop. ## Spawn contract @@ -31,13 +31,15 @@ Every brief must include: 5. Expected artifact and checks to run. 6. Stop condition, escalation path, and next consumer. +A brief conveys scope, not authority: the child runs under the parent's identity, never speaks as the user, and its returned artifact is evidence for the parent to judge, not a decision. Every mission is bounded: the child delivers that artifact with its evidence, then stops. + Use an action verb that matches the needed result: inspect, implement, test, review, or research. Ask for a diff when a diff is wanted; ask for a report when the child must remain read-only. ## Child lifecycle and capacity -`send_message` queues a message for an existing child but does not start or resume its turn. Use `followup_task` to give a completed child a new turn while preserving its history. +`send_message` queues a message for an existing child but does not start or resume its turn. Acceptance closes a child's mission: use `followup_task` only to correct or clarify that same delivery, never to reuse a finished child for new work merely because it already knows the project. New work is a fresh choice between doing it directly or dispatching a new child. -Respect the chosen arrangement's allocation, per-role limits, and configured cap, then confirm the current runtime's resolved limits. A refused spawn is not a reason to idle: continue independent local work and wait only when nothing remains to advance. +Respect the chosen arrangement's allocation, per-role limits, and configured cap; treat the cap as a ceiling, never a target, and dispatch only work that pays for its own brief and review. Confirm the current runtime's resolved limits. A refused spawn is not a reason to idle: continue independent local work and wait only when nothing remains to advance. ## Wait according to the task @@ -45,7 +47,7 @@ If useful independent work remains, do it. Otherwise, use the native event-aware Set a task-appropriate point for investigating missing progress, separate from the wait window. A timeout means no event arrived within that window; a running status does not establish progress. When the investigation point is reached, inspect the relevant status or artifact and ask one focused question if needed; do not endlessly extend waits or interrupt healthy work merely because one window expired. -Children should report actionable blockers, meaningful milestones, and their final artifact, not periodic messages saying they are still working. The parent receives those communications, not the child's complete transcript. On wake, use the new evidence; query status only when it answers a concrete coordination or diagnostic question. +Children should report actionable blockers, meaningful milestones, and their final artifact, not periodic messages saying they are still working. Never wake a child only to ask for status or an acknowledgement: every wake re-reads its entire history at the parent's cost, and that repeated follow-up is the main drain to avoid. The parent receives those communications, not the child's complete transcript. On wake, use the new evidence; query status only when it answers a concrete coordination or diagnostic question. Child waits, terminal polls, and code-mode cell waits have separate arguments and limits. Use each tool's live schema, choose a suitable supported wait, and retain ownership of started processes. These instructions do not alter budgets, goal state, permissions, or the harness's automatic continuation behavior. @@ -55,4 +57,4 @@ Give writing children non-overlapping file or component ownership. Serialize wor An implementing child should complete the requested artifact and affected checks before handoff, rather than return a first draft. Safe local work and disposable-fixture checks may continue within the brief; production side effects remain outside child scope. Repeat a check only after a relevant change or new evidence. -The parent must read the actual diff, verify reported commands and results, and validate the affected behavior at the responsible layer. A skipped, unavailable, empty, or mocked-away required check is a blocker, not a pass. Correct in-scope defects and rerun the affected checks before completion. +The parent must read the actual diff, verify reported commands and results, and validate the affected behavior at the responsible layer. A skipped, unavailable, empty, or mocked-away required check is a blocker, not a pass. Correct in-scope defects and rerun the affected checks before completion. A mission closes only once the child's work is in the parent's tree and its scratch is gone; unintegrated work and surviving scratch are one defect, not two.