Inspiration
I use Codex almost every day. At first, I mostly cared about whether it could write good code. After working through enough long tasks, I realized that was no longer the hardest part.
The harder part was managing the work and knowing whether “done” actually meant done.
I kept running into the same problems. Context would get compacted. Important decisions would disappear inside older conversations. A worker could say it finished, but the review might refer to an older version of the code. Two agents could accidentally work on the same files. A new task might have no idea what the previous task actually proved.
Sometimes the final answer sounded completely confident even when the evidence was already stale.
That frustrated me enough that I started building a private workflow for myself. I wanted Codex to feel like a real engineering partner, but I did not want to rely only on chat history or trust a convincing “tests passed” message.
The foundation existed before Build Week. During Build Week, I worked solo with Codex and extended it into Codex Workflow Kit, a repo-native control and evidence layer for longer and more serious Codex development.
What it does
Codex Workflow Kit gives one developer a durable way to manage Codex work inside the repository.
Instead of keeping everything inside one conversation, it stores the important parts of the work as files that Codex can reload and verify.
It includes:
- Tasks with clear scope and acceptance criteria
- Durable state that survives context compaction and task changes
- Optional Builder, Reviewer, Tester, Security, and Research workers
- Worker identity and generation checks
- Write ownership and lock coordination
- Separate implementation, review, and test evidence
- Verification tied to the current Git and worktree state
- Closeout gates that reject missing or stale proof
- Succession packets for continuing work without copying entire conversations
- Installation, upgrade, drift detection, and package hygiene commands
The basic workflow looks like this:
- I give Codex an objective.
- The Control Room decides how risky or complex it is.
- Codex either handles it directly or delegates a bounded assignment.
- Implementation, review, and test results return as durable files.
- The Control Room accepts, rejects, or returns the result.
- Verification runs against the current repository state.
- The task closes only when the evidence supports what Codex is claiming.
I did not want every tiny change to become a huge process. The workflow stays solo-first and uses quick, standard, or stricter handling depending on the risk.
Why it is more than prompts
The project does contain instructions and skills that help Codex understand the workflow, but the important trust checks are implemented in code.
The CLI validates task state, worker receipts, worker generations, artifact ownership, review and test provenance, managed-file hashes, worktree identity, and closeout requirements.
For a fully verified closeout, the evidence records things such as:
- The command that was run
- Its exit status
- A digest of the raw log
- The current Git commit
- A digest of the repository content
- A digest of the managed workflow files
- The repository state before and after verification
If relevant content changes afterward, the previous evidence becomes stale and the task is no longer treated as fully ready.
This means Codex Workflow Kit is not just a prompt asking Codex to be careful. The CLI can actually refuse a confident completion claim when the required proof is missing or outdated.
I also try to be honest about what it cannot do. It is not an operating-system sandbox. It does not cryptographically prove human identity, and it cannot control every action available through the Codex host.
What it does provide is workflow-command enforcement, durable evidence, drift detection, and safer coordination inside a cooperative local development environment.
How I built it with Codex and GPT-5.6
I built the project solo while collaborating with Codex throughout Build Week.
I used one permanent Codex Control Room for planning, task ownership, integration, worker routing, evidence acceptance, and closeout. It delegated bounded implementation and review work while keeping the final decisions and shared repository state in one place.
During the eligible Build Week period, the repository recorded 170 commits. Of those, 62 commits changed 40 public product-source files. The rest of the history preserves real development state, reviews, tests, benchmarks, handoffs, and closeout evidence.
I used GPT-5.6 Terra through Codex for three paired benchmark series. The benchmarks compared plain Codex with workflow-assisted Codex using matching tasks and prompts.
The results were useful because they did not only make the workflow look good. They exposed real overhead, stale-state problems, and recovery gaps. Those findings directly led to Build Week repairs.
Other models were also used during development. I am not claiming that every commit came from GPT-5.6 or from one Codex session.
One of my favorite parts of the project was watching Codex challenge the workflow itself. Independent reviewers found contradictions, stale evidence problems, unsafe path assumptions, receipt-binding gaps, and documentation claims that were stronger than the implementation.
I did not hide those findings. They became focused repair tasks.
The workflow helped build and review the workflow itself.
Challenges
The hardest challenge was separating rules written in documentation from behavior the software could actually enforce.
It is easy to write that a worker must stay in scope. It is much harder to define exactly who the worker is, which attempt is current, what files it can touch, who owns the review, when evidence becomes stale, and what the system can honestly prove.
Context was another major challenge. Long Codex sessions naturally get compacted, and serious work often continues across several tasks. I stopped treating the conversation as the main source of truth.
Instead, I moved the current goal, decisions, risks, task state, briefs, handoffs, and evidence into compact repository files that a new task can reload.
I also worried about workflow cost. A trustworthy process is not useful if every harmless fix becomes slow and expensive.
To test that, I ran a controlled four-run benchmark comparing plain Codex with workflow-assisted Codex on the same low-risk task. The workflow median was 1.66x elapsed time and 1.81x input tokens.
That is real overhead. I do not claim the workflow makes every task faster or cheaper. However, it stayed below the 2x threshold I had defined in advance for a healthy small-task path.
The benchmark also exposed a stale repo-map recovery issue, which I reported instead of hiding.
Accomplishments I am proud of
I am proud that the project coordinated a large part of its own Build Week development.
I am also proud that:
- Completion evidence becomes stale when relevant repository content changes.
- Ambiguous or outdated worker identities are rejected instead of silently accepted.
- Managed workflow files are hashed and checked for drift.
- Private runtime artifacts are excluded from the package.
- Small tasks can stay small.
- Higher-risk tasks require stronger proof.
- Review findings led to real repairs instead of automatic approval.
- The project explains what it enforces, what it only detects, and what still depends on Codex or the human operator.
What I learned
The biggest thing I learned is that an AI coding workflow needs more than a smart model.
It also needs memory, authority, identity, evidence, and honest stopping conditions.
I learned that delegation is not automatically better either. Small tasks should stay small. Workers are useful when they reduce context pressure, provide independent judgment, or isolate one clear responsibility.
They should not exist just because a complicated organization diagram looks impressive.
Most importantly, I learned that “done” is a claim. That claim should be supported by current evidence.
Sometimes a workflow that refuses to call something finished is more useful than one that always gives a confident success message.
What is next
The current product is Codex Workflow Kit for one developer operating Codex across real repositories.
For now, my goal is simple: help serious Codex users preserve context, delegate only when it is useful, review work independently, and know what “finished” actually means.
Log in or sign up for Devpost to join the conversation.