# Codex Migration Guide

## Purpose

This repository was converted from a Claude-oriented Harness template into a Codex-oriented template.

## Mapping

| Claude surface | Codex surface | Repository path |
|---|---|---|
| `CLAUDE.md` | persistent repo instructions | `AGENTS.md` |
| `.claude/commands/*.md` | repo skills | `.agents/skills/*/SKILL.md` |
| Claude sub-agents | project-scoped custom agents | `.codex/agents/*.toml` |
| `.claude/settings.json` hooks | Codex hooks | `.codex/hooks.json` |
| `claude -p` automation | `codex exec` automation | `scripts/execute.py` |
| ad hoc slash commands | optional plugin command layer | `plugins/harness-engineering/commands/` |

## Repository surfaces

### `AGENTS.md`

Codex loads `AGENTS.md` as the persistent instruction file for the repository.

Use it for:

- project-level rules
- architecture constraints
- workflow expectations
- validation commands

### `.agents/skills/`

Repo skills are the primary reusable workflow layer.

- `harness-workflow`: plan phases and generate `phases/` files
- `harness-review`: review changes against Harness docs and rules

These are automatically discoverable by Codex in this repository.

### `.codex/agents/`

Custom agents are defined as standalone TOML files.

- `phase_planner`: read-heavy planner for decomposing work into steps
- `harness_reviewer`: read-only reviewer for architecture and test compliance

Use these only when the user explicitly asks Codex to fan out work across subagents.

### `.codex/hooks.json`

As of 2026-04-15, Codex documents hooks as experimental and disabled on native Windows.

This repo still ships hook definitions because they work on macOS, Linux, and WSL once `codex_hooks` is enabled. On native Windows, use `python scripts/validate_workspace.py` manually or through `scripts/execute.py`.

### `plugins/harness-engineering/`

This is an optional repo-local plugin that exposes Harness slash-command prompts through the local marketplace.

Install path:

1. Restart Codex.
2. Open `/plugins`.
3. Choose the local marketplace `Local Harness Engineering`.
4. Install `harness-engineering`.

## Automation

`scripts/execute.py` now calls `codex exec` instead of `claude -p`.

Execution model:

- inject `AGENTS.md` and `docs/*.md` into each step prompt
- run steps in order
- retry failed steps up to 3 times with prior error feedback
- persist step outputs under `phases/{phase}/stepN-output.json`
- create code and metadata commits after successful steps

## Validation

`python scripts/validate_workspace.py` is the repo-level fallback validator.

- If `package.json` exists, it auto-runs available `npm run lint`, `npm run build`, and `npm run test`.
- If the project needs another validation chain, set `HARNESS_VALIDATION_COMMANDS` to newline-separated commands.