This commit is contained in:
DevRunbook release export
@@ -0,0 +1,133 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user