feat(codex): add portable subagent pack

README.md

@@ -49,11 +49,55 @@ Or validate already committed branch work:
 /no-mistakes
 ```
 
-Create the agent-specific forwarding files:
+Install the shared Codex subagent definitions and instruction forwarders:
 
 ```sh
-mkdir -p ~/.codex ~/.claude ~/.gemini
-printf '@~/.agents/AGENTS.md\n@~/.agents/instructions/subagents.md\n' > ~/.codex/AGENTS.md
+~/.agents/scripts/install-codex.sh
+```
+
+The installer uses `$CODEX_HOME` when set and otherwise defaults to `~/.codex`. It copies these portable definitions
+into that Codex home's `agents/` directory:
+
+| Agent | Purpose | Default configuration |
+| --- | --- | --- |
+| `explorer` | Targeted repository exploration | Read-only; inherits the configured child model and effort |
+| `worker` | Bounded implementation and verification | Workspace-write; inherits the configured child model and effort |
+| `docs_researcher` | OpenAI Docs and optional Context7 research | `gpt-5.6-sol`, medium, read-only |
+| `bulk_scout` | Large-file, log, or repository-partition scans | `gpt-5.6-terra`, medium, read-only |
+| `reviewer` | Correctness, security, regression, and test review | `gpt-5.6-sol`, high, read-only |
+
+It preserves other files in `agents/` and follows Codex's global instruction precedence: when the selected home has a
+non-empty `AGENTS.override.md`, it appends missing loader directives there; otherwise it preserves or creates
+`AGENTS.md`. The installed directive loads `~/.agents/codex/AGENTS.md`, whose opening references mirror a normal Codex
+forwarder: `~/.agents/AGENTS.md`, the portable Codex RTK rules, shared Context7 research guidance, and shared delegation
+guidance, followed by the Codex-specific routing rules. The installer does not read or modify `config.toml` in that
+Codex home. The pack contains no credentials. Configure Context7 separately in your own Codex configuration if
+`docs_researcher` should use it; the agent inherits that server configuration.
+
+Current Codex releases enable subagents by default. To reproduce this repository's bounded child defaults and
+three-child cap, merge the following settings into the selected Codex home's `config.toml` (normally
+`~/.codex/config.toml`) without duplicating an existing table:
+
+```toml
+[agents]
+enabled = true
+max_concurrent_threads_per_session = 3
+default_subagent_model = "gpt-5.6-sol"
+default_subagent_reasoning_effort = "medium"
+interrupt_message = true
+
+[features]
+multi_agent = true
+multi_agent_v2 = false
+```
+
+`fork_turns` is selected at spawn time rather than in `config.toml`. The Codex-specific instructions direct agents to
+pass `fork_turns="none"` for ordinary delegation and provide a self-contained task capsule.
+
+For other agent tools, create their forwarding files separately:
+
+```sh
+mkdir -p ~/.claude ~/.gemini
 printf '@~/.agents/AGENTS.md\n' > ~/.claude/CLAUDE.md
 printf '@~/.agents/AGENTS.md\n' > ~/.gemini/GEMINI.md
 ```
@@ -69,22 +113,41 @@ printf '@~/.agents/AGENTS.md\n' > /path/to/tool/instructions-file.md
 ## Repository Files
 
 - `AGENTS.md` - global entry point and router for topic-specific instructions.
+- `codex/AGENTS.md` - portable global, RTK, research, and delegation references plus Codex-specific role routing and
+  bounded-context guidance.
+- `codex/RTK.md` - portable Codex CLI rules for token-optimized shell output.
+- `codex/agents/` - portable custom-agent definitions installed into the selected Codex home's `agents/` directory.
 - `instructions/` - focused guidance loaded only when the task matches the topic.
+- `scripts/install-codex.sh` - idempotent Codex agent and instruction-forwarder installer.
 
 ## Verify
 
-Check that each forwarding file references the global entry point:
+With the default Codex home, inspect the active Codex global instruction file and the other forwarding files:
 
 ```sh
-cat ~/.codex/AGENTS.md
+if [ -s ~/.codex/AGENTS.override.md ]; then
+  cat ~/.codex/AGENTS.override.md
+else
+  cat ~/.codex/AGENTS.md
+fi
 cat ~/.claude/CLAUDE.md
 cat ~/.gemini/GEMINI.md
 ```
 
-Each command should include:
+The Codex active file should load:
 
 ```text
-@~/.agents/AGENTS.md
+~/.agents/codex/AGENTS.md
+```
+
+That file begins with references to `~/.agents/AGENTS.md`, `~/.agents/codex/RTK.md`,
+`~/.agents/instructions/research.md`, and `~/.agents/instructions/subagents.md`, then directs ordinary Codex delegations
+to use `fork_turns="none"`. Other tool forwarders should include the shared `~/.agents/AGENTS.md` entry point.
+
+Confirm that Codex can discover the shared roles:
+
+```sh
+ls ~/.codex/agents/{explorer,worker,docs_researcher,bulk_scout,reviewer}.toml
 ```
 
 Check that `no-mistakes` prerequisites are available:

codex/AGENTS.md

@@ -0,0 +1,36 @@
+@~/.agents/AGENTS.md
+@~/.agents/codex/RTK.md
+@~/.agents/instructions/research.md
+@~/.agents/instructions/subagents.md
+
+# Codex Subagent Defaults
+
+Apply these Codex-specific rules together with the shared delegation guidance in
+`~/.agents/instructions/subagents.md`.
+
+## Context and Task Capsules
+
+- Ordinary delegations must use `fork_turns="none"` and a self-contained, bounded task capsule.
+- Include the objective, exact repository or file scope, relevant decisions, constraints, deliverable, and focused
+  verification requirements. Exclude unrelated conversation history and raw exploration logs.
+- Use `fork_turns="2"` only when the latest clarification or failure is essential to the task. Use `fork_turns="all"`
+  only when the complete decision history is indispensable; full-history forks inherit the parent model and effort.
+
+## Routing
+
+Use these defaults when the Codex surface exposes the corresponding role and model controls:
+
+| Task | Role | Model | Effort |
+| --- | --- | --- | --- |
+| Targeted repository exploration | `explorer` | `gpt-5.6-sol` | medium |
+| Bounded implementation and verification | `worker` | `gpt-5.6-sol` | medium |
+| OpenAI or library documentation research | `docs_researcher` | `gpt-5.6-sol` | medium |
+| Large-file, log, or repository-partition scan | `bulk_scout` | `gpt-5.6-terra` | medium |
+| Correctness, security, regression, or test review | `reviewer` | `gpt-5.6-sol` | high |
+
+Keep complex or high-risk implementation with the primary agent unless one bounded `worker` task provides useful
+isolation. In that rare case, prefer `gpt-5.6-sol` with xhigh effort and the smallest sufficient context.
+
+If a Codex surface does not expose a named role, reproduce that role's responsibility in the task capsule and set the
+model and effort explicitly when supported. If it does not support bounded-history controls, provide the smallest
+available context and do not assume its context behavior matches another Codex surface.

codex/RTK.md

@@ -0,0 +1,32 @@
+# RTK - Rust Token Killer (Codex CLI)
+
+**Usage**: Token-optimized CLI proxy for shell commands.
+
+## Rule
+
+Always prefix shell commands with `rtk`.
+
+Examples:
+
+```bash
+rtk git status
+rtk cargo test
+rtk npm run build
+rtk pytest -q
+```
+
+## Meta Commands
+
+```bash
+rtk gain            # Token savings analytics
+rtk gain --history  # Recent command savings history
+rtk proxy <cmd>     # Run raw command without filtering
+```
+
+## Verification
+
+```bash
+rtk --version
+rtk gain
+which rtk
+```

codex/agents/bulk_scout.toml

@@ -0,0 +1,23 @@
+name = "bulk_scout"
+description = "Read-only high-volume scanner for large files, logs, and repository partitions."
+model = "gpt-5.6-terra"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+web_search = "disabled"
+include_apps_instructions = false
+developer_instructions = """
+Scan only the assigned files, logs, or repository partition.
+Collect evidence at high volume, deduplicate it, and return a concise summary with file and line references.
+Do not edit files, make final design decisions, use external integrations, paste raw scans, or delegate work.
+"""
+
+[features]
+apps = false
+browser_use = false
+computer_use = false
+image_generation = false
+in_app_browser = false
+multi_agent = false
+plugins = false
+remote_plugin = false
+tool_suggest = false

codex/agents/docs_researcher.toml

@@ -0,0 +1,29 @@
+name = "docs_researcher"
+description = "Read-only documentation researcher for OpenAI Developer Docs and an optional inherited Context7 server."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+web_search = "disabled"
+include_apps_instructions = false
+developer_instructions = """
+Use only OpenAI Developer Docs and an inherited Context7 MCP server, when configured, to verify current product, SDK, API, CLI, or framework behavior.
+Resolve Context7 library IDs before querying its documentation.
+Return concise findings with source links or exact documentation references. Do not edit files or delegate work.
+"""
+
+[features]
+apps = false
+browser_use = false
+computer_use = false
+image_generation = false
+in_app_browser = false
+multi_agent = false
+plugins = false
+remote_plugin = false
+shell_tool = false
+tool_suggest = false
+unified_exec = false
+
+[mcp_servers.openaiDeveloperDocs]
+url = "https://developers.openai.com/mcp"
+enabled = true

codex/agents/explorer.toml

@@ -0,0 +1,21 @@
+name = "explorer"
+description = "Read-only repository explorer for targeted evidence gathering."
+sandbox_mode = "read-only"
+web_search = "disabled"
+include_apps_instructions = false
+developer_instructions = """
+Explore only the repository and local files in the assigned scope.
+Trace concrete execution paths and return concise evidence with file and line references.
+Do not edit files, propose broad redesigns, use external integrations, paste raw logs, or delegate work.
+"""
+
+[features]
+apps = false
+browser_use = false
+computer_use = false
+image_generation = false
+in_app_browser = false
+multi_agent = false
+plugins = false
+remote_plugin = false
+tool_suggest = false

codex/agents/reviewer.toml

@@ -0,0 +1,23 @@
+name = "reviewer"
+description = "Read-only reviewer focused on correctness, security, regressions, and test coverage."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+web_search = "disabled"
+include_apps_instructions = false
+developer_instructions = """
+Review the assigned change like an owner.
+Prioritize correctness, security, behavior regressions, integration risks, and missing tests.
+Lead with actionable findings, cite exact files and lines, and do not edit files or delegate work.
+"""
+
+[features]
+apps = false
+browser_use = false
+computer_use = false
+image_generation = false
+in_app_browser = false
+multi_agent = false
+plugins = false
+remote_plugin = false
+tool_suggest = false

codex/agents/worker.toml

@@ -0,0 +1,21 @@
+name = "worker"
+description = "Workspace-scoped implementation agent for bounded code changes and verification."
+sandbox_mode = "workspace-write"
+web_search = "disabled"
+include_apps_instructions = false
+developer_instructions = """
+Implement only the assigned local change and verify it proportionately.
+Preserve unrelated work, keep the diff focused, and summarize changed files plus test results.
+Do not use external integrations, paste raw logs, or delegate work.
+"""
+
+[features]
+apps = false
+browser_use = false
+computer_use = false
+image_generation = false
+in_app_browser = false
+multi_agent = false
+plugins = false
+remote_plugin = false
+tool_suggest = false

instructions/git-and-pr.md

@@ -2,8 +2,10 @@ Use when branching, staging, committing, pushing, creating pull requests, or add
 
 - Follow repository conventions, keep commits focused, and stage only files that belong to the requested change.
 - Honor repository commit policies in every commit, including commits generated by automated fix or delivery steps.
-  When DCO is enforced, create each commit with `git commit --signoff` so its `Signed-off-by` trailer matches the
-  author. A cryptographic commit signature does not replace this trailer.
+  When DCO is enforced, pass `--signoff` when creating or amending every commit so its `Signed-off-by` trailer matches
+  the author. Before publishing, and again after each automated commit, verify the complete pull-request commit range.
+  If DCO fails, amend or rebase every unsigned commit with the matching sign-off; a later signed commit does not
+  remediate an earlier unsigned commit. A cryptographic commit signature does not replace this trailer.
 - Follow the repository's PR template and naming rules. When none exist, use
   `<ISSUEID|NOISSUE> - [<low|medium|high>] - <Title>`.
 - A fallback PR description should cover context, the change, validation, risk, and rollback.

instructions/subagents.md

@@ -31,26 +31,7 @@ non-overlapping task instead of waiting unnecessarily.
 - Assign non-overlapping responsibilities and, for implementation, non-overlapping file ownership whenever practical.
   Do not ask multiple agents to perform the same scan or edit the same files unless an independent comparison is the
   explicit purpose.
-- Default to the smallest useful context. Use `fork_turns="none"`; use `"2"` only when the latest clarification or
-  failure is essential, and `"all"` only when the complete decision history is indispensable.
 - Require concise summaries with file references and relevant failing lines, not raw logs or exploration transcripts.
 - The primary agent owns user intent, skill selection and instruction reading, integration, conflict resolution, final
   validation, and completion. Treat child output as evidence to verify, not as automatically accepted work.
 - Delegation does not reduce the completion standard in `instructions/workflow.md`.
-
-## Routing
-
-Use these defaults when the active tool exposes the corresponding roles and model controls:
-
-| Task | Role | Model and effort | `fork_turns` |
-| --- | --- | --- | --- |
-| Simple exploration | `explorer` | `gpt-5.6-sol`, `medium` | `"none"` |
-| Simple implementation | `worker` | `gpt-5.6-sol`, `medium` | `"none"` |
-| Documentation research | `docs_researcher` | `gpt-5.6-sol`, `medium` | `"none"` |
-| Large-file, log, or repository partition scan | `bulk_scout` | `gpt-5.6-terra`, `medium` | `"none"` |
-| Review, subtle debugging, or integration analysis | `reviewer` | `gpt-5.6-sol`, `high` | `"none"` or `"2"` |
-| Complex or high-risk implementation | Primary, or one bounded child | `gpt-5.6-sol`, `xhigh` | `"none"` or `"2"` |
-| Full decision-history dependency | Inherited/default | Inherit parent model and effort | `"all"` (rare) |
-
-If custom roles are unavailable, reproduce the role's responsibility in the task capsule and use explicit model and
-reasoning settings when the tool supports them. Do not assume all surfaces provide identical bounded-history behavior.

scripts/install-codex.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+
+set -eu
+
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)
+agents_repo_dir=$(CDPATH= cd -- "${script_dir}/.." && pwd -P)
+codex_target_dir=${CODEX_HOME:-"${HOME}/.codex"}
+codex_agents_dir="${codex_target_dir}/agents"
+
+if [ -s "${codex_target_dir}/AGENTS.override.md" ]; then
+  codex_instructions_file="${codex_target_dir}/AGENTS.override.md"
+else
+  codex_instructions_file="${codex_target_dir}/AGENTS.md"
+fi
+
+mkdir -p "${codex_agents_dir}"
+
+for agent_name in explorer worker docs_researcher bulk_scout reviewer; do
+  install -m 0644 \
+    "${agents_repo_dir}/codex/agents/${agent_name}.toml" \
+    "${codex_agents_dir}/${agent_name}.toml"
+done
+
+touch "${codex_instructions_file}"
+
+ensure_include() {
+  include_line=$1
+
+  if ! grep -Fqx "${include_line}" "${codex_instructions_file}"; then
+    if [ -s "${codex_instructions_file}" ]; then
+      printf '\n' >>"${codex_instructions_file}"
+    fi
+    printf '%s\n' "${include_line}" >>"${codex_instructions_file}"
+  fi
+}
+
+ensure_include 'Read and follow `~/.agents/codex/AGENTS.md` for Codex-specific subagent routing and context rules.'
+
+printf 'Installed five Codex agents in %s\n' "${codex_agents_dir}"
+printf 'Updated Codex instruction directives in %s\n' "${codex_instructions_file}"