codex2paper

A markdown-based control layer for running research workflows inside Codex / Claude Code.

What this is

codex2paper structures your repo so AI coding agents can:

• plan before execution
• iterate with phase boundaries
• integrate external critique
• keep decisions traceable

It is designed to work with CLI agents like Claude Code and OpenAI Codex.

---

Why

Agent workflows break down when:

• planning is implicit (no durable artifact)
• context is scattered across prompts
• feedback is unstructured
• iteration loops drift

In practice, strong workflows converge on:

markdown files as the source of truth (Medium)

codex2paper formalizes that structure.

---

Core idea

All work happens through a staged loop:

1. Converge
2. Validate
3. Experiment
4. Method
5. Writing

Each phase has:

• a dedicated markdown file
• an explicit gate
• a clear output

The agent reads, edits, and advances these files.

---

Quick start

git clone <repo>
cd codex2paper

Then in Claude Code / Codex:

Read control.md and summarize current phase.
Propose next actions based on queue.md.

Typical loop:

1. Ask agent to update direction.md
2. Generate a plan (Plan Mode / markdown)
3. Send for external critique
4. Write back into reviews.md
5. Advance phase in control.md

---

Structure

• control.md — current phase + next action
• queue.md — active tasks
• direction.md — problem framing
• baselines.md — validation
• reviews.md — external critique + decisions
• weekly_review.md — decision log
• skills/ — agent-facing workflows
• EXAMPLE_ROUND.md — full loop example

---

How it fits Claude Code

Claude Code already supports:

• planning before execution (Plan Mode)
• markdown-driven context (CLAUDE.md, etc.)
• subagents and structured workflows (Claude)

codex2paper adds:

• persistent phase structure
• cross-iteration memory
• explicit research gates

---

Not included

• no automation
• no experiment runner
• no agent orchestration layer
• no mcp

This repo only defines structure + conventions.

---

Status

Lightweight pattern. Works best for:

• iterative research
• paper-oriented projects
• agent-assisted exploration

---

Inspirations

See ACKNOWLEDGEMENTS.md.