AI-native SDLC with Codex

The Codex SDLC track implements the shared six-stage lifecycle with Plan mode, AGENTS.md, skills, sandbox policies, hooks, app worktrees, non-interactive execution, code review, and scheduled tasks. Use this page as the Codex adapter: it names the correct surface for each gate and links to the single canonical stage procedure.

The lifecycle remains tool-independent. Read the AI-native SDLC overview first, then use this map for Codex-specific execution details.

Verified surface

CLI commands were checked on 4 September 2026 against Codex CLI 0.146.0 and the current Codex developer command reference. Worktrees are an app capability, not a codex --worktree CLI flag. Re-run codex --version and the relevant --help command before encoding automation.

Stage map

Stage	Accepted artifact	Codex surface	Canonical procedure
Plan	intent.md	Interactive /plan; app chat for stakeholder discovery and file context	Capture intent
Design	spec.md	AGENTS.md, .agents/skills/, MCP, images, and repository inspection	Write the spec
Build	plan.md, diff, tests	App worktrees or explicit Git worktrees; CLI sandbox and approval policies	Build from an accepted plan
Test	Test evidence	Active feedback loop; codex exec for repeatable non-interactive checks	Close the feedback loop
Deploy	Reviewed pull request	codex review, openai/codex-action@v1, protected merge and release environments	Layer review and approvals
Maintain	Incident record and next intent.md	Scheduled app tasks, hooks, CI schedules, Slack or Linear intake	Close production back into planning

Configure the build path

Prerequisites: a Git repository, Codex authenticated, a clean working tree, and repository instructions plus verification commands in AGENTS.md.

1. Start the interactive CLI and enter Plan mode before the agent is working:

   codex

   /plan Read docs/intents/FEATURE.md and docs/specs/FEATURE.md. Inspect the
   repository and propose an ordered implementation plan with exact files,
   test-first steps, risks, and rollback. Do not edit source files.

2. Review the plan and save the accepted version as docs/plans/FEATURE.md.

3. For parallel work, choose Worktree in the Codex desktop app or create a worktree explicitly with Git. Codex CLI 0.146.0 has no --worktree flag.

4. Run a bounded implementation in the chosen checkout:

   Read docs/plans/FEATURE.md and AGENTS.md. Implement only milestone 1.
   Run the named typecheck, lint, unit, integration, and visual checks.
   Diagnose implementation failures; do not weaken tests or skip gates.
   Finish with changed files, command results, and remaining risk.

5. Review local changes:

   codex review --uncommitted

6. Keep merge and production release behind branch protection and a named human approval.

Put policy in the right layer

• Put durable repository instructions in AGENTS.md; a nearer file overrides broader guidance for its subtree.
• Put reusable workflows in .agents/skills/SKILL_NAME/SKILL.md.
• Put deterministic lifecycle behavior in .codex/hooks.json or the active config.toml layer.
• Use the sandbox and approval policy to constrain execution; text instructions alone do not create a security boundary.
• Put merge and production authorization in the repository and deployment platform.

Automate bounded checks

codex exec is the stable non-interactive command. New automation should request the least sandbox capability it needs:

codex exec \
  --sandbox workspace-write \
  --output-schema .github/codex/review.schema.json \
  "Run the documented checks and write a structured review of the current diff."

Use --json when the consumer needs the full JSONL event stream. --full-auto remains only as a deprecated compatibility flag; prefer the explicit sandbox form above. Use danger-full-access only inside a separately isolated runner.

Prove the adapter works

• codex --help, codex exec --help, and codex review --help match every copied flag.
• /plan is entered before an active run and produces a reviewable plan.
• The app-created or Git-created worktree appears in git worktree list.
• codex exec runs with the least capable sandbox and returns machine-consumable output when required.
• Review automation can comment or fail a check, but the named human or platform rule still controls merge and production.

Common failure modes

A guide uses codex --worktree. That flag is not present in Codex CLI 0.146.0. Use app worktrees or git worktree add.

Automation still uses --full-auto. Replace the deprecated compatibility flag with --sandbox workspace-write, then add a narrower approval and credential boundary around the job.

/plan is unavailable. It cannot switch modes while Codex is already working. Wait for or interrupt the active turn, then invoke /plan.

Continue the track

Artifact chain Create the traceable sequence from intent to the next production finding.

Codex quick start Install, authenticate, configure, and complete a first bounded task.

Worktrees Choose app-managed or explicit Git worktrees for parallel execution.

Non-interactive mode Run Codex in scripts and CI with explicit sandbox and output contracts.