Interactive Codex Engineering Workflow

01 Define Task Specification

Stage 1 of 9

Objective

Transform fuzzy product intent into an unambiguous, bounded engineering specification with explicit constraints.

Why It Matters

Vague prompts ("fix the login", "make the table responsive") force Codex to guess at architecture, often breaking existing edge-case handlers or introducing unexpected libraries.

Recommended Action

Identify inputs, expected outputs, non-functional requirements (performance, accessibility), and non-negotiable boundaries (e.g. do not touch the database schema).

Relevant Codex Prompt

Specification Prompt

I need to implement password reset token expiration.
Stack: Node.js / Express / Redis.
Requirements:
1. Expire reset tokens after exactly 15 minutes.
2. Invalidate existing token if a new request is issued for the same account.
3. Return HTTP 400 with code "TOKEN_EXPIRED" if invalid.
Do NOT modify database models or authentication cookies yet. Investigate first.

Completion Criteria

You have a written specification listing inputs, outputs, error conditions, and out-of-scope boundaries.

02 Establish Git Checkpoint

Stage 2 of 9

Objective

Create a safe, instantaneous recovery point in version control before allowing the AI agent to edit or touch any repository files.

Why It Matters

If Codex takes an incorrect architectural path or corrupts multiple files, a clean Git checkpoint allows you to revert the entire workspace back to a known working state in one second.

Relevant PowerShell Commands

PowerShell — Checkpoint & Branch

# Verify working tree is clean
git status

# Create an isolated feature branch
git switch -c feat/token-expiration

# Commit any pending changes as a clean baseline
git add .
git commit -m "checkpoint: baseline before implementing token expiration"

Completion Criteria

git status outputs "working tree clean" on a designated branch.

03 Codex Investigation (Read-Only)

Stage 3 of 9

Objective

Instruct Codex to read files, examine imports, identify dependencies, and diagnose root causes without modifying any files.

Why It Matters

AI agents that edit immediately often overwrite utility helpers or violate project architectural conventions because they haven't read the existing implementation.

Relevant Codex Prompt

Investigation Enforcement Prompt

Investigate the token handling mechanism in `src/services/auth.ts` and `src/api/routes/auth.ts`.

CRITICAL DIRECTIVE: Do NOT modify any files.
1. Read the current token generation and verification logic.
2. Note how Redis client is injected.
3. Report any potential race conditions with existing session storage.
4. Do not write code until I approve your analysis.

Completion Criteria

Codex outputs an accurate diagnostic explanation of the current codebase and zero files have been changed on disk.

04 Review Implementation Plan

Stage 4 of 9

Objective

Review and approve Codex's proposed step-by-step changes, verifying that no unwanted refactors or unnecessary packages are included.

Why It Matters

It is ten times faster to correct a flawed architectural approach in a 10-line text plan than to untangle a 600-line messy code diff.

Recommended Action

Check if Codex intends to add unnecessary dependencies, rename core interfaces, or bypass existing unit tests. If so, tighten the constraints before giving write approval.

Completion Criteria

You and Codex are aligned on the exact files that will be modified and the logic to be written.

05 Execute Implementation

Stage 5 of 9

Objective

Grant Codex permission to write code strictly in accordance with the approved plan, staged incrementally.

Relevant Codex Prompt

Execution Approval Prompt

The proposed plan is approved. Proceed with Step 1 and Step 2 only:
1. Implement token expiration logic in `src/services/auth.ts`.
2. Add unit tests in `test/unit/auth-token.test.ts`.

Remember: preserve existing function signatures and do not install any new packages.

Completion Criteria

Target files have been created or modified without syntax errors.

06 Automated Verification

Stage 6 of 9

Objective

Require Codex to run compiler checks, linters, and unit test suites, providing the real terminal output.

Relevant Commands

PowerShell — Automated Verification Commands

# Run TypeScript check (or compiler)
npm run type-check   # or: npx tsc --noEmit

# Run unit tests covering the modified component
npm test -- test/unit/auth-token.test.ts

# Run linter
npm run lint

Completion Criteria

All tests pass with exit code 0; zero compiler errors; linter passes with zero warnings.

07 Review Git Diff

Stage 7 of 9

Objective

Systematically inspect every line added, modified, or removed by Codex.

Relevant Commands

PowerShell — Review Git Diff

# Inspect modified files list
git status -s

# Review full unified diff
git diff

# Or inspect side-by-side inside VS Code:
code --diff src/services/auth.ts src/services/auth.ts

Completion Criteria

Every single modified line is understood and justified; no accidental comment deletions or unintended changes exist.

08 Manual & Browser Testing

Stage 8 of 9

Objective

Perform human verification in browser or CLI to test real runtime behavior, edge cases, and visual layout.

Recommended Action

Exercise the happy path and negative error paths. Test responsive viewports (375px mobile through 1920px desktop). Check browser console for uncaught errors.

Completion Criteria

Application performs flawlessly under real user interaction.

09 Commit & Merge

Stage 9 of 9

Objective

Commit the verified changes with a structured, conventional commit message and merge or open a pull request.

Relevant Commands

PowerShell — Final Commit & Push

# Stage verified files
git add src/services/auth.ts test/unit/auth-token.test.ts

# Create clean conventional commit
git commit -m "feat(auth): enforce 15-minute expiration on password reset tokens"

# Push to remote branch
git push -u origin feat/token-expiration

Completion Criteria

Clean Git tree, verified commit, task successfully completed.