diff --git a/docs/CODEX.md b/docs/CODEX.md deleted file mode 100644 index 42d03a1..0000000 --- a/docs/CODEX.md +++ /dev/null @@ -1,83 +0,0 @@ -# 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.