---
name: scaffold-harness-codex
description: Scaffold, repair, or align a Codex-style project harness from the repository's real AGENTS.md and .codex/ configuration. Use this skill whenever a user asks for a Codex harness, .codex agents/config/rules, Codex role models, a Codex build guard, conversion from a Claude harness to Codex, or validation of whether .codex/ is actually effective. It creates or merges the Codex mirror without silently editing global ~/.codex/config.toml, and reports what Codex can and cannot enforce.
compatibility: Requires Read, Glob, Grep, Edit, Write, Bash; Python 3.11+ is optional for TOML validation.
---

# Scaffold Codex Harness

Create a faithful, repo-specific Codex harness. Treat the root `AGENTS.md` as the runtime instruction source and `.codex/` as a project-local Codex mirror/spec. Do not pretend that `.codex/` is automatically executed: Codex uses `AGENTS.md` for project instructions and `~/.codex/config.toml` for global runtime policy. Codex does not natively spawn the role files in `.codex/agents/`; those files describe a disciplined procedure unless an external runner consumes them.

## Boundary and safety

- Modify the target repository's Codex mirror only: `.codex/README.md`, `config.toml`, `rules.toml`, `agents/*.toml`, and `guard-build.sh` when needed.
- Do not modify `~/.codex/config.toml` automatically. Show a copyable runtime block and explain that global changes require separate user approval.
- Do not clobber existing `AGENTS.md`, `.codex/`, `.claude/`, rules, or guard scripts. Read first, preserve existing wording, and make narrow edits.
- Do not invent stack commands, paths, package managers, model IDs, gates, or invariants. If a fact cannot be established, write `{{VERIFY: ...}}` in the proposed artifact and list it in the final report.
- Never run publish commands, destructive cleanup, or a repository-wide formatter merely to scaffold guidance.

## Phase 1 — Inspect before editing

1. Read the root `AGENTS.md`. It is authoritative. If absent, stop and report the missing prerequisite rather than generating contradictory instructions.
2. Read `.codex/README.md`, `.codex/config.toml`, `.codex/rules.toml`, `.codex/guard-build.sh`, and every `.codex/agents/*.toml` that exists. Record missing files.
3. Inspect the repository's actual stack and architecture using indicator files, lockfiles, build scripts, project manifests, test configuration, and representative source directories. Use the existing `AGENTS.md` and `.codex/` claims only after checking that they match the repository.
4. If `.claude/` exists, read its catalog/context only to cross-check intent. Do not convert or overwrite it; the deliverable is Codex-only.
5. Check whether the current loop is `dispatcher` or `orchestrator` from `[loop]` and surrounding docs. Preserve that choice. If no choice exists, use `dispatcher` unless durable multi-session/auditable state is an explicit requirement; document the decision.
6. Inspect model evidence from user-provided IDs, existing config, or the active runner. Never replace a valid model with a guessed provider/model name.

## Phase 2 — Reconcile the design

Build a findings table before changing files:

| Area | Evidence | Decision | Risk/open item |
|---|---|---|---|
| Runtime | global config note and repo config | repo mirror vs global policy | global config is not changed |
| Stack/build | manifests and scripts | exact commands | unresolved commands use `{{VERIFY}}` |
| Loop | `[loop]`, agent files | preserve dispatcher/orchestrator | Codex native spawning limitation |
| Roles | agent tools/ownership | dispatcher/planner/developer/verifier | tool separation may be descriptive |
| Guard | existing script/config | merge and dry-run | missing patterns remain explicit |
| Invariants | AGENTS/config/source | G7 checks | never invent domain rules |

Keep the tool-separated contract:

- `dispatcher`: routes and tracks the loop; no edits/builds.
- `planner`: read-only G1–G3 criteria, pre-mortem, and plan.
- `developer`: the only editor; implements one slice and performs local G4–G5 self-checks.
- `verifier`: no edit rights; judges G4–G8 and sends failures back to the developer.

### Role model assignment

If the repository uses `model` fields in `.codex/agents/*.toml`, assign available IDs by responsibility:

- dispatcher: lightweight/fast available model for routing;
- planner: strongest available reasoning/long-context model;
- developer: code-specialized model when available;
- verifier: strong independent reasoning/review model.

Use the exact IDs the user or runner exposes, including provider prefixes and suffixes. If fewer models exist than roles, reuse a verified ID. If more exist, leave extras unassigned and say so. Model labels alone do not prove capability; avoid claims such as “best” unless the runner documents them.

## Phase 3 — Merge the Codex artifacts

Update only what evidence requires. Keep TOML valid and preserve comments that explain Codex limitations.

### `.codex/config.toml`

Ensure it documents:

- project name, stack, solution/build entry points, default branch, and `AGENTS.md`;
- `[runtime]` policy as a **copyable example**, clearly stating that global Codex reads `~/.codex/config.toml`;
- `[build]` commands verified from the repository;
- `[loop]` phases, ownership, and whether native spawning is unavailable;
- `gates.g1` through `gates.g8` with owners and exact commands or policy checks;
- G7 invariants grounded in `AGENTS.md`, source, and project files;
- `[guard]` forbidden patterns matching the actual guard;
- architecture and pre-mortem references.

Do not put machine-specific paths, credentials, endpoints, or a mandatory local MCP server in committed config.

### `.codex/agents/*.toml`

For each role, keep `name`, `role`, `description`, `tools`, edit/build rights, owned gates, and instructions consistent with `AGENTS.md`. Add or update `model` only with a verified available ID and include a short `model_reason`. The files are role contracts, not proof that Codex can spawn subagents.

### `.codex/rules.toml`

Keep rules short and operational. Adapt build, code-search, TDD, acceptance/integration, branch hygiene, task artifacts, and auto-learning rules to the real stack. Every command and output directory must be verified. Rules should point back to `AGENTS.md` for detailed coding standards rather than duplicating the whole file.

### `.codex/guard-build.sh`

Merge rather than replace an existing guard:

- retain its stdin JSON parsing, `jq` fallback, exit contract (0 allow, 2 block), and explanatory block messages;
- derive publish/deploy/destructive-clean patterns from the real build system and existing hard rules;
- never block ordinary build/test commands;
- add a `# ADD_FORBIDDEN_PATTERNS` extension point;
- make it executable if it is created or changed.

If no guard exists, create one only when the repository provides enough evidence for safe, narrow patterns. Otherwise document the missing prerequisite instead of guessing.

### `.codex/README.md`

Explain the file map, what Codex actually auto-loads, how to copy the runtime block, the absence/presence of native sub-agent spawning, the role procedure, the guard contract, and remaining setup work. Do not claim that `.codex/agents/` or `guard-build.sh` is automatically enforced when it is not.

## Phase 4 — Verify without pretending

Run checks that are safe and relevant to the generated mirror:

1. Parse every TOML file if a TOML parser is available; otherwise perform a focused structural review and report the limitation.
If this skill's bundled `scripts/validate_harness.py` is available, run `python scripts/validate_harness.py <repo>` as a structural check; treat its warnings as report items, not proof that semantic invariants passed.
2. Confirm required role files exist and their ownership/tools agree with the loop contract.
3. Cross-check every command/path named in `.codex/README.md`, `config.toml`, and `rules.toml` against repository files.
4. Check that G4–G6 commands are real for the detected stack; mark environment-dependent integration gates `DEFERRED`, never PASS.
5. Check G7: domain/dependency purity, contract stability, tenant/feature behavior where applicable, no secrets/config values, and no generated artifacts. Use only invariants evidenced by the repository.
6. Dry-run the guard with representative forbidden payloads and allowed build/test payloads. Forbidden commands must exit 2; allowed commands must exit 0. Include a near-miss such as a non-recursive targeted file removal when the guard blocks recursive cleanup, so false positives are caught. Do not execute forbidden commands themselves.
7. Check executable permissions on the guard and inspect `git status` for unintended output.
8. Report any `{{VERIFY: ...}}` markers and any global runtime block that the user must copy manually.

## Final report

Use this structure:

```text
# Codex harness result

## Findings
- Stack/build evidence:
- Existing harness state:
- Loop choice:
- Codex runtime limitation:

## Changes
- path — change and reason

## Role model map
- dispatcher → model (or “unchanged/unverified”)
- planner → model
- developer → model
- verifier → model

## Verification
- TOML/config: PASS | FAIL | NOT RUN
- Cross-references: PASS | FAIL
- Guard dry-run: PASS | FAIL | NOT RUN
- G7 invariants: PASS | FAIL | DEFERRED
- Global config: not edited; copyable block shown

## Open items
- Exact unresolved facts, model IDs, environment variables, or CI-only gates
```

Never call the harness complete while a required artifact is a stub, a command is invented, or a failed validation is hidden.