Codex Workflow Template: A Closed-Loop Workflow Connecting Reasoning Models and Programming Agents

The Codex Workflow Template is an open-source framework for developers using Codex CLI. It enables a collaborative model where reasoning models (e.g., Claude, o1) handle architectural design and requirement analysis, while programming agents (e.g., Codex CLI) take charge of code implementation. Through a structured document system, it ensures smooth knowledge flow between the two roles and establishes a closed-loop feedback mechanism to address collaboration challenges.

With the rise of large language models, the "dual-model collaboration" pattern (reasoning models for high-level design, coding agents for implementation) has shown promise in balancing strategic systematics and tactical efficiency. However, practical challenges exist: How to accurately convey specs from reasoning models to coding agents? How to feed back implementation issues/decisions to reasoning models? How to avoid information loss or distortion during transmission? These are the problems the Codex Workflow Template aims to solve.

The template's design follows the principle of "specs in, reviews out". The forward flow: specs from reasoning models guide Codex CLI's implementation. The reverse flow: Codex CLI generates review files, progress records, and document update proposals to feed back to reasoning models. This bidirectional flow ensures architectural decisions are faithfully executed in code, while implementation realities inform architectural improvements, forming a virtuous cycle.

The template defines a hierarchical document structure:

• AGENTS.md: Project overview (tech stack, architecture rules, structure, coding standards) loaded by Codex CLI on startup.
• docs/specs/: Requirement specs (background, detailed needs, acceptance criteria) written by reasoning models/architects.
• docs/architecture.md: Living document updated with evolving architectural decisions.
• docs/domain-model.md: Core entities/enums/invariants for consistent code generation.
• docs/decisions/: Architecture Decision Records (ADR) for tracking key choices.
• docs/review/: Auto-generated review reports (conformance analysis, quality assessment) for feedback.
• docs/progress/: Progress tracking (feature-level status, design state, branch records).

Three core skills in .codex/skills/:

• $new-feature: Triggers implementation based on specs, following AGENTS.md rules.
• $review-ready: Generates review reports and updates progress records.
• $review-fix: Executes code adjustments based on review feedback.

Workflow steps:

1. Planning: Reasoning models write specs and ADRs.
2. Implementation: Use $new-feature to start coding.
3. Review: Trigger $review-ready for auto-generated reports.
4. Replay: Reasoning models update architecture/ADRs based on reviews.
5. Delivery: Human handles Git operations and PRs.

The template is ideal for:

• Complex system development (clear architectural boundaries).
• Team collaboration (shared context, consistency).
• Long-term maintenance (evolving docs keep up with code).
• AI-assisted development (leveraging strengths of both models).

Its value: Solves core pain points in AI-assisted development (effective collaboration between "thinkers" and "doers", smooth knowledge flow, implementing architectural design). It ensures software engineering principles (maintainability, traceability, collaboration) are preserved even with deep AI involvement.