codex_workflow is a modular Codex workflow with explicit responsibility
boundaries, persistent project documentation, shared user-level runtime files,
and conservative lifecycle operations.
This guide is organized into five parts:
- command prompts and route selection;
- the installed-file map;
- scripted configuration and customization;
- the Heavy-route execution model;
- the component hierarchy and ownership model.
Open Codex from the project directory and send this prompt:
Download and extract the latest GitHub Release from https://github.com/viettran-edgeAI/codex_workflow/releases. Then read the bundled `codex_workflow/bootstrap.md` and follow it exactly.
The release package is a universal ZIP for Linux, macOS, and Windows. Its installation guide invokes the bundled lifecycle CLI, which owns validation, rendering, backups, project initialization, and rollback. After the first installation, start a new Codex session so the newly installed user instructions are loaded. Python 3.11 or newer is required.
The bootstrap installs the user-level workflow and the current project. It
does not ask configuration or personalization questions. Those are explicit
follow-up commands. It also adds the workflow-owned project paths to
.gitignore and removes a project-level Codex_Workflow/ extraction directory
once the installation transaction succeeds. Bootstrap then requires one
doc-writer action to initialize new or still-template-marked agent_docs/
files, or perform a read-only completeness check when the framework is already
healthy. Installation is incomplete until that action succeeds. For listed
context documents, the worker must populate project_structure.md,
project_overview.md, and project_core_tech.md from verified project evidence.
Send each command as its own prompt. The installed lifecycle CLI performs the validated filesystem operation directly.
Interactively change the persistent user-level workflow configuration. The command displays a menu containing every setting below, with Exit at the bottom. Choose one setting at a time; after a change, the menu is displayed again until Exit is selected.
- default executor (
executor_lunaorexecutor_terra); - default executor reasoning effort (
high,xhigh, ormax); - maximum concurrent workers;
- maximum concurrent
executor_solworkers; - final-report package size.
The command shows the current values, builds a complete new JSON snapshot, and then synchronizes the Heavy route, all workflow worker TOMLs, and workflow-owned Codex platform settings. The End-of-Session handoff is integrated and automatic, not a user-configurable setting. The command does not change project personalization or project documents.
Interactively personalize the current project. The three supported areas are:
- Frontend Project Profile, including a project-specific verification profile such as reduced frontend testing when that is an intentional decision;
- Design Principles;
- Additional Workflow Decisions.
Confirmed decisions are stored in the hidden project resource and materialized inside the personalization marker in the project's workflow entry point. A missing or invalid resource is only staged as a recovery proposal until confirmation; cancellation changes no file. This command does not modify global worker configuration or the Project Documentation Framework.
Install the workflow in the current project after the user-level workflow has already been bootstrapped:
- creates or preserves the project
AGENTS.mdentry point; - imports a pre-existing project
AGENTS.mdinto the dedicated project-local region instead of semantically merging it; - creates missing files in
agent_docs/from the six project-document templates; - invokes
doc-writerto initialize new or still-template-marked documentation, while healthy existing installations are a no-op; - requires listed
project_structure.md,project_overview.md, andproject_core_tech.mdrecovery or new files to be populated from verified project evidence; - creates the default hidden personalization resource when missing;
- reuses the installed user-level configuration as a read-only source.
It does not reinstall or modify any user-level payload under ~/.codex/, reset
existing project documents, or ask configuration and personalization
questions. If the workflow already has an active or disabled project entry
point, the command first validates its state. A healthy active installation is
a no-op; a healthy disabled installation points to codex_workflow --enable.
If framework documents are missing or retain bootstrap markers after a failed
documentation action, rerunning --install recreates only missing templates
and returns the required recovery action again. Stale, malformed, or conflicted
entry points stop with an actionable error.
Update the installed workflow and the recognized current project from a GitHub Release asset. The command queries the GitHub Releases API, selects the latest eligible semantic-versioned release with the matching ZIP and checksum, downloads the asset, verifies it, and extracts it into a temporary directory. It never clones or pulls the repository.
The update migrates and preserves the installed workflow configuration and regenerates distributed worker TOMLs from the incoming package. It preserves project personalization, project-local instructions, project documents, unrelated Codex settings, source backups, the automatic-check preference, and the project's enabled or disabled state. Projects on older workflow versions are validated against their matching historical source backups. It stops on marker drift, unavailable historical source, or legacy edits requiring a one-time reviewed migration.
Run an explicit read-only release check. It always queries the available installable releases, regardless of the automatic-check setting, and reports every version newer than the installed one with a compact summary of each release's notes. It does not download or change files.
Remove the installed workflow in two phases. The first invocation creates a
read-only destructive summary and warns the user. Only after one explicit
second confirmation does the lifecycle CLI delete the project workflow entry
point, project workflow resource, user-managed workflow region, workflow-owned
Codex settings and workers, and the complete installed runtime including
backups. It preserves agent_docs/ and unrelated user-level content. A
non-affirmative response performs no changes.
The package default is disabled: ~/.codex/AGENTS.md contains no session-start
check instruction, so new sessions make no automatic update-check call.
Send codex_workflow --enable_auto_check_update to explicitly enable the
session-start check. It updates the installed configuration and adds an
instruction that runs the read-only auto-check-update command once per new
session. When enabled, the command compares the installed version with the
highest usable GitHub Release and reports an available update; it stays quiet
when current. codex_workflow --disable_auto_check_update disables the setting
and removes that instruction. Both commands preserve unrelated user-level
content.
The former --enable_auto_update and --disable_auto_update prompts remain
compatibility aliases; no command automatically installs an update.
Disable the workflow for the current project by moving the active entry point:
AGENTS.md -> .codex_workflow_hidden_resources/.AGENTS.md
The contents, personalization resource, project documents, and user-level workflow remain intact. The operation is a safe no-op when the project is already disabled.
Re-enable a disabled project by moving the entry point back:
.codex_workflow_hidden_resources/.AGENTS.md -> AGENTS.md
This changes only the active/disabled entry-point state. It does not reread or reapply configuration or personalization.
There are three execution routes:
- Light route — the default; the main agent works alone with minimal workflow overhead.
- Medium route — the main agent performs implementation and verification; only Explorer and the dedicated handoff worker are used.
- Heavy route — the main agent orchestrates enabled worker subagents for larger deployment-state tasks.
For ordinary questions and small tasks, no route command is needed. To select a route for a task or plan, include one of these instructions in the prompt:
use medium route. [task description]
use heavy route. [task description]
The selected route remains active until the user changes it or the session
ends. Each substantive Medium or Heavy deployment automatically creates a fresh
Luna xhigh worker before its final response. That worker receives the configured
recent main-agent turns and alone reconciles the complete agent_docs/
framework, handles Git closure, and returns the final three-column
worker-statistics table. No manual closure prompt, main-agent summary, usage
ledger, or second documentation worker is required. Questions and small or odd
bounded tasks use the direct worker-free path and emit no table.
The release ZIP contains only one top-level directory, codex_workflow/. It
does not contain the repository README, README images, development documents,
.git/, release scripts, or other repository-only files. On Windows, ~/.codex
means the current user's profile directory and the platform's normal path
separator is used.
After installation, the runtime is distributed between the user environment and the current project as follows:
~/.codex/
├── AGENTS.md # user-level command interface
├── config.toml # existing Codex config; only workflow-owned keys are managed
├── agents/ # all distributed workflow worker TOMLs
│ ├── executor_luna.toml
│ ├── executor_terra.toml
│ ├── executor_sol.toml
│ ├── tester.toml
│ ├── doc-writer.toml
│ ├── explorer.toml
│ └── end_of_session.toml
└── codex_workflow/
├── VERSION # installed workflow version
├── user_AGENTS.md # managed commands and optional-check placeholder
├── workflow_config.json # persistent workflow configuration
├── workflow.py # validated lifecycle CLI
├── runtime/ # validation, rendering, release, and transaction modules
├── resources/ # immutable package defaults
│ ├── auto_check_update.md
│ ├── personalization.md
│ └── workflow_config.default.json
├── install_state.json # workflow ownership and installed-state manifest
├── heavy_route.md # Heavy-route orchestration rules
├── medium_route.md # Medium-route rules
├── explorer_companion.md # read-only context gateway and brief contracts
├── end_of_session.md # shared handoff spawn contract
├── bootstrap.md # initial user/project bootstrap procedure
├── install.md # project-only installation procedure
├── update.md # Release-based update procedure
├── check_update.md # explicit read-only release check
├── remove.md # two-phase removal procedure
├── enable_auto_check_update.md # enable automatic session check
├── disable_auto_check_update.md # disable automatic session check
├── enable_auto_update.md # legacy enable alias
├── disable_auto_update.md # legacy disable alias
├── configuration_guide.md # --configure procedure
├── personalization_guide.md # --personal procedure
├── disable.md # --disable procedure
├── enable.md # --enable procedure
├── templates/
│ ├── AGENTS.md # project entry-point template
│ ├── agents/*.toml # all distributed worker templates
│ └── project_docs/*.md # six Project Documentation templates
├── .source_backup/<version>/ # complete installed release source backup
└── .backups/<old-version>-<timestamp>/ # update backups, created when needed
<project>/
├── AGENTS.md # active project workflow entry point
├── .gitignore # workflow-owned project paths are ignored
├── agent_docs/
│ ├── project_overview.md
│ ├── project_core_tech.md
│ ├── project_structure.md
│ ├── project_progress.md
│ ├── project_diary.md
│ └── latest_session_work.md
└── .codex_workflow_hidden_resources/
├── personalization.md # project-scoped private resource
├── state.json # project entry-format and activation state
└── .AGENTS.md # disabled entry point; mutually exclusive with root AGENTS.md
The last two project entry-point files are mutually exclusive: an enabled
project has AGENTS.md; a disabled project has the hidden .AGENTS.md. The
hidden directory is also where project personalization is kept so it is not
mistaken for ordinary project documentation.
The six files under agent_docs/ have different ownership and purposes:
project_overview.md— goals, architecture, workflow, and major decisions;project_core_tech.md— important technologies and architectural constraints;project_structure.md— layout, modules, ownership, and boundaries;project_progress.md— concise overall progress and current milestone;project_diary.md— durable decisions, discarded approaches, and lessons;latest_session_work.md— the latest deployment state, evidence, outcome, unfinished work when present, and continuation point.
Command prompts select an operation. The lifecycle CLI validates and materializes all generated surfaces from their source resources.
The persistent configuration is:
~/.codex/codex_workflow/workflow_config.json
This mutable installed state is distinct from the immutable package default at
~/.codex/codex_workflow/resources/workflow_config.default.json. Bootstrap
starts from the package default. Update migrates and preserves the mutable
configuration, using the incoming package default only for newly introduced
fields. The project entry point's enabled/disabled state is preserved
separately.
The current default snapshot is:
{
"schema_version": 4,
"default_executor": "executor_luna",
"default_executor_reasoning_effort": "xhigh",
"auto_check_update": false,
"max_concurrent_workers": 20,
"max_executor_sol_instances": 1,
"report_package_size": 250,
"enabled_workers": [
"executor_luna",
"executor_sol",
"tester",
"doc-writer",
"explorer",
"end_of_session"
]
}The configuration contract is:
- keep valid JSON and a supported schema;
- set
default_executortoexecutor_lunaorexecutor_terraand keep it insideenabled_workers; - set
default_executor_reasoning_efforttohigh,xhigh, ormax; - keep
auto_check_updateboolean; it defaults tofalse; - keep
doc-writerenabled because project installation depends on it and keepend_of_sessionenabled because both deployment routes require it; - keep worker names unique and backed by templates in
~/.codex/codex_workflow/templates/agents/; - keep exactly one of
executor_lunaandexecutor_terraenabled as the default executor; - keep
max_executor_sol_instancesbetween zero and the concurrency limit.
Do not edit generated surfaces directly. codex_workflow --configure
synchronizes the Heavy snapshot, all worker TOMLs, and workflow-owned
config.toml keys. End-of-Session handoff context is owned by the automatic
handoff contract rather than persistent user configuration.
The concurrency values must stay synchronized: the confirmed
max_concurrent_workers in workflow_config.json is also written to
[features.multi_agent_v2].max_concurrent_threads_per_session in
~/.codex/config.toml. The value 20 is only the current package default; it
must be replaced when the user selects another valid limit.
When worker definitions or platform settings change, open a new Codex session so the updated settings are loaded.
All distributed workers live in ~/.codex/agents/ and are generated from
templates. The enabled_workers configuration controls which materialized
workers the workflow may create and use.
Advanced changes belong in the owned template before reconfiguration. For
example, a template may add:
service_tier = "fast"to an installed worker whose service supports that setting. Keep the role's scope, reporting contract, and safety boundaries intact. Do not edit unrelated worker files or replace a materialized worker with a repository-only file.
To add a custom worker, ask Codex to create a worker template consistent with
the existing role files, place the template under the workflow template area,
add its name to enabled_workers, and install the active TOML. A custom
research-oriented investigator can be useful for web research in a niche
project, but it should be enabled only when its role and concurrency cost are
understood.
The private source resource is:
.codex_workflow_hidden_resources/personalization.md
It contains the confirmed Frontend Project Profile, Design Principles, and
Additional Workflow Decisions. Its decisions are materialized only inside the
marked personalization block in AGENTS.md (or the hidden entry point while
the project is disabled).
Do not edit its materialized marker directly. codex_workflow --personal
validates a complete candidate and atomically updates the resource and generated
region while preserving project-local instructions.
Do not put personalization in agent_docs/: those six files are durable
project context and are intentionally available to the normal workflow.
Advanced route changes belong in a maintained source package or fork, not in an installed generated copy that update will replace:
~/.codex/codex_workflow/heavy_route.md
~/.codex/codex_workflow/medium_route.md
Possible customizations include:
- replacing
project_progress.mdwith a dedicated codebase navigation or management tool for a very large repository; - adding a project-specific worker and wiring its responsibility into the Heavy route;
- adapting the
end_of_sessionworker instruction to the project's release or review practice while keepingend_of_session.mdas the spawn contract.
Keep the route's ownership boundaries, worker limits, verification gates, and
single-worker automatic-closure ownership of the complete documentation
framework. After a route change, verify that the effective configuration block
and worker list still agree with workflow_config.json.
The Heavy route is an orchestrated deployment-state workflow. It is selected explicitly by the user; Light remains the default for small tasks. The Heavy route does not mean that every prompt must spawn workers: common questions and small tasks use a direct main-agent fast path and must not call subagents. When that fast path calls no subagent, its final response also omits the worker statistics table.
The current enabled set is:
| Role | Responsibility | Can edit project source? |
|---|---|---|
| Main agent | Knowledge architect: chooses scope and architecture, distributes guidance, integrates knowledge, and reviews decision-critical boundaries | Only for exceptional scoped takeover, not routine Heavy implementation |
Selected default executor (executor_luna or executor_terra) |
Package discovery, production implementation, self-check, and routine repair | Yes, within its work package |
executor_sol |
Complex core reasoning or fallback implementation | Yes, within its work package; limited to one active instance |
tester |
Independent focused tests and failure analysis | Test/fixture scope; production defects return to the executor |
doc-writer |
Assigned documentation during implementation and required installation initialization; not automatic deployment closure | Documentation scope; installation may authorize listed new or still-template-marked recovery files |
| Explorer companion | Read-only context gateway for planning and knowledge-delta briefs | No |
end_of_session |
Inherited-context reconciliation of the complete documentation framework plus Git closure and statistics | All agent_docs/ and Git state during automatic closure |
executor_terra.toml is materialized alongside the other worker definitions;
it becomes the selected default executor only when configured as such. The
enabled list, selected executor, and limits come from workflow_config.json
and are copied into the Heavy route's
effective-configuration block.
When Heavy is selected for a deployment-state task, the main agent:
- reads the project entry point and the workflow's Heavy-route instructions;
- initializes one read-only Explorer and asks it to refine foundational documents and relevant repository evidence into a planning brief;
- uses that brief to form the architecture, bounded plan, acceptance matrix, ownership, dependencies, and verification gates without replaying raw discovery;
- directly inspects only decision-critical, contradictory, uncertain, or high-risk evidence;
- sends self-contained work packages to only the enabled workers needed for the task.
Each package distributes task identity, outcome, ownership, upstream decisions,
interfaces, dependencies, recommendation and rationale, the key invariant and
pitfall, acceptance criteria, verification, escalation conditions, and return
format. executor_sol receives the unresolved problem and constraints without a
prescribed solution. Capsules use exact references but retain judgment needed to
avoid clarification and repair. Final reports are limited by
report_package_size and describe knowledge changes rather than file activity.
The normal implementation and verification loop is:
User selects Heavy route
│
▼
Explorer refines project and repository evidence into a planning brief
│
▼
Main forms architecture and distributes guidance-rich package(s)
│
▼
Executor implements one coherent increment and self-validates
│
▼
Tester independently runs focused checks when testing is warranted
│
├── routine defect ─► direct executor repair ─► tester recheck
├── proof ─────────► compact knowledge report
└── decision defect ─► main agent re-scopes or decides
│
▼
Explorer consolidates material knowledge deltas when needed
│
▼
Main integrates verified package outcomes
│
▼
Fresh Luna xhigh worker automatically closes the deployment before the final response
The tester and responsible executor receive each other's canonical task names. Routine production defects travel directly between them as compact packets with the failed criterion, reproduction, expected and observed behavior, affected contract, evidence artifact, and scope/architecture assessment. The main agent is involved only for capsule conflict, cross-package contract change, an invalidated decision, expanded ownership, security or migration risk, or repeated failure. Test and fixture defects stay with the tester.
Workers keep raw logs, large diffs, reports, responses, and diagnostics in artifacts or retained thread context. Upward reports give the outcome, contract changes, new facts, invalidated assumptions, verification reference, residual risk, decision required, and exact evidence location. When no decision is required and evidence is coherent, the main agent normally does not reopen the artifact.
The current configuration permits at most twenty concurrent child workers and
at most one executor_sol instance. Explorer is reported as a companion rather
than a task worker, but its live thread consumes platform capacity. Heavy keeps
one child-agent slot available for the fresh End-of-Session worker and must not
exceed the enabled-worker list or configured limits.
Worker communication is event-driven and knowledge-aware. Routine repair stays inside the executor/tester pair; the main agent receives events only when new evidence changes coordination, contracts, risk, scope, or the next decision. A worker that returns no concrete evidence gets one short retry; repeated evidence-free work triggers replacement or a narrowly scoped, explicit main-agent takeover.
Task workers must not edit Git state or the shared status documents. During
automatic closure, end_of_session alone reconciles the complete documentation
framework and Git state; it does not invoke another documentation worker.
Explorer remains read-only.
project_progress.md carries only the goal, overall progress, current position,
and next milestone. latest_session_work.md carries the most recent deployment
outcome, verification, blockers, and exact continuation point. A completed
deployment remains recorded concisely instead of clearing both files.
Before each substantive Medium or Heavy deployment returns its final response,
the route automatically creates a fresh, uniquely named end_of_session worker
with the handoff contract's finite context fork. This preserves its Luna xhigh
model while inheriting recent main-agent context. Without a parent-built capsule
or usage ledger, it reconciles every core and module-specific
agent_docs/ file against verified deployment facts, performs compact closing
checks, handles the Git commit, and returns the final report. The report ends
with exactly three statistics columns:
Worker name, Quantity (distinct task names), and Number of calls
(turn-starting assignments and follow-ups). Explorer has no closure
responsibility. Direct questions and small or odd bounded tasks create no
worker, handoff, or statistics table.
The original design grouped the system into five logical blocks across two
geographical levels. That model remains useful, but some paths need a precise
distinction: agent_docs/ is project documentation, while personalization is
private under .codex_workflow_hidden_resources/; worker TOMLs are materialized
runtime definitions, while workflow_config.json is their persistent
configuration source.
The five blocks are:
Location: ~/.codex/
~/.codex/agents/contains all distributed worker TOMLs. The current enabled set isexecutor_luna,executor_sol,tester,doc-writer,explorer, andend_of_session;executor_terraremains available as the alternate default executor.~/.codex/codex_workflow/heavy_route.mddefines Heavy orchestration, delegation, limits, repair loops, and ownership.~/.codex/codex_workflow/medium_route.mddefines main-agent execution with only Explorer and End-of-Session subagent exceptions.~/.codex/codex_workflow/explorer_companion.mddefines the read-only Explorer's lifecycle, gateway role, and brief contracts.~/.codex/codex_workflow/end_of_session.mddefines the shared spawn contract;end_of_session.tomlcontains the complete handoff procedure.
This block is the reusable execution machinery. It is shared by projects and does not contain project-specific decisions.
Location: the current project directory
AGENTS.mdis the active project entry point and contains the workflow instructions materialized for this project.agent_docs/contains the six-document Project Documentation Framework..codex_workflow_hidden_resources/.AGENTS.mdis the same entry point in its disabled state and must not coexist with rootAGENTS.md.
This block connects the shared runtime to one project. Its project documents are durable context, not private configuration.
Primary resource:
~/.codex/codex_workflow/workflow_config.json
The resource currently contains:
default_executor: currentlyexecutor_luna;default_executor_reasoning_effort: currentlyxhigh;auto_check_update: currentlyfalse;max_concurrent_workers: currently20;max_executor_sol_instances: currently1;enabled_workers: currentlyexecutor_luna,executor_sol,tester,doc-writer,explorer, and requiredend_of_session;report_package_size: currently250words.
Related configuration surfaces are:
~/.codex/codex_workflow/resources/workflow_config.default.json: immutable package defaults and migration fallback;~/.codex/agents/*.toml: materialized definitions for all distributed workers;~/.codex/config.toml: workflow-owned Codex platform settings, merged into the user's existing configuration without replacing unrelated settings;~/.codex/codex_workflow/templates/agents/: all distributed worker templates, including the alternateexecutor_terra.
workflow_config.json is the source of the workflow-level values. The route
snapshot, worker files, and platform settings are synchronized outputs;
they must not silently disagree with it.
Private resource:
.codex_workflow_hidden_resources/personalization.md
It contains the confirmed project-scoped decisions:
- Frontend Project Profile — for example, a deliberate reduced frontend verification profile;
- Design Principles — project-specific design and engineering rules;
- Additional Workflow Decisions — other confirmed project instructions.
The resource is intentionally hidden from ordinary project context. Its
effective instructions are materialized between the personalization markers
in AGENTS.md or in the hidden disabled entry point. It is not stored in
agent_docs/, and agent_docs/ should not be used as a substitute for it.
Location: ~/.codex/codex_workflow/
user_AGENTS.mdcontains the workflow marker, installed version marker, optional-check placeholder, and exact command prompts for--install,--update,--remove,--enable_auto_check_update,--disable_auto_check_update,--configure,--personal,--disable, and--enable, plus the former automatic-check naming aliases.bootstrap.md,install.md,configuration_guide.md, andpersonalization_guide.mddescribe initial bootstrap, project installation, configuration, and personalization.update.md,disable.md, andenable.mddescribe update and activation lifecycle operations.remove.mddescribes the destructive two-phase removal procedure.enable_auto_check_update.mdanddisable_auto_check_update.mddescribe the explicit update-check controls;resources/auto_check_update.mdsupplies the optional session instruction.enable_auto_update.mdanddisable_auto_update.mdretain the former names as compatibility aliases.workflow.pyandruntime/implement validated lifecycle operations.VERSIONidentifies the installed workflow version.templates/stores the project entry-point, worker, and project-document templates used for installation and update..source_backup/keeps a complete release source copy for repair and recovery; update-time.backups/preserve replaced installed state.
This block is the command and lifecycle control plane. Guides define intent and the runtime performs deterministic mutations. It is not project context or the worker execution layer.
These five blocks are logical ownership boundaries, not five disjoint
directories. For example, ~/.codex/codex_workflow/ hosts routes, guidance,
configuration, templates, and backups. The distinction is about who owns the
data and how it is consumed:
User level: shared runtime + global configuration + lifecycle guidance
│
│ materialized into the current project
▼
Project level: entry point + six durable documents + private personalization