Codex Orchestrator

Coordinate Codex as a disciplined delivery system, not a one-shot generator.

Core Modes

Select both:

• project_mode

  • greenfield: build from scratch
  • brownfield: onboard and modernize an existing system

• execution_mode

  • autonomous: proceed automatically when gates pass
  • gated: pause at every gate for user approval

Governing Principle: Spec-Driven Development

No code without a spec. This is non-negotiable.

Before any implementation, a written spec must exist with:

• What is being built

• Why it's needed

• Acceptance criteria (testable)

• Constraints and out-of-scope

The coding agent MUST NOT:

• Guess at requirements

• Make assumptions about behavior

• Add unrequested features

• Invent abstractions not in spec

If spec is unclear → STOP and ask. Never guess.

See references/spec-driven-development.md for full spec templates and enforcement rules.

Non-Negotiable Sequence

1. Intake + planning questionnaire

2. Spec creation + approval (specs written BEFORE any code)

3. Docs scaffold + AGENTS.md contract

4. Mode-specific pre-architecture work

5. Architecture + ADR baseline (references specs)

6. Build by vertical slices (each task references spec)

7. Verification against spec acceptance criteria

8. Security/quality gates

9. Release readiness + handover

Never skip gates silently. Never implement without a spec.

Required Resources

Read these references before running:

• references/spec-driven-development.md (MANDATORY FIRST - governs all work)

• references/planning-questionnaire.md

• references/modes.md

• references/gate-checklists.md

• references/testing-matrix.md

• references/manual-test-templates.md

• references/codex-runbook.md

• references/gate-prompts.md

• scripts/agent_exec.py

• references/research-playbook.md (if research_mode=true)

Scaffolding

Initialize project artifacts:

python scripts/init_project_docs.py --root <project-path> --mode <greenfield|brownfield>

This creates/updates:

• AGENTS.md (project workflow contract)

• docs/*.md planning/architecture/test/progress/change docs

• brownfield docs (when mode is brownfield)

• .orchestrator/status.json (machine-readable state)

• .orchestrator/context.json (project/execution/research mode context)

Planning Rules

Before anything else, ask the user which coding agent to use (codex | claude | opencode | pi) and fallback agent. Then ask all required questions from references/planning-questionnaire.md.

Minimum required answers:

• mission

• top user journeys

• v1 scope

• hosting target

• stack preference (or explicit request for recommendation)

• project_mode

• execution_mode

• definition of done

• acceptance tests

If research_mode=true, produce docs/research-notes.md and architecture recommendation before G2.

Mode-Specific Requirements

Greenfield

Must complete before G2:

• requirements + DoD clarity

• architecture baseline

• ADR-0001 with alternatives

• CI/test baseline plan

Brownfield

Must complete before G2 (and authored by coding agent, not orchestrator):

• as-is architecture and system inventory

• dependency map and risk register

• characterization-test baseline

• migration strategy + rollback approach

• compatibility boundaries documented

Gate Engine

Use gates G0 through G7 defined in references/gate-checklists.md.

Update gate state via script:

python scripts/gate_status.py set --root <project-path> --gate G3 --state PASS --note "slice-1 verified"

Validate status schema:

python scripts/gate_status.py validate --root <project-path>

Allowed states: PENDING | IN_PROGRESS | PASS | FAIL | BLOCKED. By default, gate preconditions are enforced (sequence + mode-aware docs checks).

Validation Rules

Use references/testing-matrix.md.

Mandatory checks per progression:

• lint/type/build

• unit/integration/e2e (as applicable)

• API contract sanity (if API exists)

• security baseline

• docs sync verification

Also execute manual test scripts from references/manual-test-templates.md.

Documentation Rules

For each meaningful step:

• update docs/tasks.md

• update docs/progress.md

• append docs/change-log.md

• update docs/traceability.md

• record test evidence in docs/test-results.md

For user-requested changes, run:

python scripts/change_impact.py --root <project-path> --request "<change request>"

Then complete all TODOs it emits in impacted docs.

Codex Execution Pattern

Use PTY/background for long runs. Follow command patterns in references/codex-runbook.md.

Critical rule: each run executes ONE task, not a whole project in one prompt. For G4, maintain docs/g4-task-plan.md checklist and process tasks one by one.

Generate gate-specific prompts with:

python scripts/generate_gate_prompt.py --gate <G1..G7> --agent <codex|claude|opencode|pi> --project-mode <greenfield|brownfield> --execution-mode <autonomous|gated> --research-mode <true|false> --task "<single task summary>" --spec-ref "<spec ref when applicable>"

update_docs_step.py is now a fallback utility for recovery/manual bookkeeping only. Primary expectation: the coding agent updates docs directly during each task.

Required loop:

1. verify spec exists for the task (no spec = no implementation)

2. launch selected coding agent with spec-driven prompt template

3. coding agent updates docs immediately after task completion (including handoff checklist)

4. coding agent wakes OpenClaw with task summary + where verification steps are documented

5. OpenClaw agent runs verification itself:

   • CLI checks in terminal tools
   • Browser/manual checks in browser tools (for web flows)

6. verify output matches spec acceptance criteria

7. if validations fail, OpenClaw sends exact failures back to coding agent and re-runs fix cycle

8. write final gate status only after validations pass (or mark FAIL/BLOCKED)

Enforcement:

• run_gate.py requires --spec-ref for G3/G4 tasks (implementation gates).

• run_gate.py requires coding agent + fallback agent context.

• Each task requires validation evidence (--validate-cmd and/or --ui-review-note).

• Tasks flagged with --requires-browser-check must include --ui-review-note.

• status=PASS requires at least one --validate-cmd.

• status=PASS is blocked when --agent-dry-run is used.

• For G4, PASS is blocked until docs/g4-task-plan.md has no unchecked tasks.

• Validation output is recorded in docs/validation-log.md.

• Coding agent must update docs after every task, including docs/agent-handoff.md.

• In brownfield mode, G1/G2 fail if onboarding docs are not updated by the coding agent.

• Coding agent prompts MUST include spec preamble from references/spec-driven-development.md.

• Any implementation without spec reference = automatic FAIL.

• In autonomous mode, failed validations trigger automatic fix retries (default: 2) with failure details passed back to coding agent.

• Optional strict mode: --auto-block-on-retry-exhaust auto-classifies gate as BLOCKED when retries are exhausted.

Progress Visibility

Generate a quick status board:

python scripts/progress_dashboard.py --root <project-path>

This summarizes current gate, completion %, blockers, and recent activity.

Run a single-task gate step with one command:

python scripts/run_gate.py --root <project-path> --gate G2 --agent codex --fallback-agent claude --project-mode brownfield --execution-mode gated --research-mode true --task "architecture baseline refined for API routing" --status IN_PROGRESS --validate-cmd "npm run -s typecheck" --ui-review-note "N/A for architecture-only task"

Mark PASS only after all gate-level checklist items are complete:

python scripts/run_gate.py --root <project-path> --gate G2 --agent codex --task "architecture gate complete" --status PASS --validate-cmd "npm run -s typecheck"

For web/UI tasks, require browser verification by OpenClaw agent:

python scripts/run_gate.py ... --requires-browser-check --ui-review-note "Verified login + CRUD manually in browser via OpenClaw browser tools"

Package distributable skill artifact:

python scripts/package_skill.py --skill-dir . --out dist

End-State Deliverables

At completion provide:

• docs/progress.md at 100%

• final gate summary from .orchestrator/status.json

• test result summary + unresolved risks

• deployment + rollback notes

• next-iteration backlog

If blockers remain, mark as PARTIAL_COMPLETE with explicit blockers and owners.