# 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:

```text
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.