← Back to file list
Codex Workflow Design
The core single-thread runtime design and state model.
Design Reference · /home/jonas/social-carousel-codex/docs/codex-workflow-design.md
Last modified: 2026-03-29T06:45:30.209Z
# Codex Workflow Design Status: Phase 2 design target This document translates the reconstructed OpenClaw workflow into a Codex-native design centered on one coordinating agent/thread and deterministic repo-local state. ## Design Goals - Keep one authoritative coordinating Codex thread for a live idea. - Move the source of truth fully into this repository. - Preserve explicit approvals, research locking, revision lineage, preview verification, and recovery. - Remove the OpenClaw multi-agent relay and Slack-first orchestration model. - Keep deployment side-by-side with the live OpenClaw app until an explicit cutover phase. ## Execution Model ### One Main Agent Normal operation should use one main Codex thread that performs: - intake normalization - angle generation - research synthesis - content drafting - contract validation - preview triggering - revision classification - logging and checkpoint writes Support helpers may exist later, but they should be implementation details. The authoritative run state remains with one thread and repo-local files. ### Human Interaction Model Human input should be treated as stage-bound commands against durable state, not as free-form conversational memory. Required human gates: - angle approval - research approval - preview approval / revision instruction ## Proposed File-Based State Model ### Primary Mutable State Use one mutable ledger per idea: `state/ideas/<idea_id>/ledger.json` The ledger should hold: - `idea_id` - `status` - `stage` - `revision` - `current_action` - `current_action_status` - `intake` - `selected_angle` - `research_lock` - `latest_draft` - `latest_verified_draft` - `latest_preview` - `retry_counters` - `degraded_flags` - `accepted_risks` - `last_transition_at` - `last_operator_message_at` - `deadline_at` - `idempotency` - `notification_dedupe` - `external_refs` Recommendation: - collapse OpenClaw's separate `step.json` and `overseer.json` into this single ledger for the Codex-native path - keep the liveness fields, but keep them in one file unless implementation pressure proves a split is necessary ### Supporting Per-Idea Files Recommended directory layout: ```text state/ideas/<idea_id>/ ledger.json intake.json angle-set.json research-summary.json research-lock.json drafts/ V1.json V2.json V2-R1.json preview.json notifications.json ``` Recommended semantics: - `intake.json`: normalized source brief - `angle-set.json`: last rendered options and the one approved selection - `research-summary.json`: latest approved research package - `research-lock.json`: approved claim/source boundary - `drafts/*.json`: immutable authored draft versions - `preview.json`: latest preview request, preview verification result, and bound preview version - `notifications.json`: optional view-layer metadata such as future Slack message ids ### Immutable Checkpoints Use immutable snapshots for every major transition: `state/checkpoints/<idea_id>/<sequence>-<stage>.json` Checkpoint triggers: - intake recorded - angle set rendered - angle approved - research approved - each draft version committed - integrity pass - QC pass - preview request built - preview verified - final approval - any degraded or blocked transition Checkpoint contents: - full ledger snapshot - transition reason - input artifact references - output artifact references - timestamp ### Append-Only Logs Use one append-only per-idea event log: `state/logs/<idea_id>.ndjson` Recommended event types: - `INTAKE_RECORDED` - `ANGLES_READY` - `ANGLE_APPROVED` - `RESEARCH_APPROVED` - `DRAFT_COMMITTED` - `FORMAT_REPAIR_REQUESTED` - `INTEGRITY_REPAIR_REQUESTED` - `QC_PATCH_REQUIRED` - `QC_PASSED` - `PREVIEW_REQUEST_BUILT` - `PREVIEW_VERIFIED` - `REVISION_CLASSIFIED` - `DEGRADED` - `BLOCKED` - `PARKED` - `RESUMED` - `APPROVED` Keep logs machine-readable first. Human summaries can be rendered from them later. ### Dead-Letter / Parked State Use: - `state/dlq/<idea_id>.json` for exhausted automatic recovery - `state/ideas/<idea_id>/ledger.json` with `status=parked` when the run is intentionally waiting or paused Parked reasons: - awaiting human approval - missing prerequisite artifact - external dependency temporarily unavailable - manual pause DLQ reasons: - retry budget exhausted - conflicting or unrecoverable artifact lineage - repeated preview failure after bounded retries - invalid state transition that cannot be auto-repaired safely ## Stage Transition Rules Recommended Codex-native stage vocabulary: | Stage | Meaning | |---|---| | `intake_recorded` | brief stored, angle generation may begin | | `angle_pending_approval` | angle set rendered, waiting on human selection | | `research_in_progress` | research or research revision running | | `research_pending_approval` | research package ready, waiting on approval | | `draft_in_progress` | drafting or draft revision running | | `validation_in_progress` | integrity/QC/preflight running | | `preview_in_progress` | preview payload built and preview generation running | | `preview_pending_decision` | verified preview ready, waiting on approval or revision notes | | `complete` | approved final version | | `parked` | intentionally waiting or paused outside the standard gate flow | | `blocked` | cannot proceed without explicit human decision | Allowed transition pattern: 1. read current ledger 2. validate the triggering input against the current stage 3. persist any required artifact first 4. write the new ledger state atomically 5. append the log event 6. write a checkpoint if the transition is material The main thread must not announce progress based only on memory; it should read the ledger first. ## Checkpoint Strategy ### Why Keep Checkpoints The useful OpenClaw idea to preserve is not the exact helper shape. It is the combination of: - deterministic current state - immutable snapshots before/after important decisions - explicit artifact provenance ### What To Checkpoint Always checkpoint: - a newly approved human decision - a newly locked research package - a new draft version - a passed validation boundary - a preview version that is about to be shown to the human - any degraded or blocked branch Do not checkpoint: - trivial read-only status checks - purely cosmetic view-layer sends ## Logging Strategy ### What To Preserve Preserve these OpenClaw qualities: - append-only history - event names that explain what actually happened - explicit recording of degrade-forward and blocked branches - enough detail to reconstruct a run without chat history ### What To Simplify Do not carry over the full OpenClaw event taxonomy or split logs into: - conversational memory - Slack history - mirrored session keys - several partially overlapping runtime artifacts One ledger plus one per-idea append-only log is enough for Phase 3. ## Revision Strategy ### Versioning Use immutable version ids for draft artifacts: - `V1` - `V2` - `V3` - `V2-R1` for design-only revisions from a QC-passed base The ledger should always point to: - `latest_draft_version` - `latest_verified_version` - `preview_base_version` ### Revision Classification Classify every post-preview note into: - `design_only` - `copy_within_lock` - `research_required` - `concept_restart` Default rules: - wording / emphasis / CTA refinement -> `design_only` - broader copy change inside existing claims -> `copy_within_lock` - new claim / new source / changed conclusion -> `research_required` - new concept or new angle -> `concept_restart` ## Suggested Helper Surface The Codex-native path should preserve helper-backed deterministic mutations, but the helper surface can be smaller and more focused than the current `carousel_state.py` monolith. Recommended helper groups: - `scripts/state_commit.*` - atomic ledger writes - checkpoint writes - log append - `scripts/workflow_validate.*` - angle command parsing - research-lock checks - revision classification - `scripts/preview_contract.*` - canonical draft validation - design payload build - preview verification - `scripts/dlq.*` - park / redrive / archive helpers Preserve the invariants, not the exact file or command names. ## Future Slack Fit Slack should be a secondary adapter, not the control plane. Future Slack integration should: - read the current ledger and render a status or approval card - write only metadata such as sent message ids or thread ids back to repo-local state - never decide current stage from chat history alone - never become the approval source of truth unless the approval is durably bound to the idea and stage in the ledger In other words: - Slack can be an input/output surface - `state/` stays the source of truth ## Side-By-Side Deployment Model The Codex-native workflow should assume: - live OpenClaw app remains on `127.0.0.1:3001` - new Codex app binds on `127.0.0.1:3101` - no Caddy change in Phase 2 - no reuse of live `/c/*` or `/api/carousel/*` routes until an explicit cutover plan exists ## What This Design Preserves - explicit human gates - research lock semantics - lineage-aware revisions - deterministic preview verification - bounded retries and parked/DLQ handling - append-only auditability ## What This Design Intentionally Removes - multi-agent specialist handoffs as the default operating model - Slack-specific templates as runtime logic - Airtable as a mandatory mirror - Docker-bridge-specific assumptions such as `172.17.0.1` - path duality between sandbox and host workspaces - separate step/overseer sidecars unless later proven necessary
Save
Ready