@laitszkin/apollo-toolkit 2.4.3 → 2.6.0

package/codex-subagent-orchestration/SKILL.md

@@ -1,224 +0,0 @@
----
-name: codex-subagent-orchestration
-description: Use for almost every non-trivial Codex task. Conduct muti-agents workflow to better finish your jobs. Use this skill for better muti-agents orchestration. 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.
-- 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.
-- 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
-
-This skill adds a repeatable orchestration layer on top of Codex subagents.
-
-Use this 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 these house rules:
-
-- 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`
-
-## 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.
-
-## When To Use
-
-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
-- 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, 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.
-- 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
-
-- 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 whenever the current task exposes a stable reusable role and:
-
-- no existing agent owns the job cleanly
-- 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.
-
-### 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.
-- 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.
-
-Naming rule for this skill:
-
-- choose a short English noun phrase
-- normalize it to snake_case
-- examples: `code_mapper`, `code_reviewer`, `docs_researcher`, `rust_reviewer`, `browser_debugger`
-
-### 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
-- the instruction to stay within current tool-rule limits for delegation, sandbox, and write scope
-
-### 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
-
-- 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:
-
-- 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
-- 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
-
-### 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 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.
-
-## References
-
-Load only when needed:
-
-- `references/custom-agent-template.toml`
-- `references/routing-rubric.md`

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

@@ -1,6 +0,0 @@
-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: explicitly instruct Codex to spawn the needed subagents, 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 TOML format with a narrow role, noun-phrase snake_case name, explicit task applicability lists, and fixed developer-instructions sections, then coordinate those spawned 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

@@ -1,40 +0,0 @@
-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/routing-rubric.md

@@ -1,100 +0,0 @@
-# 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
-
-## 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`
-
-Use direct spawning language, for example: "spawn 2 subagents", "spawn a code-mapping subagent and a review subagent", or "do not spawn subagents because this task is trivial".
-
-## 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/specs-to-project-docs/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "specs-to-project-docs"
-  short_description: "Convert project specs into standardized categorized project docs"
-  default_prompt: "Use $specs-to-project-docs to inventory the project's spec.md/tasks.md/checklist.md files, reconcile them with the current repository, rewrite existing project docs into a standardized categorized structure when needed, generate or update a concise README plus split project docs for getting started, configuration, architecture, features, and developer guidance, maintain a docs/README.md reference list, then remove or archive superseded source specs after successful conversion."