@laitszkin/apollo-toolkit 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.4.2] - 2026-03-19
+
+### Changed
+- Relax `codex-subagent-orchestration` so reusable custom agents no longer require repeated historical use before creation or persistence.
+- Require agents to abstract task-specific delegation into the most general reusable role that still preserves clear ownership boundaries, such as `code_reviewer` before narrower one-off task agents.
+- Clarify when domain-specific specialization such as `rust_reviewer` is warranted and when a generic reusable reviewer should be preferred.
+
+## [v2.4.1] - 2026-03-19
+
+### Changed
+- Tighten `codex-subagent-orchestration` so non-trivial tasks must use actual subagent tool calls when delegation is allowed, instead of stopping at prose-only delegation guidance.
+- Require `codex-subagent-orchestration` to default to a parallel subagents workflow whenever two or more independent workstreams can run safely in parallel.
+- Clarify runtime handoff and orchestration boundaries for delegated agents, including tool-rule, sandbox, write-scope, and isolated-review expectations.
+
 ## [v2.4.0] - 2026-03-19
 
 ### Added

package/codex-subagent-orchestration/SKILL.md

@@ -15,8 +15,8 @@ description: Use for almost every non-trivial Codex task. Inspect existing custo
 ## Standards
 
 - Evidence: Inspect the current task shape and the existing custom-agent catalog before creating or updating any agent.
-- Execution: Use this skill for nearly every non-trivial task; explicitly tell Codex to spawn one or more subagents unless the task is trivial or delegation is disallowed; delegate read-heavy exploration, review, verification, and unrelated module edits; keep shared planning, conflict resolution, and final synthesis in the main agent.
-- Quality: Keep each custom agent narrow, opinionated, and non-overlapping; prefer read-only sandboxes for explorers and reviewers; avoid parallel write conflicts.
+- Execution: Use this skill for nearly every non-trivial task. When current tool rules allow delegation, the agent must actually launch one or more subagents instead of only describing delegation in prose. Treat a parallel subagents workflow as the default whenever two or more independent workstreams can run safely in parallel, use a single helper agent only when there is exactly one bounded sidecar job, and keep shared planning, conflict resolution, and final synthesis in the main agent.
+- Quality: Keep each custom agent narrow, opinionated, and non-overlapping; prefer read-only sandboxes for explorers and reviewers; keep review contexts isolated from the implementation thread; avoid parallel write conflicts.
 - Output: State which agents were reused or created, what each owned, whether they waited in parallel or were staged, and what remained with the main agent.
 
 ## Overview
@@ -54,7 +54,7 @@ Prefer `gpt-5.3-codex` first for agentic coding roles. Escalate to `gpt-5.4` whe
 
 ## When To Use
 
-Use this skill by default unless the task is genuinely trivial, such as:
+Use this skill by default unless the task is genuinely trivial or current tool rules disallow delegation, such as:
 
 - a one-shot factual answer with no decomposition value
 - a single obvious command or one-line edit
@@ -68,16 +68,20 @@ Subagents are most valuable for:
 - browser reproduction and debugging
 - parallel edits across unrelated files or modules
 
-Keep the main agent in charge when the work is highly continuous, tightly coupled, or depends on a single evolving mental model. In those cases, let subagents provide bounded context, not final ownership.
+Keep the main agent in charge when the work is highly continuous, tightly coupled, or depends on a single evolving mental model. In those cases, let subagents provide bounded context, not final ownership, and do not force parallel writers.
+
+This skill is not satisfied by merely writing that Codex should delegate later. When parallelizable sidecar work exists and delegation is allowed, the default compliant shape is a parallel subagents workflow.
 
 ## Workflow
 
 ### 1) Triage the task first
 
 - Decide whether the task is trivial, serial-but-complex, or parallelizable.
+- If the task is non-trivial and delegation is allowed, you must delegate at least one bounded subtask to a subagent.
+- If the task has two or more independent read/review/exploration tracks, you must use a parallel subagents workflow rather than a single helper agent or a staged suggestion-only plan.
 - Use subagents for most non-trivial tasks, but do not force them into tiny or tightly coupled work.
 - Prefer one writer plus supporting read-only agents when ownership would otherwise overlap.
-- For any non-trivial task, explicitly instruct Codex to spawn the chosen subagents unless delegation is blocked.
+- If tool rules require explicit user intent before delegation, confirm that gate first; once satisfied, launch the chosen subagents and do not stay in suggestion-only mode.
 
 ### 2) Inspect the current agent catalog
 
@@ -100,11 +104,19 @@ Reuse an existing custom agent when all of the following are true:
 - its tools, sandbox, and model profile are suitable
 - using it will not create role overlap with another active agent
 
-Create a new custom agent only when:
+Create a new custom agent whenever the current task exposes a stable reusable role and:
 
 - no existing agent owns the job cleanly
-- the job is likely to recur on similar tasks
 - the responsibility can be described independently from the current one-off prompt
+- the role can be named, bounded, and reused on future tasks even if this is its first appearance
+
+Do not require repeated historical use before creating a reusable custom agent. Treat "reusable" as a property of role clarity and stable boundaries, not as proof that the exact same task has already repeated many times.
+
+When a delegated job is task-specific in content but role-stable in shape, abstract it to the most general reusable agent that still preserves clear ownership boundaries.
+
+Prefer extracting a general role such as `code_reviewer` or `docs_researcher` before creating a narrowly phrased task agent such as `review_rust_pr_123`.
+
+If domain knowledge materially changes the workflow, create a specialized reusable agent such as `rust_reviewer`; otherwise keep the agent generic and reusable across languages or repositories.
 
 Do not create near-duplicates. Tighten or extend an existing agent when the gap is small and the responsibility remains coherent.
 
@@ -115,6 +127,7 @@ Do not create near-duplicates. Tighten or extend an existing agent when the gap
 - Match the filename to the `name` field unless there is a strong reason not to.
 - Keep `description` human-facing and routing-oriented: it should explain when Codex should use the agent.
 - Keep `developer_instructions` stable and role-specific; do not leak current task noise into reusable instructions.
+- Persist a custom agent as soon as its responsibility, inputs, workflow, and boundaries can be described independently from the current task details; do not wait for multiple repeats before persisting it.
 - Set `model` to either `gpt-5.3-codex` or `gpt-5.4`.
 - Set `model_reasoning_effort` from actual task complexity, not from agent prestige or habit.
 
@@ -122,7 +135,7 @@ Naming rule for this skill:
 
 - choose a short English noun phrase
 - normalize it to snake_case
-- examples: `code_mapper`, `docs_researcher`, `browser_debugger`, `payments_reviewer`
+- examples: `code_mapper`, `code_reviewer`, `docs_researcher`, `rust_reviewer`, `browser_debugger`
 
 ### 5) Use the fixed instruction format
 
@@ -147,6 +160,7 @@ Whenever you prompt a subagent, include:
 - the expected summary or output format
 - the file or module ownership boundary
 - the stop condition if the agent hits uncertainty or overlap
+- the instruction to stay within current tool-rule limits for delegation, sandbox, and write scope
 
 ### 6) Decompose ownership before spawning
 
@@ -163,9 +177,11 @@ Avoid combining exploration, review, and editing into one reusable agent when th
 
 ### 7) Orchestrate the run
 
-- Explicitly tell Codex to spawn the selected subagents and state exactly how to split the work.
+- Use actual subagent tool calls when delegation is allowed; do not stop at writing that Codex should spawn agents later.
+- State exactly how to split the work before each launch.
 - Say whether to wait for all agents before continuing or to stage them in sequence.
 - Ask for concise returned summaries, not raw logs.
+- Treat single-subagent delegation as the exception path, not the default orchestration pattern.
 
 Preferred patterns:
 
@@ -176,6 +192,7 @@ Preferred patterns:
 Practical default:
 
 - spawn 2-4 agents for a complex task
+- spawn at least 2 agents when the task clearly contains parallelizable investigation or review tracks
 - keep within the current `agents.max_threads`
 - keep nesting shallow; many Codex setups leave `agents.max_depth` at 1 unless configured otherwise
 
@@ -194,6 +211,7 @@ If the task turns into one tightly coupled stream of work, stop delegating new e
 ### 9) Maintain the agent catalog after the task
 
 - Persist any new reusable custom agent to `~/.codex/agents/`.
+- If the current task revealed a cleaner reusable abstraction than the one you first considered, persist the more general role unless domain-specific workflow differences are materially important.
 - If a newly created agent proved too broad, narrow its description and instructions before finishing.
 - If two agents overlap heavily, keep one and tighten the other instead of letting both drift.
 - Do not persist throwaway agents that are really just one-off prompts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Apollo Toolkit npm installer for managed skill linking across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",