dot-codex

Around December 2025, I stopped writing code. I also stopped reading generated code as the primary way to decide whether the work was done.

The product still matters. The code still matters. The rendered output still matters. What changed is the control point: instead of manually inspecting every generated source file, I shape the work before generation and make the AI produce proof that its work matches the intended behavior.

This repo is my current Codex configuration. It is tuned for Codex App, Codex Goals, local skills, and a harness that refuses to call plausible output done.

Pillars

• Feature spec: FEATURE.md is the behavior source of truth before implementation.
• Proof contract: PROOF.md defines how done will be proven.
• Real-boundary proof: primary proof must cross the relevant API, UI, DB, queue, provider, CLI, report, or workflow boundary.
• Captured evidence: feature proof runs must leave FEATURE_DIR/proof/runs/<timestamp>/ evidence through scripts/proof_run_capture.
• Autonomous repair: Codex keeps repairing code, setup, fixtures, diagnostics, or proof ownership until proof, gate, and evaluator pass or a true blocker remains.
• Contract freeze: after implementation starts, Codex must not change FEATURE.md, PROOF.md, or proof artifacts to make the result green.
• Proof scope: every non-trivial proof states what it proves, what it does not prove, false-green risks, and evidence strength.
• Done evaluator: coding-feature-evaluator is the skeptical read-only judge before completion.
• Green-but-broken: a green command with broken behavior means the proof is insufficient and must be repaired first.
• App improvement review: coding-app-improvement-review suggests app, proof, readiness, and harness improvements from evidence without applying them automatically.
• Harness evolution: harness changes need repeated evidence, before/after expectations, held-out checks, and a rollbackable manifest.

References

These references live in Zotero under the Harness Engineering collection. They are the main external background for this dot-codex harness.

• Ryan Lopopolo, Harness engineering: leveraging Codex in an agent-first world - Codex harnesses as context, tools, checks, and feedback loops around the model.
• Xuying Ning et al., Code as Agent Harness - code as executable, inspectable, stateful harness substrate across interface, mechanisms, and multi-agent coordination.
• Jiahang Lin et al., Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses - harnesses as a first-class determinant of coding-agent performance.
• Jiawei Gu et al., A Survey on LLM-as-a-Judge - evaluator reliability, bias, calibration, and judging against explicit criteria.
• Wanqin Ma et al., (Why) Is My Prompt Getting Worse? Rethinking Regression Testing for Evolving LLM APIs - prompt/API drift, slice-level regression, nondeterminism, and held-out checks.
• Lei Wang et al., A survey on large language model based autonomous agents - autonomous-agent architecture around profiling, memory, planning, action, and evaluation.
• Anthropic engineers, via Anatoli Kopadze, planner/generator/evaluator loop for full-app builds - generator/evaluator separation, live app judging, and contract-driven iteration.
• dominik kundel, A guide to /goal - Codex Goal as runtime state, not repo truth.
• Anatoli Kopadze, Loops explained: Claude, GPT, Mira and what actually works - autonomous loop patterns and persistent state.
• elvis, From Prompting Agents to Loop Engineering - the shift from prompting to engineered agent loops.
• Dan Farrelly, The Agent Loop Architecture - loop primitives behind agentic systems.
• Deepak Babu Piskala, Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants - specs and contracts as primary artifacts when agents generate implementation.
• GitHub, Spec Kit, and Fission AI, OpenSpec - practical SDD toolkits behind the FEATURE.md / PROOF.md split.
• Birgitta Bockeler, Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl - pragmatic SDD tradeoffs.
• Andrej Karpathy, Software Is Changing (Again) and coding workflow notes - human-in-the-loop coding and what remains worth reading.
• Geoffrey Huntley, Ralph Wiggum as a "software engineer" - while-loop coding-agent pattern and its limits.
• Simon Willison, What is agentic engineering? - agentic engineering as an engineering discipline, not magic prompting.
• Peter Steinberger, Shipping at Inference-Speed - field report on high-throughput agent-assisted shipping.

The local direction is spec-driven development, code-as-harness, proof-centered execution, and observability-driven harness improvement.

More Details

• Operating kernel: AGENTS.md.
• Harness workflow: docs/harness/operator-map.md.
• Proof lifecycle and evidence bundles: docs/harness/proof-lifecycle.md.
• Proof scope and false-green risk: docs/harness/oracle-scope.md.
• Target repo autofix, autosuggestions, and auto-improve: docs/harness/repo-autonomy.md.
• Autonomous execution and recovery: docs/harness/autonomous-execution.md.
• Harness evolution: docs/harness/evolution/evolution-loop.md.
• Handoff format: docs/harness/handoff.md.
• Non-coding and Second Brain workflows: docs/secondbrain.md.