Agentic-AI-Template/docs/CODEX.md

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.