134 lines
5.3 KiB
Markdown
134 lines
5.3 KiB
Markdown
# 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.
|