@laitszkin/apollo-toolkit 2.2.0 → 2.4.0

package/codex-memory-manager/scripts/sync_memory_index.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""Synchronize a normalized memory index section into ~/.codex/AGENTS.md."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+from typing import Iterable
+
+START_MARKER = "<!-- codex-memory-manager:start -->"
+END_MARKER = "<!-- codex-memory-manager:end -->"
+DEFAULT_SECTION_TITLE = "## User Memory Index"
+DEFAULT_INSTRUCTIONS = [
+    "Before starting work, review the index below and open any relevant user preference files.",
+    "When a new preference category appears, create or update the matching memory file and refresh this index.",
+]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Sync the Codex user memory index section inside AGENTS.md",
+    )
+    parser.add_argument(
+        "--agents-file",
+        default="~/.codex/AGENTS.md",
+        help="Path to AGENTS.md (default: ~/.codex/AGENTS.md)",
+    )
+    parser.add_argument(
+        "--memory-dir",
+        default="~/.codex/memory",
+        help="Directory that stores memory markdown files (default: ~/.codex/memory)",
+    )
+    parser.add_argument(
+        "--section-title",
+        default=DEFAULT_SECTION_TITLE,
+        help=f"Heading to use for the index section (default: {DEFAULT_SECTION_TITLE!r})",
+    )
+    parser.add_argument(
+        "--instruction-line",
+        action="append",
+        dest="instruction_lines",
+        help="Instruction line to place before the index bullets. Repeat to add more lines.",
+    )
+    return parser.parse_args()
+
+
+def title_from_memory_file(path: Path) -> str:
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError:
+        return path.stem.replace("-", " ").title()
+
+    for line in content.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("# "):
+            return stripped[2:].strip() or path.stem.replace("-", " ").title()
+
+    return path.stem.replace("-", " ").title()
+
+
+def iter_memory_files(memory_dir: Path) -> Iterable[Path]:
+    if not memory_dir.exists() or not memory_dir.is_dir():
+        return []
+    return sorted(
+        (path for path in memory_dir.glob("*.md") if path.is_file()),
+        key=lambda path: path.name.lower(),
+    )
+
+
+def render_section(memory_files: list[Path], section_title: str, instruction_lines: list[str]) -> str:
+    lines = [START_MARKER, section_title.strip(), ""]
+
+    cleaned_instructions = [line.strip() for line in instruction_lines if line and line.strip()]
+    for line in cleaned_instructions:
+        lines.append(line)
+    if cleaned_instructions:
+        lines.append("")
+
+    if memory_files:
+        entries = sorted(
+            ((title_from_memory_file(path), path.expanduser().resolve()) for path in memory_files),
+            key=lambda item: (item[0].lower(), str(item[1]).lower()),
+        )
+        for title, path in entries:
+            lines.append(f"- [{title}]({path})")
+    else:
+        lines.append("- No memory files are currently indexed.")
+
+    lines.append(END_MARKER)
+    return "\n".join(lines)
+
+
+def remove_existing_section(content: str) -> str:
+    pattern = re.compile(
+        rf"\n*{re.escape(START_MARKER)}.*?{re.escape(END_MARKER)}\n*",
+        re.DOTALL,
+    )
+    return re.sub(pattern, "\n\n", content).rstrip()
+
+
+def sync_agents_file(agents_file: Path, section_text: str) -> None:
+    agents_file.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        original = agents_file.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        original = ""
+
+    base = remove_existing_section(original)
+    if base:
+        updated = f"{base}\n\n{section_text}\n"
+    else:
+        updated = f"{section_text}\n"
+    agents_file.write_text(updated, encoding="utf-8")
+
+
+def main() -> int:
+    args = parse_args()
+    agents_file = Path(args.agents_file).expanduser()
+    memory_dir = Path(args.memory_dir).expanduser()
+    instruction_lines = args.instruction_lines or DEFAULT_INSTRUCTIONS
+    section_text = render_section(list(iter_memory_files(memory_dir)), args.section_title, instruction_lines)
+    sync_agents_file(agents_file, section_text)
+    print(f"SYNCED_AGENTS_FILE={agents_file.resolve()}")
+    print(f"MEMORY_FILES_INDEXED={len(list(iter_memory_files(memory_dir)))}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/codex-memory-manager/tests/test_extract_recent_conversations.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Edge-case tests for extract_recent_conversations.py."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+
+SCRIPT_PATH = (
+    Path(__file__).resolve().parents[1] / "scripts" / "extract_recent_conversations.py"
+)
+
+
+def write_session(path: Path, timestamp: datetime) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    entries = [
+        {
+            "type": "session_meta",
+            "payload": {"timestamp": timestamp.isoformat()},
+        },
+        {
+            "type": "event_msg",
+            "payload": {"type": "user_message", "message": f"user:{path.stem}"},
+        },
+        {
+            "type": "event_msg",
+            "payload": {"type": "agent_message", "message": f"assistant:{path.stem}"},
+        },
+    ]
+    with path.open("w", encoding="utf-8") as handle:
+        for entry in entries:
+            handle.write(json.dumps(entry) + "\n")
+
+
+def run_extractor(
+    sessions_dir: Path,
+    archived_dir: Path | None = None,
+    *extra_args: str,
+) -> str:
+    cmd = [
+        sys.executable,
+        str(SCRIPT_PATH),
+        "--sessions-dir",
+        str(sessions_dir),
+    ]
+    if archived_dir is not None:
+        cmd.extend(["--archived-sessions-dir", str(archived_dir)])
+    cmd.extend(extra_args)
+    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    return result.stdout
+
+
+class ExtractRecentConversationsTests(unittest.TestCase):
+    def test_default_lookback_covers_last_24_hours(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            now = datetime.now(timezone.utc)
+            write_session(sessions_root / "recent.jsonl", now - timedelta(hours=3))
+
+            output = run_extractor(sessions_root)
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=1", output)
+            self.assertIn("LOOKBACK_MINUTES=1440", output)
+
+    def test_limit_zero_is_treated_as_unlimited(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            now = datetime.now(timezone.utc)
+            write_session(sessions_root / "a.jsonl", now - timedelta(minutes=5))
+            write_session(sessions_root / "b.jsonl", now - timedelta(minutes=10))
+            write_session(sessions_root / "c.jsonl", now - timedelta(minutes=15))
+
+            output = run_extractor(
+                sessions_root,
+                None,
+                "--lookback-minutes",
+                "60",
+                "--limit",
+                "0",
+            )
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=3", output)
+
+    def test_archived_sessions_are_read_before_cleanup(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            archived_root = Path(tmp) / "archived_sessions"
+            now = datetime.now(timezone.utc)
+            archived_file = archived_root / "archived.jsonl"
+            write_session(archived_file, now - timedelta(minutes=30))
+
+            output = run_extractor(
+                sessions_root,
+                archived_root,
+                "--lookback-minutes",
+                "60",
+            )
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=1", output)
+            self.assertIn("ARCHIVED_SESSIONS_INCLUDED=true", output)
+            self.assertIn("user:archived", output)
+            self.assertIn("assistant:archived", output)
+            self.assertIn("CLEANUP_REMOVED_ARCHIVED_SESSIONS=1", output)
+            self.assertFalse(archived_file.exists())
+
+    def test_cleanup_removes_only_old_sessions_from_sessions_dir(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            now = datetime.now(timezone.utc)
+            recent_file = sessions_root / "recent.jsonl"
+            old_file = sessions_root / "old.jsonl"
+            write_session(recent_file, now - timedelta(hours=6))
+            write_session(old_file, now - timedelta(days=8))
+
+            output = run_extractor(
+                sessions_root,
+                None,
+                "--lookback-minutes",
+                "1440",
+                "--retention-days",
+                "7",
+            )
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=1", output)
+            self.assertIn("CLEANUP_REMOVED_OLD_SESSIONS=1", output)
+            self.assertTrue(recent_file.exists())
+            self.assertFalse(old_file.exists())
+
+    def test_archived_cleanup_skips_active_sessions_when_paths_overlap(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            now = datetime.now(timezone.utc)
+            recent_file = sessions_root / "recent.jsonl"
+            write_session(recent_file, now - timedelta(minutes=5))
+
+            output = run_extractor(
+                sessions_root,
+                sessions_root,
+                "--lookback-minutes",
+                "60",
+            )
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=1", output)
+            self.assertIn("CLEANUP_REMOVED_ARCHIVED_SESSIONS=0", output)
+            self.assertTrue(recent_file.exists())
+
+    def test_limit_one_only_returns_latest_session_across_sources(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            archived_root = Path(tmp) / "archived_sessions"
+            now = datetime.now(timezone.utc)
+            write_session(sessions_root / "older.jsonl", now - timedelta(minutes=20))
+            newest = archived_root / "newest.jsonl"
+            write_session(newest, now - timedelta(minutes=5))
+
+            output = run_extractor(
+                sessions_root,
+                archived_root,
+                "--lookback-minutes",
+                "60",
+                "--limit",
+                "1",
+            )
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=1", output)
+            self.assertIn("newest.jsonl", output)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/codex-memory-manager/tests/test_sync_memory_index.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Tests for sync_memory_index.py."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "sync_memory_index.py"
+
+
+def run_sync(agents_file: Path, memory_dir: Path, *extra_args: str) -> str:
+    cmd = [
+        sys.executable,
+        str(SCRIPT_PATH),
+        "--agents-file",
+        str(agents_file),
+        "--memory-dir",
+        str(memory_dir),
+    ]
+    cmd.extend(extra_args)
+    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    return result.stdout
+
+
+class SyncMemoryIndexTests(unittest.TestCase):
+    def test_appends_memory_index_with_sorted_links(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            agents_file = root / "AGENTS.md"
+            agents_file.write_text("# Base Instructions\n", encoding="utf-8")
+            memory_dir = root / "memory"
+            memory_dir.mkdir()
+            (memory_dir / "workflow-preferences.md").write_text("# Workflow Preferences\n", encoding="utf-8")
+            (memory_dir / "architecture-preferences.md").write_text("# Architecture Preferences\n", encoding="utf-8")
+
+            run_sync(agents_file, memory_dir)
+
+            content = agents_file.read_text(encoding="utf-8")
+            self.assertIn("## User Memory Index", content)
+            self.assertIn("Before starting work, review the index below", content)
+            self.assertLess(
+                content.index("[Architecture Preferences]"),
+                content.index("[Workflow Preferences]"),
+            )
+
+    def test_replaces_existing_managed_section_without_duplication(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            agents_file = root / "AGENTS.md"
+            agents_file.write_text(
+                "# Base\n\n<!-- codex-memory-manager:start -->\nold\n<!-- codex-memory-manager:end -->\n",
+                encoding="utf-8",
+            )
+            memory_dir = root / "memory"
+            memory_dir.mkdir()
+            (memory_dir / "style-preferences.md").write_text("# Style Preferences\n", encoding="utf-8")
+
+            run_sync(agents_file, memory_dir, "--instruction-line", "Read this first.")
+
+            content = agents_file.read_text(encoding="utf-8")
+            self.assertEqual(content.count("<!-- codex-memory-manager:start -->"), 1)
+            self.assertIn("Read this first.", content)
+            self.assertNotIn("\nold\n", content)
+
+    def test_uses_filename_when_heading_is_missing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            agents_file = root / "AGENTS.md"
+            memory_dir = root / "memory"
+            memory_dir.mkdir()
+            (memory_dir / "java-preferences.md").write_text("No heading here\n", encoding="utf-8")
+
+            run_sync(agents_file, memory_dir)
+
+            content = agents_file.read_text(encoding="utf-8")
+            self.assertIn("[Java Preferences]", content)
+
+
+if __name__ == "__main__":
+    unittest.main()

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,39 @@
+# 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.
+
+## Highlights
+
+- Defaults to using subagents for most non-trivial work
+- Explicitly instructs Codex to spawn subagents for 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`
+- Keeps tightly coupled serial work in the main agent
+
+## Project Structure
+
+```text
+.
+├── SKILL.md
+├── LICENSE
+├── README.md
+├── agents/
+│   └── openai.yaml
+└── references/
+    ├── custom-agent-template.toml
+    └── routing-rubric.md
+```
+
+## Requirements
+
+- Codex app or CLI with subagent support
+- Write access to `~/.codex/agents`
+- Custom agent TOML format support
+
+## License
+
+MIT. See `LICENSE` for details.

package/codex-subagent-orchestration/SKILL.md

@@ -0,0 +1,206 @@
+---
+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.
+- 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; 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.
+- 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, 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.
+- For any non-trivial task, explicitly instruct Codex to spawn the chosen subagents unless delegation is blocked.
+
+### 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
+
+- Explicitly tell Codex to spawn the selected subagents and state 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/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: 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