feat: balance and simplify delivery arrangements

[rafaelob]

Arrangement or component and purpose

Add a middle-ground delivery option and reduce role-selection and coordination overhead. Advanced, Balanced, and Lean now provide 15, 12, and 8 roles with at most 4, 3, and 2 simultaneous children. Model allocation follows responsibility; Luna implements established patterns, not just narrow discovery. References #1; does not close its unverified runtime acceptance.

Changes

• Add Balanced Delivery with two Astra high roles, two Sol high roles, and eight Luna max roles.
• Rebalance Advanced to four Astra, four Sol, and seven Luna roles; Lean has one Astra advisor, one Sol integrator, and six Luna roles.
• Remove redundant specializations and document who takes each omitted responsibility. Preserve independent review and forbid child-to-child routing: all results and blockers return to the parent.
• Keep fresh-context briefs, ASCII English nicknames, optional components and existing licenses. Update installation, rollback and configuration documentation.

Functional evidence

Catalog validation loads all three packages and all 35 role TOMLs. The existing 37 validator/component/hook behavioral tests pass on Windows using the standard-library tooling. Component preflight reports two skills and zero plugin bundles.

The target remains Codex CLI 0.155.0-alpha.3.10. No new authenticated native test was run for this revision. Existing native writer/hook results are historical, not proof of the new allocation; complete role coverage, saturation and slot release remain unverified. No permission, authentication, MCP or hook behavior is changed.

Checks

• Catalog validator and relevant executable tests pass.
• No credentials, personal paths, private services or whole-home config dumps in the change.
• Component licenses and notices are preserved.
• Version, installation instructions and changelog describe the final change.

[Copilot]

🔵 Needs a closer look

Unresolved moderate findings remain in parent-only routing, with related documentation inconsistencies.

Pull request overview

Adds Balanced Delivery and simplifies Advanced and Lean arrangements through revised role catalogs, model allocations, concurrency caps, and routing documentation.

Changes:

• Adds the 12-role Balanced arrangement.
• Rebalances Advanced and Lean rosters and capacity limits.
• Updates routing, installation, rollback, validation, configuration, and changelog documentation.

File summaries

File	Summary / final review status
README.md	Updates arrangement matrix and version status.
docs/validation.md	Documents revised caps and historical evidence. Nit (1 vote): Current status still presents 0.1.0 as current while documenting 0.2.0 caveats.
docs/README.pt-BR.md	Updates Portuguese arrangement guidance. Nit (1 vote): Lean role-model wording contradicts the allocation table and English guide.
docs/orchestration.md	Documents routing and responsibility guidance. Moderate (1 vote): Removing security-sweep leaves generic security coverage without an explicit role contract. Nit (1 vote): Lean’s lighter-model comparison is misleading for its Astra and Sol high roles.
docs/installation.md	Adds upgrade and rollback instructions.
docs/configuration.md	Records the 0.2.0 configuration changes.
docs/CHANGELOG.md	Summarizes the release changes and validation limits.
arrangements/lean-delivery/README.md	Documents Lean’s reduced roster and routing.
arrangements/lean-delivery/config.toml	Sets Lean’s three-thread cap.
arrangements/lean-delivery/arrangement.toml	Bumps Lean to 0.2.0.
arrangements/lean-delivery/agents/test-engineer.toml	Removes the obsolete test-author role.
arrangements/lean-delivery/agents/security-sweep.toml	Removes the obsolete security role.
arrangements/lean-delivery/agents/researcher.toml	Adds parent-mediated reporting guidance.
arrangements/lean-delivery/agents/integrator-reviewer.toml	Adds parent-only handoff guidance. Moderate (1 vote): High-risk certification still routes directly to critical-reviewer.
arrangements/lean-delivery/agents/hard-task-specialist.toml	Removes the obsolete coupled-work role.
arrangements/lean-delivery/agents/frontend-worker.toml	Routes escalation to the parent.
arrangements/lean-delivery/agents/frontend-worker-light.toml	Removes the obsolete light frontend role.
arrangements/lean-delivery/agents/explorer.toml	Routes diagnosis to the parent. Moderate (1 vote): Outside-source work still routes directly to researcher.
arrangements/lean-delivery/agents/docs-writer.toml	Removes the obsolete documentation role.
arrangements/lean-delivery/agents/design-lead.toml	Removes the obsolete design role.
arrangements/lean-delivery/agents/debugger.toml	Removes the obsolete debugger role.
arrangements/lean-delivery/agents/critical-reviewer.toml	Reallocates critical review to Luna.
arrangements/lean-delivery/agents/code-reviewer.toml	Adds parent-only handoff guidance. Moderate (1 vote): High-risk review needs still route directly instead of returning to the parent.
arrangements/lean-delivery/agents/backend-worker.toml	Consolidates small-work ownership.
arrangements/lean-delivery/agents/backend-worker-light.toml	Removes the obsolete light backend role.
arrangements/lean-delivery/agents/advisor.toml	Reallocates advice to Astra.
arrangements/lean-delivery/AGENTS.with-skill.snippet.md	Updates routing and capacity guidance.
arrangements/lean-delivery/AGENTS.snippet.md	Updates routing and capacity guidance.
arrangements/balanced-delivery/README.md	Adds Balanced arrangement documentation.
arrangements/balanced-delivery/config.toml	Defines the four-thread cap.
arrangements/balanced-delivery/arrangement.toml	Adds the Balanced manifest.
arrangements/balanced-delivery/agents/test-runner.toml	Adds parent-mediated test routing. Moderate (1 vote): Follow-up tasks can still bypass parent dispatch and slot management.
arrangements/balanced-delivery/agents/researcher.toml	Adds the researcher role.
arrangements/balanced-delivery/agents/integrator-reviewer.toml	Adds the Sol integration reviewer. Moderate (1 vote): High-risk work still routes directly to critical-reviewer.
arrangements/balanced-delivery/agents/infra-sre.toml	Adds the infrastructure role. Moderate (1 vote): Unknown failures can still route directly to hard-task-specialist.
arrangements/balanced-delivery/agents/hard-task-specialist.toml	Adds the Astra coupled-work role.
arrangements/balanced-delivery/agents/frontend-worker.toml	Adds the frontend role. Moderate (1 vote): Coupled UI state can still bypass the parent.
arrangements/balanced-delivery/agents/explorer.toml	Adds the explorer role. Moderate (1 vote): Child-to-child routing remains for coupled work and external research.
arrangements/balanced-delivery/agents/database-engineer.toml	Adds the database role. Moderate (1 vote): Migration risk still routes directly to critical-reviewer.
arrangements/balanced-delivery/agents/critical-reviewer.toml	Adds the Luna critical reviewer.
arrangements/balanced-delivery/agents/code-reviewer.toml	Adds the code reviewer. Moderate (1 vote): High-risk review can still bypass parent dispatch.
arrangements/balanced-delivery/agents/backend-worker.toml	Adds the Sol backend worker. Moderate (1 vote): Coupled work can still route directly to hard-task-specialist.
arrangements/balanced-delivery/agents/advisor.toml	Adds the Astra advisor.
arrangements/balanced-delivery/AGENTS.with-skill.snippet.md	Adds Balanced routing and capacity guidance.
arrangements/balanced-delivery/AGENTS.snippet.md	Adds Balanced standalone guidance.
arrangements/advanced-delivery/README.md	Documents the reduced Advanced roster.
arrangements/advanced-delivery/config.toml	Sets the five-thread cap.
arrangements/advanced-delivery/arrangement.toml	Bumps Advanced to 0.2.0.
arrangements/advanced-delivery/agents/test-runner.toml	Adds parent-only handoff guidance. Moderate (1 vote): Unknown failures and coverage work still dispatch directly to other children.
arrangements/advanced-delivery/agents/test-engineer.toml	Reallocates test authoring to Luna. Moderate (1 vote): Production fixes and reviewer selection can still be handed to another child.
arrangements/advanced-delivery/agents/security-sweep.toml	Removes the obsolete security role.
arrangements/advanced-delivery/agents/researcher.toml	Adds parent-mediated reporting.
arrangements/advanced-delivery/agents/integrator-reviewer.toml	Reallocates integration review to Sol. Moderate (1 vote): High-risk certification still routes directly to critical-reviewer.
arrangements/advanced-delivery/agents/infra-sre.toml	Reallocates infrastructure work to Luna. Moderate (1 vote): Unknown failures still route directly to debugger.
arrangements/advanced-delivery/agents/hard-task-specialist.toml	Preserves Astra coupled implementation.
arrangements/advanced-delivery/agents/frontend-worker.toml	Reallocates frontend work to Luna. Moderate (1 vote): Coupled state can still route directly to hard-task-specialist.
arrangements/advanced-delivery/agents/frontend-worker-light.toml	Removes the obsolete light frontend role.
arrangements/advanced-delivery/agents/explorer.toml	Adds parent-mediated reporting. Moderate (1 vote): Unknown-cause work and external research still route directly to children.
arrangements/advanced-delivery/agents/docs-writer.toml	Removes the obsolete documentation role.
arrangements/advanced-delivery/agents/design-lead.toml	Preserves Astra design work.
arrangements/advanced-delivery/agents/debugger.toml	Reallocates diagnosis to Sol. Moderate (1 vote): Fixes and test execution still dispatch directly to other children.
arrangements/advanced-delivery/agents/database-engineer.toml	Reallocates database work to Luna. Moderate (1 vote): Migration risk still routes directly to critical-reviewer.
arrangements/advanced-delivery/agents/critical-reviewer.toml	Preserves Astra critical review.
arrangements/advanced-delivery/agents/code-reviewer.toml	Reallocates review to Sol. Moderate (1 vote): High-risk review still bypasses parent dispatch.
arrangements/advanced-delivery/agents/backend-worker.toml	Reallocates backend work to Sol. Moderate (1 vote): Coupled work still routes directly to hard-task-specialist.
arrangements/advanced-delivery/agents/backend-worker-light.toml	Removes the obsolete light backend role.
arrangements/advanced-delivery/agents/advisor.toml	Adds parent-mediated reporting.
arrangements/advanced-delivery/AGENTS.with-skill.snippet.md	Updates routing and capacity guidance.
arrangements/advanced-delivery/AGENTS.snippet.md	Updates standalone guidance.

Review details

Suppressed comments (25)

arrangements/advanced-delivery/agents/backend-worker.toml:14

• The new parent-only instruction at line 14 is contradicted by this remaining direct handoff: a backend child can send coupled work straight to hard-task-specialist, bypassing the parent’s dispatch and acceptance ownership. Return the recommendation to the parent instead.

Return every result, blocker, and role recommendation to the parent. References to other roles are suggestions for the parent, never child-to-child handoffs. Do not contact or wait for another child; the parent decides whether to act, spawn, or resume a role.

arrangements/advanced-delivery/agents/code-reviewer.toml:14

• The new parent-only instruction at line 14 is contradicted by this direct routing instruction. Return high-risk review needs to the parent instead of allowing a child reviewer to bypass the parent’s dispatch and briefing.

Return every result, blocker, and role recommendation to the parent. References to other roles are suggestions for the parent, never child-to-child handoffs. Do not contact or wait for another child; the parent decides whether to act, spawn, or resume a role.

arrangements/advanced-delivery/agents/database-engineer.toml:14

• The new parent-only instruction at line 14 is contradicted by this remaining direct handoff: the database child sends migration risk directly to critical-reviewer, bypassing the parent’s review decision. Return the risk and recommendation to the parent instead.

Return every result, blocker, and role recommendation to the parent. References to other roles are suggestions for the parent, never child-to-child handoffs. Do not contact or wait for another child; the parent decides whether to act, spawn, or resume a role.

arrangements/advanced-delivery/agents/debugger.toml:14

• The new parent-only instruction at line 14 is contradicted by this remaining direct dispatch: the debugger sends fixes and test execution to other children. Return those recommendations to the parent so it can choose the next role and provide its brief.

Return every result, blocker, and role recommendation to the parent. References to other roles are suggestions for the parent, never child-to-child handoffs. Do not contact or wait for another child; the parent decides whether to act, spawn, or resume a role.

arrangements/advanced-delivery/agents/explorer.toml:14

• The new parent-only instruction at line 14 is contradicted by these direct child-to-child handoffs: discovery can send unknown-cause work to debugger and external research to researcher. Return both recommendations to the parent, which owns dispatch.

Return every result, blocker, and role recommendation to the parent. References to other roles are suggestions for the parent, never child-to-child handoffs. Do not contact or wait for another child; the parent decides whether to act, spawn, or resume a role.

arrangements/advanced-delivery/agents/frontend-worker.toml:14

• The new parent-only instruction at line 14 is contradicted by this remaining direct handoff: a frontend child can send coupled state straight to hard-task-specialist, bypassing the parent’s dispatch and brief. Change the later instruction to return the recommendation to the parent.

Return every result, blocker, and role recommendation to the parent. References to other roles are suggestions for the parent, never child-to-child handoffs. Do not contact or wait for another child; the parent decides whether to act, spawn, or resume a role.

arrangements/advanced-delivery/agents/infra-sre.toml:14

• The new parent-only instruction at line 14 is contradicted by this remaining direct handoff: the infrastructure child sends unknown failures straight to debugger, bypassing parent routing and briefing.

Return every result, blocker, and role recommendation to the parent. References to other roles are suggestions for the parent, never child-to-child handoffs. Do not contact or wait for another child; the parent decides whether to act, spawn, or resume a role.

arrangements/advanced-delivery/agents/integrator-reviewer.toml:14

• The new parent-only instruction at line 14 is contradicted by this remaining direct handoff: the integration reviewer sends high-risk certification to critical-reviewer instead of returning the requirement to the parent.

Return every result, blocker, and role recommendation to the parent. References to other roles are suggestions for the parent, never child-to-child handoffs. Do not contact or wait for another child; the parent decides whether to act, spawn, or resume a role.

arrangements/advanced-delivery/agents/test-engineer.toml:14

• The new parent-only instruction at line 14 is contradicted by this remaining direct handoff: the test-engineer is told to hand production fixes to another child and identify a reviewer. Return those recommendations to the parent so it controls the next brief and slot.

Return every result, blocker, and role recommendation to the parent. References to other roles are suggestions for the parent, never child-to-child handoffs. Do not contact or wait for another child; the parent decides whether to act, spawn, or resume a role.

arrangements/advanced-delivery/agents/test-runner.toml:14

• The new parent-only instruction at line 14 is contradicted by this remaining direct dispatch: the test runner sends unknown failures and coverage work to other children. Return the classification and recommendations to the parent so it controls the next brief and slot.

Return every result, blocker, and role recommendation to the parent. References to other roles are suggestions for the parent, never child-to-child handoffs. Do not contact or wait for another child; the parent decides whether to act, spawn, or resume a role.

arrangements/balanced-delivery/agents/backend-worker.toml:18

• This direct handoff contradicts the parent-only contract added above: a child can bypass the parent’s brief and ownership by sending coupled work straight to hard-task-specialist. Return the blocker and role recommendation to the parent, which should decide whether to dispatch the next child.

Prove the result at the lowest responsible layer and add focused regression coverage for changed executable behavior. Use real collaborators when claiming an integration works. Stop for an unresolved contract, authorization, billing, destructive-data, concurrency, or transaction-design decision; report the evidence and needed owner rather than guessing. Send coupled cross-component work to hard-task-specialist.

arrangements/balanced-delivery/agents/code-reviewer.toml:20

• This direct routing instruction conflicts with the parent-only contract added at line 14. A child reviewer should return the high-risk review recommendation to the parent; otherwise it can bypass the parent’s dispatch and complete brief.
  arrangements/balanced-delivery/agents/database-engineer.toml:18
• This direct handoff contradicts the parent-only contract: the database child is instructed to send a risk review directly to critical-reviewer, bypassing the parent’s routing and acceptance decision. Return the risk and review recommendation to the parent instead.
  arrangements/balanced-delivery/agents/explorer.toml:18
• This still routes work directly from one child to two other children, contradicting the parent-only dispatch contract added above. Return both recommendations to the parent; it must decide whether to dispatch hard-task-specialist or researcher.
  arrangements/balanced-delivery/agents/frontend-worker.toml:20
• This direct handoff contradicts the parent-only contract added above: a child can bypass the parent by sending coupled UI state to another child. Return the blocker and role recommendation to the parent, which should decide whether to dispatch hard-task-specialist.
  arrangements/balanced-delivery/agents/infra-sre.toml:20
• This direct handoff contradicts the parent-only contract: the infrastructure child can route an unknown failure straight to hard-task-specialist. Return the failure mechanism and recommendation to the parent, which should own the next dispatch.
  arrangements/balanced-delivery/agents/integrator-reviewer.toml:20
• This direct handoff contradicts the parent-only routing contract: the integration reviewer is told to send high-risk work straight to critical-reviewer. Return the certification requirement to the parent so it can choose the reviewer and provide the complete brief.
  arrangements/balanced-delivery/agents/test-runner.toml:20
• This tells a child to dispatch both follow-up tasks directly, despite the new rule that role recommendations return only to the parent. That can bypass the parent’s independent brief and slot management; return the classification and recommendation to the parent instead.
  arrangements/lean-delivery/agents/code-reviewer.toml:14
• The new parent-only instruction at line 14 is contradicted by this direct routing instruction. Return high-risk review needs to the parent instead of allowing a child reviewer to bypass the parent’s dispatch and briefing.
  arrangements/lean-delivery/agents/explorer.toml:18
• This remaining direct handoff contradicts the parent-only routing contract: the Lean explorer sends outside-source work directly to researcher. Return that role recommendation to the parent, which must decide whether to dispatch it.
  arrangements/lean-delivery/agents/integrator-reviewer.toml:14
• The new parent-only instruction at line 14 is contradicted by this remaining direct handoff: the Lean integrator sends high-risk certification to critical-reviewer rather than returning the requirement to the parent.
  docs/README.pt-BR.md:19
• This Portuguese sentence says that the other Lean roles also use Luna, but the immediately preceding allocation assigns the advisor to Astra and the integrator to Sol. That makes the translated routing guide contradict both the role table and the English guide; narrow the sentence to frontend/backend (and the Luna roles) instead of all remaining roles.
  docs/orchestration.md:44
• Assigning the removed security-sweep to critical-reviewer leaves a scope gap: the retained critical-reviewer contract names authorization, billing, public APIs, destructive migrations, and core invariants, while the deleted sweep covered secrets, injection/traversal/SSRF, and dependency risk. A routine security sweep therefore has no role with an explicit contract; expand critical-reviewer or document that generic sweeps require separately qualified help.
  docs/orchestration.md:22
• This still describes Lean as using lighter models, but its advisor is gpt-6-astra at high, the same allocation as Advanced's advisor, and its integrator is also Sol high. That makes the comparison misleading for users choosing the lower-cost topology; qualify the claim as a narrower roster with lighter models for most roles.
  docs/validation.md:53
• These new 0.2.0 caveats are correct, but the Current measured status section above still begins with “Version 0.1.0 is...”, so this page presents the current release as 0.1.0 while documenting 0.2.0 here. Update that status text or explicitly label it as historical so readers do not mistake the old evidence for the current release.

• Files reviewed: 69/69 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.