# Codex Integration

Protocol for Codex integration across forge skills. Skills that support Codex add a `### Codex Integration` block to their SKILL.md and follow this protocol for detection, consent, invocation, and presentation. Skills without a Codex block are unaffected. Users without Codex installed never see any Codex-related prompts. The consent flow handles user choice — skills always route to it.

## Modes

| Mode | Purpose | Who does the work | Risk |
|------|---------|-------------------|------|
| **Verify** | Codex reviews Claude's work | Claude works, Codex checks | Low — additive |
| **Takeover** | Codex does the work, Claude reviews | Codex works, Claude checks | Medium — saves tokens |
| **Delegate** | Codex executes the work independently — no Claude execution. Codex's output then enters the normal review pipeline (quality-code-review on the PR). | Codex works alone, then artifacts go through Claude review | Higher — build skills only (scaffold, tdd) |

13 skills support both **Verify** and **Takeover**. 2 build skills use **Delegate**. The consent flow lets the user choose between Verify and Takeover per invocation, or save a preference.

## Detection

Run `codex --version` in a subshell. If exit code is 0, Codex is available. If non-zero, skip all Codex steps silently.

- Detection runs at the point where a skill would invoke Codex, not at session start.
- Do not cache the result across skill invocations.
- Do not warn about Codex not being installed. Users who don't have it never see it.

## Consent

User preferences stored in `.forge/local.yaml` (gitignored, per-user):

```yaml
codex:
  mode: ask         # verify | takeover | ask | never  (default: ask)  — applies to Verify/Takeover skills
  delegate: ask     # always | ask | never             (default: ask)  — applies to Delegate build skills only
```

`codex.mode` is the shared key for Verify/Takeover skills (13 skills). `codex.delegate` is a separate key used only by build-tdd and build-scaffold. Keeping them separate prevents a `delegate` value from leaking into non-build skills whose mode check only handles Verify/Takeover/Skip.

**Consent flow:**

**Run consent ONCE per skill invocation**, at the Codex Mode Check step. Record the resulting mode (verify / takeover / skip) in skill-local state. Later inline Codex steps in the same skill MUST reuse that decision — do not re-prompt or re-run the consent flow.

1. Detect Codex (`codex --version`). If unavailable, record `skip` and proceed without Codex.
2. Read `.forge/local.yaml` for the `codex.mode` preference.
3. If `verify` or `takeover` — record that mode and proceed.
4. If `never` — record `skip` and proceed silently.
5. If `ask` or file/key is absent — prompt the user:

```
Codex is available for [skill description].
  (a) Claude does the work, Codex verifies
  (b) Codex does the work, Claude reviews  (saves tokens)
  (c) Skip Codex
  (d) Save my preference — always use [a|b|c]
```

Option (a) = Verify mode. Option (b) = Takeover mode. Option (c) = skip.

6. If user picks (d), write the choice to `.forge/local.yaml`.
7. For **Delegate** mode (build-tdd, build-scaffold only): the skill reads `codex.delegate` (not `codex.mode`) and handles its own consent flow — see the skill's Codex Integration section. If a non-build skill ever reads `codex.mode` and finds an unexpected value (e.g., `delegate`), treat it as `ask` and re-prompt.

**First-use setup:**

- If `.forge/local.yaml` does not exist, create it with `codex.mode: ask`.
- If `.gitignore` does not contain `.forge/local.yaml`, append it.

## Invocation

Codex is invoked via the existing Codex plugin runtime. Three commands are available — use the one that fits the skill's needs:

| Command | When to Use | Supports |
|---------|-------------|----------|
| `adversarial-review` | Reviewing **code in git** — challenges approach, finds gaps | `--scope`, `--base`, custom focus text |
| `review` | Reviewing **code in git** — standard defect finding | `--scope`, `--base`, no custom focus |
| `task` | Reviewing **documents/artifacts** or **building code** | Arbitrary prompt, any files |

**Command selection per skill type:**
- **Quality skills reviewing code diffs** (code-review, security-audit): Use `adversarial-review --scope branch` with focus text. Auto-scopes to git state — no need to manually point at files.
- **Plan/discover skills reviewing documents**: Use `task` with a custom prompt. Design artifacts and analyses aren't in git state.
- **Build skills delegating work**: Use `task` with the skill's SKILL.md path as methodology.
- **Debug/support skills**: Use `task` with custom prompt for hypothesis generation.

**Verify template (for `task` command):**
```
Context: [artifact file paths — Codex reads files, not inline content]
Task: [what Codex should do — review, critique, analyze]
Focus: [specific concerns — gaps, security, feasibility, coverage]
Output format: [structured findings with severity, location, and reasoning]
```

**Adversarial review invocation (for code-reviewing skills):**
```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" adversarial-review --scope branch [focus text]
```

**Delegate template (for `task` command):**
```
Context: [artifact file paths — task spec, architecture artifacts]
Task: [what Codex should build]
Methodology: [path to the skill's SKILL.md file — Codex reads and follows it]
Output format: [implementation code following the skill's methodology]
```

**Rules:**

- Pass file paths, not inline content. Codex reads current files.
- Exception: skills at pre-artifact stages (e.g., brainstorming before a spec is written) may write a temp draft file for Codex context. Delete the temp file after the step completes.
- Each skill defines its own prompt specifics. This section defines the template structure only.
- Timeout: 5 minutes for verify mode, 10 minutes for delegate mode.

## Presentation

**Verify mode** — present a unified view:

```markdown
## Claude's Analysis
[Claude's existing findings from the skill's normal process]

## Codex's Analysis
[Codex findings, structured with severity and location]

## Disagreements
[Where they differ, with reasoning from each side]
[If no disagreements: "Claude and Codex agree on all findings."]

## Resolution
User decides. The existing quality gate makes the final call.
```

**Delegate mode** — no dual presentation. Codex produced the artifact. It goes through forge's standard quality gates (tests pass, coverage meets threshold, code review by Claude).

## Error Handling

- **Codex invocation fails** (timeout, auth error, runtime crash): Log the error. Present Claude's findings only. Note: "Codex was unavailable for this step."
- **Codex returns empty or malformed output:** Treat as unavailable. Present Claude's findings only.
- **`.forge/local.yaml` is corrupted:** Reset to `codex.mode: ask`. Warn user.
- **Codex failure NEVER blocks the workflow.** Every Codex step is optional. The skill's normal process completes regardless.

## Model Selection

This protocol does not specify which Codex model to use. The Codex plugin handles model selection via its own configuration. Forge defers to the plugin's defaults.

## Constraints

1. This protocol does NOT manage Codex installation, authentication, or updates. The Codex plugin owns its own lifecycle.
2. This protocol does NOT auto-suggest switching to Codex based on token usage or session length. The user initiates Codex usage.
3. This protocol works unchanged if more skills opt in later. Skill names that appear above (build-tdd, build-scaffold, code-review, security-audit) are illustrative — they show how the protocol is currently consumed, not a closed set.

## Version Compatibility

Tested with: Codex CLI v?.? (commit pinned). Update this section when bumping CLI version.

- Minimum Codex CLI: unpinned for now — relies on whatever ships in the Codex plugin currently installed in the user's harness.
- Pinned commit: TODO — record the Codex CLI commit SHA the protocol was validated against once the Codex plugin is versioned in this repo.
- Breaking-change notes: when Codex CLI changes the `adversarial-review` / `review` / `task` command surface or output structure, update this protocol's Invocation section and bump the recorded commit.