Pro ↔ Codex CLI — Lightweight Workflow (for non-coders)

Purpose: Let ChatGPT Pro act as the engineering lead (research + planning) and Codex CLI act as the developer (edits the repo). Your job: only copy-paste the blocks between them.

Quick Use

Start in ChatGPT Pro → get a TASK FOR CODEX block.
Paste that block into Codex CLI.
Codex replies with a CODEX UPDATE block → paste it back into Pro.
Repeat until Pro says “Done.”

That’s it.

1) Start in Pro (lead/manager)

Paste this once to brief Pro on how to behave:

You are the LEAD ENGINEER. Codex CLI is the DEVELOPER with repo access.
Your job: research if needed, then produce a clear, 10–30 minute task for Codex.
Output ONLY the block below—no extra text.

### TASK FOR CODEX
**Goal:** <one-sentence outcome>
**Why it matters:** <short context in plain English>
**Details / Hints:** <file/dirs if known, approach tips, links if helpful>
**Definition of done:** <how we’ll verify success in simple terms>

Example you can ask Pro for

I want to add a basic uptime check. Please generate the task.

Project notes:
- Fastify server under `apps/api`.
- Use existing patterns if possible.
- Keep it small and safe; no secrets.

Return only the TASK block.

Pro will answer with a ### TASK FOR CODEX block. Copy it.

2) In Codex CLI (developer)

Paste the TASK FOR CODEX block into Codex CLI. Codex does the work and returns:

### CODEX UPDATE
**Summary:** <what changed, 1–2 lines>
**Changes made:** <key files or actions, in bullets>
**Verification:** <how to run or test it>
**Questions / blockers:** <if any; ask plainly>
**Next suggestion:** <optional follow-up task idea>

Copy that CODEX UPDATE back to Pro.

3) Back to Pro (review & next step)

Paste Codex’s CODEX UPDATE into Pro and say:

Please review the CODEX UPDATE.
- If it meets the goal, reply "Done".
- Otherwise, return another TASK FOR CODEX.
- If there are questions, answer them and then give the next task.
Return only the required block.

Pro will either give the next TASK FOR CODEX or say Done.

Research-first template (when you need Pro to investigate first)

Tell Pro:

Before writing a task, do a quick research pass:
- Summarize relevant findings in 5 bullets.
- Then output ONE "### TASK FOR CODEX" block to move us forward 10–30 minutes.

Return ONLY:
1) A short 5-bullet research summary,
2) A single TASK FOR CODEX block.

Worked Mini-Example

Pro → Codex

### TASK FOR CODEX
**Goal:** Add a `/health` route that returns `{ "status": "ok" }`.
**Why it matters:** Lets us monitor uptime without logging in.
**Details / Hints:** Server is in `apps/api`. Follow the existing route style.
**Definition of done:** Visiting `/health` returns HTTP 200 + the JSON body above.

Codex → Pro

### CODEX UPDATE
**Summary:** Implemented GET /health and verified locally.
**Changes made:** Added route in `apps/api/src/main.ts`; updated app wiring.
**Verification:** Run the app and visit http://localhost:3000/health to see `{ "status": "ok" }`.
**Questions / blockers:** Do you also want a `/ready` endpoint?
**Next suggestion:** Add a tiny test for `/health` in the test suite.

Pro (next step) → Codex

### TASK FOR CODEX
**Goal:** Add a simple test for `/health` and ensure it runs in CI.
**Why it matters:** Prevents regressions.
**Details / Hints:** Use the existing test framework; keep it minimal.
**Definition of done:** Test passes locally; CI shows the test ran successfully.

Optional: `agents.md` (put this in your repo root)

Codex CLI can read this to know how to behave. Keep it simple.

# agents.md — Codex CLI contract (lightweight)

**Role:** You are Codex, the developer. 
You receive a "### TASK FOR CODEX" block from ChatGPT Pro and:
1) Do the work in a safe, small step (10–30 minutes).
2) Reply with "### CODEX UPDATE" including:
   - Summary (1–2 lines)
   - Changes made (key files/actions)
   - Verification (commands or steps)
   - Questions/blockers (if any)
   - Next suggestion (optional)

**Principles:** small diffs, clear verification, no secrets.

Copy-paste cheat-sheet (keep handy)

From Pro to Codex: ### TASK FOR CODEX …
From Codex back to Pro: ### CODEX UPDATE …
Your role: Just copy the blocks. If Codex asks questions, paste them to Pro; Pro will answer and send the next task.

Troubleshooting (plain English)

Pro outputs essays? Remind it: “Return only the TASK block.”
Codex asks something you don’t know? Paste it to Pro; Pro will decide.
Task feels too big? Tell Pro: “Split it into a smaller 10–30 minute task.”
Web references needed? Ask Pro to include 1–3 links inside Details / Hints.

numman-ali/chatgpt-codex-workflow.md