DevRunbook-Public/docs/11-codex-integration.md

11 — Codex integration strategy

Current product boundary

The MVP composes and exports tasks for Codex. It does not assume direct control over a Codex session or repository. This keeps DevRunbook useful across the Codex app, CLI and IDE while the integration surface continues to evolve.

Supported MVP outputs

Plain prompt

Single rendered task copied to the clipboard.

Markdown task

A downloadable TASK.md containing the rendered contract and run metadata header.

Run Pack

A multi-file ZIP suited to long or staged work. Files separate stable specification, repository context, validation and handoff.

AGENTS.md recommendation

A generated suggestion containing durable repository rules discovered or confirmed during profile creation. The export must:

• never overwrite an existing file;
• distinguish global, repository and directory-specific guidance;
• avoid copying one-time task requirements into persistent instructions;
• include a review checklist.

Codex reads AGENTS.md files before work and supports layered repository instructions. DevRunbook should use that documented model rather than creating a competing persistent-instruction convention.

Current Codex ecosystem alignment

Codex currently supports layered AGENTS.md guidance, reusable skills, plugins that distribute skills and connectors, MCP, subagents, worktrees, browser-assisted development and automations. DevRunbook models these as adapters or execution conveniences rather than embedding one transient UI workflow into its canonical playbook format. See docs/38-codex-native-build-workflow.md.

Codex Skill and plugin export

A later milestone can convert eligible playbooks into Skills and optionally package them as plugins for distribution. A Skill packages repeatable instructions, resources and optional reviewed scripts using the current open agent skills format. The export adapter should map:

• playbook title/description to Skill discovery metadata;
• structured workflow and guardrails to SKILL.md;
• declared resources to skill resources;
• future reviewed scripts only when they meet a stricter security policy;
• declared MCP dependencies to plugin metadata such as agents/openai.yaml when the current plugin contract requires them;
• evaluation examples to authoring/test documentation.

Not every playbook should become a Skill. One-off repository-specific generated tasks remain runs, while reusable stable procedures are Skill candidates.

Future direct bridge options

Codex CLI bridge

A local companion could launch a selected generated task in a chosen worktree. Required controls:

• explicit repository and branch/worktree selection;
• preview of exact prompt and allowed context;
• no implicit elevation;
• operator approval before command execution where required;
• streaming status and final evidence import;
• cancellation and cleanup.

Codex SDK

The SDK may support programmatic orchestration from a TypeScript service. Use only after confirming current official SDK behavior, authentication and sandbox boundaries.

Codex as MCP server / Agents SDK

Codex can participate as a specialist in a broader orchestrated workflow. This is appropriate for later evaluation runners or coordinated tasks, but it adds significant operational and security scope and is not needed for MVP value.

MCP context provider

DevRunbook itself could expose an MCP server that allows Codex to:

• search validated playbooks;
• fetch a specific playbook version;
• retrieve a repository profile;
• generate a prompt with supplied inputs;
• retrieve a Run Pack manifest.

Read operations should come first. Generation through MCP must still validate authorization and never expose integration secrets.

Export compatibility contract

Every output records:

• DevRunbook run ID;
• playbook ID and semantic version;
• playbook digest;
• repository-profile revision/digest when used;
• generated prompt digest;
• generation timestamp in metadata, not necessarily prompt body;
• lint result;
• platform version.

This makes it possible to import execution feedback later without guessing which task was used.

Prompt design alignment

Generated tasks follow documented Codex best-practice principles:

• explicit goal;
• relevant context;
• constraints;
• definition of done;
• plan-first behavior for larger tasks;
• persistent repository rules separated into AGENTS.md where appropriate;
• reusable stable workflows eligible for Skills.

Execution result import — future

A result bundle can include:

run-id
repository commit before/after
changed files
commands executed
command results
agent final report
artifacts
operator rating

DevRunbook must not treat an agent's self-reported success as independent validation. Imported command evidence and operator review remain distinct fields.

Worktree awareness — future

Because Codex workflows can use isolated worktrees, a direct bridge should model worktree path, base commit, branch, cleanup state and whether changes were merged. The MVP does not need this to generate excellent prompts.

Golden composition conformance

The 28 files in examples/rendered-prompts/ are normative composition fixtures. The production composer must render the supplied examples byte-identically before Codex export compatibility is considered implemented. This checks the task contract independently from the UI and database.