@laitszkin/apollo-toolkit 2.3.0 → 2.4.1

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 manage Codex user-preference memory by reviewing the last 24 hours of chats, storing categorized memory documents under `~/.codex/memory`, and syncing a memory index into `~/.codex/AGENTS.md`.
 - 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.

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [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
+- Add `codex-memory-manager` for reviewing the last 24 hours of Codex chats, storing durable preference memory, and syncing a managed memory index into `~/.codex/AGENTS.md`.
+- Add extractor and index-sync helper scripts plus focused tests for the new Codex memory workflow.
+
+### Changed
+- Update `codex-subagent-orchestration` guidance, prompts, and routing notes to require explicit subagent spawning language for non-trivial tasks.
+
+### Removed
+- Remove the standalone OpenAI Codex subagent summary reference from `codex-subagent-orchestration` now that the skill documentation carries the needed guidance directly.
+
 ## [v2.3.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-memory-manager
 - codex-subagent-orchestration
 - deep-research-topics
 - develop-new-features

package/codex-memory-manager/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LaiTszKin
+
+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-memory-manager/README.md

@@ -0,0 +1,54 @@
+# codex-memory-manager
+
+Persist durable user preferences from recent Codex conversations into categorized memory files and a synchronized AGENTS index.
+
+## Highlights
+
+- Reads the last 24 hours of `~/.codex/sessions` and `~/.codex/archived_sessions`
+- Stores categorized preference memory under `~/.codex/memory/*.md`
+- Keeps a normalized memory index at the end of `~/.codex/AGENTS.md`
+- Adds new index entries automatically when new preference categories appear
+- Preserves the existing language already used in `~/.codex/AGENTS.md`
+
+## Project Structure
+
+```text
+.
+├── SKILL.md
+├── README.md
+├── LICENSE
+├── agents/
+│   └── openai.yaml
+├── scripts/
+│   ├── extract_recent_conversations.py
+│   └── sync_memory_index.py
+└── tests/
+    ├── test_extract_recent_conversations.py
+    └── test_sync_memory_index.py
+```
+
+## Requirements
+
+- Python 3.9+
+- Access to `~/.codex/sessions`
+- Access to `~/.codex/archived_sessions`
+- Write access to `~/.codex/AGENTS.md`
+- Write access to `~/.codex/memory/`
+
+## Quick Start
+
+Extract the recent conversations:
+
+```bash
+python3 scripts/extract_recent_conversations.py --lookback-minutes 1440
+```
+
+Refresh the AGENTS memory index after updating the memory files:
+
+```bash
+python3 scripts/sync_memory_index.py --agents-file ~/.codex/AGENTS.md --memory-dir ~/.codex/memory
+```
+
+## License
+
+MIT. See `LICENSE` for details.

package/codex-memory-manager/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: codex-memory-manager
+description: Manage persistent Codex user-preference memory from recent conversation history. Use when users ask to learn from the last 24 hours of chats, update `~/.codex/AGENTS.md`, maintain `~/.codex/memory/*.md`, or sync new preference categories discovered in `~/.codex/sessions` and `~/.codex/archived_sessions`.
+---
+
+# Codex Memory Manager
+
+## Dependencies
+
+- Required: none.
+- Conditional: `learn-skill-from-conversations` when the same conversation review should also evolve the skill catalog.
+- Optional: none.
+- Fallback: If `~/.codex/sessions`, `~/.codex/archived_sessions`, or `~/.codex/AGENTS.md` are unavailable, report the missing path and stop instead of guessing.
+
+## Standards
+
+- Evidence: Derive memory only from actual recent Codex conversations, and keep each stored preference tied to concrete chat evidence.
+- Execution: Extract the last 24 hours first, classify durable user preferences into memory files, then refresh the AGENTS index section.
+- Quality: Ignore one-off instructions, avoid duplicating categories, and preserve the existing language and tone already used in `~/.codex/AGENTS.md`.
+- Output: Report which sessions were reviewed, which memory categories were created or updated, and whether the AGENTS index changed.
+
+## Goal
+
+Keep a durable, categorized memory of user preferences so future agents can quickly review relevant guidance before starting work.
+
+## Required Resources
+
+- `scripts/extract_recent_conversations.py` to read the last 24 hours of Codex sessions, including archived sessions.
+- `scripts/sync_memory_index.py` to maintain a normalized memory index section at the end of `~/.codex/AGENTS.md`.
+
+## Workflow
+
+### 1) Extract the last 24 hours of Codex conversations
+
+- Run:
+
+```bash
+python3 ~/.codex/skills/codex-memory-manager/scripts/extract_recent_conversations.py --lookback-minutes 1440
+```
+
+- The extractor reads both `~/.codex/sessions` and `~/.codex/archived_sessions`.
+- If output is exactly `NO_RECENT_CONVERSATIONS`, stop immediately and report that no memory update is needed.
+- Review every returned `[USER]` and `[ASSISTANT]` block before deciding that a preference is stable.
+- The extractor also cleans up stale session files after reading, matching the existing conversation-learning workflow.
+
+### 2) Distill only stable user preferences
+
+- Focus on preferences that are durable and reusable, such as:
+  - architecture and abstraction preferences
+  - code style and naming preferences
+  - workflow preferences
+  - testing expectations
+  - language- or ecosystem-specific preferences
+  - reporting and communication format preferences
+- Ignore transient task details, secrets, and one-off requests that are not likely to generalize.
+- Prefer explicit user instructions. Use assistant behavior as supporting context only when it clearly reflects repeated user guidance.
+
+### 3) Classify preferences into memory documents
+
+- Store memory files under `~/.codex/memory/*.md`.
+- Reuse an existing category file when the new preference clearly belongs there.
+- Create a new category file when the recent chats introduce a distinct new class of preferences. Example: if the existing files are Rust-focused and recent chats introduce stable Java preferences, add a new Java-oriented category file and index it.
+- Keep filenames in kebab-case and scoped to a real category, for example:
+  - `architecture-preferences.md`
+  - `workflow-preferences.md`
+  - `java-preferences.md`
+- Use this normalized structure inside each memory file:
+
+```md
+# Architecture Preferences
+
+## Scope
+User preferences about system design, reuse, abstractions, and code organization.
+
+## Preferences
+- Prefer extending existing modules over parallel implementations.
+  - Applies when: adding adjacent behavior in an existing codebase.
+  - Evidence: repeated direction from recent Codex conversations reviewed on 2026-03-18.
+- Avoid speculative abstractions and over-engineering.
+  - Applies when: choosing between a focused edit and a broader refactor.
+  - Evidence: explicit repeated user guidance in recent sessions.
+
+## Maintenance
+- Keep entries concrete and action-guiding.
+- Merge duplicates instead of restating the same preference.
+- Replace older statements when newer evidence clearly supersedes them.
+```
+
+### 4) Refresh the AGENTS memory index at the end of `~/.codex/AGENTS.md`
+
+- First inspect `~/.codex/AGENTS.md` and mirror its existing language in the memory section instructions.
+- After updating memory files, run `scripts/sync_memory_index.py` to rewrite the managed section at the end of the file.
+- The section must do both of these things explicitly:
+  - instruct future agents to review the index before starting work
+  - instruct future agents to update the matching memory files and refresh the index when a new category appears
+- Example command in English AGENTS files:
+
+```bash
+python3 ~/.codex/skills/codex-memory-manager/scripts/sync_memory_index.py \
+  --agents-file ~/.codex/AGENTS.md \
+  --memory-dir ~/.codex/memory \
+  --section-title "## User Memory Index" \
+  --instruction-line "Before starting work, review the index below and open any relevant user preference files." \
+  --instruction-line "When a new preference category appears, create or update the matching memory file and refresh this index."
+```
+
+- The script writes a managed block with markdown links to every indexed memory file.
+- Keep the managed block at the tail of `~/.codex/AGENTS.md`; do not scatter memory links elsewhere in the file.
+
+### 5) Report the memory update
+
+- Summarize:
+  - how many sessions were reviewed
+  - which categories were created or updated
+  - whether a new category was introduced
+  - whether the AGENTS memory index changed
+- If no durable preferences were found, say so explicitly and avoid creating placeholder memory files.
+
+## Guardrails
+
+- Do not store secrets, tokens, credentials, or personal data that should not persist.
+- Do not invent preferences when the evidence is weak or ambiguous.
+- Do not create duplicate categories when a current memory document already covers the same theme.
+- Do not rewrite unrelated parts of `~/.codex/AGENTS.md`; only manage the memory index block at the end.

package/codex-memory-manager/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codex Memory Manager"
+  short_description: "Persist user preferences from recent Codex chats"
+  default_prompt: "Use $codex-memory-manager to review the last 24 hours of Codex sessions, update ~/.codex/memory/*.md, and refresh the memory index at the end of ~/.codex/AGENTS.md."

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

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+"""Extract recent Codex conversation history from Codex session stores."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+DEFAULT_LOOKBACK_MINUTES = 24 * 60
+DEFAULT_RETENTION_DAYS = 7
+
+
+@dataclass
+class SessionRecord:
+    path: Path
+    timestamp_utc: datetime
+    messages: Optional[List[Tuple[str, str]]] = None
+
+
+def parse_iso_timestamp(raw: Optional[str]) -> Optional[datetime]:
+    if not raw:
+        return None
+    value = raw.strip()
+    if not value:
+        return None
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def read_session_timestamp(path: Path) -> Optional[datetime]:
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            first_line = handle.readline().strip()
+    except OSError:
+        return None
+
+    if not first_line:
+        return None
+
+    try:
+        first_entry = json.loads(first_line)
+    except json.JSONDecodeError:
+        return None
+
+    if first_entry.get("type") != "session_meta":
+        return None
+
+    payload = first_entry.get("payload", {})
+    if not isinstance(payload, dict):
+        return None
+
+    return parse_iso_timestamp(payload.get("timestamp")) or parse_iso_timestamp(first_entry.get("timestamp"))
+
+
+def iter_session_paths(root: Path) -> Iterable[Path]:
+    if not root.exists() or not root.is_dir():
+        return
+    yield from root.rglob("*.jsonl")
+
+
+def find_recent_sessions(
+    session_roots: Sequence[Path],
+    cutoff_utc: datetime,
+    limit: Optional[int],
+) -> List[SessionRecord]:
+    candidates: List[SessionRecord] = []
+    seen_paths = set()
+
+    for root in session_roots:
+        for path in iter_session_paths(root):
+            resolved_path = path.resolve()
+            if resolved_path in seen_paths:
+                continue
+            seen_paths.add(resolved_path)
+
+            timestamp_utc = read_session_timestamp(path)
+            if timestamp_utc is None:
+                continue
+            if timestamp_utc < cutoff_utc:
+                continue
+            candidates.append(SessionRecord(path=path, timestamp_utc=timestamp_utc))
+
+    candidates.sort(key=lambda record: record.timestamp_utc, reverse=True)
+    if limit is None:
+        return candidates
+    return candidates[:limit]
+
+
+def sanitize_text(text: str, max_chars: int) -> str:
+    cleaned = text.replace("\r\n", "\n").replace("\r", "\n").strip()
+    if max_chars <= 0:
+        return cleaned
+    if len(cleaned) <= max_chars:
+        return cleaned
+    return cleaned[: max_chars - 1].rstrip() + "..."
+
+
+def looks_like_wrapper_message(text: str) -> bool:
+    stripped = text.strip()
+    if not stripped:
+        return True
+    lower = stripped.lower()
+    return (
+        stripped.startswith("# AGENTS.md instructions for")
+        or stripped.startswith("<environment_context>")
+        or "<collaboration_mode>" in lower
+        or stripped.startswith("<permissions instructions>")
+        or stripped.startswith("<app-context>")
+    )
+
+
+def extract_text_from_content(content: Sequence[object]) -> str:
+    texts: List[str] = []
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        part_type = part.get("type")
+        if part_type in {"input_text", "output_text", "text"}:
+            value = part.get("text", "")
+            if isinstance(value, str) and value.strip():
+                texts.append(value)
+    return "\n".join(texts).strip()
+
+
+def extract_messages_from_event_entries(entries: Iterable[dict], max_chars: int) -> List[Tuple[str, str]]:
+    messages: List[Tuple[str, str]] = []
+    for entry in entries:
+        if entry.get("type") != "event_msg":
+            continue
+        payload = entry.get("payload", {})
+        if not isinstance(payload, dict):
+            continue
+
+        payload_type = payload.get("type")
+        if payload_type == "user_message":
+            text = payload.get("message", "")
+            if isinstance(text, str) and text.strip():
+                messages.append(("user", sanitize_text(text, max_chars)))
+        elif payload_type == "agent_message":
+            text = payload.get("message", "")
+            if isinstance(text, str) and text.strip():
+                messages.append(("assistant", sanitize_text(text, max_chars)))
+    return messages
+
+
+def extract_messages_from_response_items(entries: Iterable[dict], max_chars: int) -> List[Tuple[str, str]]:
+    messages: List[Tuple[str, str]] = []
+    for entry in entries:
+        if entry.get("type") != "response_item":
+            continue
+        payload = entry.get("payload", {})
+        if not isinstance(payload, dict):
+            continue
+        if payload.get("type") != "message":
+            continue
+
+        role = payload.get("role")
+        if role not in {"user", "assistant"}:
+            continue
+
+        text = extract_text_from_content(payload.get("content", []))
+        if not text or looks_like_wrapper_message(text):
+            continue
+        messages.append((role, sanitize_text(text, max_chars)))
+    return messages
+
+
+def extract_session_messages(path: Path, max_chars: int) -> List[Tuple[str, str]]:
+    entries: List[dict] = []
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            for line in handle:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entries.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        return []
+
+    event_messages = extract_messages_from_event_entries(entries, max_chars)
+    if event_messages:
+        return event_messages
+    return extract_messages_from_response_items(entries, max_chars)
+
+
+def delete_matching_files(root: Path, predicate) -> int:
+    if not root.exists() or not root.is_dir():
+        return 0
+
+    deleted_count = 0
+    for path in root.rglob("*.jsonl"):
+        if not predicate(path):
+            continue
+        try:
+            path.unlink()
+        except OSError:
+            continue
+        deleted_count += 1
+    return deleted_count
+
+
+def path_is_same_or_nested(path: Path, root: Optional[Path]) -> bool:
+    if root is None:
+        return False
+    try:
+        path.resolve().relative_to(root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def cleanup_session_history(
+    sessions_dir: Path,
+    archived_sessions_dir: Path,
+    retention_cutoff_utc: datetime,
+) -> Tuple[int, int]:
+    sessions_root = sessions_dir.resolve() if sessions_dir.exists() else None
+    removed_old_sessions = delete_matching_files(
+        sessions_dir,
+        lambda path: (
+            (timestamp := read_session_timestamp(path)) is not None
+            and timestamp < retention_cutoff_utc
+        ),
+    )
+    removed_archived_sessions = delete_matching_files(
+        archived_sessions_dir,
+        lambda path: not path_is_same_or_nested(path, sessions_root),
+    )
+    return removed_old_sessions, removed_archived_sessions
+
+
+def render_text_output(
+    records: Sequence[SessionRecord],
+    lookback_minutes: int,
+    max_message_chars: int,
+    removed_old_sessions: int,
+    removed_archived_sessions: int,
+) -> str:
+    if not records:
+        return "NO_RECENT_CONVERSATIONS"
+
+    lines: List[str] = [
+        f"RECENT_CONVERSATIONS_FOUND={len(records)}",
+        f"LOOKBACK_MINUTES={lookback_minutes}",
+        "ARCHIVED_SESSIONS_INCLUDED=true",
+        f"CLEANUP_REMOVED_OLD_SESSIONS={removed_old_sessions}",
+        f"CLEANUP_REMOVED_ARCHIVED_SESSIONS={removed_archived_sessions}",
+    ]
+
+    for index, record in enumerate(records, start=1):
+        lines.append(f"=== SESSION {index} ===")
+        lines.append(f"TIMESTAMP_UTC={record.timestamp_utc.isoformat()}")
+        lines.append(f"FILE={record.path}")
+
+        messages = record.messages
+        if messages is None:
+            messages = extract_session_messages(record.path, max_message_chars)
+        if not messages:
+            lines.append("MESSAGES=NONE")
+            continue
+
+        for role, message in messages:
+            tag = "USER" if role == "user" else "ASSISTANT"
+            lines.append(f"[{tag}]")
+            lines.append(message)
+            lines.append(f"[/{tag}]")
+
+    return "\n".join(lines)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Extract the latest conversation history from Codex session stores",
+    )
+    parser.add_argument(
+        "--sessions-dir",
+        default="~/.codex/sessions",
+        help="Path to the Codex sessions directory (default: ~/.codex/sessions)",
+    )
+    parser.add_argument(
+        "--archived-sessions-dir",
+        default="~/.codex/archived_sessions",
+        help="Path to archived Codex sessions (default: ~/.codex/archived_sessions)",
+    )
+    parser.add_argument(
+        "--lookback-minutes",
+        type=int,
+        default=DEFAULT_LOOKBACK_MINUTES,
+        help=f"How far back to look for sessions (default: {DEFAULT_LOOKBACK_MINUTES})",
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        help="Maximum number of sessions to return (default: all within lookback window)",
+    )
+    parser.add_argument(
+        "--max-message-chars",
+        type=int,
+        default=1600,
+        help="Maximum characters per extracted message (default: 1600)",
+    )
+    parser.add_argument(
+        "--retention-days",
+        type=int,
+        default=DEFAULT_RETENTION_DAYS,
+        help=f"Delete sessions older than this many days after reading (default: {DEFAULT_RETENTION_DAYS})",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    sessions_dir = Path(args.sessions_dir).expanduser().resolve()
+    archived_sessions_dir = Path(args.archived_sessions_dir).expanduser().resolve()
+    lookback_minutes = max(args.lookback_minutes, 1)
+    limit = args.limit if args.limit is not None and args.limit > 0 else None
+    max_message_chars = max(args.max_message_chars, 100)
+    retention_days = max(args.retention_days, 1)
+    now_utc = datetime.now(timezone.utc)
+
+    if (
+        (not sessions_dir.exists() or not sessions_dir.is_dir())
+        and (not archived_sessions_dir.exists() or not archived_sessions_dir.is_dir())
+    ):
+        print("NO_RECENT_CONVERSATIONS")
+        return 0
+
+    cutoff_utc = now_utc - timedelta(minutes=lookback_minutes)
+    recent_records = find_recent_sessions((sessions_dir, archived_sessions_dir), cutoff_utc, limit)
+    for record in recent_records:
+        record.messages = extract_session_messages(record.path, max_message_chars)
+
+    retention_cutoff_utc = now_utc - timedelta(days=retention_days)
+    removed_old_sessions, removed_archived_sessions = cleanup_session_history(
+        sessions_dir,
+        archived_sessions_dir,
+        retention_cutoff_utc,
+    )
+
+    print(
+        render_text_output(
+            recent_records,
+            lookback_minutes,
+            max_message_chars,
+            removed_old_sessions,
+            removed_archived_sessions,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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/README.md

@@ -4,16 +4,14 @@ 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
+- 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`
-- Distinguishes official Codex requirements from this repository's house rules
 - Keeps tightly coupled serial work in the main agent
 
 ## Project Structure
@@ -26,7 +24,6 @@ The workflow is grounded in OpenAI's Codex subagent docs and then adds a few hou
 ├── agents/
 │   └── openai.yaml
 └── references/
-    ├── openai-codex-subagents.md
     ├── custom-agent-template.toml
     └── routing-rubric.md
 ```
@@ -35,7 +32,7 @@ The workflow is grounded in OpenAI's Codex subagent docs and then adds a few hou
 
 - Codex app or CLI with subagent support
 - Write access to `~/.codex/agents`
-- Current OpenAI Codex custom-agent format support
+- Custom agent TOML format support
 
 ## License
 

package/codex-subagent-orchestration/SKILL.md

@@ -8,39 +8,34 @@ description: Use for almost every non-trivial Codex task. Inspect existing custo
 ## 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.
+- 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, 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.
+- 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.
 
-The official OpenAI basis for this skill is summarized in `references/openai-codex-subagents.md`.
-
-Follow the current OpenAI Codex custom-agent format:
+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 two house rules on top of the official schema:
+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`
 
-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:
@@ -57,11 +52,9 @@ Set `model_reasoning_effort` by task complexity:
 
 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:
+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
@@ -75,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.
-- Remember that Codex does not spawn subagents automatically; the orchestration decision must be explicit.
+- 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
 
@@ -154,6 +151,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
 
@@ -170,9 +168,11 @@ Avoid combining exploration, review, and editing into one reusable agent when th
 
 ### 7) Orchestrate the run
 
-- Tell Codex 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:
 
@@ -183,6 +183,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
 
@@ -210,5 +211,4 @@ If the task turns into one tightly coupled stream of work, stop delegating new e
 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

@@ -1,6 +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`."
+  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/routing-rubric.md

@@ -18,8 +18,6 @@ Keep the task in the main agent when it is:
 - 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:
@@ -80,7 +78,7 @@ Every subagent handoff should include:
 - `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.
+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
 

package/package.json

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

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

@@ -1,41 +0,0 @@
-# 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.