Pantheon + Codex CLI Dev Workflow

Overview

Every fix or feature follows this path:

Codex CLI (local reasoning + code)
    │
Local DDEV  (ddev pull pantheon ← Dev/Live)
    │
    ├── git push pantheon [feature-branch]  →  Multidev Sandbox (verify remotely)
    │
    └── git push pantheon main:master  →  Pantheon Dev
    │                                           │
    └── git push github main               Test → Live (dashboard)
              │
         GitHub (web UI, history, PRs)

Codex CLI plugs in at the local DDEV stage — before code leaves your machine.

Pre-Flight Checklist (one-time or per-site verification)

Email rerouting

Confirm reroute_email is configured with the safe pattern — NOT a hardcoded environment name list:

// settings.php (correct pattern — catches Dev, Test, Multidev, and local)
if (defined('PANTHEON_ENVIRONMENT') && PANTHEON_ENVIRONMENT === 'live') {
  $config['reroute_email.settings']['disable'] = TRUE;
} else {
  $config['reroute_email.settings']['enable'] = TRUE;
  $config['reroute_email.settings']['address'] = '[email protected]';
}

Multidev names are custom (e.g. fix-validat) — they will never match a hardcoded list. The !== 'live' pattern is the only safe approach.

Multidev name limit

Pantheon truncates to 11 characters. Plan branch names accordingly.

fix-validation → use fix-validat or val-fix-01
Pick names that stay readable at 11 chars

The Workflow (Per Ticket)

Step 1 — Create a Multidev Sandbox

# Clone from Live into a fresh Multidev (≤11 char name)
terminus multidev:create your-site-name.live fix-validat

# Later, if you need a database refresh from Live:
terminus env:clone-content your-site-name.live fix-validat

The Multidev (fix-validat.your-site-name.pantheonsite.io) is your safe throwaway. Break things here.

Step 2 — Set Up Local Branch

cd /path/to/local/site

# Switch Multidev to Git mode
terminus connection:set your-site-name.fix-validat git

# Create matching local branch
git checkout -b fix-validat

# Confirm remotes (should have pantheon and github)
git remote -v

If pantheon remote is missing:

git remote add pantheon $(terminus connection:info your-site-name.dev --field=git_url)

Step 3 — Refresh Local DDEV

ddev pull pantheon

Note: ddev pull pantheon pulls from the environment configured in .ddev/providers/pantheon.yaml — not the Multidev automatically. For most tickets pulling from Dev or Live is fine.

Step 4 — Use Codex CLI to Write and Review the Fix

This is where Codex CLI enters the workflow. Run it from inside your DDEV project root (outside the container, in the host directory).

Orient Codex on the task

codex "explain what web/modules/custom/your_module/your_module.module does"

Use this before writing a fix if you're not already familiar with the code. Codex will read the file and summarize logic, hooks, and dependencies.

Let Codex write the fix

codex "In web/modules/custom/your_module/your_module.module, fix the validation in hook_entity_presave so that editors can save past-dated events without triggering an error. Do not change any other validation logic."

Always scope the prompt tightly. Specify:

Exact file path
Exact hook or function
What to change
What NOT to touch

Review Codex output before accepting

git diff

Read the diff yourself. Codex is a fast drafter, not a final authority. Sanity-check:

Does the fix do what you asked?
Did it touch anything it shouldn't?
Are there any obvious regressions?

Have Codex write the commit message

codex "Write a conventional commit message for this git diff" < <(git diff --staged)

Or interactively:

git add web/modules/custom/your_module/your_module.module
codex "Write a one-line conventional commit message for the staged change in your_module.module — it loosens validation on past event edits"

Step 5 — Test Locally in DDEV

ddev drush cr
# Test in browser at https://your-site.ddev.site

If the fix involves config changes:

ddev drush cex   # export config to confirm what changed
git diff config/ # review config diff

Step 6 — Push to Multidev for Remote Verification

git add [files]
git commit -m "fix: loosen validation on past event edits"
git push pantheon fix-validat

Verify at https://fix-validat-your-site-name.pantheonsite.io.

Check:

Fix works as expected
No PHP errors in logs (terminus drush your-site-name.fix-validat -- watchdog:show --type=php)
Email rerouting is active (spot-check if your fix touches any email-related code)

Step 7 — Merge to Main and Push to Pantheon Dev

git checkout main
git merge fix-validat
git push pantheon main:master   # master maps to Pantheon Dev
git push github main            # mirrors to GitHub for history/PRs

Verify at Pantheon Dev. Then promote through the Pantheon dashboard:

Dev → Test → Live

Don't skip Test. It takes 30 seconds. Run a smoke test on the specific workflow your fix touches.

Step 8 — Clean Up

# Delete the Multidev when done
terminus multidev:delete your-site-name.fix-validat --delete-branch

# Delete local branch
git branch -d fix-validat

Where Codex CLI Fits (Quick Reference)

Stage	Codex CLI Use
Before coding	`codex "explain [file or hook]"` — orient on unfamiliar code
Writing the fix	`codex "[tight prompt scoped to file + function]"` — draft the change
After Codex drafts	`git diff` — always review before committing
Commit message	`codex "write a conventional commit message for this change"`
Stuck on a bug	`codex "why might hook_entity_presave be firing twice in this module?"` — rubber duck
Pre-PR review	`codex "review this diff for obvious issues or regressions"`

Codex CLI Prompt Discipline

Codex works best when prompts are:

File-specific: Always include the full relative path to the file
Hook/function-specific: Name the exact function, not just "fix the module"
Bounded: Tell it what NOT to change
Drupal-aware: Mention the Drupal version and hook system context when relevant

Weak prompt:

"Fix the validation bug"

Strong prompt:

"In web/modules/custom/housing_reservations/housing_reservations.module, in hook_entity_presave for the reservation entity type, remove the date validation that blocks saves when field_start_date is in the past. Leave all other validation intact. This is Drupal 11."

Reminders

Firewall: This playbook is day job only. No day job code, clients, or Pantheon site names in Gluebox or RSVP-System work.
Tuition window: You need this job for ~4 years. Don't cut corners that put the site at risk.
Test → Live: Never skip the Test environment promotion. 30 seconds of verification.
Codex is a drafter: Always read the diff. You own the code, Codex assists.

Playbook lives at playbooks/dayjob-pantheon-codex-workflow.md in the brain vault.