dot-codex

In December 2025, I stopped writing code. Codex now does the implementation work.

That only works because I also changed how completion is judged. Source inspection is no longer the primary control point. I decide the behavior, require executable proof at the real product boundary, retain every official attempt, and demand a fresh evaluator pass before tracked work is complete.

This repository is the control layer behind that workflow. It turns Codex from a fast code generator into an accountable engineering system that can take a feature from intent to evidence-backed completion.

Pillars

• Intent becomes a contract. FEATURE.md records observable behavior, boundaries, edge cases, and material decisions before substantial implementation begins.
• Proof crosses the real boundary. PROOF.md and proof/run.sh exercise the relevant UI, API, database, queue, provider, CLI, report, or workflow and read back durable or visible behavior.
• Evidence survives the run. proof_run_capture preserves the command, output, exit state, and accepted proof inputs for official failures, timeouts, interruptions, and passes.
• Contracts do not bend for green. Revisions need a visible reason and cannot narrow the goal or weaken proof to manufacture a pass.
• Failures drive the next repair. Codex fixes the owning code, architecture, setup, fixture, diagnostic, or proof boundary and keeps going until completion or a real user-owned or external blocker.
• Evaluation challenges the evidence. A fresh read-only evaluator maps accepted claims to retained output, then inspects the relevant implementation and call paths for gaps and false greens.
• Completion belongs to the final candidate. Any relevant edit makes earlier proof and evaluation stale. Tracked work is complete only after realistic proof and a fresh evaluator PASS on unchanged work.
• One parent owns one feature. Serial execution keeps contracts, implementation, proof, repair, queue state, and completion under one accountable owner.
• Failures improve the system. Retained attempts, evaluator findings, observed false greens, and user corrections feed stronger project checks and proof design instead of disappearing into terminal history.

The standard is simple: accepted behavior, executable evidence, and no plausible shortcuts.

Install

Clone the repository as your Codex home, or point CODEX_HOME at another checkout:

git clone https://github.com/marcocello/dot-codex /path/to/dot-codex
export CODEX_HOME=/path/to/dot-codex
cp "$CODEX_HOME/config.template.toml" "$CODEX_HOME/config.toml"

Review config.toml and replace the example paths, permission roots, notification command, and MCP settings for your machine. Then ask Codex to manage the installation through the included skills:

• “Use $sync-codex-skills to bootstrap this installation.”
• “Use $sync-codex-skills to reconcile all declared skills and plugins.”
• “Use $manage-codex-skills to add, update, diagnose, list, or remove an inventory entry.”

System skills and openai-primary-runtime plugins remain runtime-managed and stay outside skills.toml. The skill management guide explains ownership, reconciliation, plugin handling, and update policy.

When editing this repository, run its read-only gate:

"${CODEX_HOME:-$HOME/.codex}/scripts/gate" --root "$CODEX_HOME"

Design references

The external background for this work lives in Zotero under the Harness Engineering collection.

Research and field reports

• Ryan Lopopolo, Harness engineering: leveraging Codex in an agent-first world on context, tools, checks, and feedback loops around the model.
• Xuying Ning et al., Code as Agent Harness on executable, inspectable, stateful harness substrate.
• Jiahang Lin et al., Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses on harnesses as a determinant of coding-agent performance.
• Jiawei Gu et al., A Survey on LLM-as-a-Judge on evaluator reliability, bias, and the need to preserve executable evidence alongside semantic judgment.
• Wanqin Ma et al., (Why) Is My Prompt Getting Worse? Rethinking Regression Testing for Evolving LLM APIs on prompt drift, nondeterminism, and held-out checks.
• Lei Wang et al., A survey on large language model based autonomous agents on profiling, memory, planning, action, and evaluation.
• Anthropic engineers, via Anatoli Kopadze, on the planner, generator, and evaluator loop for full-app builds.
• dominik kundel, A guide to /goal on Codex Goal as runtime state.
• Anatoli Kopadze, Loops explained: Claude, GPT, Mira and what actually works on autonomous loop patterns and persistent state.
• elvis, From Prompting Agents to Loop Engineering on engineered agent loops.
• Dan Farrelly, The Agent Loop Architecture on the primitives behind agentic systems.
• Deepak Babu Piskala, Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants on contracts as primary artifacts.
• GitHub, Spec Kit, and Fission AI, OpenSpec as practical spec-driven development toolkits.
• Birgitta Bockeler, Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl on the tradeoffs of spec-driven development.
• Andrej Karpathy, Software Is Changing (Again) and coding workflow notes on human-in-the-loop coding.
• Geoffrey Huntley, Ralph Wiggum as a “software engineer” on while-loop coding agents and their limits.
• Simon Willison, What is agentic engineering? on agentic engineering as an engineering discipline.
• Peter Steinberger, Shipping at Inference-Speed on high-throughput agent-assisted shipping.

Go deeper

• Harness design and workflow
• Proof lifecycle and retained attempts
• Proof scope and false-green risk
• Target repository autonomy
• Autonomous execution and recovery
• Harness evolution
• Handoff format
• Non-coding and Second Brain workflows
• Skill inventory and maintenance

Code generation is becoming abundant. Reliable acceptance remains scarce. dot-codex concentrates engineering effort on the scarce part: deciding behavior, producing evidence, and preserving enough context to repair failures without starting over.