Methodical end-to-end software delivery orchestrator for Codex CLI with dual project modes (greenfield for new builds, brownfield for existing systems) and dual execution modes (autonomous and gated). Use when users want full lifecycle delivery with strict stage gates, progress tracking, per-step manual/automated testing, continuous docs updates, change-impact management, and a reusable AGENTS.md workflow for any coding agent.
Methodical end-to-end software delivery orchestrator for Codex CLI with dual project modes (greenfield for new builds, brownfield for existing systems) and dual execution modes (autonomous and gated). Use when users want full lifecycle delivery with strict stage gates, progress tracking, per-step manual/automated testing, continuous docs updates, change-impact management, and a reusable AGENTS.md workflow for any coding agent.
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
Intake + planning questionnaire
Spec creation + approval (specs written BEFORE any code)
Docs scaffold + AGENTS.md contract
Mode-specific pre-architecture work
Architecture + ADR baseline (references specs)
Build by vertical slices (each task references spec)
Verification against spec acceptance criteria
Security/quality gates
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)
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.
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.
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:
verify spec exists for the task (no spec = no implementation)
launch selected coding agent with spec-driven prompt template
