Add Codex runtime support and dual-runtime migration path

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to System2 are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Codex runtime pack under `codex/`:
+  - `codex/templates/AGENTS.md` orchestrator template.
+  - `codex/skills/init/SKILL.md` (`system2-init`) to bootstrap `AGENTS.md`.
+  - `codex/runtime/agent-registry.json` mapping System2 roles to Codex sub-agent types.
+  - `codex/tools/validate_paths.py` for allowlist-backed write validation.
+  - `codex/install.sh` installer as the Codex alternative to Claude marketplace/plugin install.
+- Codex runtime docs in `codex/README.md`.
+- Codex-specific eval harness and golden schemas in `evals/run_codex_evals.py` and `evals/goldens/codex_*.json`.
+- Migration guide for Claude-only to dual runtime adoption in `docs/MIGRATION_CLAUDE_TO_DUAL_RUNTIME.md`.
+- Dual-runtime execution mode feature design in `docs/DUAL_RUNTIME_EXECUTION_MODES.md`.
+
+### Changed
+
+- `README.md` now documents dual runtime support (Claude Code + Codex) and Codex installation/update flow.
+- `codex/install.sh` now enables `multi_agent` during install.
+
 ## [0.2.0] - 2026-02-16
 
 Remove Roo Code support and convert to Claude Code plugin with marketplace distribution.

README.md

@@ -1,6 +1,6 @@
 # System2 - Multi-Agent Engineering Workflows
 
-A framework for **deliberate, spec-driven, verification-first** software engineering with AI assistance.
+A framework for **deliberate, spec-driven, verification-first** software engineering with AI assistance across Claude Code and Codex runtimes.
 
 ## What is System2?
 
@@ -14,6 +14,8 @@ The name comes from Daniel Kahneman's dual-process theory: **System 1** is fast
 
 Claude Code uses **subagents** defined as Markdown files with YAML frontmatter. The main conversation acts as the **orchestrator**, delegating specialist work to purpose-built subagents.
 
+Codex uses **spawned sub-agents** coordinated by `AGENTS.md` instructions plus a System2 runtime pack (`codex/`) that provides initialization and policy tooling.
+
 ## Core Concepts
 
 ### Specialized Agents
@@ -62,6 +64,15 @@ These artifacts serve as the contract between planning and execution.
 
 ## Installation
 
+### Supported Runtimes
+
+- **Claude Code runtime**: plugin + marketplace distribution (`.claude-plugin/`, `plugin/`)
+- **Codex runtime**: local runtime pack installer (`codex/install.sh`) and `system2-init` skill
+
+Choose the installation flow for your runtime.
+
+### Claude Code Installation
+
 ### Step 1: Add the System2 Marketplace
 
 ```
@@ -101,9 +112,43 @@ To overwrite an existing CLAUDE.md:
 /system2:init --force
 ```
 
+### Codex Installation (Marketplace Alternative)
+
+Codex does not use Claude plugin marketplace manifests. The System2 equivalent is a local runtime pack installer.
+
+### Step 1: Install the Codex Runtime Pack
+
+```bash
+./codex/install.sh
+```
+
+Dry run:
+
+```bash
+./codex/install.sh --dry-run
+```
+
+### Step 2: Multi-Agent Runtime Configuration
+
+```bash
+codex features enable multi_agent
+```
+
+`./codex/install.sh` runs this automatically as part of installation.
+
+Optional: merge settings from `codex/config.toml.example` into `~/.codex/config.toml`.
+
+### Step 3: Initialize AGENTS.md
+
+In your project session, ask Codex to run the `system2-init` skill.
+This writes the System2 orchestrator instructions to `AGENTS.md` in your project root.
+
+To overwrite an existing file, run with `--force`.
+
 ## Updating
 
-System2 updates are handled by the Claude Code plugin system. No manual update commands are needed.
+For Claude Code, updates are handled by the plugin system.  
+For Codex, re-run `./codex/install.sh` to refresh the installed runtime pack.
 
 To check plugin status:
 
@@ -126,11 +171,23 @@ If you previously installed System2 by copying files manually, remove the old fi
 
 After cleanup, follow the Installation steps above.
 
+## Migrating from Claude-Only to Dual Runtime
+
+For teams that already run System2 on Claude and want to add Codex in parallel, use the migration guide:
+
+- [docs/MIGRATION_CLAUDE_TO_DUAL_RUNTIME.md](docs/MIGRATION_CLAUDE_TO_DUAL_RUNTIME.md)
+
+## Dual-Runtime Execution Modes
+
+Feature design for token-window-aware cross-runtime scheduling and post-design mirror adjudication:
+
+- [docs/DUAL_RUNTIME_EXECUTION_MODES.md](docs/DUAL_RUNTIME_EXECUTION_MODES.md)
+
 ## Usage
 
 ### Basic Workflow
 
-With `CLAUDE.md` in place, Claude Code acts as the orchestrator. At session start, it assesses the spec artifact state:
+With `CLAUDE.md` (Claude) or `AGENTS.md` (Codex) in place, the orchestrator assesses the spec artifact state at session start:
 
 ```
 You: Build a user authentication system

codex/README.md

@@ -0,0 +1,41 @@
+# System2 for Codex
+
+This directory is the Codex runtime port of System2.
+
+## What it provides
+
+- `templates/AGENTS.md`: Codex orchestrator template (System2 gate workflow)
+- `skills/init/SKILL.md`: `system2-init` skill to bootstrap `AGENTS.md`
+- `runtime/agent-registry.json`: role map from System2 agents to Codex sub-agent types
+- `tools/validate_paths.py`: allowlist validator for write-restricted roles
+- `config.toml.example`: optional Codex feature/profile baseline
+- `install.sh`: local installer (marketplace alternative)
+
+## Install
+
+```bash
+./codex/install.sh
+```
+
+Dry run:
+
+```bash
+./codex/install.sh --dry-run
+```
+
+Custom Codex home:
+
+```bash
+./codex/install.sh --codex-home /path/to/.codex
+```
+
+## Use
+
+1. Install enables multi-agent mode automatically by running:
+
+```bash
+codex features enable multi_agent
+```
+
+2. In your target project, ask Codex to use `system2-init`.
+3. Follow the generated `AGENTS.md` gate workflow.

codex/config.toml.example

@@ -0,0 +1,10 @@
+# Example Codex config for System2 workflows.
+# Merge into ~/.codex/config.toml as needed.
+
+[features]
+multi_agent = true
+shell_snapshot = true
+apps = true
+
+[profiles.system2]
+model_reasoning_effort = "high"

codex/install.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DRY_RUN=0
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --codex-home)
+      CODEX_HOME="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      echo "Usage: ./codex/install.sh [--dry-run] [--codex-home <path>]" >&2
+      exit 1
+      ;;
+  esac
+done
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGET_ROOT="$CODEX_HOME/skills/system2"
+
+run_or_echo() {
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    echo "[dry-run] $*"
+  else
+    eval "$@"
+  fi
+}
+
+echo "Installing System2 Codex runtime"
+echo "Source: $SCRIPT_DIR"
+echo "Target: $TARGET_ROOT"
+
+run_or_echo "mkdir -p \"$TARGET_ROOT/skills/init\" \"$TARGET_ROOT/runtime\" \"$TARGET_ROOT/templates\" \"$TARGET_ROOT/tools\""
+run_or_echo "cp \"$SCRIPT_DIR/manifest.json\" \"$TARGET_ROOT/manifest.json\""
+run_or_echo "cp \"$SCRIPT_DIR/config.toml.example\" \"$TARGET_ROOT/config.toml.example\""
+run_or_echo "cp \"$SCRIPT_DIR/runtime/agent-registry.json\" \"$TARGET_ROOT/runtime/agent-registry.json\""
+run_or_echo "cp \"$SCRIPT_DIR/templates/AGENTS.md\" \"$TARGET_ROOT/templates/AGENTS.md\""
+run_or_echo "cp \"$SCRIPT_DIR/skills/init/SKILL.md\" \"$TARGET_ROOT/skills/init/SKILL.md\""
+run_or_echo "cp \"$SCRIPT_DIR/tools/validate_paths.py\" \"$TARGET_ROOT/tools/validate_paths.py\""
+run_or_echo "chmod +x \"$TARGET_ROOT/tools/validate_paths.py\""
+run_or_echo "CODEX_HOME=\"$CODEX_HOME\" codex features enable multi_agent"
+
+echo
+echo "Install complete."
+echo "Next steps:"
+echo "1) In your project, run the skill by prompting: use system2-init"
+echo "2) Review the generated AGENTS.md and start at Gate 0 scope definition"

codex/manifest.json

@@ -0,0 +1,21 @@
+{
+  "name": "system2-codex",
+  "version": "0.2.0",
+  "description": "Codex runtime pack for System2 spec-driven multi-agent workflows.",
+  "repository": "https://github.com/jamesnordlund/System2",
+  "license": "MIT",
+  "runtime": "codex",
+  "entrypoints": {
+    "init_skill": "./skills/init/SKILL.md",
+    "orchestrator_template": "./templates/AGENTS.md",
+    "agent_registry": "./runtime/agent-registry.json",
+    "path_validator": "./tools/validate_paths.py",
+    "installer": "./install.sh",
+    "config_example": "./config.toml.example"
+  },
+  "install": {
+    "target_skill_dir": "$CODEX_HOME/skills/system2",
+    "supports_dry_run": true,
+    "idempotent": true
+  }
+}

codex/runtime/agent-registry.json

@@ -0,0 +1,83 @@
+{
+  "description": "System2 role mapping for Codex runtime. Uses Claude plugin agent prompts as source-of-truth role definitions with Codex execution metadata.",
+  "version": "0.2.0",
+  "agents": [
+    {
+      "name": "repo-governor",
+      "codex_agent_type": "explorer",
+      "source_prompt": "plugin/agents/repo-governor.md",
+      "write_allowlist": "plugin/allowlists/repo-governor.regex"
+    },
+    {
+      "name": "spec-coordinator",
+      "codex_agent_type": "default",
+      "source_prompt": "plugin/agents/spec-coordinator.md",
+      "write_allowlist": "plugin/allowlists/spec-context.regex"
+    },
+    {
+      "name": "requirements-engineer",
+      "codex_agent_type": "default",
+      "source_prompt": "plugin/agents/requirements-engineer.md",
+      "write_allowlist": "plugin/allowlists/spec-requirements.regex"
+    },
+    {
+      "name": "design-architect",
+      "codex_agent_type": "default",
+      "source_prompt": "plugin/agents/design-architect.md",
+      "write_allowlist": "plugin/allowlists/spec-design.regex"
+    },
+    {
+      "name": "task-planner",
+      "codex_agent_type": "default",
+      "source_prompt": "plugin/agents/task-planner.md",
+      "write_allowlist": "plugin/allowlists/spec-tasks.regex"
+    },
+    {
+      "name": "executor",
+      "codex_agent_type": "worker",
+      "source_prompt": "plugin/agents/executor.md",
+      "write_allowlist": "plugin/allowlists/executor.regex"
+    },
+    {
+      "name": "test-engineer",
+      "codex_agent_type": "worker",
+      "source_prompt": "plugin/agents/test-engineer.md",
+      "write_allowlist": "plugin/allowlists/test-engineer.regex"
+    },
+    {
+      "name": "security-sentinel",
+      "codex_agent_type": "explorer",
+      "source_prompt": "plugin/agents/security-sentinel.md",
+      "write_allowlist": "plugin/allowlists/spec-security.regex"
+    },
+    {
+      "name": "eval-engineer",
+      "codex_agent_type": "worker",
+      "source_prompt": "plugin/agents/eval-engineer.md",
+      "write_allowlist": "plugin/allowlists/spec-evals.regex"
+    },
+    {
+      "name": "docs-release",
+      "codex_agent_type": "worker",
+      "source_prompt": "plugin/agents/docs-release.md",
+      "write_allowlist": "plugin/allowlists/docs-release.regex"
+    },
+    {
+      "name": "code-reviewer",
+      "codex_agent_type": "explorer",
+      "source_prompt": "plugin/agents/code-reviewer.md"
+    },
+    {
+      "name": "postmortem-scribe",
+      "codex_agent_type": "default",
+      "source_prompt": "plugin/agents/postmortem-scribe.md",
+      "write_allowlist": "plugin/allowlists/postmortems.regex"
+    },
+    {
+      "name": "mcp-toolsmith",
+      "codex_agent_type": "worker",
+      "source_prompt": "plugin/agents/mcp-toolsmith.md",
+      "write_allowlist": "plugin/allowlists/mcp.regex"
+    }
+  ]
+}