@laitszkin/apollo-toolkit 2.2.0 → 2.3.0

package/AGENTS.md

@@ -16,6 +16,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can investigate application logs and produce evidence-backed root-cause findings.
 - Users can answer repository-backed questions with additional web research when needed.
 - Users can commit and push local changes without performing version or release work.
+- Users can orchestrate Codex subagents for most non-trivial tasks by reusing or creating focused custom agents under `~/.codex/agents`, then delegating exploration, review, verification, and unrelated module work while keeping tightly coupled execution in the main agent.
 - Users can research a topic deeply and produce evidence-based deliverables.
 - Users can research the latest completed market week and produce a PDF watchlist of tradeable instruments for the coming week.
 - Users can turn a marked weekly finance PDF into a concise evidence-based financial event report.

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.3.0] - 2026-03-18
+
+### Added
+- Add `codex-subagent-orchestration` for default subagent routing on most non-trivial Codex tasks, including reusable custom-agent catalog inspection, creation, and persistence guidance.
+- Add OpenAI-backed subagent references, a reusable custom-agent TOML template, and a routing rubric for splitting exploration, review, verification, and isolated implementation work.
+
+### Changed
+- Restrict `codex-subagent-orchestration` starter model guidance to `gpt-5.4` and `gpt-5.3-codex`.
+- Require reusable subagents to set `model_reasoning_effort` by delegated task complexity instead of using a single fixed effort.
+
 ## [v2.2.0] - 2026-03-18
 
 ### Added

package/README.md

@@ -8,6 +8,7 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - analyse-app-logs
 - answering-questions-with-research
 - commit-and-push
+- codex-subagent-orchestration
 - deep-research-topics
 - develop-new-features
 - discover-edge-cases

package/codex-subagent-orchestration/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yamiyorunoshura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/codex-subagent-orchestration/README.md

@@ -0,0 +1,42 @@
+# codex-subagent-orchestration
+
+Use Codex subagents on nearly every non-trivial task.
+
+This skill inspects existing custom agents under `~/.codex/agents`, reuses them when they fit, creates new focused custom agents in the official Codex TOML format when they do not, and coordinates parallel subagent work for exploration, review, verification, and unrelated module edits.
+
+The workflow is grounded in OpenAI's Codex subagent docs and then adds a few house conventions: noun-phrase snake_case names, a fixed `developer_instructions` template, and persistence of reusable personal agents under `~/.codex/agents`.
+
+## Highlights
+
+- Defaults to using subagents for most non-trivial work
+- Reuses existing custom agents before creating new ones
+- Persists new reusable agents to `~/.codex/agents`
+- Enforces narrow responsibilities and a fixed `developer_instructions` template
+- Restricts reusable subagent models to `gpt-5.4` and `gpt-5.3-codex`
+- Distinguishes official Codex requirements from this repository's house rules
+- Keeps tightly coupled serial work in the main agent
+
+## Project Structure
+
+```text
+.
+├── SKILL.md
+├── LICENSE
+├── README.md
+├── agents/
+│   └── openai.yaml
+└── references/
+    ├── openai-codex-subagents.md
+    ├── custom-agent-template.toml
+    └── routing-rubric.md
+```
+
+## Requirements
+
+- Codex app or CLI with subagent support
+- Write access to `~/.codex/agents`
+- Current OpenAI Codex custom-agent format support
+
+## License
+
+MIT. See `LICENSE` for details.

package/codex-subagent-orchestration/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: codex-subagent-orchestration
+description: Use for almost every non-trivial Codex task. Inspect existing custom agents under `~/.codex/agents`, reuse them when they already fit, create a new focused custom agent in the official Codex TOML format when needed, and coordinate parallel subagents for exploration, review, verification, or unrelated module work while keeping tightly coupled serial work in the main agent.
+---
+
+# Codex Subagent Orchestration
+
+## Dependencies
+
+- Required: none.
+- Conditional: task-specific skills only when the delegated agent's job clearly benefits from them; `openai-docs` when the delegated work needs current OpenAI/Codex documentation or when Codex subagent schema and orchestration rules must be re-verified.
+- Optional: none.
+- Fallback: If subagent delegation is unavailable, continue in a single thread and report that orchestration was skipped. If `~/.codex/agents` does not exist, create it before persisting personal custom agents.
+
+## Standards
+
+- Evidence: Inspect the current task shape and the existing custom-agent catalog before creating or updating any agent, and check the latest official Codex docs before changing schema-level conventions.
+- Execution: Use this skill for nearly every non-trivial task; 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.
+- 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
+
+This skill adds a repeatable orchestration layer on top of Codex subagents.
+
+The official OpenAI basis for this skill is summarized in `references/openai-codex-subagents.md`.
+
+Follow the current OpenAI Codex custom-agent format:
+
+- personal custom agents live in `~/.codex/agents/`
+- project-scoped custom agents live in `.codex/agents/`
+- each custom agent is one standalone TOML file
+- required fields are `name`, `description`, and `developer_instructions`
+
+This skill adds two house rules on top of the official schema:
+
+- use short English noun phrases normalized to snake_case for `name`
+- use the fixed `developer_instructions` structure from `references/custom-agent-template.toml`
+- restrict reusable subagent model choices in this repository to `gpt-5.4` and `gpt-5.3-codex`
+
+OpenAI documents the TOML schema and examples, but it does not explicitly require noun-phrase naming. Treat noun-phrase naming as this skill's convention for clearer routing and reuse.
+OpenAI also documents that Codex only spawns subagents when explicitly asked. Treat invoking this skill as the explicit orchestration step for non-trivial work, while still respecting any stricter environment rule that forbids delegation.
+
+## Model policy
+
+Use only these reusable subagent models:
+
+- `gpt-5.3-codex` for most coding-focused explorers, reviewers, verifiers, and bounded implementers
+- `gpt-5.4` for the hardest tasks that need broader judgment, ambiguity handling, or heavier cross-cutting synthesis
+
+Set `model_reasoning_effort` by task complexity:
+
+- `low`: straightforward bounded lookups, narrow evidence gathering, or simple mechanical checks
+- `medium`: ordinary non-trivial exploration, review, test triage, and isolated edits
+- `high`: ambiguous debugging, multi-step review, or higher-risk implementation work
+- `xhigh`: only for the hardest investigations or synthesis-heavy subagents where latency is justified
+
+Prefer `gpt-5.3-codex` first for agentic coding roles. Escalate to `gpt-5.4` when the delegated job is less mechanical and more judgment-heavy.
+
+Codex does not spontaneously delegate just because custom agents exist. Calling this skill is the explicit instruction that makes the main agent inspect the catalog, decide whether delegation is worthwhile, and then reuse or create the right subagents.
+
+## When To Use
+
+Use this skill by default unless the task is genuinely trivial, such as:
+
+- a one-shot factual answer with no decomposition value
+- a single obvious command or one-line edit
+- a tiny serial fix where spawning another agent would add more coordination than value
+
+Subagents are most valuable for:
+
+- codebase exploration and architecture mapping
+- evidence gathering and independent review
+- live-doc or API verification
+- 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.
+
+## Workflow
+
+### 1) Triage the task first
+
+- Decide whether the task is trivial, serial-but-complex, or parallelizable.
+- 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.
+- Remember that Codex does not spawn subagents automatically; the orchestration decision must be explicit.
+
+### 2) Inspect the current agent catalog
+
+- Read `~/.codex/agents/*.toml` first.
+- Read `.codex/agents/*.toml` next when the current repository has project-scoped agents.
+- Build a quick catalog of each agent's:
+  - `name`
+  - `description`
+  - tool or MCP surface
+  - sandbox mode
+  - effective responsibility
+- Reuse an existing agent when its responsibility already fits the task without stretching into adjacent work.
+
+### 3) Decide reuse vs create
+
+Reuse an existing custom agent when all of the following are true:
+
+- its `description` matches the delegated job
+- its `developer_instructions` already enforce the right boundaries
+- 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:
+
+- 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
+
+Do not create near-duplicates. Tighten or extend an existing agent when the gap is small and the responsibility remains coherent.
+
+### 4) Create the custom agent in the official format when needed
+
+- Persist reusable personal agents to `~/.codex/agents/<name>.toml`.
+- Use the file template in `references/custom-agent-template.toml`.
+- 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.
+- 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.
+
+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`
+
+### 5) Use the fixed instruction format
+
+Every reusable custom agent created by this skill must keep the same section order inside `developer_instructions`:
+
+1. `# Role`
+2. `## Use when`
+3. `## Do not use when`
+4. `## Inputs`
+5. `## Workflow`
+6. `## Output`
+7. `## Boundaries`
+
+The `Use when` and `Do not use when` lists are the applicability contract. Keep them concrete.
+
+### 5.5) Use a fixed runtime handoff format
+
+Whenever you prompt a subagent, include:
+
+- the exact job split
+- whether Codex should wait for all agents before continuing
+- the expected summary or output format
+- the file or module ownership boundary
+- the stop condition if the agent hits uncertainty or overlap
+
+### 6) Decompose ownership before spawning
+
+Give each subagent one exclusive job. Good ownership boundaries include:
+
+- `code_mapper`: map files, entry points, and dependencies
+- `docs_researcher`: verify external docs or APIs
+- `security_reviewer`: look for concrete exploit or hardening risks
+- `test_reviewer`: find missing coverage and brittle assumptions
+- `browser_debugger`: reproduce UI behavior and capture evidence
+- `ui_fixer` or `api_fixer`: implement a bounded change after the problem is understood
+
+Avoid combining exploration, review, and editing into one reusable agent when those responsibilities can stay separate.
+
+### 7) Orchestrate the run
+
+- Tell Codex exactly how to split the work.
+- Say whether to wait for all agents before continuing or to stage them in sequence.
+- Ask for concise returned summaries, not raw logs.
+
+Preferred patterns:
+
+- Parallel read-only agents for exploration, review, tests, logs, or docs.
+- Explorer first, implementer second, reviewer third when the work is serial but benefits from bounded context.
+- Multiple write-capable agents only when their modules and edited files do not overlap.
+
+Practical default:
+
+- spawn 2-4 agents for a complex task
+- keep within the current `agents.max_threads`
+- keep nesting shallow; many Codex setups leave `agents.max_depth` at 1 unless configured otherwise
+
+### 8) Keep the main agent responsible for continuity
+
+The main agent must:
+
+- own the todo list and the overall plan
+- decide task boundaries
+- merge results from parallel threads
+- resolve conflicting findings or overlapping edits
+- perform final validation and final user-facing synthesis
+
+If the task turns into one tightly coupled stream of work, stop delegating new edits and bring execution back to the main agent.
+
+### 9) Maintain the agent catalog after the task
+
+- Persist any new reusable custom agent to `~/.codex/agents/`.
+- 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.
+
+## References
+
+Load only when needed:
+
+- `references/custom-agent-template.toml`
+- `references/openai-codex-subagents.md`
+- `references/routing-rubric.md`

package/codex-subagent-orchestration/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Codex Subagent Orchestration"
+  short_description: "Reuse or create focused Codex custom agents for most non-trivial tasks"
+  default_prompt: "Use $codex-subagent-orchestration for almost every non-trivial task: inspect existing custom agents under `~/.codex/agents` and `.codex/agents`, reuse a focused agent when one already fits, otherwise create a new reusable custom agent in the official Codex TOML format with a narrow role, noun-phrase snake_case name, explicit task applicability lists, and fixed developer-instructions sections, then coordinate subagents for exploration, review, verification, or unrelated module edits while keeping tightly coupled serial work and final synthesis in the main agent. Persist any new reusable agents to `~/.codex/agents`."
+policy:
+  allow_implicit_invocation: true

package/codex-subagent-orchestration/references/custom-agent-template.toml

@@ -0,0 +1,40 @@
+name = "code_mapper"
+description = "Read-only codebase explorer for locating the relevant files, entry points, and dependency paths before implementation starts."
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+# Role
+You are Code Mapper, a focused exploration subagent.
+
+## Use when
+- The parent agent needs architecture mapping before editing.
+- The task requires identifying entry points, ownership, or dependency flow.
+- A writer or reviewer needs a bounded evidence packet first.
+
+## Do not use when
+- The task is a tiny obvious fix.
+- The task requires owning the final implementation.
+- The work is mostly external-doc research or browser reproduction.
+
+## Inputs
+- The parent task summary.
+- The repository or file scope to inspect.
+- Any known symptoms, failing behavior, or suspected areas.
+
+## Workflow
+1. Stay in exploration mode.
+2. Trace the real execution path.
+3. Prefer fast search and targeted file reads over broad scans.
+4. Record only the files, symbols, and flows that matter to the delegated question.
+
+## Output
+- Relevant files and symbols.
+- The most likely execution path.
+- Key risks, unknowns, and follow-up questions for the parent agent.
+
+## Boundaries
+- Do not edit code.
+- Do not drift into solution design unless the parent explicitly asks.
+- Keep the response concise and evidence-based.
+"""

package/codex-subagent-orchestration/references/openai-codex-subagents.md

@@ -0,0 +1,41 @@
+# OpenAI Codex subagents notes
+
+Verified on 2026-03-18 from the official OpenAI Codex docs:
+
+- [Subagents](https://developers.openai.com/codex/subagents)
+- [Subagents concepts](https://developers.openai.com/codex/concepts/subagents)
+
+## Official Codex facts this skill depends on
+
+- Codex only spawns subagents when explicitly asked to do so.
+- Custom agents can live in `~/.codex/agents/` for personal reuse or `.codex/agents/` for project-scoped reuse.
+- Each custom agent file must define `name`, `description`, and `developer_instructions`.
+- The `name` field is the source of truth; matching the filename to the name is only the simplest convention.
+- Optional fields such as `nickname_candidates`, `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config` can be set per custom agent.
+- Custom agents inherit the parent session's runtime behavior unless the custom agent configuration narrows it further.
+- Global orchestration settings live under `[agents]`, including `agents.max_threads`, `agents.max_depth`, and `agents.job_max_runtime_seconds`.
+- OpenAI recommends parallel subagents especially for read-heavy work such as exploration, triage, tests, and summarization, and warns to be more careful with parallel write-heavy workflows.
+- OpenAI's current model catalog says to start with `gpt-5.4` when you are not sure which model to choose.
+- The current `gpt-5.4` model page says `reasoning.effort` supports `none`, `low`, `medium`, `high`, and `xhigh`.
+- The current `gpt-5.3-codex` model page says it is optimized for agentic coding tasks and supports `low`, `medium`, `high`, and `xhigh` reasoning effort.
+- The best custom agents are narrow and opinionated, with a clear job and clear boundaries.
+
+## House conventions added by this skill
+
+These rules are not required by OpenAI, but this skill standardizes them for better reuse:
+
+- use short English noun phrases normalized to snake_case for every custom-agent `name`
+- keep the filename equal to the `name` unless there is a strong reason not to
+- use the fixed `developer_instructions` section order from `references/custom-agent-template.toml`
+- restrict reusable subagent model choices in this repository to `gpt-5.4` and `gpt-5.3-codex`
+- choose `model_reasoning_effort` from task complexity instead of pinning one static effort everywhere
+- treat the main agent as the owner of planning, merge decisions, and final synthesis
+- persist reusable personal agents to `~/.codex/agents` so similar future tasks can reuse them
+
+## What OpenAI does not currently mandate
+
+- noun-phrase grammar for custom-agent names
+- one universal `developer_instructions` section layout
+- a policy that every task should use subagents
+
+This skill chooses those conventions as opinionated defaults for non-trivial work.

package/codex-subagent-orchestration/references/routing-rubric.md

@@ -0,0 +1,102 @@
+# Routing Rubric
+
+Use this rubric before spawning or creating a custom agent.
+
+## 1. Delegate by default for non-trivial work
+
+Subagents are usually worth it when the task benefits from:
+
+- parallel read-heavy exploration
+- independent review or verification
+- bounded evidence gathering
+- unrelated module edits that can proceed without conflicts
+
+Keep the task in the main agent when it is:
+
+- tiny and obvious
+- one continuous chain of reasoning with no clean split
+- likely to create overlapping edits across the same files
+- blocked by an environment rule that disallows live delegation
+
+OpenAI's current Codex docs also state that subagents are explicit: Codex only spawns them when asked to do so.
+
+## 2. Reuse before creating
+
+Reuse an existing custom agent when:
+
+- the `description` matches the delegated job
+- the `developer_instructions` already define the correct boundaries
+- the tool surface and sandbox mode are appropriate
+
+Create a new one only when the job is both reusable and clearly distinct.
+
+## 3. Keep roles independent
+
+Good reusable roles:
+
+- `code_mapper`
+- `docs_researcher`
+- `security_reviewer`
+- `test_reviewer`
+- `browser_debugger`
+- `ui_fixer`
+- `api_fixer`
+
+Bad reusable roles:
+
+- agents that both explore and fix
+- agents that both review and implement
+- agents whose name depends on one temporary bug ticket
+
+## 4. Prefer read-only support agents
+
+Default to read-only for:
+
+- exploration
+- review
+- docs verification
+- browser reproduction without app edits
+
+Use write-capable agents only when they own a bounded implementation scope.
+
+## 5. Control parallel writes
+
+Parallel writes are acceptable only when:
+
+- file ownership does not overlap
+- module boundaries are clear
+- the main agent can merge results cheaply
+
+Otherwise use one writer and several read-only helpers.
+
+## 6. Use a fixed handoff prompt
+
+Every subagent handoff should include:
+
+- `Objective`
+- `Inputs and scope`
+- `File or module ownership`
+- `Constraints and stop conditions`
+- `Expected output shape`
+- `Blocking or non-blocking status`
+
+This follows OpenAI's documented guidance that a good subagent prompt should explain the work split, whether Codex should wait, and what summary or output to return.
+
+## 7. Pick model and reasoning by complexity
+
+Allowed reusable subagent models for this skill:
+
+- `gpt-5.3-codex`
+- `gpt-5.4`
+
+Default selection:
+
+- use `gpt-5.3-codex` for most code-centered delegated work
+- use `gpt-5.4` when the delegated task needs broader synthesis, harder judgment, or more cross-domain reasoning
+
+Reasoning effort guide:
+
+- `low` for simple, bounded, low-risk delegated tasks
+- `medium` for standard non-trivial delegated tasks
+- `high` for complex or ambiguous delegated tasks
+- `xhigh` only when the extra latency is justified by especially difficult synthesis or investigation

package/package.json

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