sdg-codex

A Codex-native implementation of Spec-Driven Generation (SDG), adapted from modularcloud/sdg-claude. SDG maintains a behavioral master specification and uses agents to generate and refine the spec, test spec, certifications, test harness, and product. The human answers intent questions; the process performs the artifact and implementation work.

This repository is a template. Install it into a project and start a Codex or ChatGPT coding task in that project; root AGENTS.md automatically turns the main thread into the SDG Orchestrator.

How it works

• specs/PROCESS.md is the unchanged, harness-agnostic process specification.
• specs/CODEX-PROCESS.md binds that process to Codex custom agents, full-history forks, follow-up messages, Git, and GitHub.
• AGENTS.md is the automatically loaded Orchestrator charter. It explicitly limits that role to the root thread and exempts all spawned subagents.
• .codex/config.toml pins GPT-5.6 Sol and the main Orchestrator to Max, enables project-scoped custom agents, and configures unattended execution. Liaison is the one non-custom binding: a full-history fork inherits the Max root type and loads its complete charter from the spawn prompt.
• .codex/sdg-config.md selects behavior variants by pointer.
• .sdg/ENGINEERING.md is the Engineer's durable build/lint/run knowledge store. It replaces the original use of root AGENTS.md, which Codex reserves for repository instructions.

Agent profile

Role	Model	Intelligence	Lifecycle
Orchestrator	GPT-5.6 Sol	Max	Main thread
Liaison	GPT-5.6 Sol	Max	Fresh default-agent full-history fork per episode
Reviewer	GPT-5.6 Sol	Ultra	Fresh one-shot
Driver	GPT-5.6 Sol	Extra High	Fresh per refinement round; continuable on questions
Specialist	GPT-5.6 Sol	Extra High	Fresh per bounded mission
Engineer (ralph)	GPT-5.6 Sol	Extra High	Fresh per Ralph mission
Engineer (ultra)	GPT-5.6 Sol	Ultra	One phase-owning run until completion
Engineer worker	GPT-5.6 Sol	Extra High	Bounded history-free delegated unit

There is no economy profile and no Pro reasoning-mode integration. Ultra is a Codex intelligence level with subagent orchestration; it is not GPT-5.6 API Pro mode.

Engineering modes

.codex/sdg-config.md selects one of two Phase 9/10 bindings:

• engineering: ralph — the default. The Orchestrator drives fresh Extra High Engineer missions. specs/tmp/FIX_PLAN.md is durable iteration-to-iteration memory.
• engineering: ultra — no Ralph loop and no FIX_PLAN.md. A single Ultra Engineer owns the whole phase, may delegate independent work, and continues until the same compliance, tests, CI, and code-review completion standard holds.

Neither mode requires a Codex goal. Durable files, commits, branch/PR state, and the Phase 0 audit provide interruption recovery.

Other configuration defaults are liaison-mode: cto and observer: none. Liaison may be switched to pm; the optional tracker observer is retained from the source scaffold.

Bootstrap a project

Ask Codex to install and run the sdg-bootstrap skill from this repository in the target project. The skill pins one source commit, inventories the exact replacement set, backs up existing scaffold roots, installs transactionally, validates every role and reference, and stages only its explicit changed-file manifest. Existing .gitignore, README, and license are preserved.

Do not bulk-copy the scaffold over existing AGENTS.md, .codex/, .sdg/, or specs/; those roots must be reviewed and replaced as a unit so stale instructions cannot survive. After bootstrap, ensure the project has an authenticated GitHub remote and Actions enabled. Trust the project so Codex loads .codex/config.toml, start a new Codex/ChatGPT coding task from the project root, and describe what you want to build.

Requirements and safety

• Codex or ChatGPT coding mode with project-scoped custom agents, subagents, full-history forks, and follow-up messages.
• Access to GPT-5.6 Sol. Reviewer and Ultra engineering mode require Ultra availability; set Reviewer to max or choose engineering: ralph if Ultra is unavailable.
• Git and authenticated GitHub access through gh or the GitHub connector/app.
• A sandboxed or disposable environment. The shipped project config uses approval_policy = "never" and sandbox_mode = "danger-full-access" so long-running agent work does not stall. Change those values before use on a primary machine or any environment where unrestricted commands are inappropriate.

Layout

AGENTS.md                       Orchestrator charter; auto-loaded by Codex
.sdg/ENGINEERING.md             Engineer-only build/lint/run knowledge
.codex/
  config.toml                   model, effort, agent, and permission defaults
  sdg-config.md                 liaison, engineering, and observer selections
  agents/                       six history-free Codex custom-agent TOML files
  prompts/                      role missions and selected-mode runbooks
specs/
  PROCESS.md                    harness-agnostic SDG process (unchanged)
  CODEX-PROCESS.md              Codex bindings and phase runbook
  PHILOSOPHY.md                 Liaison-only Developer principles
  GOALS.md                      explicitly approved non-negotiable goals
  tmp/  patches/                durable process working state
sdg-bootstrap/                  installer skill; not copied into projects

License

MIT