Spec-as-Contract Workflow — Discuss → Approve → Implement → Verify → User Accept

What variant of Codex are you using?

VSCode Extension

What feature would you like to see?

Feature Request: Spec-as-Contract Workflow — Discuss → Approve → Implement → Verify → User Accept

Summary

I would like Codex to support a workflow where a collaboratively developed specification becomes the authoritative contract for implementation and completion.

This would go beyond a planning or discussion mode.

The goal is for the entire lifecycle of a substantial change to happen with full repository context:

Discuss → Design → Specify → Approve Spec → Implement → Verify Against Spec → User Review → Complete

The key idea is simple:

Once the user approves the specification, the specification becomes the definition of done.

Codex should not consider the work complete merely because implementation has been attempted, files were changed, or tests pass. Completion should mean that every approved requirement has been implemented, independently verified, and accepted by the user.

---

Motivation

My current workflow for substantial changes usually looks like this:

1. Discuss the feature outside Codex.
2. Work through architecture, edge cases, data behavior, compatibility concerns, and tests.
3. Turn that discussion into a large implementation prompt.
4. Give it to Codex.
5. Codex implements the feature and reports that the work is complete.
6. I ask Codex to audit its implementation against the original requirements.
7. The audit discovers something was only partially implemented.
8. Codex fixes it and reports completion again.
9. Repeat.

On a recent substantial feature, I had to ask Codex to audit the implementation roughly 30 times.

Many of those audits discovered requirements that were partially implemented even though the previous pass had reported the work as complete.

This creates a gap between two things Codex is already very good at:

• reasoning about a codebase
• implementing changes in a codebase

The missing piece is a durable contract connecting the reasoning to the implementation and verification phases.

---

Potential Duplicate Issues

There are related proposals for a Plan/Spec mode and a Talk/Discussion mode, and I think these requests are all addressing parts of the same broader workflow gap.

This proposal is intended to extend those ideas rather than duplicate them.

A discussion or planning mode helps establish what should be built before implementation begins. This proposal adds the missing lifecycle after that point: once the user approves the specification, the specification becomes a binding contract that remains authoritative throughout implementation, testing, verification, and final review.

The primary distinction is that Codex should not be able to drift from the approved design, silently reinterpret requirements during implementation, or declare “work complete” while portions of the agreed specification remain incomplete.

In short:

Discussion and planning establish the contract.
This proposal makes Codex remain accountable to that contract until the user accepts the finished implementation.

---

Proposed Workflow

1. Discussion Mode

Before editing code, Codex should be able to discuss the proposed feature while having full repository context.

During this phase it should be allowed to:

• inspect the repository
• inspect existing architecture
• inspect schemas and APIs
• inspect tests
• inspect related implementations
• inspect repository instructions such as AGENTS.md
• identify affected systems
• identify conflicts or ambiguities
• propose implementation approaches
• explore edge cases

But it should not modify the repository yet.

This is the phase where the user and Codex work through the idea together.

---

2. Living Specification

The discussion should produce a structured specification that evolves during the conversation.

The specification could include:

• functional requirements
• architecture requirements
• behavioral requirements
• affected APIs
• schemas and migrations
• compatibility requirements
• failure behavior
• edge cases
• security and tenancy constraints
• expected UI behavior
• test requirements
• non-goals
• known exceptions

Each requirement should receive a stable identifier, for example:

• REQ-001
• EDGE-004
• ARCH-007
• TEST-012

These identifiers should remain stable through implementation and review.

---

3. Repository Instructions Are Part of the Contract

All applicable repository instructions, especially AGENTS.md, should automatically become part of the implementation contract.

Codex should not silently violate repository instructions while satisfying the feature specification.

If the requested implementation conflicts with an applicable instruction, Codex should surface the conflict during specification work.

A deliberate exception should require explicit user approval.

For example:

ARCH-007 conflicts with repository rule AGENTS.md / Persistence / Rule 3.

The user could explicitly approve an exception for that work session.

That exception should then become part of the specification and verification record.

No silent deviations.

---

4. Explicit Spec Approval

Codex should not begin implementation until the user approves the specification.

The workflow might have states such as:

• Draft
• Review
• Approved
• Implementing
• Verifying
• User Review
• Complete

Once approved, the specification should become effectively immutable as the definition of done.

If implementation reveals that the specification must change, Codex should return to the specification phase and ask for approval of the change rather than silently redefining the requirements during implementation.

---

5. Requirement-to-Code Traceability

During implementation, Codex should attach concrete implementation evidence to each requirement.

For each requirement, the review should be able to show things such as:

• affected files
• classes
• functions
• methods
• modules
• schemas
• migrations
• relevant line ranges
• tests
• API endpoints
• UI components

For example:

REQ-014 — Preserve historical references when a part becomes obsolete

Implementation:

• PartLifecycleService.markObsolete()
• HistoricalMaintenanceRepository
• parts.schema.ts

Tests:

• part-lifecycle.test.ts
• historical-maintenance.test.ts

Relevant code:

• PartLifecycleService.ts:142–219
• HistoricalMaintenanceRepository.ts:88–133

This would allow the final review to function almost like a pull request review organized by original design intent.

---

6. Tests Should Be Designed With the Specification

Tests should not be an afterthought added during implementation.

While designing the feature, Codex and the user should be able to define the expected test coverage alongside the requirements.

This should include, where applicable:

• unit tests
• integration tests
• contract tests
• migration tests
• regression tests
• failure-path tests
• edge-case tests
• backward-compatibility tests

A requirement should not be considered fully verified merely because some unrelated test suite is green.

The tests should demonstrate that the specific requirement is satisfied.

---

7. Completion Status Must Be Granular

Requirements should have explicit states such as:

• NOT IMPLEMENTED
• PARTIAL
• IMPLEMENTED
• VERIFIED

PARTIAL must never roll up into “complete.”

If even one required item remains partial, the feature is not complete.

This would avoid a common failure mode where the happy path exists and Codex considers the broader requirement finished.

---

8. Independent Verification Pass

After implementation, Codex should perform a fresh verification pass against the approved specification.

Importantly, this review should not trust its previous claims of completion.

The instruction should effectively be:

Assume the implementation may be incomplete. Independently compare the current repository against every approved requirement and every applicable repository instruction.

For every requirement, Codex should provide concrete evidence.

Example:

REQ-021 — VERIFIED

Implementation:
InventorySyncService.reconcilePart()

Tests:
reconcilePart.test.ts:142–311

Evidence:
Handles discrete inventory, bulk inventory, unavailable inventory, and the required physical-check state.

REQ-022 — PARTIAL

Implementation exists for supplier closure propagation, but no test verifies behavior for historical supplier-part relationships.

Required action:
Add the missing behavior or verification before completion.

This would make auditing deterministic instead of conversational.

---

9. Final User Review

Once Codex believes every requirement is verified, the user should enter a final review phase.

This could present the specification similarly to a PR:

• requirement
• implementation evidence
• tests
• changed files
• exceptions
• verification result

The user could inspect the attached code locations, question misunderstandings, and request changes.

Codex would update the implementation and verification evidence as needed.

The workflow should continue until the user approves it.

---

10. Only the User Can Close the Contract

Codex should distinguish between:

“Implementation pass finished”

and:

“Work complete”

The latter should only occur when:

• every required specification item is verified
• every applicable repository instruction is satisfied
• every approved exception is documented
• required tests pass
• the verification pass finds no incomplete requirements
• the user approves the final review

Only then should Codex mark the work complete.

---

Why This Is Different From Plan Mode

There are several proposals around discussion, talk, planning, and spec modes, and I think they are all circling the same useful area.

This proposal focuses specifically on the next problem:

What happens after the plan is approved?

A plan is useful before implementation.

A contract remains authoritative through implementation, testing, auditing, and final acceptance.

The important capability here is not merely:

“Help me decide what to build before writing code.”

It is:

“Remember exactly what we agreed to build, prove that the resulting repository satisfies it, and do not redefine ‘done’ along the way.”

---

Why I Think This Matters

Codex is already capable of making very large changes.

As those changes become larger, correctness depends increasingly on maintaining intent across multiple phases of work.

Without a persistent specification contract, users currently have to manually maintain that intent by repeatedly:

• restating requirements
• auditing implementations
• finding partial work
• correcting misunderstandings
• re-running audits

A native spec-as-contract workflow would make Codex substantially more useful for serious engineering work.

It would also give users much more confidence in large autonomous changes because completion would become evidence-based rather than confidence-based.

---

Short Version

I want to be able to sit down with Codex, with Codex having full knowledge of my repository, and say:

“I have an idea.”

Then we work through the design, architecture, edge cases, and tests together.

We produce a specification.

I approve it.

Codex implements it.

Every requirement is traceable to code and tests.

Codex independently audits the repository against the approved spec.

I review the evidence.

We resolve misunderstandings.

And only when I approve the final result does Codex get to say:

Work complete.

Additional information

No response

Start by reading the related Plan/Spec discussion 7355 and Talk/Discussion issue 21254, then review the repository instructions in AGENTS.md referenced by the proposal. Done would require an approved specification to remain authoritative through implementation, verification, and user acceptance, with requirement-level evidence and explicit completion states.